UsdMtlx : MaterialX File Format and Shader Plugins

Overview

This library provides the MaterialX file format, shader discovery and parsing plugin for USD. It also provides utility functions for reading and interacting with MaterialX documents.

Concept Mappings

MaterialX USD Notes
parameter UsdShadeInput Connectability is interfaceOnly
input UsdShadeInput .
output UsdShadeOutput A default output is named "out"
material UsdShadeMaterial .
nodegraph UsdShadeNodeGraph .
collection UsdCollectionAPI See below
geom UsdCollectionAPI See below
node UsdShadeShader .
nodedef UsdShadeShader See below
implementation SdrShaderNode .
materialassign UsdShadeMaterialBindingAPI .
variant USD variant .
variantset USD variantset .
variantassign USD variant selection See below
bindparam & bindinput USD composition See below
look USD prim See below
  1. USD collections always contain absolute paths. The file format plugin stores all collections on a single prim.
  2. USD material bindings require a UsdCollectionAPI so geom expressions are converted to and stored with collections. geomprefix is applied at the time of conversion so the prefix is baked in. Equal collections share the same UsdCollectionAPI.
  3. The shader discovery and parsing parts of the plugin record the information for nodedefs and implementations. (nodegraphs used to implement nodedefs aren't currently supported.) However, the nodedef is also translated by the file format. This is so naive clients that don't look up the registered shader node will still see the attributes of a shader and so USD's composition can use the nodedef value's as fallbacks.
  4. Variants are used both to support MaterialX variants and to select a look.
  5. USD leverages its composition features to implement several MaterialX features. Parameters and inputs are bound simply by setting opinions on Material prims, which are stronger than the opinions on the shaders. Look inherits use references and material inherits use specializes. nodedef inherits are handled during conversion and don't map to USD composition.
  6. MaterialX looks become variants on a single USD prim. The expectation is that this prim will be referenced by various prims that will also set a variant selection to choose the desired look. XXX – How collection paths get mapped is still undecided.
  7. Materialx bindtoken statements result in USD primvars added to the Material being defined, as we expect future USD support for image filename token substitutions to be primvar-based.

Unsupported MaterialX Features

  • Geometry Name Expressions are not supported. USD cannot yet represent path expressions. Paths that require glob-like pattern matching are discarded with a warning.
  • light context shader types. USD doesn't have support for light types on materials; instead, USD encodes lights as object schemas, in UsdLux.
  • Custom type members. The file format plugin currently doesn't handle structures except as blind data. Consequently it ignores member attributes.
  • geominfo, geompropdef, and geomprop elements. These elements are ignored. The file format plugin currently doesn't attempt to bind looks to geometry.
  • geomname value type. These are treated as strings but such values are never used. The file format plugin currently doesn't attempt to bind looks to geometry.
  • property, propertyset, propertyassign and propertysetassign elements. These elements are ignored. The file format plugin currently doesn't attempt to bind looks to geometry, and in USD, properties like twosided are expressed directly on gprims in the geometry schemas.
  • visibility elements. These elements are ignored. The file format plugin currently doesn't attempt to bind looks to geometry. "Inheriting visibility" is part of the geometry schema in USD, and more specialized/contextualized visibility is expressed through lighting and rendering schemas using USD Collections, e.g. light illumination and shadowing.
  • fileprefix. This attribute is ignored.
  • Image filename substitutions. USD as yet has no support for these kind of substitutions beyond the <UDIM> token, though we do plan to add more generalized token substitutions.
  • width, height, bitdepth output attributes. These attributes are ignored.
  • disable parameter. If this exists it will be converted as expected but MaterialX considers it implicit and the file format plugin will not create it automatically. In addition it has no special meaning to USD. In particular, it does not disable the UsdShadeShader prim.
  • enumvalues attribute. This attribute is ignored.. USD has no corresponding concept. enum is handled correctly.
  • uimin and uimax attributes. These attributes are ignored. USD has no corresponding concept.
  • attributedef elements. These elements are ignored. This is technically not unsupported since support is optional and only meaningful for applications that need it, which USD does not.
  • interfacename attributes are not supported
  • UsdMtlx expects additional nodes, other than the material and surface shader nodes, to be contained inside a nodegraph. These additional nodes will be lost when translating into UsdShade, if not contained in a nodegraph.
  • Custom nodedefs are not fully supported. They currently work when the custom node is directly providing the output of a nodegraph and not passed to downstream nodes. The nodedef needs to be defined in a separate mtlx file that is included in the material mtlx file, and the filepath should be locatable by the PXR_MTLX_PLUGIN_SEARCH_PATHS environment variable. Note that the nodedef and material mtlx files should not be siblings.

Note that the file format plugin uses the MaterialX XML reader so it can read any valid MaterialX file, even it contains features not supported by the file format plugin. Those features will be ignored or incompletely handled.