|
The outermost container for scene description, which owns and presents composed prims as a scenegraph, following the composition recipe recursively described in its associated "root layer". More...
#include <stage.h>
Public Member Functions | |
template<> | |
USD_API bool | _GetTypeSpecificResolvedMetadata (const UsdObject &obj, const TfToken &fieldName, const TfToken &keyPath, bool useFallbacks, SdfTimeSampleMap *result) const |
Layer Serialization | |
Functions for saving changes to layers that contribute opinions to this stage. Layers may also be saved by calling SdfLayer::Save or exported to a new file by calling SdfLayer::Export. | |
USD_API void | Save () |
Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublayers of session layers. | |
USD_API void | SaveSessionLayers () |
Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this stage. | |
Working Set Management | |
The following rules apply to all Load/Unload methods: - Loading an already loaded prim is legal, though may result in some recomposition cost. Similarly, unloading an unloaded prim is legal. - Specifying a path that does not target a prim is legal as long it has an ancestor present in the scene graph (other than the absolute root). If the given path has no such ancestor, it is an error. - Specifying a path to an inactive prim is an error. - Specifying a path to a prototype prim or a prim within a prototype is an error. If an instance prim (or a path identifying a prim descendant to an instance) is encountered during a Load/Unload operation, these functions may cause instancing to change on the stage in order to ensure that no other instances are affected. The load/unload rules that affect a given prim hierarchy are considered when determining which prims can be instanced together. Instance sharing occurs when different instances have equivalent load rules. The GetLoadRules() and SetLoadRules() provide direct low-level access to the UsdStageLoadRules that govern payload inclusion on a stage. | |
USD_API UsdPrim | Load (const SdfPath &path=SdfPath::AbsoluteRootPath(), UsdLoadPolicy policy=UsdLoadWithDescendants) |
Modify this stage's load rules to load the prim at path , its ancestors, and all of its descendants if policy is UsdLoadWithDescendants. | |
USD_API void | Unload (const SdfPath &path=SdfPath::AbsoluteRootPath()) |
Modify this stage's load rules to unload the prim and its descendants specified by path . | |
USD_API void | LoadAndUnload (const SdfPathSet &loadSet, const SdfPathSet &unloadSet, UsdLoadPolicy policy=UsdLoadWithDescendants) |
Unload and load the given path sets. | |
USD_API SdfPathSet | GetLoadSet () |
Returns a set of all loaded paths. | |
USD_API SdfPathSet | FindLoadable (const SdfPath &rootPath=SdfPath::AbsoluteRootPath()) |
Returns an SdfPathSet of all paths that can be loaded. | |
UsdStageLoadRules const & | GetLoadRules () const |
Return the stage's current UsdStageLoadRules governing payload inclusion. | |
USD_API void | SetLoadRules (UsdStageLoadRules const &rules) |
Set the UsdStageLoadRules to govern payload inclusion on this stage. | |
UsdStagePopulationMask | GetPopulationMask () const |
Return this stage's population mask. | |
USD_API void | SetPopulationMask (UsdStagePopulationMask const &mask) |
Set this stage's population mask and recompose the stage. | |
USD_API void | ExpandPopulationMask (Usd_PrimFlagsPredicate const &traversalPredicate, std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr) |
Expand this stage's population mask to include the targets of all relationships that pass relPred and connections to all attributes that pass attrPred recursively. | |
USD_API void | ExpandPopulationMask (std::function< bool(UsdRelationship const &)> const &relPred=nullptr, std::function< bool(UsdAttribute const &)> const &attrPred=nullptr) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This convenience overload invokes ExpandPopulationMask() with the UsdPrimDefaultPredicate traversal predicate. | |
Layers and EditTargets | |
USD_API SdfLayerHandle | GetSessionLayer () const |
Return this stage's root session layer. | |
USD_API SdfLayerHandle | GetRootLayer () const |
Return this stage's root layer. | |
USD_API ArResolverContext | GetPathResolverContext () const |
Return the path resolver context for all path resolution during composition of this stage. | |
USD_API std::string | ResolveIdentifierToEditTarget (std::string const &identifier) const |
Resolve the given identifier using this stage's ArResolverContext and the layer of its GetEditTarget() as an anchor for relative references (e.g. | |
USD_API PcpErrorVector | GetCompositionErrors () const |
Return a PcpErrorVector containing all composition errors encountered when composing the prims and layer stacks on this stage. | |
USD_API SdfLayerHandleVector | GetLayerStack (bool includeSessionLayers=true) const |
includeSessionLayers is true, return the linearized strong-to-weak sublayers rooted at the stage's session layer followed by the linearized strong-to-weak sublayers rooted at this stage's root layer. | |
USD_API SdfLayerHandleVector | GetUsedLayers (bool includeClipLayers=true) const |
Return a vector of all of the layers currently consumed by this stage, as determined by the composition arcs that were traversed to compose and populate the stage. | |
USD_API bool | HasLocalLayer (const SdfLayerHandle &layer) const |
Return true if layer is one of the layers in this stage's local, root layerStack. | |
USD_API const UsdEditTarget & | GetEditTarget () const |
Return the stage's EditTarget. | |
USD_API UsdEditTarget | GetEditTargetForLocalLayer (size_t i) |
Return a UsdEditTarget for editing the layer at index i in the layer stack. | |
USD_API UsdEditTarget | GetEditTargetForLocalLayer (const SdfLayerHandle &layer) |
Return a UsdEditTarget for editing the given local layer. | |
USD_API void | SetEditTarget (const UsdEditTarget &editTarget) |
Set the stage's EditTarget. | |
USD_API void | MuteLayer (const std::string &layerIdentifier) |
Mute the layer identified by layerIdentifier . | |
USD_API void | UnmuteLayer (const std::string &layerIdentifier) |
Unmute the layer identified by layerIdentifier if it had previously been muted. | |
USD_API void | MuteAndUnmuteLayers (const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers) |
Mute and unmute the layers identified in muteLayers and unmuteLayers . | |
USD_API const std::vector< std::string > & | GetMutedLayers () const |
Returns a vector of all layers that have been muted on this stage. | |
USD_API bool | IsLayerMuted (const std::string &layerIdentifier) const |
Returns true if the layer specified by layerIdentifier is muted in this cache, false otherwise. | |
Flatten & Export Utilities | |
USD_API bool | Export (const std::string &filename, bool addSourceFileComment=true, const SdfLayer::FileFormatArguments &args=SdfLayer::FileFormatArguments()) const |
Writes out the composite scene as a single flattened layer into filename. | |
USD_API bool | ExportToString (std::string *result, bool addSourceFileComment=true) const |
Writes the composite scene as a flattened Usd text representation into the given string. | |
USD_API SdfLayerRefPtr | Flatten (bool addSourceFileComment=true) const |
Returns a single, anonymous, merged layer for this composite scene. | |
Stage Metadata | |
Stage metadata applies to the entire contents of the stage, and is recorded only in the stage's root or primary session-layer. Most of the other, specific metadata methods on UsdStage are defined in terms of these generic methods. | |
template<class T > | |
bool | GetMetadata (const TfToken &key, T *value) const |
Return in value an authored or fallback value (if one was defined for the given metadatum) for Stage metadatum key . | |
USD_API bool | GetMetadata (const TfToken &key, VtValue *value) const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
USD_API bool | HasMetadata (const TfToken &key) const |
Returns true if the key has a meaningful value, that is, if GetMetadata() will provide a value, either because it was authored or because the Stage metadata was defined with a meaningful fallback value. | |
USD_API bool | HasAuthoredMetadata (const TfToken &key) const |
Returns true if the key has an authored value, false if no value was authored or the only value available is the SdfSchema's metadata fallback. | |
template<typename T > | |
bool | SetMetadata (const TfToken &key, const T &value) const |
Set the value of Stage metadatum key to value , if the stage's current UsdEditTarget is the root or session layer. | |
USD_API bool | SetMetadata (const TfToken &key, const VtValue &value) const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
USD_API bool | ClearMetadata (const TfToken &key) const |
Clear the value of stage metadatum key , if the stage's current UsdEditTarget is the root or session layer. | |
template<typename T > | |
bool | GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const |
Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key , returning the resolved value. | |
USD_API bool | GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const |
overload | |
USD_API bool | HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const |
Return true if there exists any authored or fallback opinion for key and keyPath . | |
USD_API bool | HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const |
Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath . | |
template<typename T > | |
bool | SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const |
Author value to the field identified by key and keyPath at the current EditTarget. | |
USD_API bool | SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
USD_API bool | ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const |
Clear any authored value identified by key and keyPath at the current EditTarget. | |
USD_API void | WriteFallbackPrimTypes () |
Writes the fallback prim types defined in the schema registry to the stage as dictionary valued fallback prim type metadata. | |
TimeCode API | |
Methods for managing the Stage's active timeSample range, time units, and intended rate of playback. See Time and Timing in USD for more on time and TimeCodes in USD. | |
USD_API double | GetStartTimeCode () const |
Returns the stage's start timeCode. | |
USD_API void | SetStartTimeCode (double) |
Sets the stage's start timeCode. | |
USD_API double | GetEndTimeCode () const |
Returns the stage's end timeCode. | |
USD_API void | SetEndTimeCode (double) |
Sets the stage's end timeCode. | |
USD_API bool | HasAuthoredTimeCodeRange () const |
Returns true if the stage has both start and end timeCodes authored in the session layer or the root layer of the stage. | |
USD_API double | GetTimeCodesPerSecond () const |
Returns the stage's timeCodesPerSecond value. | |
USD_API void | SetTimeCodesPerSecond (double timeCodesPerSecond) const |
Sets the stage's timeCodesPerSecond value. | |
USD_API double | GetFramesPerSecond () const |
Returns the stage's framesPerSecond value. | |
USD_API void | SetFramesPerSecond (double framesPerSecond) const |
Sets the stage's framesPerSecond value. | |
Attribute Value Interpolation | |
Controls the interpolation behavior when retrieving attribute values. The default behavior is linear interpolation. See Attribute Value Interpolation for more details. | |
USD_API void | SetInterpolationType (UsdInterpolationType interpolationType) |
Sets the interpolation type used during value resolution for all attributes on this stage. | |
USD_API UsdInterpolationType | GetInterpolationType () const |
Returns the interpolation type used during value resolution for all attributes on this stage. | |
Instancing | |
See Scenegraph Instancing for more details. | |
USD_API std::vector< UsdPrim > | GetPrototypes () const |
Returns all native instancing prototype prims. | |
Public Member Functions inherited from TfRefBase | |
TfRefBase (TfRefBase const &) | |
TfRefBase & | operator= (TfRefBase const &) |
size_t | GetCurrentCount () const |
Return the current reference count of this object. | |
bool | IsUnique () const |
Return true if only one TfRefPtr points to this object. | |
void | SetShouldInvokeUniqueChangedListener (bool shouldCall) |
Public Member Functions inherited from TfWeakBase | |
TfWeakBase (const TfWeakBase &) | |
const TfWeakBase & | __GetTfWeakBase__ () const |
const TfWeakBase & | operator= (const TfWeakBase &) |
void | EnableNotification2 () const |
TF_API void const * | GetUniqueIdentifier () const |
Static Public Member Functions | |
Variant Management | |
These methods provide control over the policy to use when composing prims that specify a variant set but do not specify a selection. The first is to declare a list of preferences in plugInfo.json metadata on a plugin using this structure: "UsdVariantFallbacks": { # top level key
"shadingComplexity": [ # example variant set
"full", # example fallback #1
"light" # example fallback #2
]
},
This example ensures that we will get the "full" shadingComplexity for any prim with a shadingComplexity VariantSet that doesn't otherwise specify a selection, and has a "full" variant; if its shadingComplexity does not have a "full" variant, but does have a "light" variant, then the selection will be "light". In other words, the entries in the "shadingComplexity" list in the plugInfo.json represent a priority-ordered list of fallback selections. The plugin metadata is discovered and applied before the first UsdStage is constructed in a given process. It can be defined in any plugin. However, if multiple plugins express contrary lists for the same named variant set, the result is undefined. The plugin metadata approach is useful for ensuring that sensible default behavior applies across a pipeline without requiring every script and binary to explicitly configure every VariantSet that subscribes to fallback in the pipeline. There may be times when you want to override this behavior in a particular script – for example, a pipeline script that knows it wants to entirely ignore shading in order to minimize processing time – which motivates the second approach. SetGlobalVariantFallbacks() provides a way to override, for the entire process, which fallbacks to use in subsequently constructed UsdStage instances. | |
static USD_API PcpVariantFallbackMap | GetGlobalVariantFallbacks () |
Get the global variant fallback preferences used in new UsdStages. | |
static USD_API void | SetGlobalVariantFallbacks (const PcpVariantFallbackMap &fallbacks) |
Set the global variant fallback preferences used in new UsdStages. | |
Static Public Member Functions inherited from TfRefBase | |
static TF_API void | SetUniqueChangedListener (UniqueChangedListener listener) |
Friends | |
class | UsdAPISchemaBase |
class | UsdAttribute |
class | UsdAttributeQuery |
class | UsdEditTarget |
class | UsdInherits |
class | UsdNamespaceEditor |
class | UsdObject |
class | UsdPrim |
class | UsdProperty |
class | UsdRelationship |
class | UsdSpecializes |
class | UsdVariantSet |
class | UsdVariantSets |
Lifetime Management | |
enum | InitialLoadSet { LoadAll , LoadNone } |
Specifies the initial set of prims to load when opening a UsdStage. More... | |
static USD_API UsdStageRefPtr | CreateNew (const std::string &identifier, InitialLoadSet load=LoadAll) |
Create a new stage with root layer identifier , destroying potentially existing files with that identifier; it is considered an error if an existing, open layer is present with this identifier. | |
static USD_API UsdStageRefPtr | CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateNew (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateNew (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateInMemory (InitialLoadSet load=LoadAll) |
Creates a new stage only in memory, analogous to creating an anonymous SdfLayer. | |
static USD_API UsdStageRefPtr | CreateInMemory (const std::string &identifier, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateInMemory (const std::string &identifier, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | CreateInMemory (const std::string &identifier, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | Open (const std::string &filePath, InitialLoadSet load=LoadAll) |
Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the stack. | |
static USD_API UsdStageRefPtr | Open (const std::string &filePath, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | OpenMasked (const std::string &filePath, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll) |
Create a new stage and recursively compose prims defined within and referenced by the layer at filePath which must already exist, subject to mask . | |
static USD_API UsdStageRefPtr | OpenMasked (const std::string &filePath, const ArResolverContext &pathResolverContext, UsdStagePopulationMask const &mask, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | Open (const SdfLayerHandle &rootLayer, InitialLoadSet load=LoadAll) |
Open a stage rooted at rootLayer . | |
static USD_API UsdStageRefPtr | Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | Open (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | Open (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | OpenMasked (const SdfLayerHandle &rootLayer, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll) |
Open a stage rooted at rootLayer and with limited population subject to mask . | |
static USD_API UsdStageRefPtr | OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | OpenMasked (const SdfLayerHandle &rootLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API UsdStageRefPtr | OpenMasked (const SdfLayerHandle &rootLayer, const SdfLayerHandle &sessionLayer, const ArResolverContext &pathResolverContext, const UsdStagePopulationMask &mask, InitialLoadSet load=LoadAll) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
static USD_API bool | IsSupportedFile (const std::string &filePath) |
Indicates whether the specified file is supported by UsdStage. | |
virtual USD_API | ~UsdStage () |
USD_API void | Reload () |
Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers of session layers. | |
Color Configuration API | |
Methods for authoring and querying the color configuration to be used to interpret the per-attribute color-spaces. An external system (like OpenColorIO) is typically used for interpreting the configuration. Site-wide fallback values for the colorConfiguration and colorManagementSystem metadata can be set in the plugInfo.json file of a plugin using this structure: "UsdColorConfigFallbacks": {
"colorConfiguration" = "https://github.com/imageworks/OpenColorIO-Configs/blob/master/aces_1.0.1/config.ocio",
"colorManagementSystem" : "OpenColorIO"
}
The color space in which a given color or texture attribute is authored is set as token-valued metadata 'colorSpace' on the attribute. For color or texture attributes that don't have an authored 'colorSpace' value, the fallback color-space is gleaned from the color configuration oracle. This is usually the config's scene_linear role color-space. Here's the pseudo-code for determining an attribute's color-space. UsdStageRefPtr stage = UsdStage::Open(filePath);
TfToken colorSpace = attr.GetColorSpace();
if (colorSpace.IsEmpty()) {
// If colorSpace is empty, get the default from the stage's
// colorConfiguration, using external API (not provided by USD).
colorSpace = ExternalAPI::GetDefaultColorSpace(
stage->GetColorConfiguration());
}
Token for efficient comparison, assignment, and hashing of known strings. Definition: token.h:71 bool IsEmpty() const Returns true iff this token contains the empty string "". Definition: token.h:288 Scenegraph object for authoring and retrieving numeric, string, and array valued data,... Definition: attribute.h:160 USD_API TfToken GetColorSpace() const Gets the color space in which the attribute is authored. UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as ... Definition: prim.h:117 USD_API UsdAttribute GetAttribute(const TfToken &attrName) const Return a UsdAttribute with the name attrName. USD_API UsdPrim GetPrimAtPath(const SdfPath &path) const Returns the prim at path on the same stage as this prim. static USD_API UsdStageRefPtr Open(const std::string &filePath, InitialLoadSet load=LoadAll) Attempt to find a matching existing stage in a cache if UsdStageCacheContext objects exist on the sta...
| |
static USD_API void | GetColorConfigFallbacks (SdfAssetPath *colorConfiguration, TfToken *colorManagementSystem) |
Returns the global fallback values of 'colorConfiguration' and 'colorManagementSystem'. | |
static USD_API void | SetColorConfigFallbacks (const SdfAssetPath &colorConfiguration, const TfToken &colorManagementSystem) |
Sets the global fallback values of color configuration metadata which includes the 'colorConfiguration' asset path and the name of the color management system. | |
USD_API void | SetColorConfiguration (const SdfAssetPath &colorConfig) const |
Sets the default color configuration to be used to interpret the per-attribute color-spaces in the composed USD stage. | |
USD_API SdfAssetPath | GetColorConfiguration () const |
Returns the default color configuration used to interpret the per- attribute color-spaces in the composed USD stage. | |
USD_API void | SetColorManagementSystem (const TfToken &cms) const |
Sets the name of the color management system used to interpret the color configuration file pointed at by the colorConfiguration metadata. | |
USD_API TfToken | GetColorManagementSystem () const |
Sets the name of the color management system to be used for loading and interpreting the color configuration file. | |
Prim Access, Creation and Mutation | |
All of the methods in this group that accept a prim path as argument require paths in the namespace of the stage's root layer, regardless of what the currently active UsdEditTarget is set to. In other words, a UsdStage always presents a composed view of its scene, and all prim operations are specified in the composed namespace. | |
USD_API UsdPrim | GetPseudoRoot () const |
Return the stage's "pseudo-root" prim, whose name is defined by Usd. | |
USD_API UsdPrim | GetDefaultPrim () const |
Return the UsdPrim on this stage whose path is the root layer's defaultPrim metadata's value. | |
USD_API void | SetDefaultPrim (const UsdPrim &prim) |
Set the default prim layer metadata in this stage's root layer. | |
USD_API void | ClearDefaultPrim () |
Clear the default prim layer metadata in this stage's root layer. | |
USD_API bool | HasDefaultPrim () const |
Return true if this stage's root layer has an authored opinion for the default prim layer metadata. | |
USD_API UsdPrim | GetPrimAtPath (const SdfPath &path) const |
Return the UsdPrim at path , or an invalid UsdPrim if none exists. | |
USD_API UsdObject | GetObjectAtPath (const SdfPath &path) const |
Return the UsdObject at path , or an invalid UsdObject if none exists. | |
USD_API UsdProperty | GetPropertyAtPath (const SdfPath &path) const |
Return the UsdProperty at path , or an invalid UsdProperty if none exists. | |
USD_API UsdAttribute | GetAttributeAtPath (const SdfPath &path) const |
Return the UsdAttribute at path , or an invalid UsdAttribute if none exists. | |
USD_API UsdRelationship | GetRelationshipAtPath (const SdfPath &path) const |
Return the UsdAttribute at path , or an invalid UsdAttribute if none exists. | |
USD_API UsdPrimRange | Traverse () |
Traverse the active, loaded, defined, non-abstract prims on this stage depth-first. | |
USD_API UsdPrimRange | Traverse (const Usd_PrimFlagsPredicate &predicate) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Traverse the prims on this stage subject to predicate . | |
USD_API UsdPrimRange | TraverseAll () |
Traverse all the prims on this stage depth-first. | |
USD_API UsdPrim | OverridePrim (const SdfPath &path) |
Attempt to ensure a UsdPrim at path exists on this stage. | |
USD_API UsdPrim | DefinePrim (const SdfPath &path, const TfToken &typeName=TfToken()) |
Attempt to ensure a UsdPrim at path is defined (according to UsdPrim::IsDefined()) on this stage. | |
USD_API UsdPrim | CreateClassPrim (const SdfPath &rootPrimPath) |
Author an SdfPrimSpec with specifier == SdfSpecifierClass for the class at root prim path path at the current EditTarget. | |
USD_API bool | RemovePrim (const SdfPath &path) |
Remove all scene description for the given path and its subtree in the current UsdEditTarget. | |
Additional Inherited Members | |
Public Types inherited from TfRefBase | |
typedef void(* | UniqueChangedFuncPtr) (TfRefBase const *, bool) |
Protected Member Functions inherited from TfWeakBase | |
TfRefPtr< Tf_Remnant > | _Register () const |
template<class T > | |
TfRefPtr< Tf_Remnant > | _Register (T *tempRmnt) const |
bool | _HasRemnant () const |
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:
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.
enum InitialLoadSet |
USD_API void ClearDefaultPrim | ( | ) |
Clear the default prim layer metadata in this stage's root layer.
This is shorthand for:
Note that this function always authors to the stage's root layer. To author to a different layer, use the SdfLayer::SetDefaultPrim() API.
USD_API bool ClearMetadata | ( | const TfToken & | key | ) | const |
Clear the value of stage metadatum key
, if the stage's current UsdEditTarget is the root or session layer.
If the current EditTarget is any other layer, raise a coding error.
key
is not allowed as layer metadata.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.
key
is not allowed as layer metadata.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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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.
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.
Attempt to ensure a UsdPrim at path
is defined (according to UsdPrim::IsDefined()) on this stage.
If a prim at path
is already defined on this stage and typeName
is empty or equal to the existing prim's typeName, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and typeName
for the prim at path
at the current EditTarget. Author SdfPrimSpec s with specifier
== SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.
The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs (for example, in case path cannot map to the current UsdEditTarget's namespace or one of the ancestors of path
is inactive on the UsdStage), issue an error and return an invalid UsdPrim.
Note that this method may return a defined prim whose typeName does not match the supplied typeName
, in case a stronger typeName opinion overrides the opinion at the current EditTarget.
USD_API void ExpandPopulationMask | ( | std::function< bool(UsdRelationship const &)> const & | relPred = nullptr , |
std::function< bool(UsdAttribute const &)> const & | attrPred = nullptr |
||
) |
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 void ExpandPopulationMask | ( | Usd_PrimFlagsPredicate const & | traversalPredicate, |
std::function< bool(UsdRelationship const &)> const & | relPred = nullptr , |
||
std::function< bool(UsdAttribute const &)> const & | attrPred = nullptr |
||
) |
Expand this stage's population mask to include the targets of all relationships that pass relPred
and connections to all attributes that pass attrPred
recursively.
The attributes and relationships are those on all the prims found by traversing the stage according to traversalPredicate
. If relPred
is null, include all relationship targets; if attrPred
is null, include all connections.
This function can be used, for example, to expand a population mask for a given prim to include bound materials, if those bound materials are expressed as relationships or attribute connections.
See also UsdPrim::FindAllRelationshipTargetPaths() and UsdPrim::FindAllAttributeConnectionPaths().
USD_API bool Export | ( | const std::string & | filename, |
bool | addSourceFileComment = true , |
||
const SdfLayer::FileFormatArguments & | args = SdfLayer::FileFormatArguments() |
||
) | const |
Writes out the composite scene as a single flattened layer into filename.
If addSourceFileComment is true, a comment in the output layer will mention the input layer it was generated from.
See UsdStage::Flatten for details of the flattening transformation.
USD_API bool ExportToString | ( | std::string * | result, |
bool | addSourceFileComment = true |
||
) | const |
Writes the composite scene as a flattened Usd text representation into the given string.
If addSourceFileComment is true, a comment in the output layer will mention the input layer it was generated from.
See UsdStage::Flatten for details of the flattening transformation.
USD_API SdfPathSet FindLoadable | ( | const SdfPath & | rootPath = SdfPath::AbsoluteRootPath() | ) |
Returns an SdfPathSet of all paths that can be loaded.
Note that this method does not return paths to inactive prims as they cannot be loaded.
The set returned includes loaded and unloaded paths. To determine the set of unloaded paths, one can diff this set with the current load set, for example:
See Working Set Management for more information.
USD_API SdfLayerRefPtr Flatten | ( | bool | addSourceFileComment = true | ) | const |
Returns a single, anonymous, merged layer for this composite scene.
Specifically, this function removes most composition metadata and authors the resolved values for each object directly into the flattened layer.
All VariantSets are removed and only the currently selected variants will be present in the resulting layer.
Class prims will still exist, however all inherits arcs will have been removed and the inherited data will be copied onto each child object. Composition arcs authored on the class itself will be flattened into the class.
Flatten preserves scenegraph instancing by creating independent roots for each 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 GetAttributeAtPath | ( | const SdfPath & | path | ) | const |
Return the UsdAttribute at path
, or an invalid UsdAttribute if none exists.
This is equivalent to
|
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).
USD_API SdfAssetPath GetColorConfiguration | ( | ) | const |
Returns the default color configuration used to interpret the per- attribute color-spaces in the composed USD stage.
USD_API TfToken GetColorManagementSystem | ( | ) | const |
Sets the name of the color management system to be used for loading and interpreting the color configuration file.
USD_API PcpErrorVector GetCompositionErrors | ( | ) | const |
Return a PcpErrorVector containing all composition errors encountered when composing the prims and layer stacks on this stage.
USD_API UsdPrim GetDefaultPrim | ( | ) | const |
Return the UsdPrim on this stage whose path is the root layer's defaultPrim metadata's value.
Return an invalid prim if there is no such prim or if the root layer's defaultPrim metadata is unset or is not a valid prim path. Note that this function will return the prim on the stage whose path is the root layer's GetDefaultPrimAsPath() if that path is not empty and a prim at that path exists on the stage. See also SdfLayer::GetDefaultPrimAsPath().
USD_API const UsdEditTarget & GetEditTarget | ( | ) | const |
Return the stage's EditTarget.
USD_API UsdEditTarget GetEditTargetForLocalLayer | ( | const SdfLayerHandle & | layer | ) |
Return a UsdEditTarget for editing the given local layer.
If the given layer appears more than once in the layer stack, the time offset to the first occurrence will be used.
USD_API UsdEditTarget GetEditTargetForLocalLayer | ( | size_t | i | ) |
Return a UsdEditTarget for editing the layer at index i in the layer stack.
This edit target will incorporate any layer time offset that applies to the sublayer.
USD_API double GetEndTimeCode | ( | ) | const |
Returns the stage's end timeCode.
If the stage has an associated session layer with an end timeCode opinion, this value is returned. Otherwise, the end timeCode opinion from the root layer is returned.
USD_API double GetFramesPerSecond | ( | ) | const |
Returns the stage's framesPerSecond value.
This makes an advisory statement about how the contained data can be most usefully consumed and presented. It's primarily an indication of the expected playback rate for the data, but a timeline editing tool might also want to use this to decide how to scale and label its timeline.
The default value of framesPerSecond is 24.
|
static |
Get the global variant fallback preferences used in new UsdStages.
USD_API UsdInterpolationType GetInterpolationType | ( | ) | const |
Returns the interpolation type used during value resolution for all attributes on this stage.
USD_API SdfLayerHandleVector GetLayerStack | ( | bool | includeSessionLayers = true | ) | const |
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.
|
inline |
Return the stage's current UsdStageLoadRules governing payload inclusion.
See Working Set Management for more information.
USD_API SdfPathSet GetLoadSet | ( | ) |
Returns a set of all loaded paths.
The paths returned are both those that have been explicitly loaded and those that were loaded as a result of dependencies, ancestors or descendants of explicitly loaded paths.
This method does not return paths to inactive prims.
See Working Set Management for more information.
bool GetMetadata | ( | const TfToken & | key, |
T * | value | ||
) | const |
Return in value
an authored or fallback value (if one was defined for the given metadatum) for Stage metadatum key
.
Order of resolution is session layer, followed by root layer, else fallback to the SdfSchema.
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 typeThis is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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).
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 typeThe keyPath
is a ':'-separated path addressing an element in subdictionaries. If keyPath
is empty, returns an empty VtValue.
USD_API bool GetMetadataByDictKey | ( | const TfToken & | key, |
const TfToken & | keyPath, | ||
VtValue * | value | ||
) | const |
overload
USD_API const std::vector< std::string > & GetMutedLayers | ( | ) | const |
Returns a vector of all layers that have been muted on this stage.
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:
USD_API ArResolverContext GetPathResolverContext | ( | ) | const |
Return the path resolver context for all path resolution during composition of this stage.
Useful for external clients that want to resolve paths with the same context as this stage, or create new stages with the same context.
|
inline |
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 GetPropertyAtPath | ( | const SdfPath & | path | ) | const |
Return the UsdProperty at path
, or an invalid UsdProperty if none exists.
This is equivalent to
USD_API std::vector< UsdPrim > GetPrototypes | ( | ) | const |
Returns all native instancing prototype prims.
USD_API UsdPrim GetPseudoRoot | ( | ) | const |
Return the stage's "pseudo-root" prim, whose name is defined by Usd.
The stage's named root prims are namespace children of this prim, which exists to make the namespace hierarchy a tree instead of a forest. This simplifies algorithms that want to traverse all prims.
A UsdStage always has a pseudo-root prim, unless there was an error opening or creating the stage, in which case this method returns an invalid UsdPrim.
USD_API UsdRelationship GetRelationshipAtPath | ( | const SdfPath & | path | ) | const |
Return the UsdAttribute at path
, or an invalid UsdAttribute if none exists.
This is equivalent to
USD_API SdfLayerHandle GetRootLayer | ( | ) | const |
Return this stage's root layer.
USD_API SdfLayerHandle GetSessionLayer | ( | ) | const |
Return this stage's root session layer.
USD_API double GetStartTimeCode | ( | ) | const |
Returns the stage's start timeCode.
If the stage has an associated session layer with a start timeCode opinion, this value is returned. Otherwise, the start timeCode opinion from the root layer is returned.
USD_API double GetTimeCodesPerSecond | ( | ) | const |
Returns the stage's timeCodesPerSecond value.
The timeCodesPerSecond value scales the time ordinate for the samples contained in the stage to seconds. If timeCodesPerSecond is 24, then a sample at time ordinate 24 should be viewed exactly one second after the sample at time ordinate 0.
Like SdfLayer::GetTimeCodesPerSecond, this accessor uses a dynamic fallback to framesPerSecond. The order of precedence is:
USD_API SdfLayerHandleVector GetUsedLayers | ( | bool | includeClipLayers = true | ) | const |
Return a vector of all of the layers currently consumed by this stage, as determined by the composition arcs that were traversed to compose and populate the stage.
The list of consumed layers will change with the stage's load-set and variant selections, so the return value should be considered only a snapshot. The return value will include the stage's session layer, if it has one. If includeClipLayers is true, we will also include all of the layers that this stage has had to open so far to perform value resolution of attributes affected by Value Clips
USD_API bool HasAuthoredMetadata | ( | const TfToken & | key | ) | const |
Returns true
if the key has an authored value, false
if no value was authored or the only value available is the SdfSchema's metadata fallback.
false
. 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
.
USD_API bool HasAuthoredTimeCodeRange | ( | ) | const |
Returns true if the stage has both start and end timeCodes authored in the session layer or the root layer of the stage.
USD_API bool HasDefaultPrim | ( | ) | const |
Return true if this stage's root layer has an authored opinion for the default prim layer metadata.
This is shorthand for:
Note that this function only consults the stage's root layer. To consult a different layer, use the SdfLayer::HasDefaultPrim() API.
USD_API bool HasLocalLayer | ( | const SdfLayerHandle & | layer | ) | const |
Return true if layer is one of the layers in this stage's local, root layerStack.
USD_API bool HasMetadata | ( | const TfToken & | key | ) | const |
Returns true if the key has a meaningful value, that is, if GetMetadata() will provide a value, either because it was authored or because the Stage metadata was defined with a meaningful fallback value.
Returns false if key
is not allowed as layer metadata.
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.
USD_API bool IsLayerMuted | ( | const std::string & | layerIdentifier | ) | const |
Returns true if the layer specified by layerIdentifier
is muted in this cache, false otherwise.
See documentation on MuteLayer for details on how layerIdentifier
is compared to the layers that have been muted.
|
static |
Indicates whether the specified file is supported by UsdStage.
This function is a cheap way to determine whether a file might be open-able with UsdStage::Open. It is purely based on the given filePath
and does not open the file or perform analysis on the contents. As such, UsdStage::Open may still fail even if this function returns true.
USD_API UsdPrim Load | ( | const SdfPath & | path = SdfPath::AbsoluteRootPath() , |
UsdLoadPolicy | policy = UsdLoadWithDescendants |
||
) |
Modify this stage's load rules to load the prim at path
, its ancestors, and all of its descendants if policy
is UsdLoadWithDescendants.
If policy
is UsdLoadWithoutDescendants, then payloads on descendant prims are not loaded.
See Working Set Management for more information.
USD_API void LoadAndUnload | ( | const SdfPathSet & | loadSet, |
const SdfPathSet & | unloadSet, | ||
UsdLoadPolicy | policy = UsdLoadWithDescendants |
||
) |
Unload and load the given path sets.
The effect is as if the unload set were processed first followed by the load set.
This is equivalent to calling UsdStage::Unload for each item in the unloadSet followed by UsdStage::Load for each item in the loadSet, however this method is more efficient as all operations are committed in a single batch. The policy
argument is described in the documentation for Load().
See Working Set Management for more information.
USD_API void MuteAndUnmuteLayers | ( | const std::vector< std::string > & | muteLayers, |
const std::vector< std::string > & | unmuteLayers | ||
) |
Mute and unmute the layers identified in muteLayers
and unmuteLayers
.
This is equivalent to calling UsdStage::UnmuteLayer for each layer in unmuteLayers
followed by UsdStage::MuteLayer for each layer in muteLayers
, however this method is more efficient as all operations are committed in a single batch.
USD_API void MuteLayer | ( | const std::string & | layerIdentifier | ) |
Mute the layer identified by layerIdentifier
.
Muted layers are ignored by the stage; they do not participate in value resolution or composition and do not appear in any LayerStack. If the root layer of a reference or payload LayerStack is muted, the behavior is as if the muted layer did not exist, which means a composition error will be generated.
A canonical identifier for 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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
static |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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 |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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.
Attempt to ensure a UsdPrim at path
exists on this stage.
If a prim already exists at path
, return it. Otherwise author SdfPrimSpecs with specifier == SdfSpecifierOver and empty typeName at the current EditTarget to create this prim and any nonexistent ancestors, then return it.
The given path must be an absolute prim path that does not contain any variant selections.
If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget's namespace) issue an error and return an invalid UsdPrim.
If an ancestor of path
identifies an inactive prim, author scene description as described above but return an invalid prim, since the resulting prim is descendant to an inactive prim.
USD_API void Reload | ( | ) |
Calls SdfLayer::Reload on all layers contributing to this stage, except session layers and sublayers of session layers.
This includes non-session sublayers, references and payloads. Note that reloading anonymous layers clears their content, so invoking Reload() on a stage constructed via CreateInMemory() will clear its root layer.
USD_API bool RemovePrim | ( | const SdfPath & | path | ) |
Remove all scene description for the given path
and its subtree in the current UsdEditTarget.
This method does not do what you might initially think! Calling this function will not necessarily cause the UsdPrim at path
on this stage to disappear. Completely eradicating a prim from a composition can be an involved process, involving edits to many contributing layers, some of which (in many circumstances) will not be editable by a client. This method is a surgical instrument that can be used iteratively to effect complete removal of a prim and its subtree from namespace, assuming the proper permissions are acquired, but more commonly it is used to perform layer-level operations; e.g.: ensuring that a given layer (as expressed by a UsdEditTarget) provides no opinions for a prim and its subtree.
Generally, if your eye is attracted to this method, you probably want to instead use UsdPrim::SetActive(false) , which will provide the composed effect of removing the prim and its subtree from the composition, without actually removing any scene description, which as a bonus, means that the effect is reversible at a later time!
USD_API std::string ResolveIdentifierToEditTarget | ( | std::string const & | identifier | ) | const |
Resolve the given identifier using this stage's ArResolverContext and the layer of its GetEditTarget() as an anchor for relative references (e.g.
@./siblingFile.usd@).
USD_API void Save | ( | ) |
Calls SdfLayer::Save on all dirty layers contributing to this stage except session layers and sublayers of session layers.
This function will emit a warning and skip each dirty anonymous layer it encounters, since anonymous layers cannot be saved with SdfLayer::Save. These layers must be manually exported by calling SdfLayer::Export.
USD_API void SaveSessionLayers | ( | ) |
Calls SdfLayer::Save on all dirty session layers and sublayers of session layers contributing to this stage.
This function will emit a warning and skip each dirty anonymous layer it encounters, since anonymous layers cannot be saved with SdfLayer::Save. These layers must be manually exported by calling SdfLayer::Export.
|
static |
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.
USD_API void SetColorConfiguration | ( | const SdfAssetPath & | colorConfig | ) | const |
Sets the default color configuration to be used to interpret the per-attribute color-spaces in the composed USD stage.
This is specified as asset path which can be resolved to the color spec file.
USD_API void SetColorManagementSystem | ( | const TfToken & | cms | ) | const |
Sets the name of the color management system used to interpret the color configuration file pointed at by the colorConfiguration metadata.
USD_API void SetDefaultPrim | ( | const UsdPrim & | prim | ) |
Set the default prim layer metadata in this stage's root layer.
This is shorthand for:
If prim is a root prim, otherwise
Note that this function always authors to the stage's root layer. To author to a different layer, use the SdfLayer::SetDefaultPrim() API.
USD_API void SetEditTarget | ( | const UsdEditTarget & | editTarget | ) |
Set the stage's EditTarget.
If editTarget.IsLocalLayer(), check to see if it's a layer in this stage's local LayerStack. If not, issue an error and do nothing. If editTarget is invalid, issue an error and do nothing. If editTarget differs from the stage's current EditTarget, set the EditTarget and send UsdNotice::StageChangedEditTarget. Otherwise do nothing.
USD_API void SetEndTimeCode | ( | double | ) |
Sets the stage's end timeCode.
The end timeCode is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and the end timeCode is not set.
USD_API void SetFramesPerSecond | ( | double | framesPerSecond | ) | const |
Sets the stage's framesPerSecond value.
The framesPerSecond value is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and no value is set.
|
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.
USD_API void SetInterpolationType | ( | UsdInterpolationType | interpolationType | ) |
Sets the interpolation type used during value resolution for all attributes on this stage.
Changing this will cause a UsdNotice::StageContentsChanged notice to be sent, as values at times where no samples are authored may have changed.
USD_API void SetLoadRules | ( | UsdStageLoadRules const & | rules | ) |
Set the UsdStageLoadRules to govern payload inclusion on this stage.
This rebuilds the stage's entire prim hierarchy to follow rules
.
Note that subsequent calls to Load(), Unload(), LoadAndUnload() will modify this stages load rules as described in the documentation for those member functions.
See Working Set Management for more information.
bool SetMetadata | ( | const TfToken & | key, |
const T & | value | ||
) | const |
Set the value of Stage metadatum key
to value
, if the stage's current UsdEditTarget is the root or session layer.
If the current EditTarget is any other layer, raise a coding error.
key
is not allowed as layer metadata.This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
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.
key
is not allowed as layer metadata.USD_API bool SetMetadataByDictKey | ( | const TfToken & | key, |
const TfToken & | keyPath, | ||
const VtValue & | value | ||
) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
USD_API void SetPopulationMask | ( | UsdStagePopulationMask const & | mask | ) |
Set this stage's population mask and recompose the stage.
USD_API void SetStartTimeCode | ( | double | ) |
Sets the stage's start timeCode.
The start timeCode is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and the start timeCode is not set.
USD_API void SetTimeCodesPerSecond | ( | double | timeCodesPerSecond | ) | const |
Sets the stage's timeCodesPerSecond value.
The timeCodesPerSecond value is set in the current EditTarget, if it is the root layer of the stage or the session layer associated with the stage. If the current EditTarget is neither, a warning is issued and no value is set.
USD_API UsdPrimRange Traverse | ( | ) |
Traverse the active, loaded, defined, non-abstract prims on this stage depth-first.
Traverse() returns a UsdPrimRange , which allows low-latency traversal, with the ability to prune subtrees from traversal. It is python iterable, so in its simplest form, one can do:
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 Traverse | ( | const Usd_PrimFlagsPredicate & | predicate | ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Traverse the prims on this stage subject to predicate
.
This is equivalent to UsdPrimRange::Stage() .
USD_API UsdPrimRange TraverseAll | ( | ) |
Traverse all the prims on this stage depth-first.
USD_API void Unload | ( | const SdfPath & | path = SdfPath::AbsoluteRootPath() | ) |
Modify this stage's load rules to unload the prim and its descendants specified by path
.
See Working Set Management for more information.
USD_API void UnmuteLayer | ( | const std::string & | layerIdentifier | ) |
Unmute the layer identified by layerIdentifier
if it had previously been muted.
USD_API void WriteFallbackPrimTypes | ( | ) |
Writes the fallback prim types defined in the schema registry to the stage as dictionary valued fallback prim type metadata.
If the stage already has fallback prim type metadata, the fallback types from the schema registry will be added to the existing metadata, only for types that are already present in the dictionary, i.e. this won't overwrite existing fallback entries.
The current edit target determines whether the metadata is written to the root layer or the session layer. If the edit target specifies another layer besides these, this will produce an error.
This function can be used at any point before calling Save or Export on a stage to record the fallback types for the current schemas. This allows another version of Usd to open this stage and treat prim types it doesn't recognize as a type it does recognize defined for it in this metadata.
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |
|
friend |