Merge branch 'AcademySoftwareFoundation:main' into uri_for_viewer

Author: kwokcb

.github/workflows/main.yml

@@ -7,13 +7,18 @@ on:
   pull_request:
     paths-ignore:
       - '**.md'
+  schedule:
+    # Nightly build
+    - cron: '30 10 * * *'
   workflow_dispatch:
 
 jobs:
 
   build:
     name: Build
     runs-on: ${{ matrix.os }}
+    env:
+      IS_EXTENDED_BUILD: ${{ github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' }}
     strategy:
       fail-fast: false
       matrix:
@@ -109,6 +114,7 @@ jobs:
           python: 3.13
           cmake_config: -G "Visual Studio 17 2022" -A "x64"
           test_shaders: ON
+          extended_build_oiio: ON
 
         - name: Windows_VS2022_x64_SharedLibs
           os: windows-2025
@@ -156,11 +162,10 @@ jobs:
         Add-Content $env:GITHUB_PATH "$PWD/build/installed/bin"
 
     - name: Install OpenImageIO
-      if: matrix.build_oiio == 'ON' && runner.os == 'Windows'
+      if: env.IS_EXTENDED_BUILD == 'true' && matrix.extended_build_oiio == 'ON' && runner.os == 'Windows'
       run: |
-        C:/vcpkg/vcpkg install openimageio --triplet=x64-windows-release
-        Add-Content $env:GITHUB_PATH "C:/vcpkg/installed/x64-windows-release/bin"
-        Add-Content $env:GITHUB_PATH "C:/vcpkg/installed/x64-windows-release/share/openimageio"
+        C:/vcpkg/vcpkg install openimageio --triplet=x64-windows
+        Add-Content $env:GITHUB_PATH "C:/vcpkg/installed/x64-windows/bin"
 
     - name: Install Python ${{ matrix.python }}
       if: matrix.python != 'None'
@@ -178,7 +183,12 @@ jobs:
       run: find source \( -name *.h -o -name *.cpp -o -name *.mm -o -name *.inl \) ! -path "*/External/*" ! -path "*/NanoGUI/*" | xargs clang-format -i --verbose
 
     - name: CMake Generate
-      run: cmake -S . -B build -DMATERIALX_BUILD_PYTHON=ON -DMATERIALX_BUILD_VIEWER=ON -DMATERIALX_BUILD_GRAPH_EDITOR=ON -DMATERIALX_BUILD_TESTS=ON -DMATERIALX_TEST_RENDER=OFF -DMATERIALX_WARNINGS_AS_ERRORS=ON ${{matrix.cmake_config}}
+      shell: bash
+      run: |
+        if [ "${{ env.IS_EXTENDED_BUILD }}" == "true" ] && [ "${{ matrix.extended_build_oiio }}" == "ON" ]; then
+          EXTENDED_BUILD_CONFIG="-DMATERIALX_BUILD_OIIO=ON -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows"
+        fi
+        cmake -S . -B build -DMATERIALX_BUILD_PYTHON=ON -DMATERIALX_BUILD_VIEWER=ON -DMATERIALX_BUILD_GRAPH_EDITOR=ON -DMATERIALX_BUILD_TESTS=ON -DMATERIALX_TEST_RENDER=OFF -DMATERIALX_WARNINGS_AS_ERRORS=ON $EXTENDED_BUILD_CONFIG ${{matrix.cmake_config}}
 
     - name: CMake Build
       run: cmake --build build --target install --config Release --parallel 2

CONTRIBUTING.md

@@ -189,7 +189,96 @@ in the ASWF Slack or in TSC meetings before any PR is submitted, in order to
 solicit feedback, build consensus, and alert all stakeholders to be on the
 lookout for the eventual PR when it appears.
 
-### Coding Conventions
+### Developer Guidelines
+
+The following guidelines represent coding standards that we strive to follow
+in the MaterialX project. While not all existing code may adhere to these
+standards yet, we encourage all new contributions to follow these practices,
+and we welcome incremental improvements to bring existing code into alignment
+with these guidelines.
+
+#### Naming Conventions
+
+Class names should use PascalCase, as in `NodeGraph` or `ShaderGenerator`.
+Method names should use camelCase starting with a lowercase letter, for
+example `getNode` or `setName`. Protected and private member variables should
+use an underscore prefix, such as `_name` or `_parent`. Constants should be
+written in UPPER_CASE with underscores separating words, as in `EMPTY_STRING`
+or `CATEGORY`. Type aliases should append appropriate suffixes to indicate
+their purpose, using `Ptr` for pointers, `Vec` for vectors, `Map` for maps,
+and `Set` for sets.
+
+#### Static Constants and Class Organization
+
+Class members should be organized in order of decreasing visibility: public,
+protected, then private. Static constants should be placed at the end of their
+respective visibility section. String constants should be defined in implementation
+files rather than headers to avoid One Definition Rule violations. The
+`EMPTY_STRING` constant should be used instead of empty string literals (`""`)
+for clarity and consistency.
+
+#### Smart Pointer Conventions
+
+Heap-allocated objects in the public API should always use `shared_ptr` for
+memory management. Type aliases should be defined for all shared pointers,
+following the pattern of `ElementPtr` for `shared_ptr<Element>`. Both mutable
+and const versions of these type aliases should be provided, e.g. `ElementPtr`
+and `ConstElementPtr`. Raw pointers should be avoided except when representing
+non-owning references within implementation details.
+
+#### Const Correctness
+
+Methods that do not modify an object's state should be marked as `const`.
+Accessor methods should provide const versions to enable their use on const
+objects. Type aliases following the pattern `ConstElementPtr` should be used to
+indicate read-only access through shared pointers. Parameters that should not
+be modified within a function should be declared as const.
+
+#### Parameter Passing and Return Values
+
+Strings and complex objects should be passed by `const&` to avoid unnecessary
+copies. Shared pointers should be passed by value since they are designed to
+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.
+
+#### Exception Handling
+
+Exceptions should be used for exceptional conditions rather than for normal
+control flow. Custom exception types should be defined by inheriting from
+`Exception` to represent specific error categories. Exception messages should
+be descriptive and include relevant context to aid in debugging. All exceptions
+that may be thrown by a method should be documented using the `@throws` tag in
+the method's documentation. When catching exceptions, specific exception types
+should be caught rather than generic exceptions whenever possible.
+
+#### Header Includes
+
+Header includes should be written with angle brackets, with paths relative to
+the root source folder (e.g. `#include <MaterialXCore/Element.h>`). This
+ensures consistent include paths across the entire codebase, regardless of the
+location of the referencing file.
+
+Each implementation file should include its corresponding header file first,
+so the first include in `Element.cpp` should be `Element.h`. This ensures that
+the header file is self-contained and doesn't accidentally depend on includes
+from other headers.
+
+After the corresponding header, include blocks should be ordered hierarchically,
+with high-level modules listed before low-level modules (e.g.
+`MaterialXGenShader`, followed by `MaterialXFormat`, followed by
+`MaterialXCore`). This maximizes opportunities to catch missing dependencies in
+the high-level modules, which might otherwise be hidden at build time. Within
+include blocks, individual includes should be ordered alphabetically, providing
+a simple canonical order that is straightforward for developers to check.
+
+In the interest of avoiding include cycles, developers are free to leverage
+forward declarations of classes that are trivially referenced within another
+header. In the interest of clarity and efficiency, developers are free to
+leverage transitive header includes, where low-level headers that have already
+been included by a high-level header do not need to be restated individually.
+
+#### Coding Style
 
 The coding style of the MaterialX project is defined by a
 [clang-format](.clang-format) file in the repository, which is supported by
@@ -200,7 +289,18 @@ file to automatically align the code to MaterialX conventions. When modifying
 existing code, follow the surrounding formatting conventions so that new or
 modified code blends in with the current code.
 
-### Unit Tests
+#### Documentation Standards
+
+All classes and methods in the public API should be documented with Doxygen
+comments. Classes should be documented with the `@class` tag, and structs with
+the `@struct` tag, followed by a brief description and any detailed
+documentation. Method documentation should include `@param`, `@return`, and
+`@throws` tags where applicable. Related methods should be grouped together
+using `/// @name GroupName` sections to improve readability. File-level
+documentation should be placed immediately after the copyright header using
+the `/// @file` directive.
+
+#### Unit Tests
 
 Each MaterialX module has a companion folder within the
 [MaterialXTest](source/MaterialXTest) module, containing a set of unit tests

javascript/MaterialXView/example_materials.json

@@ -0,0 +1,24 @@
+{
+  "materials": [
+    {
+      "name": "StandardSurface",
+      "path": "../../resources/Materials/Examples/StandardSurface",
+      "baseURL": "Materials/Examples/StandardSurface"
+    },
+    {
+      "name": "UsdPreviewSurface", 
+      "path": "../../resources/Materials/Examples/UsdPreviewSurface",
+      "baseURL": "Materials/Examples/UsdPreviewSurface"
+    },
+    {
+      "name": "GltfPbr",
+      "path": "../../resources/Materials/Examples/GltfPbr", 
+      "baseURL": "Materials/Examples/GltfPbr"
+    },
+    {
+      "name": "OpenPbr",
+      "path": "../../resources/Materials/Examples/OpenPbr",
+      "baseURL": "Materials/Examples/OpenPbr"
+    }
+  ]
+}

javascript/MaterialXView/source/viewer.js

@@ -182,7 +182,7 @@ export class Scene
 
                 if (!child.geometry.attributes.normal)
                 {
-                    var startNormalTime = performance.new();
+                    var startNormalTime = performance.now();
                     child.geometry.computeVertexNormals();
                     normalTime += performance.now() - startNormalTime;
                 }

javascript/MaterialXView/webpack.config.js

@@ -3,41 +3,26 @@ const fs = require('fs');
 const CopyPlugin = require("copy-webpack-plugin");
 const HtmlWebpackPlugin = require('html-webpack-plugin')
 
-const stdSurfaceMaterials = "../../resources/Materials/Examples/StandardSurface";
-const stdSurfaceMaterialsBaseURL = "Materials/Examples/StandardSurface";
-let dirent = fs.readdirSync(stdSurfaceMaterials).filter(
-    function (file) { if (file.lastIndexOf(".mtlx") > -1) return file; }
-)
-let materials = dirent
-    .map((fileName) => ({ name: fileName, value: `${stdSurfaceMaterialsBaseURL}/${fileName}` }));
-
-const usdSurfaceMaterials = "../../resources/Materials/Examples/UsdPreviewSurface";
-const usdSurfaceMaterialsBaseURL = "Materials/Examples/UsdPreviewSurface";
-dirent = fs.readdirSync(usdSurfaceMaterials).filter(
-    function (file) { if (file.lastIndexOf(".mtlx") > -1) return file; }
-)
-let usdMaterials = dirent
-    .map((fileName) => ({ name: fileName, value: `${usdSurfaceMaterialsBaseURL}/${fileName}` }));
+// Load material configuration from external JSON file
+const materialConfig = JSON.parse(fs.readFileSync('./example_materials.json', 'utf8'));
 
-const gltfPbrMaterials = "../../resources/Materials/Examples/GltfPbr";
-const gltfPbrMaterialsBaseURL = "Materials/Examples/GltfPbr";
-dirent = fs.readdirSync(gltfPbrMaterials).filter(
-    function (file) { if (file.lastIndexOf(".mtlx") > -1) return file; }
-)
-let gltfMaterials = dirent
-    .map((fileName) => ({ name: fileName, value: `${gltfPbrMaterialsBaseURL}/${fileName}` }));
-
-const openPbrMaterials = "../../resources/Materials/Examples/OpenPbr";
-const openPbrMaterialsBaseURL = "Materials/Examples/OpenPbr";
-dirent = fs.readdirSync(openPbrMaterials).filter(
-    function (file) { if (file.lastIndexOf(".mtlx") > -1) return file; }
-)
-let openMaterials = dirent
-    .map((fileName) => ({ name: fileName, value: `${openPbrMaterialsBaseURL}/${fileName}` }));
+// Function to process materials from a given path
+function processMaterialPath(materialPath, baseURL) {
+    const dirent = fs.readdirSync(materialPath).filter(
+        function (file) { if (file.lastIndexOf(".mtlx") > -1) return file; }
+    );
+    return dirent.map((fileName) => ({ 
+        name: fileName, 
+        value: `${baseURL}/${fileName}` 
+    }));
+}
 
-materials = materials.concat(usdMaterials);
-materials = materials.concat(gltfMaterials);
-materials = materials.concat(openMaterials);
+// Generate materials array from configuration
+let materials = [];
+materialConfig.materials.forEach(materialType => {
+    const materialFiles = processMaterialPath(materialType.path, materialType.baseURL);
+    materials = materials.concat(materialFiles);
+});
 
 const geometryFiles = "../../resources/Geometry";
 const geometryFilesURL = "Geometry";
@@ -77,10 +62,11 @@ module.exports = {
                 { from: "./public", to: 'public' },
                 { context: "../../resources/Lights", from: "*.*", to: "Lights" },
                 { context: "../../resources/Lights/irradiance", from: "*.*", to: "Lights/irradiance" },
-                { from: stdSurfaceMaterials, to: stdSurfaceMaterialsBaseURL },
-                { from: usdSurfaceMaterials, to: usdSurfaceMaterialsBaseURL },
-                { from: gltfPbrMaterials, to: gltfPbrMaterialsBaseURL },
-                { from: openPbrMaterials, to: openPbrMaterialsBaseURL },
+                // Dynamically generate material copy patterns from configuration
+                ...materialConfig.materials.map(materialType => ({
+                    from: materialType.path,
+                    to: materialType.baseURL
+                })),
                 { from: "../build/bin/JsMaterialXCore.wasm" },
                 { from: "../build/bin/JsMaterialXCore.js" },
                 { from: "../build/bin/JsMaterialXGenShader.wasm" },

javascript/build_javascript_win.bat

@@ -5,8 +5,8 @@
 @rem Edit the following paths to match your local locations for the Emscripten and MaterialX projects.
 set EMSDK_LOCATION=C:/GitHub/emsdk
 set MATERIALX_LOCATION=C:/GitHub/MaterialX
-call %EMSDK_LOCATION%/emsdk.bat install 2.0.20
-call %EMSDK_LOCATION%/emsdk.bat activate 2.0.20
+call %EMSDK_LOCATION%/emsdk.bat install 4.0.8
+call %EMSDK_LOCATION%/emsdk.bat activate 4.0.8
 if NOT ["%errorlevel%"]==["0"] pause
 @echo --------------------- Build MaterialX With JavaScript ---------------------
 @echo on

libraries/bxdf/translation/standard_surface_to_gltf_pbr.mtlx

@@ -5,6 +5,8 @@
     <input name="base" type="float" value="1" />
     <input name="base_color" type="color3" value="0.8, 0.8, 0.8" />
     <input name="metalness" type="float" value="0" />
+    <input name="specular" type="float" value="1" />
+    <input name="specular_color" type="color3" value="1, 1, 1" />
     <input name="specular_anisotropy" type="float" value="0.0" />
     <input name="specular_rotation" type="float" value="0.0" />
     <input name="specular_roughness" type="float" value="0.2" />
@@ -27,6 +29,8 @@
     <output name="base_color_out" type="color3" />
     <output name="metallic_out" type="float" />
     <output name="roughness_out" type="float" />
+    <output name="specular_out" type="float" />
+    <output name="specular_color_out" type="color3" />
     <output name="ior_out" type="float" />
     <output name="anisotropy_strength_out" type="float" />
     <output name="anisotropy_rotation_out" type="float" />
@@ -203,6 +207,14 @@
       <input name="in" type="float" interfacename="emission" />
     </dot>
 
+    <!-- Specular -->
+    <dot name="specular" type="float">
+      <input name="in" type="float" interfacename="specular" />
+    </dot>
+    <dot name="specular_color" type="color3">
+      <input name="in" type="color3" interfacename="specular_color" />
+    </dot>
+
     <!-- Specular Index of Refraction -->
     <dot name="ior" type="float">
       <input name="in" type="float" interfacename="specular_IOR" />
@@ -236,6 +248,8 @@
     <output name="base_color_out" type="color3" nodename="base_color" />
     <output name="metallic_out" type="float" nodename="metallic" />
     <output name="roughness_out" type="float" nodename="roughness" />
+    <output name="specular_out" type="float" nodename="specular" />
+    <output name="specular_color_out" type="color3" nodename="specular_color" />
     <output name="ior_out" type="float" nodename="ior" />
     <output name="anisotropy_strength_out" type="float" nodename="anisotropy_strength" />
     <output name="anisotropy_rotation_out" type="float" nodename="anisotropy_rotation" />

libraries/pbrlib/genglsl/lib/mx_environment_fis.glsl

@@ -59,7 +59,7 @@ vec3 mx_environment_radiance(vec3 N, vec3 V, vec3 X, vec2 alpha, int distributio
     radiance /= G1V * float(envRadianceSamples);
 
     // Return the final radiance.
-    return radiance * $envLightIntensity;
+    return ($envRadianceSamples == 0 ? vec3(0.0) : radiance) * $envLightIntensity;
 }
 
 vec3 mx_environment_irradiance(vec3 N)

libraries/pbrlib/genglsl/lib/mx_shadow_platform.glsl

@@ -0,0 +1,13 @@
+
+float mx_shadow_occlusion(
+    $texSamplerSignature,
+    mat4 shadow_matrix,
+    vec3 world_position
+)
+{
+    vec4 shadowCoord4 = mx_matrix_mul(shadow_matrix, vec4(world_position, 1.0));
+    vec3 shadowCoord = shadowCoord4.xyz / shadowCoord4.w;
+    shadowCoord = shadowCoord * 0.5 + 0.5;
+    vec2 shadowMoments = texture($texSamplerSampler2D, shadowCoord.xy).xy;
+    return  mx_variance_shadow_occlusion(shadowMoments, shadowCoord.z);
+}

libraries/pbrlib/genmsl/lib/mx_lighting_platform.metal

@@ -0,0 +1,13 @@
+
+float mx_shadow_occlusion(
+    MetalTexture shadow_map_tex,
+    float4x4 shadow_matrix,
+    float3 world_position
+)
+{
+    float4 shadowCoord4 = mx_matrix_mul(shadow_matrix, float4(world_position, 1.0));
+    float3 shadowCoord = shadowCoord4.xyz / shadowCoord4.w;
+    shadowCoord.xy = shadowCoord.xy * 0.5 + 0.5;
+    float2 shadowMoments = texture(shadow_map_tex, shadowCoord.xy).xy;
+    return mx_variance_shadow_occlusion(shadowMoments, shadowCoord.z);
+}