UsdMtlx : MaterialX File Format and Shader Plugins

Overview

This library provides the MaterialX file format, shader discovery and parsing plugin for USD, and currently has no user-level API.

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

• materialx namespace attribute. This attribute is ignored.
• 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.

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.