#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 (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 UsdEditTarget &	GetEditTarget () 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< UsdPrim >	GetPrototypes () const
	Returns all native instancing prototype prims. More...

Public Member Functions inherited from TfRefBase
	TfRefBase ()

size_t	GetCurrentCount () const
	Return the current reference count of this object. More...

bool	IsUnique () const
	Return true if only one `TfRefPtr` points to this object. More...

const TfRefCount &	GetRefCount () const

void	SetShouldInvokeUniqueChangedListener (bool shouldCall)

Public Member Functions inherited from TfWeakBase
	TfWeakBase ()

	TfWeakBase (const TfWeakBase &)

const TfWeakBase &	__GetTfWeakBase__ () const

const TfWeakBase &	operator= (const TfWeakBase &)

void	EnableNotification2 () const

TF_API void const *	GetUniqueIdentifier () const

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

Member Enumeration Documentation

enum UsdStage::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 165 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 2435 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	(	std::function< bool(UsdRelationship const &)> const &	relPred = `nullptr`,
		std::function< bool(UsdAttribute const &)> const &	attrPred = `nullptr`
	)

Expand this stage's population mask to include the targets of all relationships that pass relPred and connections to all attributes that pass attrPred recursively. If relPred is null, include all relationship targets; if attrPred is null, include all connections.

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

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(),
           result;
std::set_difference(loaded.begin(), loaded.end(),
                    all.begin(), all.end(),
                    std::inserter(result, result.end()));

See Working Set Management for more information.

USD_API SdfLayerRefPtr 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 654 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 2370 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 2400 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 671 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 2392 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 2424 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.

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.