api!: add image_span versions of ImageOutput methods (AcademySoftwareFoundation#4727)

* ImageOutput methods that write scanlines, tiles, and images, which are
the main customization points for format output implementations, are
given additional methods that take `image_span` in place of raw pointers
and strides.

* Generally, for each, there is a templated version that takes
`image_span<T>` that communicates both the memory area and the data type
conversion requested, a "base case" that takes an explicit TypeDesc for
the conversion type and a `image_view<std::byte>` giving the raw memory
layout, and a `span<T>` convenience version for when there are
contiguous strides. Note that when reading mixed channel data types in
"native" mode (no type conversion, just leave the data in its original
types), you have to use the std::byte image_span version, since the idea
is not to do any format conversion, and there may not be a single type
involved.

* For now, the default implementations of these new ImageOutput methods
are just wrappers that call the old pointer-based ones. One by one, over
time, we can swap them, changing the format implementations to have a
full implementation of the new bounded versions, and make their raw
pointer versions call the wrappers. The raw pointer ones will be
understood to be "unsafe", merely assuming that the pointers always
refer to appropriately-sized memory areas. Meanwhile, the ones using
spans and image_spans will, due to assertions in their implementations,
make it easier to verify (at least in debug mode), that we never touch
memory outside these bounds.

---------

Signed-off-by: Larry Gritz <lg@larrygritz.com>

Author: lgritz

src/include/OpenImageIO/image_span.h

@@ -365,7 +365,7 @@ template<typename T> using image1d_span = image_span<T, 2>;
 /// covering the same range of memory.
 template<typename T, size_t Rank>
 image_span<const std::byte>
-as_image_span_bytes(image_span<T, Rank> src) noexcept
+as_image_span_bytes(const image_span<T, Rank>& src) noexcept
 {
     return image_span<const std::byte>(
         reinterpret_cast<const std::byte*>(src.data()), src.nchannels(),
@@ -378,7 +378,7 @@ as_image_span_bytes(image_span<T, Rank> src) noexcept
 /// the same range of memory.
 template<typename T, size_t Rank>
 image_span<std::byte>
-as_image_span_writable_bytes(image_span<T, Rank> src) noexcept
+as_image_span_writable_bytes(const image_span<T, Rank>& src) noexcept
 {
     return image_span<std::byte>(reinterpret_cast<std::byte*>(src.data()),
                                  src.nchannels(), src.width(), src.height(),

src/include/OpenImageIO/imageio.h

@@ -41,7 +41,8 @@ OIIO_NAMESPACE_BEGIN
 using span_size_t = size_t;
 using oiio_span_size_type = OIIO::span_size_t;  // back-compat alias
 
-inline constexpr span_size_t dynamic_extent = -1;
+inline constexpr span_size_t dynamic_extent
+    = std::numeric_limits<span_size_t>::max();
 
 
 
@@ -588,6 +589,18 @@ as_bytes_ref(const T& ref) noexcept
 
 
 
+/// Copy the memory contents of `src` to `dst`. They must have the same
+/// total size.
+template<typename T, typename S>
+inline void
+spancpy(span<T> dst, span<S> src)
+{
+    OIIO_DASSERT(dst.size_bytes() == src.size_bytes());
+    memcpy(dst.data(), src.data(), src.size_bytes());
+}
+
+
+
 /// Try to copy `n` items of type `T` from `src[srcoffset...]` to
 /// `dst[dstoffset...]`. Don't read or write outside the respective span
 /// boundaries. Return the number of items actually copied, which should be

src/include/OpenImageIO/span.h

@@ -394,44 +394,60 @@ inline constexpr TypeDesc TypeUstringhash(TypeDesc::USTRINGHASH);
 ///
 template<typename T> struct BaseTypeFromC {};
 template<> struct BaseTypeFromC<unsigned char> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT8; };
+template<> struct BaseTypeFromC<const unsigned char> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT8; };
 template<> struct BaseTypeFromC<char> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT8; };
+template<> struct BaseTypeFromC<const char> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT8; };
 template<> struct BaseTypeFromC<uint16_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT16; };
