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
UsdAttribute Class Reference

Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time. More...

#include <attribute.h>

+ Inheritance diagram for UsdAttribute:

Public Member Functions

 UsdAttribute ()
 Construct an invalid attribute.
 
Core Metadata
USD_API SdfVariability GetVariability () const
 An attribute's variability expresses whether it is intended to have time-samples (SdfVariabilityVarying), or only a single default value (SdfVariabilityUniform).
 
USD_API bool SetVariability (SdfVariability variability) const
 Set the value for variability at the current EditTarget, return true on success, false if the value can not be written.
 
USD_API SdfValueTypeName GetTypeName () const
 Return the "scene description" value type name for this attribute.
 
USD_API bool SetTypeName (const SdfValueTypeName &typeName) const
 Set the value for typeName at the current EditTarget, return true on success, false if the value can not be written.
 
USD_API TfToken GetRoleName () const
 Return the roleName for this attribute's typeName.
 
Querying and Editing Connections
USD_API bool AddConnection (const SdfPath &source, UsdListPosition position=UsdListPositionBackOfPrependList) const
 Adds source to the list of connections, in the position specified by position.
 
USD_API bool RemoveConnection (const SdfPath &source) const
 Removes target from the list of targets.
 
USD_API bool SetConnections (const SdfPathVector &sources) const
 Make the authoring layer's opinion of the connection list explicit, and set exactly to sources.
 
USD_API bool ClearConnections () const
 Remove all opinions about the connections list from the current edit target.
 
USD_API bool GetConnections (SdfPathVector *sources) const
 Compose this attribute's connections and fill sources with the result.
 
USD_API bool HasAuthoredConnections () const
 Return true if this attribute has any authored opinions regarding connections.
 
ColorSpace API

The color space in which a given color or texture valued attribute is authored is set as token-valued metadata 'colorSpace' on the attribute. For color or texture attributes that don't have an authored 'colorSpace' value, the fallback color-space is gleaned from whatever color management system is specified by UsdStage::GetColorManagementSystem().

USD_API TfToken GetColorSpace () const
 Gets the color space in which the attribute is authored.
 
USD_API void SetColorSpace (const TfToken &colorSpace) const
 Sets the color space of the attribute to colorSpace.
 
USD_API bool HasColorSpace () const
 Returns whether color-space is authored on the attribute.
 
USD_API bool ClearColorSpace () const
 Clears authored color-space value on the attribute.
 
- Public Member Functions inherited from UsdProperty
 UsdProperty ()
 Construct an invalid property.
 
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.
 
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.
 
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.
 
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.
 
- 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.
 

Friends

class UsdAttributeQuery
 
class UsdObject
 
class UsdPrim
 
class UsdSchemaBase
 
struct UsdPrim_AttrConnectionFinder
 

Value & Time-Sample Accessors

USD_API bool GetTimeSamples (std::vector< double > *times) const
 Populates a vector with authored sample times.
 
USD_API bool GetTimeSamplesInInterval (const GfInterval &interval, std::vector< double > *times) const
 Populates a vector with authored sample times in interval.
 
USD_API size_t GetNumTimeSamples () const
 Returns the number of time samples that have been authored.
 
USD_API bool GetBracketingTimeSamples (double desiredTime, double *lower, double *upper, bool *hasTimeSamples) const
 Populate lower and upper with the next greater and lesser value relative to the desiredTime.
 
USD_API bool HasValue () const
 Return true if this attribute has an authored default value, authored time samples or a fallback value provided by a registered schema.
 
USD_API bool HasAuthoredValueOpinion () const
 
USD_API bool HasAuthoredValue () const
 Return true if this attribute has either an authored default value or authored time samples.
 
USD_API bool HasFallbackValue () const
 Return true if this attribute has a fallback value provided by a registered schema.
 
USD_API bool ValueMightBeTimeVarying () const
 Return true if it is possible, but not certain, that this attribute's value changes over time, false otherwise.
 
template<typename T >
bool Get (T *value, UsdTimeCode time=UsdTimeCode::Default()) const
 Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time, which defaults to default.
 
