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.

[ld-kerley]

This table is missing the following nod definitions

• ND_noise2d_color3
• ND_noise2d_color4
• ND_noise2d_color3FA
• ND_noise2d_color4FA
• ND_noise2d_vector2FA
• ND_noise2d_vector3FA
• ND_noise2d_vector4FA

The corresponding node definitions are also missing from noise3d and fractal3d

[ld-kerley]

Missing "Accepted Values" derived from the enum values for style.

Also for worleynoise3d.

[ld-kerley]

The default value specified here is not actual defined in the data library - this may be in a bug in the data library that we should fix separately, but currently this specification statement does not accurately reflect the data library as it stands.

Similarly for unifiednoise3d

[ld-kerley]

There is no ND_multiply_matrix33FA or ND_multiply_matrix44FA.

This looks like a copy/paste bug to include the "or float" here.

[ld-kerley]

should be "matrixNN"

[ld-kerley]

suggest "closest, linear, cubic" instead of "closest,linear,cubic"

[ld-kerley]

suggest "closest, linear, cubic" instead of "closest,linear,cubic"

[ld-kerley]

suggest removing additional spaces in table.

[ld-kerley]

suggest removing additional spaces in table.

[ld-kerley]

suggest removing additional spaces in table.