This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdProperty Class Reference

Base class for UsdAttribute and UsdRelationship scenegraph objects. More...

#include <property.h>

+ Inheritance diagram for UsdProperty:

Public Member Functions

 UsdProperty ()
 Construct an invalid property.
 
Object and Namespace Accessors
USD_API SdfPropertySpecHandleVector GetPropertyStack (UsdTimeCode time=UsdTimeCode::Default()) const
 Returns a strength-ordered list of property specs that provide opinions for this property.
 
USD_API std::vector< std::pair< SdfPropertySpecHandle, SdfLayerOffset > > GetPropertyStackWithLayerOffsets (UsdTimeCode time=UsdTimeCode::Default()) const
 Returns a strength-ordered list of property specs that provide opinions for this property paired with the cumulative layer offset from the stage's root layer to the layer containing the property spec.
 
USD_API TfToken GetBaseName () const
 Return this property's name with all namespace prefixes removed, i.e.
 
USD_API TfToken GetNamespace () const
 Return this property's complete namespace prefix.
 
USD_API std::vector< std::string > SplitName () const
 Return this property's name elements including namespaces and its base name as the final element.
 
Core Metadata
USD_API std::string GetDisplayGroup () const
 Return this property's display group (metadata).
 
USD_API bool SetDisplayGroup (const std::string &displayGroup) const
 Sets this property's display group (metadata).
 
USD_API bool ClearDisplayGroup () const
 Clears this property's display group (metadata) in the current EditTarget (only).
 
USD_API bool HasAuthoredDisplayGroup () const
 Returns true if displayGroup was explicitly authored and GetMetadata() will return a meaningful value for displayGroup.
 
USD_API std::vector< std::string > GetNestedDisplayGroups () const
 Return this property's displayGroup as a sequence of groups to be nested, or an empty vector if displayGroup is empty or not authored.
 
USD_API bool SetNestedDisplayGroups (const std::vector< std::string > &nestedGroups) const
 Sets this property's display group (metadata) to the nested sequence.
 
USD_API bool IsCustom () const
 Return true if this is a custom property (i.e., not part of a prim schema).
 
USD_API bool SetCustom (bool isCustom) const
 Set the value for custom at the current EditTarget, return true on success, false if the value can not be written.
 
Existence and Validity
USD_API bool IsDefined () const
 Return true if this is a builtin property or if the strongest authored SdfPropertySpec for this property's path matches this property's dynamic type.
 
USD_API bool IsAuthored () const
 Return true if there are any authored opinions for this property in any layer that contributes to this stage, false otherwise.
 
USD_API bool IsAuthoredAt (const class UsdEditTarget &editTarget) const
 Return true if there is an SdfPropertySpec authored for this property at the given editTarget, otherwise return false.
 
- Public Member Functions inherited from UsdObject
 UsdObject ()
 Default constructor produces an invalid object.
 
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.
 
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.
 
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 SdfPathGetPrimPath () 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 TfTokenGetName () const
 Return the full name of this object, i.e.
 
template<class 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.
 

Flattening

class UsdAttribute
 
class UsdObject
 
class UsdPrim
 
class UsdRelationship
 
USD_API UsdProperty FlattenTo (const UsdPrim &parent) const
 Flattens this property to a property spec with the same name beneath the given parent prim in the edit target of its owning stage.
 
USD_API UsdProperty FlattenTo (const UsdPrim &parent, const TfToken &propName) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec with the given propName beneath the given parent prim in the edit target of its owning stage.
 
USD_API UsdProperty FlattenTo (const UsdProperty &property) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec for the given property in the edit target of its owning prim's stage.
 
template<class Derived >
 UsdProperty (_Null< Derived >)
 
bool _GetTargets (SdfSpecType specType, SdfPathVector *out, bool *foundErrors=nullptr) const
 

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

Base class for UsdAttribute and UsdRelationship scenegraph objects.