+template<> struct BaseTypeFromC<const uint16_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT16; };
 template<> struct BaseTypeFromC<int16_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT16; };
+template<> struct BaseTypeFromC<const int16_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT16; };
 template<> struct BaseTypeFromC<uint32_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT; };
+template<> struct BaseTypeFromC<const uint32_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT; };
 template<> struct BaseTypeFromC<int32_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT; };
+template<> struct BaseTypeFromC<const int32_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT; };
 template<> struct BaseTypeFromC<uint64_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT64; };
+template<> struct BaseTypeFromC<const uint64_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT64; };
 template<> struct BaseTypeFromC<int64_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT64; };
+template<> struct BaseTypeFromC<const int64_t> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT64; };
 #if defined(__GNUC__) && __WORDSIZE == 64 && !(defined(__APPLE__) && defined(__MACH__))
 // Some platforms consider int64_t and long long to be different types, even
 // though they are actually the same size.
 static_assert(!std::is_same_v<unsigned long long, uint64_t>);
 static_assert(!std::is_same_v<long long, int64_t>);
 template<> struct BaseTypeFromC<unsigned long long> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT64; };
+template<> struct BaseTypeFromC<const unsigned long long> { static constexpr TypeDesc::BASETYPE value = TypeDesc::UINT64; };
 template<> struct BaseTypeFromC<long long> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT64; };
+template<> struct BaseTypeFromC<const long long> { static constexpr TypeDesc::BASETYPE value = TypeDesc::INT64; };
 #endif
 #if defined(_HALF_H_) || defined(IMATH_HALF_H_)
 template<> struct BaseTypeFromC<half> { static constexpr TypeDesc::BASETYPE value = TypeDesc::HALF; };
+template<> struct BaseTypeFromC<const half> { static constexpr TypeDesc::BASETYPE value = TypeDesc::HALF; };
 #endif
 template<> struct BaseTypeFromC<float> { static constexpr TypeDesc::BASETYPE value = TypeDesc::FLOAT; };
+template<> struct BaseTypeFromC<const float> { static constexpr TypeDesc::BASETYPE value = TypeDesc::FLOAT; };
 template<> struct BaseTypeFromC<double> { static constexpr TypeDesc::BASETYPE value = TypeDesc::DOUBLE; };
-template<> struct BaseTypeFromC<const char*> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
+template<> struct BaseTypeFromC<const double> { static constexpr TypeDesc::BASETYPE value = TypeDesc::DOUBLE; };
 template<> struct BaseTypeFromC<char*> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
+template<> struct BaseTypeFromC<const char*> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 template<> struct BaseTypeFromC<std::string> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
+template<> struct BaseTypeFromC<const std::string> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 template<> struct BaseTypeFromC<string_view> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
+template<> struct BaseTypeFromC<const string_view> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 class ustring;
 template<> struct BaseTypeFromC<ustring> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
+template<> struct BaseTypeFromC<const ustring> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 template<size_t S> struct BaseTypeFromC<char[S]> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 template<size_t S> struct BaseTypeFromC<const char[S]> { static constexpr TypeDesc::BASETYPE value = TypeDesc::STRING; };
 template<typename P> struct BaseTypeFromC<P*> { static constexpr TypeDesc::BASETYPE value = TypeDesc::PTR; };
 
 /// `BaseTypeFromC_v<T>` is shorthand for `BaseTypeFromC<T>::value()`.
 template<typename T>
-constexpr TypeDesc::BASETYPE BaseTypeFromC_v = BaseTypeFromC<std::remove_cv_t<T>>::value();
+constexpr TypeDesc::BASETYPE BaseTypeFromC_v = BaseTypeFromC<std::remove_cv_t<T>>::value;
 
 /// A template mechanism for getting the TypeDesc from a C type.
 /// The default for simple types is just the TypeDesc based on BaseTypeFromC.
 /// But we can specialize more complex types.
