All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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...

+ 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. More...
 
USD_API void SaveSessionLayers ()
 Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this stage. More...
 
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 master prim or a prim within a master 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. More...
 
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. More...
 
USD_API void LoadAndUnload (const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
 Unload and load the given path sets. More...
 
USD_API SdfPathSet GetLoadSet ()
 Returns a set of all loaded paths. More...
 
USD_API SdfPathSet FindLoadable (const SdfPath &rootPath=SdfPath::AbsoluteRootPath())
 Returns an SdfPathSet of all paths that can be loaded. More...
 
UsdStageLoadRules const & GetLoadRules () const
 Return the stage's current UsdStageLoadRules governing payload inclusion. More...
 
USD_API void SetLoadRules (UsdStageLoadRules const &rules)
 Set the UsdStageLoadRules to govern payload inclusion on this stage. More...
 
UsdStagePopulationMask GetPopulationMask () const
 Return this stage's population mask. More...
 
USD_API void SetPopulationMask (UsdStagePopulationMask const &mask)
 Set this stage's population mask and recompose the stage. More...
 
USD_API void ExpandPopulationMask (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. More...
 
Layers and EditTargets

USD_API SdfLayerHandle GetSessionLayer () const
 Return this stage's root session layer. More...
 
USD_API SdfLayerHandle GetRootLayer () const
 Return this stage's root layer. More...
 
USD_API ArResolverContext GetPathResolverContext () const
 Return the path resolver context for all path resolution during composition of this stage. More...
 
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. More...
 
USD_API SdfLayerHandleVector GetLayerStack (bool includeSessionLayers=true) const
 Return this stage's local layers in strong-to-weak order. More...
 
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. More...
 
USD_API bool HasLocalLayer (const SdfLayerHandle &layer) const
 Return true if layer is one of the layers in this stage's local, root layerStack. More...
 
USD_API const UsdEditTargetGetEditTarget () const
 Return the stage's EditTarget. More...
 
USD_API UsdEditTarget GetEditTargetForLocalLayer (size_t i)
 Return a UsdEditTarget for editing the layer at index i in the layer stack. More...
 
USD_API UsdEditTarget GetEditTargetForLocalLayer (const SdfLayerHandle &layer)
 Return a UsdEditTarget for editing the given local layer. More...
 
USD_API void SetEditTarget (const UsdEditTarget &editTarget)
 Set the stage's EditTarget. More...
 
USD_API void MuteLayer (const std::string &layerIdentifier)
 Mute the layer identified by layerIdentifier. More...
 
USD_API void UnmuteLayer (const std::string &layerIdentifier)
 Unmute the layer identified by layerIdentifier if it had previously been muted. More...
 
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. More...
 
USD_API const std::vector
< std::string > & 
GetMutedLayers () const
 Returns a vector of all layers that have been muted on this stage. More...
 
USD_API bool IsLayerMuted (const std::string &layerIdentifier) const
 Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise. More...
 
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. More...
 
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. More...
 
USD_API SdfLayerRefPtr Flatten (bool addSourceFileComment=true) const
 Returns a single, anonymous, merged layer for this composite scene. More...
 
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. More...
 
USD_API bool GetMetadata (const TfToken &key, VtValue *value) const
 
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. More...
 
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. More...
 
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
 Set the value of Stage metadatum key to value, if the stage's current UsdEditTarget is the root or session layer. More...
 
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
 
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. More...
 
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. More...
 
USD_API bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
 overload More...
 
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. More...
 
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. More...
 
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
 Author value to the field identified by key and keyPath at the current EditTarget. More...
 
USD_API bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const
 
USD_API bool ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
 Clear any authored value identified by key and keyPath at the current EditTarget. More...
 
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. More...
 
USD_API void SetStartTimeCode (double)
 Sets the stage's start timeCode. More...
 
USD_API double GetEndTimeCode () const
 Returns the stage's end timeCode. More...
 
USD_API void SetEndTimeCode (double)
 Sets the stage's end timeCode. More...
 
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. More...
 
USD_API double GetTimeCodesPerSecond () const
 Returns the stage's timeCodesPerSecond value. More...
 
USD_API void SetTimeCodesPerSecond (double timeCodesPerSecond) const
 Sets the stage's timeCodesPerSecond value. More...
 
USD_API double GetFramesPerSecond () const
 Returns the stage's framesPerSecond value. More...
 
USD_API void SetFramesPerSecond (double framesPerSecond) const
 Sets the stage's framesPerSecond value. More...
 
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. More...
 
USD_API UsdInterpolationType GetInterpolationType () const
 Returns the interpolation type used during value resolution for all attributes on this stage. More...
 
Instancing

See Scenegraph Instancing for more details.

USD_API std::vector< UsdPrimGetMasters () const
 Returns all master prims. More...
 
- Public Member Functions inherited from TfRefBase
size_t GetCurrentCount () const
 Return the current reference count of this object. More...
 
bool IsUnique () const
 Return true if only one TfRefPtr points to this object. More...
 
const TfRefCountGetRefCount () const
 
void SetShouldInvokeUniqueChangedListener (bool shouldCall)
 
- Public Member Functions inherited from TfWeakBase
 TfWeakBase (const TfWeakBase &)
 
const TfWeakBase__GetTfWeakBase__ () const
 
const TfWeakBaseoperator= (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. More...
 
static USD_API void SetGlobalVariantFallbacks (const PcpVariantFallbackMap &fallbacks)
 Set the global variant fallback preferences used in new UsdStages. More...
 
- 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 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. More...
 
static USD_API UsdStageRefPtr CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateNew (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateInMemory (InitialLoadSet load=LoadAll)
 Creates a new stage only in memory, analogous to creating an anonymous SdfLayer. More...
 
static USD_API UsdStageRefPtr CreateInMemory (const std::string &identifier, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateInMemory (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
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. More...
 
static USD_API UsdStageRefPtr Open (const std::string &filePath, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
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. More...
 
static USD_API UsdStageRefPtr OpenMasked (const std::string &filePath, const ArResolverContext &pathResolverContext, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr Open (const SdfLayerHandle &rootLayer, InitialLoadSet load=LoadAll)
 Open a stage rooted at rootLayer. More...
 
static USD_API UsdStageRefPtr Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr Open (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll)
 
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. More...
 
static USD_API UsdStageRefPtr OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr OpenMasked (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
 
static USD_API UsdStageRefPtr OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll)
 
static USD_API bool IsSupportedFile (const std::string &filePath)
 Indicates whether the specified file is supported by UsdStage. More...
 
virtual USD_API ~UsdStage ()
 
USD_API void Reload ()
 Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers of session layers. More...
 

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. More...
 
USD_API UsdPrim GetDefaultPrim () const
 Return the root UsdPrim on this stage whose name is the root layer's defaultPrim metadata's value. More...
 
USD_API void SetDefaultPrim (const UsdPrim &prim)
 Set the default prim layer metadata in this stage's root layer. More...
 
USD_API void ClearDefaultPrim ()
 Clear the default prim layer metadata in this stage's root layer. More...
 
USD_API bool HasDefaultPrim () const
 Return true if this stage's root layer has an authored opinion for the default prim layer metadata. More...
 
USD_API UsdPrim GetPrimAtPath (const SdfPath &path) const
 Return the UsdPrim at path, or an invalid UsdPrim if none exists. More...
 
USD_API UsdObject GetObjectAtPath (const SdfPath &path) const
 Return the UsdObject at path, or an invalid UsdObject if none exists. More...
 
USD_API UsdPrimRange Traverse ()
 Traverse the active, loaded, defined, non-abstract prims on this stage depth-first. More...
 
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. More...
 
USD_API UsdPrimRange TraverseAll ()
 Traverse all the prims on this stage depth-first. More...
 
USD_API UsdPrim OverridePrim (const SdfPath &path)
 Attempt to ensure a UsdPrim at path exists on this stage. More...
 
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. More...
 
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. More...
 
USD_API bool RemovePrim (const SdfPath &path)
 Remove all scene description for the given path and its subtree in the current UsdEditTarget. More...
 

Color Configuration API

Methods for authoring and querying the color configuration to be used to interpret the per-attribute color-spaces. An external system (like OpenColorIO) is typically used for interpreting the configuration.

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://github.com/imageworks/OpenColorIO-Configs/blob/master/aces_1.0.1/config.ocio",
* "colorManagementSystem" : "OpenColorIO"
* }
*

The color space in which a given color or texture attribute is authored is set as token-valued metadata 'colorSpace' on the attribute. For color or texture attributes that don't have an authored 'colorSpace' value, the fallback color-space is gleaned from the color configuration oracle. This is usually the config's scene_linear role color-space.

Here's the pseudo-code for determining an attribute's color-space.

* UsdStageRefPtr stage = UsdStage::Open(filePath);
* UsdPrim prim = stage->GetPrimAtPath("/path/to/prim")
* UsdAttribute attr = prim.GetAttribute("someColorAttr");
* TfToken colorSpace = attr.GetColorSpace();
* if (colorSpace.IsEmpty()) {
* // If colorSpace is empty, get the default from the stage's
* // colorConfiguration, using external API (not provided by USD).
* colorSpace = ExternalAPI::GetDefaultColorSpace(
* }
*
See Also
UsdAttribute ColorSpace API
static USD_API void GetColorConfigFallbacks (SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
 Returns the global fallback values of 'colorConfiguration' and 'colorManagementSystem'. More...
 
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. More...
 
USD_API void SetColorConfiguration (const SdfAssetPath &colorConfig) const
 Sets the default color configuration to be used to interpret the per-attribute color-spaces in the composed USD stage. More...
 
USD_API SdfAssetPath GetColorConfiguration () const
 Returns the default color configuration used to interpret the per- attribute color-spaces in the composed USD stage. More...
 
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. More...
 
USD_API TfToken GetColorManagementSystem () const
 Sets the name of the color management system to be used for loading and interpreting the color configuration file. More...
 

Additional Inherited Members

- Public Types inherited from TfRefBase
typedef void(* UniqueChangedFuncPtr )(TfRefBase const *, bool)
 
- 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 targetted 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 ASCII 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 perform interactive vising/invsning of geometry and assets in the scene. A session layer, if present, contributes to a UsdStage's identity, for purposes of stage-caching, etc.

Definition at line 142 of file stage.h.

Member Enumeration Documentation

Specifies the initial set of prims to load when opening a UsdStage.

Enumerator
LoadAll 

Load all loadable prims.

LoadNone 

Load no loadable prims.

Definition at line 155 of file stage.h.

Member Function Documentation

USD_API void ClearDefaultPrim ( )

Clear the default prim layer metadata in this stage's root layer.

This is shorthand for:

* stage->GetRootLayer()->ClearDefaultPrim();
*

Note that this function always authors to the stage's root layer. To author to a different layer, use the SdfLayer::SetDefaultPrim() API.

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.

If the current EditTarget is any other layer, raise a coding error.

Returns
true if authoring was successful, false otherwise. Generates a coding error if key is not allowed as layer metadata.
See Also
General Metadata in USD
USD_API bool ClearMetadataByDictKey ( const TfToken key,
const TfToken keyPath 
) const

Clear any authored value identified by key and keyPath at the current EditTarget.

The keyPath is a ':'-separated path identifying a path in subdictionaries stored in the metadata field at key. If keyPath is empty, no action is taken.

Returns
true if the value is cleared successfully, false otherwise. Generates a coding error if key is not allowed as layer metadata.
See Also
Dictionary-valued Metadata
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.

The current EditTarget must have UsdEditTarget::IsLocalLayer() == true.

The given path must be an absolute, root prim path that does not contain any variant selections.

If a defined (UsdPrim::IsDefined()) non-class prim already exists at path, issue an error and return an invalid UsdPrim.

If it is impossible to author the necessary PrimSpec, issue an error and return an invalid UsdPrim.

static USD_API UsdStageRefPtr CreateInMemory ( InitialLoadSet  load = LoadAll)
static

Creates a new stage only in memory, analogous to creating an anonymous SdfLayer.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContext.

The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Invoking an overload that does not take a sessionLayer argument will create a stage with an anonymous in-memory session layer. To create a stage without a session layer, pass TfNullPtr (or None in python) as the sessionLayer argument.

static USD_API UsdStageRefPtr CreateInMemory ( const std::string &  identifier,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

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 
)
static

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 
)
static

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,
InitialLoadSet  load = LoadAll 
)
static

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.

See Also
SdfLayer::CreateNew()

Invoking an overload that does not take a sessionLayer argument will create a stage with an anonymous in-memory session layer. To create a stage without a session layer, pass TfNullPtr (or None in python) as the sessionLayer argument. The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its real path.
static USD_API UsdStageRefPtr CreateNew ( const std::string &  identifier,
const SdfLayerHandle &  sessionLayer,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

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 
)
static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

If a prim at path is already defined on this stage and typeName is empty or equal to the existing prim's typeName, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and typeName for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs (for example, in case path cannot map to the current UsdEditTarget's namespace or one of the ancestors of path is inactive on the UsdStage), issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not match the supplied typeName, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

USD_API void ExpandPopulationMask ( 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.

If relPred is null, include all relationship targets; if attrPred is null, include all connections.

This function can be used, for example, to expand a population mask for a given prim to include bound materials, if those bound materials are expressed as relationships or attribute connections.

See also UsdPrim::FindAllRelationshipTargetPaths() and UsdPrim::FindAllAttributeConnectionPaths().

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.

If addSourceFileComment is true, a comment in the output layer will mention the input layer it was generated from.

See UsdStage::Flatten for details of the flattening transformation.

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.

If addSourceFileComment is true, a comment in the output layer will mention the input layer it was generated from.

See UsdStage::Flatten for details of the flattening transformation.

USD_API SdfPathSet FindLoadable ( const SdfPath rootPath = SdfPath::AbsoluteRootPath())

Returns an SdfPathSet of all paths that can be loaded.

Note that this method does not return paths to inactive prims as they cannot be loaded.

The set returned includes loaded and unloaded paths. To determine the set of unloaded paths, one can diff this set with the current load set, for example:

* SdfPathSet loaded = stage->GetLoadSet(),
* all = stage->FindLoadable(),
* result;
* std::set_difference(loaded.begin(), loaded.end(),
* all.begin(), all.end(),
* std::inserter(result, result.end()));
*

See Working Set Management for more information.

USD_API SdfLayerRefPtr Flatten ( bool  addSourceFileComment = true) const

Returns a single, anonymous, merged layer for this composite scene.

Specifically, this function removes most composition metadata and authors the resolved values for each object directly into the flattened layer.

All VariantSets are removed and only the currently selected variants will be present in the resulting layer.

Class prims will still exist, however all inherits arcs will have been removed and the inherited data will be copied onto each child object. Composition arcs authored on the class itself will be flattened into the class.

Flatten preserves scenegraph instancing by creating independent roots for each master currently composed on this stage, and adding a single internal reference arc on each instance prim to its corresponding master.

Time samples across sublayer offsets will will have the time offset and scale applied to each time index.

Finally, any deactivated prims will be pruned from the result.

static USD_API void GetColorConfigFallbacks ( SdfAssetPath colorConfiguration,
TfToken colorManagementSystem 
)
static

Returns the global fallback values of 'colorConfiguration' and 'colorManagementSystem'.

These are set in the plugInfo.json file of a plugin, but can be overridden by calling the static method SetColorConfigFallbacks().

The python wrapping of this method returns a tuple containing (colorConfiguration, colorManagementSystem).

See Also
SetColorConfigFallbacks, Color Configuration API
USD_API SdfAssetPath GetColorConfiguration ( ) const

Returns the default color configuration used to interpret the per- attribute color-spaces in the composed USD stage.

Color Configuration API

USD_API TfToken GetColorManagementSystem ( ) const

Sets the name of the color management system to be used for loading and interpreting the color configuration file.

Color Configuration API

USD_API UsdPrim GetDefaultPrim ( ) const

Return the root UsdPrim on this stage whose name is the root layer's defaultPrim metadata's value.

Return an invalid prim if there is no such prim or if the root layer's defaultPrim metadata is unset or is not a valid prim name. Note that this function only examines this stage's rootLayer. It does not consider sublayers of the rootLayer. See also SdfLayer::GetDefaultPrim().

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.

This edit target will incorporate any layer time offset that applies to the sublayer.

USD_API UsdEditTarget GetEditTargetForLocalLayer ( const SdfLayerHandle &  layer)

Return a UsdEditTarget for editing the given local layer.

If the given layer appears more than once in the layer stack, the time offset to the first occurrence will be used.

USD_API double GetEndTimeCode ( ) const

Returns the stage's end timeCode.

If the stage has an associated session layer with an end timeCode opinion, this value is returned. Otherwise, the end timeCode opinion from the root layer is returned.

USD_API double GetFramesPerSecond ( ) const

Returns the stage's framesPerSecond value.

This makes an advisory statement about how the contained data can be most usefully consumed and presented. It's primarily an indication of the expected playback rate for the data, but a timeline editing tool might also want to use this to decide how to scale and label its timeline.

The default value of framesPerSecond is 24.

static USD_API PcpVariantFallbackMap GetGlobalVariantFallbacks ( )
static

Get the global variant fallback preferences used in new UsdStages.

USD_API UsdInterpolationType GetInterpolationType ( ) const

Returns the interpolation type used during value resolution for all attributes on this stage.

USD_API SdfLayerHandleVector GetLayerStack ( bool  includeSessionLayers = true) const

Return this stage's local layers in strong-to-weak order.

If 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. If includeSessionLayers is false, omit the sublayers rooted at this stage's session layer.

UsdStageLoadRules const& GetLoadRules ( ) const
inline

Return the stage's current UsdStageLoadRules governing payload inclusion.

See Working Set Management for more information.

Definition at line 639 of file stage.h.

USD_API SdfPathSet GetLoadSet ( )

Returns a set of all loaded paths.

The paths returned are both those that have been explicitly loaded and those that were loaded as a result of dependencies, ancestors or descendants of explicitly loaded paths.

This method does not return paths to inactive prims.

See Working Set Management for more information.

USD_API std::vector<UsdPrim> GetMasters ( ) const

Returns all master prims.

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.

Order of resolution is session layer, followed by root layer, else fallback to the SdfSchema.

Returns
true if we successfully retrieved a value of the requested type; false if key is not allowed as layer metadata or no value was found. Generates a coding error if we retrieved a stored value of a type other than the requested type
See Also
General Metadata in USD

Definition at line 2124 of file stage.h.

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.

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.

If you know you need just a small number of elements from a dictionary, accessing them element-wise using this method can be much less expensive than fetching the entire dictionary with GetMetadata(key).

Returns
true if we successfully retrieved a value of the requested type; false if key is not allowed as layer metadata or no value was found. Generates a coding error if we retrieved a stored value of a type other than the requested type

The keyPath is a ':'-separated path addressing an element in subdictionaries. If keyPath is empty, returns an empty VtValue.

Definition at line 2154 of file stage.h.

USD_API bool GetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
VtValue value 
) const

overload

USD_API const std::vector<std::string>& GetMutedLayers ( ) const

Returns a vector of all layers that have been muted on this stage.

USD_API UsdObject GetObjectAtPath ( const SdfPath path) const

Return the UsdObject at path, or an invalid UsdObject if none exists.

If path indicates a prim beneath an instance, returns an instance proxy prim if a prim exists at the corresponding path in that instance's master. If path indicates a property beneath a child of an instance, returns a property whose parent prim is an instance proxy prim.

Example:

* if (UsdObject obj = stage->GetObjectAtPath(path)) {
* if (UsdPrim prim = obj.As<UsdPrim>()) {
* // Do things with prim
* }
* else if (UsdProperty prop = obj.As<UsdProperty>()) {
* // Do things with property. We can also cast to
* // UsdRelationship or UsdAttribute using this same pattern.
* }
* }
* else {
* // No object at specified path
* }
*
USD_API ArResolverContext GetPathResolverContext ( ) const

Return the path resolver context for all path resolution during composition of this stage.

Useful for external clients that want to resolve paths with the same context as this stage, or create new stages with the same context.

UsdStagePopulationMask GetPopulationMask ( ) const
inline

Return this stage's population mask.

Definition at line 656 of file stage.h.

USD_API UsdPrim GetPrimAtPath ( const SdfPath path) const

Return the UsdPrim at path, or an invalid UsdPrim if none exists.

If path indicates a prim beneath an instance, returns an instance proxy prim if a prim exists at the corresponding path in that instance's master.

Unlike OverridePrim() and DefinePrim(), this method will never author scene description, and therefore is safe to use as a "reader" in the Usd multi-threading model.

USD_API UsdPrim GetPseudoRoot ( ) const

Return the stage's "pseudo-root" prim, whose name is defined by Usd.

The stage's named root prims are namespace children of this prim, which exists to make the namespace hierarchy a tree instead of a forest. This simplifies algorithms that want to traverse all prims.

A UsdStage always has a pseudo-root prim, unless there was an error opening or creating the stage, in which case this method returns an invalid UsdPrim.

USD_API SdfLayerHandle GetRootLayer ( ) const

Return this stage's root layer.

USD_API SdfLayerHandle GetSessionLayer ( ) const

Return this stage's root session layer.

USD_API double GetStartTimeCode ( ) const

Returns the stage's start timeCode.

If the stage has an associated session layer with a start timeCode opinion, this value is returned. Otherwise, the start timeCode opinion from the root layer is returned.

USD_API double GetTimeCodesPerSecond ( ) const

Returns the stage's timeCodesPerSecond value.

The timeCodesPerSecond value scales the time ordinate for the samples contained in the stage to seconds. If timeCodesPerSecond is 24, then a sample at time ordinate 24 should be viewed exactly one second after the sample at time ordinate 0.

The default value of timeCodesPerSecond is 24.

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.

The list of consumed layers will change with the stage's load-set and variant selections, so the return value should be considered only a snapshot. The return value will include the stage's session layer, if it has one. If includeClipLayers is true, we will also include all of the layers that this stage has had to open so far to perform value resolution of attributes affected by Value Clips

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.

Note
If a value for a metadatum not legal to author on layers is present in the root or session layer (which could happen through hand-editing or use of certain low-level API's), this method will still return false.
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.

The keyPath is a ':'-separated path identifying a value in subdictionaries stored in the metadata field at key. If keyPath is empty, returns false.

See Also
Dictionary-valued Metadata
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 bool HasDefaultPrim ( ) const

Return true if this stage's root layer has an authored opinion for the default prim layer metadata.

This is shorthand for:

* stage->GetRootLayer()->HasDefaultPrim();
*

Note that this function only consults the stage's root layer. To consult a different layer, use the SdfLayer::HasDefaultPrim() API.

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 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.

Returns false if key is not allowed as layer metadata.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries stored in the metadata field at key. If keyPath is empty, returns false.

Returns false if key is not allowed as layer metadata.

See Also
Dictionary-valued Metadata
USD_API bool IsLayerMuted ( const std::string &  layerIdentifier) const

Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise.

See documentation on MuteLayer for details on how layerIdentifier is compared to the layers that have been muted.

static USD_API bool IsSupportedFile ( const std::string &  filePath)
static

Indicates whether the specified file is supported by UsdStage.

This function is a cheap way to determine whether a file might be open-able with UsdStage::Open. It is purely based on the given filePath and does not open the file or perform analysis on the contents. As such, UsdStage::Open may still fail even if this function returns true.

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.

If policy is UsdLoadWithoutDescendants, then payloads on descendant prims are not loaded.

See Working Set Management for more information.

USD_API void LoadAndUnload ( const SdfPathSet &  loadSet,
const SdfPathSet &  unloadSet,
UsdLoadPolicy  policy = UsdLoadWithDescendants 
)

Unload and load the given path sets.

The effect is as if the unload set were processed first followed by the load set.

This is equivalent to calling UsdStage::Unload for each item in the unloadSet followed by UsdStage::Load for each item in the loadSet, however this method is more efficient as all operations are committed in a single batch. The policy argument is described in the documentation for Load().

See Working Set Management for more information.

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.

This is equivalent to calling UsdStage::UnmuteLayer for each layer in unmuteLayers followed by UsdStage::MuteLayer for each layer in muteLayers, however this method is more efficient as all operations are committed in a single batch.

USD_API void MuteLayer ( const std::string &  layerIdentifier)

Mute the layer identified by layerIdentifier.

Muted layers are ignored by the stage; they do not participate in value resolution or composition and do not appear in any LayerStack. If the root layer of a reference or payload LayerStack is muted, the behavior is as if the muted layer did not exist, which means a composition error will be generated.

A canonical identifier for layerIdentifier will be computed using ArResolver::ComputeRepositoryPath. Any layer encountered during composition with the same repository path will be considered muted and ignored. Relative paths will be assumed to be relative to the cache's root layer. Search paths are immediately resolved and the result is used for computing the canonical path.

Note that muting a layer will cause this stage to release all references to that layer. If no other client is holding on to references to that layer, it will be unloaded. In this case, if there are unsaved edits to the muted layer, those edits are lost. Since anonymous layers are not serialized, muting an anonymous layer will cause that layer and its contents to be lost in this case.

Muting a layer that has not been used by this stage is not an error. If that layer is encountered later, muting will take effect and that layer will be ignored.

The root layer of this stage may not be muted; attempting to do so will generate a coding error.

static USD_API UsdStageRefPtr Open ( const std::string &  filePath,
InitialLoadSet  load = LoadAll 
)
static

Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the stack.

Failing that, create a new stage and recursively compose prims defined within and referenced by the layer at filePath, which must already exist.

The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its real path.
static USD_API UsdStageRefPtr Open ( const std::string &  filePath,
const ArResolverContext pathResolverContext,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

Open a stage rooted at rootLayer.

Attempt to find a stage that matches the passed arguments in a UsdStageCache if UsdStageCacheContext objects exist on the calling stack. If a matching stage is found, return that stage. Otherwise, create a new stage rooted at rootLayer.

Invoking an overload that does not take a sessionLayer argument will create a stage with an anonymous in-memory session layer. To create a stage without a session layer, pass TfNullPtr (or None in python) as the sessionLayer argument.

The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its real path.

When searching for a matching stage in bound UsdStageCache s, only the provided arguments matter for cache lookup. For example, if only a root layer (or a root layer file path) is provided, the first stage found in any cache that has that root layer is returned. So, for example if you require that the stage have no session layer, you must explicitly specify TfNullPtr (or None in python) for the sessionLayer argument.

static USD_API UsdStageRefPtr Open ( const SdfLayerHandle &  rootLayer,
const SdfLayerHandle &  sessionLayer,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

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 
)
static

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 
)
static

Create a new stage and recursively compose prims defined within and referenced by the layer at filePath which must already exist, subject to mask.

These OpenMasked() methods do not automatically consult or populate UsdStageCache s.

The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its real path.
static USD_API UsdStageRefPtr OpenMasked ( const std::string &  filePath,
const ArResolverContext pathResolverContext,
UsdStagePopulationMask const &  mask,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

Open a stage rooted at rootLayer and with limited population subject to mask.

These OpenMasked() methods do not automatically consult or populate UsdStageCache s.

Invoking an overload that does not take a sessionLayer argument will create a stage with an anonymous in-memory session layer. To create a stage without a session layer, pass TfNullPtr (or None in python) as the sessionLayer argument.

The initial set of prims to load on the stage can be specified using the load parameter.

See Also
UsdStage::InitialLoadSet.

Note that the pathResolverContext passed here will apply to all path resolutions for this stage, regardless of what other context may be bound at resolve time. If no context is passed in here, Usd will create one by calling

See Also
ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its real path.
static USD_API UsdStageRefPtr OpenMasked ( const SdfLayerHandle &  rootLayer,
const SdfLayerHandle &  sessionLayer,
const UsdStagePopulationMask mask,
InitialLoadSet  load = LoadAll 
)
static

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 
)
static

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 
)
static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

USD_API UsdPrim OverridePrim ( const SdfPath path)

Attempt to ensure a UsdPrim at path exists on this stage.

If a prim already exists at path, return it. Otherwise author SdfPrimSpecs with specifier == SdfSpecifierOver and empty typeName at the current EditTarget to create this prim and any nonexistent ancestors, then return it.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget's namespace) issue an error and return an invalid UsdPrim.

If an ancestor of path identifies an inactive prim, author scene description as described above but return an invalid prim, since the resulting prim is descendant to an inactive prim.

USD_API void Reload ( )

Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers of session layers.

This includes non-session sublayers, references and payloads. Note that reloading anonymous layers clears their content, so invoking Reload() on a stage constructed via CreateInMemory() will clear its root layer.

Note
This method is considered a mutation, which has potentially global effect! Unlike the various Load() methods whose actions affect only this stage, Reload() may cause layers to change their contents, and because layers are global resources shared by potentially many Stages, calling Reload() on one stage may result in a mutation to any number of stages. In general, unless you are highly confident your stage is the only consumer of its layers, you should only call Reload() when you are assured no other threads may be reading from any Stages.
USD_API bool RemovePrim ( const SdfPath path)

Remove all scene description for the given path and its subtree in the current UsdEditTarget.

This method does not do what you might initially think! Calling this function will not necessarily cause the UsdPrim at path on this stage to disappear. Completely eradicating a prim from a composition can be an involved process, involving edits to many contributing layers, some of which (in many circumstances) will not be editable by a client. This method is a surgical instrument that can be used iteratively to effect complete removal of a prim and its subtree from namespace, assuming the proper permissions are acquired, but more commonly it is used to perform layer-level operations; e.g.: ensuring that a given layer (as expressed by a UsdEditTarget) provides no opinions for a prim and its subtree.

Generally, if your eye is attracted to this method, you probably want to instead use UsdPrim::SetActive(false) , which will provide the composed effect of removing the prim and its subtree from the composition, without actually removing any scene description, which as a bonus, means that the effect is reversible at a later time!

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.

@./siblingFile.usd@).

Returns
a non-empty string containing either the same identifier that was passed in (if the identifier refers to an already-opened layer or an "anonymous", in-memory layer), or a resolved layer filepath. If the identifier was not resolvable, return the empty string.
USD_API void Save ( )

Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublayers of session layers.

This function will emit a warning and skip each dirty anonymous layer it encounters, since anonymous layers cannot be saved with SdfLayer::Save. These layers must be manually exported by calling SdfLayer::Export.

USD_API void SaveSessionLayers ( )

Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this stage.

This function will emit a warning and skip each dirty anonymous layer it encounters, since anonymous layers cannot be saved with SdfLayer::Save. These layers must be manually exported by calling SdfLayer::Export.

static USD_API void SetColorConfigFallbacks ( const SdfAssetPath colorConfiguration,
const TfToken colorManagementSystem 
)
static

Sets the global fallback values of color configuration metadata which includes the 'colorConfiguration' asset path and the name of the color management system.

This overrides any fallback values authored in plugInfo files.

If the specified value of colorConfiguration or colorManagementSystem is empty, then the corresponding fallback value isn't set. In other words, for this call to have an effect, at least one value must be non-empty. Additionally, these can't be reset to empty values.

See Also
GetColorConfigFallbacks() Color Configuration API
USD_API void SetColorConfiguration ( const SdfAssetPath colorConfig) const

Sets the default color configuration to be used to interpret the per-attribute color-spaces in the composed USD stage.

This is specified as asset path which can be resolved to the color spec file.

Color Configuration API

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.

Color Configuration API

USD_API void SetDefaultPrim ( const UsdPrim prim)

Set the default prim layer metadata in this stage's root layer.

This is shorthand for:

* stage->GetRootLayer()->SetDefaultPrim(prim.GetName());
*

Note that this function always authors to the stage's root layer. To author to a different layer, use the SdfLayer::SetDefaultPrim() API.

USD_API void SetEditTarget ( const UsdEditTarget editTarget)

Set the stage's EditTarget.

If editTarget.IsLocalLayer(), check to see if it's a layer in this stage's local LayerStack. If not, issue an error and do nothing. If editTarget is invalid, issue an error and do nothing. If editTarget differs from the stage's current EditTarget, set the EditTarget and send UsdNotice::StageChangedEditTarget. Otherwise do nothing.

USD_API void SetEndTimeCode ( double  )

Sets the stage's end timeCode.

The end timeCode is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and the end timeCode is not set.

USD_API void SetFramesPerSecond ( double  framesPerSecond) const

Sets the stage's framesPerSecond value.

The framesPerSecond value is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and no value is set.

See Also
GetFramesPerSecond()
static USD_API void SetGlobalVariantFallbacks ( const PcpVariantFallbackMap fallbacks)
static

Set the global variant fallback preferences used in new UsdStages.

This overrides any fallbacks configured in plugin metadata, and only affects stages created after this call.

Note
This does not affect existing UsdStages.
USD_API void SetInterpolationType ( UsdInterpolationType  interpolationType)

Sets the interpolation type used during value resolution for all attributes on this stage.

Changing this will cause a UsdNotice::StageContentsChanged notice to be sent, as values at times where no samples are authored may have changed.

USD_API void SetLoadRules ( UsdStageLoadRules const &  rules)

Set the UsdStageLoadRules to govern payload inclusion on this stage.

This rebuilds the stage's entire prim hierarchy to follow rules.

Note that subsequent calls to Load(), Unload(), LoadAndUnload() will modify this stages load rules as described in the documentation for those member functions.

See Working Set Management for more information.

bool SetMetadata ( const TfToken key,
const T &  value 
) const

Set the value of Stage metadatum key to value, if the stage's current UsdEditTarget is the root or session layer.

If the current EditTarget is any other layer, raise a coding error.

Returns
true if authoring was successful, false otherwise. Generates a coding error if key is not allowed as layer metadata.
See Also
General Metadata in USD

Definition at line 2146 of file stage.h.

USD_API bool SetMetadata ( const TfToken key,
const 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.

bool SetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
const T &  value 
) const

Author value to the field identified by key and keyPath at the current EditTarget.

The keyPath is a ':'-separated path identifying a value in subdictionaries stored in the metadata field at key. If keyPath is empty, no action is taken.

Returns
true if the value is authored successfully, false otherwise. Generates a coding error if key is not allowed as layer metadata.
See Also
Dictionary-valued Metadata

Definition at line 2178 of file stage.h.

USD_API bool SetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
const 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 void SetPopulationMask ( UsdStagePopulationMask const &  mask)

Set this stage's population mask and recompose the stage.

USD_API void SetStartTimeCode ( double  )

Sets the stage's start timeCode.

The start timeCode is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and the start timeCode is not set.

USD_API void SetTimeCodesPerSecond ( double  timeCodesPerSecond) const

Sets the stage's timeCodesPerSecond value.

The timeCodesPerSecond value is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and no value is set.

See Also
GetTimeCodesPerSecond()
USD_API UsdPrimRange Traverse ( )

Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.

Traverse() returns a UsdPrimRange , which allows low-latency traversal, with the ability to prune subtrees from traversal. It is python iterable, so in its simplest form, one can do:

1 * for prim in stage.Traverse():
2 * print prim.GetPath()
3 *

If either a pre-and-post-order traversal or a traversal rooted at a particular prim is desired, construct a UsdPrimRange directly.

This is equivalent to UsdPrimRange::Stage() .

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.

This is equivalent to UsdPrimRange::Stage() .

USD_API UsdPrimRange TraverseAll ( )

Traverse all the prims on this stage depth-first.

See Also
Traverse()
UsdPrimRange::Stage()
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.

See Working Set Management for more information.

USD_API void UnmuteLayer ( const std::string &  layerIdentifier)

Unmute the layer identified by layerIdentifier if it had previously been muted.


The documentation for this class was generated from the following file: