api: imagebufalgo.h mark, warn, or remove various deprecations (#4344)

* The old versions (deprecated since 2.0) of IBA::compare() and
computePixelStats() that took a reference to the CompareResults or
PixelStats structure now have deprecation warnings. Use the versions
that return the structure instead.
* The deprecated (often since as far back as 2.0) versions of functions
that took raw pointers to color values now have deprecations warnings.
Use the versions that take `span<>` or `cspan<>` instead. These include
versions of: isConstantColor, isConstantChannel, isMonochrome,
isConstantChannel, colorconvert, fill, checker, add, sub, absdiff, mul,
div, mad, pow, channel_sum, channels, clamp, color_count,
color_range_check, render_text.
* The `histogram()` function that takes a reference to a result vector
(deprecated since 2.0 and previously warned) has been removed. Use the
version that returns the vector instead. The `histogram_draw()`
(deprecated since 2.0 and previously warned) has been removed and has no
replacement since it was always silly.
* The versions of ociodisplay that lacked an `inverse` parameter, which
were marked as deprecated since 2.5, now have deprecation warnings. Use
the version that takes an `inverse` bool.
* The OpenCV-related functions that take old-style IplImage pointers
(deprecated since 2.0) have been removed. Use the modern ones that use
cv::Mat.
* The pre-KWArgs versions of resize, warp, and fit now have deprecation
warnings. Use the versions that take KWArgs instead.
* IBA::type_merge, deprecated since 2.3, now has a deprecation warning.
Instead, use TypeDesc::basetype_merge().

All of the IBA functions with deprecation warnings are additionally
implemented inline, so that they can be easily removed later if
necessary without an ABI break at that time.

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

Author: lgritz

docs/Deprecations-3.0.md

@@ -12,6 +12,9 @@ which only occur once every several years, we allow removal of functionality.
 OpenImageIO v3.0 is a major release that includes removal of many
 long-deprecated API facets. This document lists the deprecations and removals.
 
+NOTE: This is an in-progress document. Some things currently only warning
+about being deprecated will be removed in the final 3.0 release.
+
 ### Glossary
 
 - "Marked as deprecated" means that we consider an API facet to be obsolete,
@@ -29,6 +32,7 @@ long-deprecated API facets. This document lists the deprecations and removals.
 
 ---
 
+---
 
 ## array_view.h
 
@@ -82,6 +86,37 @@ long-deprecated API facets. This document lists the deprecations and removals.
   deprecated since OIIO 1.5, now has deprecation warnings. Use
   `interppixel_NDC()` instead.
 
+## imagebufalgo.h
+
+* The old versions (deprecated since 2.0) of IBA::compare() and
+  computePixelStats() that took a reference to the CompareResults or
+  PixelStats structure now have deprecation warnings. Use the versions that
+  return the structure instead.
+* The deprecated (often since as far back as 2.0) versions of functions that
+  took raw pointers to color values now have deprecations warnings. Use the
+  versions that take `span<>` or `cspan<>` instead. These include versions of:
+  isConstantColor, isConstantChannel, isMonochrome, isConstantChannel,
+  colorconvert, fill, checker, add, sub, absdiff, mul, div, mad, pow,
+  channel_sum, channels, clamp, color_count, color_range_check, render_text.
+* The `histogram()` function that takes a reference to a result vector
+  (deprecated since 2.0 and previously warned) has been removed. Use the
+  version that returns the vector instead. The `histogram_draw()` (deprecated
+  since 2.0 and previously warned) has been removed and has no replacement
+  since it was always silly.
+* The versions of ociodisplay that lacked an `inverse` parameter, which were
+  marked as deprecated since 2.5, now have deprecation warnings. Use the
+  version that takes an `inverse` bool.
+* The OpenCV-related functions that take old-style IplImage pointers
+  (deprecated since 2.0) have been removed. Use the modern ones that use
+  cv::Mat.
+* The pre-KWArgs versions of resize, warp, and fit now have deprecation
+  warnings. Use the versions that take KWArgs instead.
+
+## imagebufalgo_util.h
+
+* IBA::type_merge, deprecated since 2.3, now has a deprecation warning.
+  Instead, use TypeDesc::basetype_merge().
+
 ## missingmath.h
 
 * This header has been removed entirely. It has was originally needed for

src/include/OpenImageIO/imagebufalgo.h

@@ -250,15 +250,18 @@ enum IBAprep_flags {
 
 
 
-// DEPRECATED(2.3): Prefer TypeDesc::basetype_merge().
-TypeDesc::BASETYPE OIIO_API type_merge (TypeDesc::BASETYPE a, TypeDesc::BASETYPE b);
+OIIO_DEPRECATED("Use TypeDesc::basetype_merge [2.3]")
+inline TypeDesc::BASETYPE type_merge (TypeDesc::BASETYPE a, TypeDesc::BASETYPE b)
+{
+    return TypeDesc::basetype_merge(a, b);
+}
 
-// DEPRECATED(2.3): Prefer TypeDesc::basetype_merge().
+OIIO_DEPRECATED("Use TypeDesc::basetype_merge [2.3]")
 inline TypeDesc type_merge (TypeDesc a, TypeDesc b) {
     return TypeDesc::basetype_merge(a, b);
 }
 
-// DEPRECATED(2.3): Prefer TypeDesc::basetype_merge().
+OIIO_DEPRECATED("Use TypeDesc::basetype_merge [2.3]")
 inline TypeDesc type_merge (TypeDesc a, TypeDesc b, TypeDesc c)
 {
     return TypeDesc::basetype_merge(TypeDesc::basetype_merge(a,b), c);

src/include/OpenImageIO/imagebufalgo_util.h

@@ -530,6 +530,8 @@ class OIIO_UTIL_API ParamValueSpan : public cspan<ParamValue> {
     //   - operator[int]
     //   - begin(), end(), cbegin(), cend()
 
+    ParamValueSpan() = default;
+
     ParamValueSpan(cspan<ParamValue> p)
         : cspan<ParamValue>(p)
     {

src/include/OpenImageIO/paramlist.h

@@ -335,6 +335,9 @@ struct OIIO_UTIL_API TypeDesc {
     /// guess for one that can handle both without any loss of range or
     /// precision.
     static BASETYPE basetype_merge(TypeDesc a, TypeDesc b);
+    static BASETYPE basetype_merge(TypeDesc a, TypeDesc b, TypeDesc c) {
+        return basetype_merge(basetype_merge(a, b), c);
+    }
 
 #if OIIO_DISABLE_DEPRECATED < OIIO_MAKE_VERSION(1,8,0) && OIIO_VERSION_LESS(2,7,0) && !defined(OIIO_DOXYGEN)
     // DEPRECATED(1.8): These static const member functions were mildly

src/include/OpenImageIO/typedesc.h

@@ -2649,33 +2649,6 @@ ImageBufAlgo::ociodisplay(const ImageBuf& src, string_view display,
 
 
 
-// DEPRECATED(2.5)
-bool
-ImageBufAlgo::ociodisplay(ImageBuf& dst, const ImageBuf& src,
-                          string_view display, string_view view,
-                          string_view from, string_view looks, bool unpremult,
-                          string_view key, string_view value,
-                          const ColorConfig* colorconfig, ROI roi, int nthreads)
-{
-    return ociodisplay(dst, src, display, view, from, looks, unpremult, false,
-                       key, value, colorconfig, roi, nthreads);
-}
-
-
-
-// DEPRECATED(2.5)
-ImageBuf
-ImageBufAlgo::ociodisplay(const ImageBuf& src, string_view display,
-                          string_view view, string_view from, string_view looks,
-                          bool unpremult, string_view key, string_view value,
-                          const ColorConfig* colorconfig, ROI roi, int nthreads)
-{
-    return ociodisplay(src, display, view, from, looks, unpremult, false, key,
-                       value, colorconfig, roi, nthreads);
-}
-
-
-
 bool
 ImageBufAlgo::ociofiletransform(ImageBuf& dst, const ImageBuf& src,
                                 string_view name, bool unpremult, bool inverse,

src/libOpenImageIO/color_ocio.cpp

@@ -271,8 +271,10 @@ main(int argc, char* argv[])
     float green[3] = { 0, 1, 0 };
     float blue[3]  = { 0, 0, 1 };
     float black[3] = { 0, 0, 0 };
-    ImageBufAlgo::fill(imgA, red, green, red, green);
-    ImageBufAlgo::fill(imgB, blue, blue, black, black);
+    ImageBufAlgo::fill(imgA, cspan<float>(red), cspan<float>(green),
+                       cspan<float>(red), cspan<float>(green));
+    ImageBufAlgo::fill(imgB, cspan<float>(blue), cspan<float>(blue),
+                       cspan<float>(black), cspan<float>(black));
     // imgA.write ("A.exr");
     // imgB.write ("B.exr");
 

src/libOpenImageIO/compute_test.cpp

@@ -248,7 +248,7 @@ ImageBuf_test_appbuffer_strided()
     // Wrap the whole buffer, fill with green
     ImageBuf wrapped(ImageSpec(res, res, nchans, TypeFloat), mem);
     const float green[nchans] = { 0.0f, 1.0f, 0.0f };
-    ImageBufAlgo::fill(wrapped, green);
+    ImageBufAlgo::fill(wrapped, cspan<float>(green));
     float color[nchans] = { -1, -1, -1 };
     OIIO_CHECK_ASSERT(ImageBufAlgo::isConstantColor(wrapped, 0.0f, color)
                       && color[0] == 0.0f && color[1] == 1.0f
@@ -260,7 +260,7 @@ ImageBuf_test_appbuffer_strided()
                      2 * nchans * sizeof(float) /* every other pixel */,
                      2 * res * nchans * sizeof(float) /* ever other line */);
     const float red[nchans] = { 1.0f, 0.0f, 0.0f };
-    ImageBufAlgo::fill(strided, red);
+    ImageBufAlgo::fill(strided, cspan<float>(red));
 
     // The strided IB ought to look all-red
     OIIO_CHECK_ASSERT(ImageBufAlgo::isConstantColor(strided, 0.0f, color)
@@ -409,7 +409,7 @@ test_read_channel_subset()
     // FIrst, write a test image with 6 channels
     static float color6[] = { 0.6f, 0.5f, 0.4f, 0.3f, 0.2f, 0.1f };
     ImageBuf A(ImageSpec(2, 2, 6, TypeDesc::FLOAT));
-    ImageBufAlgo::fill(A, color6);
+    ImageBufAlgo::fill(A, cspan<float>(color6));
     A.write("sixchans.tif");
     std::cout << " Start with image:\n";
     print(A);

src/libOpenImageIO/imagebuf_test.cpp

@@ -761,15 +761,6 @@ ImageBufAlgo::perpixel_op(const ImageBuf& srcA, const ImageBuf& srcB,
 
 
 
-// DEPRECATED(2.3): Replaced by TypeDesc::type_merge(BASETYPE,BASETYPE)
-TypeDesc::BASETYPE
-ImageBufAlgo::type_merge(TypeDesc::BASETYPE a, TypeDesc::BASETYPE b)
-{
-    return TypeDesc::basetype_merge(a, b);
-}
-
-
-
 template<typename DSTTYPE, typename SRCTYPE>
 static bool
 convolve_(ImageBuf& dst, const ImageBuf& src, const ImageBuf& kernel,
@@ -1618,7 +1609,8 @@ ImageBufAlgo::fillholes_pushpull(ImageBuf& dst, const ImageBuf& src, ROI roi,
         ImageSpec smallspec(w, h, src.nchannels(), TypeDesc::FLOAT);
         smallspec.alpha_channel = topspec.alpha_channel;
         ImageBuf* small         = new ImageBuf(smallspec);
-        ImageBufAlgo::resize(*small, *pyramid.back(), "triangle");
+        ImageBufAlgo::resize(*small, *pyramid.back(),
+                             { { "filtername", "triangle" } });
         divide_by_alpha(*small, get_roi(smallspec), nthreads);
         pyramid.emplace_back(small);
         // small->write(Strutil::fmt::format("push{:04d}.exr", small->spec().width));
@@ -1632,7 +1624,7 @@ ImageBufAlgo::fillholes_pushpull(ImageBuf& dst, const ImageBuf& src, ROI roi,
     for (int i = (int)pyramid.size() - 2; i >= 0; --i) {
         ImageBuf &big(*pyramid[i]), &small(*pyramid[i + 1]);
         ImageBuf blowup(big.spec());
-        ImageBufAlgo::resize(blowup, small, "triangle");
+        ImageBufAlgo::resize(blowup, small, { { "filtername", "triangle" } });
         ImageBufAlgo::over(big, big, blowup);
         // big.write(Strutil::sprintf("pull{:04}.exr", big.spec().width));
     }