Merge branch 'AcademySoftwareFoundation:main' into node_editor_traversal

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

CMakeLists.txt

@@ -39,7 +39,7 @@ option(MATERIALX_BUILD_GRAPH_EDITOR "Build the MaterialX Graph Editor." OFF)
 option(MATERIALX_BUILD_DOCS "Create HTML documentation using Doxygen. Requires that Doxygen be installed." OFF)
 
 option(MATERIALX_BUILD_GEN_GLSL "Build the GLSL shader generator back-end." ON)
-option(MATERIALX_BUILD_GEN_OSL "Build the OSL shader generator back-end." ON)
+option(MATERIALX_BUILD_GEN_OSL "Build the OSL shader generator back-ends." ON)
 option(MATERIALX_BUILD_GEN_MDL "Build the MDL shader generator back-end." ON)
 option(MATERIALX_BUILD_GEN_MSL "Build the MSL shader generator back-end." ON)
 option(MATERIALX_BUILD_RENDER "Build the MaterialX Render modules." ON)
@@ -48,6 +48,7 @@ option(MATERIALX_BUILD_OIIO "Build OpenImageIO support for MaterialXRender." OFF
 option(MATERIALX_BUILD_OCIO "Build OpenColorIO support for shader generators." OFF)
 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_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)
@@ -85,6 +86,7 @@ if (CMAKE_SYSTEM_NAME MATCHES "iOS" OR CMAKE_SYSTEM_NAME MATCHES "tvOS" OR CMAKE
     set(MATERIALX_BUILD_GEN_GLSL OFF)
     set(MATERIALX_BUILD_GEN_OSL OFF)
     set(MATERIALX_BUILD_GEN_MDL OFF)
+    set(MATERIALX_BUILD_OSOS OFF)
     set(MATERIALX_BUILD_TESTS OFF)
 endif()
 
@@ -103,6 +105,7 @@ if (MATERIALX_BUILD_APPLE_FRAMEWORK)
 endif()
 
 if (MATERIALX_BUILD_JS)
+    set(MATERIALX_BUILD_OSOS OFF)
     set(MATERIALX_BUILD_RENDER OFF)
     set(MATERIALX_BUILD_TESTS OFF)
 endif()
@@ -136,6 +139,13 @@ if(SKBUILD)
     set(MATERIALX_PYTHON_FOLDER_NAME "MaterialX")
 endif()
 
+if (MATERIALX_BUILD_OSOS)
+    set(MATERIALX_BUILD_DATA_LIBRARY ON)
+    set(MATERIALX_BUILD_GEN_OSL ON)
+    set(MATERIALX_BUILD_RENDER ON)
+    set(MATERIALX_BUILD_RENDER_PLATFORMS ON)
+endif()
+
 # Helpers for MDL validation
 if (MATERIALX_BUILD_GEN_MDL)
     set(MATERIALX_MDLC_EXECUTABLE "" CACHE FILEPATH "Full path to the mdlc binary.")
@@ -164,6 +174,7 @@ mark_as_advanced(MATERIALX_BUILD_GEN_GLSL)
 mark_as_advanced(MATERIALX_BUILD_GEN_OSL)
 mark_as_advanced(MATERIALX_BUILD_GEN_MDL)
 mark_as_advanced(MATERIALX_BUILD_GEN_MSL)
+mark_as_advanced(MATERIALX_BUILD_OSOS)
 mark_as_advanced(MATERIALX_BUILD_RENDER)
 mark_as_advanced(MATERIALX_BUILD_RENDER_PLATFORMS)
 mark_as_advanced(MATERIALX_BUILD_OIIO)
@@ -215,7 +226,7 @@ endif()
 
 # Allow the OSL CMake package to provide binary locations for render tests.
 # This will not override explicitly provided oslc, testrender, and include paths.
-if(MATERIALX_BUILD_RENDER AND MATERIALX_BUILD_GEN_OSL AND MATERIALX_BUILD_TESTS)
+if((MATERIALX_BUILD_RENDER AND MATERIALX_BUILD_GEN_OSL AND MATERIALX_BUILD_TESTS) OR MATERIALX_BUILD_OSOS)
     find_package(OSL QUIET)
     if(OSL_FOUND)
         if(NOT MATERIALX_OSL_BINARY_OSLC)
@@ -225,6 +236,10 @@ if(MATERIALX_BUILD_RENDER AND MATERIALX_BUILD_GEN_OSL AND MATERIALX_BUILD_TESTS)
             # OSL does not yet export a CMake target for testrender.
             set(MATERIALX_OSL_BINARY_TESTRENDER $<TARGET_FILE_DIR:OSL::oslc>/testrender)
         endif()
+        if(NOT MATERIALX_OSL_INCLUDE_PATH)
+            # OSL does not yet export a CMake target for testrender.
+            set(MATERIALX_OSL_INCLUDE_PATH $<TARGET_FILE_DIR:OSL::oslc>/../include)
+        endif()
     endif()
 endif()
 
@@ -467,6 +482,9 @@ if(MATERIALX_BUILD_GEN_GLSL OR MATERIALX_BUILD_GEN_OSL OR MATERIALX_BUILD_GEN_MD
         add_definitions(-DMATERIALX_BUILD_GEN_OSL)
         add_subdirectory(source/MaterialXGenOsl)
     endif()
+    if (MATERIALX_BUILD_OSOS)
+        add_definitions(-DMATERIALX_BUILD_OSOS)
+    endif()
     if (MATERIALX_BUILD_GEN_MDL)
         add_definitions(-DMATERIALX_BUILD_GEN_MDL)
         add_subdirectory(source/MaterialXGenMdl)

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`.
+Variable and function names should use camelCase starting with a lowercase
+letter, as in `childName` or `getNode`. Protected and private member variables
+additionally require an underscore prefix, as in `_parent` or `_childMap`.
+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

documents/Specification/MaterialX.Specification.md

@@ -99,7 +99,7 @@ Because the same word can be used to mean slightly different things in different
 
 An **Element** is a named object within a MaterialX document, which may possess any number of child elements and attributes.  An **Attribute** is a named property of a MaterialX element.
 
-A **Node** is a function that generates or operates upon spatially-varying data.  This specification provides a set of standard nodes with precise definitions, and also supports the creation of custom nodes for application-specific uses.  The interface for a node’s incoming data is declared through **Inputs**, which may be spatially-varying or uniform, and **Tokens**, which are string values that can be substituted into filenames declared in node inputs.
+A **Node** is a function that generates or operates upon spatially-varying data.  This specification provides a set of standard nodes with precise definitions, and also supports the creation of custom nodes for application-specific uses.  The interface for a node’s incoming data is declared through **Inputs**, which may be spatially-varying or uniform, and **Tokens**, which are string values that can be substituted into filenames declared in node inputs.  The interface for a node's outgoing data is declared through one or more **Outputs**; a node's Inputs, Tokens and Outputs are collectively referred to as the node's **Ports**.
 
 A **Pattern** is a node that generates or processes simple scalar, vector, and color data, and has access to local properties of any geometry that has been bound.
 
@@ -937,7 +937,7 @@ Specific applications will commonly support sources and operators that do not ma
 
 ### Custom Node Declaration NodeDef Elements
 
-Each custom node must be explicitly declared with a <nodedef> element, with child <input>, <token> and <output> elements specifying the expected names and types of the node’s inputs and output(s).
+Each custom node must be explicitly declared with a <nodedef> element, with child <input>, <token> and <output> elements specifying the expected names and types of the node’s ports.
 
 Attributes for <nodedef> elements: