From 0124dc940e1146eaf94fd5767907f63479fe7250 Mon Sep 17 00:00:00 2001 From: Jonathan Stone Date: Wed, 12 Nov 2025 17:03:42 -0800 Subject: [PATCH 1/3] Specification proposal for `template` elements This changelist proposes the addition of `template` elements to the MaterialX specification, along with an extension of `token` elements in the context of a `typedef`. Accompanying the new specification language is a proposed implementation, outlining a concrete approach that automatically expands templates within existing MaterialX API calls, without impacting downstream clients such as OpenUSD. --- .../Specification/MaterialX.Proposals.md | 109 ++++++++++++++++++ 1 file changed, 109 insertions(+) diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md index 4548bda33a..bd4e03a6d2 100644 --- a/documents/Specification/MaterialX.Proposals.md +++ b/documents/Specification/MaterialX.Proposals.md @@ -157,6 +157,115 @@ Materials can inherit from other materials, to add or change shaders connected t 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. + +### TypeDef Token Elements + +TypeDef token elements allow the definition of value strings with a consistent meaning across types, e.g. a `half` value that corresponds to "0.5" for the `float` type and "0.5, 0.5, 0.5" for the `vector3` type. Their primary use case is in the expansion of `template` elements, as described in the next section. + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +### Template Elements + +Template elements allow a single template pattern to be used in instantiating an arbitrary number of elements at runtime, with each reference to the provided `key` being replaced with one of the corresponding strings in the `values` array. Each element within the scope of the `template` will be instantiated separately for each string in the `values` array. + +References to the template `key` are expressed as the string value of the `key` bracketed by the `(` and `)` characters, e.g. `(keystring)`. Substitution of key-value pairs takes precedence over any other supported substitutions within the scope of a `template` element. + +To support generic typed values, TypeDef `token` strings may be used in place of any literal value within a `template` element, using the same bracketing syntax as template keys. At template expansion time, any typed value that corresponds to a TypeDef `token` will be replaced with the corresponding literal value for the given `token` and type. + +Template elements may be nested to any depth, allowing for efficient authoring of combinatorial element templates. + +The following example show how the full set of `nodedef` and `nodegraph` variations for the `contrast` node in MaterialX would be expressed using two `template` elements. + +```xml + + + +``` + +#### Proposed Template Implementation + +When a document containing `template` elements is loaded through the MaterialX API, its templates are automatically expanded to their full form through a built-in `Document::expandTemplates` method. This allows the document to be authored and stored on disk in its clearest and most compact form, while MaterialX runtimes and downstream clients can assume templates are fully expanded at load time, allowing them to operate as if no templates are present. + +For an initial implementation of this feature, a proposed approach is to implement the `TemplateElement` class, the TypeDef form of the `Token` class, and the `Document::expandTemplates` method in the MaterialX runtime, and to add a single example of a `template` to the MaterialX data libraries (e.g. the `contrast` example above), in order to prove out the syntax and logic before committing to a full data library upgrade. This represents roughly 2-4 days of work for a developer that is familiar with the MaterialX C++ codebase. + +An important property of this proposed implementation is that downstream clients such as OpenUSD will require no changes to support it, as the template expansion logic will be fully contained within existing MaterialX API calls. Clients that define custom MaterialX nodes will have the option of using `template` elements for efficiency and clarity, but will be under no obligation to do so, and they can effectively ignore the presence of template functionality if they choose. + +

 

# Proposals: Stdlib Nodes From 392118a0de2a6b33043c44c605bbb356e27f3e46 Mon Sep 17 00:00:00 2001 From: Jonathan Stone Date: Thu, 13 Nov 2025 15:40:58 -0800 Subject: [PATCH 2/3] Clarify the parallel with `Document::upgradeVersion` --- documents/Specification/MaterialX.Proposals.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md index bd4e03a6d2..6ad0f96377 100644 --- a/documents/Specification/MaterialX.Proposals.md +++ b/documents/Specification/MaterialX.Proposals.md @@ -259,7 +259,7 @@ The following example show how the full set of `nodedef` and `nodegraph` variati #### Proposed Template Implementation -When a document containing `template` elements is loaded through the MaterialX API, its templates are automatically expanded to their full form through a built-in `Document::expandTemplates` method. This allows the document to be authored and stored on disk in its clearest and most compact form, while MaterialX runtimes and downstream clients can assume templates are fully expanded at load time, allowing them to operate as if no templates are present. +When a document containing `template` elements is loaded through the MaterialX API, its templates are expanded to their full form through a built-in `Document::expandTemplates` method, which is invoked automatically at load-time in the same fashion as the existing `Document::upgradeVersion` method. This allows the document to be authored and stored on disk in its clearest and most compact form, while MaterialX runtimes and downstream clients can assume templates are fully expanded at load time, allowing them to operate as if no templates are present. For an initial implementation of this feature, a proposed approach is to implement the `TemplateElement` class, the TypeDef form of the `Token` class, and the `Document::expandTemplates` method in the MaterialX runtime, and to add a single example of a `template` to the MaterialX data libraries (e.g. the `contrast` example above), in order to prove out the syntax and logic before committing to a full data library upgrade. This represents roughly 2-4 days of work for a developer that is familiar with the MaterialX C++ codebase. From d820206be1a1a6409c88e92e177343c77d24e7c8 Mon Sep 17 00:00:00 2001 From: Jonathan Stone Date: Sun, 16 Nov 2025 11:50:34 -0800 Subject: [PATCH 3/3] Use standard `token` bracketing for TypeDef tokens --- documents/Specification/MaterialX.Proposals.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documents/Specification/MaterialX.Proposals.md b/documents/Specification/MaterialX.Proposals.md index 6ad0f96377..e646ceb4b5 100644 --- a/documents/Specification/MaterialX.Proposals.md +++ b/documents/Specification/MaterialX.Proposals.md @@ -160,7 +160,7 @@ Inheritance of material-type custom nodes is also allowed, so that new or change ### TypeDef Token Elements -TypeDef token elements allow the definition of value strings with a consistent meaning across types, e.g. a `half` value that corresponds to "0.5" for the `float` type and "0.5, 0.5, 0.5" for the `vector3` type. Their primary use case is in the expansion of `template` elements, as described in the next section. +TypeDef token elements allow the definition of value strings with a consistent meaning across types, e.g. a `half` value that corresponds to "0.5" for the `float` type and "0.5, 0.5, 0.5" for the `vector3` type. References to TypeDef tokens are restricted to typed `value` attributes, and are bracketed by the `[` and `]` characters, e.g. `[half]`. Within a typed `value` attribute, TypeDef token substitutions are applied before all other token substitutions. ```xml @@ -201,7 +201,7 @@ Template elements allow a single template pattern to be used in instantiating an References to the template `key` are expressed as the string value of the `key` bracketed by the `(` and `)` characters, e.g. `(keystring)`. Substitution of key-value pairs takes precedence over any other supported substitutions within the scope of a `template` element. -To support generic typed values, TypeDef `token` strings may be used in place of any literal value within a `template` element, using the same bracketing syntax as template keys. At template expansion time, any typed value that corresponds to a TypeDef `token` will be replaced with the corresponding literal value for the given `token` and type. +To support generic typed values, TypeDef `token` strings may be used in place of any literal value within a `template` element, bracketed by the `[` and `]` characters. At template expansion time, any typed value that corresponds to a TypeDef `token` will be replaced with the corresponding literal value for the given `token` and type. Template elements may be nested to any depth, allowing for efficient authoring of combinatorial element templates. @@ -210,9 +210,9 @@ The following example show how the full set of `nodedef` and `nodegraph` variati ```xml