USD_API bool Get (VtValue *value, UsdTimeCode time=UsdTimeCode::Default()) 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, often not as efficient as typed access.
 
USD_API UsdResolveInfo GetResolveInfo (UsdTimeCode time) const
 Perform value resolution to determine the source of the resolved value of this attribute at the requested UsdTimeCode time.
 
USD_API UsdResolveInfo GetResolveInfo () const
 Perform value resolution to determine the source of the resolved value of this attribute at any non-default time.
 
template<typename T >
bool Set (const T &value, UsdTimeCode time=UsdTimeCode::Default()) const
 Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time, which defaults to default.
 
USD_API bool Set (const char *value, UsdTimeCode time=UsdTimeCode::Default()) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. As a convenience, we allow the setting of string value typed attributes via a C string value.
 
USD_API bool Set (const VtValue &value, UsdTimeCode time=UsdTimeCode::Default()) 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 HasSpline () const
 IN DEVELOPMENT.
 
USD_API TsSpline GetSpline () const
 IN DEVELOPMENT.
 
USD_API bool SetSpline (const TsSpline &spline)
 IN DEVELOPMENT.
 
USD_API bool Clear () const
 Clears the authored default value and all time samples for this attribute at the current EditTarget and returns true on success.
 
USD_API bool ClearAtTime (UsdTimeCode time) const
 Clear the authored value for this attribute at the given time, at the current EditTarget and return true on success.
 
USD_API bool ClearDefault () const
 Shorthand for ClearAtTime(UsdTimeCode::Default()).
 
USD_API void Block () const
 Remove all time samples on an attribute and author a block default value.
 
static USD_API bool GetUnionedTimeSamples (const std::vector< UsdAttribute > &attrs, std::vector< double > *times)
 Populates the given vector, times with the union of all the authored sample times on all of the given attributes, attrs.
 
static USD_API bool GetUnionedTimeSamplesInInterval (const std::vector< UsdAttribute > &attrs, const GfInterval &interval, std::vector< double > *times)
 Populates the given vector, times with the union of all the authored sample times in the GfInterval, interval on all of the given attributes, attrs.
 

Additional Inherited Members

- Static Public Member Functions inherited from UsdObject
static char GetNamespaceDelimiter ()
 
- Protected Member Functions inherited from UsdProperty
template<class Derived >
 UsdProperty (_Null< Derived >)
 
bool _GetTargets (SdfSpecType specType, SdfPathVector *out, bool *foundErrors=nullptr) const
 
- 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

Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time.

The allowed value types for UsdAttribute are dictated by the Sdf ("Scene Description Foundations") core's data model, which we summarize in Basic Datatypes for Scene Description Provided by Sdf .

Attribute Defining Qualities

In addition to its value type, an Attribute has two other defining qualities:

  • Custom Determines whether an attribute belongs to a schema (IsCustom() == false), or is a user-defined, custom attribute. schema attributes will always be defined on a prim of the schema type, ans may possess fallback values from the schema, whereas custom attributes must always first be authored in order to be defined. Note that custom is actually an aspect of UsdProperty, as UsdRelationship can also be custom or provided by a schema.

Attribute Creation and Existence

One can always create an attribute generically via UsdPrim::CreateAttribute(), which ensures that an attribute "is defined" in the current UsdEditTarget . In order to author any metadata or a default or timesample for an attribute, it must first be defined. It is sufficient that the attribute be defined in any one of the layers participating in the stage's current composition; for builtin attributes (those belonging to the owning prim's defining schema, i.e. the most specific subclass of UsdTypedSchema for which prim.IsA<schema>() will evaluate to true) there need be no authored scene description, because a definition is provided by the prim's schema definition.

Creating an attribute does not imply that the attribute has a value. More broadly, in the following code:

if (UsdAttribute attr = prim.GetAttribute(TfToken("myAttr"))){
...
}
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:160

The UsdAttribute passes the bool test, because it is defined; however, inside the clause, we have no guarantee that attr has a value.

Attribute Value Interpolation

UsdAttribute supports two interpolation behaviors when retrieving attribute values at times where no value is explicitly authored. The desired behavior may be specified via UsdStage::SetInterpolationType. That behavior will be used for all calls to UsdAttribute::Get.

