Add API to allow input reordering on node graphs

[kwokcb]

Workflow Motivation

In order for users to specify interface ordering for node graphs they need to re-order the storage order of child inputs. Additionally, when creating new definitions (nodedef) they may which to specify the ordering of child inputs as part of definition publishing.

Proposal

Provide a simple atomic API to allow for inputs on node graphs to be re-ordered without affecting non-input child ordering.
The proposed API name is: NodeGraph::setInputOrdering() where a list all input names specifies the desired ordering.

[meshula]

Would this need some work on the usd side to capture the ordering somewhere? Perhaps UsdUI or something?

[kwokcb]

Hi @meshula,
This doesn't add any additional metadata to specify the UI ordering. It's just a way to re-order inputs on a nodegraph.

Does USD already have separate specifiers for UI ordering (e.g. is this this stacking order in UsdUITokenType ?
I'm guessing from your comment it does not, but If it does then it might be worthwhile to look at the equivalent support for MaterialX as a related but separate change.

[meshula]

Stacking order relates to the screen depth of nodes (this node should appear over that node if they overlap).

Reading the mx code, I see that childOrder is not a user imposed reordering of the nodes, but rather encodes a construction order. Since hdMtlx iterates that list, there's no reordering hints necessary at that end as order is implicit in that loop.

✅ #does-it-usd

[kwokcb]

Thanks for the explanation about stacking order.

To confirm your summary of childOrder:

• Yes this is construction order but can serve double duty as "interface order" for inputs (not nodes).
• This user ordering is optional for a compound graphs but from the various DCCs I've seen it's pretty well what folks are using for the UI. I've seen that Maya additionally allows for input re-ordering to modify user ordering.
• When it comes to creating a new definitions from such a graph the input ordering is taken as a definition's input ordering so becomes "fixed" at that time -- i.e. if you change the ordering the definition is actually a different one.

Thus this utility to change construction ordering is being proposed to help support both the above workflows for user ordering.

---

That all said there is nothing required on the usd side. If at some point in the future definitions or graphs have additional meta-data to specify input ordering than this can be brought up.