Merge branch 'AcademySoftwareFoundation:main' into projection_definitions

Author: kwokcb

.github/workflows/main.yml

@@ -25,17 +25,17 @@ jobs:
           python: 3.9
           cmake_config: -DMATERIALX_BUILD_SHARED_LIBS=ON -DMATERIALX_BUILD_MONOLITHIC=ON
 
-        - name: Linux_GCC_14_Python312
+        - name: Linux_GCC_14_Python39
           os: ubuntu-24.04
           compiler: gcc
           compiler_version: "14"
-          python: 3.12
+          python: 3.9
 
-        - name: Linux_GCC_14_Python313
+        - name: Linux_GCC_14_Python311
           os: ubuntu-24.04
           compiler: gcc
           compiler_version: "14"
-          python: 3.13
+          python: 3.11
           test_render: ON
 
         - name: Linux_GCC_CoverageAnalysis
@@ -53,32 +53,32 @@ jobs:
           python: 3.9
           cmake_config: -DMATERIALX_BUILD_SHARED_LIBS=ON
 
-        - name: Linux_Clang_18_Python313
+        - name: Linux_Clang_18_Python311
           os: ubuntu-24.04
           compiler: clang
           compiler_version: "18"
-          python: 3.13
+          python: 3.11
           clang_format: ON
 
-        - name: MacOS_Xcode_15_Python311
+        - name: MacOS_Xcode_15_Python39
           os: macos-14
           compiler: xcode
           compiler_version: "15.4"
           cmake_config: -DMATERIALX_BUILD_SHARED_LIBS=ON
-          python: 3.11
+          python: 3.9
 
-        - name: MacOS_Xcode_15_Python312
+        - name: MacOS_Xcode_15_Python311
           os: macos-15
           compiler: xcode
           compiler_version: "15.4"
-          python: 3.12
+          python: 3.11
           test_shaders: ON
 
-        - name: MacOS_Xcode_16_Python313
+        - name: MacOS_Xcode_16_Python311
           os: macos-15
           compiler: xcode
           compiler_version: "16.1"
-          python: 3.13
+          python: 3.11
           static_analysis: ON
           cmake_config: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
 
@@ -103,10 +103,10 @@ jobs:
           python: 3.9
           cmake_config: -G "Visual Studio 16 2019" -A "Win32"
 
-        - name: Windows_VS2022_x64_Python313
+        - name: Windows_VS2022_x64_Python311
           os: windows-2025
           architecture: x64
-          python: 3.13
+          python: 3.11
           cmake_config: -G "Visual Studio 17 2022" -A "x64"
           test_shaders: ON
 

CMakeLists.txt

@@ -4,7 +4,7 @@ set(MATERIALX_MINOR_VERSION 39)
 set(MATERIALX_BUILD_VERSION 4)
 set(MATERIALX_LIBRARY_VERSION ${MATERIALX_MAJOR_VERSION}.${MATERIALX_MINOR_VERSION}.${MATERIALX_BUILD_VERSION})
 
