api: image_span-ify ImageBuf (#4814)

We've already done ImageInput, ImageOutput, ImageCache, TextureSystem.

This applies the analogous set of changes to the public APIs of ImageBuf
-- adding span and image_span versions of all the API calls that
previously required raw pointers and strides. Many of the internals are
still using the old versions, but at least this takes care of the
interface.

Specifically, this does constructors, reset(), and get_pixels().

---------

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

Author: lgritz

src/doc/imagebuf.rst

@@ -62,6 +62,9 @@ Constructing a writable ImageBuf
 Constructing an ImageBuf that "wraps" an application buffer
 -------------------------------------------------------------
 
+.. doxygenfunction:: OIIO::ImageBuf::ImageBuf(const ImageSpec &spec, const image_span<T>&)
+.. doxygenfunction:: OIIO::ImageBuf::reset(const ImageSpec &spec, const image_span<T>&)
+
 .. doxygenfunction:: OIIO::ImageBuf::ImageBuf(const ImageSpec &spec, void *buffer, stride_t xstride = AutoStride, stride_t ystride = AutoStride, stride_t zstride = AutoStride)
 .. doxygenfunction:: OIIO::ImageBuf::reset(const ImageSpec &spec, void *buffer, stride_t xstride = AutoStride, stride_t ystride = AutoStride, stride_t zstride = AutoStride)
 
@@ -176,6 +179,16 @@ Getting and setting pixel values
 
 **Getting and setting regions of pixels -- fast**
 
+.. doxygenfunction:: OIIO::ImageBuf::get_pixels(ROI, const image_span<T>&) const
+.. doxygenfunction:: OIIO::ImageBuf::get_pixels(ROI, TypeDesc, const image_span<std::byte>&) const
+
+|
+
+**Getting and setting regions of pixels -- deprecated**
+
+These raw pointer versions of `get_pixels()` and `set_pixels()` should be
+converted to the `span` and `image_span` based versions.
+
 .. doxygenfunction:: OIIO::ImageBuf::get_pixels(ROI, span<T>, stride_t, stride_t, stride_t) const
 .. doxygenfunction:: OIIO::ImageBuf::get_pixels(ROI, span<T>, T*, stride_t, stride_t, stride_t) const
 .. doxygenfunction:: OIIO::ImageBuf::set_pixels(ROI, span<T>, stride_t, stride_t, stride_t)

src/include/OpenImageIO/image_span.h

@@ -70,7 +70,6 @@ template<typename T, size_t Rank = 4> class image_span {
         // Validations:
         // - an image_span<byte> can have any chansize, but any other T must
         //   have the chansize equal to the data type size.
-        OIIO_DASSERT(nchannels > 0 && width > 0 && height > 0 && depth > 0);
         OIIO_DASSERT((std::is_same<std::remove_const_t<T>, std::byte>::value)
                      || chansize == sizeof(T));
 
@@ -374,8 +373,8 @@ as_image_span_bytes(const image_span<T, Rank>& src) noexcept
 }
 
 
-/// Convert an image_span of any type to a mutable span of bytes covering
-/// the same range of memory.
+/// Convert an image_span of any nonconst type to a mutable span of bytes
+/// covering the same range of memory.
 template<typename T, size_t Rank>
 image_span<std::byte>
 as_image_span_writable_bytes(const image_span<T, Rank>& src) noexcept
@@ -386,7 +385,6 @@ as_image_span_writable_bytes(const image_span<T, Rank>& src) noexcept
                                  src.ystride(), src.zstride(), src.chansize());
 }
 
-
 /// Verify that the image_span has all its contents lying within the
 /// contiguous span.
 OIIO_API bool

src/include/OpenImageIO/imagebuf.h

@@ -281,6 +281,40 @@ class OIIO_API ImageBuf {
              void* buforigin = nullptr, stride_t xstride = AutoStride,
              stride_t ystride = AutoStride, stride_t zstride = AutoStride);
 
+    /// Construct an ImageBuf that "wraps" existing pixel memory owned by the
+    /// calling application. The ImageBuf does not own the pixel storage and
+    /// will not free/delete that memory, even when the ImageBuf is destroyed.
+    /// Upon successful initialization, the storage will be reported as
+    /// `APPBUFFER`. Note that the ImageBuf will be writable if passed an
+    /// `image_span<T>` with a mutable type `T`, but it will be "read-only" if
+    /// passed an `image_span<const T>`.
+    ///
+    /// @param spec
+    ///             An ImageSpec describing the image and its metadata. If
+    ///             not enough information is given to know the "shape" of
+    ///             the image (width, height, depth, channels, and data
+    ///             format), the ImageBuf will remain in an UNINITIALIZED
+    ///             state.
+    /// @param buffer
+    ///             An image_span delineating the extent and striding of the
+    ///             safely accessible memory comprising the pixel data.
+    template<typename T>
+    ImageBuf(const ImageSpec& spec, const image_span<T>& buffer)
+        : ImageBuf(spec, as_image_span_writable_bytes(buffer))
+    {
+    }
+    template<typename T>
+    ImageBuf(const ImageSpec& spec, const image_span<const T>& buffer)
+        : ImageBuf(spec, as_image_span_bytes(buffer))
+    {
+    }
+    // Special base case for read-only byte image_spans, this one does the
+    // hard work.
+    ImageBuf(const ImageSpec& spec, const image_span<const std::byte>& buffer);
+    // Special base case for mutable byte image_spans, this one does the hard
+    // work.
+    ImageBuf(const ImageSpec& spec, const image_span<std::byte>& buffer);
+
     // Unsafe constructor of an ImageBuf that wraps an existing buffer, where
     // only the origin pointer and the strides are given. Use with caution!
     OIIO_IB_DEPRECATE_RAW_PTR
