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

UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as described in the Universal Scene Description Composition Compendium More...

+ Inheritance diagram for UsdPrim:

Public Types

typedef UsdPrimSiblingIterator SiblingIterator
 Convenience typedefs. More...
 
typedef UsdPrimSiblingRange SiblingRange
 
typedef UsdPrimSubtreeIterator SubtreeIterator
 Convenience typedefs. More...
 
typedef UsdPrimSubtreeRange SubtreeRange
 
using PropertyPredicateFunc = std::function< bool(const TfToken &propertyName)>
 Alias for the "predicate" function parameter passed into the various Get{Authored}{PropertyNames,Properties} methods. More...
 

Public Member Functions

 UsdPrim ()
 Construct an invalid prim. More...
 
const UsdPrimTypeInfoGetPrimTypeInfo () const
 Return the prim's full type info composed from its type name, applied API schemas, and any fallback types defined on the stage for unrecognized prim type names. More...
 
const UsdPrimDefinitionGetPrimDefinition () const
 Return this prim's definition based on the prim's type if the type is a registered prim type. More...
 
SdfSpecifier GetSpecifier () const
 Return this prim's composed specifier. More...
 
USD_API SdfPrimSpecHandleVector GetPrimStack () const
 Return all the authored SdfPrimSpecs that may contain opinions for this prim in order from strong to weak. More...
 
bool SetSpecifier (SdfSpecifier specifier) const
 Author an opinion for this Prim's specifier at the current edit target. More...
 
const TfTokenGetTypeName () const
 Return this prim's composed type name. More...
 
bool SetTypeName (const TfToken &typeName) const
 Author this Prim's typeName at the current EditTarget. More...
 
bool ClearTypeName () const
 Clear the opinion for this Prim's typeName at the current edit target. More...
 
bool HasAuthoredTypeName () const
 Return true if a typeName has been authored. More...
 
bool IsActive () const
 Return true if this prim is active, meaning neither it nor any of its ancestors have active=false. More...
 
bool SetActive (bool active) const
 Author 'active' metadata for this prim at the current EditTarget. More...
 
bool ClearActive () const
 Remove the authored 'active' opinion at the current EditTarget. More...
 
bool HasAuthoredActive () const
 Return true if this prim has an authored opinion for 'active', false otherwise. More...
 
bool IsLoaded () const
 Return true if this prim is active, and either it is loadable and it is loaded, or its nearest loadable ancestor is loaded, or it has no loadable ancestor; false otherwise. More...
 
bool IsModel () const
 Return true if this prim is a model based on its kind metadata, false otherwise. More...
 
bool IsGroup () const
 Return true if this prim is a model group based on its kind metadata, false otherwise. More...
 
bool IsAbstract () const
 Return true if this prim or any of its ancestors is a class. More...
 
bool IsDefined () const
 Return true if this prim and all its ancestors have defining specifiers, false otherwise. More...
 
bool HasDefiningSpecifier () const
 Return true if this prim has a specifier of type SdfSpecifierDef or SdfSpecifierClass. More...
 
USD_API TfTokenVector GetAppliedSchemas () const
 Return a vector containing the names of API schemas which have been applied to this prim. More...
 
USD_API TfTokenVector GetPropertyNames (const PropertyPredicateFunc &predicate={}) const
 Return all of this prim's property names (attributes and relationships), including all builtin properties. More...
 
USD_API TfTokenVector GetAuthoredPropertyNames (const PropertyPredicateFunc &predicate={}) const
 Return this prim's property names (attributes and relationships) that have authored scene description, ordered according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan. More...
 
USD_API std::vector< UsdPropertyGetProperties (const PropertyPredicateFunc &predicate={}) const
 Return all of this prim's properties (attributes and relationships), including all builtin properties, ordered by name according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan. More...
 
USD_API std::vector< UsdPropertyGetAuthoredProperties (const PropertyPredicateFunc &predicate={}) const
 Return this prim's properties (attributes and relationships) that have authored scene description, ordered by name according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan. More...
 
USD_API std::vector< UsdPropertyGetPropertiesInNamespace (const std::vector< std::string > &namespaces) const
 Return this prim's properties that are inside the given property namespace ordered according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan. More...
 
USD_API std::vector< UsdPropertyGetPropertiesInNamespace (const std::string &namespaces) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. namespaces must be an already-concatenated ordered set of namespaces, and may or may not terminate with the namespace-separator character. More...
 
USD_API std::vector< UsdPropertyGetAuthoredPropertiesInNamespace (const std::vector< std::string > &namespaces) const
 Like GetPropertiesInNamespace(), but exclude properties that do not have authored scene description from the result. More...
 
USD_API std::vector< UsdPropertyGetAuthoredPropertiesInNamespace (const std::string &namespaces) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. namespaces must be an already-concatenated ordered set of namespaces, and may or may not terminate with the namespace-separator character. More...
 
USD_API TfTokenVector GetPropertyOrder () const
 Return the strongest propertyOrder metadata value authored on this prim. More...
 
void SetPropertyOrder (const TfTokenVector &order) const
 Author an opinion for propertyOrder metadata on this prim at the current EditTarget. More...
 
void ClearPropertyOrder () const
 Remove the opinion for propertyOrder metadata on this prim at the current EditTarget. More...
 
USD_API bool RemoveProperty (const TfToken &propName)
 Remove all scene description for the property with the given propName in the current UsdEditTarget. More...
 
USD_API UsdProperty GetProperty (const TfToken &propName) const
 Return a UsdProperty with the name propName. More...
 
USD_API bool HasProperty (const TfToken &propName) const
 Return true if this prim has an property named propName, false otherwise. More...
 
template<typename T >
bool IsA () const
 Return true if the prim's schema type, is or inherits schema type T. More...
 
USD_API bool IsA (const TfType &schemaType) const
 Return true if the prim's schema type is or inherits schemaType. More...
 
template<typename T >
bool HasAPI (const TfToken &instanceName=TfToken()) const
 Return true if the UsdPrim has had an API schema represented by the C++ class type T applied to it through the Apply() method provided on the API schema class. More...
 
USD_API bool HasAPI (const TfType &schemaType, const TfToken &instanceName=TfToken()) const
 Return true if a prim has an API schema with TfType schemaType. More...
 
template<typename SchemaType >
bool CanApplyAPI (std::string *whyNot=nullptr) const
 Returns whether a single-apply API schema with the given C++ type 'SchemaType' can be applied to this prim. More...
 
USD_API bool CanApplyAPI (const TfType &schemaType, std::string *whyNot=nullptr) const
 Non-templated overload of the templated CanApplyAPI above. More...
 
template<typename SchemaType >
bool CanApplyAPI (const TfToken &instanceName, std::string *whyNot=nullptr) const
 Returns whether a multiple-apply API schema with the given C++ type 'SchemaType' can be applied to this prim with the given instanceName. More...
 
USD_API bool CanApplyAPI (const TfType &schemaType, const TfToken &instanceName, std::string *whyNot=nullptr) const
 Non-templated overload of the templated CanApplyAPI above. More...
 
template<typename SchemaType >
bool ApplyAPI () const
 Applies a single-apply API schema with the given C++ type 'SchemaType' to this prim in the current edit target. More...
 
USD_API bool ApplyAPI (const TfType &schemaType) const
 Non-templated overload of the templated ApplyAPI above. More...
 
template<typename SchemaType >
bool ApplyAPI (const TfToken &instanceName) const
 Applies a multiple-apply API schema with the given C++ type 'SchemaType' and instance name instanceName to this prim in the current edit target. More...
 
USD_API bool ApplyAPI (const TfType &schemaType, const TfToken &instanceName) const
 Non-templated overload of the templated ApplyAPI above. More...
 
template<typename SchemaType >
bool RemoveAPI () const
 Removes a single-apply API schema with the given C++ type 'SchemaType' from this prim in the current edit target. More...
 
USD_API bool RemoveAPI (const TfType &schemaType) const
 Non-templated overload of the templated RemoveAPI above. More...
 
template<typename SchemaType >
bool RemoveAPI (const TfToken &instanceName) const
 Removes a multiple-apply API schema with the given C++ type 'SchemaType' and instance name instanceName from this prim in the current edit target. More...
 
USD_API bool RemoveAPI (const TfType &schemaType, const TfToken &instanceName) const
 Non-templated overload of the templated RemoveAPI above. More...
 
USD_API bool AddAppliedSchema (const TfToken &appliedSchemaName) const
 Adds the applied API schema name token appliedSchemaName to the apiSchemas metadata for this prim at the current edit target. More...
 