-# Cmake setup
+# CMake setup
 cmake_minimum_required(VERSION 3.26)
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_POSITION_INDEPENDENT_CODE TRUE)
@@ -61,10 +61,10 @@ option(MATERIALX_WARNINGS_AS_ERRORS "Interpret all compiler warnings as errors."
 option(MATERIALX_COVERAGE_ANALYSIS "Build MaterialX libraries with coverage analysis on supporting platforms." OFF)
 option(MATERIALX_DYNAMIC_ANALYSIS "Build MaterialX libraries with dynamic analysis on supporting platforms." OFF)
 
-option(MATERIALX_BUILD_IOS "Build MaterialX for iOS. (Deprecated. Set CMAKE_SYSTEM_NAME instead)" OFF)
+option(MATERIALX_BUILD_IOS "Build MaterialX for iOS. (Deprecated. Set CMAKE_SYSTEM_NAME to iOS instead.)" OFF)
 option(MATERIALX_BUILD_APPLE_FRAMEWORK "Build MaterialX as an Apple Framework" ${__build_apple_framework})
 if (MATERIALX_BUILD_IOS)
-    MESSAGE(WARNING "The MATERIALX_BUILD_IOS is deprecated. Set the CMAKE_SYSTEM_NAME to the platform instead")
+    message(DEPRECATION "The MATERIALX_BUILD_IOS option is deprecated. Set CMAKE_SYSTEM_NAME to iOS instead.")
     set(CMAKE_SYSTEM_NAME iOS)
 endif()
 
@@ -107,8 +107,8 @@ if (MATERIALX_BUILD_JS)
     set(MATERIALX_BUILD_TESTS OFF)
 endif()
 
+# All hardware shading languages currently depend on the GLSL shader generator.
 if(MATERIALX_BUILD_GEN_MSL)
-    # All hardware shading languages currently depend on the GLSL shader generator.
     set(MATERIALX_BUILD_GEN_GLSL ON)
 endif()
 
@@ -156,7 +156,7 @@ message(STATUS "Setting namespace to '${MATERIALX_NAMESPACE}'")
 # Library name custom suffix
 # This helps an application that needs to ship a dynamic library MaterialX ensure
 # that it has a unique name that won't conflict with one elsewhere on the system.
-set (MATERIALX_LIBNAME_SUFFIX "" CACHE STRING "Specify a suffix to all libraries that are built")
+set(MATERIALX_LIBNAME_SUFFIX "" CACHE STRING "Specify a suffix to all libraries that are built")
 
 mark_as_advanced(MATERIALX_BUILD_DOCS)
 mark_as_advanced(MATERIALX_BUILD_GEN_GLSL)
@@ -211,21 +211,18 @@ if (MATERIALX_BUILD_USE_CCACHE)
     endif()
 endif()
 
-# Attempt to configure OSL testing if it can be found by cmake.
-# This will not override any explicitly provided oslc and testrender
+# 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)
-    # We currently only need the actual OSL binaries if we're running tests with Render and GenOSL enabled.
     find_package(OSL QUIET)
     if(OSL_FOUND)
         if(NOT MATERIALX_OSL_BINARY_OSLC)
             set(MATERIALX_OSL_BINARY_OSLC $<TARGET_FILE:OSL::oslc>)
         endif()
         if(NOT MATERIALX_OSL_BINARY_TESTRENDER)
-            # currently OSL does not export a cmake target for testrender, but once that's added this can be simplified.
+            # OSL does not yet export a CMake target for testrender.
             set(MATERIALX_OSL_BINARY_TESTRENDER $<TARGET_FILE_DIR:OSL::oslc>/testrender)
         endif()
-        # NOTE : we do not derive a value for MATERIALX_OSL_INCLUDE_PATH here, as a a cmake installed OSL package
-        # should have the shader includes in the expected location.
     endif()
 endif()
 
@@ -327,20 +324,20 @@ function(mx_add_library MATERIALX_MODULE_NAME)
     set(options ADD_OBJECTIVE_C_CODE)
     set(oneValueArgs EXPORT_DEFINE)
     set(multiValueArgs
-            SOURCE_FILES
-            HEADER_FILES
-            INLINED_FILES
-            MTLX_MODULES)
+        SOURCE_FILES
+        HEADER_FILES
+        INLINED_FILES
+        MTLX_MODULES)
     cmake_parse_arguments(args
-            "${options}"
-            "${oneValueArgs}"
-            "${multiValueArgs}"
-            ${ARGN})
+        "${options}"
+        "${oneValueArgs}"
+        "${multiValueArgs}"
+        ${ARGN})
 
     if (APPLE AND args_ADD_OBJECTIVE_C_CODE)
         file(GLOB_RECURSE materialx_source_oc "${CMAKE_CURRENT_SOURCE_DIR}/*.m*")
         set_source_files_properties(${materialx_source_oc} PROPERTIES
-                COMPILE_FLAGS "-x objective-c++")
+            COMPILE_FLAGS "-x objective-c++")
         set(args_SOURCE_FILES ${args_SOURCE_FILES} ${materialx_source_oc})
     endif()
 
