Sublayer vs. Reference vs. Payload

Community USD
1

Hi.
I have some unclarity about Sublayering vs. Referencing vs. Payloading.
The general concepts and differences are clear to me.
But I have a few things I am confused about…

Let’s start with an Asset Component.
In the ASWF USD Asset Structure Guidelines there is the following section:

Additional Layers/Contributors

Models which incorporate work from other departments or disciplines, can follow the materials pattern and reference their layer into the asset’s root file layer. It may also be helpful to define a scope for any unique/new contributions to the asset.

For example, in the case of a campfire, which has asset-based lighting and volumetric effects:

/campfire        (xform) ← Component Kind
    /fx          (scope)
    /geo         (scope)
    /lgt         (scope)
    /mtl         (scope)
/__class__       (class)
    /campfire    (class) ← Inherited by /<component>

All other layer contributions to an asset should be crate files (binary .usd or .usdc) and named after their role/contribution, which get referenced into “payload”. The ordering of these extra layers depends on their function, and their place in the workflow-timeline. Generally, the layers build on one another, so that later disciplines/contributors can use and/or override existing work. This is why geometry is at the bottom, then materials. And is why “lighting” is usually one of the last layers to contribute to USD assets/shots.

TODO:

  • When should individual layers be sublayered vs referenced in asset structures?

Unfortunately it’s exactly the “TODO” section I am confused about.
Normally I would assume sublayering the different department contributions in the correct order is the way to go. This also seems to work fine.

But there is also this section:

Composition & File Organization

…

  • Layers are usually divided by department/work/contribution/content
    • A payload requires an external file, but otherwise layer separation is mostly about organizing work as needed
  • Individual element layers of a component are generally either referenced or sublayered together.
    • Referencing helps keep opinion strength a bit more predictable, as each contribution is the “R” in LIVRPS

So here it is suggested to reference the layers instead of sublayering them due to strength ordering reasons. SideFX also follows this recommendation in their default Solaris / USD Component Builder.