The supported interpolation types are:

  • Held Attribute values are held constant between authored values. An attribute's value will be equal to the nearest preceding authored value. If there is no preceding authored value, the value will be equal to the nearest subsequent value.
  • Linear Attribute values are linearly interpolated between authored values.

Linear interpolation is only supported for certain data types. See USD_LINEAR_INTERPOLATION_TYPES for the list of these types. Types that do not support linear interpolation will use held interpolation instead.

Linear interpolation is done element-by-element for array, vector, and matrix data types. If linear interpolation is requested for two array values with different sizes, held interpolation will be used instead.

Attribute Value Blocking

While prims can effectively be removed from a scene by deactivating them, properties cannot. However, it is possible to block an attribute's value, thus making the attribute behave as if it has a definition (and possibly metadata), but no authored value.

One blocks an attribute using UsdAttribute::Block(), which will block the attribute in the stage's current UsdEditTarget, by authoring an SdfValueBlock in the attribute's default, and only values authored in weaker layers than the editTarget will be blocked. If the value block is the strongest authored opinion for the attribute, the HasAuthoredValue() method will return false, and the HasValue() and Get() methods will only return true if the attribute possesses a fallback value from the prim's schema. "Unblocking" a blocked attribute is as simple as setting a default or timeSample value for the attribute in the same or stronger layer.

Time-varying Blocks

The semantics of Value Clips necessitate the ability to selectively block an attribute's value for only some intervals in its authored range of samples. One can block an attribute's value at time t by calling attr.Set(SdfValueBlock, t) When an attribute is thusly "partially blocked", UsdAttribute::Get() will succeed only for those time intervals whose left/earlier bracketing timeSample is not SdfValueBlock.

Due to this time-varying potential of value blocking, it may be the case that an attribute's HasAuthoredValue() and HasValue() methods both return true (because they do not and cannot consider time-varying blocks), but Get() may yet return false over some intervals.

Attributes of type SdfAssetPath and UsdAttribute::Get()

If an attribute's value type is SdfAssetPath or SdfAssetPathArray, Get() performs extra work to compute the resolved asset paths, using the layer that has the strongest value opinion as the anchor for "relative" asset paths. Both the unresolved and resolved results are available through SdfAssetPath::GetAssetPath() and SdfAssetPath::GetResolvedPath(), respectively.

Clients that call Get() on many asset-path-valued attributes may wish to employ an ArResolverScopedCache to improve asset path resolution performance.

Definition at line 160 of file attribute.h.

Constructor & Destructor Documentation

◆ UsdAttribute()

UsdAttribute ( )
inline

Construct an invalid attribute.

Definition at line 163 of file attribute.h.

Member Function Documentation

◆ AddConnection()

USD_API bool AddConnection ( const SdfPath source,
UsdListPosition  position = UsdListPositionBackOfPrependList 
) const

Adds source to the list of connections, in the position specified by position.

Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.

What data this actually authors depends on what data is currently authored in the authoring layer, with respect to list-editing semantics, which we will document soon

◆ Block()

USD_API void Block ( ) const

Remove all time samples on an attribute and author a block default value.

This causes the attribute to resolve as if there were no authored value opinions in weaker layers.

See Attribute Value Blocking for more information, including information on time-varying blocking.

◆ Clear()

USD_API bool Clear ( ) const

Clears the authored default value and all time samples for this attribute at the current EditTarget and returns true on success.

Calling clear when either no value is authored or no spec is present, is a silent no-op returning true.

This method does not affect any other data authored on this attribute.

◆ ClearAtTime()

USD_API bool ClearAtTime ( UsdTimeCode  time) const

Clear the authored value for this attribute at the given time, at the current EditTarget and return true on success.

UsdTimeCode::Default() can be used to clear the default value.

Calling clear when either no value is authored or no spec is present, is a silent no-op returning true.

◆ ClearColorSpace()

USD_API bool ClearColorSpace ( ) const

Clears authored color-space value on the attribute.

See also
SetColorSpace()

◆ ClearConnections()

USD_API bool ClearConnections ( ) const

