SdrRegistry as a source of truth

[JamesPedFoundry]

Summary:

I recently joined the ASWF OpenUSD WG to raise some high level questions around the SdrRegistry, here are our notes for discussion.

As a DCC vendor, we need to create UI and UX that could be universally understood and with customization that can be defined by the creator (third-party renderers). The Schema and shader registries do a great job at providing what’s currently available. Historically, we have used our own plug-in system, for which creators have written plug-ins to provide information about how to display and categorize the parameters. We have noticed different DCC’s going many different routes in terms of how to make this information present from USD. Since these are all different, we’d like to propose possible ways to consolidate into the SdrRegistry the required information. In this issue we’ll outline our current hurdles with the SdrRegistry and our thoughts on what we’d need for presentable UI/UX, which could hopefully be replicated across the various industries that will need to display USD data. I will be referring to behavors and uses of the SdrRegistry that are being used already, but also as something we’d like to encourage and ensure continues. I will also refer a few times to some example names, these are to provide some context and may not be accurate.

Shaders

Ordering of Shaders

We find that the order of shaders returned by GetShaderNames or GetShaderIdentifiers can change.

• Having looked at the code we understand that changing this would not be trivial.
  Ordering alphabetically may also be OK (we can do this on our end), but the next few sections will explain why that isn’t yet the answer.

Category

We are unable to determine, with multiple Sdr plug-ins registered at the same time, which renderer registered which shaders. Therefore, the end user is left with a large list of every single shader to sift through, without customized logic - which may break if third-parties update other fields.

• We believe this is a perfect point for renderers to provide their creators name as they’d like it to show in the UI. Potentially with name-spacing if they wished to group up elements. This could be delimited by : or ., and would allow us to create submenus or utilize the initial root name to categorize shaders; such that the end user doesn’t end up with an endless list of shaders. This problem will become more prevalent with MaterialX, since it has a very large shader count, categorization will become paramount. We could then use the primary prefix as a “renderer selection”, and utilize the following suffixes to provide menus.
  • For example:
    • UsdPreviewSurface.GetCategory() = Usd:UsdPreviewSurface
    • ND_mult_float.GetCategory() = mtlx:math
    • ND_plus_float.GetCategory() = mtlx:math or mtlx:math:plus or mtlx:math:arithmetic
    • ND_sin_vector3.GetCategory() = mtlx:math
    • ND_worleynoise3d_vector3.GetCategory() = mtlx:noise

Shader Type

Determining what the type of a shader is, whether it’s for lighting or surface/volumetric materials.
- Similar to multiple shaders from many creators, it’s hard to determine what is a light compared to a surface or a volume shader (or otherwise).
- Could use “Departments” here to re-use the API, although I’m not convinced here.
- Context could be used, I have seen this provide some uses but, again, naming is inconsistent. Open to ideas.

Knowing the Prim/API Schema to create.

Given we use the SdrRegistry for authoring Prims, it is difficult to discern the correct schema(concrete or otherwise) to use.

• We are able to work this out for the most part, however a system where in the Metadata, schemas were stored could provide a more solid and robust definition. For example a RectLight would provide the “concreteSchema”: “RectLight” whereas MeshLight would provide ”apiSchema”: "MeshLightAPI”. This would be similar to the already implemented apiSchemaAutoApplyTo Metadata.
• Order of precedence likely being apiSchemaAutoApplyTo -> concreteSchema -> apiSchema
• Alternatively, if there was a base Light Concrete and API schema, we could then look at descendents of this to get the available Schemas.

Knowing possible ancillary accompanying schemas

Some shaders, like RectLight and DiskLight can have accompanying API schemas ShapingAPI and ShadowAPI, whereas other shaders DistantLight only make use of ShadowAPI. It would be nice to know what other possible API schemas could apply to the Prim containing this shader, similar to above, when creating Prims from this data set.
Typically the Shaders inputs do have the inputs related to the API schemas mentioned; would be nice to know the schema they’d expect the Sdf data to come from.

Metadata