@@ -360,30 +357,29 @@ function(mx_add_library MATERIALX_MODULE_NAME)
 
         target_link_libraries(${TARGET_NAME}
             PUBLIC
-                ${args_MTLX_MODULES}
-                ${CMAKE_DL_LIBS})
+            ${args_MTLX_MODULES}
+            ${CMAKE_DL_LIBS})
 
         target_include_directories(${TARGET_NAME}
-                PUBLIC
-                $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../>
-                $<INSTALL_INTERFACE:${MATERIALX_INSTALL_INCLUDE_PATH}>
-                PRIVATE
-                ${EXTERNAL_INCLUDE_DIRS})
+            PUBLIC
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../>
+            $<INSTALL_INTERFACE:${MATERIALX_INSTALL_INCLUDE_PATH}>
+            PRIVATE
+            ${EXTERNAL_INCLUDE_DIRS})
 
         set_target_properties(
-                ${TARGET_NAME} PROPERTIES
-                OUTPUT_NAME ${MATERIALX_MODULE_NAME}${MATERIALX_LIBNAME_SUFFIX}
-                COMPILE_FLAGS "${EXTERNAL_COMPILE_FLAGS}"
-                LINK_FLAGS "${EXTERNAL_LINK_FLAGS}"
-                INSTALL_RPATH "${MATERIALX_SAME_DIR_RPATH}"
-                VERSION "${MATERIALX_LIBRARY_VERSION}"
-                SOVERSION "${MATERIALX_MAJOR_VERSION}")
+            ${TARGET_NAME} PROPERTIES
+            OUTPUT_NAME ${MATERIALX_MODULE_NAME}${MATERIALX_LIBNAME_SUFFIX}
+            COMPILE_FLAGS "${EXTERNAL_COMPILE_FLAGS}"
+            LINK_FLAGS "${EXTERNAL_LINK_FLAGS}"
+            INSTALL_RPATH "${MATERIALX_SAME_DIR_RPATH}"
+            VERSION "${MATERIALX_LIBRARY_VERSION}"
+            SOVERSION "${MATERIALX_MAJOR_VERSION}")
     else()
         set(TARGET_NAME ${MATERIALX_MONOLITHIC_TARGET})
-
         add_library(${MATERIALX_MODULE_NAME} ALIAS ${MATERIALX_MONOLITHIC_TARGET})
 
-        # Store the aliased MaterialX modules name to create cmake export aliases later.
+        # Store the aliased MaterialX modules name to create CMake export aliases later.
         set_property(GLOBAL APPEND PROPERTY MATERIALX_MODULES ${MATERIALX_MODULE_NAME})
     endif()
 
@@ -406,7 +402,7 @@ function(mx_add_library MATERIALX_MODULE_NAME)
                 ${args_INLINED_FILES})
 
     target_include_directories(${TARGET_NAME} PUBLIC
-            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../>)
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../>)
 
     target_compile_definitions(${TARGET_NAME} PRIVATE "-D${args_EXPORT_DEFINE}")
 
@@ -424,11 +420,11 @@ function(mx_add_library MATERIALX_MODULE_NAME)
                 DESTINATION "${MATERIALX_INSTALL_LIB_PATH}/" OPTIONAL)
     endif()
 
-    # pass TARGET_NAME back to call site - so caller can modify the build target
+    # Pass TARGET_NAME back to call site, so the caller can modify the build target.
     set(TARGET_NAME ${TARGET_NAME} PARENT_SCOPE)
 endfunction()
 
-# Propagate shared library setting to NanoGUI:
+# Propagate shared library setting to NanoGUI
 if(MATERIALX_BUILD_SHARED_LIBS)
     set(BUILD_SHARED_LIBS "ON")
 else()
@@ -517,7 +513,7 @@ if(MATERIALX_BUILD_JS)
     add_subdirectory(source/JsMaterialX)
 endif()
 
-if (MATERIALX_BUILD_MONOLITHIC)
+if(MATERIALX_BUILD_MONOLITHIC)
     # MaterialX monolithic build target needs to be installed after any other included
     # modules to ensure the correct files are in mxHeaders
     if(NOT SKBUILD)
@@ -552,6 +548,7 @@ if (MATERIALX_BUILD_MONOLITHIC)
     endif()
 endif()
 
+# Set Visual Studio startup projects
 if(MATERIALX_BUILD_VIEWER)
     set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT MaterialXView)
 elseif(MATERIALX_BUILD_GRAPH_EDITOR)
