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"
34 #include "pxr/usd/usd/timeCode.h"
35 
36 #include "pxr/base/tf/token.h"
37 
38 #include <vector>
39 
41 
42 
43 /// \class UsdAttributeQuery
44 ///
45 /// Object for efficiently making repeated queries for attribute values.
46 ///
47 /// Retrieving an attribute's value at a particular time requires determining
48 /// the source of strongest opinion for that value. Often (i.e. unless the
49 /// attribute is affected by \ref Usd_Page_ValueClips "Value Clips") this
50 /// source does not vary over time. UsdAttributeQuery uses this fact to
51 /// speed up repeated value queries by caching the source information for an
52 /// attribute. It is safe to use a UsdAttributeQuery for any attribute - if
53 /// the attribute \em is affected by Value Clips, the performance gain will
54 /// just be less.
55 ///
56 /// \section Resolve_targets Resolve targets
57 /// An attribute query can also be constructed for an attribute along with a
58 /// UsdResolveTarget. A resolve target allows value resolution to consider only
59 /// a subrange of the prim stack instead of the entirety of it. All of the methods
60 /// of an attribute query created with a resolve target will perform value
61 /// resolution within that resolve target. This can be useful for finding the
62 /// value of an attribute resolved up to a particular layer or for determining
63 /// if a value authored on layer would be overridden by a stronger opinion.
64 ///
65 /// \section Thread_safety Thread safety
66 /// This object provides the basic thread-safety guarantee. Multiple threads
67 /// may call the value accessor functions simultaneously.
68 ///
69 /// \section Invalidation
70 /// This object does not listen for change notification. If a consumer is
71 /// holding on to a UsdAttributeQuery, it is their responsibility to dispose
72 /// of it in response to a resync change to the associated attribute.
73 /// Failing to do so may result in incorrect values or crashes due to
74 /// dereferencing invalid objects.
75 ///
77 {
78 public:
79  /// Construct an invalid query object.
80  USD_API
82 
83  /// Copy constructor.
84  USD_API
85  UsdAttributeQuery(const UsdAttributeQuery &other);
86 
87  /// Move constructor.
88  USD_API
89  UsdAttributeQuery(UsdAttributeQuery &&other) = default;
90 
91  /// Construct a new query for the attribute \p attr.
92  USD_API
93  explicit UsdAttributeQuery(const UsdAttribute& attr);
94 
95  /// Construct a new query for the attribute named \p attrName under
96  /// the prim \p prim.
97  USD_API
98  UsdAttributeQuery(const UsdPrim& prim, const TfToken& attrName);
99 
100  /// Construct a new query for the attribute \p attr with the given
101  /// resolve target \p resolveTarget.
102  ///
103  /// Note that a UsdResolveTarget is associated with a particular prim so
104  /// only resolve targets for the attribute's owning prim are allowed.
105  USD_API
106  UsdAttributeQuery(const UsdAttribute &attr,
107  const UsdResolveTarget &resolveTarget);
108 
109  /// Construct new queries for the attributes named in \p attrNames under
110  /// the prim \p prim. The objects in the returned vector will line up
111  /// 1-to-1 with \p attrNames.
112  USD_API
113  static std::vector<UsdAttributeQuery> CreateQueries(
114  const UsdPrim& prim, const TfTokenVector& attrNames);
115 
116  // --------------------------------------------------------------------- //
117  /// \name Query information
118  // --------------------------------------------------------------------- //
119 
120  /// @{
121 
122  /// Return the attribute associated with this query.
123  USD_API
124  const UsdAttribute& GetAttribute() const;
125 
126  /// Return true if this query is valid (i.e. it is associated with a
127  /// valid attribute), false otherwise.
128  bool IsValid() const {
129  return GetAttribute().IsValid();
130  }
131 
132 public:
133  /// Returns \c true if the query object is valid, \c false otherwise.
134  explicit operator bool() const {
135  return IsValid();
136  }
137 
138  /// Copy assignment.
139  USD_API
140  UsdAttributeQuery &operator=(const UsdAttributeQuery &other);
141 
142  /// Move assignment.
143  USD_API
144  UsdAttributeQuery &operator=(UsdAttributeQuery &&other) = default;
145 
146  /// @}
147 
148  // --------------------------------------------------------------------- //
149  /// \name Value & Time-Sample Accessors
150  // --------------------------------------------------------------------- //
151 
152  /// @{
153 
154  /// Perform value resolution to fetch the value of the attribute associated
155  /// with this query at the requested UsdTimeCode \p time.
156  ///
157  /// \sa UsdAttribute::Get
158  template <typename T>
161  "T must be an SdfValueType.");
162  return _Get(value, time);
163  }
164  /// \overload
165  /// Type-erased access, often not as efficient as typed access.
166  USD_API
167  bool Get(VtValue* value, UsdTimeCode time = UsdTimeCode::Default()) const;
168 
169  /// Populates a vector with authored sample times.
170  /// Returns false only on error.
171  //
172  /// Behaves identically to UsdAttribute::GetTimeSamples()
173  ///
174  /// \sa UsdAttributeQuery::GetTimeSamplesInInterval
175  USD_API
176  bool GetTimeSamples(std::vector<double>* times) const;
177 
178  /// Populates a vector with authored sample times in \p interval.
179  /// Returns false only on an error.
180  ///
181  /// Behaves identically to UsdAttribute::GetTimeSamplesInInterval()
182  USD_API
183  bool GetTimeSamplesInInterval(const GfInterval& interval,
184  std::vector<double>* times) const;
185 
186  /// Populates the given vector, \p times with the union of all the
187  /// authored sample times on all of the given attribute-query objects,
188  /// \p attrQueries.
189  ///
190  /// Behaves identically to UsdAttribute::GetUnionedTimeSamples()
191  ///
192  /// \return false if one or more attribute-queries in \p attrQueries are
193  /// invalid or if there's an error fetching time-samples for any of
194  /// the attribute-query objects.
195  ///
196  /// \sa UsdAttribute::GetUnionedTimeSamples
197  /// \sa UsdAttributeQuery::GetUnionedTimeSamplesInInterval
198  USD_API
199  static bool GetUnionedTimeSamples(
200  const std::vector<UsdAttributeQuery> &attrQueries,
201  std::vector<double> *times);
202 
203  /// Populates the given vector, \p times with the union of all the
204  /// authored sample times in the GfInterval, \p interval on all of the
205  /// given attribute-query objects, \p attrQueries.
206  ///
207  /// Behaves identically to UsdAttribute::GetUnionedTimeSamplesInInterval()
208  ///
209  /// \return false if one or more attribute-queries in \p attrQueries are
210  /// invalid or if there's an error fetching time-samples for any of
211  /// the attribute-query objects.
212  ///
213  /// \sa UsdAttribute::GetUnionedTimeSamplesInInterval
214  USD_API
216  const std::vector<UsdAttributeQuery> &attrQueries,
217  const GfInterval &interval,
218  std::vector<double> *times);
219 
220  /// Returns the number of time samples that have been authored.
221  ///
222  /// \sa UsdAttribute::GetNumTimeSamples
223  USD_API
224  size_t GetNumTimeSamples() const;
225 
226  /// Populate \a lower and \a upper with the next greater and lesser
227  /// value relative to the \a desiredTime.
228  ///
229  /// \sa UsdAttribute::GetBracketingTimeSamples
230  USD_API
231  bool GetBracketingTimeSamples(double desiredTime,
232  double* lower,
233  double* upper,
234  bool* hasTimeSamples) const;
235 
236  /// Return true if the attribute associated with this query has an
237  /// authored default value, authored time samples or a fallback value
238  /// provided by a registered schema.
239  ///
240  /// \sa UsdAttribute::HasValue
241  USD_API
242  bool HasValue() const;
243 
244  /// \deprecated This method is deprecated because it returns `true` even when
245  /// an attribute is blocked. Please use HasAuthoredValue() instead. If
246  /// you truly need to know whether the attribute has **any** authored
247  /// value opinions, *including blocks*, you can make the following query:
248  /// `query.GetAttribute().GetResolveInfo().HasAuthoredValueOpinion()`
249  ///
250  ///
251  /// Return true if this attribute has either an authored default value or
252  /// authored time samples.
253  USD_API
254  bool HasAuthoredValueOpinion() const;
255 
256  /// Return true if this attribute has either an authored default value or
257  /// authored time samples. If the attribute has been
258  /// \ref Usd_AttributeBlocking "blocked", then return `false`
259  /// \sa UsdAttribute::HasAuthoredValue()
260  USD_API
261  bool HasAuthoredValue() const;
262 
263  /// Return true if the attribute associated with this query has a
264  /// fallback value provided by a registered schema.
265  ///
266  /// \sa UsdAttribute::HasFallbackValue
267  USD_API
268  bool HasFallbackValue() const;
269 
270  /// Return true if it is possible, but not certain, that this attribute's
271  /// value changes over time, false otherwise.
272  ///
273  /// \sa UsdAttribute::ValueMightBeTimeVarying
274  USD_API
275  bool ValueMightBeTimeVarying() const;
276 
277  /// @}
278 
279 private:
280  void _Initialize();
281 
282  void _Initialize(const UsdResolveTarget &resolveTarget);
283 
284  template <typename T>
285  USD_API
286  bool _Get(T* value, UsdTimeCode time) const;
287 
288 private:
289  UsdAttribute _attr;
290  UsdResolveInfo _resolveInfo;
291  std::unique_ptr<UsdResolveTarget> _resolveTarget;
292 };
293 
295 
296 #endif // PXR_USD_USD_ATTRIBUTE_QUERY_H
std::string upper(string_view a)
Return an all-upper case version of a (locale-independent).
Definition: strutil.h:402
bool Get(T *value, UsdTimeCode time=UsdTimeCode::Default()) const
USD_API bool HasValue() const
static constexpr UsdTimeCode Default()
Definition: timeCode.h:112
#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 & operator=(const UsdAttributeQuery &other)
Copy assignment.
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:133
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:457
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:1432
bool IsValid() const
Return true if this is a valid object, false otherwise.
Definition: object.h:143
USD_API bool HasAuthoredValue() const
std::string lower(string_view a)
Return an all-upper case version of a (locale-independent).
Definition: strutil.h:395
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.
Definition: core.h:1131
static USD_API std::vector< UsdAttributeQuery > CreateQueries(const UsdPrim &prim, const TfTokenVector &attrNames)
Definition: value.h:164