Remove all opinions about the connections list from the current edit target.

◆ ClearDefault()

USD_API bool ClearDefault ( ) const

Shorthand for ClearAtTime(UsdTimeCode::Default()).

◆ Get() [1/2]

bool Get ( T *  value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const
inline

Perform value resolution to fetch the value of this attribute at the requested UsdTimeCode time, which defaults to default.

If no value is authored at time but values are authored at other times, this function will return an interpolated value based on the stage's interpolation type. See Attribute Value Interpolation.

If no value is authored and no fallback value is provided by the schema for this attribute, this function will return false. If the consumer's use-case requires a default value, the consumer will need to provide one, possibly using GetTypeName().GetDefaultValue().

This templated accessor is designed for high performance data-streaming applications, allowing one to fetch data into the same container repeatedly, avoiding memory allocations when possible (VtArray containers will be resized as necessary to conform to the size of data being read).

This template is only instantiated for the valid scene description value types and their corresponding VtArray containers. See Basic Datatypes for Scene Description Provided by Sdf for the complete list of types.

Values are retrieved without regard to this attribute's variability. For example, a uniform attribute may retrieve time sample values if any are authored. However, the USD_VALIDATE_VARIABILITY TF_DEBUG code will cause debug information to be output if values that are inconsistent with this attribute's variability are retrieved. See UsdAttribute::GetVariability for more details.

Returns
true if there was a value to be read, it was of the type T requested, and we read it successfully - false otherwise.

For more details, see TimeSamples, Defaults, and Value Resolution , and also Attributes of type SdfAssetPath and UsdAttribute::Get() for information on how to retrieve resolved asset paths from SdfAssetPath-valued attributes.

Definition at line 420 of file attribute.h.

◆ Get() [2/2]

USD_API bool Get ( VtValue value,
UsdTimeCode  time = UsdTimeCode::Default() 
) 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, often not as efficient as typed access.

◆ GetBracketingTimeSamples()

USD_API bool GetBracketingTimeSamples ( double  desiredTime,
double *  lower,
double *  upper,
bool *  hasTimeSamples 
) const

Populate lower and upper with the next greater and lesser value relative to the desiredTime.

Return false if no value exists or an error occurs, true if either a default value or timeSamples exist.

Use standard resolution semantics: if a stronger default value is authored over weaker time samples, the default value hides the underlying timeSamples.

1) If a sample exists at the desiredTime, set both upper and lower to desiredTime.

2) If samples exist surrounding, but not equal to the desiredTime, set lower and upper to the bracketing samples nearest to the desiredTime.

3) If the desiredTime is outside of the range of authored samples, clamp upper and lower to the nearest time sample.

4) If no samples exist, do not modify upper and lower and set hasTimeSamples to false.

In cases (1), (2) and (3), set hasTimeSamples to true.

All four cases above are considered to be successful, thus the return value will be true and no error message will be emitted.

◆ GetColorSpace()

USD_API TfToken GetColorSpace ( ) const

Gets the color space in which the attribute is authored.

See also
SetColorSpace() UsdStage Color Configuration API

◆ GetConnections()

USD_API bool GetConnections ( SdfPathVector *  sources) const

Compose this attribute's connections and fill sources with the result.

All preexisting elements in sources are lost.

Returns true if any connection path opinions have been authored and no composition errors were encountered, returns false otherwise. Note that authored opinions may include opinions that clear the connections and a return value of true does not necessarily indicate that sources will contain any connection paths.

See Relationship Targets and Attribute Connections for details on behavior when targets point to objects beneath instance prims.

The result is not cached, and thus recomputed on each query.

◆ GetNumTimeSamples()

USD_API size_t GetNumTimeSamples ( ) const

Returns the number of time samples that have been authored.

This method uses the standard resolution semantics, so if a stronger default value is authored over weaker time samples, the default value will hide the underlying timesamples.

Note
This function will query all value clips that may contribute time samples for this attribute, opening them if needed. This may be expensive, especially if many clips are involved.

◆ GetResolveInfo() [1/2]

USD_API UsdResolveInfo GetResolveInfo ( ) const