@@ -562,16 +559,15 @@ endif()
 
 # Install root-level documents
 if(NOT SKBUILD)
-    install(FILES LICENSE CHANGELOG.md README.md THIRD-PARTY.md
-            DESTINATION .)
+    install(FILES LICENSE CHANGELOG.md README.md THIRD-PARTY.md DESTINATION .)
 
     set(MATERIALX_GEN_CONFIG_PATH "${MATERIALX_INSTALL_LIB_PATH}/cmake/${CMAKE_PROJECT_NAME}")
 
     include(CMakePackageConfigHelpers)
 
     if (MATERIALX_BUILD_MONOLITHIC)
-        # export aliases for the MaterialX modules built in this monolithic build to be
-        # less disruptive to downstream probjects.
+        # Export aliases for the MaterialX modules built in this monolithic build
+        # to be less disruptive to downstream projects.
         get_property(MATERIALX_MODULES GLOBAL PROPERTY MATERIALX_MODULES)
         set(EXPORT_ALIASES "# Aliased targets for the the monolithic build\n")
         foreach (MODULE ${MATERIALX_MODULES})
@@ -584,19 +580,17 @@ if(NOT SKBUILD)
     endif()
 
     configure_package_config_file(cmake/modules/MaterialXConfig.cmake.in
-                                ${PROJECT_BINARY_DIR}/cmake/${CMAKE_PROJECT_NAME}Config.cmake
-                                INSTALL_DESTINATION "${MATERIALX_GEN_CONFIG_PATH}"
-                                PATH_VARS CMAKE_INSTALL_PREFIX CMAKE_PROJECT_NAME)
+                                  ${PROJECT_BINARY_DIR}/cmake/${CMAKE_PROJECT_NAME}Config.cmake
+                                  INSTALL_DESTINATION "${MATERIALX_GEN_CONFIG_PATH}"
+                                  PATH_VARS CMAKE_INSTALL_PREFIX CMAKE_PROJECT_NAME)
     write_basic_package_version_file(${PROJECT_BINARY_DIR}/cmake/${CMAKE_PROJECT_NAME}ConfigVersion.cmake
-                                    VERSION ${MATERIALX_LIBRARY_VERSION}
-                                    COMPATIBILITY AnyNewerVersion)
-
-    # Install the auto-generated CMake configuration files:
+                                     VERSION ${MATERIALX_LIBRARY_VERSION}
+                                     COMPATIBILITY AnyNewerVersion)
 
+    # Install auto-generated CMake configuration files
     install(EXPORT MaterialX
             DESTINATION "${MATERIALX_GEN_CONFIG_PATH}"
             FILE ${CMAKE_PROJECT_NAME}Targets.cmake)
-
     install(FILES "${PROJECT_BINARY_DIR}/cmake/${CMAKE_PROJECT_NAME}ConfigVersion.cmake"
             "${PROJECT_BINARY_DIR}/cmake/${CMAKE_PROJECT_NAME}Config.cmake"
             DESTINATION "${MATERIALX_GEN_CONFIG_PATH}")

README.md

@@ -79,7 +79,7 @@ The following packages contain pre-built binaries for the latest release, includ
 
 ## Additional Resources
 
