UsdStage Class Reference

The outermost container for scene description, which owns and presents composed prims as a scenegraph, following the composition recipe recursively described in its associated "root layer". More...

#include <stage.h>

Inheritance diagram for UsdStage:

Public Member Functions
Layer Serialization
Functions for saving changes to layers that contribute opinions to this stage. Layers may also be saved by calling SdfLayer::Save or exported to a new file by calling SdfLayer::Export.
USD_API void	Save ()
	Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublayers of session layers.
USD_API void	SaveSessionLayers ()
	Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this stage.
Working Set Management
The following rules apply to all Load/Unload methods: - Loading an already loaded prim is legal, though may result in some recomposition cost. Similarly, unloading an unloaded prim is legal. - Specifying a path that does not target a prim is legal as long it has an ancestor present in the scene graph (other than the absolute root). If the given path has no such ancestor, it is an error. - Specifying a path to an inactive prim is an error. - Specifying a path to a prototype prim or a prim within a prototype is an error. If an instance prim (or a path identifying a prim descendant to an instance) is encountered during a Load/Unload operation, these functions may cause instancing to change on the stage in order to ensure that no other instances are affected. The load/unload rules that affect a given prim hierarchy are considered when determining which prims can be instanced together. Instance sharing occurs when different instances have equivalent load rules. The GetLoadRules() and SetLoadRules() provide direct low-level access to the UsdStageLoadRules that govern payload inclusion on a stage.
USD_API UsdPrim	Load (const SdfPath &path=SdfPath::AbsoluteRootPath(), UsdLoadPolicy policy=UsdLoadWithDescendants)
	Modify this stage's load rules to load the prim at path, its ancestors, and all of its descendants if policy is UsdLoadWithDescendants.
USD_API void	Unload (const SdfPath &path=SdfPath::AbsoluteRootPath())
	Modify this stage's load rules to unload the prim and its descendants specified by path.
