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

#include <stage.h>

+ Inheritance diagram for UsdStage:

Public Member Functions

template<>
USD_API bool _GetTypeSpecificResolvedMetadata (const UsdObject &obj, const TfToken &fieldName, const TfToken &keyPath, bool useFallbacks, SdfTimeSampleMap *result) const
 
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 UsdEditTargetGetEditTarget () 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.
 
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.
 
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.
 
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.
 
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.
 
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 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< UsdPrimGetPrototypes () const
 Returns all native instancing prototype prims.
 
- Public Member Functions inherited from TfRefBase
 TfRefBase (TfRefBase const &)
 
TfRefBaseoperator= (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 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.
 
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.
 
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.
 

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(
stage->GetColorConfiguration());
}
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
bool IsEmpty() const
Returns true iff this token contains the empty string "".
Definition: token.h:288
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160
USD_API TfToken GetColorSpace() const
Gets the color space in which the attribute is authored.
UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ...
Definition: prim.h:117
USD_API UsdAttribute GetAttribute(const TfToken &attrName) const
Return a UsdAttribute with the name attrName.
USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const
Returns the prim at path on the same stage as this prim.
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 sta...
See also
UsdAttribute ColorSpace API
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 to interpret the per-attribute color-spaces in the composed USD stage.
 
USD_API SdfAssetPath GetColorConfiguration () const
 Returns the default color configuration used to interpret the per- attribute color-spaces in the composed USD stage.
 
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 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 UsdEditContext.

Definition at line 136 of file stage.h.

Member Enumeration Documentation

◆ InitialLoadSet

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 149 of file stage.h.

Member Function Documentation

◆ ClearDefaultPrim()

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.

◆ ClearMetadata()

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

◆ ClearMetadataByDictKey()

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

◆ CreateClassPrim()

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.

◆ CreateInMemory() [1/5]

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.

◆ CreateInMemory() [2/5]

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.

◆ CreateInMemory() [3/5]

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.

◆ CreateInMemory() [4/5]

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.

◆ CreateInMemory() [5/5]

static USD_API UsdStageRefPtr CreateInMemory ( InitialLoadSet  load = LoadAll)
static

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

If pathResolverContext is provided it will be bound when creating the root layer at identifier and whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will create the root layer with no context bound, then create a context for all future asset path resolution for the stage by calling 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.

◆ CreateNew() [1/4]

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.

◆ CreateNew() [2/4]

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.

◆ CreateNew() [3/4]

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.

◆ CreateNew() [4/4]

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.

If pathResolverContext is provided it will be bound when creating the root layer at identifier and whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will create the root layer with no context bound, then create a context for all future asset path resolution for the stage by calling ArResolver::CreateDefaultContextForAsset with the root layer's repository path if the layer has one, otherwise its resolved path.

◆ DefinePrim()

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.

◆ ExpandPopulationMask() [1/2]

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.

◆ ExpandPopulationMask() [2/2]

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.

The attributes and relationships are those on all the prims found by traversing the stage according to traversalPredicate. 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().

◆ Export()

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.

◆ ExportToString()

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.

◆ FindLoadable()

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.

◆ Flatten()

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 prototype currently composed on this stage, and adding a single internal reference arc on each instance prim to its corresponding prototype.

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.

◆ GetAttributeAtPath()

USD_API UsdAttribute GetAttributeAtPath ( const SdfPath path) const

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

This is equivalent to

stage.GetObjectAtPath(path).As<UsdAttribute>();
See also
GetObjectAtPath(const SdfPath&) const

◆ GetColorConfigFallbacks()

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

◆ GetColorConfiguration()

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

◆ GetColorManagementSystem()

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

◆ GetCompositionErrors()

USD_API PcpErrorVector GetCompositionErrors ( ) const

Return a PcpErrorVector containing all composition errors encountered when composing the prims and layer stacks on this stage.

◆ GetDefaultPrim()

USD_API UsdPrim GetDefaultPrim ( ) const

Return the UsdPrim on this stage whose path 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 path. Note that this function will return the prim on the stage whose path is the root layer's GetDefaultPrimAsPath() if that path is not empty and a prim at that path exists on the stage. See also SdfLayer::GetDefaultPrimAsPath().

◆ GetEditTarget()

USD_API const UsdEditTarget & GetEditTarget ( ) const

Return the stage's EditTarget.

◆ GetEditTargetForLocalLayer() [1/2]

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.

◆ GetEditTargetForLocalLayer() [2/2]

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.

◆ GetEndTimeCode()

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.

◆ GetFramesPerSecond()

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.

◆ GetGlobalVariantFallbacks()

static USD_API PcpVariantFallbackMap GetGlobalVariantFallbacks ( )
static

