HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdStage Class Reference

#include <stage.h>

+ Inheritance diagram for UsdStage:

Classes

struct  _HasTypeSpecificResolution
 

Public Member Functions

template<>
USD_API bool _GetTypeSpecificResolvedMetadata (const UsdObject &obj, const TfToken &fieldName, const TfToken &keyPath, bool useFallbacks, SdfTimeSampleMap *result) const
 
template<class T >
std::enable_if
< !UsdStage::_HasTypeSpecificResolution
< T >::value, bool >::type 
_GetMetadata (const UsdObject &obj, const TfToken &fieldName, const TfToken &keyPath, bool useFallbacks, T *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 ()
 
USD_API void SaveSessionLayers ()
 
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)
 
USD_API void Unload (const SdfPath &path=SdfPath::AbsoluteRootPath())
 
USD_API void LoadAndUnload (const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants)
 
USD_API SdfPathSet GetLoadSet ()
 
USD_API SdfPathSet FindLoadable (const SdfPath &rootPath=SdfPath::AbsoluteRootPath())
 
UsdStageLoadRules const & GetLoadRules () const
 
USD_API void SetLoadRules (UsdStageLoadRules const &rules)
 
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 (Usd_PrimFlagsPredicate const &traversalPredicate, std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
 
USD_API void ExpandPopulationMask (std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr)
 
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
 
USD_API std::string ResolveIdentifierToEditTarget (std::string const &identifier) const
 
USD_API SdfLayerHandleVector GetLayerStack (bool includeSessionLayers=true) const
 
USD_API SdfLayerHandleVector GetUsedLayers (bool includeClipLayers=true) const
 
USD_API bool HasLocalLayer (const SdfLayerHandle &layer) const
 
USD_API const UsdEditTargetGetEditTarget () const
 Return the stage's EditTarget. More...
 
USD_API UsdEditTarget GetEditTargetForLocalLayer (size_t i)
 
USD_API UsdEditTarget GetEditTargetForLocalLayer (const SdfLayerHandle &layer)
 
USD_API void SetEditTarget (const UsdEditTarget &editTarget)
 
USD_API void MuteLayer (const std::string &layerIdentifier)
 
USD_API void UnmuteLayer (const std::string &layerIdentifier)
 
USD_API void MuteAndUnmuteLayers (const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers)
 
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
 
Flatten & Export Utilities

USD_API bool Export (const std::string &filename, bool addSourceFileComment=true, const SdfLayer::FileFormatArguments &args=SdfLayer::FileFormatArguments()) const
 
USD_API bool ExportToString (std::string *result, bool addSourceFileComment=true) const
 
USD_API SdfLayerRefPtr Flatten (bool addSourceFileComment=true) const
 
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
 
USD_API bool GetMetadata (const TfToken &key, VtValue *value) const
 
USD_API bool HasMetadata (const TfToken &key) const
 
USD_API bool HasAuthoredMetadata (const TfToken &key) const
 
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
 
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
 
USD_API bool ClearMetadata (const TfToken &key) const
 
template<typename T >
bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const
 
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
 
USD_API bool HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
 
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
 
USD_API void WriteFallbackPrimTypes ()
 
TimeCode API

Methods for managing the Stage's active timeSample range, time units, and intended rate of playback. See Usd_OM_UsdTimeCode for more on time and TimeCodes in USD.

USD_API double GetStartTimeCode () const
 
USD_API void SetStartTimeCode (double)
 
USD_API double GetEndTimeCode () const
 
USD_API void SetEndTimeCode (double)
 
USD_API bool HasAuthoredTimeCodeRange () const
 
USD_API double GetTimeCodesPerSecond () const
 
USD_API void SetTimeCodesPerSecond (double timeCodesPerSecond) const
 
USD_API double GetFramesPerSecond () const
 
USD_API void SetFramesPerSecond (double framesPerSecond) const
 
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)
 
USD_API UsdInterpolationType GetInterpolationType () const
 
Instancing

See Usd_Page_ScenegraphInstancing for more details.

USD_API std::vector< UsdPrimGetPrototypes () const
 Returns all native instancing prototype prims. More...
 
- Public Member Functions inherited from TfRefBase
 TfRefBase ()
 
 TfRefBase (TfRefBase const &)
 
TfRefBaseoperator= (TfRefBase const &)
 
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...
 
void SetShouldInvokeUniqueChangedListener (bool shouldCall)
 
- Public Member Functions inherited from TfWeakBase
 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)
 
- 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
 