-- The [Developer Guide](http://www.materialx.org/docs/api/index.html) contains a developer-oriented overview of MaterialX with API documentation.
+- The [Developer Guide](http://www.materialx.org/docs/api/index.html) contains a developer-oriented overview of MaterialX with Build and API documentation.
 - The [Python Scripts](python/Scripts) folder contains standalone examples of MaterialX Python code.
 - The [JavaScript](javascript) folder contains details on building JavaScript bindings for MaterialX.
 - Presentations at [ASWF Open Source Days](https://materialx.org/assets/ASWF_OSD2024_MaterialX_Final.pdf) and the [SIGGRAPH Physically Based Shading Course](https://blog.selfshadow.com/publications/s2020-shading-course/#materialx) provide details on the roadmap for MaterialX development.

documents/DeveloperGuide/MainPage.md

@@ -20,6 +20,8 @@ The MaterialX codebase requires a compiler with support for C++17, and can be bu
 
 The Python bindings for MaterialX are based on [PyBind11](https://github.com/pybind/pybind11), and support Python versions 3.9 and greater.
 
+On macOS, you'll need to [install Xcode](https://developer.apple.com/xcode/resources/), in order to get access to the Metal Tools as well as compiler toolchains.
+
 ## Building MaterialX
 
 ### Building MaterialX C++
@@ -52,6 +54,29 @@ Select the `MATERIALX_BUILD_VIEWER` option to build the MaterialX Viewer.  Insta
 
 To generate HTML documentation for the MaterialX C++ API, make sure a version of [Doxygen](https://www.doxygen.org/) is on your path, and select the advanced option `MATERIALX_BUILD_DOCS` in CMake.  This option will add a target named `MaterialXDocs` to your project, which can be built as an independent step from your development environment.
 
+## Editor Setup
+
+MaterialX should work in any editor that supports CMake, or that CMake can generate a project for.
+Some common Editors are listed here to help developers get started.
+
+### CLion
+
+[CLion](https://www.jetbrains.com/clion/) is a cross-platform IDE that can be used to develop MaterialX.
+Additionally, it includes CMake and is free for non-commercial Use.
+
+To get started with CLion, open the MaterialX repository directly, and it will load the CMake project for you.
+If you want to enable features like Python, go to `Settings -> Build, Execution and Deployment -> CMake` and configure
+the CMake Options, for example:
+
+```
+-DMATERIALX_BUILD_PYTHON=ON
+-DMATERIALX_BUILD_VIEWER=ON
+-DMATERIALX_BUILD_GRAPH_EDITOR=ON
+```
+
+To build, either select `Build -> Build Project` or select a specific configuration to build.
+To install, select `Build -> Install`
+
 ## Installing MaterialX
 
 Building the `install` target of your project will install the MaterialX C++ and Python libraries to the folder specified by the `CMAKE_INSTALL_PREFIX` setting, and will install MaterialX Python as a third-party library in your Python environment.  Installation of MaterialX Python as a third-party library can be disabled by setting `MATERIALX_INSTALL_PYTHON` to `OFF`.

libraries/README.md

@@ -75,3 +75,4 @@ This folder contains the standard data libraries for MaterialX, providing declar
     - point, directional, spot
 - Shader generation does not currently support:
     - `displacementshader` and `volumeshader` nodes for hardware shading targets (GLSL, MSL).
+    - `hextiledimage` and `hextilednormalmap` for OSL and MDL.

libraries/bxdf/translation/standard_surface_to_usd.mtlx

@@ -49,7 +49,7 @@
       <input name="in1" type="color3" interfacename="base_color" />
       <input name="in2" type="float" interfacename="base" />
     </multiply>
-    <mix name="albedoOpaqueDielectric" type="color3">
+    <mix name="baseSubsurfaceColor" type="color3">
       <input name="fg" type="color3" interfacename="subsurface_color" />
       <input name="bg" type="color3" nodename="scaledBaseColor" />
       <input name="mix" type="float" interfacename="subsurface" />
@@ -60,7 +60,7 @@
       <input name="mix" type="float" interfacename="coat" />
     </mix>
     <multiply name="diffuseColor" type="color3">
-      <input name="in1" type="color3" nodename="albedoOpaqueDielectric" />
+      <input name="in1" type="color3" nodename="baseSubsurfaceColor" />
       <input name="in2" type="color3" nodename="coatAttenuation" />
     </multiply>
     <dot name="roughness" type="float">
@@ -71,12 +71,12 @@
     </dot>
 
     <!-- Clearcoat -->
-    <multiply name="coatColor" type="color3">
+    <multiply name="scaledCoatColor" type="color3">
       <input name="in1" type="color3" interfacename="coat_color" />
       <input name="in2" type="float" interfacename="coat" />
     </multiply>
     <convert name="coatColorVector" type="vector3">
-      <input name="in" type="color3" nodename="coatColor" />
+      <input name="in" type="color3" nodename="scaledCoatColor" />
     </convert>
     <dotproduct name="clearcoat" type="float">
       <input name="in1" type="vector3" nodename="coatColorVector" />