We make strong use of a few key pieces of metadata, that I’d like to spread knowledge of.

• apiSchemaAutoApplyTo: describes what the shader auto applies to when authoring.
• SdrPropertyMetadata->SdrUsdDefinitionType, describes the conversions that may need to occur between USD attribute type and Hydra.

UsdPreviewSurface in particular

Looking at the definitions of UsdPreviewSurface and its accompanying shaders, there’s a lot if info in the shaderDefs.usda. However, that appears not to be translated into the SdrRegsitry. I’m not entirely sure if this is a build issue on our end or a different bug I should raise/look at?

Inputs/Outputs

Pages

• Use of Pages for specifying grouping of parameters for easy categorization.
  • These exist, so again more of a reminder, delimited by ..
  • if the delimiter isn't specified yet, I'm keen for either . or :.

Ordering

Ideally (similarly to shaders) Ordering of inputs/outputs should be determined by the plug-in and not changed by the registry.

Outputs

• This is more just a general request to creators, please make sure outputs are specified and tightly typed.
• This particularly is the case with shaders which can output a vector3, or a single component. E.g color4f, typically can also have output fields for each channel. We would like to request these are explicitly stated, and that there is no confusion around whether these should be implicitly inferred. (this way there can be no confusion where this splitting of components cannot be applied).

Help

• As part of GetHelp() at the various levels (shader/input/output).

Widgets

For a lot of types, we can infer a widget, however there are a lot of values which could be presented in a few different ways. For some widget types it is important to specify min/max values.

• There is GetWidget. I’d like to suggest we define a list of Tokens to use. My current suggestion is to utilize naming close to QtWidgets, I believe that is mostly the case
• For Min/Max values, I believe these could be stored in GetHints, or GetOptions. These would be soft limits, softMin softMax or similar to make it obvious that these values can be exceeded by typing in different values, or could be ignored by UI/UX if required. Again, I think this just needs some pre-defined tokens such that terms are “universally”.

Conditional visibility of properties

I have also noticed some shaders utilizing visual conditional operations, which is excellent.
I also realise that this comes from a USD plug-in built specifically for Katana, so this may be unique and explain why it uses Katana’s conditional Visibility syntax. However, the use case for conditional visibility is likely not unique to Katana.
For those that do not know what these are, it allows a variety of operations to happen to decide whether certain properties should be shown to the user. In some cases properties are only relevant if others are set to certain values.

• One example:
  {'conditionalVisValue': '0', 'conditionalVisPath': '../../Glass/Advanced/mwWalkable', 'conditionalVisOp': 'equalTo'}.
  • This is great for us, since this matches Katana’s conditional visibility settings(Widgets and Hints — Katana Developer Guide, however, if I’m putting my “Universal” hat on, it could be that conditionalVisPath could specify the name of the input property more directly e.g {'conditionalVisValue': '0', 'conditionalVisPath': 'mwWalkable', 'conditionalVisOp': 'equalTo'}.

Closing Thoughts

A lot of the issues described above don’t necessarily require a lot of code changes to USD itself, likely a little documentation and examples, along with extra Tokens to nudge plug-in authors to more universal terms. We also believe that some of this could be re-used/utilized for schemas as well. I believe this was part of a “limits working group” (at least for min/max values), so I will not dive deeper into that here.

There’s a few suggestions for a list of tokens to be used and defined in USD, this wouldn’t necessarily be the only list available, but would at least provide some shared naming to make it easier to convert between naming conventions.

Again this is essentially a long list of challenges we have faced using the SdrRegistry as our source of truth for registered shaders for both lights and materials. We’re more than happy to adjust the above suggestions (since they are merely thoughts/suggestions) and work with the USD community to try and bring some consistency to how Shaders are handled for UI/UX.

Thanks for reading, and apologies it was so long! Happy to provide examples in cases where the descriptions fall short.
James

[jesschimein]

Filed as internal issue #USD-10809

(This is an automated message. See here for more information.)

[spiffmon]

Thank you @JamesPedFoundry - we are actively discussing this internally right now!