Skip to content

Latest commit

 

History

History

Specification

README.md

MaterialX is an open standard for representing rich material and look-development content in computer graphics, enabling its platform-independent description and exchange across applications and renderers. MaterialX addresses the need for a common, open standard to represent the data values and relationships required to describe the look of a computer graphics model, including shading networks, patterns and texturing, complex nested materials and geometric assignments. To further encourage interchangeable CG look setups, MaterialX also defines a large set of standard shading and processing nodes with a precise mechanism for functional extensibility.

The documents in this folder comprise the complete MaterialX Specification, version 1.39.

MaterialX v1.39 provides the following enhancements over v1.38:

MaterialX Geometry Extensions

The parts of the main MaterialX Specification document dealing with various Geometry-related features has now been split into a separate MaterialX Geometry Extensions document, describing Collections, Geometry Name Expressions, geometry-related data types, Geometry Info elements and the GeomProp and Token elements used within them, and Look, Property, Visibility and assignment elements.

With this split, applications can claim to be MaterialX Compatible if they support all the things described in the main Specification, e.g. the elements for nodegraph shading networks and materials as well as the standard set of nodes, while using an application's native mechanisms or something like USD to describe the assignment of these materials to geometry. Applications may additionally support the MaterialX Geometry Extensions and thus use a single unified representation for complete CG objecct looks.

New Support for Shader AOVs

Previously, MaterialX used custom types with a structure of output variables to define shader AOVs. But this approach was not very flexible and in fact had not been implemented. In v1.39, nodegraph-based shader implementations can include new <aovoutput> elements to define AOVs which renderers can use to output additional channels of information in addition to the final shading result, while file-based <implementation>s can similarly define AOVs using <aov> elements.

Array Types Now Uniform and Static Length

Many shading languages do not support dynamic array types with a variable length, so MaterialX now only supports arrays with a fixed maximum length, and all array-type node inputs must be uniform; nodes are no longer permitted to output an array type. Array-type inputs may be accompanied by a uniform integer input declaring the number of array elements actually used in the array (the <curveadjust> node has been updated in this way). Because of this change, the unimplemented <arrayappend> node has been removed.

Connectable Uniform Inputs and New Tokenvalue Node

A uniform node input is now explicitly allowed to be connected to the output of a <constant> node. This makes it possible to define a uniform value and use it in multiple places in a nodegraph.

Similarly, <token>s in materials and other node instances may now be connected to the output of a new <tokenvalue> node: this is essentially a <constant> node but which connects to <token>s rather than <input>s.

Standardized Color Space Names

The standard colorspace names in MaterialX have now been defined explicitly in the Specification, and are aligned to their definitions in the ACES 1.2 OCIO config file. With this change, there is no need for a definition of "cms" or "cmsconfig" in MaterialX documents, so those two attributes have been deprecated. Additionally, two new colorspaces, "srgb_displayp3" and "lin_displayp3" have been added as standard colorspaces.

Disambiguated Nodedef and Nodegraph References

Normally, the set of provided inputs to a node and their types in conjunction with the output type of the node itself is sufficient to disambiguate exactly which nodedef signature should be applied. In the rare situations where this is not sufficient, it is now permissible for any node instantiation to specify the name of a nodedef to completely disambiguate the intended node signature.

Additionally, a <nodegraph> could previously declare itself to be an implementation of a particular <nodedef> by providing a "nodedef" attribute, which is still the preferred method for making this association. Now, it is also permissible for an <implementation> element to provide a "nodegraph" attribute to declare that nodegraph to be the implementation for the nodedef specified in the <implementation>. This allows a single nodegraph to be the implementation of multiple nodedefs, e.g. two different node names with the same underlying implementation, or if the only difference between two versions of a nodedef is the default values.

Generalized Swizzle Operator Removed

