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

#include <object.h>

+ Inheritance diagram for UsdObject:

Classes

struct  _Null
 

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
 
USD_API bool GetMetadata (const TfToken &key, VtValue *value) const
 
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
 
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
 
USD_API bool ClearMetadata (const TfToken &key) const
 
USD_API bool HasMetadata (const TfToken &key) const
 
USD_API bool HasAuthoredMetadata (const TfToken &key) const
 
template<class T >
bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const
 
USD_API bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
 
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
 
USD_API bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const
 
USD_API bool ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
 
USD_API bool HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 
USD_API bool HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 
USD_API UsdMetadataValueMap GetAllMetadata () const
 
USD_API UsdMetadataValueMap GetAllAuthoredMetadata () const
 
Core metadata fields
USD_API bool IsHidden () const
 
USD_API bool SetHidden (bool hidden) const
 
USD_API bool ClearHidden () const
 Clears the opinion for "Hidden" at the current EditTarget. More...
 
USD_API bool HasAuthoredHidden () const
 
USD_API VtDictionary GetCustomData () const
 
USD_API VtValue GetCustomDataByKey (const TfToken &keyPath) const
 
USD_API void SetCustomData (const VtDictionary &customData) const
 
USD_API void SetCustomDataByKey (const TfToken &keyPath, const VtValue &value) const
 
USD_API void ClearCustomData () const
 
USD_API void ClearCustomDataByKey (const TfToken &keyPath) const
 
USD_API bool HasCustomData () const
 
USD_API bool HasCustomDataKey (const TfToken &keyPath) const
 
USD_API bool HasAuthoredCustomData () const
 
USD_API bool HasAuthoredCustomDataKey (const TfToken &keyPath) const
 
USD_API VtDictionary GetAssetInfo () const
 
USD_API VtValue GetAssetInfoByKey (const TfToken &keyPath) const
 
USD_API void SetAssetInfo (const VtDictionary &customData) const
 
USD_API void SetAssetInfoByKey (const TfToken &keyPath, const VtValue &value) const
 
USD_API void ClearAssetInfo () const
 
USD_API void ClearAssetInfoByKey (const TfToken &keyPath) const
 
USD_API bool HasAssetInfo () const
 
USD_API bool HasAssetInfoKey (const TfToken &keyPath) const
 
USD_API bool HasAuthoredAssetInfo () const
 
USD_API bool HasAuthoredAssetInfoKey (const TfToken &keyPath) const
 
USD_API std::string GetDocumentation () const
 
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
 
USD_API bool HasAuthoredDocumentation () const
 
USD_API std::string GetDisplayName () const
 
USD_API bool SetDisplayName (const std::string &name) const
 
USD_API bool ClearDisplayName () const
 
USD_API bool HasAuthoredDisplayName () const
 

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
 
UsdObjType Usd_GetObjType (const UsdObject &obj)
 

Structural and Integrity Info about the Object itself

bool operator== (const UsdObject &lhs, const UsdObject &rhs)
 
bool operator!= (const UsdObject &lhs, const UsdObject &rhs)
 
bool operator< (const UsdObject &lhs, const UsdObject &rhs)
 
size_t hash_value (const UsdObject &obj)
 
