Merge branch 'AcademySoftwareFoundation:main' into uri_for_viewer

Author: kwokcb

.github/workflows/main.yml

@@ -31,6 +31,7 @@ jobs:
           compiler: gcc
           compiler_version: "14"
           python: 3.13
+          extended_build_perfetto: ON
 
         - name: Linux_GCC_14_Python314
           os: ubuntu-24.04
@@ -174,8 +175,8 @@ jobs:
     - name: Install MDL SDK
       if: env.IS_EXTENDED_BUILD == 'true' && matrix.extended_build_mdl_sdk == 'ON' && runner.os == 'Windows'
       run: |
-        C:/vcpkg/vcpkg install mdl-sdk --triplet=x64-windows
-        Add-Content $env:GITHUB_PATH "C:/vcpkg/installed/x64-windows/bin"
+        C:/vcpkg/vcpkg install mdl-sdk[dds,df-vulkan,openimageio] --triplet=x64-windows-release
+        Add-Content $env:GITHUB_PATH "C:/vcpkg/installed/x64-windows-release/bin"
 
     - name: Install Python ${{ matrix.python }}
       if: matrix.python != 'None'
@@ -198,13 +199,16 @@ jobs:
         EXTENDED_BUILD_CONFIG=""
         if [ "${{ env.IS_EXTENDED_BUILD }}" == "true" ]; then
           if [ "${{ runner.os }}" == "Windows" ]; then
-            EXTENDED_BUILD_CONFIG="-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows"
+            EXTENDED_BUILD_CONFIG="-DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake"
           fi
           if [ "${{ matrix.extended_build_oiio }}" == "ON" ]; then
-            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DMATERIALX_BUILD_OIIO=ON"
+            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DVCPKG_TARGET_TRIPLET=x64-windows -DMATERIALX_BUILD_OIIO=ON"
           fi
           if [ "${{ matrix.extended_build_mdl_sdk }}" == "ON" -a "${{ runner.os }}" == "Windows" ]; then
-            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DMATERIALX_MDL_SDK_DIR=C:/vcpkg/installed/x64-windows"
+            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DVCPKG_TARGET_TRIPLET=x64-windows-release -DMATERIALX_MDL_SDK_DIR=C:/vcpkg/installed/x64-windows-release"
+          fi
+          if [ "${{ matrix.extended_build_perfetto }}" == "ON" ]; then
+            EXTENDED_BUILD_CONFIG="$EXTENDED_BUILD_CONFIG -DMATERIALX_BUILD_PERFETTO_TRACING=ON"
           fi
         fi
         TEST_RENDER_CONFIG="-DMATERIALX_TEST_RENDER=OFF"
@@ -228,7 +232,8 @@ jobs:
       run: |
         python MaterialXTest/main.py
         python MaterialXTest/genshader.py
-        python Scripts/comparenodedefs.py
+        python Scripts/comparenodedefs.py --spec ../documents/Specification/MaterialX.StandardNodes.md --mtlx ../libraries/stdlib/stdlib_defs.mtlx
+        python Scripts/comparenodedefs.py --spec ../documents/Specification/MaterialX.PBRSpec.md --mtlx ../libraries/pbrlib/pbrlib_defs.mtlx
         python Scripts/creatematerial.py ../resources/Materials/Examples/StandardSurface/chess_set --texturePrefix chessboard --shadingModel standard_surface
         python Scripts/creatematerial.py ../resources/Materials/Examples/GltfPbr/boombox --shadingModel gltf_pbr
         python Scripts/mxformat.py ../resources/Materials/TestSuite/stdlib/upgrade --yes --upgrade
@@ -265,7 +270,7 @@ jobs:
       run: |
         sudo apt-get install gcovr
         mkdir coverage
-        gcovr --html --html-details --output coverage/index.html --exclude .*\/External\/.* --root .. .
+        gcovr --html --html-details --output coverage/index.html --exclude .*\/External\/.* --exclude .*perfetto.* --root .. .
       working-directory: build
 
     - name: Static Analysis Tests
@@ -276,7 +281,7 @@ jobs:
         else
           brew install cppcheck
         fi
-        cppcheck --project=build/compile_commands.json --error-exitcode=1 --suppress=normalCheckLevelMaxBranches --suppress=*:*/External/* --suppress=*:*/NanoGUI/*
+        cppcheck --project=build/compile_commands.json --error-exitcode=1 --suppress=normalCheckLevelMaxBranches --suppress=*:*/External/* --suppress=*:*/NanoGUI/* --suppress=*:*perfetto*
 
     - name: Setup Rendering Environment (Linux)
       if: matrix.test_render == 'ON' && runner.os == 'Linux'
@@ -357,6 +362,14 @@ jobs:
         name: MaterialX_Coverage
         path: build/coverage
 
+    - name: Upload Perfetto Traces
+      uses: actions/upload-artifact@v4
+      if: matrix.extended_build_perfetto == 'ON' && env.IS_EXTENDED_BUILD == 'true'
+      with:
+        name: Traces_${{ matrix.name }}
+        path: build/**/*.perfetto-trace
+        if-no-files-found: ignore
+
   javascript:
     name: JavaScript
     runs-on: ubuntu-latest