UsdProperty has a bool conversion operator that validates that the property IsDefined() and thus valid for querying and authoring values and metadata. This is a fairly expensive query that we do not cache, so if client code retains UsdProperty objects it should manage its object validity closely for performance. An ideal pattern is to listen for UsdNotice::StageContentsChanged notifications, and revalidate/refetch retained UsdObjects only then and otherwise use them without validity checking.

Definition at line 38 of file property.h.

Constructor & Destructor Documentation

◆ UsdProperty() [1/2]

UsdProperty ( )
inline

Construct an invalid property.

Definition at line 41 of file property.h.

◆ UsdProperty() [2/2]

UsdProperty ( _Null< Derived >  )
inlineprotected

Definition at line 259 of file property.h.

Member Function Documentation

◆ ClearDisplayGroup()

USD_API bool ClearDisplayGroup ( ) const

Clears this property's display group (metadata) in the current EditTarget (only).

Returns true on success.

◆ FlattenTo() [1/3]

USD_API UsdProperty FlattenTo ( const UsdPrim parent) const

Flattens this property to a property spec with the same name beneath the given parent prim in the edit target of its owning stage.

The parent prim may belong to a different stage than this property's owning stage.

Flattening authors all authored resolved values and metadata for this property into the destination property spec. If this property is a builtin property, fallback values and metadata will also be authored if the destination property has a different fallback value or no fallback value, or if the destination property has an authored value that overrides its fallback.

Attribute connections and relationship targets that target an object beneath this property's owning prim will be remapped to target objects beneath the destination parent prim.

If the destination spec already exists, it will be overwritten.

See also
UsdStage::Flatten

◆ FlattenTo() [2/3]