-template<typename T> struct TypeDescFromC { static const constexpr TypeDesc value() { return TypeDesc(BaseTypeFromC<T>::value); } };
+template<typename T> struct TypeDescFromC { static const constexpr TypeDesc value() { return TypeDesc(BaseTypeFromC_v<T>); } };
 template<> struct TypeDescFromC<int32_t> { static const constexpr TypeDesc value() { return TypeDesc::INT32; } };
 template<> struct TypeDescFromC<uint32_t> { static const constexpr TypeDesc value() { return TypeDesc::UINT32; } };
 template<> struct TypeDescFromC<int16_t> { static const constexpr TypeDesc value() { return TypeDesc::INT16; } };

src/include/OpenImageIO/typedesc.h

@@ -89,7 +89,7 @@ get_default_quantize(TypeDesc format, long long& quant_min,
 /// which is either dst or src (if the strides indicated that data were
 /// already contiguous).
 OIIO_API span<const std::byte>
-contiguize(image_span<const std::byte> src, span<std::byte> dst);
+contiguize(const image_span<const std::byte>& src, span<std::byte> dst);
 
 /// Turn potentially non-contiguous-stride data (e.g. "RGBxRGBx") into
 /// contiguous-stride ("RGBRGB"), for any format or stride values

src/include/imageio_pvt.h

@@ -349,6 +349,124 @@ test_image_span_convert_image()
 
 
 
+// Sum all values in an image using a pass-by-value image_span
+float
+sum_image_span_val(image_span<const float> img)
+{
+    float sum = 0;
+    for (uint32_t z = 0; z < img.depth(); ++z) {
+        for (uint32_t y = 0; y < img.height(); ++y) {
+            for (uint32_t x = 0; x < img.width(); ++x) {
+                for (uint32_t c = 0; c < img.nchannels(); ++c) {
+                    sum += img.get(c, x, y, z);
+                }
+            }
+        }
+    }
+    return sum;
+}
+
+
+// Sum all values in an image using a pass-by-reference image_span
+float
+sum_image_span_ref(const image_span<const float>& img)
+{
+    float sum = 0;
+    for (uint32_t z = 0; z < img.depth(); ++z) {
+        for (uint32_t y = 0; y < img.height(); ++y) {
+            for (uint32_t x = 0; x < img.width(); ++x) {
+                for (uint32_t c = 0; c < img.nchannels(); ++c) {
+                    sum += img.get(c, x, y, z);
+                }
+            }
+        }
+    }
+    return sum;
+}
+
+
+// Sum all values in an image using raw pointers, sizes, strides
+float
+sum_image_span_ptr(const float* ptr, uint32_t chans, uint32_t width,
+                   uint32_t height, uint32_t depth, int64_t chstride,
+                   int64_t xstride, int64_t ystride, int64_t zstride)
+{
+    float sum = 0;
+    for (uint32_t z = 0; z < depth; ++z) {
+        for (uint32_t y = 0; y < height; ++y) {
+            for (uint32_t x = 0; x < width; ++x) {
+                for (uint32_t c = 0; c < chans; ++c) {
+                    const float* p = reinterpret_cast<const float*>(
+                        (const char*)ptr + c * chstride + x * xstride
+                        + y * ystride + z * zstride);
+                    sum += *p;
+                }
+            }
+        }
+    }
+    return sum;
+}
+
+
+
+void
+benchmark_image_span_passing()
+{
+    print("\nbenchmark_image_span_passing\n");
+    const int xres = 2048, yres = 1536, nchans = 4;
+    std::vector<float> sbuf(xres * yres * nchans, 1.0f);
+    image_span<const float> ispan(sbuf.data(), nchans, xres, yres, 1);
+
+    Benchmarker bench;
+    bench.units(Benchmarker::Unit::us);
+    float sum = 0.0f;
+
+    bench("  pass by value     (big)",
+          [=, &sum]() { sum += sum_image_span_val(ispan); });
+    bench("  pass by value imm (big)", [=, &sum]() {
+        sum += sum_image_span_val(
+            image_span<const float>(sbuf.data(), nchans, xres, yres, 1));
+    });
+    bench("  pass by ref       (big)",
+          [=, &sum]() { sum += sum_image_span_ref(ispan); });
+    bench("  pass by ref imm   (big)", [=, &sum]() {
+        sum += sum_image_span_ref(
+            image_span<const float>(sbuf.data(), nchans, xres, yres, 1));
+    });
+    bench("  pass by ptr       (big)", [=, &sum]() {
+        sum += sum_image_span_ptr(sbuf.data(), nchans, xres, yres, 1,
+                                  sizeof(float), nchans * sizeof(float),
+                                  nchans * sizeof(float) * xres,
+                                  nchans * sizeof(float) * xres * yres);
+    });
+
+    // Do it all again for a SMALL image
+    bench.units(Benchmarker::Unit::ns);
+    int small = 16;
+    image_span<const float> smispan(sbuf.data(), nchans, small, small, 1);
+    bench("  pass by value     (small)",
+          [=, &sum]() { sum += sum_image_span_val(smispan); });
+    bench("  pass by value imm (small)", [=, &sum]() {
+        sum += sum_image_span_val(
+            image_span<const float>(sbuf.data(), nchans, small, small, 1));
+    });
+    bench("  pass by ref       (small)",
+          [=, &sum]() { sum += sum_image_span_ref(smispan); });
+    bench("  pass by ref imm   (small)", [=, &sum]() {
+        sum += sum_image_span_ref(
+            image_span<const float>(sbuf.data(), nchans, small, small, 1));
+    });
+    bench("  pass by ptr       (small)", [=, &sum]() {
+        sum += sum_image_span_ptr(sbuf.data(), nchans, small, small, 1,
+                                  sizeof(float), nchans * sizeof(float),
+                                  nchans * sizeof(float) * small,
+                                  nchans * sizeof(float) * small * small);
+    });
+    print("  [sum={}]\n", sum);  // seems necessary to not optimize away
+}
+
+
+
 int
 main(int /*argc*/, char* /*argv*/[])
 {
@@ -378,5 +496,7 @@ main(int /*argc*/, char* /*argv*/[])
     test_image_span_convert_image<uint16_t, half>();
     test_image_span_convert_image<half, uint16_t>();
 
+    benchmark_image_span_passing();
+
     return unit_test_failures;
 }

src/libOpenImageIO/image_span_test.cpp

@@ -739,7 +739,7 @@ _contiguize(const T* src, int nchannels, stride_t xstride, stride_t ystride,
 
 
 span<const std::byte>
-pvt::contiguize(image_span<const std::byte> src, span<std::byte> dst)
+pvt::contiguize(const image_span<const std::byte>& src, span<std::byte> dst)
 {
     // Contiguized result must fit in dst
     OIIO_DASSERT(src.size_bytes() <= dst.size_bytes());
@@ -1058,7 +1058,8 @@ copy_image(int nchannels, int width, int height, int depth, const void* src,
 
 template<typename T>
 void
-aligned_copy_image(image_span<std::byte> dst, image_span<const std::byte> src)
+aligned_copy_image(const image_span<std::byte>& dst,
+                   const image_span<const std::byte>& src)
 {
     size_t systride  = src.ystride();
     size_t dystride  = dst.ystride();
@@ -1086,7 +1087,8 @@ aligned_copy_image(image_span<std::byte> dst, image_span<const std::byte> src)
 
 
 bool
-copy_image(image_span<std::byte> dst, image_span<const std::byte> src)
+copy_image(const image_span<std::byte>& dst,
+           const image_span<const std::byte>& src)
 {
     OIIO_DASSERT(src.width() == dst.width() && src.height() == dst.height()
                  && src.depth() == dst.depth()