api: Versioned namespace to preserve ABI compatibility between minor releases

.github/workflows/build-steps.yml

@@ -203,7 +203,7 @@ jobs:
             time make sphinx
       - name: Upload testsuite debugging artifacts
         uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
-        if: ${{ failure() || inputs.build_docs == '1' || inputs.benchmark == '1' }}
+        if: ${{ failure() || inputs.build_docs == '1' || inputs.benchmark == '1' || inputs.abi_check != '' }}
         with:
           name: oiio-${{github.job}}-${{inputs.nametag}}
           path: |

.github/workflows/ci.yml

@@ -388,7 +388,7 @@ jobs:
             simd: "avx2,f16c"
             skip_tests: 1
             # abi_check: v3.1.3.0
-            abi_check: ae5dca7865c9956b43cc04dee00a65ad893e251e
+            abi_check: 9bfcce725a3806a3f70c7e838d9d98d6d95c917a
             setenvs: export OIIO_CMAKE_FLAGS="-DOIIO_BUILD_TOOLS=0 -DOIIO_BUILD_TESTS=0 -DUSE_PYTHON=0"
                             USE_OPENCV=0 USE_FFMPEG=0 USE_PYTHON=0 USE_FREETYPE=0
 

src/build-scripts/ci-abicheck.bash

@@ -41,14 +41,14 @@ for lib in $LIBS ; do
     fgrep "Binary compatibility:" ${lib}-abi-results.txt
     echo -e "\x1b[33;0m"
 done
+cp -r compat_reports ${BUILDDIR_NEW}/compat_reports || true
 
 #
 # If the "Binary compatibility" summary results say anything other than 100%,
 # we fail!
 #
 for lib in $LIBS ; do
     if [[ `fgrep "Binary compatibility:" ${lib}-abi-results.txt | grep -v 100\%` != "" ]] ; then
-        cp -r compat_reports ${BUILDDIR_NEW}/compat_reports
         exit 1
     fi
 done

src/doc/Doxyfile

@@ -2189,6 +2189,8 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OIIO_NAMESPACE_3_0_END="}" \
                          OIIO_NAMESPACE_3_1_BEGIN="namespace OIIO {" \
                          OIIO_NAMESPACE_3_1_END="}" \
+                         OIIO_NAMESPACE_3_2_BEGIN="namespace OIIO {" \
+                         OIIO_NAMESPACE_3_2_END="}" \
                          OIIO_NS_BEGIN="namespace OIIO {" \
                          OIIO_NS_END="}" \
                          OIIO_CONSTEXPR17=constexpr \

src/include/OpenImageIO/argparse.h

@@ -20,8 +20,12 @@
 #include <OpenImageIO/paramlist.h>
 #include <OpenImageIO/strutil.h>
 
+// Define symbols that let client applications determine if newly added
+// features are supported.
+#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
+#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /////////////////////////////////////////////////////////////////////////////
@@ -173,7 +177,7 @@ OIIO_NAMESPACE_BEGIN
 
 class OIIO_UTIL_API ArgParse {
 public:
-    class Arg;  // Forward declarion of Arg
+    class Arg;  // Forward declaration of Arg
 
     // ------------------------------------------------------------------
     /// @defgroup Setting up an ArgParse
@@ -782,11 +786,4 @@ class OIIO_UTIL_API ArgParse {
     void usage() const { print_help(); }
 };
 
-
-
-// Define symbols that let client applications determine if newly added
-// features are supported.
-#define OIIO_ARGPARSE_SUPPORTS_BRIEFUSAGE 1
-#define OIIO_ARGPARSE_SUPPORTS_HUMAN_PARAMNAME 1
-
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/atomic.h

@@ -19,11 +19,11 @@
 
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 using std::atomic;
-typedef atomic<int> atomic_int;
-typedef atomic<long long> atomic_ll;
+using atomic_int = atomic<int>;
+using atomic_ll  = atomic<long long>;
 
 
 
@@ -79,5 +79,17 @@ atomic_fetch_add(atomic<double>& a, double f)
     } while (true);
 }
 
