VERIFIED ON USD VERSION 21.08
This tutorial will walk you through referencing the simple stage that we created in the previous exercises into a new stage. Thethat we'll use as our starting point and all the code for this exercise is in the extras/usd/tutorials/referencingLayers folder.
- Author the defaultPrim metadata on the layer that you want to reference. This is the name of the root prim that will be referenced. If it is not authored here, then the referencing client must specify the root prim path it wants from the referenced layer. We also want to author a transformation on the default root prim, so that we can override it later; to do this we use the UsdGeomXformCommonAPI schema, which we will discuss further, later.
Now let's create a new stage to reference in HelloWorld.usda and create an override prim to contain the reference.
All of the previous prims we had created are defs, which are concrete prims that appear in standard scenegraph traversals (i.e. by clients performing imaging, or importing the stage into another DCC application).
By contrast, an over can be thought of as containing a set of speculative opinions that are applied over any concrete prims that may be defined in other layers at the corresponding namespace location. Overs can contain an opinion for any property, metadatum, or any prim composition operator. For example, an over can non-destructively express a different opinion for the transform and displayColor attributes above.
Let's reference in the stage from HelloWorld.
producesIn this simple example, we are using (an effectively absolute) file path to reference the layer—in practice, the layer identifier given to Usd.References.AddReference() would be a string that a path resolver and scene description file format would process to populate the actual scene description. Both path resolvers and file formats can be implemented as plugins to customize site-specific behavior—there is nothing that requires USD layers to be physical files on disk.
The code in USD/extras/usd/examples/usdObj/ shows how to bring in OBJ mesh topology as a USD file format.
Note that since we authored defaultPrim in HelloWorld.usda, we only need to specify the root layer we want to reference, and it is inferred that we will be bringing in the scenegraph contents rooted at /hello into our /refSphere. If we usdview our exported RefExample.usda, we can see the composed result.
If it were unselected in the namespace browser, usdview would show refSphere in orange to indicate that it is a referencing point on our stage. Our screenshot shows refSphere's row selected, however, to show both what our overridden transformation looks like as attributes, and to note in the Meta Data inspector that the reference and its target are listed. Note also that there is no prim named "hello" since it has been referenced into /refSphere.
Let's re-set the transform on our over to the identity.
What Just Happened???
The UsdGeomXformable schema is component-based, allowing you to specify a single 4x4 matrix, or an unlimited sequence of translate, rotate, scale, matrix, and (quaternion) orientation "ops". Each xformable prim has a builtin xformOpOrder attribute that specifies the order in which the ops are applied. By explicitly setting the ordering to an empty list:
we are telling the schema to ignore any ops, even if authored, effectively setting the transformation to the identity. We could also have explicitly authored an identity matrix, or set all existing, composed op attributes to their identity values. For a complete explanation of Xformable and XformOps, please see the API documentation for UsdGeomXformable
Reference in another HelloWorld.
We can see that our over has been applied to move the first sphere to the origin, while the second sphere is still translated by (4, 5, 6).
Of course, overs can be authored for the actual sphere prims underneath the reference as well. Let's color our second sphere red.
Note that we don't need to call OverridePrim again—because /refSphere2/world already has a presence in the composed scenegraph, upon calling Set() on a Usd.Attribute, the USD API automatically creates an over for it if one doesn't already exist in the current authoring layer.
We can also flatten out the composed results—all of the printouts of the scene description above were of the root layer upon which we were performing our authoring. If we call ExportToString() or Export() on the UsdStage itself, we'll print or save out the flattened scene description, respectively.
When we use the term flattening we generally mean producing a single Layer of scene description that contains all of the "composed data" from a set of inputs, and retains no composition operators (such as references, payloads, inherits, variants, sublayers, and activations). UsdStage::Flatten(), which flattens an entire stage (and is used by Export() and ExportToString()) is the only basic form of flattening we currently provide, though we hope to expand that in the future to flattening subtrees of a stage, as well as just selected layers in a layerStack.