Initial AOUSD formatting proposals

[jstone-lucasfilm]

This changelist contains an initial set of formatting proposals for the Standard Nodes specification, organized by the AOUSD Materials Working Group.

[dbsmythe]

Generally speaking, I really like this new proposal: it's quite a bit easier to read, and the increased consistency of formatting and the use of the tables for inputs improves the ease of finding specific information.

A few notes:

1. The first column in each table should be labeled "Input" or "Input name" rather than "Port", to be consistent with the terminology used elsewhere in the Specification.
2. We need to ensure that all descriptive and clarifying text that appeared in the legacy-format document is replicated in the new-format document somewhere: for example, for the input node, the additional text for the "layer" and "default" input descriptions is omitted, while for the "luminance" node, there is no notation of what the given default value for "lumacoeffs" actually represents (they are the ACEScg/ap1 luma coefficients). I like the conciseness that the current abbreviated Descriptions provide, so I would suggest adding that extra text as separate notes above or below the table, similar to how the extra descriptive notes are presented for the "file" and "filtertype" inputs (although in the case of "filtertype", the same information about acceptable values is currently being presented twice: once in the table, and again in the separate leading paragraph).
3. We should clean up the capitalization and punctuation of the node and input descriptions, e.g. always capitalize the first word in a node or input description (the descriptions for "atan2" and all the logical operator nodes are currently not) and end with a period ("ramplr" is missing the ending "."). We should probably also be more consistent about whether the description starts with "Outputs ..." or "Returns..." or not.
4. If a default value is of type string, I think the value should be shown within double-quotes.
5. The font size currently used for node name headers is a bit large (at least on my display), appearing larger than sub-section headers, e.g. in the "Blend Nodes" subsection, the "plus" and "minus" node name text is larger than the "Blend Nodes" header font above them; this makes it more difficult to see the sectional organization of the document.

Some things we can discuss:

• Should there always be an "Accepted Values" column in the tables, or (as is the case now) only when one of the inputs has a requirement about allowable values?
• In the legacy-format document, I tried to consistently identify with "(NG)" which nodes were implemented as nodegraphs in the standard library, to distinguish them from nodes that needed native implementations in each target. Do others find value in that, or does adding "(NG)" just add noise to the descriptions? There are a few nodes like "tiledimage" that were marked with "(NG)" in the legacy-format document that have lost their "(NG)" designation in the new-format document.
• Having the widths of the tables change from one node to the next is a bit visually distracting: is there a Markdown syntax that could allow more consistent table presentation and column widths?
• If we are writing up a normative description, should there be a standard way to express in this document what the exact math or algorithm (pseudo code) is expected to be? For the simple math operators this may be overkill, but for nodes like "range", "rgbtohsv" or "colorcorrect", this could be very handy.

I would also suggest that while we're in this transition period, we should keep the original-format version around e.g. "MaterialX.StandardNodes.legacyformat.md" or something like that; once we're happy with the new format and are certain that no information from the legacy document is lost, the legacy-formatted version could be removed in a separate PR.

[ld-kerley]

I've made some good progress on the automatic generation of this doc.

The comments below are the outstanding differences. Mainly either minor formatting changes, or places that look like small errors introduced in the human refactoring.

[anderslanglands]

@dbsmythe regarding your questions:

1. We use "Port" here as it covers both inputs and outputs so felt like it needed a new word and "Port" is somewhat common elsewhere. Would you be OK with this is we added it to the front of the spec explaining clearly what is meant here?

For Accepted Values, we tried with it always there and it was pretty ugly, so we're inclined to keep it optional. We can try again if we manage to figure out a way of getting the table widths to always be 100% as maybe that will be less distracting .
We're explicitly not differentiating node graphs as from the POV of a user (or clean-room implementer) this is an implementation detail.

There normative description does indeed use equations to unambiguously define the operations of the nodes. In the cases where that would be onerous (e.g. fractals) we'll probbaly use pseudo-code. It sounds like you might be asking to include the normative descriptions in the MaterialX spec as well?

[dbsmythe]

@anderslanglands Responses to your responses:
Re: using "port" to cover both inputs and outputs: I like this idea, and would support adding this term to the paragraph describing Nodes in the MaterialX Spec's "Definitions" section, and editing the Spec to use "port" wherever "inputs and outputs" are used together. I'll try to take a crack at this.

Re: accepted values optional vs always: as long as "accepted values" are shown wherever they make an important difference, I'm okay with leaving "accepted values" empty if any value of the type for that input is acceptable, and removing that column if all ports for a node can accept any value.

Re: indicating nodegraph vs native implementations: I agree this is generally an implementation detail, though I thought it would be useful to those implementing new targets to know which nodes they'd need to implement explicitly for the target and which "come for free" via a nodegraph implementation. But I'll defer to the community if this detail isn't worth the added clutter to the tables.

Re: adding equations/pseudocode descriptions to the Spec: I think this would worthwhile in some instances where there could be confusion, but would just be added clutter in most cases. If the normative descriptions become part of (or are tightly linked to) the Spec, then no additional equations/pseudocode descriptions would be necessary.

[ld-kerley]

@dbsmythe - Firstly thanks for all the feedback - I know you're super busy with production.

Regarding annotating the nodegraphs - I would pose that anyone who is implementing a new target would also be required to investigate the actual data library files themselves, and so would "hopefully" have the expertise to understand which nodegraph elements they could choose adopt "for free". I'll note that implementors are free to choose to reimplemented, existing nodegraphs themselves as well. The specification is complete enough to stand alone, without any dependence on the data library.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[dbsmythe]

Thanks- this all looks good as a solid starting point- I have some nitpicky formatting and clarifying change thoughts, and a few nodes haven't yet been updated to the new table-style format, but I think the best way forward would be to approve this, then I'll offer up my suggested changes as a follow-on PR to this.

Huge thanks to the AOUSD group for their efforts in this update.

[jstone-lucasfilm]

Thanks @dbsmythe, and let's go ahead and merge this as a foundation for your upcoming improvements.

Thanks to my colleagues at the AOUSD Materials Working Group, whose work made these improvements possible!