HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
attributeQuery.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_USD_USD_ATTRIBUTE_QUERY_H
25 #define PXR_USD_USD_ATTRIBUTE_QUERY_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/usd/usd/api.h"
29 #include "pxr/usd/usd/attribute.h"
30 #include "pxr/usd/usd/common.h"
31 #include "pxr/usd/usd/prim.h"
33 #include "pxr/usd/usd/timeCode.h"
34 
35 #include "pxr/base/tf/token.h"
36 
37 #include <vector>
38 
40 
41 
42 /// \class UsdAttributeQuery
43 ///
44 /// Object for efficiently making repeated queries for attribute values.
45 ///
46 /// Retrieving an attribute's value at a particular time requires determining
47 /// the source of strongest opinion for that value. Often (i.e. unless the
48 /// attribute is affected by \ref Usd_Page_ValueClips "Value Clips") this
49 /// source does not vary over time. UsdAttributeQuery uses this fact to
50 /// speed up repeated value queries by caching the source information for an
51 /// attribute. It is safe to use a UsdAttributeQuery for any attribute - if
52 /// the attribute \em is affected by Value Clips, the performance gain will
53 /// just be less.
54 ///
55 /// \section Thread safety
56 /// This object provides the basic thread-safety guarantee. Multiple threads
57 /// may call the value accessor functions simultaneously.
58 ///
59 /// \section Invalidation
60 /// This object does not listen for change notification. If a consumer is
61 /// holding on to a UsdAttributeQuery, it is their responsibility to dispose
62 /// of it in response to a resync change to the associated attribute.
63 /// Failing to do so may result in incorrect values or crashes due to
64 /// dereferencing invalid objects.
65 ///
67 {
68 public:
69  /// Construct an invalid query object.
70  USD_API
72 
73  /// Construct a new query for the attribute \p attr.
74  USD_API
75  explicit UsdAttributeQuery(const UsdAttribute& attr);
76 
77  /// Construct a new query for the attribute named \p attrName under
78  /// the prim \p prim.
79  USD_API
80  UsdAttributeQuery(const UsdPrim& prim, const TfToken& attrName);
81 
82  /// Construct new queries for the attributes named in \p attrNames under
83  /// the prim \p prim. The objects in the returned vector will line up
84  /// 1-to-1 with \p attrNames.
85  USD_API
86  static std::vector<UsdAttributeQuery> CreateQueries(
87  const UsdPrim& prim, const TfTokenVector& attrNames);
88 
89  // --------------------------------------------------------------------- //
90  /// \name Query information
91  // --------------------------------------------------------------------- //
92 
93  /// @{
94 
95  /// Return the attribute associated with this query.
96  USD_API
97  const UsdAttribute& GetAttribute() const;
98 
99  /// Return true if this query is valid (i.e. it is associated with a
100  /// valid attribute), false otherwise.
101  bool IsValid() const {
102  return GetAttribute().IsValid();
103  }
104 
105 public:
106  /// Returns \c true if the query object is valid, \c false otherwise.
107  explicit operator bool() const {
108  return IsValid();
109  }
110 
111  /// @}
112 
113  // --------------------------------------------------------------------- //
114  /// \name Value & Time-Sample Accessors
115  // --------------------------------------------------------------------- //
116 
117  /// @{
118 
119  /// Perform value resolution to fetch the value of the attribute associated
120  /// with this query at the requested UsdTimeCode \p time.
121  ///
122  /// \sa UsdAttribute::Get
123  template <typename T>
126  "T must be an SdfValueType.");
127  return _Get(value, time);
128  }
129  /// \overload
130  /// Type-erased access, often not as efficient as typed access.
131  USD_API
132  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
133 
134  /// Populates a vector with authored sample times.
135  /// Returns false only on error.
136  //
137  /// Behaves identically to UsdAttribute::GetTimeSamples()
138  ///
139  /// \sa UsdAttributeQuery::GetTimeSamplesInInterval
140  USD_API
141  bool GetTimeSamples(std::vector<double>* times) const;
142 
143  /// Populates a vector with authored sample times in \p interval.
144  /// Returns false only on an error.
145  ///
146  /// Behaves identically to UsdAttribute::GetTimeSamplesInInterval()
147  USD_API
148  bool GetTimeSamplesInInterval(const GfInterval& interval,
149  std::vector<double>* times) const;
150 
151  /// Populates the given vector, \p times with the union of all the
152  /// authored sample times on all of the given attribute-query objects,
153  /// \p attrQueries.
154  ///
155  /// Behaves identically to UsdAttribute::GetUnionedTimeSamples()
156  ///
157  /// \return false if one or more attribute-queries in \p attrQueries are
158  /// invalid or if there's an error fetching time-samples for any of
159  /// the attribute-query objects.
160  ///
161  /// \sa UsdAttribute::GetUnionedTimeSamples
162  /// \sa UsdAttributeQuery::GetUnionedTimeSamplesInInterval
163  USD_API
164  static bool GetUnionedTimeSamples(
165  const std::vector<UsdAttributeQuery> &attrQueries,
166  std::vector<double> *times);
167 
168  /// Populates the given vector, \p times with the union of all the
169  /// authored sample times in the GfInterval, \p interval on all of the
170  /// given attribute-query objects, \p attrQueries.
171  ///
172  /// Behaves identically to UsdAttribute::GetUnionedTimeSamplesInInterval()
173  ///
174  /// \return false if one or more attribute-queries in \p attrQueries are
175  /// invalid or if there's an error fetching time-samples for any of
176  /// the attribute-query objects.
177  ///
178  /// \sa UsdAttribute::GetUnionedTimeSamplesInInterval
179  USD_API
181  const std::vector<UsdAttributeQuery> &attrQueries,
182  const GfInterval &interval,
183  std::vector<double> *times);
184 
185  /// Returns the number of time samples that have been authored.
186  ///
187  /// \sa UsdAttribute::GetNumTimeSamples
188  USD_API
189  size_t GetNumTimeSamples() const;
190 
191  /// Populate \a lower and \a upper with the next greater and lesser
192  /// value relative to the \a desiredTime.
193  ///
194  /// \sa UsdAttribute::GetBracketingTimeSamples
195  USD_API
196  bool GetBracketingTimeSamples(double desiredTime,
197  double* lower,
198  double* upper,
199  bool* hasTimeSamples) const;
200 
201  /// Return true if the attribute associated with this query has an
202  /// authored default value, authored time samples or a fallback value
203  /// provided by a registered schema.
204  ///
205  /// \sa UsdAttribute::HasValue
206  USD_API
207  bool HasValue() const;
208 
209  /// \deprecated This method is deprecated because it returns `true` even when
210  /// an attribute is blocked. Please use HasAuthoredValue() instead. If
211  /// you truly need to know whether the attribute has **any** authored
212  /// value opinions, *including blocks*, you can make the following query:
213  /// `query.GetAttribute().GetResolveInfo().HasAuthoredValueOpinion()`
214  ///
215  ///
216  /// Return true if this attribute has either an authored default value or
217  /// authored time samples.
218  USD_API
219  bool HasAuthoredValueOpinion() const;
220 
221  /// Return true if this attribute has either an authored default value or
222  /// authored time samples. If the attribute has been
223  /// \ref Usd_AttributeBlocking "blocked", then return `false`
224  /// \sa UsdAttribute::HasAuthoredValue()
225  USD_API
226  bool HasAuthoredValue() const;
227 
228  /// Return true if the attribute associated with this query has a
229  /// fallback value provided by a registered schema.
230  ///
231  /// \sa UsdAttribute::HasFallbackValue
232  USD_API
233  bool HasFallbackValue() const;
234 
235  /// Return true if it is possible, but not certain, that this attribute's
236  /// value changes over time, false otherwise.
237  ///
238  /// \sa UsdAttribute::ValueMightBeTimeVarying
239  USD_API
240  bool ValueMightBeTimeVarying() const;
241 
242  /// @}
243 
244 private:
245  void _Initialize(const UsdAttribute& attr);
246 
247  template <typename T>
248  USD_API
249  bool _Get(T* value, UsdTimeCode time) const;
250 
251 private:
252  UsdAttribute _attr;
253  UsdResolveInfo _resolveInfo;
254 };
255 
257 
258 #endif // PXR_USD_USD_ATTRIBUTE_QUERY_H
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
USD_API bool HasValue() const
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
#define USD_API
Definition: api.h:40
GT_API const UT_StringHolder time
USD_API size_t GetNumTimeSamples() const
USD_API bool HasAuthoredValueOpinion() const
USD_API UsdAttributeQuery()
Construct an invalid query object.
USD_API bool HasFallbackValue() const
Definition: token.h:87
USD_API bool ValueMightBeTimeVarying() const
Definition: prim.h:132
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:446
static USD_API bool GetUnionedTimeSamplesInInterval(const std::vector< UsdAttributeQuery > &attrQueries, const GfInterval &interval, std::vector< double > *times)
USD_API bool GetTimeSamples(std::vector< double > *times) const
USD_API bool GetTimeSamplesInInterval(const GfInterval &interval, std::vector< double > *times) const
static USD_API bool GetUnionedTimeSamples(const std::vector< UsdAttributeQuery > &attrQueries, std::vector< double > *times)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
bool IsValid() const
Return true if this is a valid object, false otherwise.
Definition: object.h:141
USD_API bool HasAuthoredValue() const
bool IsValid() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USD_API bool GetBracketingTimeSamples(double desiredTime, double *lower, double *upper, bool *hasTimeSamples) const
USD_API const UsdAttribute & GetAttribute() const
Return the attribute associated with this query.
static USD_API std::vector< UsdAttributeQuery > CreateQueries(const UsdPrim &prim, const TfTokenVector &attrNames)
GLsizei const GLfloat * value
Definition: glew.h:1849
Definition: value.h:174