Merge branch 'AcademySoftwareFoundation:main' into projection_definitions

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
@@ -206,6 +207,9 @@ jobs:
           if [ "${{ matrix.extended_build_mdl_sdk }}" == "ON" -a "${{ runner.os }}" == "Windows" ]; then
             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"
         if [ "${{ matrix.test_render }}" == "ON" ]; then
@@ -266,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
@@ -277,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'
@@ -358,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

CHANGELOG.md

@@ -2,6 +2,56 @@
 
 ## [1.39.5] - Development
 
+### Added
+- Added support for the [Slang shading language](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2548) in MaterialX shader generation and rendering, with [language bindings](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2679) for Python and JavaScript.
+- Added [OSL implementations](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2734) for hex-tiled images, completing cross-language coverage for hextiling nodes.
+- Added an [OSL command string code generator](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2603), enabling the mixing of external OSL shaders with MaterialX-generated nodes.
+- Added support for [GLSL probability density functions](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2779), providing a foundation for path-tracer use of generated GLSL, ESSL, and MSL shaders.
+- Added an [enableDirectLight option](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2773) to the MaterialX Viewer, enabling pure image-based lighting without direct light contributions.
+- Added support for [upstream and downstream node traversal](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2225) in the property editor of the MaterialX Graph Editor.
+- Added shader generation options for [Airy Fresnel iterations](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2569) and [constant node eliding](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2521), supporting quality and performance trade-offs on iridescent materials and interactive editing workflows.
+- Added [Python operator bindings](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2594) for Vector and Matrix types.
+- Added support for [Doxygen-generated docstrings](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2657) in MaterialX Python bindings, enabling IDE support and interactive help.
+- Added a [nodedef comparison script](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2723) for validating alignment between data library definitions and specification documents.
+- Added [Perfetto tracing](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2742) as an optional performance instrumentation framework.
+- Added a [nightly build workflow](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2621) to GitHub Actions, with [test suite rendering on MacOS](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2675) and [MDL compiler validation](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2254).
+- Added [developer guidelines](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2632) to the MaterialX contributing guide.
+
+### Changed
+- Improved specifications for the [Standard Nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2520), [PBR Nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2732), and [NPR Nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2767), converting prose descriptions to structured tables.
+- Consolidated hardware shader generation in a new [MaterialXGenHw module](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2565), [unifying node implementations](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2555) across GLSL and MSL, adopting [syntax-portable type names](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2625) for native Metal support, and [streamlining](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2652) the ShaderGenerator API across hardware shading language generators.
+- Refactored the [layout engine](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2775) in the MaterialX Graph Editor, organizing its logic into a new Layout class aligned with the Sugiyama layered graph drawing algorithm.
+- Improved the [Metal syntax](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2622) in generated MSL shaders, replacing preprocessor workarounds with native Metal code.
+- Improved the [MDL generator](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2684) with support for backsurface shaders and [volume IOR](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2747) preservation.
+- Improved [thread safety](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2736) in the Document cache, adopting `std::shared_mutex` for reader and writer guarantees.
+- Improved [hextiling implementations](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2615) in GLSL and MDL, using array-based data structures for better maintainability.
+- Improved the translation graph from Standard Surface to glTF PBR, adding support for [specular and specular color](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2623), [IOR](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2589), [emissive strength](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2593), [dispersion](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2636), [normal and tangent](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2587), and [alpha](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2591).
+- Updated the [OpenPBR Surface definition](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2759) to connect geometry_thin_walled to the surface node.
+- Extended [shader generation tests](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2761) to cover all example materials.
+- Raised the default PyBind11 version to [PyBind11 3.0.1](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2715), with [Python 3.14](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2717) added to GitHub CI.
+- Raised the default Emscripten SDK to [emsdk 4.0.8](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2599) in the MaterialX Web Viewer.
+
+### Fixed
+- Fixed [node key collisions](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2768) in ShaderGraph, addressing crashes and shader generation errors when multiple nodes shared the same base name.
+- Fixed the implementations of [splittb, ramptb, and ramp4](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2721) in GLSL, OSL, and MDL, correcting the inverted ordering of top and bottom values.
+- Fixed [sheen roughness](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2643) and the handling of [thin_walled and transmission_depth](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2644) in the translation graph from Standard Surface to glTF PBR.
+- Fixed [direct lighting](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2781) in MSL rendering, addressing a uniform name mismatch that caused missing lighting on MacOS.
+- Fixed a crash in shader generation for [constant nodes with zero inputs](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2746), with a [stricter eliding check](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2754) to prevent false matches on custom nodes.
+- Fixed a crash on selecting [functional graph outputs](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2597) in the MaterialX Graph Editor.
+- Fixed [CMake build rules](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2687) for resource installation, the [export](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2724) of MATERIALX_INSTALL_STDLIB_PATH in the CMake config, and the [propagation of dependencies](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2752) for OpenGL and X11 in downstream projects.
+- Fixed a [missing OCIO include](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2780) in the MaterialX Graph Editor, addressing a build error when OCIO support is enabled.
+- Fixed [shadow and environment edge cases](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2617) in GLSL generation, addressing spot light projection, shadow occlusion resetting, and zero-sample environment radiance.
+- Fixed alignment of [two-sided refraction](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2703) and [texture magnification filtering](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2705) between GLSL and MSL rendering.
+- Fixed OSL shader generation for [textureresource and LamaSurface](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2590) nodes.
+- Fixed default inputs in the vector definitions of the [atan2 nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2554).
+- Fixed edge cases in the version upgrade process for [swizzle nodes](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2637).
+- Fixed [Python interfaces](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2541) for image loaders.
+
+### Removed
+- Removed the [NodeGraph dependency](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2601) in shader translation, using NodeDef outputs directly for improved flexibility.
+- Removed [global constructors](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2639) for Traversal constants, improving compatibility with MacOS environments.
+- Removed [unused static members](https://github.com/AcademySoftwareFoundation/MaterialX/pull/2709) from the ShaderNode class.
+
 ## [1.39.4] - 2025-09-15
 
 ### Added

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)
@@ -228,6 +229,41 @@ 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
@@ -491,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)

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

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>