api: image_span-ify ImageCache and TextureSystem (#4783)

I think this is all the span-izing that the public interface of
ImageCache and TextureSystem needs. And it doesn't break ABI
compatibility (unlike the ImageInput and ImageOutput changes recently)
because these aren't virtual methods.

---------

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

Author: lgritz

src/doc/imagecache.rst

@@ -60,8 +60,8 @@ Below are some simple code fragments that shows ImageCache in action::
     // (for brevity of this example, let's assume that 'size' is the
     // number of channels times the number of pixels in the requested region)
     float pixels[size];
-    cache->get_pixels ("file1.jpg", 0, 0, xbegin, xend, ybegin, yend,
-                       zbegin, zend, TypeDesc::FLOAT, pixels);
+    cache->get_pixels ("file1.jpg", 0, 0, ROI(xbegin, xend, ybegin, yend),
+                       make_span(pixels));
 
     // Get information about a file
     ImageSpec spec;

src/include/OpenImageIO/imagecache.h

@@ -872,6 +872,139 @@ class OIIO_API ImageCache {
     /// @{
     /// @name   Getting Pixels
 
+    /// For an image specified by name, retrieve the rectangle of pixels from
+    /// the designated subimage and MIP level, storing the pixel values in the
+    /// memory layout specified by `result`.  The pixel values will be
+    /// converted to the data type specified by `format`. The rectangular
+    /// region to be retrieved, specified by `roi`, includes `begin` but does
+    /// not include `end` (much like STL begin/end usage). Requested pixels
+    /// that are not part of the valid pixel data region of the image file
+    /// will be filled with zero values.
+    ///
+    /// @param  filename
+    ///             The name of the image, as a UTF-8 encoded ustring.
+    /// @param  subimage/miplevel
+    ///             The subimage and MIP level to retrieve pixels from.
+    /// @param  roi
+    ///             The range of pixels and channels to retrieve. The pixels
+    ///             retrieved include the begin values but not the end values
+    ///             (much like STL begin/end usage).
+    /// @param  format
+    ///             TypeDesc describing the data type of the values you want
+    ///             to retrieve into `result`. The pixel values will be
+    ///             converted to this type regardless of how they were
+    ///             stored in the cache.
+    /// @param  result
+    ///             An `image_span` describing the memory layout where the
+    ///             pixel values should be  stored, including bounds and
+    ///             strides for each dimension.
+    /// @param  cache_chbegin/cache_chend
+    ///             These parameters can be used to tell the ImageCache to
+    ///             read and cache a subset of channels (if not specified or
+    ///             if they denote a non-positive range, all the channels of
+    ///             the file will be stored in the cached tile).
+    /// @returns    `true` upon success, or `false` upon failure.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    ///
+    bool get_pixels(ustring filename, int subimage, int miplevel,
+                    const ROI& roi, TypeDesc format,
+                    const image_span<std::byte>& result, int cache_chbegin = 0,
+                    int cache_chend = -1);
+    /// A more efficient variety of `get_pixels()` for cases where you can use
+    /// an `ImageHandle*` to specify the image and optionally have a
+    /// `Perthread*` for the calling thread.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    bool get_pixels(ImageHandle* file, Perthread* thread_info, int subimage,
+                    int miplevel, const ROI& roi, TypeDesc format,
+                    const image_span<std::byte>& result, int cache_chbegin = 0,
+                    int cache_chend = -1);
+
+    /// A version of `get_pixels()` taking an `image_span<T>`, where the type
+    /// of the underlying data is `T`.  This is a convenience wrapper around
+    /// the `get_pixels()` that takes an `image_span<std::byte>`.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    template<typename T>
+    bool get_pixels(ustring filename, int subimage, int miplevel,
+                    const ROI& roi, const image_span<T>& result,
+                    int cache_chbegin = 0, int cache_chend = -1)
+    {
+        static_assert(!std::is_const_v<T>,
+                      "get_pixels() does not accept image_span<const T>");
+        return get_pixels(filename, subimage, miplevel, roi,
+                          TypeDescFromC<T>::value(),
+                          as_image_span_writable_bytes(result), cache_chbegin,
+                          cache_chend);
+    }
+    /// A more efficient variety of `get_pixels()` taking an `image_span<T>`,
+    /// for cases where you can use an `ImageHandle*` to specify the image and
+    /// optionally have a `Perthread*` for the calling thread.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    template<typename T>
+    bool get_pixels(ImageHandle* file, Perthread* thread_info, int subimage,
+                    int miplevel, const ROI& roi, const image_span<T>& result,
+                    int cache_chbegin = 0, int cache_chend = -1)
+    {
+        static_assert(!std::is_const_v<T>,
+                      "get_pixels() does not accept image_span<const T>");
+        return get_pixels(file, thread_info, subimage, miplevel, roi,
+                          TypeDescFromC<T>::value(),
+                          as_image_span_writable_bytes(result), cache_chbegin,
+                          cache_chend);
+    }
+
+    /// A version of `get_pixels()` taking a `span<T>`, which assumes
+    /// contiguous strides in all dimensions. This is a convenience wrapper
+    /// around the `get_pixels()` that takes an `image_span<T>`.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    template<typename T>
+    bool get_pixels(ImageHandle* file, Perthread* thread_info, int subimage,
+                    int miplevel, const ROI& roi, const span<T>& result,
+                    int cache_chbegin = 0, int cache_chend = -1)
+    {
+        static_assert(!std::is_const_v<T>,
+                      "get_pixels() does not accept span<const T>");
+        auto ispan = image_span<T>(result.data(), roi.nchannels(), roi.width(),
+                                   roi.height(), roi.depth());
+        OIIO_DASSERT(result.size_bytes() == ispan.size_bytes()
+                     && ispan.is_contiguous());
+        return get_pixels(file, thread_info, subimage, miplevel, roi,
+                          TypeDescFromC<T>::value(),
+                          as_image_span_writable_bytes(result), cache_chbegin,
+                          cache_chend);
+    }
+    /// A more efficient variety of `get_pixels()` taking a `span<T>`, for
+    /// cases where you can use an `ImageHandle*` to specify the image and
+    /// optionally have a `Perthread*` for the calling thread.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    template<typename T>
+    bool get_pixels(ustring filename, int subimage, int miplevel,
+                    const ROI& roi, const span<T>& result,
+                    int cache_chbegin = 0, int cache_chend = -1)
+    {
+        static_assert(!std::is_const_v<T>,
+                      "get_pixels() does not accept span<const T>");
+        auto ispan = image_span<T>(result.data(), roi.nchannels(), roi.width(),
+                                   roi.height(), roi.depth());
+        OIIO_DASSERT(result.size_bytes() == ispan.size_bytes()
+                     && ispan.is_contiguous());
+        return get_pixels(filename, subimage, miplevel, roi,
+                          TypeDescFromC<T>::value(),
+                          as_image_span_writable_bytes(result), cache_chbegin,
+                          cache_chend);
+    }
+
     /// For an image specified by name, retrieve the rectangle of pixels
     /// from the designated subimage and MIP level, storing the pixel values
     /// beginning at the address specified by `result` and with the given
@@ -881,6 +1014,10 @@ class OIIO_API ImageCache {
     /// usage). Requested pixels that are not part of the valid pixel data
     /// region of the image file will be filled with zero values.
     ///
+    /// These pointer-based versions are considered "soft-deprecated" in
+    /// OpenImageIO 3.1, will be marked/warned as deprecated in 3.2, and will
+    /// be removed in 4.0.
+    ///
     /// @param  filename
     ///             The name of the image, as a UTF-8 encoded ustring.
     /// @param  subimage/miplevel
@@ -926,6 +1063,10 @@ class OIIO_API ImageCache {
     /// A more efficient variety of `get_pixels()` for cases where you can
     /// use an `ImageHandle*` to specify the image and optionally have a
     /// `Perthread*` for the calling thread.
+    ///
+    /// These pointer-based versions are considered "soft-deprecated" in
+    /// OpenImageIO 3.1, will be marked/warned as deprecated in 3.2, and will
+    /// be removed in 4.0.
     bool get_pixels(ImageHandle* file, Perthread* thread_info, int subimage,
                     int miplevel, int xbegin, int xend, int ybegin, int yend,
                     int zbegin, int zend, int chbegin, int chend,
@@ -937,15 +1078,24 @@ class OIIO_API ImageCache {
 
     /// A simplified `get_pixels()` where all channels are retrieved,
     /// strides are assumed to be contiguous.
+    ///
+    /// These pointer-based versions are considered "soft-deprecated" in
+    /// OpenImageIO 3.1, will be marked/warned as deprecated in 3.2, and will
+    /// be removed in 4.0.
     bool get_pixels(ustring filename, int subimage, int miplevel, int xbegin,
                     int xend, int ybegin, int yend, int zbegin, int zend,
                     TypeDesc format, void* result);
     /// A more efficient variety of `get_pixels()` for cases where you can
     /// use an `ImageHandle*` to specify the image and optionally have a
     /// `Perthread*` for the calling thread.
+    ///
+    /// These pointer-based versions are considered "soft-deprecated" in
+    /// OpenImageIO 3.1, will be marked/warned as deprecated in 3.2, and will
+    /// be removed in 4.0.
     bool get_pixels(ImageHandle* file, Perthread* thread_info, int subimage,
                     int miplevel, int xbegin, int xend, int ybegin, int yend,
                     int zbegin, int zend, TypeDesc format, void* result);
+
     /// @}
 
     /// @{
@@ -1085,6 +1235,34 @@ class OIIO_API ImageCache {
                   stride_t ystride = AutoStride, stride_t zstride = AutoStride,
                   bool copy = true);
 
+    /// Preemptively add a tile corresponding to the named image, at the given
+    /// subimage, MIP level, and channel range.  The tile added is the one
+    /// whose corner is (x,y,z), and buffer points to the pixels (in the given
+    /// format) which will be copied and inserted into the cache and made
+    /// available for future lookups. If chend < chbegin, it will add a tile
+    /// containing the full set of channels for the image. Note that if the
+    /// 'copy' flag is false, the data is assumed to be in some kind of
+    /// persistent storage and will not be copied, nor will its pixels take up
+    /// additional memory in the cache.
+    bool add_tile(ustring filename, int subimage, int miplevel, int x, int y,
+                  int z, int chbegin, int chend, TypeDesc format,
+                  const image_span<const std::byte>& buffer, bool copy = true);
+
+    /// A version of `add_tile()` taking an `image_span<T>`, where the type of
+    /// the underlying data is `T`.  This is a convenience wrapper around the
+    /// `add_tile()` that takes an `image_span<std::byte>`.
+    template<typename T>
+    bool add_tile(ustring filename, int subimage, int miplevel, int x, int y,
+                  int z, int chbegin, int chend, const image_span<T>& buffer,
+                  bool copy = true)
+    {
+        static_assert(!std::is_const_v<T>,
+                      "add_tile() does not accept image_span<const T>");
+        return add_tile(filename, subimage, miplevel, x, y, z, chbegin, chend,
+                        TypeDescFromC<T>::value(), as_image_span_bytes(buffer),
+                        copy);
+    }
+
     /// @}
 
     /// @{

src/include/OpenImageIO/texture.h

@@ -1514,6 +1514,62 @@ class OIIO_API TextureSystem {
     /// @param  miplevel
     ///             The MIP level to retrieve pixels from (0 is the highest
     ///             resolution level).
+    /// @param  roi
+    ///             The range of pixels and channels to retrieve. The pixels
+    ///             retrieved include the begin values but not the end values
+    ///             (much like STL begin/end usage).
+    /// @param  format
+    ///             TypeDesc describing the data type of the values you want
+    ///             to retrieve into `result`. The pixel values will be
+    ///             converted to this type regardless of how they were
+    ///             stored in the file or in the cache.
+    /// @param  result
+    ///             An `image_span` describing the memory layout where the
+    ///             pixel values should be  stored, including bounds and
+    ///             strides for each dimension.
+    /// @returns
+    ///             `true` for success, `false` for failure.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    ///
+    bool get_texels(ustring filename, TextureOpt& options, int miplevel,
+                    const ROI& roi, TypeDesc format,
+                    const image_span<std::byte>& result);
+    /// A more efficient variety of `get_texels()` for cases where you can
+    /// use a `TextureHandle*` to specify the image and optionally have a
+    /// `Perthread*` for the calling thread.
+    ///
+    /// Added in OIIO 3.1, this is the "safe" preferred alternative to
+    /// the version of read_scanlines that takes raw pointers.
+    bool get_texels(TextureHandle* texture_handle, Perthread* thread_info,
+                    TextureOpt& options, int miplevel, const ROI& roi,
+                    TypeDesc format, const image_span<std::byte>& result);
+
+    /// For a texture specified by name, retrieve the rectangle of raw
+    /// unfiltered texels from the subimage specified in `options` and at
+    /// the designated `miplevel`, storing the pixel values beginning at the
+    /// address specified by `result`.  The pixel values will be converted
+    /// to the data type specified by `format`. The rectangular region to be
+    /// retrieved includes `begin` but does not include `end` (much like STL
+    /// begin/end usage). Requested pixels that are not part of the valid
+    /// pixel data region of the image file will be filled with zero values.
+    /// Channels requested but not present in the file will get the
+    /// `options.fill` value.
+    ///
+    /// These pointer-based versions are considered "soft-deprecated" in
+    /// OpenImageIO 3.1, will be marked/warned as deprecated in 3.2, and will
+    /// be removed in 4.0.
+    ///
+    /// @param  filename
+    ///             The name of the texture, as a UTF-8 encode ustring.
+    /// @param  options
+    ///             A TextureOpt describing access options, including wrap
+    ///             modes, fill value, and subimage, that will be used when
+    ///             retrieving pixels.
+    /// @param  miplevel
+    ///             The MIP level to retrieve pixels from (0 is the highest
+    ///             resolution level).
     /// @param  xbegin/xend/ybegin/yend/zbegin/zend
     ///             The range of pixels to retrieve. The pixels retrieved
     ///             include the begin value but not the end value (much like