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

#include <attributeQuery.h>

Public Member Functions

USD_API UsdAttributeQuery ()
 Construct an invalid query object. More...
 
USD_API UsdAttributeQuery (const UsdAttributeQuery &other)
 Copy constructor. More...
 
USD_API UsdAttributeQuery (UsdAttributeQuery &&other)=default
 Move constructor. More...
 
USD_API UsdAttributeQuery (const UsdAttribute &attr)
 Construct a new query for the attribute attr. More...
 
USD_API UsdAttributeQuery (const UsdPrim &prim, const TfToken &attrName)
 
USD_API UsdAttributeQuery (const UsdAttribute &attr, const UsdResolveTarget &resolveTarget)
 
Query information
USD_API const UsdAttributeGetAttribute () const
 Return the attribute associated with this query. More...
 
bool IsValid () const
 
 operator bool () const
 Returns true if the query object is valid, false otherwise. More...
 
USD_API UsdAttributeQueryoperator= (const UsdAttributeQuery &other)
 Copy assignment. More...
 
USD_API UsdAttributeQueryoperator= (UsdAttributeQuery &&other)=default
 Move assignment. More...
 

Static Public Member Functions

static USD_API std::vector
< UsdAttributeQuery
CreateQueries (const UsdPrim &prim, const TfTokenVector &attrNames)
 

Value & Time-Sample Accessors

template<typename T >
bool Get (T *value, UsdTimeCode time=UsdTimeCode::Default()) const
 
USD_API bool Get (VtValue *value, UsdTimeCode time=UsdTimeCode::Default()) const
 
USD_API bool GetTimeSamples (std::vector< double > *times) const
 
USD_API bool GetTimeSamplesInInterval (const GfInterval &interval, std::vector< double > *times) const
 
USD_API size_t GetNumTimeSamples () const
 
USD_API bool GetBracketingTimeSamples (double desiredTime, double *lower, double *upper, bool *hasTimeSamples) const
 
USD_API bool HasValue () const
 
USD_API bool HasAuthoredValueOpinion () const
 
USD_API bool HasAuthoredValue () const
 
USD_API bool HasFallbackValue () const
 
USD_API bool ValueMightBeTimeVarying () const
 
static USD_API bool GetUnionedTimeSamples (const std::vector< UsdAttributeQuery > &attrQueries, std::vector< double > *times)
 
static USD_API bool GetUnionedTimeSamplesInInterval (const std::vector< UsdAttributeQuery > &attrQueries, const GfInterval &interval, std::vector< double > *times)
 

Detailed Description

Object for efficiently making repeated queries for attribute values.

Retrieving an attribute's value at a particular time requires determining the source of strongest opinion for that value. Often (i.e. unless the attribute is affected by Value Clips) this source does not vary over time. UsdAttributeQuery uses this fact to speed up repeated value queries by caching the source information for an attribute. It is safe to use a UsdAttributeQuery for any attribute - if the attribute is affected by Value Clips, the performance gain will just be less.

Resolve targets

An attribute query can also be constructed for an attribute along with a UsdResolveTarget. A resolve target allows value resolution to consider only a subrange of the prim stack instead of the entirety of it. All of the methods of an attribute query created with a resolve target will perform value resolution within that resolve target. This can be useful for finding the value of an attribute resolved up to a particular layer or for determining if a value authored on layer would be overridden by a stronger opinion.

Thread safety

This object provides the basic thread-safety guarantee. Multiple threads may call the value accessor functions simultaneously.

Invalidation

This object does not listen for change notification. If a consumer is holding on to a UsdAttributeQuery, it is their responsibility to dispose of it in response to a resync change to the associated attribute. Failing to do so may result in incorrect values or crashes due to dereferencing invalid objects.

Definition at line 76 of file attributeQuery.h.

Constructor & Destructor Documentation

USD_API UsdAttributeQuery::UsdAttributeQuery ( )

Construct an invalid query object.

USD_API UsdAttributeQuery::UsdAttributeQuery ( const UsdAttributeQuery other)

Copy constructor.

USD_API UsdAttributeQuery::UsdAttributeQuery ( UsdAttributeQuery &&  other)
default

Move constructor.

USD_API UsdAttributeQuery::UsdAttributeQuery ( const UsdAttribute attr)
explicit

Construct a new query for the attribute attr.

