 |
An SdfLayer provides the interface to a persistent (in a file) or in-memory only (via "anonymous" layers) container of scene description. The scene description contained in a layer consists of prims, attributes, relationships, user-metadata on all of the above, and composition operators that specify how the contained scene description should be composed with scene description in other files.
If working directly with an SdfLayer, clients should be aware that Sdf maintains an internal registry of layers that clients have requested to be opened via SdfLayer::FindOrOpen(), SdfLayer::CreateNew() or SdfLayer::CreateAnonymous(). The registry holds only weak pointers (SdfLayerHandle) to the layers it caches, so it is the client's responsibility to retain the strong SdfLayerRefPtr that the above methods return, if they expect the layer to persist. UsdStage takes care of this for the layer for which the stage was opened, and all layers reached during the process of population the stage by traversing composition arcs; the set of "reached" layers may be different for different variant selections on the stage, different activation opinions, and different load-states.
As described in its class documentation, a UsdStage is the interface to a specific SdfLayer (known as its rootLayer), interpreting the data it contains through the composition rules provided by Pcp. Pcp informs the UsdStage about which UsdPrim s should be populated on the stage, and provides PcpPrimIndex objects, per-prim, which allow usd to perform efficient value resolution.
The primary client-facing aspect and purpose of a UsdStage is that it creates and maintains (as new scene description is authored or mutated) a scenegraph of UsdPrim s that enables efficient scene traversal, data extraction and authoring. A UsdStage can contain any number of "root level" prims, each of which represents a different tree/graph (which may be related to each other via composition operators or relationships). To facilitate traversals that visit all root prims, every UsdStage has an un-named "pseudo-root" prim that is the parent of all root prims; it can be accessed via UsdStage::GetPseudoRoot().
An important property of the stage is that it always presents the accurate, fully-composed view of the data in its underlying SdfLayer s. This has impact on Authoring and Editing Scene Description , and implies that a UsdStage may perform a potentially substantial amount of work in "recomposing" a scene in response to certain kinds of authoring operations, namely the authoring of composition operators. For example, when one adds a reference to a prim using UsdReferences, the stage on which the prim sits will immediately pull in the scene topology information from the referenced SdfLayer, and repopulate the affected parts of the stage. Something similar occurs even when one changes a variant selection on an existing UsdVariantSet.
SdfLayer and UsdStage are the only objects in USD whose lifetime matters. SdfLayer is the true data container in USD, and if a layer is destroyed before its contents are explicitly serialized (SdfLayer::Save(), SdfLayer::Export()), then data may be lost. If a UsdStage is destroyed, it will drop its retention of all of the SdfLayer s it composes; if that results in a layer-with-changes' refcount to drop to zero, the layer will be destroyed.
Like SdfLayer, UsdStage is also managed by strong and weak pointers; all stage-creation methods return a UsdStageRefPtr for the client to retain. UsdStages can also be managed in a registry, known as a UsdStageCache. Unlike the SdfLayer registry, however:
UsdPrim is the primary object used to interact with composed scene description, and has the largest API of any of the core objects. A UsdPrim represents a unique "namespace location" in a hierarchical composition on a UsdStage. Each UsdPrim can contain properties and child UsdPrim's, which is what allows us to build hierarchies. If the following usd example were opened on a UsdStage:
then we would be able to access the UsdPrim's on the stage, like so:
All of the objects we have described so far, SdfLayer, UsdStage, UsdPrim, and both subclasses of UsdProperty, can possess metadata. In USD, metadata serves several critical roles for describing object behavior and meaning, and is defined by the following properties:
The singleton class UsdSchemaRegistry exists to provide access to all available schemas. It queries plugins to find all registered schema types and generates prim definitions from the processed generatedSchema.usda files (generated when a schema.usda file is processed by usdGenSchema).
A prim definition, provided by the UsdPrimDefinition class, is an encapsulation of the built-in data that is imparted on a prim by the schemas for the prim's complete type signature. The built-in data accessible from a prim definition includes the list of built-in properties, an SdfSpec defining each property, the list of built-in metadata fields, and fallback values for attributes and metadata fields.
The schema registry creates and provides access to prim definitions for each individual "IsA" and applied API schema. It also provides API to build a composite prim definition for a combination of an "IsA" type with a list of applied API schemas. The prim definition that a prim uses is determined by the combination of its type name and the list of any applied API schemas applied to the prim and is generally what we are referring to when we talk about a UsdPrim's "prim definition".
When you create a new "IsA" schema to use as a prim type, there may be an expectation that stages containing prims of your new type will be opened using a version of USD that does not have the new schema. You may want to provide these other, typically older, versions of USD with one or more reasonable alternative prim types to use instead of your type when its schema is not available. We provide the following mechanism for this.
You can specify an array of fallbackTypes tokens as customData for your class in the schema.usda. Schema generation will process this list of fallback types and add it to the dictionary of all prim fallback types that the schema registry provides.
To provide the currently registered prim type fallbacks to a version of USD that does not have some of these schemas, they must be recorded into any stages that may want to be opened in one of these versions. At any point before saving or exporting a stage, this can be done by calling the function UsdStage::WriteFallbackPrimTypes to write the schema registry's dictionary of fallback prim types to the stage's root layer metadata.
When a stage is opened and a prim with an unrecognized type name is encountered, the stage's fallback prim types metadata is consulted. If the unrecognized type has a fallback types list in the metadata, all prims with the unrecognized type name will be treated as having the effective schema type of the first recognized type in the list.
1.8.5 
