MaterialX: Proposed Additions and Changes

Proposals for Version 1.39
September 15, 2024

Introduction

The MaterialX Specification has historically included descriptions of not just current functionality, but also forward-looking proposed functionality intended for eventual implementation. We believe it will be beneficial to provide clarity on which functionality is currently supported in the library, and which sections document proposed additions.

As such, those forward-looking proposals have been moved from the formal Specification documents into this Proposed Additions and Changes document to be discussed and debated. These descriptions can then be migrated into the appropriate formal Specification document once actually implemented in the code base. New proposals for changes and additions to MaterialX may be added to this document once a generally favorable consensus from the community is reached.

Introduction

Proposals: General

Proposals: Elements

Proposals: Stdlib Nodes

Proposals: PBR Nodes

Proposals: NPR Nodes

Proposals: General

Color Spaces

When the OCIO NanoColor library (provide link) becomes available, MaterialX should support the official colorspace names in that spec, with the current MaterialX colorspace names supported as aliases.

MaterialX should also support the following color spaces:

lin_rec2020
g22_rec2020

Proposals: Elements

AOV Output Elements

(Summary for README.md: 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. )

A functional nodegraph with either a "shader" or "material"-semantic output type may contain a number of <aovoutput> elements to declare arbitrary output variables ("AOVs") which the renderer can see and output as additional streams of information. AOVoutputs must be of type float, color3 or vector3 for pre-shading "pattern" values, or BSDF or EDF for shader-node output values; the renderer is expected to extract the appropriate color-like information from BSDF and EDF types. AOVs defined within a shader-semantic node instantiated within this functional nodegraph may be "passed along" and potentially renamed (but may not be modified or operated on in any way) by providing a sourceaov attribute in the <aovoutput>.

  <aovoutput name="name" type="type" aovname="aovname"
             nodename="node_to_connect_to" [sourceaov="aovname"]/>

The attributes for <aovoutput> elements are:

name (string, required): a user-chosen name for this aov output definition element.
type (string, required): the type of the AOV, which must be one of the supported types listed above.
aovname (string, required): the name that the renderer should use for the AOV.
nodename (string, required): the name of the node whose output defines the AOV value.
sourceaov (string, optional): If nodename is a surfaceshader type, the name of the output AOV defined within nodename to pass along as the output AOV. The type of the sourceaov defined within nodename must match the <aovoutput> type.

Examples:

  <aovoutput name="Aalbedo" type="color3" aovname="albedo"
             nodename="coat_affected_diffuse_color"/>
  <aovoutput name="Adiffuse" type="BSDF" aovname="diffuse">
             nodename="diffuse_bsdf"/>

AovOutput Example

Example of using <aovoutput> with sourceaov to forward AOVs from within an instantiation of a shader-semantic node; this assumes that <standard_surface> has itself defined <aovoutput>s for "diffuse" and "specular" AOVs:

  <nodegraph name="NG_basic_surface_srfshader" nodedef="ND_basic_surface_srfshader">
    <image name="i_diff1" type="color3">
      <input name="file" type="filename"
                 value="txt/[diff_map_effect]/[diff_map_effect].<UDIM>.tif"/>
    </image>
    <mix name="diffmix" type="color3">
      <input name="bg" type="color3" interfacename="diff_albedo"/>
      <input name="fg" type="color3" nodename="i_diff1"/>
      <input name="mix" type="float" interfacename="diff_map_mix"/>
    </mix>
    <standard_surface name="stdsurf1" type="surfaceshader">
      <input name="base_color" type="color3" nodename="diffmix"/>
      <input name="diffuse_roughness" type="float" interfacename="roughness"/>
      <input name="specular_color" type="color3" interfacename="spec_color"/>
      <input name="specular_roughness" type="float" interfacename="roughness"/>
      <input name="specular_IOR" type="float" interfacename="spec_ior"/>
    </standard_surface>
    <output name="out" type="surfaceshader" nodename="stdsurf1"/>
    <aovoutput name="NGAalbedo" type="color3" aovname="albedo" nodename="diffmix"/>
    <aovoutput name="NGAdiffuse" type="BSDF" aovname="diffuse" nodename="stdsurf1"
                  sourceaov="diffuse"/>
    <aovoutput name="NGAspecular" type="BSDF" aovname="specular" nodename="stdsurf1"
                  sourceaov="specular"/>
  </nodegraph>

Layered shaders or materials must internally handle blending of AOV-like values from source layers before outputting them as AOVs: there is currently no facility for blending AOVs defined within post-shading blended surfaceshaders.

Note: while it is syntactically possible to create <aovoutput>s for geometric primitive values such as shading surface point and normal accessed within a nodegraph, it is preferred that renderers derive such information directly from their internal shading state or geometric primvars.

Implementation AOV Elements

