api: add image_span, deprecate image_view (#4703)

* `image_span<T,Rank>` is a 2D-to-4D bounded span with byte-measured
strides (describing data layout with dimensions for channel, x, y, z)
for us to have future APIs deal with bounded+strided regions rather than
YOLOing raw pointers. Among other advantages, image_span will have
robust bounds checking in debug builds. It also simplifies interfaces to
pass a single image_span that encapsulates everything about an up-to-4D
data layout, rather than needing to pass a long list of individual
pointers, sizes, and strides.

* I've templated image_span on Rank, but default to Rank=4 and am using
that version only in practice. The templating by rank allows future
expansion to describe one scanline (rank 2) or 2D image plane (Rank 3)
if we want to do so for certain API calls, but I'm not sure yet whether
to bother with that, so for now, the ability to template by Rank is just
flexibility for the future.

* Add image_span based versions of copy_image(), contiguize(),
convert_pixel_values(), convert_image(), and parallel_convert_image()
utilities. I added tests and benchmarks to verify their correctness and
that they have similar performance to the pointer based versions.

* Deprecate image_view, which we did not ever use internally to OIIO or
in its APIs. But since we published the headers, there's a chance it's
used downstream and would be unwise to change its behavior or data
layout. The new image_span is what we will use moving forward so that we
are free to modify it and start with a fresh slate. Keeping the
definition/header for now, but marking it with a deprecation warning.

---------

Signed-off-by: Larry Gritz <[email protected]>

Author: lgritz

src/doc/imageioapi.rst

@@ -95,8 +95,8 @@ Efficient unique strings: ``ustring``
 
 .. _sec-span:
 
-Non-owning array views: ``span`` / ``cspan``
-============================================
+Non-owning contiguous array views: ``span`` / ``cspan``
+=======================================================
 
 .. doxygenclass:: OIIO::span
     :members:
@@ -111,6 +111,18 @@ Additionally, there is a convenience template:
 |
 
 
+.. _sec-span:
+
+Non-owning image array views: ``image_span``
+============================================
+
+.. doxygenclass:: OIIO::image_span
+    :members:
+
+
+|
+
+
 
  .. _sec-ROI:
 

src/include/OpenImageIO/fmath.h

@@ -757,7 +757,7 @@ scaled_conversion(const S& src, F scale, F min, F max)
 template<typename S, typename D>
 void convert_type (const S *src, D *dst, size_t n, D _min, D _max)
 {
-    if (std::is_same<S,D>::value) {
+    if constexpr (std::is_same<S,D>::value) {
         // They must be the same type.  Just memcpy.
         memcpy (dst, src, n*sizeof(D));
         return;
@@ -968,6 +968,25 @@ inline void convert_type (const S *src, D *dst, size_t n)
 
 
 
+/// Copy (type convert) consecutive values from the cspan `src` holding data
+/// of type S into the span `dst` holding the same number of elements of data
+/// of type D.
+///
+/// The conversion is not a simple cast, but correctly remaps the 0.0->1.0
+/// range from and to the full positive range of integral types. It's just a
+/// straight copy if both types are identical. Optional arguments `min` and
+/// `max` can give nonstandard quantizations.
+template<typename S, typename D>
+void convert_type (cspan<S> src, span<D> dst,
+                   D min = std::numeric_limits<D>::min(),
+                   D max = std::numeric_limits<D>::min())
+{
+    OIIO_DASSERT(src.size() == dst.size());
+    convert_type(src.data(), dst.data(), std::min(src.size(), dst.size()),
+                 min, max);
+}
+
+
 
 /// Convert a single value from the type of S to the type of D.
 /// The conversion is not a simple cast, but correctly remaps the
@@ -978,7 +997,7 @@ template<typename S, typename D>
 inline D
 convert_type (const S &src)
 {
-    if (std::is_same<S,D>::value) {
+    if constexpr (std::is_same<S,D>::value) {
         // They must be the same type.  Just return it.
         return (D)src;
     }