Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
UsdAttribute Class Reference

Scenegraph object for authoring and retrieving numeric, string, and array valued data, sampled over time, or animated by a spline. 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 or splines (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. Please refer to GfColorSpaceNames for a list of built in color space token values.

For color or texture attributes that don't have an authored 'colorSpace' value, the fallback color space may be authored on the owning prim, and determined using the UsdColorSpaceAPI applied schema.

Standard color space names

USD_API TfToken GetColorSpace () const
 Gets the color space in which the attribute is authored if it has been explicitly set.
 
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.
 
Limits Dictionary

The limits dictionary contains minimum and maximum values for the attribute, organized by purpose into sub-dictionaries (see, e.g., UsdAttribute::GetSoftLimits() and UsdAttribute::GetHardLimits()).

Each sub-dictionary can store a minimum and maximum value for a different purpose (encoded under the UsdLimitsKeys->Minimum and UsdLimitsKeys->Maximum keys, respectively). For example the "soft" sub-dictionary is for limits which usually hold but can be exceeded as necessary.

Limits sub-dictionaries may store additional related values as well (see UsdAttributeLimits::Set()).

For example, a limits dictionary might look like the following:

def "MyPrim"
{
int attr = 7 (
limits = {
dictionary soft = {
int minimum = 5
int maximum = 10
bool customKey = 1
}
dictionary hard = {
int minimum = 0
int maximum = 15
}
dictionary customLimits = {
int maximum = 25
}
}
)
}

UsdAttribute's value authoring API does not enforce limits constraints, but authored values that lie outside the hard limits will trigger validation errors.

USD_API VtDictionary GetLimits () const
 Return the composed limits dictionary for the attribute.
 
USD_API bool SetLimits (const VtDictionary &limits) const
 Set the limits dictionary for the attribute to limits, at the current edit target.
 
USD_API bool HasAuthoredLimits () const
 Return whether a limits dictionary is authored for the attribute.
 
USD_API bool ClearLimits () const
 Clear the authored limits dictionary for the attribute, at the current edit target.
 
USD_API UsdAttributeLimits GetSoftLimits () const
 Return a UsdAttributeLimits object configured to edit the attribute's soft limits sub-dictionary.
 
USD_API UsdAttributeLimits GetHardLimits () const
 Return a UsdAttributeLimits object configured to edit the attribute's hard limits sub-dictionary.
 
USD_API UsdAttributeLimits GetLimits (const TfToken &key) const
 Return a UsdAttributeLimits object configured to edit the attribute's limits sub-dictionary given by key.
 
Array Size Constraint

For array-valued attributes, the array size constraint value encodes information about the expected number of elements and the tuple-length (i.e., column count):

  • If the value is 0 (the fallback), the array is dynamic and its size is unrestricted.
  • If the value is greater than 0, it indicates the exact, fixed size of the array.
  • If the value is less than 0, its absolute value is the array's tuple-length. The array's size is unrestricted, but must be a multiple of this tuple-length.

UsdAttribute's value authoring API does not enforce these constraints, but violating them will trigger validation errors.

USD_API int64_t GetArraySizeConstraint () const
 Return the array size constraint value for this attribute.
 
USD_API bool SetArraySizeConstraint (int64_t constraint) const
 Set the array size constraint value for this attribute.
 
USD_API bool HasAuthoredArraySizeConstraint () const
 Return whether an array size constraint value is authored on this attribute.
 
USD_API bool ClearArraySizeConstraint () const
 Clear the authored array size constraint value for this attribute at the current edit target.
 
- 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 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.
 

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
 Returns true if this attribute has a spline as the strongest value source.
 
USD_API TsSpline GetSpline () const
 Returns a copy of the resolved spline if the spline is the strongest value source.
 
USD_API bool SetSpline (const TsSpline &spline)
 Set the spline using the current edit target.
 
USD_API bool Clear () const
 Clears the authored default value, all time samples and spline 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 or spline on an attribute and author a block default value.
 
USD_API void BlockAnimation () const
 Remove any timeSamples or spline on an attribute and authors an AnimationBlock 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, or animated by a spline.

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, and 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"))){
...
}
TfToken
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:71
UsdAttribute
Scenegraph object for authoring and retrieving numeric, string, and array valued data,...
Definition: attribute.h:183

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.

