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

Base class for Usd scenegraph objects, providing common API. More...

+ Inheritance diagram for UsdObject:

Public Member Functions

 UsdObject ()
 Default constructor produces an invalid object. More...
 
Generic Metadata Access
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...
 
Core metadata fields
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...
 

Static Public Member Functions

static char GetNamespaceDelimiter ()
 

Protected Member Functions

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
 

Friends

class UsdStage
 

Structural and Integrity Info about the Object itself

bool operator== (const UsdObject &lhs, const UsdObject &rhs)
 Equality comparison. More...
 
bool operator!= (const UsdObject &lhs, const UsdObject &rhs)
 Inequality comparison. More...
 
bool operator< (const UsdObject &lhs, const UsdObject &rhs)
 Less-than operator. More...
 
USD_API friend size_t hash_value (const UsdObject &obj)
 
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...
 

Detailed Description

Base class for Usd scenegraph objects, providing common API.

The commonality between the three types of scenegraph objects in Usd (UsdPrim, UsdAttribute, UsdRelationship) is that they can all have metadata. Other objects in the API (UsdReferences, UsdVariantSets, etc.) simply are kinds of metadata.

UsdObject's API primarily provides schema for interacting with the metadata common to all the scenegraph objects, as well as generic access to metadata.

section Usd_UsdObject_Lifetime Lifetime Management and Object Validity

Every derived class of UsdObject supports explicit detection of object validity through an explicit-bool operator, so client code should always be able use objects safely, even across edits to the owning UsdStage. UsdObject classes also perform some level of validity checking upon every use, in order to facilitate debugging of unsafe code, although we reserve the right to activate that behavior only in debug builds, if it becomes compelling to do so for performance reasons. This per-use checking will cause a fatal error upon failing the inline validity check, with an error message describing the namespace location of the dereferenced object on its owning UsdStage.

Definition at line 130 of file object.h.

Constructor & Destructor Documentation

UsdObject ( )
inline

Default constructor produces an invalid object.

Definition at line 133 of file object.h.

Member Function Documentation

T As ( ) const
inline

Convert this UsdObject to another object type T if possible.

Return an invalid T instance if this object's dynamic type is not convertible to T or if this object is invalid.

Definition at line 237 of file object.h.

USD_API void ClearAssetInfo ( ) const

Clear the authored opinion for this object's assetInfo dictionary at the current EditTarget.

Do nothing if there is no such authored opinion.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries. Do nothing if there is no such authored opinion.

USD_API void ClearCustomData ( ) const

Clear the authored opinion for this object's customData dictionary at the current EditTarget.

Do nothing if there is no such authored opinion.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries. Do nothing if there is no such authored opinion.

USD_API bool ClearDocumentation ( ) const

Clears this object's documentation (metadata) in the current EditTarget (only).

Returns true on success.

USD_API bool ClearHidden ( ) const

Clears the opinion for "Hidden" at the current EditTarget.

USD_API bool ClearMetadata ( const TfToken key) const

Clears the authored key's value at the current EditTarget, returning false on error.

If no value is present, this method is a no-op and returns true. It is considered an error to call ClearMetadata when no spec is present for this UsdObject, i.e. if the object has no presence in the current UsdEditTarget.

See Also
General Metadata in USD
USD_API bool ClearMetadataByDictKey ( const TfToken key,
const TfToken keyPath 
) const

Clear any authored value identified by key and keyPath at the current EditTarget.

The keyPath is a ':'-separated path identifying a path in subdictionaries stored in the metadata field at key. Return true if the value is cleared successfully, false otherwise.

See Also
Dictionary-valued Metadata
USD_API UsdMetadataValueMap GetAllAuthoredMetadata ( ) const

Resolve and return all user-authored metadata on this object, sorted lexicographically.

Note
This method does not return field keys for composition arcs, such as references, inherits, payloads, sublayers, variants, or primChildren, nor does it return the default value or timeSamples.
USD_API UsdMetadataValueMap GetAllMetadata ( ) const

Resolve and return all metadata (including both authored and fallback values) on this object, sorted lexicographically.

Note
This method does not return field keys for composition arcs, such as references, inherits, payloads, sublayers, variants, or primChildren, nor does it return the default value or timeSamples.
USD_API VtDictionary GetAssetInfo ( ) const