+OIIO_NAMESPACE_3_1_END
+
 
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+using std::atomic;
+using atomic_int = atomic<int>;
+using atomic_ll  = atomic<long long>;
+using v3_1::atomic_fetch_add;
+using v3_1::atomic_max;
+using v3_1::atomic_min;
+#endif
 OIIO_NAMESPACE_END

src/include/OpenImageIO/attrdelegate.h

@@ -14,7 +14,7 @@
 #include <OpenImageIO/ustring.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 namespace pvt {
@@ -229,4 +229,13 @@ template<class C> class AttrDelegate {
 };
 
 
+OIIO_NAMESPACE_3_1_END
+
+
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+using v3_1::AttrDelegate;
+#endif
 OIIO_NAMESPACE_END

src/include/OpenImageIO/benchmark.h

@@ -24,7 +24,7 @@
 #endif
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// DoNotOptimize(val) is a helper function for timing benchmarks that fools
 /// the compiler into thinking the the location 'val' is used and will not
@@ -470,6 +470,24 @@ OIIO_FORCEINLINE void clobber_all_memory() { }
 
 #endif
 
+OIIO_UTIL_API std::ostream& operator<<(std::ostream& out,
+                                       const Benchmarker& bench);
+
+OIIO_NAMESPACE_3_1_END
 
 
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+using v3_1::Benchmarker;
+using v3_1::clobber;
+using v3_1::clobber_all_memory;
+using v3_1::DoNotOptimize;
+using v3_1::time_trial;
+using v3_1::timed_thread_wedge;
+using v3_1::operator<<;
+namespace pvt {
+using v3_1::pvt::use_char_ptr;
+}
+#endif
 OIIO_NAMESPACE_END

src/include/OpenImageIO/bit.h

@@ -10,7 +10,7 @@
 #include <OpenImageIO/platform.h>
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /// Standards-compliant bit cast of two equally sized types. This is used
@@ -273,4 +273,19 @@ rotl64(uint64_t x, int k)
 
 
 
+OIIO_NAMESPACE_3_1_END
+
+
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+using v3_1::bitcast;
+using v3_1::bitcast_to_float;
+using v3_1::bitcast_to_int;
+using v3_1::byteswap;
+using v3_1::rotl;
+using v3_1::rotl32;
+using v3_1::rotl64;
+#endif
 OIIO_NAMESPACE_END

src/include/OpenImageIO/color.h

@@ -12,6 +12,9 @@
 #include <OpenImageIO/typedesc.h>
 #include <OpenImageIO/ustring.h>
 
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
+#define OIIO_HAS_COLORPROCESSOR 1
 
 //
 // Some general color management information materials to have handy:
@@ -23,7 +26,12 @@
 //
 
 
-OIIO_NAMESPACE_BEGIN
+// Preprocessor symbol to allow conditional compilation depending on
+// whether the ColorConfig returns ColorProcessor shared pointers or raw.
+#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+
+
+OIIO_NAMESPACE_3_1_BEGIN
 
 /// The ColorProcessor encapsulates a baked color transformation, suitable for
 /// application to raw pixels, or ImageBuf(s). These are generated using
@@ -50,17 +58,9 @@ class OIIO_API ColorProcessor {
     }
 };
 
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorProcessor class is exposed (it was not prior to OIIO 1.9).
-#define OIIO_HAS_COLORPROCESSOR 1
-
-
 
-typedef std::shared_ptr<ColorProcessor> ColorProcessorHandle;
 
-// Preprocessor symbol to allow conditional compilation depending on
-// whether the ColorConfig returns ColorProcessor shared pointers or raw.
-#define OIIO_COLORCONFIG_USES_SHARED_PTR 1
+using ColorProcessorHandle = std::shared_ptr<ColorProcessor>;
 
 
 
@@ -445,7 +445,18 @@ class OIIO_API ColorConfig {
     Impl* getImpl() const { return m_impl.get(); }
 };
 