USD_API void	LoadAndUnload (const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
	Unload and load the given path sets.
USD_API SdfPathSet	GetLoadSet ()
	Returns a set of all loaded paths.
USD_API SdfPathSet	FindLoadable (const SdfPath &rootPath=SdfPath::AbsoluteRootPath())
	Returns an SdfPathSet of all paths that can be loaded.
UsdStageLoadRules const &	GetLoadRules () const
	Return the stage's current UsdStageLoadRules governing payload inclusion.
USD_API void	SetLoadRules (UsdStageLoadRules const &rules)
	Set the UsdStageLoadRules to govern payload inclusion on this stage.
UsdStagePopulationMask	GetPopulationMask () const
	Return this stage's population mask.
USD_API void	SetPopulationMask (UsdStagePopulationMask const &mask)
	Set this stage's population mask and recompose the stage.
USD_API void	ExpandPopulationMask (Usd_PrimFlagsPredicate const &traversalPredicate, std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
	Expand this stage's population mask to include the targets of all relationships that pass relPred and connections to all attributes that pass attrPred recursively.
USD_API void	ExpandPopulationMask (std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This convenience overload invokes ExpandPopulationMask() with the UsdPrimDefaultPredicate traversal predicate.
Layers and EditTargets
USD_API SdfLayerHandle	GetSessionLayer () const
	Return this stage's root session layer.
USD_API SdfLayerHandle	GetRootLayer () const
	Return this stage's root layer.
USD_API ArResolverContext	GetPathResolverContext () const
	Return the path resolver context for all path resolution during composition of this stage.
USD_API std::string	ResolveIdentifierToEditTarget (std::string const &identifier) const
	Resolve the given identifier using this stage's ArResolverContext and the layer of its GetEditTarget() as an anchor for relative references (e.g.
USD_API PcpErrorVector	GetCompositionErrors () const
	Return a PcpErrorVector containing all composition errors encountered when composing the prims and layer stacks on this stage.
USD_API SdfLayerHandleVector	GetLayerStack (bool includeSessionLayers=true) const
	includeSessionLayers is true, return the linearized strong-to-weak sublayers rooted at the stage's session layer followed by the linearized strong-to-weak sublayers rooted at this stage's root layer.
USD_API SdfLayerHandleVector	GetUsedLayers (bool includeClipLayers=true) const
	Return a vector of all of the layers currently consumed by this stage, as determined by the composition arcs that were traversed to compose and populate the stage.
USD_API bool	HasLocalLayer (const SdfLayerHandle &layer) const
	Return true if layer is one of the layers in this stage's local, root layerStack.
USD_API const UsdEditTarget &	GetEditTarget () const
	Return the stage's EditTarget.
USD_API UsdEditTarget	GetEditTargetForLocalLayer (size_t i)
	Return a UsdEditTarget for editing the layer at index i in the layer stack.
USD_API UsdEditTarget	GetEditTargetForLocalLayer (const SdfLayerHandle &layer)
	Return a UsdEditTarget for editing the given local layer.
USD_API void	SetEditTarget (const UsdEditTarget &editTarget)
	Set the stage's EditTarget.
USD_API void	MuteLayer (const std::string &layerIdentifier)
	Mute the layer identified by layerIdentifier.
USD_API void	UnmuteLayer (const std::string &layerIdentifier)
	Unmute the layer identified by layerIdentifier if it had previously been muted.
USD_API void	MuteAndUnmuteLayers (const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers)
	Mute and unmute the layers identified in muteLayers and unmuteLayers.
USD_API const std::vector< std::string > &	GetMutedLayers () const
	Returns a vector of all layers that have been muted on this stage.
USD_API bool	IsLayerMuted (const std::string &layerIdentifier) const
	Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise.
Flatten & Export Utilities
USD_API bool	Export (const std::string &filename, bool addSourceFileComment=true, const SdfLayer::FileFormatArguments &args=SdfLayer::FileFormatArguments()) const
	Writes out the composite scene as a single flattened layer into filename.
USD_API bool	ExportToString (std::string *result, bool addSourceFileComment=true) const
	Writes the composite scene as a flattened Usd text representation into the given string.
USD_API SdfLayerRefPtr	Flatten (bool addSourceFileComment=true) const
	Returns a single, anonymous, merged layer for this composite scene.
Stage Metadata
Stage metadata applies to the entire contents of the stage, and is recorded only in the stage's root or primary session-layer. Most of the other, specific metadata methods on UsdStage are defined in terms of these generic methods.
template<class T >
bool	GetMetadata (const TfToken &key, T *value) const
	Return in value an authored or fallback value (if one was defined for the given metadatum) for Stage metadatum key.
USD_API bool	GetMetadata (const TfToken &key, VtValue *value) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API bool	HasMetadata (const TfToken &key) const
	Returns true if the key has a meaningful value, that is, if GetMetadata() will provide a value, either because it was authored or because the Stage metadata was defined with a meaningful fallback value.
USD_API bool	HasAuthoredMetadata (const TfToken &key) const
	Returns true if the key has an authored value, false if no value was authored or the only value available is the SdfSchema's metadata fallback.
USD_API bool	SetMetadata (const TfToken &key, VtValueRef value) const
	Set the value of Stage metadatum key to value, if the stage's current UsdEditTarget is the root or session layer.
USD_API bool	ClearMetadata (const TfToken &key) const
	Clear the value of stage metadatum key, if the stage's current UsdEditTarget is the root or session layer.
template<typename T >
bool	GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const
	Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key, returning the resolved value.
USD_API bool	GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
	overload
USD_API bool	HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
	Return true if there exists any authored or fallback opinion for key and keyPath.
USD_API bool	HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
	Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath.
USD_API bool	SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValueRef value) const
	Author value to the field identified by key and keyPath at the current EditTarget.
USD_API bool	ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
	Clear any authored value identified by key and keyPath at the current EditTarget.
USD_API void	WriteFallbackPrimTypes ()
	Writes the fallback prim types defined in the schema registry to the stage as dictionary valued fallback prim type metadata.
TimeCode API
Methods for managing the Stage's active timeSample range, time units, and intended rate of playback. See Time and Timing in USD for more on time and TimeCodes in USD.
USD_API double	GetStartTimeCode () const
	Returns the stage's start timeCode.
USD_API void	SetStartTimeCode (double)
	Sets the stage's start timeCode.
USD_API double	GetEndTimeCode () const
	Returns the stage's end timeCode.
USD_API void	SetEndTimeCode (double)
	Sets the stage's end timeCode.
USD_API bool	HasAuthoredTimeCodeRange () const
	Returns true if the stage has both start and end timeCodes authored in the session layer or the root layer of the stage.
USD_API double	GetTimeCodesPerSecond () const
	Returns the stage's timeCodesPerSecond value.
USD_API void	SetTimeCodesPerSecond (double timeCodesPerSecond) const
	Sets the stage's timeCodesPerSecond value.
USD_API double	GetFramesPerSecond () const
	Returns the stage's framesPerSecond value.
USD_API void	SetFramesPerSecond (double framesPerSecond) const
	Sets the stage's framesPerSecond value.
Attribute Value Interpolation
Controls the interpolation behavior when retrieving attribute values. The default behavior is linear interpolation. See Attribute Value Interpolation for more details.
USD_API void	SetInterpolationType (UsdInterpolationType interpolationType)
	Sets the interpolation type used during value resolution for all attributes on this stage.
USD_API UsdInterpolationType	GetInterpolationType () const
	Returns the interpolation type used during value resolution for all attributes on this stage.
Instancing
See Scenegraph Instancing for more details.
USD_API std::vector< UsdPrim >	GetPrototypes () const
	Returns all native instancing prototype prims.
Public Member Functions inherited from TfRefBase
	TfRefBase (TfRefBase const &)
TfRefBase &	operator= (TfRefBase const &)
size_t	GetCurrentCount () const
	Return the current reference count of this object.
bool	IsUnique () const
	Return true if only one TfRefPtr points to this object.
void	SetShouldInvokeUniqueChangedListener (bool shouldCall)
Public Member Functions inherited from TfWeakBase
	TfWeakBase (const TfWeakBase &)
const TfWeakBase &	__GetTfWeakBase__ () const
const TfWeakBase &	operator= (const TfWeakBase &)
void	EnableNotification2 () const
TF_API void const *	GetUniqueIdentifier () const

Static Public Member Functions
Variant Management
These methods provide control over the policy to use when composing prims that specify a variant set but do not specify a selection. The first is to declare a list of preferences in plugInfo.json metadata on a plugin using this structure: "UsdVariantFallbacks": { # top level key "shadingComplexity": [ # example variant set "full", # example fallback #1 "light" # example fallback #2 ] }, This example ensures that we will get the "full" shadingComplexity for any prim with a shadingComplexity VariantSet that doesn't otherwise specify a selection, and has a "full" variant; if its shadingComplexity does not have a "full" variant, but does have a "light" variant, then the selection will be "light". In other words, the entries in the "shadingComplexity" list in the plugInfo.json represent a priority-ordered list of fallback selections. The plugin metadata is discovered and applied before the first UsdStage is constructed in a given process. It can be defined in any plugin. However, if multiple plugins express contrary lists for the same named variant set, the result is undefined. The plugin metadata approach is useful for ensuring that sensible default behavior applies across a pipeline without requiring every script and binary to explicitly configure every VariantSet that subscribes to fallback in the pipeline. There may be times when you want to override this behavior in a particular script – for example, a pipeline script that knows it wants to entirely ignore shading in order to minimize processing time – which motivates the second approach. SetGlobalVariantFallbacks() provides a way to override, for the entire process, which fallbacks to use in subsequently constructed UsdStage instances.
static USD_API PcpVariantFallbackMap	GetGlobalVariantFallbacks ()
	Get the global variant fallback preferences used in new UsdStages.
static USD_API void	SetGlobalVariantFallbacks (const PcpVariantFallbackMap &fallbacks)
	Set the global variant fallback preferences used in new UsdStages.
Static Public Member Functions inherited from TfRefBase
static TF_API void	SetUniqueChangedListener (UniqueChangedListener listener)

Friends
class	UsdAPISchemaBase
class	UsdAttribute
class	UsdAttributeQuery
class	UsdEditTarget
class	UsdInherits
class	UsdNamespaceEditor
class	UsdObject
class	UsdPrim
class	UsdProperty
class	UsdRelationship
class	UsdSpecializes
class	UsdVariantSet
class	UsdVariantSets

Lifetime Management
enum	InitialLoadSet { LoadAll , LoadNone }
	Specifies the initial set of prims to load when opening a UsdStage. More...
static USD_API UsdStageRefPtr	CreateNew (const std::string &identifier, InitialLoadSet load=LoadAll)
	Create a new stage with root layer identifier, destroying potentially existing files with that identifier; it is considered an error if an existing, open layer is present with this identifier.
static USD_API UsdStageRefPtr	CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateNew (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateInMemory (InitialLoadSet load=LoadAll)
	Creates a new stage only in memory, analogous to creating an anonymous SdfLayer.
static USD_API UsdStageRefPtr	CreateInMemory (const std::string &identifier, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateInMemory (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	Open (const std::string &filePath, InitialLoadSet load=LoadAll)
	Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the stack.
static USD_API UsdStageRefPtr	Open (const std::string &filePath, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	OpenMasked (const std::string &filePath, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll)
	Create a new stage and recursively compose prims defined within and referenced by the layer at filePath which must already exist, subject to mask.
static USD_API UsdStageRefPtr	OpenMasked (const std::string &filePath, const ArResolverContext &pathResolverContext, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	Open (const SdfLayerHandle &rootLayer, InitialLoadSet load=LoadAll)
	Open a stage rooted at rootLayer.
static USD_API UsdStageRefPtr	Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	Open (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	OpenMasked (const SdfLayerHandle &rootLayer, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
	Open a stage rooted at rootLayer and with limited population subject to mask.
static USD_API UsdStageRefPtr	OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	OpenMasked (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API UsdStageRefPtr	OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
static USD_API bool	IsSupportedFile (const std::string &filePath)
	Indicates whether the specified file is supported by UsdStage.
USD_API void	Reload ()
	Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers of session layers.

Color Configuration API
Methods for authoring and querying the display color configuration encoded in layer metadata. This color configuration information is stored as a convenience for use in pipeline tools and is unrelated to color space information associated with Usd attributes or textures. Site-wide fallback values for the colorConfiguration and colorManagementSystem metadata can be set in the plugInfo.json file of a plugin using this structure: "UsdColorConfigFallbacks": { "colorConfiguration" = "https://path/to/color/config.ocio", "colorManagementSystem" : "OpenColorIO" }
static USD_API void	GetColorConfigFallbacks (SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
	Returns the global fallback values of 'colorConfiguration' and 'colorManagementSystem'.
static USD_API void	SetColorConfigFallbacks (const SdfAssetPath &colorConfiguration, const TfToken &colorManagementSystem)
	Sets the global fallback values of color configuration metadata which includes the 'colorConfiguration' asset path and the name of the color management system.
USD_API void	SetColorConfiguration (const SdfAssetPath &colorConfig) const
	Sets the default color configuration to be used for querying color configuration metadata stored in a layer.
USD_API SdfAssetPath	GetColorConfiguration () const
	Returns the default color configuration stored in layer metadata.
USD_API void	SetColorManagementSystem (const TfToken &cms) const
	Sets the name of the color management system used to interpret the color configuration file pointed at by the colorConfiguration metadata.
USD_API TfToken	GetColorManagementSystem () const
	Sets the name of the color management system to be used for loading and interpreting the color configuration file.

Prim Access, Creation and Mutation
All of the methods in this group that accept a prim path as argument require paths in the namespace of the stage's root layer, regardless of what the currently active UsdEditTarget is set to. In other words, a UsdStage always presents a composed view of its scene, and all prim operations are specified in the composed namespace.
USD_API UsdPrim	GetPseudoRoot () const
	Return the stage's "pseudo-root" prim, whose name is defined by Usd.
USD_API UsdPrim	GetDefaultPrim () const
	Return the UsdPrim on this stage whose path is the root layer's defaultPrim metadata's value.
USD_API void	SetDefaultPrim (const UsdPrim &prim)
	Set the default prim layer metadata in this stage's root layer.
USD_API void	ClearDefaultPrim ()
	Clear the default prim layer metadata in this stage's root layer.
USD_API bool	HasDefaultPrim () const
	Return true if this stage's root layer has an authored opinion for the default prim layer metadata.
USD_API UsdPrim	GetPrimAtPath (const SdfPath &path) const
	Return the UsdPrim at path, or an invalid UsdPrim if none exists.
USD_API UsdObject	GetObjectAtPath (const SdfPath &path) const
	Return the UsdObject at path, or an invalid UsdObject if none exists.
USD_API UsdProperty	GetPropertyAtPath (const SdfPath &path) const
	Return the UsdProperty at path, or an invalid UsdProperty if none exists.
USD_API UsdAttribute	GetAttributeAtPath (const SdfPath &path) const
	Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
USD_API UsdRelationship	GetRelationshipAtPath (const SdfPath &path) const
	Return the UsdAttribute at path, or an invalid UsdAttribute if none exists.
USD_API UsdPrimRange	Traverse ()
	Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.
USD_API UsdPrimRange	Traverse (const Usd_PrimFlagsPredicate &predicate)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Traverse the prims on this stage subject to predicate.
USD_API UsdPrimRange	TraverseAll ()
	Traverse all the prims on this stage depth-first.
USD_API UsdPrim	OverridePrim (const SdfPath &path)
	Attempt to ensure a UsdPrim at path exists on this stage.
USD_API UsdPrim	DefinePrim (const SdfPath &path, const TfToken &typeName=TfToken())
	Attempt to ensure a UsdPrim at path is defined (according to UsdPrim::IsDefined()) on this stage.
USD_API UsdPrim	CreateClassPrim (const SdfPath &rootPrimPath)
	Author an SdfPrimSpec with specifier == SdfSpecifierClass for the class at root prim path path at the current EditTarget.
USD_API bool	RemovePrim (const SdfPath &path)
	Remove all scene description for the given path and its subtree in the current UsdEditTarget.

Additional Inherited Members
Public Types inherited from TfRefBase
typedef void(*)	UniqueChangedFuncPtr(TfRefBase const *, bool)
Protected Member Functions inherited from TfRefBase
Protected Member Functions inherited from TfWeakBase
TfRefPtr< Tf_Remnant >	_Register () const
template<class T >
TfRefPtr< Tf_Remnant >	_Register (T *tempRmnt) const
bool	_HasRemnant () const

Detailed Description

The outermost container for scene description, which owns and presents composed prims as a scenegraph, following the composition recipe recursively described in its associated "root layer".

USD derives its persistent-storage scalability by combining and reusing simple compositions into richer aggregates using referencing and layering with sparse overrides. Ultimately, every composition (i.e. "scene") is identifiable by its root layer, i.e. the .usd file, and a scene is instantiated in an application on a UsdStage that presents a composed view of the scene's root layer. Each simple composition referenced into a larger composition could be presented on its own UsdStage, at the same (or not) time that it is participating in the larger composition on its own UsdStage; all of the underlying layers will be shared by the two stages, while each maintains its own scenegraph of composed prims.

A UsdStage has sole ownership over the UsdPrim 's with which it is populated, and retains shared ownership (with other stages and direct clients of SdfLayer's, via the Sdf_LayerRegistry that underlies all SdfLayer creation methods) of layers. It provides roughly five categories of API that address different aspects of scene management:

• Stage lifetime management methods for constructing and initially populating a UsdStage from an existing layer file, or one that will be created as a result, in memory or on the filesystem.
• Load/unload working set management methods that allow you to specify which payloads should be included and excluded from the stage's composition.
• Variant management methods to manage policy for which variant to use when composing prims that provide a named variant set, but do not specify a selection.
• Prim access, creation, and mutation methods that allow you to find, create, or remove a prim identified by a path on the stage. This group also provides methods for efficiently traversing the prims on the stage.
• Layers and EditTargets methods provide access to the layers in the stage's root LayerStack (i.e. the root layer and all of its recursive sublayers), and the ability to set a UsdEditTarget into which all subsequent mutations to objects associated with the stage (e.g. prims, properties, etc) will go.
• Serialization methods for "flattening" a composition (to varying degrees), and exporting a completely flattened view of the stage to a string or file. These methods can be very useful for targeted asset optimization and debugging, though care should be exercized with large scenes, as flattening defeats some of the benefits of referenced scene description, and may produce very large results, especially in file formats that do not support data de-duplication, like the usda text format!

Stage Session Layers

Each UsdStage can possess an optional "session layer". The purpose of a session layer is to hold ephemeral edits that modify a UsdStage's contents or behavior in a way that is useful to the client, but should not be considered as permanent mutations to be recorded upon export. A very common use of session layers is to make variant selections, to pick a specific LOD or shading variation, for example. The session layer is also frequently used to override the visibility of geometry and assets in the scene. A session layer, if present, contributes to a UsdStage's identity, for purposes of stage-caching, etc.

To edit content in a session layer, get the layer's edit target using stage->GetEditTargetForLocalLayer(stage->GetSessionLayer()) and set that target in the stage by calling SetEditTarget() or creating a