From 147ef232ac3b0d2db5574d770adcd8b844baf19b Mon Sep 17 00:00:00 2001 From: Doug Smythe Date: Sun, 21 Jul 2024 16:15:28 -0700 Subject: [PATCH 1/5] Add MaterialX Proposals Doc Add new MaterialX Proposals document. Remove duplicated description of and/or/not in Math nodes section of main spec. Add TOC links for Kronos PBR and OpenPBR shading examples. --- documents/Specification/MaterialX.PBRSpec.md | 2 + .../Specification/MaterialX.Proposals.md | 346 ++++++++++++++++++ .../Specification/MaterialX.Specification.md | 19 +- 3 files changed, 349 insertions(+), 18 deletions(-) create mode 100644 documents/Specification/MaterialX.Proposals.md diff --git a/documents/Specification/MaterialX.PBRSpec.md b/documents/Specification/MaterialX.PBRSpec.md index 32cef574c6..2e314d479d 100644 --- a/documents/Specification/MaterialX.PBRSpec.md +++ b/documents/Specification/MaterialX.PBRSpec.md @@ -43,6 +43,8 @@ This document describes a number of shader-semantic nodes implementing widely-us **[Shading Model Examples](#shading-model-examples)**  [Autodesk Standard Surface](#autodesk-standard-surface)  [UsdPreviewSurface](#usdpreviewsurface) + [Khronos glTF PBR](#khronos-gltf-pbr) + [OpenPBR Surface](#openpbr-surface) **[References](#references)** diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md new file mode 100644 index 0000000000..de7d23b81d --- /dev/null +++ b/documents/Specification/MaterialX.Proposals.md @@ -0,0 +1,346 @@ + + + +# MaterialX: Proposed Additions and Changes + +**Proposals for Version 1.39** +July 20, 2024 + + +# Introduction + +The [MaterialX Specification](./MaterialX.Specification.md) has historically included descriptions of not just current functionality, but also forward-looking proposed functionality intended for eventual implementation. This has resulted in a lack of clarity about which functionality is actually supported in the library, and which are proposed additions. + +To remedy this, those forward-looking proposals have been moved 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. + + + +## Table of Contents + +**[Introduction](#introduction)** + +**[Proposals: General](#propose-general)** + +**[Proposals: Elements](#propose-elements)** + +**[Proposals: Stdlib Nodes](#propose-stdlib-nodes)** + +**[Proposals: PBR Nodes](#propose-pbr-nodes)** + +**[Proposals: NPR Nodes](#propose-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 + +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>. + +```xml + +``` + +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: + +```xml + + + 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: + +```xml + + + + + + + + + + + + + + + + + + + + + +``` + +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. + +```xml + + ...... + + + +``` + + + +### 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: + +```xml + + + + + + + + + + + +``` + +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. + * `value` (any uniform non-shader-semantic type): the token value to output; "enum" and "enumvalues" attributes may be provided to define a specific set of allowed token values. + + + +### Noise Nodes + + + +We have a standard 3d fractal noise, but a 2d variant would be useful as well. + +* **`fractal2d`**: Zero-centered 2D Fractal noise in 1, 2, 3 or 4 channels, created by summing several octaves of 2D Perlin noise, increasing the frequency and decreasing the amplitude at each octave. + * `amplitude` (float or vectorN): the center-to-peak amplitude of the noise (peak-to-peak amplitude is 2x this value). Default is 1.0. + * `octaves` (integer): the number of octaves of noise to be summed. Default is 3. + * `lacunarity` (float or vectorN): the exponential scale between successive octaves of noise; must be an integer value if period is non-zero so the result is properly tileable. VectorN-output types can provide either a float (isotropic) or vectorN (anisotropic) values for lacunarity and diminish. Default is 2.0. + * `diminish` (float or vectorN): the rate at which noise amplitude is diminished for each octave. Should be between 0.0 and 1.0; default is 0.5. VectorN-output types can provide either a float (isotropic) or vectorN (anisotropic) values for lacunarity and diminish. + * `period` (float or vectorN): the positive integer distance at which the noise function returns the same value for texture coordinates repeated at that step. Default is 0, meaning the noise is not periodic. + * `texcoord` (vector2): the 2D texture coordinate at which the noise is evaluated. Default is to use the first set of texture coordinates. + + + +1D Cell noise was proposed an an alternative approach to random value generation. + +* **`cellnoise1d`**: 1D cellular noise, 1 or 3 channels (type float or vector3). + * `period` (float or vector3): the positive integer distance at which the noise function returns the same value for input coordinate repeated at that step. Default is 0, meaning the noise is not periodic. + * `in` (float): the 1D coordinate at which the noise is evaluated. + + + +### Shape Nodes + +Some of the current shape nodes only output an on/off float output, while others output a color3, some with the ability to specify the "inside" and "outside" colors and others not. It would be good to standardize all shape nodes to include both "float" and "color3" output variants, and to consistently provide "value0"/"value1" inputs (float or color3 to match the output type). + + + +### Geometric Nodes + + + +* **`bump`**: Existing node, proposal to add a vector3 `bitangent` input + + + +* **`geompropvalueuniform`**: the value of the specified uniform geometric property (defined using <geompropdef>) of the currently-bound geometry. This node's type must match that of the referenced geomprop. + * `geomprop` (uniform string): the geometric property to be referenced. + * `default` (same type as the geomprop's value): a value to return if the specified `geomprop` is not defined on the current geometry. + + + +### 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. This node must be of type float. + * `coneangle` (float): the half-angle of a cone about the surface normal, within which geometric surface features are considered as potential occluders. The unit for this input is degrees, and its default value is 90.0 (full hemisphere). + * `maxdistance` (float): the maximum distance from the surface point at which geometric surface features are considered as potential occluders. Defaults to 1e38, e.g. "unlimited". + + + +### Application Nodes + + + +* **`updirection`**: the current scene "up vector" direction, as defined by the shading environment. This node must be of type vector3. + * `space` (uniform string): the space in which to return the up vector direction, defaults to "world". + + + +### 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. + * `in` (color3 or color4): the input color. + * `fromspace` (uniform string): the name of a standard colorspace or a colorspace understood by the application to transform the `in` color from; may be empty (the default) to specify the document's working colorspace. + * `tospace` (uniform string): the name of a standard colorspace or a colorspace understood by the application to transform the `in` color to; may be empty (the default) to specify the document's working colorspace. + + + +* **`triplanarblend`** (NG): 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. + * `inx` (float or colorN): the image to be projected in the direction from the +X axis back toward the origin. Default is 0 in all channels. + * `iny` (float or colorN): the image to be projected in the direction from the +Y axis back toward the origin with the +X axis to the right. Default is 0 in all channels. + * `inz` (float or colorN): the image to be projected in the direction from the +Z axis back toward the origin. Default is 0 in all channels. + * `position` (vector3): a spatially-varying input specifying the 3D position at which the projection is evaluated. Default is to use the current 3D object-space coordinate. + * `normal` (vector3): a spatially-varying input specifying the 3D normal vector used for blending. Default is to use the current object-space surface normal. + * `blend` (float): a 0-1 weighting factor for blending the three axis samples using the geometric normal, with higher values giving softer blending. Default is 1.0. + * `filtertype` (uniform string): the type of texture filtering to use; standard values include "closest" (nearest-neighbor single-sample), "linear", and "cubic". If not specified, an application may use its own default texture filtering method. + + + +### Adjustment Nodes + + + +* **`curveinversecubic`**: remap a 0-1 input float value using an inverse Catmull-Rom spline lookup on the input `knots` values. Outputs a 0-1 float interpolant value. + * `in` (float): the input value or nodename + * `knots` (uniform floatarray): the list of non-uniformly distributed input values defining the curve for the remapping. At least 2 values must be provided, and the first and last knot have multiplicity 2. + + + +* **`curveuniformlinear`**: output a float, colorN or vectorN value linearly interpolated between a number of `knotvalues` values, using the value of `in` as the interpolant. + * `in` (float): the input interpolant value or nodename + * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the array of at least 2 values to interpolate between. + + + +* **`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. + * `in` (float): the input interpolant value or nodename + * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the array of at least 2 values to interpolate between. + + + +* **`curveadjust`** (NG): 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. + * `in` (float or colorN or vectorN): the input value or nodename + * `numknots` (uniform integer): the number of values in the knots and knotvalues arrays + * `knots` (uniform floatarray): the list of input values defining the curve for the remapping. At least 2 and at most 16 values must be provided. + * `knotvalues` (uniform floatarray): the list of output values defining the curve for the remapping. Must be the same length as knots. + + + +* **`curvelookup`** (NG): 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. + * `in` (float): the input interpolant value or nodename + * `numknots` (uniform integer): the number of values in the knots and knotvalues arrays + * `knots` (uniform floatarray): the list of knot values to interpolate in within. At least 2 and at most 16 values must be provided. + * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the values at each knot position to interpolate between. Must be the same length as knots. + + + +### 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 + * `infalse`, `intrue` (float or colorN or vectorN): the values or nodenames to select from based on the value of the `which` input. The types of the various `inN` inputs must match the type of the `switch` node itself. The default value of all `inN` inputs is 0.0 in all channels. + * `which` (boolean): a selector to choose which input to take values from; default is "false". + + + +### Channel Nodes + + + +* **`extractrowvector`**: extract the specified row vector number from a matrixN stream. + * `in` (matrixN): the input value or nodename + * `index` (integer): the row number to extract, should be 0-2 for matrix33 streams, or 0-3 for matrix44 streams. + + + +* **`separatecolor4`** (NG): output the RGB and alpha channels of a color4 as separate outputs. + * `in` (color4): the input value or nodename + * `outcolor` (output, color3): the RGB channel values. + * `outa` (output, float): the value of the alpha channel. + + + +### Convolution Nodes + + + +* **`blur`**: a convolution blur. + * `in` (float or colorN or vectorN): the input value or nodename + * `size` (float): the size of the blur kernel, relative to 0-1 UV space; default is 0. + * `filtertype` (uniform string): the spatial filter used in the blur, either "box" for a linear box filter, or "gaussian" for a gaussian filter. Default is "box". + + + +

 

+ +# Proposals: PBR Nodes + + + +

 

+ +# Proposals: NPR Nodes + +### Toon Shader + +The community has expressed interest in a standard "toon shader", and a proposed definition and implementation would be welcome. diff --git a/documents/Specification/MaterialX.Specification.md b/documents/Specification/MaterialX.Specification.md index 681f36ea36..9d3bfcb9cc 100644 --- a/documents/Specification/MaterialX.Specification.md +++ b/documents/Specification/MaterialX.Specification.md @@ -8,7 +8,7 @@ MaterialX Specification v1.39 **Version 1.39** Doug Smythe - Industrial Light & Magic Jonathan Stone - Lucasfilm Advanced Development Group -May 9, 2024 +July 20, 2024 # Introduction @@ -1363,23 +1363,6 @@ Math nodes have one or two spatially-varying inputs, and are used to perform a m * `in1` (float or colorN or vectorN): the first value or nodename * `in2` (same type as `in1` or float): the second value or nodename - - -* **`and`**: boolean "and" of the two incoming boolean values - * `in1` (boolean): the first value or nodename - * `in2` (boolean): the second value or nodename - - - -* **`or`**: boolean "or" of the two incoming boolean values - * `in1` (boolean): the first value or nodename - * `in2` (boolean): the second value or nodename - - - -* **`not`**: boolean "not" of the incoming boolean value - * `in` (boolean): the value or nodename - * **`normalize`**: output the normalized vectorN from the incoming vectorN stream; cannot be used on float or colorN streams. Note: the fourth channel in vector4 streams is not treated any differently, e.g. not as a homogeneous "w" value. From 7454d78e196843e0354f4c69b88c1364ce14f3f3 Mon Sep 17 00:00:00 2001 From: Doug Smythe Date: Fri, 26 Jul 2024 12:10:28 -0700 Subject: [PATCH 2/5] Updated Proposals doc Updated proposals doc to address feedback, added mention of it in the README --- documents/Specification/MaterialX.Proposals.md | 10 +++------- documents/Specification/README.md | 1 + 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md index de7d23b81d..af019a51ab 100644 --- a/documents/Specification/MaterialX.Proposals.md +++ b/documents/Specification/MaterialX.Proposals.md @@ -6,14 +6,14 @@ MaterialX Proposals v1.39 # MaterialX: Proposed Additions and Changes **Proposals for Version 1.39** -July 20, 2024 +July 26, 2024 # Introduction -The [MaterialX Specification](./MaterialX.Specification.md) has historically included descriptions of not just current functionality, but also forward-looking proposed functionality intended for eventual implementation. This has resulted in a lack of clarity about which functionality is actually supported in the library, and which are proposed additions. +The [MaterialX Specification](./MaterialX.Specification.md) 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. -To remedy this, those forward-looking proposals have been moved 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. +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. @@ -192,7 +192,6 @@ We have a standard 3d fractal noise, but a 2d variant would be useful as well. ### Shape Nodes -Some of the current shape nodes only output an on/off float output, while others output a color3, some with the ability to specify the "inside" and "outside" colors and others not. It would be good to standardize all shape nodes to include both "float" and "color3" output variants, and to consistently provide "value0"/"value1" inputs (float or color3 to match the output type). @@ -341,6 +340,3 @@ Some of the current shape nodes only output an on/off float output, while others # Proposals: NPR Nodes -### Toon Shader - -The community has expressed interest in a standard "toon shader", and a proposed definition and implementation would be welcome. diff --git a/documents/Specification/README.md b/documents/Specification/README.md index 82e0a81566..e8425c07bd 100644 --- a/documents/Specification/README.md +++ b/documents/Specification/README.md @@ -11,6 +11,7 @@ The documents in this folder comprise the complete MaterialX Specification, vers * [**MaterialX NPR Shading Nodes**](./MaterialX.NPRSpec.md) - specifies shading nodes that are designed for use in non-photorealistic and stylized rendering * [**MaterialX Geometry Extensions**](./MaterialX.GeomExts.md) - additional MaterialX elements to define geometry-related information such as collections, properties and material assignments * [**MaterialX Supplemental Notes**](./MaterialX.Supplement.md) - describes recommended naming and structuring conventions for libraries of custom node definitions +* [**MaterialX: Proposed Additions and Changes**](./MaterialX.Proposals.md) - describes proposed future updates to various components of the Specification

From 85a7b0c96f3ee4c3af9898eed8d8f996a20190c2 Mon Sep 17 00:00:00 2001 From: Doug Smythe Date: Sun, 28 Jul 2024 16:04:30 -0700 Subject: [PATCH 3/5] Remove Proposal items from Main Specification Nodes and elements and other things that were moved into the Proposals doc are here removed from the Specification doc. --- .../Specification/MaterialX.Specification.md | 222 +----------------- 1 file changed, 3 insertions(+), 219 deletions(-) diff --git a/documents/Specification/MaterialX.Specification.md b/documents/Specification/MaterialX.Specification.md index 9d3bfcb9cc..7a51dee109 100644 --- a/documents/Specification/MaterialX.Specification.md +++ b/documents/Specification/MaterialX.Specification.md @@ -8,7 +8,7 @@ MaterialX Specification v1.39 **Version 1.39** Doug Smythe - Industrial Light & Magic Jonathan Stone - Lucasfilm Advanced Development Group -July 20, 2024 +July 26, 2024 # Introduction @@ -24,7 +24,7 @@ At least four distinct interrelated data relationships are required to specify t **MaterialX** addresses the need for an open, platform-independent, well-defined standard for specifying the "look" of computer graphics objects built using node networks by defining a material content schema along with a corresponding XML-based file format to read and write MaterialX content. The MaterialX schema defines a number of primary element types plus several supplemental and sub-element types, as well as a set of **standard nodes** with specific functionality for defining data-processing graphs, shaders and materials. -This document describes the core MaterialX specification. Companion documents [**MaterialX Physically Based Shading Nodes**](./MaterialX.PBRSpec.md), [**MaterialX Geometry Extensions**](./MaterialX.GeomExts.md) and [**MaterialX Supplemental Notes**](./MaterialX.Supplement.md) describe additional node and element types and other information about the library. +This document describes the core MaterialX specification. Companion documents [**MaterialX Physically Based Shading Nodes**](./MaterialX.PBRSpec.md), [**MaterialX Geometry Extensions**](./MaterialX.GeomExts.md) and [**MaterialX Supplemental Notes**](./MaterialX.Supplement.md) describe additional node and element types and other information about the library, while [**MaterialX: Proposed Additions and Changes**](./MaterialX.Proposals.md) describes forward-looking proposed funnctionality for MaterialX. @@ -84,7 +84,6 @@ This document describes the core MaterialX specification. Companion documents [    [NodeDef Token Elements](#nodedef-token-elements)    [NodeDef Output Elements](#nodedef-output-elements)   [Custom Node Definition Using Implementation Elements](#custom-node-definition-using-implementation-elements) -   [Implementation AOV Elements](#implementation-aov-elements)    [Example Custom Nodes Defined by External File Implementations](#example-custom-nodes-defined-by-external-file-implementations)   [Custom Node Definition Using Node Graphs](#custom-node-definition-using-node-graphs)    [Functional Nodegraphs](#functional-nodegraphs) @@ -93,10 +92,7 @@ This document describes the core MaterialX specification. Companion documents [   [Custom Node Use](#custom-node-use)  [Shader Nodes](#shader-nodes)   [Standard Library Shader Nodes](#standard-library-shader-nodes) -  [AOV Output Elements](#aov-output-elements) -   [AOVOutput Example](#aovoutput-example)  [Material Nodes](#material-nodes) -  [Material Inheritance](#material-inheritance)   [Example Pre-Shader Compositing Material](#example-pre-shader-compositing-material)  [Material Variants](#material-variants) @@ -774,11 +770,6 @@ Standard Procedural nodes: * **`constant`**: a constant value. * `value` (any non-shader-semantic type): the value to output - - -* **`tokenvalue`**: a constant "interface token" value, may only be connected to <token>s in nodes, not to <input>s. - * `value` (any uniform non-shader-semantic type): the token value to output; "enum" and "enumvalues" attributes may be provided to define a specific set of allowed token values. - * **`ramplr`**: a left-to-right linear value ramp. @@ -872,16 +863,6 @@ Standard Noise nodes: * `period` (float or vectorN): the positive integer distance at which the noise function returns the same value for position coordinates repeated at that step. Default is 0, meaning the noise is not periodic. * `position` (vector3): the 3D position at which the noise is evaluated. Default is to use the current 3D object-space coordinate. - - -* **`fractal2d`**: Zero-centered 2D Fractal noise in 1, 2, 3 or 4 channels, created by summing several octaves of 2D Perlin noise, increasing the frequency and decreasing the amplitude at each octave. - * `amplitude` (float or vectorN): the center-to-peak amplitude of the noise (peak-to-peak amplitude is 2x this value). Default is 1.0. - * `octaves` (integer): the number of octaves of noise to be summed. Default is 3. - * `lacunarity` (float or vectorN): the exponential scale between successive octaves of noise; must be an integer value if period is non-zero so the result is properly tileable. VectorN-output types can provide either a float (isotropic) or vectorN (anisotropic) values for lacunarity and diminish. Default is 2.0. - * `diminish` (float or vectorN): the rate at which noise amplitude is diminished for each octave. Should be between 0.0 and 1.0; default is 0.5. VectorN-output types can provide either a float (isotropic) or vectorN (anisotropic) values for lacunarity and diminish. - * `period` (float or vectorN): the positive integer distance at which the noise function returns the same value for texture coordinates repeated at that step. Default is 0, meaning the noise is not periodic. - * `texcoord` (vector2): the 2D texture coordinate at which the noise is evaluated. Default is to use the first set of texture coordinates. - * **`fractal3d`**: Zero-centered 3D Fractal noise in 1, 2, 3 or 4 channels, created by summing several octaves of 3D Perlin noise, increasing the frequency and decreasing the amplitude at each octave. @@ -892,12 +873,6 @@ Standard Noise nodes: * `period` (float or vectorN): the positive integer distance at which the noise function returns the same value for position coordinates repeated at that step. Default is 0, meaning the noise is not periodic. * `position` (vector3): the 3D position at which the noise is evaluated. Default is to use the current 3D object-space coordinate. - - -* **`cellnoise1d`**: 1D cellular noise, 1 or 3 channels (type float or vector3). - * `period` (float or vector3): the positive integer distance at which the noise function returns the same value for input coordinate repeated at that step. Default is 0, meaning the noise is not periodic. - * `in` (float): the 1D coordinate at which the noise is evaluated. - * **`cellnoise2d`**: 2D cellular noise, 1 or 3 channels (type float or vector3). @@ -1148,19 +1123,9 @@ Applications may also reference other renderer-specific named spaces, at the exp Global nodes generate color data using non-local geometric context, requiring access to geometric features beyond the surface point being processed. This non-local context can be provided by tracing rays into the scene, rasterizing scene geometry, or any other appropriate method. -```xml - - - -``` - Standard 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. This node must be of type float. - * `coneangle` (float): the half-angle of a cone about the surface normal, within which geometric surface features are considered as potential occluders. The unit for this input is degrees, and its default value is 90.0 (full hemisphere). - * `maxdistance` (float): the maximum distance from the surface point at which geometric surface features are considered as potential occluders. Defaults to 1e38, e.g. "unlimited". +There are currently no Global Nodes implemented in MaterialX. @@ -1183,11 +1148,6 @@ Standard Application nodes: * **`time`**: the current time in seconds, as defined by the host environment. This node must be of type float. Applications may use whatever method is appropriate to communicate the current time to the <time> node's implementation, whether via an internal state variable, a custom input, dividing the current frame number by a local "frames per second" value, or other method; real-time applications may return some variation of wall-clock time. - - -* **`updirection`**: the current scene "up vector" direction, as defined by the shading environment. This node must be of type vector3. - * `space` (uniform string): the space in which to return the up vector direction, defaults to "world". - ## Standard Operator Nodes @@ -1419,13 +1379,6 @@ Math nodes have one or two spatially-varying inputs, and are used to perform a m * `in` (vectorN): the input vector. If needed, an additional 1.0 component will be temporarily appended to the `in` vector to make it match the dimension of the transforming `mat` matrix, then removed after transformation. * `mat` matrix33/44): the matrix used to transform the vector; a vector2 `in` can be transformed by a matrix33, a vector3 by a matrix33 or a matrix44, and a vector4 by a matrix44. Default is the identity matrix. - - -* **`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. - * `in` (color3 or color4): the input color. - * `fromspace` (uniform string): the name of a standard colorspace or a colorspace understood by the application to transform the `in` color from; may be empty (the default) to specify the document's working colorspace. - * `tospace` (uniform string): the name of a standard colorspace or a colorspace understood by the application to transform the `in` color to; may be empty (the default) to specify the document's working colorspace. - * **`normalmap`**: transform a normal vector from encoded tangent space to world space. The input normal vector is assumed to be encoded with all channels in the [0-1] range, as would commonly be output from a normal map. @@ -1484,7 +1437,6 @@ Math nodes have one or two spatially-varying inputs, and are used to perform a m * `normal` (vector3): the normal vector about which to reflect "in", defaults to the value of the "Nworld" (world space view direction) geometric property. This vector is expected to be prenormalized to length 1.0. * `ior` (float): the index of refraction of the surface, defaults to 1.0. - * **`place2d`** (NG): transform incoming UV texture coordinates for 2D texture placement. @@ -1495,17 +1447,6 @@ Math nodes have one or two spatially-varying inputs, and are used to perform a m * `offset` (vector2): subtract this amount from the scaled/rotated/“pivot added back” UV coordinate; since U0,V0 is typically the lower left corner, a positive offset moves the texture image up and right. Default is (0,0). * `operationorder` (integer enum): the order in which to perform the transform operations. "0" or "SRT" performs "-pivot scale rotate translate +pivot" as per the original implementation matching the behavior of certain DCC packages, and "1" or "TRS" performs "-pivot translate rotate scale +pivot" which does not introduce texture shear. Default is 0 "SRT" for backward compatibility. - - -* **`triplanarblend`** (NG): 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. - * `inx` (float or colorN): the image to be projected in the direction from the +X axis back toward the origin. Default is 0 in all channels. - * `iny` (float or colorN): the image to be projected in the direction from the +Y axis back toward the origin with the +X axis to the right. Default is 0 in all channels. - * `inz` (float or colorN): the image to be projected in the direction from the +Z axis back toward the origin. Default is 0 in all channels. - * `position` (vector3): a spatially-varying input specifying the 3D position at which the projection is evaluated. Default is to use the current 3D object-space coordinate. - * `normal` (vector3): a spatially-varying input specifying the 3D normal vector used for blending. Default is to use the current object-space surface normal. - * `blend` (float): a 0-1 weighting factor for blending the three axis samples using the geometric normal, with higher values giving softer blending. Default is 1.0. - * `filtertype` (uniform string): the type of texture filtering to use; standard values include "closest" (nearest-neighbor single-sample), "linear", and "cubic". If not specified, an application may use its own default texture filtering method. - * **`dot`**: a no-op, passes its input through to its output unchanged. Users can use dot nodes to shape edge connection paths or provide documentation checkpoints in node graph layout UI's. Dot nodes may also pass uniform values from <constant>, <tokenvalue> or other nodes with uniform="true" outputs to uniform <input>s and <token>s. @@ -1579,40 +1520,6 @@ Adjustment nodes have one input named "in", and apply a specified function to va * `low` (same type as `in` or float): input low value; an input value of this or lower will result in an output value of 0; default is 0.0 in all channels * `high` (same type as `in` or float): input high value; an input value of this or higher will result in an output value of 1; default is 1.0 in all channels - - -* **`curveinversecubic`**: remap a 0-1 input float value using an inverse Catmull-Rom spline lookup on the input `knots` values. Outputs a 0-1 float interpolant value. - * `in` (float): the input value or nodename - * `knots` (uniform floatarray): the list of non-uniformly distributed input values defining the curve for the remapping. At least 2 values must be provided, and the first and last knot have multiplicity 2. - - - -* **`curveuniformlinear`**: output a float, colorN or vectorN value linearly interpolated between a number of `knotvalues` values, using the value of `in` as the interpolant. - * `in` (float): the input interpolant value or nodename - * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the array of at least 2 values to interpolate between. - - - -* **`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. - * `in` (float): the input interpolant value or nodename - * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the array of at least 2 values to interpolate between. - - - -* **`curveadjust`** (NG): 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. - * `in` (float or colorN or vectorN): the input value or nodename - * `numknots` (uniform integer): the number of values in the knots and knotvalues arrays - * `knots` (uniform floatarray): the list of input values defining the curve for the remapping. At least 2 and at most 16 values must be provided. - * `knotvalues` (uniform floatarray): the list of output values defining the curve for the remapping. Must be the same length as knots. - - - -* **`curvelookup`** (NG): 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. - * `in` (float): the input interpolant value or nodename - * `numknots` (uniform integer): the number of values in the knots and knotvalues arrays - * `knots` (uniform floatarray): the list of knot values to interpolate in within. At least 2 and at most 16 values must be provided. - * `knotvalues` (uniform floatarray or colorNarray or vectorNarray): the values at each knot position to interpolate between. Must be the same length as knots. - * **`luminance`**: (color3 or color4 only) output a grayscale value containing the luminance of the incoming RGB color in all color channels, computed using the dot product of the incoming color with the luma coefficients of the working colorspace; the alpha channel is left unchanged if present. @@ -1791,12 +1698,6 @@ Conditional nodes are used to compare values of two streams, or to select a valu * `in1`, `in2`, `in3`, `in4`, `in5`, `in6`, `in7`, `in8`, `in9`, `in10` (float or colorN or vectorN or matrixNN): the values or nodenames to select from based on the value of the `which` input. The types of the various `in`N inputs must match the type of the `switch` node itself. The default value of all `in`N inputs is 0.0 in all channels. * `which` (integer or float): a selector to choose which input to take values from; the output comes from input "floor(`which`)+1", clamped to the 1-10 range. So `which`<1 will pass on the value from in1, 1<=`which`<2 will pass the value from in2, 2<=`which`<3 will pass the value from in3, and so on up to 9<=`which` will pass the value from in10. The default value of `which` is 0. - - -* **`ifelse`**: output the value of one of two input streams, according to whether the value of a boolean selector input is true or false - * `infalse`, `intrue` (float or colorN or vectorN): the values or nodenames to select from based on the value of the `which` input. The types of the various `inN` inputs must match the type of the `switch` node itself. The default value of all `inN` inputs is 0.0 in all channels. - * `which` (boolean): a selector to choose which input to take values from; default is "false". - ### Channel Nodes @@ -1810,12 +1711,6 @@ Channel nodes are used to perform channel manipulations and data type conversion * `in` (colorN or vectorN): the input value or nodename * `index` (integer): the channel number to extract. For colorN streams, use "0" to extract the red channel, "1" for green, "2" for blue and "3" for alpha; for vectorN streams, use "0" to extract the x channel, "1" for y, "2" for z and "3" for w. Default is 0. - - -* **`extractrowvector`**: extract the specified row vector number from a matrixN stream. - * `in` (matrixN): the input value or nodename - * `index` (integer): the row number to extract, should be 0-2 for matrix33 streams, or 0-3 for matrix44 streams. - * **`convert`**: convert a stream from one data type to another. Only certain unambiguous conversions are supported; see list below. @@ -1855,13 +1750,6 @@ Channel nodes are used to perform channel manipulations and data type conversion * `outb`/`outz` (**output**, float): the value of the blue (for color4 streams) or z (for vector4 streams) channel. * `outa`/`outw` (**output**, float): the value of the alpha (for color4 streams) or w (for vector4 streams) channel. - - -* **`separatecolor4`** (NG): output the RGB and alpha channels of a color4 as separate outputs. - * `in` (color4): the input value or nodename - * `outcolor` (output, color3): the RGB channel values. - * `outa` (output, float): the value of the alpha channel. - The following input/output data type conversions are supported by **`convert`**: @@ -1895,13 +1783,6 @@ Table of allowable input/output types for **`combine2`**, **`combine3`**, **`com Convolution nodes have one input named "in", and apply a defined convolution function on the input stream. Some of these nodes may not be implementable in ray tracing applications; they are provided for the benefit of purely 2D image processing applications. - - -* **`blur`**: a convolution blur. - * `in` (float or colorN or vectorN): the input value or nodename - * `size` (float): the size of the blur kernel, relative to 0-1 UV space; default is 0. - * `filtertype` (uniform string): the spatial filter used in the blur, either "box" for a linear box filter, or "gaussian" for a gaussian filter. Default is "box". - * **`heighttonormal`**: convert a scalar height map to a normal map of type vector3. @@ -2324,20 +2205,6 @@ For uniform inputs and tokens whose nodedef description includes an enum list of ``` -#### 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. - -```xml - - ...... - - - -``` - #### Example Custom Nodes Defined by External File Implementations ```xml @@ -2595,69 +2462,6 @@ The Standard MaterialX Library defines the following nodes and node variants ope -### AOV Output 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>. - -```xml - -``` - -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: - -```xml - - - 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: - -```xml - - - - - - - - - - - - - - - - - - - - - -``` - -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. - - - ## Material Nodes Custom nodes that output data types with a "material" semantic are referred to in MaterialX as "Material Nodes". Material nodes typically have one or more "shader" semantic inputs which establish what shaders the material references; previous versions of MaterialX used <shaderref> elements to establish these shader-to-material connections. Material Nodes are declared using the same <nodedef> elements as described above: @@ -2732,26 +2536,6 @@ Creating materials with specific values bound to shader inputs involves instanti Alternatively, and perhaps more usefully, a complete network of multiple shader nodes of different types or for different targets along with a material node to collect them all can be packaged within a nodegraph, and the various inputs of the shader nodes and any other nodes connected to their inputs can be connected to a single material nodedef interface to provide parameter values for the entire multi-shader network. Because nodedef inputs can be referenced by more than one node, a single unified interface could be created for several shaders for different targets, and the networks for those targets could contain input value conversion nodes as needed to handle differences in parametrization or shading methodologies. -#### 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: - -```xml - - - - - - - - - - - -``` - -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. - #### Example Pre-Shader Compositing Material A material to blend between three different surface layers using mask textures. This example also demonstrates the use of the "target" attribute of a shader implementation element to define multiple renderer-specific shaders of the same type referenced within a single material, and the use of interface tokens to define texture filenames. From 596dd23f42ed79e6ecf1c0ecd5983023a879043b Mon Sep 17 00:00:00 2001 From: Doug Smythe Date: Tue, 30 Jul 2024 19:18:34 -0700 Subject: [PATCH 4/5] Move Blur back from Proposals to main Spec --- documents/Specification/MaterialX.Proposals.md | 11 ----------- documents/Specification/MaterialX.Specification.md | 7 +++++++ 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md index af019a51ab..97b37787ba 100644 --- a/documents/Specification/MaterialX.Proposals.md +++ b/documents/Specification/MaterialX.Proposals.md @@ -319,17 +319,6 @@ We have a standard 3d fractal noise, but a 2d variant would be useful as well. -### Convolution Nodes - - - -* **`blur`**: a convolution blur. - * `in` (float or colorN or vectorN): the input value or nodename - * `size` (float): the size of the blur kernel, relative to 0-1 UV space; default is 0. - * `filtertype` (uniform string): the spatial filter used in the blur, either "box" for a linear box filter, or "gaussian" for a gaussian filter. Default is "box". - - -

 

# Proposals: PBR Nodes diff --git a/documents/Specification/MaterialX.Specification.md b/documents/Specification/MaterialX.Specification.md index 7a51dee109..72d04d55fa 100644 --- a/documents/Specification/MaterialX.Specification.md +++ b/documents/Specification/MaterialX.Specification.md @@ -1783,6 +1783,13 @@ Table of allowable input/output types for **`combine2`**, **`combine3`**, **`com Convolution nodes have one input named "in", and apply a defined convolution function on the input stream. Some of these nodes may not be implementable in ray tracing applications; they are provided for the benefit of purely 2D image processing applications. + + +* **`blur`**: a convolution blur. + * `in` (float or colorN or vectorN): the input value or nodename + * `size` (float): the size of the blur kernel, relative to 0-1 UV space; default is 0. + * `filtertype` (uniform string): the spatial filter used in the blur, either "box" for a linear box filter, or "gaussian" for a gaussian filter. Default is "box". + * **`heighttonormal`**: convert a scalar height map to a normal map of type vector3. From b369a3e9ab4bd91f3fde8018684bd8d40abdf613 Mon Sep 17 00:00:00 2001 From: Doug Smythe Date: Fri, 2 Aug 2024 16:05:38 -0700 Subject: [PATCH 5/5] Remove empty Global Nodes section and links to it --- .../Specification/MaterialX.Specification.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/documents/Specification/MaterialX.Specification.md b/documents/Specification/MaterialX.Specification.md index 72d04d55fa..0232074701 100644 --- a/documents/Specification/MaterialX.Specification.md +++ b/documents/Specification/MaterialX.Specification.md @@ -56,7 +56,6 @@ This document describes the core MaterialX specification. Companion documents [   [Noise Nodes](#noise-nodes)   [Shape Nodes](#shape-nodes)   [Geometric Nodes](#geometric-nodes) -  [Global Nodes](#global-nodes)   [Application Nodes](#application-nodes)  [Standard Operator Nodes](#standard-operator-nodes) @@ -664,7 +663,7 @@ MaterialX also supports the following additional attributes for Output elements Source nodes use external data and/or procedural functions to form an output; they do not have any required inputs. Each source node must define its output type. -This section defines the Source Nodes that all MaterialX implementations are expected to support. Standard Source Nodes are grouped into the following classifications: [Texture Nodes](#texture-nodes), [Procedural Nodes](#procedural-nodes), [Noise Nodes](#noise-nodes), [Shape Nodes](#shape-nodes), [Geometric Nodes](#geometric-nodes), [Global Nodes](#global-nodes) and [Application Nodes](#application-nodes). +This section defines the Source Nodes that all MaterialX implementations are expected to support. Standard Source Nodes are grouped into the following classifications: [Texture Nodes](#texture-nodes), [Procedural Nodes](#procedural-nodes), [Noise Nodes](#noise-nodes), [Shape Nodes](#shape-nodes), [Geometric Nodes](#geometric-nodes) and [Application Nodes](#application-nodes). ### Texture Nodes @@ -1119,16 +1118,6 @@ Applications may also reference other renderer-specific named spaces, at the exp -### Global Nodes - -Global nodes generate color data using non-local geometric context, requiring access to geometric features beyond the surface point being processed. This non-local context can be provided by tracing rays into the scene, rasterizing scene geometry, or any other appropriate method. - -Standard Global nodes: - -There are currently no Global Nodes implemented in MaterialX. - - - ### Application Nodes Application nodes are used to reference application-defined properties within a node graph, and have no inputs: @@ -2069,7 +2058,7 @@ Attributes for <nodedef> elements: * `name` (string, required): a unique name for this <nodedef> * `node` (string, required): the name of the custom node being defined * `inherit` (string, optional): the `name` of a <nodedef> to inherit node definitions from; the output types of this nodedef and the inherited one must match, and the input/output definitions of this nodedef will be applied on top of those in the inherited-from one. -* `nodegroup` (string, optional): an optional group to which this node declaration belongs. Standard MaterialX nodes have `nodegroup` values matching the titles of the section headings in which they are described, e.g. "texture2d", "procedural", "geometric", "global", "application", "math", "adjustment", "compositing", "conditional", "channel", "convolution", or "organization". +* `nodegroup` (string, optional): an optional group to which this node declaration belongs. Standard MaterialX nodes have `nodegroup` values matching the titles of the section headings in which they are described, e.g. "texture2d", "procedural", "geometric", "application", "math", "adjustment", "compositing", "conditional", "channel", "convolution", or "organization". * `version` (string, optional): a version string for this nodedef, allowing usage of a node to reference a specific version of a node. Version strings should be of the format "_major_[._minor_]", i.e. one or two integer numbers separated by a dot (the minor version is assumed to be "0" if not provided). If there are multiple nodedefs for the same `node` and `target` with the same combination of input and output types, they must each specify a `version`. * `isdefaultversion` (boolean, optional): If true, then this nodedef should be used for node instances which do not request a specific version. Specifying `isdefaultversion` "true" is only required if there are multiple nodedefs for a node declaring a `version`, and it is not permissible for multiple nodedefs for the same `node` and `target` with the same combination of input and output types to set `isdefaultversion` "true". Defaults to "false". * `target` (stringarray, optional): the set of targets to which this nodedef is restricted. By default, a nodedef is considered universal, not restricted to any specific targets, but it is possible that certain targets may have different parameter names or usage for the same node.