class Usd_AssetPathContext
 
class Usd_FlattenAccess
 
class Usd_PcpCacheAccess
 
class Usd_PrimData
 
class Usd_StageOpenRequest
 
template<class T >
struct Usd_AttrGetValueHelper
 
struct Usd_AttrGetUntypedValueHelper
 
template<class RefsOrPayloadsEditorType , class RefsOrPayloadsProxyType >
struct Usd_ListEditImpl
 

Lifetime Management

enum  InitialLoadSet { LoadAll, LoadNone }
 
static USD_API UsdStageRefPtr CreateNew (const std::string &identifier, InitialLoadSet load=LoadAll)
 
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)
 
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)
 
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)
 
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)
 
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)
 
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)
 
virtual USD_API ~UsdStage ()
 
USD_API void Reload ()
 

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
 
USD_API UsdPrim GetDefaultPrim () const
 
USD_API void SetDefaultPrim (const UsdPrim &prim)
 
USD_API void ClearDefaultPrim ()
 
USD_API bool HasDefaultPrim () const
 
USD_API UsdPrim GetPrimAtPath (const SdfPath &path) const
 
USD_API UsdObject GetObjectAtPath (const SdfPath &path) const
 
USD_API UsdProperty GetPropertyAtPath (const SdfPath &path) const
 
USD_API UsdAttribute GetAttributeAtPath (const SdfPath &path) const
 
USD_API UsdRelationship GetRelationshipAtPath (const SdfPath &path) const
 
USD_API UsdPrimRange Traverse ()
 
USD_API UsdPrimRange Traverse (const Usd_PrimFlagsPredicate &predicate)
 
USD_API UsdPrimRange TraverseAll ()
 
USD_API UsdPrim OverridePrim (const SdfPath &path)
 
USD_API UsdPrim DefinePrim (const SdfPath &path, const TfToken &typeName=TfToken())
 
USD_API UsdPrim CreateClassPrim (const SdfPath &rootPrimPath)
 
USD_API bool RemovePrim (const SdfPath &path)
 

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());
}
See Also
UsdAttribute ColorSpace API
static USD_API void GetColorConfigFallbacks (SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem)
 
static USD_API void SetColorConfigFallbacks (const SdfAssetPath &colorConfiguration, const TfToken &colorManagementSystem)
 
USD_API void SetColorConfiguration (const SdfAssetPath &colorConfig) const
 
USD_API SdfAssetPath GetColorConfiguration () const
 
USD_API void SetColorManagementSystem (const TfToken &cms) const
 
USD_API TfToken GetColorManagementSystem () const
 

Additional Inherited Members

- Public Types inherited from TfRefBase
typedef void(* UniqueChangedFuncPtr )(TfRefBase const *, bool)
 
- Protected Member Functions inherited from TfRefBase
virtual TF_API ~TfRefBase ()
 
- Protected Member Functions inherited from TfWeakBase
 ~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 151 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 164 of file stage.h.

Constructor & Destructor Documentation

virtual USD_API UsdStage::~UsdStage ( )
virtual

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

Member Function Documentation

template<class T >
std::enable_if< !UsdStage::_HasTypeSpecificResolution<T>::value, bool>::type UsdStage::_GetMetadata ( const UsdObject obj,
const TfToken fieldName,
const TfToken keyPath,
bool  useFallbacks,
T result 
) const

Definition at line 2458 of file stage.h.

template<>
USD_API bool UsdStage::_GetTypeSpecificResolvedMetadata ( const UsdObject obj,
const TfToken fieldName,
const TfToken keyPath,
bool  useFallbacks,
SdfTimeSampleMap result 
) const
USD_API void UsdStage::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 UsdStage::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
Usd_OM_Metadata
USD_API bool UsdStage::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
Usd_Dictionary_Type
USD_API UsdPrim UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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().

USD_API void UsdStage::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.

USD_API bool UsdStage::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 UsdStage::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 UsdStage::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(),
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 UsdStage::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.

USD_API UsdAttribute UsdStage::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
static USD_API void UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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& UsdStage::GetEditTarget ( ) const

Return the stage's EditTarget.

USD_API UsdEditTarget UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::GetGlobalVariantFallbacks ( )
static

Get the global variant fallback preferences used in new UsdStages.

USD_API UsdInterpolationType UsdStage::GetInterpolationType ( ) const

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

USD_API SdfLayerHandleVector UsdStage::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& UsdStage::GetLoadRules ( ) const
inline

