api: image_span_within_span (#4784)

A utility to confirm that an image_span (possibly with non-contiguous
strides) entirely fits within another contiguous span.

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

Author: lgritz

src/include/OpenImageIO/image_span.h

@@ -387,5 +387,21 @@ as_image_span_writable_bytes(const image_span<T, Rank>& src) noexcept
 }
 
 
+/// Verify that the image_span has all its contents lying within the
+/// contiguous span.
+OIIO_API bool
+image_span_within_span(const image_span<const std::byte>& ispan,
+                       span<const std::byte> contiguous) noexcept;
+
+/// image_span_within_span() for generic span types. Just reduce to
+/// const byte versions.
+template<typename T, size_t Trank, typename S>
+bool
+image_span_within_span(const image_span<T, Trank>& ispan,
+                       span<S> contiguous) noexcept
+{
+    return image_span_within_span(as_image_span_bytes(ispan),
+                                  as_bytes(contiguous));
+}
 
 OIIO_NAMESPACE_END

src/libOpenImageIO/image_span_test.cpp

@@ -467,6 +467,83 @@ benchmark_image_span_passing()
 
 
 
+void
+test_image_span_within_span()
+{
+    print("\ntest_image_span_within_span\n");
+
+    const int nchans = 3, xres = 5, yres = 7, zres = 11;
+    const int chstride = sizeof(float), xstride = chstride * nchans,
+              ystride = xstride * xres, zstride = ystride * yres;
+    float array[nchans * xres * yres * zres];
+    cspan<float> aspan(array);
+    // It better worrk with the same origin and default strides
+    OIIO_CHECK_ASSERT(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride, ystride, zstride),
+                               aspan));
+    // Make sure too big are recognized
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride + 1, xstride, ystride,
+                                          zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride + 1, ystride,
+                                          zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride, ystride + 1,
+                                          zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride, ystride,
+                                          zstride + 1),
+                               aspan));
+    // Make sure negagive strides used CORRECTLY are recognized
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          -chstride, xstride, ystride, zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, -xstride, ystride, zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride, -ystride, zstride),
+                               aspan));
+    OIIO_CHECK_FALSE(
+        image_span_within_span(image_span(array, nchans, xres, yres, zres,
+                                          chstride, xstride, ystride, -zstride),
+                               aspan));
+    // Make sure negagive strides used CORRECTLY are recognized
+    OIIO_CHECK_ASSERT(
+        image_span_within_span(image_span(array + nchans - 1, nchans, xres,
+                                          yres, zres, -chstride, xstride,
+                                          ystride, zstride),
+                               aspan));
+    OIIO_CHECK_ASSERT(
+        image_span_within_span(image_span(array + (xres - 1) * nchans, nchans,
+                                          xres, yres, zres, chstride, -xstride,
+                                          ystride, zstride),
+                               aspan));
+    OIIO_CHECK_ASSERT(
+        image_span_within_span(image_span(array + (yres - 1) * xres * nchans,
+                                          nchans, xres, yres, zres, chstride,
+                                          xstride, -ystride, zstride),
+                               aspan));
+    OIIO_CHECK_ASSERT(image_span_within_span(
+        image_span(array + (zres - 1) * xres * yres * nchans, nchans, xres,
+                   yres, zres, chstride, xstride, ystride, -zstride),
+        aspan));
+}
+
+
+
 int
 main(int /*argc*/, char* /*argv*/[])
 {
@@ -496,6 +573,8 @@ main(int /*argc*/, char* /*argv*/[])
     test_image_span_convert_image<uint16_t, half>();
     test_image_span_convert_image<half, uint16_t>();
 
+    test_image_span_within_span();
+
     benchmark_image_span_passing();
 
     return unit_test_failures;

src/libOpenImageIO/imageio.cpp

@@ -1356,4 +1356,45 @@ wrap_mirror(int& coord, int origin, int width)
 }
 
 
+
+/// Verify that the image_span has all its contents lying within the
+/// contiguous span.
+bool
+image_span_within_span(const image_span<const std::byte>& ispan,
+                       span<const std::byte> contiguous) noexcept
+{
+    // Start with first,last being the first byte of pixel 0, channel 0
+    const std::byte* first = ispan.data();  // first byte of ispan
+    const std::byte* last  = ispan.data();  // last byte of ispan
+    // Extend them to the start of the first pixel of the first and last image
+    // plane.
+    if (ispan.zstride() > 0)
+        last += ispan.zstride() * (ispan.depth() - 1);
+    else
+        first += ispan.zstride() * (ispan.depth() - 1);  // neg stride
+    // Extend them to the start of the first pixel of the first and last
+    // scanline of the first and last image plane.
+    if (ispan.ystride() > 0)
+        last += ispan.ystride() * (ispan.height() - 1);
+    else
+        first += ispan.ystride() * (ispan.height() - 1);  // neg stride
+    // Extend them to the start of the first pixel of the first and last
+    // column of the first and last scanline of the first and last image
+    // plane.
+    if (ispan.xstride() > 0)
+        last += ispan.xstride() * (ispan.width() - 1);
+    else
+        first += ispan.xstride() * (ispan.width() - 1);  // neg stride
+    // Make sure they cover the whole of those extreme pixels
+    if (ispan.chanstride() > 0)
+        last += ispan.chanstride() * (ispan.nchannels() - 1);
+    else
+        first += ispan.chanstride() * (ispan.nchannels() - 1);  // neg stride
+    // Make sure last covers the whole data type
+    last += ispan.chansize() - 1;
+    return (first >= contiguous.data()
+            && last < contiguous.data() + contiguous.size());
+}
+
+
 OIIO_NAMESPACE_END