USD_API bool RemoveAppliedSchema (const TfToken &appliedSchemaName) const
 Removes the applied API schema name token appliedSchemaName from the apiSchemas metadata for this prim at the current edit target. More...
 
Prim Children
USD_API UsdPrim GetChild (const TfToken &name) const
 Return this prim's direct child named name if it has one, otherwise return an invalid UsdPrim. More...
 
SiblingRange GetChildren () const
 Return this prim's active, loaded, defined, non-abstract children as an iterable range. More...
 
SiblingRange GetAllChildren () const
 Return all this prim's children as an iterable range. More...
 
SiblingRange GetFilteredChildren (const Usd_PrimFlagsPredicate &predicate) const
 Return a subset of all of this prim's children filtered by predicate as an iterable range. More...
 
USD_API TfTokenVector GetChildrenNames () const
 Return the names of the child prims in the order they appear when iterating over GetChildren. More...
 
USD_API TfTokenVector GetAllChildrenNames () const
 Return the names of the child prims in the order they appear when iterating over GetAllChildren. More...
 
USD_API TfTokenVector GetFilteredChildrenNames (const Usd_PrimFlagsPredicate &predicate) const
 Return the names of the child prims in the order they appear when iterating over GetFilteredChildren(predicate). More...
 
SubtreeRange GetDescendants () const
 Return this prim's active, loaded, defined, non-abstract descendants as an iterable range. More...
 
SubtreeRange GetAllDescendants () const
 Return all this prim's descendants as an iterable range. More...
 
SubtreeRange GetFilteredDescendants (const Usd_PrimFlagsPredicate &predicate) const
 Return a subset of all of this prim's descendants filtered by predicate as an iterable range. More...
 
USD_API TfTokenVector GetChildrenReorder () const
 Return the strongest opinion for the metadata used to reorder children of this prim. More...
 
void SetChildrenReorder (const TfTokenVector &order) const
 Author an opinion for the metadata used to reorder children of this prim at the current EditTarget. More...
 
void ClearChildrenReorder () const
 Remove the opinion for the metadata used to reorder children of this prim at the current EditTarget. More...
 
Parent & Stage
UsdPrim GetParent () const
 Return this prim's parent prim. More...
 
USD_API UsdPrim GetNextSibling () const
 Return this prim's next active, loaded, defined, non-abstract sibling if it has one, otherwise return an invalid UsdPrim. More...
 
USD_API UsdPrim GetFilteredNextSibling (const Usd_PrimFlagsPredicate &predicate) const
 Return this prim's next sibling that matches predicate if it has one, otherwise return the invalid UsdPrim. More...
 
USD_API bool IsPseudoRoot () const
 Returns true if the prim is the pseudo root. More...
 
USD_API UsdPrim GetPrimAtPath (const SdfPath &path) const
 Returns the prim at path on the same stage as this prim. More...
 
USD_API UsdObject GetObjectAtPath (const SdfPath &path) const
 Returns the object at path on the same stage as this prim. More...
 
USD_API UsdProperty GetPropertyAtPath (const SdfPath &path) const
 Returns the property at path on the same stage as this prim. More...
 
USD_API UsdAttribute GetAttributeAtPath (const SdfPath &path) const
 Returns the attribute at path on the same stage as this prim. More...
 
USD_API UsdRelationship GetRelationshipAtPath (const SdfPath &path) const
 Returns the relationship at path on the same stage as this prim. More...
 
Variants
USD_API UsdVariantSets GetVariantSets () const
 Return a UsdVariantSets object representing all the VariantSets present on this prim. More...
 
USD_API UsdVariantSet GetVariantSet (const std::string &variantSetName) const
 Retrieve a specifically named VariantSet for editing or constructing a UsdEditTarget. More...
 
USD_API bool HasVariantSets () const
 Return true if this prim has any authored VariantSets. More...
 
Attributes
USD_API UsdAttribute CreateAttribute (const TfToken &name, const SdfValueTypeName &typeName, bool custom, SdfVariability variability=SdfVariabilityVarying) const
 Author scene description for the attribute named attrName at the current EditTarget if none already exists. More...
 