Return this object's composed assetInfo dictionary.

The asset info dictionary is used to annotate objects representing the root-prims of assets (generally organized as models) with various data related to asset management. For example, asset name, root layer identifier, asset version etc.

The elements of this dictionary are composed element-wise, and are nestable.

There is no means to query an assetInfo field's valuetype other than fetching the value and interrogating it.

See Also
GetAssetInfoByKey()
USD_API VtValue GetAssetInfoByKey ( const TfToken keyPath) const

Return the element identified by keyPath in this object's composed assetInfo dictionary.

The keyPath is a ':'-separated path identifying a value in subdictionaries. This is in general more efficient than composing the entire assetInfo dictionary than pulling out one sub-element.

USD_API VtDictionary GetCustomData ( ) const

Return this object's composed customData dictionary.

CustomData is "custom metadata", a place for applications and users to put uniform data that is entirely dynamic and subject to no schema known to Usd. Unlike metadata like 'hidden', 'displayName' etc, which must be declared in code or a data file that is considered part of one's Usd distribution (e.g. a plugInfo.json file) to be used, customData keys and the datatypes of their corresponding values are ad hoc. No validation will ever be performed that values for the same key in different layers are of the same type - strongest simply wins.

Dictionaries like customData are composed element-wise, and are nestable.

There is no means to query a customData field's valuetype other than fetching the value and interrogating it.

See Also
GetCustomDataByKey()
USD_API VtValue GetCustomDataByKey ( const TfToken keyPath) const

Return the element identified by keyPath in this object's composed customData dictionary.

The keyPath is a ':'-separated path identifying a value in subdictionaries. This is in general more efficient than composing the entire customData dictionary and then pulling out one sub-element.

USD_API std::string GetDescription ( ) const

Return a string that provides a brief summary description of the object.

This method, along with IsValid()/bool_operator, is always safe to call on a possibly-expired object, and the description will specify whether the object is valid or expired, along with a few other bits of data.

USD_API std::string GetDocumentation ( ) const

Return this object's documentation (metadata).

This returns the empty string if no documentation has been set.

See Also
SetDocumentation()
bool GetMetadata ( const TfToken key,
T *  value 
) const
inline

Resolve the requested metadatum named key into value, returning true on success.

Returns
false if key was not resolvable, or if value's type T differed from that of the resolved metadatum.
Note
For any composition-related metadata, as enumerated in GetAllMetadata(), this method will return only the strongest opinion found, not applying the composition rules used by Pcp to process the data. For more processed/composed views of composition data, please refer to the specific interface classes, such as UsdReferences, UsdInherits, UsdVariantSets, etc.
See Also
General Metadata in USD

Definition at line 723 of file object.h.

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.

bool GetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
T *  value 
) const
inline

Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key into value, returning true on success.

If you know you neeed just a small number of elements from a dictionary, accessing them element-wise using this method can be much less expensive than fetching the entire dictionary with GetMetadata(key).

Returns
false if key was not resolvable, or if value's type T differed from that of the resolved metadatum.

The keyPath is a ':'-separated path addressing an element in subdictionaries.

See Also
Dictionary-valued Metadata

Definition at line 739 of file object.h.

USD_API bool GetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
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.

const TfToken& GetName ( ) const
inline

Return the full name of this object, i.e.

the last component of its SdfPath in namespace.

This is equivalent to, but generally cheaper than, GetPath().GetNameToken()

Definition at line 229 of file object.h.

SdfPath GetPath ( ) const
inline

Return the complete scene path to this object on its UsdStage, which may (UsdPrim) or may not (all other subclasses) return a cached result.

Definition at line 194 of file object.h.

UsdPrim GetPrim ( ) const
inline

Return this object if it is a prim, otherwise return this object's nearest owning prim.

Definition at line 2107 of file prim.h.

const SdfPath& GetPrimPath ( ) const
inline

Return this object's path if this object is a prim, otherwise this object's nearest owning prim's path.

Equivalent to GetPrim().GetPath().

Definition at line 209 of file object.h.

USD_API UsdStageWeakPtr GetStage ( ) const

Return the stage that owns the object, and to whose state and lifetime this object's validity is tied.

