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
- USD collections always contain absolute paths. The file format plugin stores all collections on a single prim.
- 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.
- The shader discovery and parsing parts of the plugin record the information for nodedefs and implementations. 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.
- Variants are used both to support MaterialX variants and to select a look.
- USD leverages its composition features to implement several MaterialX features. 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.
- 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.
- Custom nodes can be defined either locally or in a shared library.
- Locally defined nodes need to have their associated nodedef/nodegraph either in the same mtlx file as the material, or included in the material mtlx file.
- Custom nodes defined in a shared library do not need to be included in the material mtlx file, but do need to be defined in a separate mtlx file such that the nodedef and material mtlx files are not siblings, and whose containing folder is indicated with the PXR_MTLX_PLUGIN_SEARCH_PATHS environment variable.
- Library defined custom nodes that use textures need to set the nodegroup on the nodedef to 'texture2d', and make sure the 'filename' typed input is exposed so renderers can recognize the texture references.
- Custom nodes with an output of type 'surfaceshader' that use textures also need to expose the 'filename' typed inputs, but can follow the MaterialX convention of using 'shader' as the nodegroup name.
- Nodegraphs with a 'surfaceshader' output can be defined locally, however custom nodes which are implemented using such a nodegraph need to have both the node and nodegraph defined in a shared library.
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.
- Shared library custom nodes are not fully supported. Library defined custom nodes that use textures or texture coordinates must use the primary texture coordinate name, which defaults to 'st' but can be altered by setting the USDMTLX_PRIMARY_UV_NAME environment variable.
- Locally defined custom nodes are not supported when the node is defined as a source code in a specific shading language (<implementation>) instead of a nodegraph.
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.
1.9.6