api: Switch to a 2-level namespace (#1922)

Related OIIO PR: AcademySoftwareFoundation/OpenImageIO#4567 Like in the corresponding OIIO PR, I'm proposing switching to a 2-level namespace scheme (basically, `OSL::v1_14` instead of the current `OSL_v1_14) because that opens the door to possible future schemes to preserve better ABI compatibility between minor releases. I would like to squeeze this in before I finalize a 1.14 beta, so that it doesn't change again during the beta period. Also, I changed some macro names. Signed-off-by: Larry Gritz <[email protected]>
AcademySoftwareFoundation · Jan 16, 2025 · 42ccf22 · 42ccf22
1 parent 5446c1d
commit 42ccf22
Show file tree

Hide file tree

Showing 184 changed files with 449 additions and 426 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -4,7 +4,7 @@
 
 cmake_minimum_required (VERSION 3.19)
 
-set (OSL_VERSION "1.14.3.0")
+set (OSL_VERSION "1.14.4.0")
 set (OSL_VERSION_OVERRIDE "" CACHE STRING
      "Version override (use with caution)!")
 mark_as_advanced (OSL_VERSION_OVERRIDE)
@@ -163,22 +163,32 @@ add_compile_definitions (OSL_INTERNAL=1)
 # OIIO_DISABLE_DEPRECATED before including any OIIO headers.
 add_compile_definitions (OIIO_DISABLE_DEPRECATED=900000)
 
-# Set the default namespace. For symbol hiding reasons, it's important that
-# the project name is a subset of the namespace name.
-set (${PROJ_NAME}_NAMESPACE ${PROJECT_NAME} CACHE STRING
-     "Customized outer namespace base name (version will be added)")
-option (${PROJ_NAME}_NAMESPACE_INCLUDE_PATCH
-        "Should the inner namespace include the patch number" ${${PROJECT_NAME}_DEV_RELEASE})
-set (PROJ_NAMESPACE "${${PROJ_NAME}_NAMESPACE}")
-string(REGEX MATCH ${PROJECT_NAME} NAMESPACE_HAS_PROJECT_NAME ${PROJ_NAMESPACE})
-if (NOT NAMESPACE_HAS_PROJECT_NAME)
-    set (PROJ_NAMESPACE ${PROJECT_NAME}_${PROJ_NAMESPACE})
+# Namespace settings
+#
+# The "outer namespace" defaults to the project name, but it can be overridden
+# to allow custom builds that put everything inside a unique namespace that
+# can't conflict with default builds.
+set (${PROJ_NAME}_OUTER_NAMESPACE ${PROJECT_NAME} CACHE STRING
+     "Customized outer namespace")
+set (PROJ_NAMESPACE "${${PROJ_NAME}_OUTER_NAMESPACE}")  # synonym
+if (NOT ${PROJ_NAME}_OUTER_NAMESPACE STREQUAL ${PROJECT_NAME})
+    set (${PROJ_NAME}_CUSTOM_OUTER_NAMESPACE 1)
 endif ()
-set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE}_v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}")
-if (${PROJ_NAME}_NAMESPACE_INCLUDE_PATCH)
-    set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE_V}_${PROJECT_VERSION_PATCH}")
+# There is also an inner namespace that is either vMAJ_MIN or vMAJ_MIN_PATCH,
+# depending on the setting of ${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH.
+option (${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH
+        "Should the inner namespace include the patch number" ${${PROJECT_NAME}_DEV_RELEASE})
+if (${PROJ_NAME}_INNER_NAMESPACE_INCLUDE_PATCH)
+    set (PROJ_VERSION_NAMESPACE "v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}_${PROJECT_VERSION_PATCH}")
+else ()
+    set (PROJ_VERSION_NAMESPACE "v${PROJECT_VERSION_MAJOR}_${PROJECT_VERSION_MINOR}")
 endif ()
-message(STATUS "Setting Namespace to: ${PROJ_NAMESPACE_V}")
+# PROJ_NAMESPACE_V combines the outer and inner namespaces into one symbol
+set (PROJ_NAMESPACE_V "${PROJ_NAMESPACE}_${PROJ_VERSION_NAMESPACE}")
+message(STATUS "Outer namespace PROJ_OUTER_NAMESPACE:   ${PROJ_NAMESPACE}")
+message(STATUS "Inner namespace PROJ_VERSION_NAMESPACE: ${PROJ_VERSION_NAMESPACE}")
+message(STATUS "Joint namespace PROJ_NAMESPACE_V:       ${PROJ_NAMESPACE_V}")
+
 
 # Define OSL_INTERNAL symbol only when building OSL itself, will not be
 # defined for downstream projects using OSL.

diff --git a/src/doc/Doxyfile b/src/doc/Doxyfile
@@ -697,7 +697,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -2162,6 +2162,8 @@ PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
                          OSL_HOSTDEVICE= \
                          OSL_NAMESPACE_BEGIN="namespace OSL {" \
                          OSL_NAMESPACE_END="}" \
+                         OSL_NS_BEGIN="namespace OSL {" \
+                         OSL_NS_END="}" \
                          OSL_CONSTEXPR14=constexpr \
                          OSL_CONSTEXPR17=constexpr \
                          OSL_CONSTEXPR20=constexpr \

diff --git a/src/include/OSL/Imathx/Imathx.h b/src/include/OSL/Imathx/Imathx.h
@@ -18,7 +18,7 @@
 
 // clang-format off
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 // Choose to treat helper functions as static
@@ -494,4 +494,4 @@ det4x4(const Imath::Matrix44<F>& m)
 }
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/accum.h b/src/include/OSL/accum.h
@@ -9,7 +9,7 @@
 #include <list>
 #include <stack>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 class Aov {
 public:
