MaterialX

MaterialX is a collection of C++ libraries designed for managing complex shading and look development data. The ecosystem is divided into core data management, various shader generation backends, and language bindings:

Core Libraries

• MaterialXCore: Provides support for core MaterialX elements and graph traversal.
• MaterialXFormat: Handles XML serialization and provides file accessor utilities.

Shader Generation

MaterialX supports generating shading language code through several specialized libraries:

• MaterialXGenShader: The core shader generation support.
• MaterialXGenGlsl: Generates GLSL shading language code.
• MaterialXGenMdl: Generates MDL (Material Definition Language) code.
• MaterialXGenOsl: Generates OSL (Open Shading Language) code.

Bindings and Tools

• PyMaterialX: Python wrappers for the C++ modules.
• JsMaterialX: JavaScript bindings for the C++ modules.
• MaterialXView: The default material viewer application.
• MaterialXTest: A suite of unit tests for all MaterialX libraries.

MaterialX provides several standard data libraries that contain node declarations, graph definitions, and shader generator source code. These libraries are organized by functional purpose:

• Standard Pattern Library (stdlib): Contains core node definitions (stdlib_defs.mtlx) and nodegraph definitions (stdlib_ng.mtlx). It includes language-specific support for:
  • GLSL (genglsl)
  • OSL (genosl)
  • MDL (genmdl)
  • MSL (genmsl)
• Physically Based Shading Library (pbrlib): Provides PBR-specific node declarations and nodegraph definitions, including language-specific implementations for GLSL, OSL, MDL, and MSL.
• BxDF Graph Library (bxdf): Contains graph definitions for specific shading models, such as:
  • standard_surface.mtlx (Autodesk Standard Surface)
  • gltf_pbr.mtlx (glTF PBR)
  • usd_preview_surface.mtlx (UsdPreviewSurface)
  • lama (MaterialX Lama node set)
• Color Management Library (cmlib): Provides language-independent MaterialX graphs for common color space transforms (e.g., acescg, srgb_displayp3, rec709_display).

The Test Suite is used to validate MaterialX by parsing input documents to identify renderable elements. It performs two main types of validation:

1. ShaderGen tests: Uses appropriate shader generators to produce source code from MaterialX elements.
2. Render validation tests: Compiles and/or renders the generated code to verify correctness.

Folder Layout

• Library Groupings: Input files are primarily grouped by library, such as stdlib and pbrlib.
• Element Categories: Sub-folders group documents by element type (e.g., stdlib/math contains math-related .mtlx files like math.mtlx, trig.mtlx, etc.).
• Dependencies: The Geometry and Images folders provide the necessary stock assets used during testing.
• Utilities: The Utilities folder contains tools for rendering with testrender and light configuration specifications for hardware rendering.

Configuration

Execution options for Render tests are defined in the _options.mtlx file located at the top level of the test suite. This file can be edited locally to modify test behavior.

Operator nodes process input streams to form an output. The naming of input ports follows specific conventions based on the operator type:

1. Compositing Operators: Use fg (foreground) and bg (background) as input names. For float and color3 variants, an alpha port is also used. For the mix operator, use mix.
2. Single-input Operators: Use in if there is exactly one input.
3. Multi-input Operators: Use in1, in2, etc., if there is more than one input.

If an implementation does not support a specific operator, it should generally pass through the bg, in, or in1 input unchanged.

  <multiply name="n7" type="color3">
    <input name="in1" type="color3" nodename="n5"/>
    <input name="in2" type="float" value="2.0"/>
  </multiply>
  <over name="n11" type="color4">
    <input name="fg" type="color4" nodename="n8"/>
    <input name="bg" type="color4" nodename="inbg"/>
  </over>
  <add name="n2" type="color3">
    <input name="in1" type="color3" nodename="n12"/>
    <input name="in2" type="color3" nodename="img4"/>
  </add>

The Chiang hair model describes scattering from a hair fiber modeled as a rough dielectric cylinder with tilted cuticle scales. It is implemented via the <chiang_hair_bsdf> node.

Input Parameters

• ior: The index of refraction ($\eta$).
• absorption_coefficient: The absorption coefficient ($\sigma_a$).
• cuticle_angle: The cuticle angle ($\alpha$), remapped from the input range $[0, 1]$ to $[-\pi/2, \pi/2]$.
• roughness_R: Longitudinal variance $v$ for the R lobe.
• roughness_TT: Longitudinal variance $v$ for the TT lobe.
• roughness_TRT: Longitudinal variance $v$ for the TRT lobe.
• roughness_R (azimuthal): Azimuthal logistic scale $s$ for the R lobe.
• roughness_TT (azimuthal): Azimuthal logistic scale $s$ for the TT lobe.
• roughness_TRT (azimuthal): Azimuthal logistic scale $s$ for the TRT lobe.

Scattering Lobes

The model defines several lobes with different scattering behaviors:

• R (Reflection): Primary specular reflection.
• TT (Transmission-Transmission): Light passing through the fiber.
• TRT (Transmission-Reflection-Transmission): Light reflecting off the internal back surface.
• TRRT+: An additional lobe used for complex scattering, which features uniform azimuthal scattering ($N_{TRRT+} = 1/(2\pi)$).