Get the global variant fallback preferences used in new UsdStages.

◆ GetInterpolationType()

USD_API UsdInterpolationType GetInterpolationType ( ) const

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

◆ GetLayerStack()

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.

If includeSessionLayers is false, omit the sublayers rooted at this stage's session layer.

◆ GetLoadRules()

UsdStageLoadRules const & GetLoadRules ( ) const
inline

Return the stage's current UsdStageLoadRules governing payload inclusion.

See Working Set Management for more information.

Definition at line 638 of file stage.h.

◆ GetLoadSet()

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.

◆ GetMetadata() [1/2]

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 2399 of file stage.h.

◆ GetMetadata() [2/2]

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.

◆ GetMetadataByDictKey() [1/2]

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 2429 of file stage.h.

◆ GetMetadataByDictKey() [2/2]

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

overload

◆ GetMutedLayers()

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

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

◆ GetObjectAtPath()

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 prototype. 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
}
Base class for Usd scenegraph objects, providing common API.
Definition: object.h:115
T As() const
Convert this UsdObject to another object type T if possible.
Definition: object.h:229
Base class for UsdAttribute and UsdRelationship scenegraph objects.
Definition: property.h:38

◆ GetPathResolverContext()

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.

◆ GetPopulationMask()

UsdStagePopulationMask GetPopulationMask ( ) const
inline

Return this stage's population mask.

Definition at line 655 of file stage.h.

◆ GetPrimAtPath()

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

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.

◆ GetPropertyAtPath()

USD_API UsdProperty GetPropertyAtPath ( const SdfPath path) const

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

This is equivalent to

stage.GetObjectAtPath(path).As<UsdProperty>();
See also
GetObjectAtPath(const SdfPath&) const

◆ GetPrototypes()

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

Returns all native instancing prototype prims.

◆ GetPseudoRoot()

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.

◆ GetRelationshipAtPath()

USD_API UsdRelationship GetRelationshipAtPath ( const SdfPath path) const

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

This is equivalent to

stage.GetObjectAtPath(path).As<UsdRelationship>();
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other ...
Definition: relationship.h:111
See also
GetObjectAtPath(const SdfPath&) const

◆ GetRootLayer()

USD_API SdfLayerHandle GetRootLayer ( ) const

Return this stage's root layer.

◆ GetSessionLayer()

USD_API SdfLayerHandle GetSessionLayer ( ) const

Return this stage's root session layer.

◆ GetStartTimeCode()

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.

◆ GetTimeCodesPerSecond()

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.

Like SdfLayer::GetTimeCodesPerSecond, this accessor uses a dynamic fallback to framesPerSecond. The order of precedence is:

  • timeCodesPerSecond from session layer
  • timeCodesPerSecond from root layer
  • framesPerSecond from session layer
  • framesPerSecond from root layer
  • fallback value of 24

◆ GetUsedLayers()

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

◆ HasAuthoredMetadata()

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.

◆ HasAuthoredMetadataDictKey()

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

◆ HasAuthoredTimeCodeRange()

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.

◆ HasDefaultPrim()

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.

◆ HasLocalLayer()

USD_API bool HasLocalLayer ( const SdfLayerHandle &  layer) const

Return true if layer is one of the layers in this stage's local, root layerStack.

◆ HasMetadata()

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.

◆ HasMetadataDictKey()

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

◆ IsLayerMuted()

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.

◆ IsSupportedFile()

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.

◆ Load()

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.

◆ LoadAndUnload()

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.

◆ MuteAndUnmuteLayers()

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.

◆ MuteLayer()

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 each layer in layersToMute will be computed using ArResolver::CreateIdentifier using the stage's root layer as the anchoring asset. Any layer encountered during composition with the same identifier will be considered muted and ignored.

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.

◆ Open() [1/6]

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.

◆ Open() [2/6]

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.

◆ Open() [3/6]

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.

◆ Open() [4/6]

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.

If pathResolverContext is provided it will be bound when whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will create a context for all future asset path resolution for the stage by calling ArResolver::CreateDefaultContextForAsset with the layer's repository path if the layer has one, otherwise its resolved 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.

◆ Open() [5/6]

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.

◆ Open() [6/6]

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.

If pathResolverContext is provided it will be bound when opening the root layer at filePath and whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will open the root layer with no context bound, then create a context for all future asset path resolution for the stage by calling ArResolver::CreateDefaultContextForAsset with the layer's repository path if the layer has one, otherwise its resolved path.

◆ OpenMasked() [1/6]

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.

◆ OpenMasked() [2/6]

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.

◆ OpenMasked() [3/6]

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.

◆ OpenMasked() [4/6]

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.