@@ -230,4 +230,4 @@ class OSLEXECPUBLIC Accumulator {
 };
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/batched_rendererservices.h b/src/include/OSL/batched_rendererservices.h
@@ -11,7 +11,7 @@
 
 #include <OpenImageIO/ustring.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 // Implementation detail:  virtual methods that have a corresponding
 // virtual bool is_overridden_* method
@@ -456,4 +456,4 @@ template<int WidthT> class OSLEXECPUBLIC BatchedRendererServices {
 };
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/batched_shaderglobals.h b/src/include/OSL/batched_shaderglobals.h
@@ -12,7 +12,7 @@
 
 #include <OSL/shaderglobals.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 namespace pvt {
 class BatchedBackendLLVM;
@@ -197,8 +197,7 @@ template<int WidthT> struct alignas(64) BatchedShaderGlobals {
 };
 
 #define __OSL_USING_SHADERGLOBALS(WIDTH_OF_OSL_DATA) \
-    using BatchedShaderGlobals                       \
-        = OSL_NAMESPACE::BatchedShaderGlobals<WIDTH_OF_OSL_DATA>;
+    using BatchedShaderGlobals = OSL::BatchedShaderGlobals<WIDTH_OF_OSL_DATA>;
 
 #undef OSL_USING_DATA_WIDTH
 #ifdef __OSL_USING_BATCHED_TEXTURE
