HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
skeletonQuery.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_SKEL_SKELETON_QUERY_H
25 #define PXR_USD_USD_SKEL_SKELETON_QUERY_H
26 
27 /// \file usdSkel/skeletonQuery.h
28 
29 #include "pxr/pxr.h"
30 #include "pxr/usd/usdSkel/api.h"
31 
33 #include "pxr/base/vt/types.h"
34 
35 #include "pxr/usd/usd/prim.h"
36 
39 
40 
42 
43 class UsdGeomXformCache;
44 class UsdSkelSkeleton;
45 class UsdSkelTopology;
46 
47 TF_DECLARE_REF_PTRS(UsdSkel_SkelDefinition);
48 
49 
50 /// \class UsdSkelSkeletonQuery
51 ///
52 /// Primary interface to reading *bound* skeleton data.
53 /// This is used to query properties such as resolved transforms and animation
54 /// bindings, as bound through the UsdSkelBindingAPI.
55 ///
56 /// A UsdSkelSkeletonQuery can not be constructed directly, and instead must be
57 /// constructed through a UsdSkelCache instance. This is done as follows:
58 ///
59 /// \code
60 /// // Global cache, intended to persist.
61 /// UsdSkelCache skelCache;
62 /// // Populate the cache for a skel root.
63 /// skelCache.Populate(UsdSkelRoot(skelRootPrim));
64 ///
65 /// if (UsdSkelSkeletonQuery skelQuery = skelCache.GetSkelQuery(skelPrim)) {
66 /// ...
67 /// }
68 /// \endcode
69 ///
71 {
72 public:
74 
75  /// Return true if this query is valid.
76  bool IsValid() const { return _definition; }
77 
78  /// Boolean conversion operator. Equivalent to IsValid().
79  explicit operator bool() const { return IsValid(); }
80 
81  /// Equality comparison. Return true if \a lhs and \a rhs represent the
82  /// same UsdSkelSkeletonQuery, false otherwise.
83  friend bool operator==(const UsdSkelSkeletonQuery& lhs,
84  const UsdSkelSkeletonQuery& rhs) {
85  return lhs._definition == rhs._definition &&
86  lhs._animQuery == rhs._animQuery;
87  }
88 
89  /// Inequality comparison. Return false if \a lhs and \a rhs represent the
90  /// same UsdSkelSkeletonQuery, true otherwise.
91  friend bool operator!=(const UsdSkelSkeletonQuery& lhs,
92  const UsdSkelSkeletonQuery& rhs) {
93  return !(lhs == rhs);
94  }
95 
96  /// Returns \c true if the size of the array returned by
97  /// skeleton::GetBindTransformsAttr() matches the number of joints in the skeleton.
99  bool HasBindPose() const;
100 
101  /// Returns \c true if the size of the array returned by
102  /// skeleton::GetRestTransformsAttr() matches the number of joints in the skeleton.
104  bool HasRestPose() const;
105 
106  // hash_value overload for std/hboost hash.
108  friend size_t hash_value(const UsdSkelSkeletonQuery& query);
109 
110  /// Returns the underlying Skeleton primitive corresponding to the
111  /// bound skeleton instance, if any.
113  UsdPrim GetPrim() const;
114 
115  /// Returns the bound skeleton instance, if any.
117  const UsdSkelSkeleton& GetSkeleton() const;
118 
119  /// Returns the animation query that provides animation for the
120  /// bound skeleton instance, if any.
122  const UsdSkelAnimQuery& GetAnimQuery() const;
123 
124  /// Returns the topology of the bound skeleton instance, if any.
126  const UsdSkelTopology& GetTopology() const;
127 
128  /// Returns a mapper for remapping from the bound animation, if any,
129  /// to the Skeleton.
131  const UsdSkelAnimMapper& GetMapper() const;
132 
133  /// Returns an array of joint paths, given as tokens, describing
134  /// the order and parent-child relationships of joints in the skeleton.
135  ///
136  /// \sa UsdSkelSkeleton::GetJointOrder
138  VtTokenArray GetJointOrder() const;
139 
140  /// Compute joint transforms in joint-local space, at \p time.
141  /// This returns transforms in joint order of the skeleton.
142  /// If \p atRest is false and an animation source is bound, local transforms
143  /// defined by the animation are mapped into the skeleton's joint order.
144  /// Any transforms not defined by the animation source use the transforms
145  /// from the rest pose as a fallback value.
146  /// If valid transforms cannot be computed for the animation source, the
147  /// \p xforms are instead set to the rest transforms.
148  template <typename Matrix4>
152  bool atRest=false) const;
153 
154  /// Compute joint transforms in skeleton space, at \p time.
155  /// This concatenates joint transforms as computed from
156  /// ComputeJointLocalTransforms(). If \p atRest is true, any bound animation
157  /// source is ignored, and transforms are computed from the rest pose.
158  /// The skeleton-space transforms of the rest pose are cached internally.
159  template <typename Matrix4>
163  bool atRest=false) const;
164 
165  /// Compute joint transforms which, when concatenated against the rest pose,
166  /// produce joint transforms in joint-local space. More specifically, this
167  /// computes *restRelativeTransform* in:
168  /// \code
169  /// restRelativeTransform * restTransform = jointLocalTransform
170  /// \endcode
171  template <typename Matrix4>
174  UsdTimeCode time) const;
175 
176  /// Compute joint transforms in world space, at whatever time is configured
177  /// on \p xfCache.
178  /// This is equivalent to computing skel-space joint transforms with
179  /// CmoputeJointSkelTransforms(), and then concatenating all transforms
180  /// by the local-to-world transform of the Skeleton prim.
181  /// If \p atRest is true, any bound animation source is ignored, and
182  /// transforms are computed from the rest pose.
183  template <typename Matrix4>
186  UsdGeomXformCache* xfCache,
187  bool atRest=false) const;
188 
189  /// Compute transforms representing the change in transformation
190  /// of a joint from its rest pose, in skeleton space.
191  ///
192  /// I.e.,
193  /// \code
194  /// inverse(bindTransform)*jointTransform
195  /// \endcode
196  ///
197  /// These are the transforms usually required for skinning.
198  template <typename Matrix4>
201  UsdTimeCode time) const;
202 
203  /// Returns the world space joint transforms at bind time.
204  template <typename Matrix4>
206  bool GetJointWorldBindTransforms(VtArray<Matrix4>* xforms) const;
207 
209  std::string GetDescription() const;
210 
211 private:
212 
214  UsdSkelSkeletonQuery(const UsdSkel_SkelDefinitionRefPtr& definition,
215  const UsdSkelAnimQuery& anim=UsdSkelAnimQuery());
216 
217  bool _HasMappableAnim() const;
218 
219  template <typename Matrix4>
220  bool _ComputeJointLocalTransforms(VtArray<Matrix4>* xforms,
222  bool atRest=false) const;
223 
224  template <typename Matrix4>
225  bool _ComputeJointSkelTransforms(VtArray<Matrix4>* xforms,
227  bool atRest=false) const;
228 
229  template <typename Matrix4>
230  bool _ComputeSkinningTransforms(VtArray<Matrix4>* xforms,
231  UsdTimeCode time) const;
232 
233 private:
234  UsdSkel_SkelDefinitionRefPtr _definition;
235  UsdSkelAnimQuery _animQuery;
236  UsdSkelAnimMapper _animToSkelMapper;
237 
238  friend class UsdSkel_CacheImpl;
239 };
240 
241 
243 
244 #endif // PXR_USD_USD_SKEL_SKELETON_QUERY_H
GLenum query
Definition: glad.h:2772
GT_API const UT_StringHolder time
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
USDSKEL_API bool HasBindPose() const
USDSKEL_API bool ComputeSkinningTransforms(VtArray< Matrix4 > *xforms, UsdTimeCode time) const
USDSKEL_API const UsdSkelSkeleton & GetSkeleton() const
Returns the bound skeleton instance, if any.
USDSKEL_API bool ComputeJointRestRelativeTransforms(VtArray< Matrix4 > *xforms, UsdTimeCode time) const
friend bool operator==(const UsdSkelSkeletonQuery &lhs, const UsdSkelSkeletonQuery &rhs)
Definition: skeletonQuery.h:83
USDSKEL_API bool HasRestPose() const
friend class UsdSkel_CacheImpl
USDSKEL_API VtTokenArray GetJointOrder() const
TF_DECLARE_REF_PTRS(UsdSkel_SkelDefinition)
USDSKEL_API bool GetJointWorldBindTransforms(VtArray< Matrix4 > *xforms) const
Returns the world space joint transforms at bind time.
USDSKEL_API const UsdSkelTopology & GetTopology() const
Returns the topology of the bound skeleton instance, if any.
USDSKEL_API UsdPrim GetPrim() const
USDSKEL_API bool ComputeJointLocalTransforms(VtArray< Matrix4 > *xforms, UsdTimeCode time, bool atRest=false) const
Definition: prim.h:135
#define USDSKEL_API
Definition: api.h:40
Definition: types.h:173
bool IsValid() const
Return true if this query is valid.
Definition: skeletonQuery.h:76
USDSKEL_API bool ComputeJointSkelTransforms(VtArray< Matrix4 > *xforms, UsdTimeCode time, bool atRest=false) const
USDSKEL_API bool ComputeJointWorldTransforms(VtArray< Matrix4 > *xforms, UsdGeomXformCache *xfCache, bool atRest=false) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDSKEL_API friend size_t hash_value(const UsdSkelSkeletonQuery &query)
USDSKEL_API const UsdSkelAnimQuery & GetAnimQuery() const
friend bool operator!=(const UsdSkelSkeletonQuery &lhs, const UsdSkelSkeletonQuery &rhs)
Definition: skeletonQuery.h:91
USDSKEL_API std::string GetDescription() const
USDSKEL_API const UsdSkelAnimMapper & GetMapper() const