If pathResolverContext is provided it will be bound when whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will create a context for all future asset path resolution for the stage by calling ArResolver::CreateDefaultContextForAsset with the layer's repository path if the layer has one, otherwise its resolved path.

◆ OpenMasked() [5/6]

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.

◆ OpenMasked() [6/6]

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.

If pathResolverContext is provided it will be bound when opening the root layer at filePath and whenever asset path resolution is done for this stage, regardless of what other context may be bound at that time. Otherwise Usd will open the root layer with no context bound, then create a context for all future asset path resolution for the stage by calling ArResolver::CreateDefaultContextForAsset with the layer's repository path if the layer has one, otherwise its resolved path.

◆ OverridePrim()

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.

◆ Reload()

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.

◆ RemovePrim()

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!

◆ ResolveIdentifierToEditTarget()

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.

◆ Save()

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.

◆ SaveSessionLayers()

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.

◆ SetColorConfigFallbacks()

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

◆ SetColorConfiguration()

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

◆ SetColorManagementSystem()

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

◆ SetDefaultPrim()

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());

If prim is a root prim, otherwise

stage->GetRootLayer()->SetDefaultPrim(prim.GetPath().GetAsToken());

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

◆ SetEditTarget()

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.

◆ SetEndTimeCode()

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.

◆ SetFramesPerSecond()

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

◆ SetGlobalVariantFallbacks()

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.

◆ SetInterpolationType()

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.

◆ SetLoadRules()

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.

◆ SetMetadata() [1/2]

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 2421 of file stage.h.

◆ SetMetadata() [2/2]

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.

◆ SetMetadataByDictKey() [1/2]

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 2453 of file stage.h.

◆ SetMetadataByDictKey() [2/2]

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.

◆ SetPopulationMask()

USD_API void SetPopulationMask ( UsdStagePopulationMask const &  mask)

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

◆ SetStartTimeCode()

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.

◆ SetTimeCodesPerSecond()

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

◆ Traverse() [1/2]

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:

for prim in stage.Traverse():
print prim.GetPath()

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

You'll need to use the returned UsdPrimRange's iterator to perform actions such as pruning subtrees. See the "Using Usd.PrimRange in python" section in UsdPrimRange for more details and examples.

This is equivalent to UsdPrimRange::Stage() .

◆ Traverse() [2/2]

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

◆ TraverseAll()

USD_API UsdPrimRange TraverseAll ( )

Traverse all the prims on this stage depth-first.

See also
Traverse()
UsdPrimRange::Stage()

◆ Unload()

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.

◆ UnmuteLayer()

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

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

◆ WriteFallbackPrimTypes()

USD_API void WriteFallbackPrimTypes ( )

Writes the fallback prim types defined in the schema registry to the stage as dictionary valued fallback prim type metadata.

If the stage already has fallback prim type metadata, the fallback types from the schema registry will be added to the existing metadata, only for types that are already present in the dictionary, i.e. this won't overwrite existing fallback entries.

The current edit target determines whether the metadata is written to the root layer or the session layer. If the edit target specifies another layer besides these, this will produce an error.

This function can be used at any point before calling Save or Export on a stage to record the fallback types for the current schemas. This allows another version of Usd to open this stage and treat prim types it doesn't recognize as a type it does recognize defined for it in this metadata.

See also
Fallback Prim Types UsdSchemaRegistry::GetFallbackPrimTypes

Friends And Related Function Documentation

◆ UsdAPISchemaBase

friend class UsdAPISchemaBase
friend

Definition at line 2360 of file stage.h.

◆ UsdAttribute

friend class UsdAttribute
friend

Definition at line 2361 of file stage.h.

◆ UsdAttributeQuery

friend class UsdAttributeQuery
friend

Definition at line 2362 of file stage.h.

◆ UsdEditTarget

friend class UsdEditTarget
friend

Definition at line 2363 of file stage.h.

◆ UsdInherits

friend class UsdInherits
friend

Definition at line 2364 of file stage.h.

◆ UsdNamespaceEditor

friend class UsdNamespaceEditor
friend

Definition at line 2365 of file stage.h.

◆ UsdObject

friend class UsdObject
friend

Definition at line 2366 of file stage.h.

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 2367 of file stage.h.

◆ UsdProperty

friend class UsdProperty
friend

Definition at line 2368 of file stage.h.

◆ UsdRelationship

friend class UsdRelationship
friend

Definition at line 2369 of file stage.h.

◆ UsdSpecializes

friend class UsdSpecializes
friend

Definition at line 2370 of file stage.h.

◆ UsdVariantSet

friend class UsdVariantSet
friend

Definition at line 2371 of file stage.h.

◆ UsdVariantSets

friend class UsdVariantSets
friend

Definition at line 2372 of file stage.h.


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