From 4999c7b15eee2fac9dd851ee3fccc49aaac43386 Mon Sep 17 00:00:00 2001 From: Larry Gritz Date: Sat, 13 Jul 2024 06:11:28 -0700 Subject: [PATCH] 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 --- docs/Deprecations-3.0.md | 70 ++++++++++++++ src/doc/Doxyfile | 1 - src/include/OpenImageIO/array_view.h | 20 ---- src/include/OpenImageIO/benchmark.h | 11 +-- src/include/OpenImageIO/bit.h | 18 +--- src/include/OpenImageIO/color.h | 21 ++++- src/include/OpenImageIO/errorhandler.h | 124 ------------------------- src/libOpenImageIO/color_ocio.cpp | 40 +------- src/libOpenImageIO/maketexture.cpp | 4 +- src/libutil/benchmark.cpp | 2 +- src/libutil/span_test.cpp | 5 - src/libutil/spin_rw_test.cpp | 2 +- src/maketx/maketx.cpp | 2 +- src/testtex/testtex.cpp | 2 +- 14 files changed, 101 insertions(+), 221 deletions(-) create mode 100644 docs/Deprecations-3.0.md delete mode 100644 src/include/OpenImageIO/array_view.h diff --git a/docs/Deprecations-3.0.md b/docs/Deprecations-3.0.md new file mode 100644 index 0000000000..c92983bf17 --- /dev/null +++ b/docs/Deprecations-3.0.md @@ -0,0 +1,70 @@ + + + +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. + + diff --git a/src/doc/Doxyfile b/src/doc/Doxyfile index 69a3c49cfa..caee03d212 100644 --- a/src/doc/Doxyfile +++ b/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 \ diff --git a/src/include/OpenImageIO/array_view.h b/src/include/OpenImageIO/array_view.h deleted file mode 100644 index 2ee47081f8..0000000000 --- a/src/include/OpenImageIO/array_view.h +++ /dev/null @@ -1,20 +0,0 @@ -// Copyright Contributors to the OpenImageIO project. -// SPDX-License-Identifier: Apache-2.0 -// https://github.com/AcademySoftwareFoundation/OpenImageIO - - -#pragma once - -#include - -OIIO_NAMESPACE_BEGIN - -// Backwards-compatibility: define array_view<> (our old name) as a -// synonym for span<> (which is the nomenclature favored by C++20). - -template using array_view = span; - -template using array_view_strided = span_strided; - - -OIIO_NAMESPACE_END diff --git a/src/include/OpenImageIO/benchmark.h b/src/include/OpenImageIO/benchmark.h index e5bac2c985..6f13a22dcc 100644 --- a/src/include/OpenImageIO/benchmark.h +++ b/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 +#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 -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. diff --git a/src/include/OpenImageIO/bit.h b/src/include/OpenImageIO/bit.h index 6b0cc7b9b0..1b8265b591 100644 --- a/src/include/OpenImageIO/bit.h +++ b/src/include/OpenImageIO/bit.h @@ -73,22 +73,6 @@ bitcast(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 -OIIO_DEPRECATED("Use OIIO::bitcast instead") -OIIO_NODISCARD OIIO_FORCEINLINE OIIO_HOSTDEVICE OUT_TYPE - bit_cast(const IN_TYPE& in) -{ - return bitcast(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) { diff --git a/src/include/OpenImageIO/color.h b/src/include/OpenImageIO/color.h index 2fbf94e319..a88a5bdb68 100644 --- a/src/include/OpenImageIO/color.h +++ b/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 diff --git a/src/include/OpenImageIO/errorhandler.h b/src/include/OpenImageIO/errorhandler.h index e9f23de661..007386903f 100644 --- a/src/include/OpenImageIO/errorhandler.h +++ b/src/include/OpenImageIO/errorhandler.h @@ -10,19 +10,6 @@ #include -// 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 - 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 - 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 - 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 - 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 - 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 - 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 - OIIO_ERRORHANDLER_PRINTF_DEPRECATED void infof(const char* format, - const Args&... args) - { - if (verbosity() >= VERBOSE) - info(Strutil::sprintf(format, args...)); - } - - template - OIIO_ERRORHANDLER_PRINTF_DEPRECATED void warningf(const char* format, - const Args&... args) - { - if (verbosity() >= NORMAL) - warning(Strutil::sprintf(format, args...)); - } - - template - OIIO_ERRORHANDLER_PRINTF_DEPRECATED void errorf(const char* format, - const Args&... args) - { - error(Strutil::sprintf(format, args...)); - } - - template - OIIO_ERRORHANDLER_PRINTF_DEPRECATED void severef(const char* format, - const Args&... args) - { - severe(Strutil::sprintf(format, args...)); - } - - template - OIIO_ERRORHANDLER_PRINTF_DEPRECATED void messagef(const char* format, - const Args&... args) - { - if (verbosity() > QUIET) - message(Strutil::sprintf(format, args...)); - } - - template - 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 diff --git a/src/libOpenImageIO/color_ocio.cpp b/src/libOpenImageIO/color_ocio.cpp index 4373ceb43d..ef0c109112 100644 --- a/src/libOpenImageIO/color_ocio.cpp +++ b/src/libOpenImageIO/color_ocio.cpp @@ -935,14 +935,6 @@ ColorConfig::has_error() const -bool -ColorConfig::error() const -{ - return has_error(); -} - - - std::string ColorConfig::geterror(bool clear) const { @@ -2072,30 +2064,6 @@ ColorConfig::createDisplayTransform(ustring display, ustring view, -ColorProcessorHandle -ColorConfig::createDisplayTransform(string_view display, string_view view, - string_view inputColorSpace, - string_view looks, string_view context_key, - string_view context_value) const -{ - return createDisplayTransform(ustring(display), ustring(view), - ustring(inputColorSpace), ustring(looks), - false, ustring(context_key), - ustring(context_value)); -} - -ColorProcessorHandle -ColorConfig::createDisplayTransform(ustring display, ustring view, - ustring inputColorSpace, ustring looks, - ustring context_key, - ustring context_value) const -{ - return createDisplayTransform(display, view, inputColorSpace, looks, false, - context_key, context_value); -} - - - ColorProcessorHandle ColorConfig::createFileTransform(string_view name, bool inverse) const { @@ -2260,7 +2228,7 @@ ImageBufAlgo::colorconvert(ImageBuf& dst, const ImageBuf& src, string_view from, colorconfig->resolve(to), context_key, context_value); if (!processor) { - if (colorconfig->error()) + if (colorconfig->has_error()) dst.errorfmt("{}", colorconfig->geterror()); else #ifdef USE_OCIO @@ -2578,7 +2546,7 @@ ImageBufAlgo::ociolook(ImageBuf& dst, const ImageBuf& src, string_view looks, colorconfig->resolve(to), inverse, key, value); if (!processor) { - if (colorconfig->error()) + if (colorconfig->has_error()) dst.errorfmt("{}", colorconfig->geterror()); else #ifdef USE_OCIO @@ -2643,7 +2611,7 @@ ImageBufAlgo::ociodisplay(ImageBuf& dst, const ImageBuf& src, colorconfig->resolve(from), looks, inverse, key, value); if (!processor) { - if (colorconfig->error()) + if (colorconfig->has_error()) dst.errorfmt("{}", colorconfig->geterror()); else #ifdef USE_OCIO @@ -2725,7 +2693,7 @@ ImageBufAlgo::ociofiletransform(ImageBuf& dst, const ImageBuf& src, colorconfig = &ColorConfig::default_colorconfig(); processor = colorconfig->createFileTransform(name, inverse); if (!processor) { - if (colorconfig->error()) + if (colorconfig->has_error()) dst.errorfmt("{}", colorconfig->geterror()); else #ifdef USE_OCIO diff --git a/src/libOpenImageIO/maketexture.cpp b/src/libOpenImageIO/maketexture.cpp index 19de5726c9..b5c26c8d00 100644 --- a/src/libOpenImageIO/maketexture.cpp +++ b/src/libOpenImageIO/maketexture.cpp @@ -1622,14 +1622,14 @@ make_texture_impl(ImageBufAlgo::MakeTextureMode mode, const ImageBuf* input, } ColorConfig colorconfig(colorconfigname); - if (colorconfig.error()) { + if (colorconfig.has_error()) { errorfmt("Error Creating ColorConfig: {}", colorconfig.geterror()); return false; } ColorProcessorHandle processor = colorconfig.createColorProcessor(incolorspace, outcolorspace); - if (!processor || colorconfig.error()) { + if (!processor || colorconfig.has_error()) { errorfmt("Error Creating Color Processor: {}", colorconfig.geterror()); return false; diff --git a/src/libutil/benchmark.cpp b/src/libutil/benchmark.cpp index a595058643..666e9b05e4 100644 --- a/src/libutil/benchmark.cpp +++ b/src/libutil/benchmark.cpp @@ -204,7 +204,7 @@ timed_thread_wedge(function_view task, function_view pretask, threads.join_all(); posttask(); }, - ntrials, &range); + ntrials, 1, &range); if (out) { double one_thread_time = times[0] * threadcounts[0]; double ideal = one_thread_time / nthreads; diff --git a/src/libutil/span_test.cpp b/src/libutil/span_test.cpp index d29f5a540c..81a2a59e92 100644 --- a/src/libutil/span_test.cpp +++ b/src/libutil/span_test.cpp @@ -6,7 +6,6 @@ #include #include -#include #include #include #include @@ -494,9 +493,5 @@ main(int /*argc*/, char* /*argv*/[]) test_spanset(); test_spanzero(); - // array_view and span should be synonyms - OIIO_CHECK_ASSERT(( - std::is_same, OIIO::array_view>::value)); - return unit_test_failures; } diff --git a/src/libutil/spin_rw_test.cpp b/src/libutil/spin_rw_test.cpp index 5a3abd65d4..8fbef4a949 100644 --- a/src/libutil/spin_rw_test.cpp +++ b/src/libutil/spin_rw_test.cpp @@ -121,7 +121,7 @@ main(int argc, char* argv[]) int its = iterations / nt; double range; - double t = time_trial(std::bind(test_spin_rw, nt, its), ntrials, + double t = time_trial(std::bind(test_spin_rw, nt, its), ntrials, 1, &range); Strutil::printf("%2d\t%s\t%5.1fs, range %.1f\t(%d iters/thread)\n", nt, diff --git a/src/maketx/maketx.cpp b/src/maketx/maketx.cpp index 82c15bd452..d85b49fc8c 100644 --- a/src/maketx/maketx.cpp +++ b/src/maketx/maketx.cpp @@ -91,7 +91,7 @@ colorconvert_help_string() s += " (choices: "; ColorConfig colorconfig; - if (colorconfig.error() || colorconfig.getNumColorSpaces() == 0) { + if (colorconfig.has_error() || colorconfig.getNumColorSpaces() == 0) { s += "NONE"; } else { for (int i = 0; i < colorconfig.getNumColorSpaces(); ++i) { diff --git a/src/testtex/testtex.cpp b/src/testtex/testtex.cpp index 31ebca9570..03a43f9858 100644 --- a/src/testtex/testtex.cpp +++ b/src/testtex/testtex.cpp @@ -1919,7 +1919,7 @@ main(int argc, const char* argv[]) int tries = nt <= 2 ? std::min(lowtrials, ntrials) : ntrials; double range; float t = (float)time_trial(std::bind(launch_tex_threads, nt, its), - tries, &range); + tries, 1, &range); if (single_thread_time == 0.0f) single_thread_time = t * nt; float speedup = single_thread_time / t;