@@ -467,6 +480,10 @@ jobs:
         name: MaterialX_Python_SDist
         path: sdist
 
+    - name: Install Doxygen (Windows)
+      uses: ssciwr/doxygen-install@v1
+      if: runner.os == 'Windows'
+
     - name: Build Wheel
       uses: pypa/cibuildwheel@v2.23.2
       with:
@@ -478,7 +495,6 @@ jobs:
         CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
         CIBW_BEFORE_ALL_LINUX: yum install -y libXt-devel doxygen
         CIBW_BEFORE_ALL_MACOS: brew install doxygen
-        CIBW_BEFORE_ALL_WINDOWS: choco install doxygen.install -y
         CIBW_BUILD_VERBOSITY: 1
         CIBW_ENVIRONMENT: CMAKE_BUILD_PARALLEL_LEVEL=2
         MACOSX_DEPLOYMENT_TARGET: '11.0'

CMakeLists.txt

@@ -51,6 +51,7 @@ option(MATERIALX_BUILD_OCIO "Build OpenColorIO support for shader generators." O
 option(MATERIALX_BUILD_TESTS "Build unit tests." OFF)
 option(MATERIALX_BUILD_BENCHMARK_TESTS "Build benchmark tests." OFF)
 option(MATERIALX_BUILD_OSOS "Build OSL .oso's of standard library shaders for the OSL Network generator" OFF)
+option(MATERIALX_BUILD_PERFETTO_TRACING "Build with Perfetto tracing support for performance analysis." OFF)
 
 option(MATERIALX_BUILD_SHARED_LIBS "Build MaterialX libraries as shared rather than static." OFF)
 option(MATERIALX_BUILD_DATA_LIBRARY "Build generated products from the MaterialX data library." OFF)
@@ -224,9 +225,45 @@ mark_as_advanced(MATERIALX_EMSDK_PATH)
 mark_as_advanced(MATERIALX_BUILD_IOS)
 mark_as_advanced(MATERIALX_BUILD_APPLE_FRAMEWORK)
 mark_as_advanced(MATERIALX_MDL_BINARY_MDLC)
+mark_as_advanced(MATERIALX_MDL_BINARY_TESTRENDER)
 mark_as_advanced(MATERIALX_MDL_MODULE_PATHS)
 mark_as_advanced(MATERIALX_MDL_SDK_DIR)
 mark_as_advanced(MATERIALX_SLANG_RHI_SOURCE_DIR)
+mark_as_advanced(MATERIALX_BUILD_PERFETTO_TRACING)
+
+# Perfetto tracing support
+if(MATERIALX_BUILD_PERFETTO_TRACING)
+    include(FetchContent)
+    FetchContent_Declare(
+        perfetto
+        GIT_REPOSITORY https://android.googlesource.com/platform/external/perfetto
+        GIT_TAG v43.0
+        GIT_SHALLOW TRUE
+    )
+    # Only fetch the SDK, not the full Perfetto source
+    set(PERFETTO_SDK_INCLUDE_DIR "${CMAKE_BINARY_DIR}/_deps/perfetto-src/sdk")
+    FetchContent_MakeAvailable(perfetto)
+    add_definitions(-DMATERIALX_BUILD_PERFETTO_TRACING)
+    
+    # Define compile flags for perfetto.cc (Perfetto SDK triggers various warnings)
+    # These variables are used in source/CMakeLists.txt (monolithic) and MaterialXTrace (non-monolithic)
+    # Note: set_source_files_properties is directory-scoped, so we define variables here
+    # but apply them in the directories where targets are created.
+    if(MSVC)
+        set(MATERIALX_PERFETTO_COMPILE_DEFINITIONS "NOMINMAX;WIN32_LEAN_AND_MEAN" CACHE INTERNAL "")
+        # /bigobj: perfetto.cc has too many sections for default MSVC object format
+        # /W0: disable all warnings for third-party Perfetto SDK code
+        # /WX-: disable warnings-as-errors (overrides project-level /WX)
+        set(MATERIALX_PERFETTO_COMPILE_FLAGS "/bigobj /W0 /WX-" CACHE INTERNAL "")
+    else()
+        set(MATERIALX_PERFETTO_COMPILE_DEFINITIONS "" CACHE INTERNAL "")
+        # -Wno-error: Don't treat warnings as errors (Perfetto has shadowing issues)
+        # -Wno-shadow: Suppress shadow warnings (kDevNull shadows global)
+        set(MATERIALX_PERFETTO_COMPILE_FLAGS "-Wno-error -Wno-shadow" CACHE INTERNAL "")
+    endif()
+    
+    message(STATUS "Perfetto tracing support enabled")
+endif()
 
 if (MATERIALX_BUILD_USE_CCACHE)
     # Setup CCache for C/C++ compilation
@@ -264,11 +301,23 @@ if (MATERIALX_BUILD_BENCHMARK_TESTS)
     add_definitions(-DMATERIALX_BUILD_BENCHMARK_TESTS)
 endif()
 
-# GEN MDL does not have any additional dependencies. For loading and compiling MDL, e.g., in the test renderer, the MDL SDK is needed.
+# MaterialXGenMdl does not have any additional dependencies.
+# MaterialXTest/MaterialXGenMdl performs a syntax check if the mdlc binary is available.
+# MaterialXTest/MaterialXRenderMdl needs the df_vulkan example, SDK library, and image plugins.
 if(MATERIALX_MDL_SDK_DIR)
     find_package(mdl QUIET CONFIG REQUIRED PATHS ${MATERIALX_MDL_SDK_DIR})
     get_target_property(MATERIALX_MDL_BINARY_MDLC mdl::mdlc LOCATION)
     set(MATERIALX_MDL_BINARY_MDLC ${MATERIALX_MDL_BINARY_MDLC} CACHE FILEPATH "Full path to the mdlc binary." FORCE)
+    if((${mdl_VERSION} VERSION_GREATER_EQUAL "2025.0.3") OR (${mdl_VERSION} STREQUAL "trunk"))
+        find_program(MATERIALX_MDL_BINARY_TESTRENDER
+            NAMES df_vulkan
+            HINTS
+                ${MATERIALX_MDL_SDK_DIR}/examples/mdl_sdk/df_vulkan   # regular install layout
+                ${MATERIALX_MDL_SDK_DIR}/tools/mdl-sdk)               # vcpkg layout
+    else()
+        message(WARNING "The MDL df_vulkan test renderer requires an MDL SDK >= 2025.0.3 (found ${mdl_VERSION}).")
+        set(MATERIALX_MDL_BINARY_TESTRENDER "" CACHE FILEPATH "Full path to the MDL df_vulkan test renderer.")
+    endif()
 endif()
 
 # Adjust the default installation path
@@ -478,6 +527,9 @@ endif()
 # Add core subdirectories
 add_subdirectory(source/MaterialXCore)
 add_subdirectory(source/MaterialXFormat)
+if(MATERIALX_BUILD_PERFETTO_TRACING)
+    add_subdirectory(source/MaterialXTrace)
+endif()
 
 # Add shader generation subdirectories
 add_subdirectory(source/MaterialXGenShader)

CONTRIBUTING.md

@@ -242,6 +242,14 @@ be cheap to copy. When returning shared pointers, they should be returned by
 value rather than by reference. Methods should be marked as `const` whenever
 they do not modify the object's state.
 
+#### Thread Safety
+
+MaterialX classes support multiple concurrent readers, but not concurrent
+reads and writes, following the pattern of standard C++ containers.  This
+design enables efficient parallel processing in read-heavy workloads such
+as shader generation and scene traversal, while keeping the implementation 
+simple and avoiding the overhead of fine-grained locking.
+
 #### Exception Handling
 
 Exceptions should be used for exceptional conditions rather than for normal

GOVERNANCE.md

@@ -48,6 +48,8 @@ The current Voting Members of the MaterialX TSC are:
 - Doug Smythe - Industrial Light & Magic
 - Niklas Harrysson - Lumiere Software
 - Orn Gunnarsson - Autodesk
+- Lee Kerley - Apple
+- Frankie Liu - NVIDIA
 - Andréa Machizaud - Adobe
 
 ### Stakeholders
@@ -66,8 +68,6 @@ The current Stakeholders of the MaterialX TSC are:
 - Fran González García - Pixar RenderMan
 - Ole Gulbrandsen - Sony Pictures Imageworks
 - Rafal Jaroszkiewicz - SideFX
-- Lee Kerley - Apple
-- Lutz Kettner - NVIDIA
 - Chris Kulla - Epic Games
 - Bernard Kwok - Khronos Group
 - Karen Lucknavalai - Pixar USD

cmake/modules/MaterialXConfig.cmake.in

@@ -39,6 +39,14 @@ if(@MATERIALX_BUILD_RENDER@ AND @MATERIALX_INSTALL_RESOURCES@)
     set_and_check(MATERIALX_RESOURCES_DIR "@PACKAGE_CMAKE_INSTALL_PREFIX@/resources")
 endif()
 
+if(UNIX AND NOT APPLE)
+    find_dependency(X11 REQUIRED COMPONENTS Xt)
+    if("RenderGlsl" IN_LIST MaterialX_FIND_COMPONENTS)
+        find_dependency(OpenGL REQUIRED)
+        set(MaterialX_RenderGlsl_FOUND TRUE)
+    endif()
+endif()
+
 check_required_components(@CMAKE_PROJECT_NAME@)
 
 @EXPORT_ALIASES@

documents/Specification/MaterialX.NPRSpec.md

@@ -36,35 +36,55 @@ This document describes a number of MaterialX nodes primarily applicable to non-
 
 <a id="node-viewdirection"> </a>
 
-* **`viewdirection`**: the current scene view direction (e.g. from the viewing/camera position to the current shading position).  If `viewdirection` is used in a PBR shading context, it should be noted that this would be the same as the incident ray direction for primary ("camera") rays but **not** for secondary/reflection rays.  This node must be of type vector3.
+### `viewdirection`
+The current scene view direction, as defined by the shading environment.
 
-    * `space` (uniform string):  the space in which to return the view vector direction, defaults to `world`. 
+The view direction is a normalized vector from the viewer position to the current shading position. In a PBR shading context, it represents the incident direction for primary camera rays, independent of any secondary or reflection rays.
+
+|Port   |Description                           |Type   |Default|Accepted Values     |
+|-------|--------------------------------------|-------|-------|--------------------|
+|`space`|The space of the view direction vector|string |world  |model, object, world|
+|`out`  |Output: view direction                |vector3|       |                    |
 
 
 
 ## NPR Utility Nodes
 
 <a id="node-facingratio"> </a>
 
-* **`facingratio`**: returns the geometric facing ratio, computed as the dot product between the view direction and geometric normal.  Output is a float between 0.0 and 1.0.
+### `facingratio`
+The geometric facing ratio of the view direction and surface normal.
+
+Facing ratio is computed as the dot product between the view direction and surface normal.
+
+|Port           |Description                                                               |Type   |Default |
+|---------------|--------------------------------------------------------------------------|-------|--------|
+|`viewdirection`|The input view direction vector                                           |vector3|_Vworld_|
+|`normal`       |The input surface normal vector                                           |vector3|_Nworld_|
+|`faceforward`  |Makes the output always positive, facing towards the view direction       |boolean|true    |
+|`invert`       |Inverts the output values by multiplying them by -1                       |boolean|false   |
+|`out`          |Output: the float representing the ratio between view direction and normal|float  |        |
 
-    * `viewdirection` (vector3): the viewing direction, defaults to the value of the "Vworld" (world space view direction) geometric property.
-    * `normal` (vector3): the surface normal vector, defaults to the value of the "Nworld" (world space view direction) geometric property.  This vector is expected to be prenormalized to length 1.0.
-    * `faceforward` (boolean): description needed; default is false.
-    * `invert` (boolean): description needed; default is false.
 
 
 
 ## NPR Shading Nodes
 
 <a id="node-gooch-shade"> </a>
 
-* **`gooch_shade`**: Computes the single-pass shading portion of the Gooch[^Gooch1998] lighting model.  Output type `surfaceshader`.
-    * `warm_color` (color3): the "warm" color for shading, defaults to (0.8, 0.8, 0.7) in the `lin_rec709` colorspace.
-    * `cool_color` (color3): the "cool" color for shading, defaults to (0.3, 0.3, 0.8) in the `lin_rec709` colorspace.
-    * `specular_intensity` (float): the intensity of the specular component. Defaults to 1.0.
-    * `shininess` (float): the specular power typically ranging from 1 to 256, defaults to 64.
-    * `light_direction` (vector3): the incoming predominant lighting direction in world space, defaults to (1.0, -0.5, -0.5).
+### `gooch_shade`
+Computes the color from single-pass shading portion of the Gooch[^Gooch1998] lighting model.
+
+Gooch shade provides an illustrative shading effect by blending colors based on the angle between the surface normal and the light direction. It also provides a simple Phong specular highlight, on top of the warm and cool colors.
+
+|Port                |Description                            |Type   |Default      |
+|--------------------|---------------------------------------|-------|-------------|
+|`warm_color`        |The color facing toward the light      |color3 |0.8, 0.8, 0.7|
+|`cool_color`        |The color facing away from the light   |color3 |0.3, 0.3, 0.8|
+|`specular_intensity`|The intensity of the highlight         |float  |1            |
+|`shininess`         |The size of the highlight              |float  |64           |
+|`light_direction`   |The world-space direction of the light |vector3|1, -0.5, -0.5|
+|`out`               |Output: the Gooch lighting model result|color3 |             |
 
 <br>