Material Graph#

Overview#

Material Graph

The Material Graph allows for the authoring of custom material shade graphs. The graph is composed of shading nodes connected together and stored as UsdShade within the stage.

Attention

Starting with Material Graph version 1.8.8 Pause and Resume has been added.

Pause and Resume#

Material Graph Pause

The Pause(1) and Resume(2) buttons are a feature that allows you to temporarily halt the processing or rendering of your material in the Material Graph. When you click the Pause button, Omniverse USD Composer will pause the execution of the nodes in the node graph, effectively freezing the current state of the process. Here’s an explanation of how the Pause button works and its practical uses:

  • By clicking the Pause button, you can pause the execution of the material graph. This means that any ongoing computations, image processing, or rendering will be temporarily halted, freezing the state of the node graph at that moment. It allows you to take a break, without consuming additional system resources while you make changes to the graph. This is useful when assembling large or complex graphs without wanting to wait for the material to recompile. Once the graph is in a state for evaluation, unpause the graph, wait for the material to compile and view the results.

Nodes#

Provided with the Material Graph is a comprehensive list of MDL, BSDFs, and functions. Materials and functions are represented as drag-and-drop nodes in the Material Graph Node List.

Materials#

Materials Modifiers#

Texturing High Level#

Texturing Basic#

Math Functions#

Constants, State and Primvars#

Constructors, Conversions, and Swizzles#

Advanced#

UsdPreviewSurface#

Miscellaneous#

Custom User Nodes#

You can can add custom MDL nodes to the Material Editor by adding MDL modules to the “User Allow List” in the Material Preferences

Custom OmniImage Nodes

User Allow List#

To add MDL functions and Materials to the Material Editor node list, use the plus button to the right of the “User Allow List” list. Modules listed in the Allow list must also be included somewhere in the MDL Search Path.

Custom OmniImage Nodes

User Block List#

To exclude a module from the node list, add the module the “User Block List”. Use the plus button to the right of the “User Block List” and add the name of module you wish to exclude from the node list.

Material Config#

Adding MDL modules to the “Allow” and “Block” lists are specified in the material.config.toml in the $HOME/Documents/Kit/shared folder.

material.config.toml

[materialGraph]
userBlockList = [
    "OmniShared.mdl"
]
userAllowList = [
    "OmniImage.mdl"
]

Exporting Functions and Materials#

Functions and materials that are prefixed with export are made available to the editor and referenced in UsdShade using the sourceAsset and subIdentifier info attributes.

OmniImage.mdl

export base::projection_mode to_native_projection_mode(uniform projection_mode mode)
{ ... }

export float3 compute_latitude_longitude_projection(float3 pos, uniform float3 rotation)
{ ... }

export base::texture_return texture_lookup_2(
    uniform texture_2d texture = texture_2d(),
    uniform bool ignore_missing_texture = false,
    color missing_color = color(0.0),
    uniform bool use_uv_coords = false,
    float2 uv_coords = float2(0.0),
    uniform wrap_mode s_wrap = wrap_periodic,
    uniform wrap_mode t_wrap = wrap_periodic,
    base::texture_coordinate_info texture_coordinate_info = base::texture_coordinate_info())
{ ... }
Custom OmniImage Nodes

Note

New annotation support for Kit versions 106.0.0 and higher

  • Struct Unrolling

    anno::node_output_port_default( node port value )

    Material Graph nodes support multiple outputs from MDL Functions. MDL Material Graph nodes can use the new MDL 1.8 annotation node_output_port_default and node_port_mode to control how single value struct returns from MDL function integrate with multiple output ports in the Material Editor.

    When the annotations are applied to a compound return type of a MDL function or user-defined struct, the Material Editor can output either:

    • The single value of the return as an output port called out.

    • Each field of the compound is returned as an output port called by its field name.

    • Both the compound single value of the return as an output port called out, and each field of the compound is returned as an output port called by its field name.

    For more details please refer to MDL Specification 1.9, page 108

Example MDL code for struct unrolling
mdl 1.8;
import ::anno::*;

export struct TestStruct
{
      int i = 1;
      float f = 0.2;
};

export TestStruct
[[

      anno::node_output_port_default(anno::node_port_value_only)
]]
test_annotation_struct_value_and_fields
(
      TestStruct pStruct = TestStruct()
)
{
      return pStruct;
}

export TestStruct
[[
      anno::node_output_port_default(anno::node_port_fields_only)
]]
test_annotation_struct_fields_only
(
      TestStruct pStruct = TestStruct()
)
{
      return pStruct;
}

export TestStruct
[[

      anno::node_output_port_default(anno::node_port_value_and_fields)
]]
test_annotation_struct_value_only
(
      TestStruct pStruct = TestStruct()
)
{
      return pStruct;
}

The image below shows how this will appear in the material graph.

Struct Unrolling


On this page