@@ -332,6 +366,28 @@ class OIIO_API ImageBuf {
         set_name(name);
     }
 
+    /// Destroy any previous contents of the ImageBuf and re-initialize it as
+    /// if newly constructed with the same arguments, to "wrap" existing pixel
+    /// memory owned by the calling application. See the ImageBuf constructor
+    /// from an image_span for more details.
+    template<typename T>
+    void reset(const ImageSpec& spec, const image_span<T>& buffer)
+    {
+        // The general case for non-byte data types just converts to bytes and
+        // calls the byte version.
+        if constexpr (std::is_const_v<T>)
+            reset(spec, as_image_span_bytes(buffer));
+        else
+            reset(spec, as_image_span_writable_bytes(buffer));
+    }
+    // Special base case for read-only byte spans, this one does the hard work.
+    void reset(const ImageSpec& spec,
+               const image_span<const std::byte>& buffer);
+    // Special base case for mutable byte spans, this one does the hard work.
+    void reset(const ImageSpec& spec, const image_span<std::byte>& buffer);
+
+    /// Slated for deprecation in favor of the image_span-based version.
+    ///
     /// Destroy any previous contents of the ImageBuf and re-initialize it as
     /// if newly constructed with the same arguments, to "wrap" existing pixel
     /// memory owned by the calling application.
@@ -929,6 +985,33 @@ class OIIO_API ImageBuf {
         setpixel(i, make_cspan(pixel, size_t(n)));
     }
 
+    /// Retrieve the rectangle of pixels spanning the ROI (including
+    /// channels) at the current subimage and MIP-map level, storing the
+    /// pixel values into the `buffer`.
+    ///
+    /// @param roi
+    ///             The region of interest to copy into. A default
+    ///             uninitialized ROI means the entire image.
+    /// @param buffer
+    ///             An image_span delineating the extent of the safely
+    ///             accessible memory where the results should be stored.
+    /// @returns
+    ///             Return true if the operation could be completed,
+    ///             otherwise return false.
+    ///
+    template<typename T>
+    bool get_pixels(ROI roi, const image_span<T>& buffer) const
+    {
+        static_assert(!std::is_const_v<T>);
+        return get_pixels(roi, TypeDescFromC<T>::value(),
+                          as_image_span_writable_bytes(buffer));
+    }
+
+    /// Base case of get_pixels: read into an image_span of generic bytes. The
+    /// requested data type is supplied by `format`.
+    bool get_pixels(ROI roi, TypeDesc format,
+                    const image_span<std::byte>& buffer) const;
+
     /// Retrieve the rectangle of pixels spanning the ROI (including
     /// channels) at the current subimage and MIP-map level, storing the
     /// pixel values into the `buffer`.
@@ -981,13 +1064,13 @@ class OIIO_API ImageBuf {
 
 #ifndef OIIO_DOXYGEN
     /// Base case of get_pixels: read into a span of generic bytes. The
-    /// requested data type is supplied by `format.
+    /// requested data type is supplied by `format`.
     bool get_pixels(ROI roi, TypeDesc format, span<std::byte> buffer,
                     void* buforigin = nullptr, stride_t xstride = AutoStride,
                     stride_t ystride = AutoStride,
                     stride_t zstride = AutoStride) const;
 
-    /// Potentially unsafe get_pixels() using raw pointers. Use with catution!
+    /// Potentially unsafe get_pixels() using raw pointers. Use with caution!
     OIIO_IB_DEPRECATE_RAW_PTR
     bool get_pixels(ROI roi, TypeDesc format, void* result,
                     stride_t xstride = AutoStride,
@@ -1053,7 +1136,7 @@ class OIIO_API ImageBuf {
 
 #ifndef OIIO_DOXYGEN
     /// Base case of get_pixels: read into a span of generic bytes. The
-    /// requested data type is supplied by `format.
+    /// requested data type is supplied by `format`.
     bool set_pixels(ROI roi, TypeDesc format, cspan<std::byte> buffer,
                     const void* buforigin = nullptr,
                     stride_t xstride      = AutoStride,