|
Base class for Usd scenegraph objects, providing common API. More...
#include <object.h>
Public Member Functions | |
UsdObject () | |
Default constructor produces an invalid object. | |
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. | |
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. | |
template<typename T > | |
bool | SetMetadata (const TfToken &key, const T &value) const |
Set metadatum key's value to value . | |
USD_API bool | SetMetadata (const TfToken &key, const VtValue &value) const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
USD_API bool | ClearMetadata (const TfToken &key) const |
Clears the authored key's value at the current EditTarget, returning false on error. | |
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 | 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. | |
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. | |
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. | |
template<typename T > | |
bool | SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const |
Author value to the field identified by key and keyPath at the current EditTarget. | |
USD_API bool | SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. | |
USD_API bool | ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const |
Clear any authored value identified by key and keyPath at the current EditTarget. | |
USD_API bool | HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const |
Return true if there exists any authored or fallback opinion for key and keyPath . | |
USD_API bool | HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const |
Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath . | |
USD_API UsdMetadataValueMap | GetAllMetadata () const |
Resolve and return all metadata (including both authored and fallback values) on this object, sorted lexicographically. | |
USD_API UsdMetadataValueMap | GetAllAuthoredMetadata () const |
Resolve and return all user-authored metadata on this object, sorted lexicographically. | |
Core metadata fields | |
USD_API bool | IsHidden () const |
Gets the value of the 'hidden' metadata field, false if not authored. | |
USD_API bool | SetHidden (bool hidden) const |
Sets the value of the 'hidden' metadata field. | |
USD_API bool | ClearHidden () const |
Clears the opinion for "Hidden" at the current EditTarget. | |
USD_API bool | HasAuthoredHidden () const |
Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for Hidden. | |
USD_API VtDictionary | GetCustomData () const |
Return this object's composed customData dictionary. | |
USD_API VtValue | GetCustomDataByKey (const TfToken &keyPath) const |
Return the element identified by keyPath in this object's composed customData dictionary. | |
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. | |
USD_API void | ClearCustomData () const |
Clear the authored opinion for this object's customData dictionary at the current EditTarget. | |
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. | |
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. | |
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. | |
USD_API VtDictionary | GetAssetInfo () const |
Return this object's composed assetInfo dictionary. | |
USD_API VtValue | GetAssetInfoByKey (const TfToken &keyPath) const |
Return the element identified by keyPath in this object's composed assetInfo dictionary. | |
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. | |
USD_API void | ClearAssetInfo () const |
Clear the authored opinion for this object's assetInfo dictionary at the current EditTarget. | |
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. | |
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. | |
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. | |
USD_API std::string | GetDocumentation () const |
Return this object's documentation (metadata). | |
USD_API bool | SetDocumentation (const std::string &doc) const |
Sets this object's documentation (metadata). Returns true on success. | |
USD_API bool | ClearDocumentation () const |
Clears this object's documentation (metadata) in the current EditTarget (only). | |
USD_API bool | HasAuthoredDocumentation () const |
Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful value for documentation. | |
USD_API std::string | GetDisplayName () const |
Return this object's display name (metadata). | |
USD_API bool | SetDisplayName (const std::string &name) const |
Sets this object's display name (metadata). | |
USD_API bool | ClearDisplayName () const |
Clears this object's display name (metadata) in the current EditTarget (only). | |
USD_API bool | HasAuthoredDisplayName () const |
Returns true if displayName was explicitly authored and GetMetadata() will return a meaningful value for displayName. | |
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. | |
bool | operator!= (const UsdObject &lhs, const UsdObject &rhs) |
Inequality comparison. | |
bool | operator< (const UsdObject &lhs, const UsdObject &rhs) |
Less-than operator. | |
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. | |
operator bool () const | |
Returns true if this object is valid, false otherwise. | |
USD_API UsdStageWeakPtr | GetStage () const |
Return the stage that owns the object, and to whose state and lifetime this object's validity is tied. | |
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. | |
const SdfPath & | GetPrimPath () const |
Return this object's path if this object is a prim, otherwise this object's nearest owning prim's path. | |
UsdPrim | GetPrim () const |
Return this object if it is a prim, otherwise return this object's nearest owning prim. | |
const TfToken & | GetName () const |
Return the full name of this object, i.e. | |
template<class T > | |
T | As () const |
Convert this UsdObject to another object type T if possible. | |
template<class T > | |
bool | Is () const |
Return true if this object is convertible to T . | |
USD_API std::string | GetDescription () const |
Return a string that provides a brief summary description of the object. | |
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.
|
inline |
|
inlineprotected |
|
inline |
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 ClearDisplayName | ( | ) | const |
Clears this object's display name (metadata) in the current EditTarget (only).
Returns true on success.
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.
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.
USD_API UsdMetadataValueMap GetAllAuthoredMetadata | ( | ) | const |
Resolve and return all user-authored metadata on this object, sorted lexicographically.
USD_API UsdMetadataValueMap GetAllMetadata | ( | ) | const |
Resolve and return all metadata (including both authored and fallback values) on this object, sorted lexicographically.
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.
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.
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 GetDisplayName | ( | ) | const |
Return this object's display name (metadata).
This returns the empty string if no display name has been set.
USD_API std::string GetDocumentation | ( | ) | const |
Return this object's documentation (metadata).
This returns the empty string if no documentation has been set.
|
inline |
Resolve the requested metadatum named key
into value
, returning true on success.
key
was not resolvable, or if value's
type T
differed from that of the resolved metadatum.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.
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).
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.
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.
|
inline |
|
inline |
|
inline |
|
inline |
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 HasAuthoredDisplayName | ( | ) | const |
Returns true if displayName was explicitly authored and GetMetadata() will return a meaningful value for displayName.
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.
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
.
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.
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
.
|
inline |
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.
|
inline |
|
inlineexplicit |
USD_API void SetAssetInfo | ( | const VtDictionary & | customData | ) | const |
Author this object's assetInfo dictionary to assetInfo
at the current EditTarget.
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.
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 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 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.
|
inline |
Set metadatum key's
value to value
.
value's
type does not match the schema type for key
.This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
|
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.
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.
|
friend |