template<class HashState >
void TfHashAppend (HashState &h, 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
 
SdfPath GetPath () const
 
const SdfPathGetPrimPath () const
 
UsdPrim GetPrim () const
 
const TfTokenGetName () const
 
template<class T >
T As () const
 
template<class T >
bool Is () const
 
USD_API std::string GetDescription () const
 

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 132 of file object.h.

Constructor & Destructor Documentation

UsdObject::UsdObject ( )
inline

Default constructor produces an invalid object.

Definition at line 135 of file object.h.

template<class Derived >
UsdObject::UsdObject ( _Null< Derived >  )
inlineexplicitprotected

Definition at line 694 of file object.h.

UsdObject::UsdObject ( const Usd_PrimDataHandle prim,
const SdfPath proxyPrimPath 
)
inlineprotected

Definition at line 698 of file object.h.

UsdObject::UsdObject ( UsdObjType  objType,
const Usd_PrimDataHandle prim,
const SdfPath proxyPrimPath,
const TfToken propName 
)
inlineprotected

Definition at line 708 of file object.h.

Member Function Documentation

USD_API SdfSpecType UsdObject::_GetDefiningSpecType ( ) const
protected
UsdStage* UsdObject::_GetStage ( ) const
inlineprotected

Definition at line 721 of file object.h.

const Usd_PrimDataHandle& UsdObject::_Prim ( ) const
inlineprotected

Definition at line 728 of file object.h.

const TfToken& UsdObject::_PropName ( ) const
inlineprotected

Definition at line 731 of file object.h.

const SdfPath& UsdObject::_ProxyPrimPath ( ) const
inlineprotected

Definition at line 734 of file object.h.

template<class T >
T UsdObject::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 246 of file object.h.

USD_API void UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::ClearDisplayName ( ) const

Clears this object's display name (metadata) in the current EditTarget (only). Returns true on success.

USD_API bool UsdObject::ClearDocumentation ( ) const

Clears this object's documentation (metadata) in the current EditTarget (only). Returns true on success.

USD_API bool UsdObject::ClearHidden ( ) const

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

USD_API bool UsdObject::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
Usd_OM_Metadata
USD_API bool UsdObject::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
Usd_Dictionary_Type
USD_API UsdMetadataValueMap UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::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 UsdObject::GetDisplayName ( ) const

Return this object's display name (metadata). This returns the empty string if no display name has been set.

See Also
SetDisplayName()
USD_API std::string UsdObject::GetDocumentation ( ) const

Return this object's documentation (metadata). This returns the empty string if no documentation has been set.

See Also
SetDocumentation()
template<typename T >
bool UsdObject::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
Usd_OM_Metadata

Definition at line 756 of file object.h.

USD_API bool UsdObject::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

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

Definition at line 772 of file object.h.

USD_API bool UsdObject::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& UsdObject::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 238 of file object.h.

static char UsdObject::GetNamespaceDelimiter ( )
inlinestatic

Definition at line 667 of file object.h.

SdfPath UsdObject::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 203 of file object.h.

UsdPrim UsdObject::GetPrim ( ) const
inline

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

Definition at line 2610 of file prim.h.

const SdfPath& UsdObject::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 218 of file object.h.

USD_API UsdStageWeakPtr UsdObject::GetStage ( ) const

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

USD_API bool UsdObject::HasAssetInfo ( ) const

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

USD_API bool UsdObject::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 UsdObject::HasAuthoredAssetInfo ( ) const

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

USD_API bool UsdObject::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 UsdObject::HasAuthoredCustomData ( ) const

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

USD_API bool UsdObject::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 UsdObject::HasAuthoredDisplayName ( ) const

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

USD_API bool UsdObject::HasAuthoredDocumentation ( ) const

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

USD_API bool UsdObject::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 UsdObject::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 UsdObject::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
Usd_Dictionary_Type
USD_API bool UsdObject::HasCustomData ( ) const

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

USD_API bool UsdObject::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 UsdObject::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 UsdObject::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
Usd_Dictionary_Type
template<class T >
bool UsdObject::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 257 of file object.h.

USD_API bool UsdObject::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 UsdObject::IsValid ( ) const
inline

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

Definition at line 143 of file object.h.

UsdObject::operator bool ( ) const
inlineexplicit

Returns true if this object is valid, false otherwise.

Definition at line 156 of file object.h.

USD_API void UsdObject::SetAssetInfo ( const VtDictionary customData) const

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

USD_API void UsdObject::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 UsdObject::SetCustomData ( const VtDictionary customData) const

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

USD_API void UsdObject::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 UsdObject::SetDisplayName ( const std::string name) const

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

DisplayName is meant to be a descriptive label, not necessarily an alternate identifier; therefore there is no restriction on which characters can appear in it.

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

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

USD_API bool UsdObject::SetHidden ( bool  hidden) const

Sets the value of the 'hidden' metadata field. See IsHidden() for details.

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

Definition at line 764 of file object.h.

USD_API bool UsdObject::SetMetadata ( const TfToken key,
const VtValue value 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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

Definition at line 782 of file object.h.

USD_API bool UsdObject::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

size_t hash_value ( const UsdObject obj)
friend

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

Definition at line 185 of file object.h.

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 173 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 180 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 164 of file object.h.

template<class HashState >
void TfHashAppend ( HashState &  h,
const UsdObject obj 
)
friend

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

Definition at line 191 of file object.h.

UsdObjType Usd_GetObjType ( const UsdObject obj)
friend

Definition at line 742 of file object.h.

friend class UsdStage
friend

Definition at line 740 of file object.h.


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