+OIIO_NAMESPACE_3_1_END
+
 
+// Compatibility
+#ifndef OIIO_DOXYGEN
+OIIO_NAMESPACE_BEGIN
+using v3_1::ColorProcessorHandle;
+OIIO_NAMESPACE_END
+#endif
+
+
+OIIO_NAMESPACE_BEGIN
 
 /// Utility -- convert sRGB value to linear transfer function, without
 /// any change in color primaries.

src/include/OpenImageIO/deepdata.h

@@ -10,12 +10,7 @@
 #include <OpenImageIO/span.h>
 #include <OpenImageIO/string_view.h>
 
-OIIO_NAMESPACE_BEGIN
-
-
-struct TypeDesc;
-class ImageSpec;
-
+OIIO_NAMESPACE_3_1_BEGIN
 
 
 /// A `DeepData` holds the contents of an image of ``deep'' pixels (multiple
@@ -209,4 +204,4 @@ class OIIO_API DeepData {
 };
 
 
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END

src/include/OpenImageIO/detail/farmhash.h

@@ -216,7 +216,7 @@ STATIC_INLINE void simpleSwap(T &a, T &b) {
 #define Hash128to64   OIIO::farmhash::Hash128to64
 
 // namespace NAMESPACE_FOR_HASH_FUNCTIONS {
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 
 namespace farmhash {
 namespace inlined {
@@ -379,7 +379,8 @@ STATIC_INLINE uint64_t Rotate64(uint64_t val, int shift) {
 
 // }  // namespace NAMESPACE_FOR_HASH_FUNCTIONS
 } /*end namespace inlined */
-} /*end namespace farmhash*/ OIIO_NAMESPACE_END 
+} /*end namespace farmhash*/
+OIIO_NAMESPACE_3_1_END
 
 // FARMHASH PORTABILITY LAYER: debug mode or max speed?
 // One may use -DFARMHASH_DEBUG=1 or -DFARMHASH_DEBUG=0 to force the issue.
@@ -506,7 +507,7 @@ STATIC_INLINE uint64_t Rotate64(uint64_t val, int shift) {
 
 
 // namespace NAMESPACE_FOR_HASH_FUNCTIONS {
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 //using namespace OIIO::farmhash;
     namespace farmhash {
     namespace inlined {
@@ -2184,8 +2185,16 @@ STATIC_INLINE uint128_t Fingerprint128(const char* s, size_t len) {
 #undef Murk
 #undef Chunk
 
-OIIO_NAMESPACE_END
-
 #undef STATIC_INLINE
 
+OIIO_NAMESPACE_3_1_END
+
 
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+namespace farmhash {
+using namespace OIIO::v3_1::farmhash;
+}  // namespace farmhash
+#endif
+OIIO_NAMESPACE_END

src/include/OpenImageIO/detail/fmt.h

@@ -21,12 +21,12 @@
 
 #if OIIO_VERSION_LESS(3, 1, 2)
 /* DEPRECATED -- remove at next ABI compatibility boundary */
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 namespace pvt {
 OIIO_UTIL_API void
 log_fmt_error(const char* message);
 };
-OIIO_NAMESPACE_END
+OIIO_NAMESPACE_3_1_END
 #endif
 
 // Use the grisu fast floating point formatting for old fmt versions
@@ -78,7 +78,7 @@ OIIO_PRAGMA_WARNING_POP
 #endif
 
 
-OIIO_NAMESPACE_BEGIN
+OIIO_NAMESPACE_3_1_BEGIN
 namespace pvt {
 
 
@@ -197,4 +197,15 @@ struct array_formatter : format_parser_with_separator {
 
 
 }  // namespace pvt
+OIIO_NAMESPACE_3_1_END
+
+
+// Compatibility
+OIIO_NAMESPACE_BEGIN
+#ifndef OIIO_DOXYGEN
+namespace pvt {
+using v3_1::pvt::array_formatter;
+using v3_1::pvt::index_formatter;
+}  // namespace pvt
+#endif
 OIIO_NAMESPACE_END