USD_API UsdAttribute CreateAttribute (const TfToken &name, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Create a custom attribute with name, typeName and variability. More...
 
USD_API UsdAttribute CreateAttribute (const std::vector< std::string > &nameElts, const SdfValueTypeName &typeName, bool custom, SdfVariability variability=SdfVariabilityVarying) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload of CreateAttribute() accepts a vector of name components used to construct a namespaced property name. More...
 
USD_API UsdAttribute CreateAttribute (const std::vector< std::string > &nameElts, const SdfValueTypeName &typeName, SdfVariability variability=SdfVariabilityVarying) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Create a custom attribute with nameElts, typeName, and variability. More...
 
USD_API std::vector< UsdAttributeGetAttributes () const
 Like GetProperties(), but exclude all relationships from the result. More...
 
USD_API std::vector< UsdAttributeGetAuthoredAttributes () const
 Like GetAttributes(), but exclude attributes without authored scene description from the result. More...
 
USD_API UsdAttribute GetAttribute (const TfToken &attrName) const
 Return a UsdAttribute with the name attrName. More...
 
USD_API bool HasAttribute (const TfToken &attrName) const
 Return true if this prim has an attribute named attrName, false otherwise. More...
 
USD_API SdfPathVector FindAllAttributeConnectionPaths (std::function< bool(UsdAttribute const &)> const &pred=nullptr, bool recurseOnSources=false) const
 Search the prim subtree rooted at this prim for attributes for which predicate returns true, collect their connection source paths and return them in an arbitrary order. More...
 
Relationships
USD_API UsdRelationship CreateRelationship (const TfToken &relName, bool custom=true) const
 Author scene description for the relationship named relName at the current EditTarget if none already exists. More...
 
USD_API UsdRelationship CreateRelationship (const std::vector< std::string > &nameElts, bool custom=true) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload of CreateRelationship() accepts a vector of name components used to construct a namespaced property name. More...
 
USD_API std::vector
< UsdRelationship
GetRelationships () const
 Like GetProperties(), but exclude all attributes from the result. More...
 
USD_API std::vector
< UsdRelationship
GetAuthoredRelationships () const
 Like GetRelationships(), but exclude relationships without authored scene description from the result. More...
 
USD_API UsdRelationship GetRelationship (const TfToken &relName) const
 Return a UsdRelationship with the name relName. More...
 
USD_API bool HasRelationship (const TfToken &relName) const
 Return true if this prim has a relationship named relName, false otherwise. More...
 
USD_API SdfPathVector FindAllRelationshipTargetPaths (std::function< bool(UsdRelationship const &)> const &pred=nullptr, bool recurseOnTargets=false) const
 Search the prim subtree rooted at this prim for relationships for which predicate returns true, collect their target paths and return them in an arbitrary order. More...
 
Payload Authoring
Deprecated:
This API is now deprecated. Please use the HasAuthoredPayloads and the UsdPayloads API returned from GetPayloads() to query and author payloads instead.
USD_API bool ClearPayload () const
 
USD_API bool HasPayload () const
 
USD_API bool SetPayload (const SdfPayload &payload) const
 
USD_API bool SetPayload (const std::string &assetPath, const SdfPath &primPath) const
 
USD_API bool SetPayload (const SdfLayerHandle &layer, const SdfPath &primPath) const
 
Payloads, Load and Unload
USD_API UsdPayloads GetPayloads () const
 Return a UsdPayloads object that allows one to add, remove, or mutate payloads at the currently set UsdEditTarget. More...
 
USD_API bool HasAuthoredPayloads () const
 Return true if this prim has any authored payloads. More...
 
USD_API void Load (UsdLoadPolicy policy=UsdLoadWithDescendants) const
 Load this prim, all its ancestors, and by default all its descendants. More...
 
USD_API void Unload () const
 Unloads this prim and all its descendants. More...
 
References
USD_API UsdReferences GetReferences () const
 Return a UsdReferences object that allows one to add, remove, or mutate references at the currently set UsdEditTarget. More...
 
USD_API bool HasAuthoredReferences () const
 Return true if this prim has any authored references. More...
 
Inherits
USD_API UsdInherits GetInherits () const
 Return a UsdInherits object that allows one to add, remove, or mutate inherits at the currently set UsdEditTarget. More...
 
USD_API bool HasAuthoredInherits () const
 Return true if this prim has any authored inherits. More...
 
Specializes
USD_API UsdSpecializes GetSpecializes () const
 Return a UsdSpecializes object that allows one to add, remove, or mutate specializes at the currently set UsdEditTarget. More...
 
USD_API bool HasAuthoredSpecializes () const
 Returns true if this prim has any authored specializes. More...
 
Composition Structure
const PcpPrimIndexGetPrimIndex () const
 Return the cached prim index containing all sites that can contribute opinions to this prim. More...
 
USD_API PcpPrimIndex ComputeExpandedPrimIndex () const
 Compute the prim index containing all sites that could contribute opinions to this prim. More...
 
- Public Member Functions inherited from UsdObject
 UsdObject ()
 Default constructor produces an invalid object. More...
 
template<typename T >
bool GetMetadata (const TfToken &key, T *value) const
 Resolve the requested metadatum named key into value, returning true on success. More...
 
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.Type-erased access. More...
 
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
 Set metadatum key's value to value. More...
 
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
 
USD_API bool ClearMetadata (const TfToken &key) const
 Clears the authored key's value at the current EditTarget, returning false on error. More...
 
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 a prim's metadata fallback will be provided. More...
 
USD_API bool HasAuthoredMetadata (const TfToken &key) const
 Returns true if the key has an authored value, false if no value was authored or the only value available is a prim's metadata fallback. More...
 
template<class 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 into value, returning true on success. More...
 
USD_API bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
 
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
 Author value to the field identified by key and keyPath at the current EditTarget. More...
 
USD_API bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const
 
USD_API bool ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
 Clear any authored value identified by key and keyPath at the current EditTarget. More...
 
USD_API bool HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 Return true if there exists any authored or fallback opinion for key and keyPath. More...
 
USD_API bool HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath. More...
 
USD_API UsdMetadataValueMap GetAllMetadata () const
 Resolve and return all metadata (including both authored and fallback values) on this object, sorted lexicographically. More...
 
USD_API UsdMetadataValueMap GetAllAuthoredMetadata () const
 Resolve and return all user-authored metadata on this object, sorted lexicographically. More...
 
USD_API bool IsHidden () const
 Gets the value of the 'hidden' metadata field, false if not authored. More...
 
USD_API bool SetHidden (bool hidden) const
 Sets the value of the 'hidden' metadata field. More...
 
USD_API bool ClearHidden () const
 Clears the opinion for "Hidden" at the current EditTarget. More...
 
USD_API bool HasAuthoredHidden () const
 Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for Hidden. More...
 
USD_API VtDictionary GetCustomData () const
 Return this object's composed customData dictionary. More...
 
USD_API VtValue GetCustomDataByKey (const TfToken &keyPath) const
 Return the element identified by keyPath in this object's composed customData dictionary. More...
 
USD_API void SetCustomData (const VtDictionary &customData) const
 Author this object's customData dictionary to customData at the current EditTarget. More...
 
USD_API void SetCustomDataByKey (const TfToken &keyPath, const VtValue &value) const
 Author the element identified by keyPath in this object's customData dictionary at the current EditTarget. More...
 
USD_API void ClearCustomData () const
 Clear the authored opinion for this object's customData dictionary at the current EditTarget. More...
 
USD_API void ClearCustomDataByKey (const TfToken &keyPath) const
 Clear the authored opinion identified by keyPath in this object's customData dictionary at the current EditTarget. More...
 
USD_API bool HasCustomData () const
 Return true if there are any authored or fallback opinions for this object's customData dictionary, false otherwise. More...
 
USD_API bool HasCustomDataKey (const TfToken &keyPath) const
 Return true if there are any authored or fallback opinions for the element identified by keyPath in this object's customData dictionary, false otherwise. More...
 
USD_API bool HasAuthoredCustomData () const
 Return true if there are any authored opinions (excluding fallback) for this object's customData dictionary, false otherwise. More...
 
USD_API bool HasAuthoredCustomDataKey (const TfToken &keyPath) const
 Return true if there are any authored opinions (excluding fallback) for the element identified by keyPath in this object's customData dictionary, false otherwise. More...
 
USD_API VtDictionary GetAssetInfo () const
 Return this object's composed assetInfo dictionary. More...
 
USD_API VtValue GetAssetInfoByKey (const TfToken &keyPath) const
 Return the element identified by keyPath in this object's composed assetInfo dictionary. More...
 
USD_API void SetAssetInfo (const VtDictionary &customData) const
 Author this object's assetInfo dictionary to assetInfo at the current EditTarget. More...
 
USD_API void SetAssetInfoByKey (const TfToken &keyPath, const VtValue &value) const
 Author the element identified by keyPath in this object's assetInfo dictionary at the current EditTarget. More...
 
USD_API void ClearAssetInfo () const
 Clear the authored opinion for this object's assetInfo dictionary at the current EditTarget. More...
 
USD_API void ClearAssetInfoByKey (const TfToken &keyPath) const
 Clear the authored opinion identified by keyPath in this object's assetInfo dictionary at the current EditTarget. More...
 
USD_API bool HasAssetInfo () const
 Return true if there are any authored or fallback opinions for this object's assetInfo dictionary, false otherwise. More...
 
USD_API bool HasAssetInfoKey (const TfToken &keyPath) const
 Return true if there are any authored or fallback opinions for the element identified by keyPath in this object's assetInfo dictionary, false otherwise. More...
 
USD_API bool HasAuthoredAssetInfo () const
 Return true if there are any authored opinions (excluding fallback) for this object's assetInfo dictionary, false otherwise. More...
 
USD_API bool HasAuthoredAssetInfoKey (const TfToken &keyPath) const
 Return true if there are any authored opinions (excluding fallback) for the element identified by keyPath in this object's assetInfo dictionary, false otherwise. More...
 
USD_API std::string GetDocumentation () const
 Return this object's documentation (metadata). More...
 
USD_API bool SetDocumentation (const std::string &doc) const
 Sets this object's documentation (metadata). Returns true on success. More...
 
USD_API bool ClearDocumentation () const
 Clears this object's documentation (metadata) in the current EditTarget (only). More...
 
USD_API bool HasAuthoredDocumentation () const
 Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful value for documentation. More...
 
bool IsValid () const
 Return true if this is a valid object, false otherwise. More...
 
 operator bool () const
 Returns true if this object is valid, false otherwise. More...
 
USD_API UsdStageWeakPtr GetStage () const
 Return the stage that owns the object, and to whose state and lifetime this object's validity is tied. More...
 
SdfPath GetPath () const
 Return the complete scene path to this object on its UsdStage, which may (UsdPrim) or may not (all other subclasses) return a cached result. More...
 
const SdfPathGetPrimPath () const
 Return this object's path if this object is a prim, otherwise this object's nearest owning prim's path. More...
 
UsdPrim GetPrim () const
 Return this object if it is a prim, otherwise return this object's nearest owning prim. More...
 
const TfTokenGetName () const
 Return the full name of this object, i.e. More...
 
template<class T >
As () const
 Convert this UsdObject to another object type T if possible. More...
 
template<class T >
bool Is () const
 Return true if this object is convertible to T. More...
 
USD_API std::string GetDescription () const
 Return a string that provides a brief summary description of the object. More...
 

Friends

class UsdObject
 
class UsdPrimSiblingIterator
 
class UsdPrimSubtreeIterator
 
class UsdProperty
 
class UsdSchemaBase
 
class UsdAPISchemaBase
 
class UsdStage
 
class UsdPrimRange
 
struct UsdPrim_RelTargetFinder
 
struct UsdPrim_AttrConnectionFinder
 

Instancing

See Scenegraph Instancing for more details.

bool IsInstanceable () const
 Return true if this prim has been marked as instanceable. More...
 
bool SetInstanceable (bool instanceable) const
 Author 'instanceable' metadata for this prim at the current EditTarget. More...
 
bool ClearInstanceable () const
 Remove the authored 'instanceable' opinion at the current EditTarget. More...
 
bool HasAuthoredInstanceable () const
 Return true if this prim has an authored opinion for 'instanceable', false otherwise. More...
 
bool IsInstance () const
 Return true if this prim is an instance of a prototype, false otherwise. More...
 
bool IsInstanceProxy () const
 Return true if this prim is an instance proxy, false otherwise. More...
 
bool IsPrototype () const
 Return true if this prim is an instancing prototype prim, false otherwise. More...
 
bool IsInPrototype () const
 Return true if this prim is a prototype prim or a descendant of a prototype prim, false otherwise. More...
 
USD_API UsdPrim GetPrototype () const
 If this prim is an instance, return the UsdPrim for the corresponding prototype. More...
 
UsdPrim GetPrimInPrototype () const
 If this prim is an instance proxy, return the UsdPrim for the corresponding prim in the instance's prototype. More...
 
USD_API std::vector< UsdPrimGetInstances () const
 If this prim is a prototype prim, returns all prims that are instances of this prototype. More...
 
static USD_API bool IsPrototypePath (const SdfPath &path)
 Return true if the given path identifies a prototype prim, false otherwise. More...
 
static USD_API bool IsPathInPrototype (const SdfPath &path)
 Return true if the given path identifies a prototype prim or a prim or property descendant of a prototype prim, false otherwise. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from UsdObject
static char GetNamespaceDelimiter ()
 
- Protected Member Functions inherited from UsdObject
template<class Derived >
 UsdObject (_Null< Derived >)
 
 UsdObject (const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath)
 
 UsdObject (UsdObjType objType, const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath, const TfToken &propName)
 
UsdStage_GetStage () const
 
USD_API SdfSpecType _GetDefiningSpecType () const
 
const Usd_PrimDataHandle & _Prim () const
 
const TfToken_PropName () const
 
const SdfPath_ProxyPrimPath () const
 

Detailed Description

UsdPrim is the sole persistent scenegraph object on a UsdStage, and is the embodiment of a "Prim" as described in the Universal Scene Description Composition Compendium

A UsdPrim is the principal container of other types of scene description. It provides API for accessing and creating all of the contained kinds of scene description, which include:

As well as access to the API objects for properties contained within the prim - UsdPrim as well as all of the following classes are subclasses of UsdObject:

UsdPrim also provides access to iteration through its prim children, optionally making use of the prim predicates facility (GetChildren(), GetAllChildren(), GetFilteredChildren()).

Management

Clients acquire UsdPrim objects, which act like weak/guarded pointers to persistent objects owned and managed by their originating UsdStage. We provide the following guarantees for a UsdPrim acquired via UsdStage::GetPrimAtPath() or UsdStage::OverridePrim() or UsdStage::DefinePrim():

  • As long as no further mutations to the structure of the UsdStage are made, the UsdPrim will still be valid. Loading and Unloading are considered structural mutations.
  • When the UsdStage's structure is mutated, the thread performing the mutation will receive a UsdNotice::ObjectsChanged notice after the stage has been reconfigured, which provides details as to what prims may have been created or destroyed, and what prims may simply have changed in some structural way.

Prim access in "reader" threads should be limited to GetPrimAtPath(), which will never cause a mutation to the Stage or its layers.

Please refer to UsdNotice for a listing of the events that could cause UsdNotice::ObjectsChanged to be emitted.

Definition at line 132 of file prim.h.

Member Typedef Documentation

using PropertyPredicateFunc = std::function<bool (const TfToken &propertyName)>

Alias for the "predicate" function parameter passed into the various Get{Authored}{PropertyNames,Properties} methods.

Definition at line 285 of file prim.h.

Convenience typedefs.

Definition at line 136 of file prim.h.

Convenience typedefs.

Definition at line 140 of file prim.h.

Constructor & Destructor Documentation

UsdPrim ( )
inline

Construct an invalid prim.

Definition at line 144 of file prim.h.

Member Function Documentation

USD_API bool AddAppliedSchema ( const TfToken appliedSchemaName) const

Adds the applied API schema name token appliedSchemaName to the apiSchemas metadata for this prim at the current edit target.

For multiple-apply schemas the name token should include the instance name for the applied schema, for example 'CollectionAPI:plasticStuff'.

The name will only be added if the list operation at the edit target does not already have this applied schema in its explicit, prepended, or appended lists and is always added to the end of either the prepended or explicit items.

Returns true upon success or if the API schema is already applied in the current edit target.

An error is issued and false returned for any of the following conditions:

  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be added to the apiSchemas listOp metadata

Unlike ApplyAPI this method does not require that the name token refer to a valid API schema type. ApplyAPI is the preferred method for applying valid API schemas.

bool ApplyAPI ( ) const
inline

Applies a single-apply API schema with the given C++ type 'SchemaType' to this prim in the current edit target.

This information is stored by adding the API schema's name token to the token-valued, listOp metadata apiSchemas on this prim.

Returns true upon success or if the API schema is already applied in the current edit target.

An error is issued and false returned for any of the following conditions:

  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be added to the apiSchemas listOp metadata

Definition at line 700 of file prim.h.

USD_API bool ApplyAPI ( const TfType schemaType) const

Non-templated overload of the templated ApplyAPI above.

This function behaves exactly like the templated ApplyAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated ApplyAPI is preferred.

bool ApplyAPI ( const TfToken instanceName) const
inline

Applies a multiple-apply API schema with the given C++ type 'SchemaType' and instance name instanceName to this prim in the current edit target.

This information is stored in the token-valued, listOp metadata apiSchemas on this prim. For example, if SchemaType is 'UsdCollectionAPI' and instanceName is 'plasticStuff', the name 'CollectionAPI:plasticStuff' is added to the 'apiSchemas' listOp metadata.

Returns true upon success or if the API schema is already applied with this instanceName in the current edit target.

An error is issued and false returned for any of the following conditions:

  • instanceName is empty
  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be added to the apiSchemas listOp metadata

Definition at line 742 of file prim.h.

USD_API bool ApplyAPI ( const TfType schemaType,
const TfToken instanceName 
) const

Non-templated overload of the templated ApplyAPI above.

This function behaves exactly like the templated ApplyAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated ApplyAPI is preferred.

bool CanApplyAPI ( std::string *  whyNot = nullptr) const
inline

Returns whether a single-apply API schema with the given C++ type 'SchemaType' can be applied to this prim.

If the return value is false, and whyNot is provided, the reason the schema cannot be applied is written to whyNot.

Whether the schema can be applied is determined by the schema type definition which may specify that the API schema can only be applied to certain prim types.

The return value of this function only indicates whether it would be valid to apply this schema to the prim. It has no bearing on whether calling ApplyAPI will be successful or not.

Definition at line 624 of file prim.h.

USD_API bool CanApplyAPI ( const TfType schemaType,
std::string *  whyNot = nullptr 
) const

Non-templated overload of the templated CanApplyAPI above.

This function behaves exactly like the templated CanApplyAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated CanApplyAPI is preferred.

bool CanApplyAPI ( const TfToken instanceName,
std::string *  whyNot = nullptr 
) const
inline

Returns whether a multiple-apply API schema with the given C++ type 'SchemaType' can be applied to this prim with the given instanceName.

If the return value is false, and whyNot is provided, the reason the schema cannot be applied is written to whyNot.

Whether the schema can be applied is determined by the schema type definition which may specify that the API schema can only be applied to certain prim types. It also determines whether the instance name is a valid instance name for the multiple apply schema.

The return value of this function only indicates whether it would be valid to apply this schema to the prim. It has no bearing on whether calling ApplyAPI will be successful or not.

Definition at line 660 of file prim.h.

USD_API bool CanApplyAPI ( const TfType schemaType,
const TfToken instanceName,
std::string *  whyNot = nullptr 
) const

Non-templated overload of the templated CanApplyAPI above.

This function behaves exactly like the templated CanApplyAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated CanApplyAPI is preferred.

bool ClearActive ( ) const
inline

Remove the authored 'active' opinion at the current EditTarget.

Do nothing if there is no authored opinion.

See How "active" Affects Prims on a UsdStage for the effects of activating or deactivating a prim.

Definition at line 234 of file prim.h.

void ClearChildrenReorder ( ) const
inline

Remove the opinion for the metadata used to reorder children of this prim at the current EditTarget.

Definition at line 1027 of file prim.h.

bool ClearInstanceable ( ) const
inline

Remove the authored 'instanceable' opinion at the current EditTarget.

Do nothing if there is no authored opinion.

Definition at line 1514 of file prim.h.

USD_API bool ClearPayload ( ) const
Deprecated:
Clears the payload at the current EditTarget for this prim. Return false if the payload could not be cleared.
void ClearPropertyOrder ( ) const
inline

Remove the opinion for propertyOrder metadata on this prim at the current EditTarget.

Definition at line 437 of file prim.h.

bool ClearTypeName ( ) const
inline

Clear the opinion for this Prim's typeName at the current edit target.

Definition at line 206 of file prim.h.

USD_API PcpPrimIndex ComputeExpandedPrimIndex ( ) const

Compute the prim index containing all sites that could contribute opinions to this prim.

This function is similar to UsdPrim::GetPrimIndex. However, the returned prim index includes all sites that could possibly contribute opinions to this prim, not just the sites that currently do so. This is useful in certain situations; for example, this could be used to generate a list of sites where clients could make edits to affect this prim, or for debugging purposes.

This function may be relatively slow, since it will recompute the prim index on every call. Clients should prefer UsdPrim::GetPrimIndex unless the additional site information is truly needed.

USD_API UsdAttribute CreateAttribute ( const TfToken name,
const SdfValueTypeName typeName,
bool  custom,
SdfVariability  variability = SdfVariabilityVarying 
) const

Author scene description for the attribute named attrName at the current EditTarget if none already exists.

Return a valid attribute if scene description was successfully authored or if it already existed, return invalid attribute otherwise. Note that the supplied typeName and custom arguments are only used in one specific case. See below for details.

Suggested use:

* if (UsdAttribute myAttr = prim.CreateAttribute(...)) {
* // success.
* }
*

To call this, GetPrim() must return a valid prim.

  • If a spec for this attribute already exists at the current edit target, do nothing.
  • If a spec for attrName of a different spec type (e.g. a relationship) exists at the current EditTarget, issue an error.
  • If name refers to a builtin attribute according to the prim's definition, author an attribute spec with required metadata from the definition.
  • If name refers to a builtin relationship, issue an error.
  • If there exists an absolute strongest authored attribute spec for attrName, author an attribute spec at the current EditTarget by copying required metadata from that strongest spec.
  • If there exists an absolute strongest authored relationship spec for attrName, issue an error.
  • Otherwise author an attribute spec at the current EditTarget using the provided typeName and custom for the required metadata fields. Note that these supplied arguments are only ever used in this particular circumstance, in all other cases they are ignored.
USD_API UsdAttribute CreateAttribute ( const TfToken name,
const SdfValueTypeName typeName,
SdfVariability  variability = SdfVariabilityVarying 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Create a custom attribute with name, typeName and variability.

USD_API UsdAttribute CreateAttribute ( const std::vector< std::string > &  nameElts,
const SdfValueTypeName typeName,
bool  custom,
SdfVariability  variability = SdfVariabilityVarying 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload of CreateAttribute() accepts a vector of name components used to construct a namespaced property name.

For details, see Names, Namespace Ordering, and Property Namespaces

USD_API UsdAttribute CreateAttribute ( const std::vector< std::string > &  nameElts,
const SdfValueTypeName typeName,
SdfVariability  variability = SdfVariabilityVarying 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Create a custom attribute with nameElts, typeName, and variability.

USD_API UsdRelationship CreateRelationship ( const TfToken relName,
bool  custom = true 
) const

Author scene description for the relationship named relName at the current EditTarget if none already exists.

Return a valid relationship if scene description was successfully authored or if it already existed, return an invalid relationship otherwise.

Suggested use:

* if (UsdRelationship myRel = prim.CreateRelationship(...)) {
* // success.
* }
*

To call this, GetPrim() must return a valid prim.

  • If a spec for this relationship already exists at the current edit target, do nothing.
  • If a spec for relName of a different spec type (e.g. an attribute) exists at the current EditTarget, issue an error.
  • If name refers to a builtin relationship according to the prim's definition, author a relationship spec with required metadata from the definition.
  • If name refers to a builtin attribute, issue an error.
  • If there exists an absolute strongest authored relationship spec for relName, author a relationship spec at the current EditTarget by copying required metadata from that strongest spec.
  • If there exists an absolute strongest authored attribute spec for relName, issue an error.
  • Otherwise author a uniform relationship spec at the current EditTarget, honoring custom .
USD_API UsdRelationship CreateRelationship ( const std::vector< std::string > &  nameElts,
bool  custom = true 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload of CreateRelationship() accepts a vector of name components used to construct a namespaced property name.

For details, see Names, Namespace Ordering, and Property Namespaces

USD_API SdfPathVector FindAllAttributeConnectionPaths ( std::function< bool(UsdAttribute const &)> const &  pred = nullptr,
bool  recurseOnSources = false 
) const

Search the prim subtree rooted at this prim for attributes for which predicate returns true, collect their connection source paths and return them in an arbitrary order.

If recurseOnSources is true, act as if this function was invoked on the connected prims and owning prims of connected properties also and return the union.

USD_API SdfPathVector FindAllRelationshipTargetPaths ( std::function< bool(UsdRelationship const &)> const &  pred = nullptr,
bool  recurseOnTargets = false 
) const

Search the prim subtree rooted at this prim for relationships for which predicate returns true, collect their target paths and return them in an arbitrary order.

If recurseOnTargets is true, act as if this function was invoked on the targeted prims and owning prims of targeted properties also (but not of forwarding relationships) and return the union.

UsdPrimSiblingRange GetAllChildren ( ) const
inline

Return all this prim's children as an iterable range.

Definition at line 1878 of file prim.h.

USD_API TfTokenVector GetAllChildrenNames ( ) const

Return the names of the child prims in the order they appear when iterating over GetAllChildren.

UsdPrimSubtreeRange GetAllDescendants ( ) const
inline

Return all this prim's descendants as an iterable range.

Note
This method is not yet available in python, pending some refactoring to make it more feasible.

See Prim predicate flags and UsdPrimDefaultPredicate for more information, UsdStage::Traverse(), and UsdPrimRange for more general Stage traversal behaviors.

Definition at line 2075 of file prim.h.

USD_API TfTokenVector GetAppliedSchemas ( ) const

Return a vector containing the names of API schemas which have been applied to this prim.

This includes both the authored API schemas applied using the Apply() method on the particular schema class as well as any built-in API schemas that are automatically included through the prim type's prim definition. To get only the authored API schemas use GetPrimTypeInfo instead.

USD_API UsdAttribute GetAttribute ( const TfToken attrName) const

Return a UsdAttribute with the name attrName.

The attribute returned may or may not actually exist so it must be checked for validity. Suggested use:

* if (UsdAttribute myAttr = prim.GetAttribute("myAttr")) {
* // myAttr is safe to use.
* // Edits to the owning stage requires subsequent validation.
* } else {
* // myAttr was not defined/authored
* }
*
USD_API UsdAttribute GetAttributeAtPath ( const SdfPath path) const

Returns the attribute at path on the same stage as this prim.

If path is relative, it will be anchored to the path of this prim.

Note
There is no guarantee that this method returns an attribute on this prim. This is only guaranteed if path is a purely relative property path.
See Also
GetAttribute(const TfToken&) const
UsdStage::GetAttributeAtPath(const SdfPath&) const
USD_API std::vector<UsdAttribute> GetAttributes ( ) const

Like GetProperties(), but exclude all relationships from the result.

USD_API std::vector<UsdAttribute> GetAuthoredAttributes ( ) const

Like GetAttributes(), but exclude attributes without authored scene description from the result.

See UsdProperty::IsAuthored().

USD_API std::vector<UsdProperty> GetAuthoredProperties ( const PropertyPredicateFunc predicate = {}) const

Return this prim's properties (attributes and relationships) that have authored scene description, ordered by name according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan.

If a valid predicate is passed in, then only authored properties whose names pass the predicate are included in the result. This is useful if the client is interested only in a subset of authored properties on the prim. For example, only the ones in a given namespace or only the ones needed to compute a value.

See Also
GetProperties()
UsdProperty::IsAuthored()
USD_API std::vector<UsdProperty> GetAuthoredPropertiesInNamespace ( const std::vector< std::string > &  namespaces) const

Like GetPropertiesInNamespace(), but exclude properties that do not have authored scene description from the result.

See UsdProperty::IsAuthored().

For details of namespaced properties, see Names, Namespace Ordering, and Property Namespaces

USD_API std::vector<UsdProperty> GetAuthoredPropertiesInNamespace ( const std::string &  namespaces) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. namespaces must be an already-concatenated ordered set of namespaces, and may or may not terminate with the namespace-separator character.

If namespaces is empty, this method is equivalent to GetAuthoredProperties().

USD_API TfTokenVector GetAuthoredPropertyNames ( const PropertyPredicateFunc predicate = {}) const

Return this prim's property names (attributes and relationships) that have authored scene description, ordered according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan.

If a valid predicate is passed in, then only the authored properties whose names pass the predicate are included in the result. This is useful if the client is interested only in a subset of authored properties on the prim. For example, only the ones in a given namespace or only the ones needed to compute a value.

See Also
GetPropertyNames()
UsdProperty::IsAuthored()
USD_API std::vector<UsdRelationship> GetAuthoredRelationships ( ) const

Like GetRelationships(), but exclude relationships without authored scene description from the result.

See UsdProperty::IsAuthored().

USD_API UsdPrim GetChild ( const TfToken name) const

Return this prim's direct child named name if it has one, otherwise return an invalid UsdPrim.

Equivalent to:

* prim.GetStage()->GetPrimAtPath(prim.GetPath().AppendChild(name))
*
UsdPrimSiblingRange GetChildren ( ) const
inline

Return this prim's active, loaded, defined, non-abstract children as an iterable range.

Equivalent to:

See Prim predicate flags and UsdPrimDefaultPredicate for more information.

Definition at line 1884 of file prim.h.

USD_API TfTokenVector GetChildrenNames ( ) const

Return the names of the child prims in the order they appear when iterating over GetChildren.

USD_API TfTokenVector GetChildrenReorder ( ) const

Return the strongest opinion for the metadata used to reorder children of this prim.

Due to how reordering of prim children is composed, this value cannot be relied on to get the actual order of the prim's children. Use GetChidrenNames, GetAllChildrenNames, GetFilteredChildrenNames to get the true child order if needed.

UsdPrimSubtreeRange GetDescendants ( ) const
inline

Return this prim's active, loaded, defined, non-abstract descendants as an iterable range.

Equivalent to:

Note
This method is not yet available in python, pending some refactoring to make it more feasible.

See Prim predicate flags and UsdPrimDefaultPredicate for more information, UsdStage::Traverse(), and UsdPrimRange for more general Stage traversal behaviors.

Definition at line 2081 of file prim.h.

UsdPrimSiblingRange GetFilteredChildren ( const Usd_PrimFlagsPredicate &  predicate) const
inline

Return a subset of all of this prim's children filtered by predicate as an iterable range.

The predicate is generated by combining a series of prim flag terms with either && or || and !.

Example usage:

* // Get all active model children.
*
* // Get all model children that pass the default predicate.
*

If this prim is an instance, no children will be returned unless UsdTraverseInstanceProxies is used to allow instance proxies to be returned, or if this prim is itself an instance proxy.

See Prim predicate flags and UsdPrimDefaultPredicate for more information.

Definition at line 1871 of file prim.h.

USD_API TfTokenVector GetFilteredChildrenNames ( const Usd_PrimFlagsPredicate &  predicate) const

Return the names of the child prims in the order they appear when iterating over GetFilteredChildren(predicate).

UsdPrimSubtreeRange GetFilteredDescendants ( const Usd_PrimFlagsPredicate &  predicate) const
inline

Return a subset of all of this prim's descendants filtered by predicate as an iterable range.

The predicate is generated by combining a series of prim flag terms with either && or || and !.

Example usage:

* // Get all active model descendants.
*
* // Get all model descendants that pass the default predicate.
*

If this prim is an instance, no descendants will be returned unless UsdTraverseInstanceProxies is used to allow instance proxies to be returned, or if this prim is itself an instance proxy.

Note
This method is not yet available in python, pending some refactoring to make it more feasible.

See Prim predicate flags and UsdPrimDefaultPredicate for more information, UsdStage::Traverse(), and UsdPrimRange for more general Stage traversal behaviors.

Definition at line 2068 of file prim.h.

USD_API UsdPrim GetFilteredNextSibling ( const Usd_PrimFlagsPredicate &  predicate) const

Return this prim's next sibling that matches predicate if it has one, otherwise return the invalid UsdPrim.

See Prim predicate flags and UsdPrimDefaultPredicate for more information.

USD_API UsdInherits GetInherits ( ) const

Return a UsdInherits object that allows one to add, remove, or mutate inherits at the currently set UsdEditTarget.

While the UsdInherits object has no methods for listing the currently authored inherits on a prim, one can use a UsdPrimCompositionQuery to query the inherits arcs that are composed by this prim.

See Also
UsdPrimCompositionQuery::GetDirectInherits
USD_API std::vector<UsdPrim> GetInstances ( ) const

If this prim is a prototype prim, returns all prims that are instances of this prototype.

Otherwise, returns an empty vector.

Note that this function will return prims in prototypes for instances that are nested beneath other instances.

USD_API UsdPrim GetNextSibling ( ) const

Return this prim's next active, loaded, defined, non-abstract sibling if it has one, otherwise return an invalid UsdPrim.

Equivalent to:

See Prim predicate flags and UsdPrimDefaultPredicate for more information.

USD_API UsdObject GetObjectAtPath ( const SdfPath path) const

Returns the object at path on the same stage as this prim.

If path is is relative, it will be anchored to the path of this prim.

See Also
UsdStage::GetObjectAtPath(const SdfPath&) const
UsdPrim GetParent ( ) const
inline

Return this prim's parent prim.

Return an invalid UsdPrim if this is a root prim.

Definition at line 1038 of file prim.h.

USD_API UsdPayloads GetPayloads ( ) const

Return a UsdPayloads object that allows one to add, remove, or mutate payloads at the currently set UsdEditTarget.

While the UsdPayloads object has no methods for listing the currently authored payloads on a prim, one can use a UsdPrimCompositionQuery to query the payload arcs that are composed by this prim.

USD_API UsdPrim GetPrimAtPath ( const SdfPath path) const

Returns the prim at path on the same stage as this prim.

If path is is relative, it will be anchored to the path of this prim.

See Also
UsdStage::GetPrimAtPath(const SdfPath&) const
const UsdPrimDefinition& GetPrimDefinition ( ) const
inline

Return this prim's definition based on the prim's type if the type is a registered prim type.

Returns an empty prim definition if it is not.

Definition at line 161 of file prim.h.

const PcpPrimIndex& GetPrimIndex ( ) const
inline

Return the cached prim index containing all sites that can contribute opinions to this prim.

The prim index can be used to examine the composition arcs and scene description sites that can contribute to this prim's property and metadata values.

The prim index returned by this function is optimized and may not include sites that do not contribute opinions to this prim. Use UsdPrim::ComputeExpandedPrimIndex to compute a prim index that includes all possible sites that could contribute opinions.

This prim index will be empty for prototype prims. This ensures that these prims do not provide any attribute or metadata values. For all other prims in prototypes, this is the prim index that was chosen to be shared with all other instances. In either case, the prim index's path will not be the same as the prim's path.

Prim indexes may be invalidated by changes to the UsdStage and cannot detect if they are expired. Clients should avoid keeping copies of the prim index across such changes, which include scene description changes or changes to load state.

Definition at line 1621 of file prim.h.

UsdPrim GetPrimInPrototype ( ) const
inline

If this prim is an instance proxy, return the UsdPrim for the corresponding prim in the instance's prototype.

Otherwise, return an invalid UsdPrim.

Definition at line 1578 of file prim.h.

USD_API SdfPrimSpecHandleVector GetPrimStack ( ) const

Return all the authored SdfPrimSpecs that may contain opinions for this prim in order from strong to weak.

This does not include all the places where contributing prim specs could potentially be created; rather, it includes only those prim specs that already exist. To discover all the places that prim specs could be authored that would contribute opinions, see "Composition Structure"

Note
Use this method for debugging and diagnostic purposes. It is not advisable to retain a PrimStack for expedited metadata value resolution, since not all metadata resolves with simple "strongest opinion wins" semantics.
const UsdPrimTypeInfo& GetPrimTypeInfo ( ) const
inline

Return the prim's full type info composed from its type name, applied API schemas, and any fallback types defined on the stage for unrecognized prim type names.

The returned type structure contains the "true" schema type used to create this prim's prim definition and answer the IsA query. This value is cached and efficient to query.

See Also
GetTypeName
GetAppliedSchemas
Fallback Prim Types

Definition at line 154 of file prim.h.

USD_API std::vector<UsdProperty> GetProperties ( const PropertyPredicateFunc predicate = {}) const

Return all of this prim's properties (attributes and relationships), including all builtin properties, ordered by name according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan.

If a valid predicate is passed in, then only properties whose names pass the predicate are included in the result. This is useful if the client is interested only in a subset of properties on the prim. For example, only the ones in a given namespace or only the ones needed to compute a value.

To obtain only either attributes or relationships, use either GetAttributes() or GetRelationships().

To determine whether a property is either an attribute or a relationship, use the UsdObject::As() and UsdObject::Is() methods in C++:

* // Use As<>() to obtain a subclass instance.
* if (UsdAttribute attr = property.As<UsdAttribute>()) {
* // use attribute 'attr'.
* else if (UsdRelationship rel = property.As<UsdRelationship>()) {
* // use relationship 'rel'.
* }
*
* // Use Is<>() to discriminate only.
* if (property.Is<UsdAttribute>()) {
* // property is an attribute.
* }
*

In Python, use the standard isinstance() function:

* if isinstance(property, Usd.Attribute):
* # property is a Usd.Attribute.
* elif isinstance(property, Usd.Relationship):
* # property is a Usd.Relationship.
*
See Also
GetAuthoredProperties()
UsdProperty::IsAuthored()
USD_API std::vector<UsdProperty> GetPropertiesInNamespace ( const std::vector< std::string > &  namespaces) const

Return this prim's properties that are inside the given property namespace ordered according to the strongest propertyOrder statement in scene description if one exists, otherwise ordered according to TfDictionaryLessThan.

A namespaces argument whose elements are ["ri", "attribute"] will return all the properties under the namespace "ri:attribute", i.e. "ri:attribute:*". An empty namespaces argument is equivalent to GetProperties().

For details of namespaced properties, see Names, Namespace Ordering, and Property Namespaces

USD_API std::vector<UsdProperty> GetPropertiesInNamespace ( const std::string &  namespaces) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. namespaces must be an already-concatenated ordered set of namespaces, and may or may not terminate with the namespace-separator character.

If namespaces is empty, this method is equivalent to GetProperties().

USD_API UsdProperty GetProperty ( const TfToken propName) const

Return a UsdProperty with the name propName.

The property returned may or may not actually exist so it must be checked for validity. Suggested use:

* if (UsdProperty myProp = prim.GetProperty("myProp")) {
* // myProp is safe to use.
* // Edits to the owning stage requires subsequent validation.
* } else {
* // myProp was not defined/authored
* }
*
USD_API UsdProperty GetPropertyAtPath ( const SdfPath path) const

Returns the property at path on the same stage as this prim.

If path is relative, it will be anchored to the path of this prim.

Note
There is no guarantee that this method returns a property on this prim. This is only guaranteed if path is a purely relative property path.
See Also
GetProperty(const TfToken&) const
UsdStage::GetPropertyAtPath(const SdfPath&) const
USD_API TfTokenVector GetPropertyNames ( const PropertyPredicateFunc predicate = {}) const

Return all of this prim's property names (attributes and relationships), including all builtin properties.

If a valid predicate is passed in, then only properties whose names pass the predicate are included in the result. This is useful if the client is interested only in a subset of properties on the prim. For example, only the ones in a given namespace or only the ones needed to compute a value.

See Also
GetAuthoredPropertyNames()
UsdProperty::IsAuthored()
USD_API TfTokenVector GetPropertyOrder ( ) const

Return the strongest propertyOrder metadata value authored on this prim.

USD_API UsdPrim GetPrototype ( ) const

If this prim is an instance, return the UsdPrim for the corresponding prototype.

Otherwise, return an invalid UsdPrim.

USD_API UsdReferences GetReferences ( ) const

Return a UsdReferences object that allows one to add, remove, or mutate references at the currently set UsdEditTarget.

While the UsdReferences object has no methods for listing the currently authored references on a prim, one can use a UsdPrimCompositionQuery to query the reference arcs that are composed by this prim.

See Also
UsdPrimCompositionQuery::GetDirectReferences
USD_API UsdRelationship GetRelationship ( const TfToken relName) const

Return a UsdRelationship with the name relName.

The relationship returned may or may not actually exist so it must be checked for validity. Suggested use:

* if (UsdRelationship myRel = prim.GetRelationship("myRel")) {
* // myRel is safe to use.
* // Edits to the owning stage requires subsequent validation.
* } else {
* // myRel was not defined/authored
* }
*
USD_API UsdRelationship GetRelationshipAtPath ( const SdfPath path) const

Returns the relationship at path on the same stage as this prim.

If path is relative, it will be anchored to the path of this prim.

Note
There is no guarantee that this method returns a relationship on this prim. This is only guaranteed if path is a purely relative property path.
See Also
GetRelationship(const TfToken&) const
UsdStage::GetRelationshipAtPath(const SdfPath&) const
USD_API std::vector<UsdRelationship> GetRelationships ( ) const

Like GetProperties(), but exclude all attributes from the result.

USD_API UsdSpecializes GetSpecializes ( ) const

Return a UsdSpecializes object that allows one to add, remove, or mutate specializes at the currently set UsdEditTarget.

While the UsdSpecializes object has no methods for listing the currently authored specializes on a prim, one can use a UsdPrimCompositionQuery to query the specializes arcs that are composed by this prim.

SdfSpecifier GetSpecifier ( ) const
inline

Return this prim's composed specifier.

Definition at line 166 of file prim.h.

const TfToken& GetTypeName ( ) const
inline

Return this prim's composed type name.

This value is cached and is efficient to query. Note that this is just the composed type name as authored and may not represent the full type of the prim and its prim definition. If you need to reason about the actual type of the prim, use GetPrimTypeInfo instead as it accounts for recognized schemas, applied API schemas, fallback types, etc.

Definition at line 197 of file prim.h.

USD_API UsdVariantSet GetVariantSet ( const std::string &  variantSetName) const

Retrieve a specifically named VariantSet for editing or constructing a UsdEditTarget.

This is a shortcut for

* prim.GetVariantSets().GetVariantSet(variantSetName)
*
USD_API UsdVariantSets GetVariantSets ( ) const

Return a UsdVariantSets object representing all the VariantSets present on this prim.

The returned object also provides the API for adding new VariantSets to the prim.

bool HasAPI ( const TfToken instanceName = TfToken()) const
inline

Return true if the UsdPrim has had an API schema represented by the C++ class type T applied to it through the Apply() method provided on the API schema class.

instanceName, if non-empty is used to determine if a particular instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been applied to the prim. A coding error is issued if a non-empty instanceName is passed in and T represents a single-apply API schema.

__Using HasAPI in C++__

* UsdPrim prim = stage->OverridePrim("/path/to/prim");
* MyDomainBozAPI = MyDomainBozAPI::Apply(prim);
* assert(prim.HasAPI<MyDomainBozAPI>());
*
* /*instanceName*/ TfToken("geom"))
* assert(prim.HasAPI<UsdCollectionAPI>()
* assert(prim.HasAPI<UsdCollectionAPI>(/*instanceName*/ TfToken("geom")))
*

The python version of this method takes as an argument the TfType of the API schema class. Similar validation of the schema type is performed in python at run-time and a coding error is issued if the given type is not a valid applied API schema.

Using HasAPI in Python

1 * prim = stage.OverridePrim("/path/to/prim")
2 * bozAPI = MyDomain.BozAPI.Apply(prim)
3 * assert prim.HasAPI(MyDomain.BozAPI)
4 *
5 * collAPI = Usd.CollectionAPI.Apply(prim, "geom")
6 * assert(prim.HasAPI(Usd.CollectionAPI))
7 * assert(prim.HasAPI(Usd.CollectionAPI, instanceName="geom"))
8 *

Definition at line 577 of file prim.h.

USD_API bool HasAPI ( const TfType schemaType,
const TfToken instanceName = TfToken() 
) const

Return true if a prim has an API schema with TfType schemaType.

instanceName, if non-empty is used to determine if a particular instance of a multiple-apply API schema (eg. UsdCollectionAPI) has been applied to the prim. A coding error is issued if a non-empty instanceName is passed in and T represents a single-apply API schema.

USD_API bool HasAttribute ( const TfToken attrName) const

Return true if this prim has an attribute named attrName, false otherwise.

bool HasAuthoredActive ( ) const
inline

Return true if this prim has an authored opinion for 'active', false otherwise.

See How "active" Affects Prims on a UsdStage for what it means for a prim to be active.

Definition at line 242 of file prim.h.

USD_API bool HasAuthoredInherits ( ) const

Return true if this prim has any authored inherits.

bool HasAuthoredInstanceable ( ) const
inline

Return true if this prim has an authored opinion for 'instanceable', false otherwise.

Definition at line 1520 of file prim.h.

USD_API bool HasAuthoredPayloads ( ) const

Return true if this prim has any authored payloads.

USD_API bool HasAuthoredReferences ( ) const

Return true if this prim has any authored references.

USD_API bool HasAuthoredSpecializes ( ) const

Returns true if this prim has any authored specializes.

bool HasAuthoredTypeName ( ) const
inline

Return true if a typeName has been authored.

Definition at line 211 of file prim.h.

bool HasDefiningSpecifier ( ) const
inline

Return true if this prim has a specifier of type SdfSpecifierDef or SdfSpecifierClass.

See Also
SdfIsDefiningSpecifier

Definition at line 269 of file prim.h.

USD_API bool HasPayload ( ) const
Deprecated:
Return true if a payload is present on this prim.
See Also
Payloads: Impact of Using and Not Using
USD_API bool HasProperty ( const TfToken propName) const

Return true if this prim has an property named propName, false otherwise.

USD_API bool HasRelationship ( const TfToken relName) const

Return true if this prim has a relationship named relName, false otherwise.

USD_API bool HasVariantSets ( ) const

Return true if this prim has any authored VariantSets.

Note
this connotes only the existence of one of more VariantSets, not that such VariantSets necessarily contain any variants or variant opinions.
bool IsA ( ) const
inline

Return true if the prim's schema type, is or inherits schema type T.

See Also
GetPrimTypeInfo
UsdPrimTypeInfo::GetSchemaType
Fallback Prim Types

Definition at line 526 of file prim.h.

USD_API bool IsA ( const TfType schemaType) const

Return true if the prim's schema type is or inherits schemaType.

See Also
GetPrimTypeInfo
UsdPrimTypeInfo::GetSchemaType
Fallback Prim Types
bool IsAbstract ( ) const
inline

Return true if this prim or any of its ancestors is a class.

Definition at line 261 of file prim.h.

bool IsActive ( ) const
inline

Return true if this prim is active, meaning neither it nor any of its ancestors have active=false.

Return false otherwise.

See How "active" Affects Prims on a UsdStage for what it means for a prim to be active.

Definition at line 219 of file prim.h.

bool IsDefined ( ) const
inline

Return true if this prim and all its ancestors have defining specifiers, false otherwise.

See Also
SdfIsDefiningSpecifier.

Definition at line 265 of file prim.h.

bool IsGroup ( ) const
inline

Return true if this prim is a model group based on its kind metadata, false otherwise.

If this prim is a group, it is also necessarily a model.

Definition at line 258 of file prim.h.

bool IsInPrototype ( ) const
inline

Return true if this prim is a prototype prim or a descendant of a prototype prim, false otherwise.

See Also
IsPrototype

Definition at line 1565 of file prim.h.

bool IsInstance ( ) const
inline

Return true if this prim is an instance of a prototype, false otherwise.

If this prim is an instance, calling GetPrototype() will return the UsdPrim for the corresponding prototype prim.

Definition at line 1529 of file prim.h.

bool IsInstanceable ( ) const
inline

Return true if this prim has been marked as instanceable.

Note that this is not the same as IsInstance(). A prim may return true for IsInstanceable() and false for IsInstance() if this prim is not active or if it is marked as instanceable but contains no instanceable data.

Definition at line 1500 of file prim.h.

bool IsInstanceProxy ( ) const
inline

Return true if this prim is an instance proxy, false otherwise.

An instance proxy prim represents a descendent of an instance prim.

Definition at line 1534 of file prim.h.

bool IsLoaded ( ) const
inline

Return true if this prim is active, and either it is loadable and it is loaded, or its nearest loadable ancestor is loaded, or it has no loadable ancestor; false otherwise.

Definition at line 249 of file prim.h.

bool IsModel ( ) const
inline

Return true if this prim is a model based on its kind metadata, false otherwise.

Definition at line 253 of file prim.h.

static USD_API bool IsPathInPrototype ( const SdfPath path)
static

Return true if the given path identifies a prototype prim or a prim or property descendant of a prototype prim, false otherwise.

See Also
IsPrototypePath
bool IsPrototype ( ) const
inline

Return true if this prim is an instancing prototype prim, false otherwise.

See Also
IsInPrototype

Definition at line 1559 of file prim.h.

static USD_API bool IsPrototypePath ( const SdfPath path)
static

Return true if the given path identifies a prototype prim, false otherwise.

This function will return false for prim and property paths that are descendants of a prototype prim path.

See Also
IsPathInPrototype
USD_API bool IsPseudoRoot ( ) const

Returns true if the prim is the pseudo root.

Equivalent to

USD_API void Load ( UsdLoadPolicy  policy = UsdLoadWithDescendants) const

Load this prim, all its ancestors, and by default all its descendants.

If loadPolicy is UsdLoadWithoutDescendants, then load only this prim and its ancestors.

See UsdStage::Load for additional details.

bool RemoveAPI ( ) const
inline

Removes a single-apply API schema with the given C++ type 'SchemaType' from this prim in the current edit target.

This is done by removing the API schema's name token from the token-valued, listOp metadata apiSchemas on this prim as well as authoring an explicit deletion of schema name from the listOp.

Returns true upon success or if the API schema is already deleted in the current edit target.

An error is issued and false returned for any of the following conditions:

  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be deleted in the apiSchemas listOp metadata

Definition at line 780 of file prim.h.

USD_API bool RemoveAPI ( const TfType schemaType) const

Non-templated overload of the templated RemoveAPI above.

This function behaves exactly like the templated RemoveAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated RemoveAPI is preferred.

bool RemoveAPI ( const TfToken instanceName) const
inline

Removes a multiple-apply API schema with the given C++ type 'SchemaType' and instance name instanceName from this prim in the current edit target.

This is done by removing the instanced schema name token from the token-valued, listOp metadata apiSchemas on this prim as well as authoring an explicit deletion of the name from the listOp. For example, if SchemaType is 'UsdCollectionAPI' and instanceName is 'plasticStuff', the name 'CollectionAPI:plasticStuff' is deleted from the 'apiSchemas' listOp metadata.

Returns true upon success or if the API schema with this instanceName is already deleted in the current edit target.

An error is issued and false returned for any of the following conditions:

  • instanceName is empty
  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be deleted in the apiSchemas listOp metadata

Definition at line 823 of file prim.h.

USD_API bool RemoveAPI ( const TfType schemaType,
const TfToken instanceName 
) const

Non-templated overload of the templated RemoveAPI above.

This function behaves exactly like the templated RemoveAPI except for the runtime schemaType validation which happens at compile time in the templated version. This method is provided for python clients. Use of the templated RemoveAPI is preferred.

USD_API bool RemoveAppliedSchema ( const TfToken appliedSchemaName) const

Removes the applied API schema name token appliedSchemaName from the apiSchemas metadata for this prim at the current edit target.

For multiple-apply schemas the name token should include the instance name for the applied schema, for example 'CollectionAPI:plasticStuff'

For an explicit list operation, this removes the applied schema name from the explicit items list if it was present. For a non-explicit list operation, this will remove any occurrence of the applied schema name from the prepended and appended item as well as adding it to the deleted items list.

Returns true upon success or if the API schema is already deleted in the current edit target.

An error is issued and false returned for any of the following conditions:

  • this prim is not a valid prim for editing
  • this prim is valid, but cannot be reached or overridden in the current edit target
  • the schema name cannot be deleted in the apiSchemas listOp metadata

Unlike RemoveAPI this method does not require that the name token refer to a valid API schema type. RemoveAPI is the preferred method for removing valid API schemas.

USD_API bool RemoveProperty ( const TfToken propName)

Remove all scene description for the property with the given propName in the current UsdEditTarget.

Return true if the property is removed, false otherwise.

Because this method can only remove opinions about the property from the current EditTarget, you may generally find it more useful to use UsdAttribute::Block(), which will ensure that all values from the EditTarget and weaker layers for the property will be ignored.

bool SetActive ( bool  active) const
inline

Author 'active' metadata for this prim at the current EditTarget.

See How "active" Affects Prims on a UsdStage for the effects of activating or deactivating a prim.

Definition at line 225 of file prim.h.

void SetChildrenReorder ( const TfTokenVector order) const
inline

Author an opinion for the metadata used to reorder children of this prim at the current EditTarget.

Definition at line 1021 of file prim.h.

bool SetInstanceable ( bool  instanceable) const
inline

Author 'instanceable' metadata for this prim at the current EditTarget.

Definition at line 1508 of file prim.h.

USD_API bool SetPayload ( const SdfPayload payload) const
Deprecated:
Author payload metadata for this prim at the current edit target. Return true on success, false if the value could not be set.
See Also
Payloads: Impact of Using and Not Using
USD_API bool SetPayload ( const std::string &  assetPath,
const SdfPath primPath 
) const
Deprecated:
Shorthand for SetPayload(SdfPayload(assetPath, primPath)).
USD_API bool SetPayload ( const SdfLayerHandle &  layer,
const SdfPath primPath 
) const
Deprecated:
Shorthand for SetPayload(SdfPayload(layer->GetIdentifier(), primPath)).
void SetPropertyOrder ( const TfTokenVector order) const
inline

Author an opinion for propertyOrder metadata on this prim at the current EditTarget.

Definition at line 431 of file prim.h.

bool SetSpecifier ( SdfSpecifier  specifier) const
inline

Author an opinion for this Prim's specifier at the current edit target.

Definition at line 186 of file prim.h.

bool SetTypeName ( const TfToken typeName) const
inline

Author this Prim's typeName at the current EditTarget.

Definition at line 200 of file prim.h.

USD_API void Unload ( ) const

Unloads this prim and all its descendants.

See UsdStage::Unload for additional details.


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