USD_API UsdAttributeQuery::UsdAttributeQuery ( const UsdPrim prim,
const TfToken attrName 
)

Construct a new query for the attribute named attrName under the prim prim.

USD_API UsdAttributeQuery::UsdAttributeQuery ( const UsdAttribute attr,
const UsdResolveTarget resolveTarget 
)

Construct a new query for the attribute attr with the given resolve target resolveTarget.

Note that a UsdResolveTarget is associated with a particular prim so only resolve targets for the attribute's owning prim are allowed.

Member Function Documentation

static USD_API std::vector<UsdAttributeQuery> UsdAttributeQuery::CreateQueries ( const UsdPrim prim,
const TfTokenVector attrNames 
)
static

Construct new queries for the attributes named in attrNames under the prim prim. The objects in the returned vector will line up 1-to-1 with attrNames.

template<typename T >
bool UsdAttributeQuery::Get ( T value,
UsdTimeCode  time = UsdTimeCode::Default() 
) const
inline

Perform value resolution to fetch the value of the attribute associated with this query at the requested UsdTimeCode time.

See Also
UsdAttribute::Get

Definition at line 159 of file attributeQuery.h.

USD_API bool UsdAttributeQuery::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 const UsdAttribute& UsdAttributeQuery::GetAttribute ( ) const

Return the attribute associated with this query.

USD_API bool UsdAttributeQuery::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.

See Also
UsdAttribute::GetBracketingTimeSamples
USD_API size_t UsdAttributeQuery::GetNumTimeSamples ( ) const

Returns the number of time samples that have been authored.

See Also
UsdAttribute::GetNumTimeSamples
USD_API bool UsdAttributeQuery::GetTimeSamples ( std::vector< double > *  times) const

Populates a vector with authored sample times. Returns false only on error. Behaves identically to UsdAttribute::GetTimeSamples()

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

Populates a vector with authored sample times in interval. Returns false only on an error.

Behaves identically to UsdAttribute::GetTimeSamplesInInterval()

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

Populates the given vector, times with the union of all the authored sample times on all of the given attribute-query objects, attrQueries.

Behaves identically to UsdAttribute::GetUnionedTimeSamples()

Returns
false if one or more attribute-queries in attrQueries are invalid or if there's an error fetching time-samples for any of the attribute-query objects.
See Also
UsdAttribute::GetUnionedTimeSamples
UsdAttributeQuery::GetUnionedTimeSamplesInInterval
static USD_API bool UsdAttributeQuery::GetUnionedTimeSamplesInInterval ( const std::vector< UsdAttributeQuery > &  attrQueries,
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 attribute-query objects, attrQueries.

Behaves identically to UsdAttribute::GetUnionedTimeSamplesInInterval()

Returns
false if one or more attribute-queries in attrQueries are invalid or if there's an error fetching time-samples for any of the attribute-query objects.
See Also
UsdAttribute::GetUnionedTimeSamplesInInterval
USD_API bool UsdAttributeQuery::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

See Also
UsdAttribute::HasAuthoredValue()
USD_API bool UsdAttributeQuery::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: query.GetAttribute().GetResolveInfo().HasAuthoredValueOpinion()

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

USD_API bool UsdAttributeQuery::HasFallbackValue ( ) const

Return true if the attribute associated with this query has a fallback value provided by a registered schema.

See Also
UsdAttribute::HasFallbackValue
USD_API bool UsdAttributeQuery::HasValue ( ) const

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

See Also
UsdAttribute::HasValue
bool UsdAttributeQuery::IsValid ( ) const
inline

Return true if this query is valid (i.e. it is associated with a valid attribute), false otherwise.

Definition at line 128 of file attributeQuery.h.

UsdAttributeQuery::operator bool ( ) const
inlineexplicit

Returns true if the query object is valid, false otherwise.

Definition at line 134 of file attributeQuery.h.

USD_API UsdAttributeQuery& UsdAttributeQuery::operator= ( const UsdAttributeQuery other)

Copy assignment.

USD_API UsdAttributeQuery& UsdAttributeQuery::operator= ( UsdAttributeQuery &&  other)
default

Move assignment.

USD_API bool UsdAttributeQuery::ValueMightBeTimeVarying ( ) const

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

See Also
UsdAttribute::ValueMightBeTimeVarying

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