Payloads in the Scene Explorer

Payloads for Selective Stage Loading

Katana makes use of deferred loading to improve performance. When working with large datasets, portions of the data can be kept in reserve until needed, thus freeing up computational resources for more pressing tasks. In the Katana Scene Graph this is achieved by selectively expanding branches of the tree. In the USD Scene Explorer, it is achieved using payloads.

Loading and unloading payloads triggers the recomposition of the USD stage. When a payload is loaded, it brings in new data, such as prims and properties to the stage. Similarly, when you remove a payload from a stage, recomposition is triggered as data is removed from the scene graph.

A payload is a reference to scene information that can be loaded into the stage when needed. Any prim can contain one or more payloads, or have none.

For example, imagine you have a tree asset that is highly detailed. You want to include multiple instances of the tree in a forest.

Your tree asset looks like this:

Copy

#usda 1.0
def Xform "Tree" {
    def Mesh "Trunk" { /*... mesh details ...*/ }
    def Mesh "Leaves" { /*... mesh details ...*/ }
    // ... Perhaps more variations or details like fruits, flowers, etc.
}

To include trees as payloads in your forest, the USD file could be written as follows:

Copy

#usda 1.0
    ()

def Xform "Forest"() {

    def Cube "Tree1"
        (

            prepend payload = @. / tree.usda @ < /Tree>
        ) {
            double3 xformOp: translate = (0, 0, 0) uniform token[] xformOpOrder = ["xformOp:translate"]
        }

    def Cone "Tree2"(
        prepend payload = @. / tree.usda @ < /Tree>
    ) {
        double3 xformOp: translate = (5, 0, 10) // Positioned for natural tree spacinguniform token[] xformOpOrder = ["xformOp:translate"]
    }
}

Using payload enables selective loading and unloading of specific portions of a USD stage to speed up your workflow. Loading any prims or layers that are not currently needed can be deferred until required.

Example: Consider working with a large cityscape. Instead of loading all the buildings, cars, and trees simultaneously, which can be resource-intensive and slow, you can use payloads to load only the parts of the city that are currently visible or necessary for the scene. As you shift the focus of your work, you can revise the payload loading options to select the parts you need.

Deferred loading should be familiar to experienced users who have worked with the Katana Scene Graph. As part of the USD workflow, we have incorporated deferred loading using payloads into the Scene Explorer.

Loading and Unloading USD Payloads

Payloads are activated by selecting the Payload button in the Scene Explorer toolbar.

When this payload button is deactivated, payloads are loaded via expansion of USD scene graph locations, mimicking Katana’s deferred loading workflow. When expanding prim locations using the deferred loading method, payloads will load if they are present on that prim, but will not load any payloads on its decendants.

Prims with payloads have a down arrow icon in the Payload column.

Payloads are managed by assigning a rule to a prim. This rule determines if payloads are to be loaded for the prim and its descendants.

There are three stage load rules available, as shown in the image below. Either right-click the dot for the options or use the mouse-click combinations listed.

Right-click in the payload column to open the context menu.

Note: Though named differently, the three stage load rules map directly to the stage load rules found in USD. Load One is the OnlyRule, Load None is the NoneRule, and Load All is the AllRule.

The rules only apply if there are payloads on the stage. When there are no payload the rules have no effect.

Prim Payload Status

The color of both the arrow and the background change to indicate the payload status on a particular prim. The table below shows the possible states.

Payload Rule	Payload Management Column Active
Payload Rule	Loaded	Unloaded
Empty
Load One
Load All
Load None
By Inheritance (loaded due to implicit loading by ancestors or descendant load rules)		n/a

If the prim has been deactivated, Katana desaturates the icon and draws it in a grey circle.

Effects of Stage Load Rules

The table below describes how payloads are managed according to the stage load rule on the prim.

To help understand how the rules affect payload loading, the tree diagrams in the table below represent some simple scenes. Each box is a prim and the connecting lines show the prim hierarchy. A green box indicates if there is a payload at this prim, then this payload is loaded. A grey box indicates if there is a payload at this prim, then the payload is not loaded.

Load One Click to toggle	Load payloads on the prim but not its descendants Only the payload on the prim in green is loaded. Example: Suppose the scene is In an old church, full of details like candlesticks, icons, stained glass windows, and furniture. You choose to work initially on the daylight shining through the windows. By using the Load One payload method you load only the structural components and windows, reducing memory overhead and enhancing viewport performance. This allows you to fine-tune the primary light dynamics without the computational overhead of secondary assets like books and artifacts.
Load All Shift + click	Include payloads on the prim plus all its descendants Payloads on the prim and on all descendant prims are loaded if present. Example: In the church example above, once you have addressed primary lighting behaviour, you could then use Load All to bring in all other objects and address more detailed lighting challenges.
Load None Ctrl + click	Exclude payloads on the prim and all its descendants. No payloads are loaded on the prim and any descendant prims with payloads. Example: In any building environment, such as the previous church example, there may be detailed items that you don’t need to see to address a particular lighting task. Load None gives you an easy way of turning off loading for entire sections of your scene that are not in your area of focus. Aside from geometry, this could be any kind of data that you don’t need, such as animation data.
Empty the default value, or click until it resets to this value	If no rule is assigned and the prim has a payload, then the behavior depends on the load rules on the prim’s ancestors and descendants. For example, load the payload if any of the following is true: there are no load rules on the stage there are no load rules on any of the prim’s ancestors the closest* ancestor with a rule, has the Load All rule the closest* descendant with a rule, has a Load All or a Load One rule The payload is not loaded if: the closest* ancestor with a rule, has a Load One or Load None rule. (*closest can be any number of generations away, but the intermediate generations have no rule assigned)

Cascading Payload Rules to Refine Prim Loading

In real-world production scenarios, it may be preferable that certain parts of a scene should not be loaded to conserve memory. However, specific sections might still be required for a particular shot, sequence, or operation. With USD, child prims can override their ancestors' load policies, giving artists and developers precise control to optimize scenes for their specific requirements.

To achieve this, you can apply rules at different levels of the hierarchy to include or exclude specific prims as needed. For example, the tree below shows the effect of combining two rules.

A combination of payload rules on a simple graph. The leftmost node has a Load None rule but if present the payload would be loaded as there is a downstream Load One rule.