An <implementation> element with a file attribute defining an external compiled implementation of a surface shader may contain one or more <aov> elements to declare the names and types of arbitrary output variables ("AOVs") which the shader can output to the renderer. AOVs must be of type float, color3, vector3, BSDF or EDF. Note that in MaterialX, AOVs for pre-shading "pattern" colors are normally of type color3, while post-shaded color-like values are normally of type BSDF and emissive color-like values are normally of type EDF. An <implementation> with a nodegraph attribute may not contain <aov> elements; instead, <aovoutput> elements within the nodegraph should be used.

  <implementation name="IM_basicsurface_surface_rmanris"
                  nodedef="ND_basic_surface_surface" implname="basic_srf"
                  target="rmanris" file="basic_srf.C">
    ...<inputs>...
    <aov name="IMalbedo" type="color3" aovname="albedo"/"/>
    <aov name="IMdiffuse" type="BSDF" aovname="diffuse"/"/>
  </implementation>

Material Inheritance

Materials can inherit from other materials, to add or change shaders connected to different inputs; in this example, a displacement shader is added to the above "Mgold" material to create a new "Mgolddsp" material:

  <noise2d name="noise1" type="float">
    <input name="amplitude" type="float" value="1.0"/>
    <input name="pivot" type="float" value="0.0"/>
  </noise2d>
  <displacement name="stddsp" type="displacementshader">
    <input name="displacement" type="float" nodename="noise1"/>
    <input name="scale" tpe="float" value="0.1"/>
  </displacement>
  <surfacematerial name="Mgolddsp" type="material" inherit="Mgold">
    <input name="displacementshader" type="displacementshader" nodename="stddsp"/>
  </surfacematerial>

Inheritance of material-type custom nodes is also allowed, so that new or changed input values can be applied on top of those specified in the inherited material.

Proposals: Stdlib Nodes

Procedural Nodes

`tokenvalue`

A constant "interface token" value, may only be connected to <token>s in nodes, not to <input>s.

Port	Description	Type	Default
`value`	The value that will be sent to `out`	string, filename	empty
`out`	Output: `value`	Same as `value`	empty

Noise Nodes

`cellnoise1d`

1D cellular noise, proposed as an alternative approach to random value generation.

Port	Description	Type	Default
`in`	The 1D coordinate at which the noise is evaluated	float
`period`	The period of the noise	float, vector3	zero
`out`	Output: the computed noise value	float, vector3	zero

`worleynoise2d`

This proposal extends the existing worleynoise2d node to support different distance metrics and periodicity.

Port	Description	Type	Default	Accepted Values
`metric`	The distance metric to return	string	distance	distance, distance2, manhattan, chebyshev
`period`	The period of the noise	float, vector3	zero
`out`	Output: the computed noise value	float, vector2, vector3	zero

`worleynoise3d`

This proposal extends the existing worleynoise3d node to support different distance metrics and periodicity.

Port	Description	Type	Default	Accepted Values
`metric`	The distance metric to return	string	distance	distance, distance2, manhattan, chebyshev
`period`	The period of the noise	float, vector3	zero
`out`	Output: the computed noise value	float, vector2, vector3	zero

The period input is a positive integer distance at which the noise function returns the same value for coordinates repeated at that step. A value of 0 means the noise is not periodic.

Periodic Noises

In #1201 it was decided that separate periodic versions of all of the noises is preferred to adding it to the existing noises.

Shape Nodes

Geometric Nodes

Global Nodes

`ambientocclusion`

Compute the ambient occlusion at the current surface point, returning a scalar value between 0 and 1. Ambient occlusion represents the accessibility of each surface point to ambient lighting, with larger values representing greater accessibility to light.

The coneangle input defines a half-angle about the surface normal, so the default value of 90 degrees represents the full hemisphere.

Port	Description	Type	Default
`coneangle`	The half-angle of the occlusion cone, in degrees	float	90.0
`maxdistance`	The maximum distance to consider for occlusion	float	1e38
`out`	Output: the computed ambient occlusion value	float

Application Nodes

`updirection`

The current scene "up vector" direction, as defined by the shading environment.

Port	Description	Type	Default	Accepted Values
`space`	The space in which to return the up vector direction	string	world	model, object, world
`out`	Output: the up direction in `space`	vector3

Math Nodes

`transformcolor`

Transform the incoming color from one specified colorspace to another, ignoring any colorspace declarations that may have been provided upstream. For color4 types, the alpha channel value is unaffected. The fromspace and tospace inputs accept the name of a standard colorspace or a colorspace understood by the application; either may be empty to specify the document's working colorspace.

Port	Description	Type	Default
`in`	The input color	color3, color4	zero
`fromspace`	The colorspace to transform `in` from	string	empty
`tospace`	The colorspace to transform `in` to	string	empty
`out`	Output: the transformed color	Same as `in`

`triplanarblend`

Samples data from three inputs, and projects a tiled representation of the images along each of the three respective coordinate axes, computing a weighted blend of the three samples using the geometric normal.

The iny input is projected in the direction from the +Y axis back toward the origin, with the +X axis to the right.