Note that for attributes with spline value sources, the interpolation behavior is determined by the spline itself, and the interpolation type set on the stage is ignored.

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.

Attribute Animation Blocking

In addition to blocking all authored values, one can block only the animation (time samples and spline) on an attribute in the intermediate layers, allowing default values from the weaker layers to shine through.

One blocks an attribute's animation using UsdAttribute::BlockAnimation(),

Attributes of type SdfAssetPath and UsdAttribute::Get()

If an attribute's value type is SdfAssetPath or SdfAssetPathArray, Get() does extra work to perform variable expression evaluation and compute resolved asset paths. The layer that has the strongest value opinion is used as the anchor for "relative" asset paths. The unresolved results are available through SdfAssetPath::GetAssetPath. The fully resolved path (including any substitutions) can be retrieved with SdfAssetPath::GetResolvedPath. The authored or evaluated paths may be explicitly retrieved through SdfAssetPath::GetAuthoredPath and SdfAssetPath::GetEvaluatedPath respectively.

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

Array Size Constraint

For array-valued attributes, the value returned by GetArraySizeConstraint() encodes information about the expected number of elements as well as the tuple-length (i.e., column count). See Array Size Constraint for details of the encoding.

Definition at line 183 of file attribute.h.

Constructor & Destructor Documentation

◆ UsdAttribute()

UsdAttribute ( )
inline

Construct an invalid attribute.

Definition at line 186 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 or spline 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.

◆ BlockAnimation()

USD_API void BlockAnimation ( ) const

Remove any timeSamples or spline on an attribute and authors an AnimationBlock default value.

This causes the attribute to resolve as if there were no authored animation (time samples or spline) opinions but still allows default values shine through.

See Attribute Animation Blocking for more information.

◆ Clear()

USD_API bool Clear ( ) const

Clears the authored default value, all time samples and spline 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.

◆ ClearArraySizeConstraint()

USD_API bool ClearArraySizeConstraint ( ) const

Clear the authored array size constraint value for this attribute at the current edit target.

◆ 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.

Issue a coding error if time is a pre-time, which is only used to for querying for values at the limit when the time is approached from the left.

◆ 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()).

◆ ClearLimits()

USD_API bool ClearLimits ( ) const

Clear the authored limits dictionary for the attribute, at the current edit target.

Note that since this field is dictionary-valued, clearing it at the current edit target will not necessarily result in clearing the entire composed value.

◆ 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.

An attribute's value may be discontinuous at time samples. This happens when the stage is in held interpolation mode or when the sample values are not interpolatable. To obtain the attribute's value immediately before a given time sample, use UsdTimeCode::PreTime(time). This evaluates the limit of the attribute's value as time approaches the given time from the left.

For example, if a string-valued attribute has time samples {1.0: "foo", 2.0: "bar"}, calling Get() with UsdTimeCode(2.0) returns "bar", whereas calling Get() with UsdTimeCode::PreTime(2.0) returns "foo". However, if the attribute's values are interpolatable, such as {1.0: 3.0, 2.0: 4.0}, then calling Get() with UsdTimeCode(2.0)
and UsdTimeCode::PreTime(2.0) will both return 4.0, since the value is continuous at time=2.0.

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().

Value resolution first needs to determine the source of the strongest value opinion for this attribute at the requested UsdTimeCode time. But often (i.e. unless the attribute is affected by Value Clips) the source of the resolved value does not vary over time. UsdAttributeQuery finds the source opinion and saves it so that repeated calls to UsdAttributeQuery::Get() avoid redundant work.

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 468 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.

◆ GetArraySizeConstraint()

USD_API int64_t GetArraySizeConstraint ( ) const

Return the array size constraint value for this attribute.

◆ 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 if it has been explicitly set.

If the color space is not authored, any color space set on the attribute's prim definiton will be returned. Use UsdColorSpaceAPI in order to compute the color space taking into account any inherited color spaces.

See also
SetColorSpace() Standard color space names Usd Prim Color Space 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.

◆ GetHardLimits()