@@ -212,4 +211,4 @@ template<int WidthT> struct alignas(64) BatchedShaderGlobals {
         __OSL_USING_SHADERGLOBALS(WIDTH_OF_OSL_DATA)
 #endif
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/batched_texture.h b/src/include/OSL/batched_texture.h
@@ -6,7 +6,7 @@
 
 #include <OSL/wide.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 namespace Tex {
 
@@ -279,11 +279,10 @@ template<int WidthT> class BatchedTextureOutputs {
     Mask<WidthT> m_mask;
 };
 
-#define __OSL_USING_BATCHED_TEXTURE(WIDTH_OF_OSL_DATA)             \
-    using BatchedTextureOutputs                                    \
-        = OSL_NAMESPACE::BatchedTextureOutputs<WIDTH_OF_OSL_DATA>; \
-    using BatchedTextureOptions                                    \
-        = OSL_NAMESPACE::BatchedTextureOptions<WIDTH_OF_OSL_DATA>;
+#define __OSL_USING_BATCHED_TEXTURE(WIDTH_OF_OSL_DATA)   \
+    using BatchedTextureOutputs                          \
+        = OSL::BatchedTextureOutputs<WIDTH_OF_OSL_DATA>; \
+    using BatchedTextureOptions = OSL::BatchedTextureOptions<WIDTH_OF_OSL_DATA>;
 
 #undef OSL_USING_DATA_WIDTH
 #ifdef __OSL_USING_SHADERGLOBALS
@@ -297,4 +296,4 @@ template<int WidthT> class BatchedTextureOutputs {
         __OSL_USING_BATCHED_TEXTURE(WIDTH_OF_OSL_DATA)
 #endif
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/device_ptr.h b/src/include/OSL/device_ptr.h
@@ -8,7 +8,7 @@
 
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 /// Wrapper class for holding a "device" pointer -- GPU or whatnot. It
@@ -54,4 +54,4 @@ template<class T> class device_ptr {
 
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/dual.h b/src/include/OSL/dual.h
@@ -13,7 +13,7 @@
 #include <OpenImageIO/fmath.h>
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 // Shortcut notation for enable_if trickery
@@ -1367,4 +1367,4 @@ ifloor (const Dual<T,P> &x)
 }
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/dual_vec.h b/src/include/OSL/dual_vec.h
@@ -26,7 +26,7 @@
 #include <OSL/dual.h>
 #include <OSL/Imathx/Imathx.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 #if 0 // appears unused
 /// Templated trick to be able to derive what type we use to represent
@@ -559,4 +559,4 @@ distance (const Vec3 &a, const Dual<Vec3,P> &b)
     return length (a - b);
 }
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/encodedtypes.h b/src/include/OSL/encodedtypes.h
@@ -6,7 +6,7 @@
 
 #include <OSL/oslconfig.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 // Substitute for variable argument list, which is traditionally used with a printf, with arrays
@@ -214,4 +214,4 @@ template<> struct TypeEncoder<uint8_t> {
 }  // namespace pvt
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/fmt_util.h b/src/include/OSL/fmt_util.h
@@ -15,7 +15,7 @@
 // functions must be ustringhash.  To make this easier, these wrappers
 // automatically convert ustring and const char * to ustringhash.
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 namespace pvt {
 // PackedArgs is similar to tuple but packs its data back to back
@@ -143,4 +143,4 @@ warningfmt(OpaqueExecContextPtr oec, const SpecifierT& fmt_specification,
 }
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/genclosure.h b/src/include/OSL/genclosure.h
@@ -9,7 +9,7 @@
 #include <OpenImageIO/ustring.h>
 #include <OSL/oslconfig.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 struct ClosureParam {
@@ -61,4 +61,4 @@ struct ClosureParam {
 
 #define CLOSURE_FINISH_PARAM(st) { TypeDesc(), sizeof(st), nullptr, alignof(st) }
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/hashes.h b/src/include/OSL/hashes.h
@@ -14,7 +14,7 @@
 // specifying the string literal and the name to use for the variable.
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 namespace pvt {
 
@@ -68,4 +68,4 @@ namespace Hashes {
 
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/journal.h b/src/include/OSL/journal.h
@@ -13,7 +13,7 @@
 #include <OSL/oslconfig.h>
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 /// Journal Buffer approach:  each thread gets its own chain of pages within
 /// the shared journal buffer for recording errors, warnings, etc.
@@ -361,4 +361,4 @@ class OSLEXECPUBLIC Writer {
 
 }  // namespace journal
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/llvm_util.h b/src/include/OSL/llvm_util.h
@@ -48,7 +48,7 @@ class PassManager;
 
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 namespace pvt {  // OSL::pvt
 
@@ -1247,4 +1247,4 @@ class OSLEXECPUBLIC LLVM_Util {
 
 
 };  // namespace pvt
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/mask.h b/src/include/OSL/mask.h
@@ -8,7 +8,7 @@
 
 #include <OSL/oslconfig.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 // clang-format off
@@ -371,4 +371,4 @@ Mask<WidthT>::invoke_foreach(FunctorT f) const
 }
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/optautomata.h b/src/include/OSL/optautomata.h
@@ -11,7 +11,7 @@
 
 #include <vector>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 class DfAutomata;
 
@@ -68,4 +68,4 @@ class OSLEXECPUBLIC DfOptimizedAutomata {
     std::vector<State> m_states;
 };
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/oslclosure.h b/src/include/OSL/oslclosure.h
@@ -7,7 +7,7 @@
 #include <OSL/oslconfig.h>
 #include <cstring>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 /// Labels for light walks
 ///
@@ -146,4 +146,4 @@ typedef ClosureComponent* ClosureComponentPtr;
 typedef ClosureAdd* ClosureAddPtr;
 typedef ClosureMul* ClosureMulPtr;
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/oslcomp.h b/src/include/OSL/oslcomp.h
@@ -6,7 +6,7 @@
 
 #include <OSL/oslconfig.h>
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 
 namespace pvt {
@@ -48,4 +48,4 @@ class OSLCOMPPUBLIC OSLCompiler {
 
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
diff --git a/src/include/OSL/oslconfig.h.in b/src/include/OSL/oslconfig.h.in
@@ -55,7 +55,7 @@
 #include <OpenImageIO/span.h>
 
 
-OSL_NAMESPACE_ENTER
+OSL_NAMESPACE_BEGIN
 
 /// Various compile-time defaults are defined here that could, in
 /// principle, be redefined if you are using OSL in some particular
@@ -306,7 +306,7 @@ using ConstIndex = std::integral_constant<int, N>;
 #endif
 
 
-OSL_NAMESPACE_EXIT
+OSL_NAMESPACE_END
 
 
 namespace std {  // not necessary in C++17, then we can just say std::hash