Perform value resolution to determine the source of the resolved value of this attribute at any non-default time.

Often (i.e. unless the attribute is affected by Value Clips) the source of the resolved value does not vary over time. See UsdAttributeQuery as an example that takes advantage of this quality of value resolution.

◆ GetResolveInfo() [2/2]

USD_API UsdResolveInfo GetResolveInfo ( UsdTimeCode  time) const

Perform value resolution to determine the source of the resolved value of this attribute at the requested UsdTimeCode time.

◆ GetRoleName()

USD_API TfToken GetRoleName ( ) const

Return the roleName for this attribute's typeName.

◆ GetSpline()

USD_API TsSpline GetSpline ( ) const

IN DEVELOPMENT.

◆ GetTimeSamples()

USD_API bool GetTimeSamples ( std::vector< double > *  times) const

Populates a vector with authored sample times.

Returns false only on error.

This method uses the standard resolution semantics, so if a stronger default value is authored over weaker time samples, the default value will hide the underlying timesamples.

Note
This function will query all value clips that may contribute time samples for this attribute, opening them if needed. This may be expensive, especially if many clips are involved.
Parameters
times- on return, will contain the sorted, ascending timeSample ordinates. Any data in times will be lost, as this method clears times.
See also
UsdAttribute::GetTimeSamplesInInterval

◆ GetTimeSamplesInInterval()

USD_API bool GetTimeSamplesInInterval ( const GfInterval interval,
std::vector< double > *  times 
) const

Populates a vector with authored sample times in interval.

Returns false only on an error.

Note
This function will only query the value clips that may contribute time samples for this attribute in the given interval, opening them if necessary.
Parameters
interval- the GfInterval on which to gather time samples.
times- on return, will contain the sorted, ascending timeSample ordinates. Any data in times will be lost, as this method clears times.
See also
UsdAttribute::GetTimeSamples

◆ GetTypeName()

USD_API SdfValueTypeName GetTypeName ( ) const

Return the "scene description" value type name for this attribute.

◆ GetUnionedTimeSamples()

static USD_API bool GetUnionedTimeSamples ( const std::vector< UsdAttribute > &  attrs,
std::vector< double > *  times 
)
static

Populates the given vector, times with the union of all the authored sample times on all of the given attributes, attrs.

Note
This function will query all value clips that may contribute time samples for the attributes in attrs, opening them if needed. This may be expensive, especially if many clips are involved.

The accumulated sample times will be in sorted (increasing) order and will not contain any duplicates.

This clears any existing values in the times vector before accumulating sample times of the given attributes.

Returns
false if any of the attributes in attr are invalid or if there's an error when fetching time-samples for any of the attributes.
See also
UsdAttribute::GetTimeSamples
UsdAttribute::GetUnionedTimeSamplesInInterval

◆ GetUnionedTimeSamplesInInterval()

static USD_API bool GetUnionedTimeSamplesInInterval ( const std::vector< UsdAttribute > &  attrs,
const GfInterval interval,
std::vector< double > *  times 
)
static

Populates the given vector, times with the union of all the authored sample times in the GfInterval, interval on all of the given attributes, attrs.

Note
This function will only query the value clips that may contribute time samples for the attributes in attrs, in the given interval, opening them if necessary.

The accumulated sample times will be in sorted (increasing) order and will not contain any duplicates.

This clears any existing values in the times vector before accumulating sample times of the given attributes.

Returns
false if any of the attributes in attr are invalid or if there's an error fetching time-samples for any of the attributes.
See also
UsdAttribute::GetTimeSamplesInInterval
UsdAttribute::GetUnionedTimeSamples

◆ GetVariability()

USD_API SdfVariability GetVariability ( ) const

An attribute's variability expresses whether it is intended to have time-samples (SdfVariabilityVarying), or only a single default value (SdfVariabilityUniform).

Variability is required meta-data of all attributes, and its fallback value is SdfVariabilityVarying.

◆ HasAuthoredConnections()

USD_API bool HasAuthoredConnections ( ) const

Return true if this attribute has any authored opinions regarding connections.

Note that this includes opinions that remove connections, so a true return does not necessarily indicate that this attribute has connections.