The standard <swizzle> node using a string of channel names and allowing arbitrary channel reordering is very inefficient (and in some shading languages virtually impossible) to implement as previously specified, and as such has been removed. Nodegraphs should instead use combinations of <extract> (which is now a standard node), <separateN> and <combineN> nodes to perform arbitrary channel reordering. Additionally, the previous "channels" attribute for inputs which allowed arbitrary channel reordering and used string "swizzle" channel naming has been removed.

New Unlit Surface Shader and Standard Materials

A new <surface_unlit> node for unlit surfaces has been added to the standard library.

Additionally, the standard <surfacematerial> material now supports both single- or double-sided surfaces with the addition of a separate backsurface input.

Inheritance and Hints for Typedefs

Typedefs may now inherit from other types, including built-in types, and may provide hints about their values such as floating-point precision. These new "inherit" and "hint" attributes are themselves merely metadata hints about the types; applications and code generators are still expected to provide their own precise definitions for all custom types.

New and Updated Standard Library Nodes

In 1.39, we are removing the distinction between "standard nodes" and "supplemental nodes", and descriptions of both can now be found in the main Specification document. Nodes that are implemented in the standard distribution using nodegraphs are annotated with "(NG)" in the Spec to differentiate them from nodes implemented in each rendering target's native shading language.

Additionally, the following new operator nodes have been added to the standard library:

  • Procedural nodes: tokenvalue, checkerboard, fractal2d, cellnoise1d, unifiednoise2d, unifiednoise3d
  • Geometric nodes: bump, geompropvalueuniform
  • Math nodes: boolean and, or, not; distance, transformcolor, creatematrix and triplanarblend, as well as integer-output variants of floor and ceil
  • Adjustment nodes: curveinversecubic, curveuniformlinear, curveuniformcubic and colorcorrect
  • Conditional nodes: boolean-output variants of ifgreater, ifgreatereq and ifequal; new ifelse node
  • Channel nodes: extractrowvector and separatecolor4

New Physically Based Shading Nodes

The following new standard physically based shading nodes have been added:

Other Changes

  • The "valuerange" and "valuecurve" attributes describing expressions and function curves have been removed, in favor of using the new <curveinversecubic> / <curveuniformcubic> / etc. nodes.
  • The <geomcolor>, <geompropvalue> and <geompropvalueuniform> nodes for color3/4-type values can now take a "colorspace" attribute to declare the colorspace of the property value.
  • The <cellnoise2d> and <cellnoise3d> nodes now support vectorN output types in addition to float output.
  • The <noise2d/3d>, <fractal2d/3d>, <cellnoise2d/3d> and <worleynoise2d/3d> nodes now support a "period" input.
  • The <worleynoise2d> and <worleynoise3d> nodes now support a number of different distance metrics.
  • The <time> node no longer has a "frames per second" input: the application is now always expected to generate the "current time in seconds" using an appropriate method. The "fps" input was removed because variable-rate real-time applications have no static "fps", and it's generally not good to bake a situation-dependent value like fps into a shading network.
  • A standard "tangent" space is now defined in addition to "model", "object" and "world" spaces, and the <heighttonormal> node now accepts a uniform "space" input to define the space of the output normal vector.
  • The <switch> node now supports 10 inputs instead of just 5.
  • The <surface> and <displacement> nodes are now part of the main Specification rather than being Physically Based Shading nodes.
  • <Token> elements are now explicitly allowed to be children of compound nodegraphs, and token values may now have defined enum/enumvalues.
  • Inputs in <nodedef>s may now supply "hints" to code generators as to their intended interpretation, e.g. "transparency" or "opacity".
  • <Attributedef> elements may now define enum/enumvalues to list acceptable values or labels/mapped values for an attribute.
  • If a string input specifies an "enum" list, the list is now considered a "strict" list of allowable values; no values are allowed outside that list. To make the input non-strict, one must omit the "enum" atribute from the input.

Suggestions for v1.39:

  • Add a boolean “bound” output to the various geometry property nodes, so materials can be flexible if a given attribute doesn’t exist. Especially ones like <texcoord> that don’t let users specify names.