api: various deprecations in array_view.h, benchmark.h, bit.h, color.…

…h, errorhandler.h (#4335)

* array_view.h: Remove this long-deprecated header.
* benchmark.h: Attach DEPRECATED warning to external use of
benchmark.h's time_trial().
* bit.h: Remove bit_cast that's had deprecation warnings for several
releases, and add deprecation warnings to the old rotl32 and rotl64
* color.h: add deprecation warnings and make the deprecated things
inline so they can be removed later without an ABI break.
* errorhandler.h: remove deprecated old printf style methods

---------

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

docs/Deprecations-3.0.md

@@ -0,0 +1,70 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- Copyright Contributors to the OpenImageIO Project. -->
+
+OpenImageIO 3.0 Deprecations
+============================
+
+For minor or patch releases, we try very hard to never fully remove
+functionality that will force downstream applications using OpenImageIO to
+change their source code. However, for major releases (e.g., 2.x -> 3.0),
+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.
+
+### Glossary
+
+- "Marked as deprecated" means that we consider an API facet to be obsolete,
+  and document it as such in the comments or documentation (or remove it from
+  the documentation).
+
+- "Deprecation warning" means that a deprecated function is tagged with
+  attributes that should cause a compiler warning if the function is used. The
+  warning can be disabled by the downstream project, but it is recommended
+  that you fix the code to use the new API before it is permanently removed.
+
+- "Removed" means that the deprecated API facet has been removed from the
+  library completely.
+
+
+---
+
+
+## array_view.h
+
+* This header has been eliminated. It originally had the template `array_view`,
+  which many years ago was renamed `span<>` and lives in span.h, and since then
+  the array_view.h header has merely made an alias.
+
+## bit.h
+
+* The `bit_cast` template, which was deprecated and warned since 2.5, has been
+  removed. It was confusing because C++23 has a `std::bit_cast` that used the
+  reverse order of arguments. Users should instead use `std::bit_cast` (if
+  C++23) or the equivalent `OIIO::bitcast`.
+* The `rotl32` and `rotl64` functions which have been marked as deprecated
+  since 2.1 now have deprecation warnings. Use `rotl` instead.
+
+## benchmark.h
+
+* The full `time_trial()` function now has deprecation warnings. Users should
+  generally use the `Benchmrker` class instead.
+* The abbreviated `time_trial()` function (that lacks a `repeats` parameter
+  has been removed.
+
+## color.h
+
+* `ColorConfig::error()` now has a deprecation warning. Use
+  `ColorConfig::has_error()` instead.
+* The versions of `createDisplayTransform()` that lack an `inverse` parameter
+  now have deprecation warnings. Use the version that takes an `inverse` bool.
+
+## errorhandler.h
+
+* All of the old methods that did printf-style formatting have been deprecated
+  (info/infof, warning/warningf, error/errorf, severe/severef,
+  message/messagef, debug/debugf). Instead, use infofmt, warningfmt, errorfmt,
+  severefmt, messagefmt, debugfmt, respectively, which all use the std::format
+  notation.
+
+

src/doc/Doxyfile

@@ -2194,7 +2194,6 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OIIO_NODISCARD:= \
                          OIIO_DEPRECATED:=[[deprecated]] \
                          OIIO_FORMAT_DEPRECATED:= \
-                         OIIO_ERRORHANDLER_PRINTF_DEPRECATED:= \
                          OIIO_FORCEINLINE=inline \
                          IMATH_HALF_H_=1 \
                          INCLUDED_IMATHVEC_H=1 \

src/include/OpenImageIO/benchmark.h

@@ -318,6 +318,9 @@ class OIIO_UTIL_API Benchmarker {
 /// DEPRECATED(1.8): This may be considered obsolete, probably the
 /// Benchmarker class is a better solution.
 template<typename FUNC>
+#ifndef OIIO_INTERNAL
+OIIO_DEPRECATED("use Benchmarker instead")
+#endif
 double
 time_trial(FUNC func, int ntrials = 1, int nrepeats = 1, double* range = NULL)
 {
@@ -340,14 +343,6 @@ time_trial(FUNC func, int ntrials = 1, int nrepeats = 1, double* range = NULL)
     return mintime;
 }
 
-/// Version without repeats.
-template<typename FUNC>
-double
-time_trial(FUNC func, int ntrials, double* range)
-{
-    return time_trial(func, ntrials, 1, range);
-}
-
 
 
 // Benchmarking helper function: Time a function with various thread counts.

src/include/OpenImageIO/bit.h

@@ -73,22 +73,6 @@ bitcast<float, int32_t>(const int32_t& val) noexcept
 #endif
 
 
-#if OIIO_VERSION_LESS(3, 0, 0)
-/// Note: The C++20 std::bit_cast has the reverse order of the template
-/// arguments of our original bit_cast! That is unfortunate. For now, we
-/// prefer using OIIO::bitcast. We'll keep this old one for backward
-/// compatibility, but will eventually deprecate for OIIO 2.5 and remove it
-/// for 3.0.
-template<typename IN_TYPE, typename OUT_TYPE>
-OIIO_DEPRECATED("Use OIIO::bitcast<To, From> instead")
-OIIO_NODISCARD OIIO_FORCEINLINE OIIO_HOSTDEVICE OUT_TYPE
-    bit_cast(const IN_TYPE& in)
-{
-    return bitcast<OUT_TYPE, IN_TYPE>(in);
-}
-#endif
-
-
 OIIO_NODISCARD OIIO_FORCEINLINE OIIO_HOSTDEVICE int
 bitcast_to_int(float x)
 {
@@ -269,6 +253,7 @@ rotl(uint32_t x, int s) noexcept
 
 
 // Old names -- DEPRECATED(2.1)
+OIIO_DEPRECATED("use rotl() instead (2.1)")
 OIIO_FORCEINLINE OIIO_HOSTDEVICE uint32_t
 rotl32(uint32_t x, int k)
 {
@@ -279,6 +264,7 @@ rotl32(uint32_t x, int k)
 #endif
 }
 
+OIIO_DEPRECATED("use rotl() instead (2.1)")
 OIIO_FORCEINLINE OIIO_HOSTDEVICE uint64_t
 rotl64(uint64_t x, int k)
 {

src/include/OpenImageIO/color.h

@@ -90,7 +90,8 @@ class OIIO_API ColorConfig {
     bool has_error() const;
 
     /// DEPRECATED(2.4), old name for has_error().
-    bool error() const;
+    OIIO_DEPRECATED("Use has_error()")
+    bool error() const { return has_error(); }
 
     /// This routine will return the error string (and by default, clear any
     /// error flags).  If no error has occurred since the last time
@@ -268,16 +269,26 @@ class OIIO_API ColorConfig {
                            ustring context_key   = ustring(),
                            ustring context_value = ustring()) const;
 
-    // OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
+    OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
     ColorProcessorHandle
     createDisplayTransform(string_view display, string_view view,
                            string_view inputColorSpace, string_view looks,
                            string_view context_key,
-                           string_view context_value = "") const;
-    // OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
+                           string_view context_value = "") const
+    {
+        return createDisplayTransform(ustring(display), ustring(view),
+                                      ustring(inputColorSpace), ustring(looks),
+                                      false, ustring(context_key),
+                                      ustring(context_value));
+    }
+    OIIO_DEPRECATED("prefer the kind that takes an `inverse` parameter (2.5)")
     ColorProcessorHandle createDisplayTransform(
         ustring display, ustring view, ustring inputColorSpace, ustring looks,
-        ustring context_key, ustring context_value = ustring()) const;
+        ustring context_key, ustring context_value = ustring()) const
+    {
+        return createDisplayTransform(display, view, inputColorSpace, looks,
+                                      false, context_key, context_value);
+    }
 
     /// Construct a processor to perform color transforms determined by an
     /// OpenColorIO FileTransform. It is possible that this will return an

src/include/OpenImageIO/errorhandler.h

@@ -10,19 +10,6 @@
 #include <OpenImageIO/strutil.h>
 
 
-// If OIIO_ERRORHANDLER_HIDE_PRINTF is defined, mark the old-style printf-like
-// format functions as deprecated. (This is a debugging aid for downstream
-// projects who want to root out any places where they might be using the old
-// one).
-#if defined(OIIO_ERRORHANDLER_HIDE_PRINTF) || defined(OIIO_INTERNAL)
-#    define OIIO_ERRORHANDLER_PRINTF_DEPRECATED \
-        OIIO_DEPRECATED(                        \
-            "old style (printf-like) formatting version of this function is deprecated")
-#else
-#    define OIIO_ERRORHANDLER_PRINTF_DEPRECATED
-#endif
-
-
 OIIO_NAMESPACE_BEGIN
 
 /// ErrorHandler is a simple class that accepts error messages
@@ -94,117 +81,6 @@ class OIIO_UTIL_API ErrorHandler {
     void debug(const std::string&) {}
 #endif
 
-    // Formatted output with the same notation as Strutil::format.
-    /// Use with caution! Some day this will change to be fmt-like rather
-    /// than printf-like.
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void info(const char* format, const Args&... args)
-    {
-        if (verbosity() >= VERBOSE)
-            info(Strutil::format(format, args...));
-    }
-
-    /// Warning message with printf-like formatted error message.
-    /// Will not print unless verbosity >= NORMAL (i.e. will suppress
-    /// for QUIET).
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void warning(const char* format, const Args&... args)
-    {
-        if (verbosity() >= NORMAL)
-            warning(Strutil::format(format, args...));
-    }
-
-    /// Error message with printf-like formatted error message.
-    /// Will print regardless of verbosity.
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void error(const char* format, const Args&... args)
-    {
-        error(Strutil::format(format, args...));
-    }
-
-    /// Severe error message with printf-like formatted error message.
-    /// Will print regardless of verbosity.
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void severe(const char* format, const Args&... args)
-    {
-        severe(Strutil::format(format, args...));
-    }
-
-    /// Prefix-less message with printf-like formatted error message.
-    /// Will not print if verbosity is QUIET.  Also note that unlike
-    /// the other routines, message() will NOT append a newline.
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void message(const char* format, const Args&... args)
-    {
-        if (verbosity() > QUIET)
-            message(Strutil::format(format, args...));
-    }
-
-    /// Debugging message with printf-like formatted error message.
-    /// This will not produce any output if not in DEBUG mode, or
-    /// if verbosity is QUIET.
-    template<typename... Args>
-    OIIO_FORMAT_DEPRECATED void debug(const char* format OIIO_MAYBE_UNUSED,
-                                      const Args&... args OIIO_MAYBE_UNUSED)
-    {
-#ifndef NDEBUG
-        debug(Strutil::format(format, args...));
-#endif
-    }
-
-    //
-    // Formatted output with printf notation. Use these if you specifically
-    // want printf-notation, even after format() changes to python notation
-    // in some future OIIO release.
-    //
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void infof(const char* format,
-                                                   const Args&... args)
-    {
-        if (verbosity() >= VERBOSE)
-            info(Strutil::sprintf(format, args...));
-    }
-
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void warningf(const char* format,
-                                                      const Args&... args)
-    {
-        if (verbosity() >= NORMAL)
-            warning(Strutil::sprintf(format, args...));
-    }
-
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void errorf(const char* format,
-                                                    const Args&... args)
-    {
-        error(Strutil::sprintf(format, args...));
-    }
-
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void severef(const char* format,
-                                                     const Args&... args)
-    {
-        severe(Strutil::sprintf(format, args...));
-    }
-
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void messagef(const char* format,
-                                                      const Args&... args)
-    {
-        if (verbosity() > QUIET)
-            message(Strutil::sprintf(format, args...));
-    }
-
-    template<typename... Args>
-    OIIO_ERRORHANDLER_PRINTF_DEPRECATED void
-    debugf(const char* format OIIO_MAYBE_UNUSED,
-           const Args&... args OIIO_MAYBE_UNUSED)
-    {
-#ifndef NDEBUG
-        debug(Strutil::sprintf(format, args...));
-#endif
-    }
-
     //
     // Formatted output with std::format notation. Use these if you
     // specifically want std::format-notation, even before format() changes