USD_API UsdProperty FlattenTo ( const UsdPrim parent,
const TfToken propName 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec with the given propName beneath the given parent prim in the edit target of its owning stage.

The parent prim may belong to a different stage than this property's owning stage.

◆ FlattenTo() [3/3]

USD_API UsdProperty FlattenTo ( const UsdProperty property) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec for the given property in the edit target of its owning prim's stage.

The property owning prim may belong to a different stage than this property's owning stage.

◆ GetBaseName()

USD_API TfToken GetBaseName ( ) const

Return this property's name with all namespace prefixes removed, i.e.

the last component of the return value of GetName()

This is generally the property's "client name"; property namespaces are often used to group related properties together. The namespace prefixes the property name but many consumers will care only about un-namespaced name, i.e. its BaseName. For more information, see Names, Namespace Ordering, and Property Namespaces

◆ GetDisplayGroup()

USD_API std::string GetDisplayGroup ( ) const

Return this property's display group (metadata).

This returns the empty token if no display group has been set.

See also
SetDisplayGroup()

◆ GetNamespace()

USD_API TfToken GetNamespace ( ) const

Return this property's complete namespace prefix.

Return the empty token if this property has no namespaces.

This is the complement of GetBaseName(), although it does not contain a trailing namespace delimiter

◆ GetNestedDisplayGroups()

USD_API std::vector< std::string > GetNestedDisplayGroups ( ) const

Return this property's displayGroup as a sequence of groups to be nested, or an empty vector if displayGroup is empty or not authored.

◆ GetPropertyStack()

USD_API SdfPropertySpecHandleVector GetPropertyStack ( UsdTimeCode  time = UsdTimeCode::Default()) const

Returns a strength-ordered list of property specs that provide opinions for this property.

If time is UsdTimeCode::Default(), or this property is a UsdRelationship (which are never affected by clips), we will not consider value clips for opinions. For any other time, for a UsdAttribute, clips whose samples may contribute an opinion will be included. These specs are ordered from strongest to weakest opinion, although if time requires interpolation between two adjacent clips, both clips will appear, sequentially.

Note
The results returned by this method are meant for debugging and diagnostic purposes. It is not advisable to retain a PropertyStack for the purposes of expedited value resolution for properties, since the makeup of an attribute's PropertyStack may itself be time-varying. To expedite repeated value resolution of attributes, you should instead retain a UsdAttributeQuery .
See also
UsdClipsAPI

◆ GetPropertyStackWithLayerOffsets()

USD_API std::vector< std::pair< SdfPropertySpecHandle, SdfLayerOffset > > GetPropertyStackWithLayerOffsets ( UsdTimeCode  time = UsdTimeCode::Default()) const

Returns a strength-ordered list of property specs that provide opinions for this property paired with the cumulative layer offset from the stage's root layer to the layer containing the property spec.

This behaves exactly the same as UsdProperty::GetPropertyStack with the addition of providing the cumulative layer offset of each spec's layer.

Note
The results returned by this method are meant for debugging and diagnostic purposes. It is not advisable to retain a PropertyStack for the purposes of expedited value resolution for properties, since the makeup of an attribute's PropertyStack may itself be time-varying. To expedite repeated value resolution of attributes, you should instead retain a UsdAttributeQuery .

◆ HasAuthoredDisplayGroup()

USD_API bool HasAuthoredDisplayGroup ( ) const

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


◆ IsAuthored()

USD_API bool IsAuthored ( ) const

Return true if there are any authored opinions for this property in any layer that contributes to this stage, false otherwise.

◆ IsAuthoredAt()

USD_API bool IsAuthoredAt ( const class UsdEditTarget editTarget) const

Return true if there is an SdfPropertySpec authored for this property at the given editTarget, otherwise return false.

Note that this method does not do partial composition. It does not consider whether authored scene description exists at editTarget or weaker, only exactly at the given editTarget.

◆ IsCustom()

USD_API bool IsCustom ( ) const

Return true if this is a custom property (i.e., not part of a prim schema).

The 'custom' modifier in USD serves the same function as Alembic's 'userProperties', which is to say as a categorization for ad hoc client data not formalized into any schema, and therefore not carrying an expectation of specific processing by consuming applications.

◆ IsDefined()

USD_API bool IsDefined ( ) const

Return true if this is a builtin property or if the strongest authored SdfPropertySpec for this property's path matches this property's dynamic type.

That is, SdfRelationshipSpec in case this is a UsdRelationship, and SdfAttributeSpec in case this is a UsdAttribute. Return false if this property's prim has expired.

For attributes, a true return does not imply that this attribute possesses a value, only that has been declared, is of a certain type and variability, and that it is safe to use to query and author values and metadata.

◆ SetCustom()

USD_API bool SetCustom ( bool  isCustom) const

Set the value for custom at the current EditTarget, return true on success, false if the value can not be written.

Note that this value should not be changed as it is typically either automatically authored or provided by a property definition. This method is provided primarily for fixing invalid scene description.

◆ SetDisplayGroup()

USD_API bool SetDisplayGroup ( const std::string &  displayGroup) const

Sets this property's display group (metadata).

Returns true on success.

DisplayGroup provides UI hinting for grouping related properties together for display. We define a convention for specifying nesting of groups by recognizing the property namespace separator in displayGroup as denoting group-nesting.

See also
SetNestedDisplayGroups()

◆ SetNestedDisplayGroups()

USD_API bool SetNestedDisplayGroups ( const std::vector< std::string > &  nestedGroups) const

Sets this property's display group (metadata) to the nested sequence.


Returns true on success.

A displayGroup set with this method can still be retrieved with GetDisplayGroup(), with the namespace separator embedded in the result. If nestedGroups is empty, we author an empty string for displayGroup.

See also
SetDisplayGroup()

◆ SplitName()

USD_API std::vector< std::string > SplitName ( ) const

Return this property's name elements including namespaces and its base name as the final element.

Friends And Related Function Documentation

◆ UsdAttribute

friend class UsdAttribute
friend

Definition at line 268 of file property.h.

◆ UsdObject

friend class UsdObject
friend

Definition at line 269 of file property.h.

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 270 of file property.h.

◆ UsdRelationship

friend class UsdRelationship
friend

Definition at line 271 of file property.h.


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