Return the stage's current UsdStageLoadRules governing payload inclusion.

See Working Set Management for more information.

Definition at line 653 of file stage.h.

USD_API SdfPathSet UsdStage::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.

template<typename T >
bool UsdStage::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
Usd_OM_Metadata

Definition at line 2393 of file stage.h.

USD_API bool UsdStage::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.

template<typename T >
bool UsdStage::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 2423 of file stage.h.

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

overload

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

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

USD_API UsdObject UsdStage::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
}
USD_API ArResolverContext UsdStage::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 UsdStage::GetPopulationMask ( ) const
inline

Return this stage's population mask.

Definition at line 670 of file stage.h.

USD_API UsdPrim UsdStage::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.

USD_API UsdProperty UsdStage::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
USD_API std::vector<UsdPrim> UsdStage::GetPrototypes ( ) const

Returns all native instancing prototype prims.

USD_API UsdPrim UsdStage::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 UsdRelationship UsdStage::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>();
See Also
GetObjectAtPath(const SdfPath&) const
USD_API SdfLayerHandle UsdStage::GetRootLayer ( ) const

Return this stage's root layer.

USD_API SdfLayerHandle UsdStage::GetSessionLayer ( ) const

Return this stage's root session layer.

USD_API double UsdStage::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 UsdStage::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
USD_API SdfLayerHandleVector UsdStage::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 UsdStage::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 UsdStage::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
Usd_Dictionary_Type
USD_API bool UsdStage::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 UsdStage::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 UsdStage::HasLocalLayer ( const SdfLayerHandle &  layer) const

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

USD_API bool UsdStage::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 UsdStage::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
Usd_Dictionary_Type
USD_API bool UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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.

static USD_API UsdStageRefPtr UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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 UsdStage::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.

template<typename T >
bool UsdStage::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
Usd_OM_Metadata

Definition at line 2415 of file stage.h.

USD_API bool UsdStage::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.

template<typename T >
bool UsdStage::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
Usd_Dictionary_Type

Definition at line 2447 of file stage.h.

USD_API bool UsdStage::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 UsdStage::SetPopulationMask ( UsdStagePopulationMask const &  mask)

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

USD_API void UsdStage::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 UsdStage::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 UsdStage::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()

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

USD_API UsdPrimRange UsdStage::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 UsdStage::TraverseAll ( )

Traverse all the prims on this stage depth-first.

See Also
Traverse()
UsdPrimRange::Stage()
USD_API void UsdStage::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 UsdStage::UnmuteLayer ( const std::string layerIdentifier)

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

USD_API void UsdStage::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
Usd_OM_FallbackPrimTypes UsdSchemaRegistry::GetFallbackPrimTypes

Friends And Related Function Documentation

friend class Usd_AssetPathContext
friend

Definition at line 2368 of file stage.h.

friend struct Usd_AttrGetUntypedValueHelper
friend

Definition at line 2374 of file stage.h.

template<class T >
friend struct Usd_AttrGetValueHelper
friend

Definition at line 2373 of file stage.h.

friend class Usd_FlattenAccess
friend

Definition at line 2369 of file stage.h.

template<class RefsOrPayloadsEditorType , class RefsOrPayloadsProxyType >
friend struct Usd_ListEditImpl
friend

Definition at line 2376 of file stage.h.

friend class Usd_PcpCacheAccess
friend

Definition at line 2370 of file stage.h.

friend class Usd_PrimData
friend

Definition at line 2371 of file stage.h.

friend class Usd_StageOpenRequest
friend

Definition at line 2372 of file stage.h.

friend class UsdAPISchemaBase
friend

Definition at line 2356 of file stage.h.

friend class UsdAttribute
friend

Definition at line 2357 of file stage.h.

friend class UsdAttributeQuery
friend

Definition at line 2358 of file stage.h.

friend class UsdEditTarget
friend

Definition at line 2359 of file stage.h.

friend class UsdInherits
friend

Definition at line 2360 of file stage.h.

friend class UsdObject
friend

Definition at line 2361 of file stage.h.

friend class UsdPrim
friend

Definition at line 2362 of file stage.h.

friend class UsdProperty
friend

Definition at line 2363 of file stage.h.

friend class UsdRelationship
friend

Definition at line 2364 of file stage.h.

friend class UsdSpecializes
friend

Definition at line 2365 of file stage.h.

friend class UsdVariantSet
friend

Definition at line 2366 of file stage.h.

friend class UsdVariantSets
friend

Definition at line 2367 of file stage.h.


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