◆ HasAuthoredValue()

USD_API bool HasAuthoredValue ( ) const

Return true if this attribute has either an authored default value or authored time samples.

If the attribute has been blocked, then return false

◆ HasAuthoredValueOpinion()

USD_API bool HasAuthoredValueOpinion ( ) const
Deprecated:
This method is deprecated because it returns true even when an attribute is blocked. Please use HasAuthoredValue() instead. If you truly need to know whether the attribute has any authored value opinions, including blocks, you can make the following query: attr.GetResolveInfo().HasAuthoredValueOpinion()

Return true if this attribute has either an authored default value or authored time samples.

◆ HasColorSpace()

USD_API bool HasColorSpace ( ) const

Returns whether color-space is authored on the attribute.

See also
GetColorSpace()

◆ HasFallbackValue()

USD_API bool HasFallbackValue ( ) const

Return true if this attribute has a fallback value provided by a registered schema.

◆ HasSpline()

USD_API bool HasSpline ( ) const

IN DEVELOPMENT.

◆ HasValue()

USD_API bool HasValue ( ) const

Return true if this attribute has an authored default value, authored time samples or a fallback value provided by a registered schema.

If the attribute has been blocked, then return true if and only if it has a fallback value.

◆ RemoveConnection()

USD_API bool RemoveConnection ( const SdfPath source) const

Removes target from the list of targets.

Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.

◆ Set() [1/3]

USD_API bool Set ( const char *  value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. As a convenience, we allow the setting of string value typed attributes via a C string value.

◆ Set() [2/3]

bool Set ( const T &  value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const
inline

Set the value of this attribute in the current UsdEditTarget to value at UsdTimeCode time, which defaults to default.

Values are authored without regard to this attribute's variability. For example, time sample values may be authored on a uniform attribute. However, the USD_VALIDATE_VARIABILITY TF_DEBUG code will cause debug information to be output if values that are inconsistent with this attribute's variability are authored. See UsdAttribute::GetVariability for more details.

Returns
false and generate an error if type T does not match this attribute's defined scene description type exactly, or if there is no existing definition for the attribute.

Definition at line 461 of file attribute.h.

◆ Set() [3/3]

USD_API bool Set ( const VtValue value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const

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

◆ SetColorSpace()

USD_API void SetColorSpace ( const TfToken colorSpace) const

Sets the color space of the attribute to colorSpace.

See also
GetColorSpace() UsdStage Color Configuration API

◆ SetConnections()

USD_API bool SetConnections ( const SdfPathVector &  sources) const

Make the authoring layer's opinion of the connection list explicit, and set exactly to sources.

Issue an error if source identifies a prototype prim or an object descendant to a prototype prim. It is not valid to author connections to these objects.

If any path in sources is invalid, issue an error and return false.

◆ SetSpline()

USD_API bool SetSpline ( const TsSpline spline)

IN DEVELOPMENT.

◆ SetTypeName()

USD_API bool SetTypeName ( const SdfValueTypeName typeName) const

Set the value for typeName 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.

◆ SetVariability()

USD_API bool SetVariability ( SdfVariability  variability) const

Set the value for variability 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.

◆ ValueMightBeTimeVarying()

USD_API bool ValueMightBeTimeVarying ( ) const

Return true if it is possible, but not certain, that this attribute's value changes over time, false otherwise.

If this function returns false, it is certain that this attribute's value remains constant over time.

This function is equivalent to checking if GetNumTimeSamples() > 1, but may be more efficient since it does not actually need to get a full count of all time samples.

Friends And Related Function Documentation

◆ UsdAttributeQuery

friend class UsdAttributeQuery
friend

Definition at line 631 of file attribute.h.

◆ UsdObject

friend class UsdObject
friend

Definition at line 632 of file attribute.h.

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 633 of file attribute.h.

◆ UsdPrim_AttrConnectionFinder

friend struct UsdPrim_AttrConnectionFinder
friend

Definition at line 636 of file attribute.h.

◆ UsdSchemaBase

friend class UsdSchemaBase
friend

Definition at line 634 of file attribute.h.


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