USD_API UsdAttributeLimits GetHardLimits ( ) const

Return a UsdAttributeLimits object configured to edit the attribute's hard limits sub-dictionary.

Hard limits are intended to provide a strict range that the attribute's value is expected to conform to.

UsdAttribute's value authoring API does not enforce hard limits, but an authored value that lies outside the hard limits will trigger a validation error.

See also
GetSoftLimits()

◆ GetLimits() [1/2]

USD_API VtDictionary GetLimits ( ) const

Return the composed limits dictionary for the attribute.

See also
GetSoftLimits()(), GetHardLimits()

◆ GetLimits() [2/2]

USD_API UsdAttributeLimits GetLimits ( const TfToken &  key) const

Return a UsdAttributeLimits object configured to edit the attribute's limits sub-dictionary given by key.

Custom limits values are for use by clients for their own specific purposes. UsdAttribute's value API does not enforce them.

See also
GetSoftLimits(), GetHardLimits()

◆ 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.

◆ GetSoftLimits()

USD_API UsdAttributeLimits GetSoftLimits ( ) const

Return a UsdAttributeLimits object configured to edit the attribute's soft limits sub-dictionary.

Soft limits are intended to provide a value range that is typical or useful for most purposes, but which may be exceeded as necessary.

UsdAttribute's value authoring API does not enforce soft limits.

See also
GetHardLimits()

◆ GetSpline()

USD_API TsSpline GetSpline ( ) const

Returns a copy of the resolved spline if the spline is the strongest value source.

If the strongest opinion is not a spline, returns an empty spline.

◆ 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 or splines (SdfVariabilityVarying), or only a single default value (SdfVariabilityUniform).

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

◆ HasAuthoredArraySizeConstraint()

USD_API bool HasAuthoredArraySizeConstraint ( ) const

Return whether an array size constraint value is authored on this attribute.

◆ 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.

◆ HasAuthoredLimits()

USD_API bool HasAuthoredLimits ( ) const

Return whether a limits dictionary is authored for the attribute.

◆ 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

Returns true if this attribute has a spline as the strongest value source.

◆ 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, or if the time is pre-time, which is only used to for querying for values at the limit when the time is approached from the left.

Definition at line 511 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.

◆ SetArraySizeConstraint()

USD_API bool SetArraySizeConstraint ( int64_t  constraint) const

Set the array size constraint value for this attribute.

◆ SetColorSpace()

USD_API void SetColorSpace ( const TfToken &  colorSpace) const

Sets the color space of the attribute to colorSpace.

Parameters
colorSpaceThe target color space for this attribute.

Usd Prim Color Space API provides methods to compute an attribute's resolved color, considering any inherited colorspaces. Standard color space names are listed in GfColorSpaceNames.

See also
GetColorSpace()

◆ 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.

◆ SetLimits()

USD_API bool SetLimits ( const VtDictionary &  limits) const

Set the limits dictionary for the attribute to limits, at the current edit target.

Return true on success.

Limits values must be nested inside sub-dictionaries, and the types of encoded minimum and maximum values must match the value type of the attribute.

Note that since this field is dictionary-valued, its composed value will be the combination of all its entries as specified across all relevant opinions. Overrides occur per-entry rather than the dictionary as a whole.

See also
GetSoftLimits(), GetHardLimits() for more convenient validation, editing, and look-up API

◆ SetSpline()

USD_API bool SetSpline ( const TsSpline &  spline)

Set the spline using the current edit target.

◆ 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 checks if the attribute either has more than 1 time samples or is spline valued. Which is more efficient than actually counting the time samples or evaluating the spline, both of which are potentially expensive operations.

Friends And Related Function Documentation

◆ UsdAttributeQuery

friend class UsdAttributeQuery
friend

Definition at line 876 of file attribute.h.

◆ UsdObject

friend class UsdObject
friend

Definition at line 877 of file attribute.h.

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 878 of file attribute.h.

◆ UsdPrim_AttrConnectionFinder

friend struct UsdPrim_AttrConnectionFinder
friend

Definition at line 881 of file attribute.h.

◆ UsdSchemaBase

friend class UsdSchemaBase
friend

Definition at line 879 of file attribute.h.

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