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

Object for efficiently making repeated queries for attribute values. More...

#include <attributeQuery.h>

Public Member Functions

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

Static Public Member Functions

static USD_API std::vector< UsdAttributeQueryCreateQueries (const UsdPrim &prim, const TfTokenVector &attrNames)
 Construct new queries for the attributes named in attrNames under the prim prim.
 

Value & Time-Sample Accessors

template<typename T >
bool Get (T *value, UsdTimeCode time=UsdTimeCode::Default()) const
 Perform value resolution to fetch the value of the attribute associated with this query at the requested UsdTimeCode time.
 
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 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 the attribute associated with this query 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 the attribute associated with this query 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.
 
static USD_API bool GetUnionedTimeSamples (const std::vector< UsdAttributeQuery > &attrQueries, std::vector< double > *times)
 Populates the given vector, times with the union of all the authored sample times on all of the given attribute-query objects, attrQueries.
 
static USD_API bool GetUnionedTimeSamplesInInterval (const std::vector< UsdAttributeQuery > &attrQueries, 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 attribute-query objects, attrQueries.
 

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 59 of file attributeQuery.h.

Constructor & Destructor Documentation

◆ UsdAttributeQuery() [1/6]

USD_API UsdAttributeQuery ( )

Construct an invalid query object.

◆ UsdAttributeQuery() [2/6]

USD_API UsdAttributeQuery ( const UsdAttributeQuery other)

Copy constructor.

◆ UsdAttributeQuery() [3/6]

USD_API UsdAttributeQuery ( UsdAttributeQuery &&  other)
default

Move constructor.

◆ UsdAttributeQuery() [4/6]

USD_API UsdAttributeQuery ( const UsdAttribute attr)
explicit

Construct a new query for the attribute attr.

◆ UsdAttributeQuery() [5/6]

USD_API UsdAttributeQuery ( const UsdPrim prim,
const TfToken attrName 
)

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

◆ UsdAttributeQuery() [6/6]

USD_API 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

◆ CreateQueries()

static USD_API std::vector< 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.

◆ Get() [1/2]

bool 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 142 of file attributeQuery.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.

◆ GetAttribute()

USD_API const UsdAttribute & GetAttribute ( ) const

Return the attribute associated with this query.

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

See also
UsdAttribute::GetBracketingTimeSamples

◆ GetNumTimeSamples()

USD_API size_t GetNumTimeSamples ( ) const

Returns the number of time samples that have been authored.

See also
UsdAttribute::GetNumTimeSamples

◆ GetTimeSamples()

USD_API bool 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

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

Behaves identically to UsdAttribute::GetTimeSamplesInInterval()

◆ GetUnionedTimeSamples()

static USD_API bool 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

◆ GetUnionedTimeSamplesInInterval()

static USD_API bool 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

◆ 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

See also
UsdAttribute::HasAuthoredValue()

◆ 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: query.GetAttribute().GetResolveInfo().HasAuthoredValueOpinion()

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

◆ HasFallbackValue()

USD_API bool HasFallbackValue ( ) const

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

See also
UsdAttribute::HasFallbackValue

◆ HasValue()

USD_API bool 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

◆ IsValid()

bool IsValid ( ) const
inline

Return true if this query is valid (i.e.

it is associated with a valid attribute), false otherwise.

Definition at line 111 of file attributeQuery.h.

◆ operator bool()

operator bool ( ) const
inlineexplicit

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

Definition at line 117 of file attributeQuery.h.

◆ operator=() [1/2]

USD_API UsdAttributeQuery & operator= ( const UsdAttributeQuery other)

Copy assignment.

◆ operator=() [2/2]

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

Move assignment.

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

See also
UsdAttribute::ValueMightBeTimeVarying

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