If adopted, the existing triplanarprojection node would be reimplemented as a wrapper that resolves its three image inputs and passes them to triplanarblend.

Port	Description	Type	Default	Accepted Values
`inx`	The image to be projected in the direction from the +X axis back toward the origin	float or colorN	zero
`iny`	The image to be projected in the direction from the +Y axis back toward the origin	float or colorN	zero
`inz`	The image to be projected in the direction from the +Z axis back toward the origin	float or colorN	zero
`position`	The 3D position at which the projection is evaluated	vector3	Pobject
`normal`	The 3D normal vector used for blending	vector3	Nobject
`blend`	Weighting factor for blending the three axis samples, with higher values giving softer blending	float	1.0	[0, 1]
`filtertype`	The type of texture filtering to use	string	linear	closest, linear, cubic
`out`	Output: the blended value	Same as `inx`	zero

Adjustment Nodes

`curveinversecubic`

Remap a 0-1 input value using an inverse Catmull-Rom spline lookup on the input knots values. At least 2 knot values must be provided, and the first and last knot have multiplicity 2.

Port	Description	Type	Default
`in`	The input value	float	0.0
`knots`	The list of input knot values for the remapping	floatarray
`out`	Output: the remapped value	float

`curveuniformlinear`

Output a float, colorN or vectorN value linearly interpolated between a number of knotvalues values, using the value of in as the interpolant.

Port	Description	Type	Default
`in`	The input interpolant value	float	0.0
`knotvalues`	The array of at least 2 values to interpolate between	floatarray, colorNarray, vectorNarray
`out`	Output: the interpolated value	float, colorN, vectorN

`curveuniformcubic`

Output a float, colorN or vectorN value smoothly interpolated between a number of knotvalues values using a Catmull-Rom spline with the value of in as the interpolant.

Port	Description	Type	Default
`in`	The input interpolant value	float	0.0
`knotvalues`	The array of at least 2 values to interpolate between	floatarray, colorNarray, vectorNarray
`out`	Output: the interpolated value	float, colorN, vectorN

`curveadjust`

Output a smooth remapping of input values using the centripetal Catmull-Rom cubic spline curve defined by specified knot values, using an inverse spline lookup on input knot values and a forward spline through output knot values. All channels of the input will be remapped using the same curve.

Port	Description	Type	Default
`in`	The input value	float, colorN, vectorN	zero
`numknots`	The number of values in the knots and knotvalues arrays	integer	2
`knots`	The list of input values defining the curve for the remapping; at least 2 and at most 16 values	floatarray
`knotvalues`	The list of output values defining the curve for the remapping; must be the same length as knots	floatarray
`out`	Output: the remapped value	Same as `in`

`curvelookup`

Output a float, colorN or vectorN value smoothly interpolated between a number of knotvalue values, using the position of in within knots as the knotvalues interpolant.

Port	Description	Type	Default
`in`	The input interpolant value	float	0.0
`numknots`	The number of values in the knots and knotvalues arrays	integer	2
`knots`	The list of knot values to interpolate `in` within; at least 2 and at most 16 values	floatarray
`knotvalues`	The values at each knot position to interpolate between; must be the same length as knots	floatarray, colorNarray, vectorNarray
`out`	Output: the interpolated value	float, colorN, vectorN

Compositing Nodes

Conditional Nodes

`ifelse`

Output the value of one of two input streams, according to whether the value of a boolean selector input is true or false.

Port	Description	Type	Default
`infalse`	The value to output if `which` is false	float, colorN, vectorN	zero
`intrue`	The value to output if `which` is true	Same as `infalse`	zero
`which`	A selector to choose which input to take values from	boolean	false
`out`	Output: the selected input	Same as `infalse`

Channel Nodes

`separatecolor4`

Output the RGB and alpha channels of a color4 as separate outputs.

Port	Description	Type	Default
`in`	The input color4 value	color4	0.0, 0.0, 0.0, 0.0
`outcolor`	Output: the RGB channels of `in`	color3	0.0, 0.0, 0.0
`outa`	Output: the alpha channel of `in`	float	0.0

FilesExpand file tree

MaterialX.Proposals.md

Latest commit

History

MaterialX.Proposals.md

File metadata and controls

MaterialX: Proposed Additions and Changes

Introduction

Table of Contents

Proposals: General

Color Spaces

Proposals: Elements

AOV Output Elements

AovOutput Example

Implementation AOV Elements

Material Inheritance

Proposals: Stdlib Nodes

Procedural Nodes

tokenvalue

Noise Nodes

cellnoise1d

worleynoise2d

worleynoise3d

Periodic Noises

Shape Nodes

Geometric Nodes

Global Nodes

ambientocclusion

Application Nodes

updirection

Math Nodes

transformcolor

triplanarblend

Adjustment Nodes

curveinversecubic

curveuniformlinear

curveuniformcubic

curveadjust

curvelookup