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]>

Author: lgritz

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.

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 \

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

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

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

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

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

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

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

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