However, when using referencing instead, it works whenever a new layer is adding a new element. But when a new layer should overlay / override a previous layer (like a CFX cloth sim loop in the asset_cfx.usd layer overlay the asset_geo.usd layer, referencing does not work for me. The opinion seems to be too weak. When sublayering this works as expected, following the local layer stack ordering.

Am I doing something wrong here? Or is sublayering the only and proper way to achieve this?

If the later is true, what is meant by:

Referencing helps keep opinion strength a bit more predictable, as each contribution is the “R” in LIVRPS

For me it feels a bit like the opposite actually. And also referencing feels very counter intuitive here. But there seems to be a reason why also SideFX did it.

Might I get into trouble with variants (or nested variants etc.) within the asset and or payloading then for example?

Is there maybe a reason to use referencing in the asset component context, and sublayering in the scene context?

Now a similar question regarding payloading…
Which is just a special type of reference, and even lower in the LIVRPS so it probably makes sense the behavior is similar.

Let’s say I have an assembly that loads multiple asset components (which contents are behind a payload).
This is done in the assembly_layout.usd layer.
Now I want to add some small geometry to the assembly (let’s say a box) and modify an existing asset geometry (in Houdini via the SOP Modify LOP). I do that in the assembly_geo.usd
As this is not contained in a proper component, it’s not payloaded.
Now I want to make sure to also payload it, so I payload the layer instead of sublayering it within the root assembly.usd layer.

Now again, the additional geometry (the box) is visible as expected and also can be unloaded.
But the geometry modification that should be overlayed has no effect, also when payloads are loaded.

A similar scenario would be in the shot level with an FX department layer.
It adds a Pyro Explosion.
And overlays transforms from and RBD sim over a building asset.
If I would payload the FX department layer the RBD overlay wouldn’t work. The pyro sim would.

Interestingly, whenever sublayering an overlay (like the RBD sim over the building asset component), unloading (payloads) in the viewport works just fine, as the root component is unloaded, and thus the overlays that have opinions about prims inside the root are also invisible.

However when unloading (payloads) on the stage (not just the viewport), they still show up, and thus have to be fully loaded.

Am I right with the assumption / “rule of thump” that whenever I add new elements in a layer, I can payload them (the individual sublayers like the pyro_fx_cache.usd)?

And when I want to overlay another layer (like the RBD sim) I can not not use payloading at all? (Yes, in these cases it will still work in the viewport, but not in the scene graph.)

Help would be much appreciated.
Thanks very much!

2

Hi @adrianmeyerart , there’s alot in there! Regarding subLayering vs referencing, we have a FAQ topic that targets this question precisely!

As to why referencing did not seem to be working for you, an example of your referencing structure would be helpful. I am positive that if you make a list of references on the component root prim that lists the target layers in strength order, you will get the overriding you expect.

The “predictability of opinion strength” tends to be less of a concern at shot/sequence-level (for us at least) because variantSets tend to be defined only inside referenced assets, not in the shot layerStack.

For your payload question… I think it depends on what is actually getting authored into the RD overlay layer that you are sublayering. If it contains only “over” prims, then those prims will indeed still be composed into the stage when you unload, but only as undefined opinions that will not result in any imaging. This is how we structure data in our own pipeline.

But if the RBD layer actually contains def’s then imageable prims will still be present after you unload. I wouldn’t expect a simulator to output defs for an RBD sim, but maybe that’s something that’s configurable in Solaris?

3

Hi @spiff ,
thanks a lot for the super quick reply!

Regarding subLayering vs referencing, thank you for pointing me to the FAQ section. This indeed exactly answers this question and I had overseen it.
(maybe worth just copying that section into the mentioned empty ASWF Asset Guidlines section)?

And regarding my confusion why referencing the layers did not work for me, I also figured that out now. It’s of course important to reference each layer at the same level, and not nested.
Questions left…

  1. As variants are pretty much always wanted for a component model, referencing together the different department layers then seems like the only option correct?
  2. Same for an assembly model, variants are also a key feature here that would be eliminated through sublayering right?
  3. On the shot level, variants are probably not often used? But they could (like having two variants of an RBD destruction). Would it not be more consistent and flexible to also use referencing instead of subLayer the department layers? Or are the disadvantages here to big…
    3.a. Yes, the shot/scene would need to be under one common parent prim like in a component model to make referencing work, but isn’t that a good idea anyways?
    3.b. Worse composition performance / how “worse” is it?
    3.c. Not being able to use EditTargets? Or is it still possible somehow?
    3.d. Layer Muting. The FAQ says layer muting is easily possible with subLayering, but I could not find any problems doing layer muting when referencing either…?

Regarding the payload question.
Ok. A few questions to clarify if I got everything right…

  1. Is it correct that it is not possible to “over” anything from a sublayer or ref, over another sublayer or ref, when the “over” prims are behind a payload? (as P is behind L & R in LIVRPS)
  2. Is it correct that this also means, it is not possible to fully unload such an “over”? As it will compose the undefined opinions into the scene graph (but without any imaging).
  3. As the undefined opinions and prims still get loaded and composed in the scene graph (not the viewport), how “bad” is the performance impact here opposed to full unloading (also in the scene graph, not just the viewport). Assuming lots of prims in the “over”
  4. Whenever a layer is creating new “defs”, and not “overs”, it would make sense to then payload instead of reference them within the layer, correct? (assuming they are heavy)

Thanks a lot!!

4

Okay, I tested a bit regarding the payload questions.
My finding was that assumption 1. is correct when sublayering, but not when referencing.

In simpler terms:

  • Composing 2 layers, where layer_2 has opinions about prims in layer_1
  • The opinions of layer_2 are behind a payload arc
  • When composing layer_2 over layer_1 via referencing, this works
  • When composing layer_2 over layer_1 via sublayering, this does not work

I am honestly a bit confused why this actually works, as the P is behind R in LIVRPS.

But anyways, I think it’s great that this is possible.
However, this sounds like a big reason to me, to also compose department layers in the scene/shot level by referencing and not sublayering?!
As otherwise putting opinions about other layers behind payloads wouldn’t work.

But maybe I’m just getting this all pretty wrong.
Would be great if someone could help me out here.
(all of my other questions still remain so far)
Thanks a lot!

5

THe explanation for the behavior you are seeing is “reference encapsulation”, which, thought of in programming terms, is that LIVRPS is recursive .

In other words, when layer_2 and layer_1 are related via referencing, then with respect to layer_1, everything in layer_2’s composed layerStack comes in at reference strength - all the subLayering and arcs inside of layer_2’s layerStack are effectively “composition implementation details” that are encapsulated inside the reference.

But sublayering intentionally does not provide any kind of encapsulation, so then the payload inside layer_2 is “visible” in the root layerStack, and becomes weaker than all direct opinions in the root layerStack, and weaker than all referenced layers.

I am also curious to hear others’ perspectives on your final question about assembling departments in shots. It works well for us because in our pipeline, all shot-level (and sequence-level) opinions are authored in layers in the root layerstack - and that includes the animation bake layers that our post-animation-rig-baking process produces.

As you might imagine, FX/Sim sometimes generates a ton of data that wants to be overlaid on top of the departmental and animation-baked scene, and payloads would give you a way to manage the complexity of some of that data. But when you have an effect that is doing overrides on a whole lot of existing set/environment models, LIVRPS makes payloading awkward for that (and also, to see/image anything in the set, you’d need to load that data in anyways).

So what we do instead is to leverage Value Clips. A ClipSet authored on a “strong” layer in the root layerStack will override all weaker data in the layerStack as if the data had been injected directly into that subLayer, but, the only clips that will be opened by your Stage will be the ones that contribute to your selected evaluation times, so if “layer size” is an important metric for you, value clips can be an option.

Just to say it, though, usdc is already pretty good at deferring any cost associated with “big attribute data” until that data is specifically requested, sample-by-sample. Since we optimized usdc to lay out its sample data primarily by increasing sample-time, we have not had any scalability issues that I’m aware of deriving from the fact that we keep all of our heavy animation-bake data in subLayers of the root layerStack. We do tend to aggregate baked data for multiple models, so we’ll typically have 4 - 12ish layers worth of animation bake data, rather than a layer-per-model, while our shots wind up with 60 - 100 sublayers total, when you add in all the crowds, lighting, and FX override layers that are stronger than the animation bake and “shot structure” layers.

6

Okay great. Thanks for the detailed reply.

Actually the reference encapsulation behavior does sound pretty nice and logic to me and would intuitively speak for composing department layers via referencing and not subLayering to me again. As encapsulated payload arcs and variantSets seem to be more predictable then.
Like: “Do your payloading and whatever composition inside your layers, and then don’t worry when combining them, as they’ll all come in at reference strength.”

But I’ll just trust your production proven workflows here and follow your lead (-;

  • Referencing department layers for the asset & assembly context.
  • Sublayering for the shot/scene context.
7

Just to note, the Pixar setup makes no claim at being best :slight_smile: Sublayering the animation caches works well for us because we do a monolithic “shot conversion” process for animation baking, where all shot animation is baked out (and asset managed) at once, regularly. AFAIK, we’re the only shop that works that way, and if you are caching models individually, you will run into the strength ordering issues you noted, bringing in the caches by payload or reference.

So, still curious to hear about structures other studios are using.

2 Likes
8

Thank you.
Yes maybe not “best”. But probably not “that bad” either :wink: