Skip to content

Proposed Spec Clarification : Input Nodes / Interface References #2814

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kwokcb wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Proposed Spec Clarification : Input Nodes / Interface References #2814

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion documents/Specification/MaterialX.Specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -612,7 +612,33 @@ Unless specified otherwise, all inputs default to a value of 0 in all channels f

Standard MaterialX nodes have exactly one output, while custom nodes may have any number of outputs; please see the [Custom Nodes](#custom-nodes) section for details.

### Input Nodes

Input nodes (<input>) may be defined at the root level of a MaterialX document. The input values of these nodes are considered to be part of the interface of the document.
Copy link
Copy Markdown
Contributor Author

@kwokcb kwokcb Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unsure what the "proper" name is for this so have called them "input nodes".

Copy link
Copy Markdown
Contributor

@dbsmythe dbsmythe Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To me, a "Node" is something that would be shown as a standalone block in a graph editor; earlier in the document (within the "Nodes" section), they are referred to as "Input elements", as they are children of the node element.
If we want to support <input>s as a root-level node, maybe we should clarify that "Input nodes may only be placed at the root level of a document", although this then immediately causes confusion about <input> elements placed immediately within a node (as has always been allowed).
Further thought on wording is required.


Input ports on nodes or nodegraphs may referenced input nodes at the same scope as the node or nodegraph by specifying the name of the input node as the value of the `interfacename` attribute of the port.
Copy link
Copy Markdown
Contributor

@dbsmythe dbsmythe Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo: "referenced" should be "reference".


```xml
<nodegraph name="nodegraph">
<input name="graph_input" type="color3" interfacename="root_input" />
</nodegraph>
<add name="add" type="color3">
<input name="in1" type="color3" interfacename="root_input" />
<input name="in2" type="color3" value="0, 0, 0" />
</add>
<input name="root_input" type="color3" value="0, 0, 0" />
```
Comment on lines +621 to +630
Copy link
Copy Markdown
Contributor

@dbsmythe dbsmythe Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ordering of elements in this example is confusing- for clarity, the "root_input" <input> should be declared first, then the <add>, and then the <nodegraph>.


Input nodes may not be connected to the output of any node or nodegraph.

```xml
<add name="node_reference" type="color3" />
<nodegraph name="nodegraph_reference" />
<input name="input_node_reference" type="color3" value="0, 0, 0" />
<input name="input_node_1" type="color3" interfacename="input_node_reference" />
<input name="input_node_2" type="color3" nodename="node_reference" />
<input name="input_node_3" type="color3" nodegraph="nodegraph_reference" />
```
Comment on lines +632 to +641
Copy link
Copy Markdown
Contributor

@dbsmythe dbsmythe Mar 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm assuming that by "Input nodes", you mean "Root-level input nodes", as we're only adding Input "nodes" at the root level, other <input> semantics within nodes and nodegraphs are unchanged from previous syntax.
Given that, I am confused about this example: the text says that input nodes may not be connected to the output of any node or nodegraph (which sounds correct to me), but then the example shows input nodes with exactly that kind of prohibited connection.


## Node Graph Elements

Expand Down Expand Up @@ -1193,7 +1219,11 @@ A **compound &lt;nodegraph>** element may specify one or more child &lt;input> a
</nodegraph>
```

A compound nodegraph provides a set of named input and output connection ports which may be referenced by its contained nodes using `interfacename` attributes, and interface token names whose values may be substituted into filenames used within the nodegraph; nodes within this &lt;nodegraph> adopt the context of that nodegraph. The &lt;input>s and &lt;token>s of a compound nodegraph may also be connected to other nodes outside the &lt;nodegraph> at the same scope as the &lt;nodegraph> itself using `nodename` attributes; inputs of nodes within a compound nodegraph may only be connected to the outputs of other nodes within the same compound nodegraph, or to the input connection ports using interfacename. This is in contrast to a &lt;backdrop> node whose contained nodes connect directly to nodes outside the backdrop at the same level of context without going through an intermediate named &lt;input>. A &lt;nodegraph> element of this form may specify the same float `width` and `height` and boolean `minimized` attributes as &lt;backdrop> nodes. Inputs of other nodes, or the inputs of a compound nodegraph, can connect to an output of a (different) compound nodegraph using a `nodegraph` attribute (and for multiple-output compound nodegraphs, an `output` attribute as well) on a node's &lt;input>.
A compound nodegraph provides a set of named input and output connection ports which may be referenced by its contained nodes using `interfacename` attributes, and interface token names whose values may be substituted into filenames used within the nodegraph; nodes within this &lt;nodegraph> adopt the context of that nodegraph.

The &lt;input> ports of a compound graph may reference &lt;input> nodes outside the &lt;nodegraph> at the same scope as the &lt;nodegraph> itself using `interfacename` attributes, but may not reference sibling &lt;input> ports within the nodegraph.
Copy link
Copy Markdown
Contributor Author

@kwokcb kwokcb Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only this part is new.

Copy link
Copy Markdown
Contributor

@dbsmythe dbsmythe Mar 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We may want to consider a specification-document-wide review of the usage of the terms "element" vs. "port", as sometimes <input>s are referred to as "elements", sometimes (now) as "nodes", and sometimes as "ports". I think this only applies to <input>s and <output>s (where the term "port" makes sense to use), not globally.


The &lt;input>s and &lt;token>s of a compound nodegraph may also be connected to other non-input nodes outside the &lt;nodegraph> at the same scope as the &lt;nodegraph> itself using `nodename` attributes; inputs of nodes within a compound nodegraph may only be connected to the outputs of other nodes within the same compound nodegraph, or to the input connection ports using interfacename. This is in contrast to a &lt;backdrop> node whose contained nodes connect directly to nodes outside the backdrop at the same level of context without going through an intermediate named &lt;input>. A &lt;nodegraph> element of this form may specify the same float `width` and `height` and boolean `minimized` attributes as &lt;backdrop> nodes. Inputs of other nodes, or the inputs of a compound nodegraph, can connect to an output of a (different) compound nodegraph using a `nodegraph` attribute (and for multiple-output compound nodegraphs, an `output` attribute as well) on a node's &lt;input>.

It is permissible to define multiple nodegraph- and/or file-based implementations for a custom node for the same combination of input and output types, as long as the specified `version`/`target`/`format` combinations are unique, e.g. one implementation for target "oslpattern" and another for "glsl", or one "osl" target with `format="shader"` and another with `format="fragment"`. It is allowable for there to be both a &lt;nodegraph> and an &lt;implementation> for the same nodedef target/version, with the &lt;implementation> generally prevailing in order to allow for optimized native-code node implementations, although ultimately it would be up to the host application to determine which implementation to actually use.

Expand Down