USD_API bool HasAssetInfo ( ) const

Return true if there are any authored or fallback opinions for this object's assetInfo dictionary, false otherwise.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

USD_API bool HasAuthoredAssetInfo ( ) const

Return true if there are any authored opinions (excluding fallback) for this object's assetInfo dictionary, false otherwise.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

USD_API bool HasAuthoredCustomData ( ) const

Return true if there are any authored opinions (excluding fallback) for this object's customData dictionary, false otherwise.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

USD_API bool HasAuthoredDocumentation ( ) const

Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful value for documentation.

USD_API bool HasAuthoredHidden ( ) const

Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for Hidden.

Note that IsHidden returns a fallback value (false) when hidden is not authored.

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.

USD_API bool HasAuthoredMetadataDictKey ( const TfToken key,
const TfToken keyPath 
) const

Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath.

The keyPath is a ':'-separated path identifying a value in subdictionaries stored in the metadata field at key.

See Also
Dictionary-valued Metadata
USD_API bool HasCustomData ( ) const

Return true if there are any authored or fallback opinions for this object's customData dictionary, false otherwise.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

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.

USD_API bool HasMetadataDictKey ( const TfToken key,
const TfToken keyPath 
) const

Return true if there exists any authored or fallback opinion for key and keyPath.

The keyPath is a ':'-separated path identifying a value in subdictionaries stored in the metadata field at key.

See Also
Dictionary-valued Metadata
bool Is ( ) const
inline

Return true if this object is convertible to T.

This is equivalent to but cheaper than:

* bool(obj.As<T>())
*

Definition at line 248 of file object.h.

USD_API bool IsHidden ( ) const

Gets the value of the 'hidden' metadata field, false if not authored.

When an object is marked as hidden, it is an indicator to clients who generically display objects (such as GUI widgets) that this object should not be included, unless explicitly asked for. Although this is just a hint and thus up to each application to interpret, we use it primarily as a way of simplifying hierarchy displays, by hiding only the representation of the object itself, not its subtree, instead "pulling up" everything below it one level in the hierarchical nesting.

Note again that this is a hint for UI only - it should not be interpreted by any renderer as making a prim invisible to drawing.

bool IsValid ( ) const
inline

Return true if this is a valid object, false otherwise.

Definition at line 141 of file object.h.

operator bool ( ) const
inlineexplicit

Returns true if this object is valid, false otherwise.

Definition at line 154 of file object.h.

USD_API void SetAssetInfo ( const VtDictionary customData) const

Author this object's assetInfo dictionary to assetInfo at the current EditTarget.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

USD_API void SetCustomData ( const VtDictionary customData) const

Author this object's customData dictionary to customData at the current EditTarget.

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.

The keyPath is a ':'-separated path identifying a value in subdictionaries.

USD_API bool SetDocumentation ( const std::string &  doc) const

Sets this object's documentation (metadata). Returns true on success.

USD_API bool SetHidden ( bool  hidden) const

Sets the value of the 'hidden' metadata field.

See IsHidden() for details.

bool SetMetadata ( const TfToken key,
const T &  value 
) const
inline

Set metadatum key's value to value.

Returns
false if value's type does not match the schema type for key.
See Also
General Metadata in USD

Definition at line 731 of file object.h.

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.

bool SetMetadataByDictKey ( const TfToken key,
const TfToken keyPath,
const T &  value 
) const
inline

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. Return true if the value is authored successfully, false otherwise.

See Also
Dictionary-valued Metadata

Definition at line 749 of file object.h.

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.

Friends And Related Function Documentation

bool operator!= ( const UsdObject lhs,
const UsdObject rhs 
)
friend

Inequality comparison.

Return false if lhs and rhs represent the same UsdObject, true otherwise.

Definition at line 171 of file object.h.

bool operator< ( const UsdObject lhs,
const UsdObject rhs 
)
friend

Less-than operator.

Returns true if lhs < rhs.

This simply compares the paths of the objects.

Definition at line 178 of file object.h.

bool operator== ( const UsdObject lhs,
const UsdObject rhs 
)
friend

Equality comparison.

Return true if lhs and rhs represent the same UsdObject, false otherwise.

Definition at line 162 of file object.h.


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