HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
bindingAPI.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDSKEL_GENERATED_BINDINGAPI_H
8 #define USDSKEL_GENERATED_BINDINGAPI_H
9 
10 /// \file usdSkel/bindingAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdSkel/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdSkel/tokens.h"
18 
19 #include "pxr/base/tf/span.h"
22 
23 #include "pxr/base/vt/value.h"
24 
25 #include "pxr/base/gf/vec3d.h"
26 #include "pxr/base/gf/vec3f.h"
27 #include "pxr/base/gf/matrix4d.h"
28 
29 #include "pxr/base/tf/token.h"
30 #include "pxr/base/tf/type.h"
31 
33 
34 class SdfAssetPath;
35 
36 // -------------------------------------------------------------------------- //
37 // SKELBINDINGAPI //
38 // -------------------------------------------------------------------------- //
39 
40 /// \class UsdSkelBindingAPI
41 ///
42 /// Provides API for authoring and extracting all the skinning-related
43 /// data that lives in the "geometry hierarchy" of prims and models that want
44 /// to be skeletally deformed.
45 ///
46 /// See the extended \ref UsdSkel_BindingAPI "UsdSkelBindingAPI schema"
47 /// documentation for more about bindings and how they apply in a scene graph.
48 ///
49 ///
50 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
51 /// that are text/tokens, the actual token is published and defined in \ref UsdSkelTokens.
52 /// So to set an attribute to the value "rightHanded", use UsdSkelTokens->rightHanded
53 /// as the value.
54 ///
56 {
57 public:
58  /// Compile time constant representing what kind of schema this class is.
59  ///
60  /// \sa UsdSchemaKind
62 
63  /// Construct a UsdSkelBindingAPI on UsdPrim \p prim .
64  /// Equivalent to UsdSkelBindingAPI::Get(prim.GetStage(), prim.GetPath())
65  /// for a \em valid \p prim, but will not immediately throw an error for
66  /// an invalid \p prim
67  explicit UsdSkelBindingAPI(const UsdPrim& prim=UsdPrim())
68  : UsdAPISchemaBase(prim)
69  {
70  }
71 
72  /// Construct a UsdSkelBindingAPI on the prim held by \p schemaObj .
73  /// Should be preferred over UsdSkelBindingAPI(schemaObj.GetPrim()),
74  /// as it preserves SchemaBase state.
75  explicit UsdSkelBindingAPI(const UsdSchemaBase& schemaObj)
76  : UsdAPISchemaBase(schemaObj)
77  {
78  }
79 
80  /// Destructor.
82  virtual ~UsdSkelBindingAPI();
83 
84  /// Return a vector of names of all pre-declared attributes for this schema
85  /// class and all its ancestor classes. Does not include attributes that
86  /// may be authored by custom/extended methods of the schemas involved.
88  static const TfTokenVector &
89  GetSchemaAttributeNames(bool includeInherited=true);
90 
91  /// Return a UsdSkelBindingAPI holding the prim adhering to this
92  /// schema at \p path on \p stage. If no prim exists at \p path on
93  /// \p stage, or if the prim at that path does not adhere to this schema,
94  /// return an invalid schema object. This is shorthand for the following:
95  ///
96  /// \code
97  /// UsdSkelBindingAPI(stage->GetPrimAtPath(path));
98  /// \endcode
99  ///
101  static UsdSkelBindingAPI
102  Get(const UsdStagePtr &stage, const SdfPath &path);
103 
104 
105  /// Returns true if this <b>single-apply</b> API schema can be applied to
106  /// the given \p prim. If this schema can not be a applied to the prim,
107  /// this returns false and, if provided, populates \p whyNot with the
108  /// reason it can not be applied.
109  ///
110  /// Note that if CanApply returns false, that does not necessarily imply
111  /// that calling Apply will fail. Callers are expected to call CanApply
112  /// before calling Apply if they want to ensure that it is valid to
113  /// apply a schema.
114  ///
115  /// \sa UsdPrim::GetAppliedSchemas()
116  /// \sa UsdPrim::HasAPI()
117  /// \sa UsdPrim::CanApplyAPI()
118  /// \sa UsdPrim::ApplyAPI()
119  /// \sa UsdPrim::RemoveAPI()
120  ///
122  static bool
123  CanApply(const UsdPrim &prim, std::string *whyNot=nullptr);
124 
125  /// Applies this <b>single-apply</b> API schema to the given \p prim.
126  /// This information is stored by adding "SkelBindingAPI" to the
127  /// token-valued, listOp metadata \em apiSchemas on the prim.
128  ///
129  /// \return A valid UsdSkelBindingAPI object is returned upon success.
130  /// An invalid (or empty) UsdSkelBindingAPI object is returned upon
131  /// failure. See \ref UsdPrim::ApplyAPI() for conditions
132  /// resulting in failure.
133  ///
134  /// \sa UsdPrim::GetAppliedSchemas()
135  /// \sa UsdPrim::HasAPI()
136  /// \sa UsdPrim::CanApplyAPI()
137  /// \sa UsdPrim::ApplyAPI()
138  /// \sa UsdPrim::RemoveAPI()
139  ///
141  static UsdSkelBindingAPI
142  Apply(const UsdPrim &prim);
143 
144 protected:
145  /// Returns the kind of schema this class belongs to.
146  ///
147  /// \sa UsdSchemaKind
149  UsdSchemaKind _GetSchemaKind() const override;
150 
151 private:
152  // needs to invoke _GetStaticTfType.
153  friend class UsdSchemaRegistry;
155  static const TfType &_GetStaticTfType();
156 
157  static bool _IsTypedSchema();
158 
159  // override SchemaBase virtuals.
161  const TfType &_GetTfType() const override;
162 
163 public:
164  // --------------------------------------------------------------------- //
165  // SKINNINGMETHOD
166  // --------------------------------------------------------------------- //
167  /// The skinningMethod specifies the skinning method for the prim.
168  ///
169  /// | ||
170  /// | -- | -- |
171  /// | Declaration | `uniform token primvars:skel:skinningMethod = "classicLinear"` |
172  /// | C++ Type | TfToken |
173  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
174  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
175  /// | \ref UsdSkelTokens "Allowed Values" | classicLinear, dualQuaternion |
178 
179  /// See GetSkinningMethodAttr(), and also
180  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
181  /// If specified, author \p defaultValue as the attribute's default,
182  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
183  /// the default for \p writeSparsely is \c false.
185  UsdAttribute CreateSkinningMethodAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
186 
187 public:
188  // --------------------------------------------------------------------- //
189  // GEOMBINDTRANSFORM
190  // --------------------------------------------------------------------- //
191  /// Encodes the bind-time world space transforms of the prim.
192  /// If the transform is identical for a group of gprims that share a common
193  /// ancestor, the transform may be authored on the ancestor, to "inherit"
194  /// down to all the leaf gprims. If this transform is unset, an identity
195  /// transform is used instead.
196  ///
197  /// | ||
198  /// | -- | -- |
199  /// | Declaration | `matrix4d primvars:skel:geomBindTransform` |
200  /// | C++ Type | GfMatrix4d |
201  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Matrix4d |
204 
205  /// See GetGeomBindTransformAttr(), and also
206  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
207  /// If specified, author \p defaultValue as the attribute's default,
208  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
209  /// the default for \p writeSparsely is \c false.
211  UsdAttribute CreateGeomBindTransformAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
212 
213 public:
214  // --------------------------------------------------------------------- //
215  // JOINTS
216  // --------------------------------------------------------------------- //
217  /// An (optional) array of tokens defining the list of
218  /// joints to which jointIndices apply. If not defined, jointIndices applies
219  /// to the ordered list of joints defined in the bound Skeleton's *joints*
220  /// attribute. If undefined on a primitive, the primitive inherits the
221  /// value of the nearest ancestor prim, if any.
222  ///
223  /// | ||
224  /// | -- | -- |
225  /// | Declaration | `uniform token[] skel:joints` |
226  /// | C++ Type | VtArray<TfToken> |
227  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->TokenArray |
228  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
230  UsdAttribute GetJointsAttr() const;
231 
232  /// See GetJointsAttr(), and also
233  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
234  /// If specified, author \p defaultValue as the attribute's default,
235  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
236  /// the default for \p writeSparsely is \c false.
238  UsdAttribute CreateJointsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
239 
240 public:
241  // --------------------------------------------------------------------- //
242  // JOINTINDICES
243  // --------------------------------------------------------------------- //
244  /// Indices into the *joints* attribute of the closest
245  /// (in namespace) bound Skeleton that affect each point of a PointBased
246  /// gprim. The primvar can have either *constant* or *vertex* interpolation.
247  /// This primvar's *elementSize* will determine how many joint influences
248  /// apply to each point. Indices must point be valid. Null influences should
249  /// be defined by setting values in jointWeights to zero.
250  /// See UsdGeomPrimvar for more information on interpolation and
251  /// elementSize.
252  ///
253  /// | ||
254  /// | -- | -- |
255  /// | Declaration | `int[] primvars:skel:jointIndices` |
256  /// | C++ Type | VtArray<int> |
257  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->IntArray |
260 
261  /// See GetJointIndicesAttr(), and also
262  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
263  /// If specified, author \p defaultValue as the attribute's default,
264  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
265  /// the default for \p writeSparsely is \c false.
267  UsdAttribute CreateJointIndicesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
268 
269 public:
270  // --------------------------------------------------------------------- //
271  // JOINTWEIGHTS
272  // --------------------------------------------------------------------- //
273  /// Weights for the joints that affect each point of a PointBased
274  /// gprim. The primvar can have either *constant* or *vertex* interpolation.
275  /// This primvar's *elementSize* will determine how many joints influences
276  /// apply to each point. The length, interpolation, and elementSize of
277  /// *jointWeights* must match that of *jointIndices*. See UsdGeomPrimvar
278  /// for more information on interpolation and elementSize.
279  ///
280  /// | ||
281  /// | -- | -- |
282  /// | Declaration | `float[] primvars:skel:jointWeights` |
283  /// | C++ Type | VtArray<float> |
284  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->FloatArray |
287 
288  /// See GetJointWeightsAttr(), and also
289  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
290  /// If specified, author \p defaultValue as the attribute's default,
291  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
292  /// the default for \p writeSparsely is \c false.
294  UsdAttribute CreateJointWeightsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
295 
296 public:
297  // --------------------------------------------------------------------- //
298  // BLENDSHAPES
299  // --------------------------------------------------------------------- //
300  /// An array of tokens defining the order onto which blend shape
301  /// weights from an animation source map onto the *skel:blendShapeTargets*
302  /// rel of a binding site. If authored, the number of elements must be equal
303  /// to the number of targets in the _blendShapeTargets_ rel. This property
304  /// is not inherited hierarchically, and is expected to be authored directly
305  /// on the skinnable primitive to which the blend shapes apply.
306  ///
307  /// | ||
308  /// | -- | -- |
309  /// | Declaration | `uniform token[] skel:blendShapes` |
310  /// | C++ Type | VtArray<TfToken> |
311  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->TokenArray |
312  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
315 
316  /// See GetBlendShapesAttr(), and also
317  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
318  /// If specified, author \p defaultValue as the attribute's default,
319  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
320  /// the default for \p writeSparsely is \c false.
322  UsdAttribute CreateBlendShapesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
323 
324 public:
325  // --------------------------------------------------------------------- //
326  // ANIMATIONSOURCE
327  // --------------------------------------------------------------------- //
328  /// Animation source to be bound to Skeleton primitives at or
329  /// beneath the location at which this property is defined.
330  ///
331  ///
334 
335  /// See GetAnimationSourceRel(), and also
336  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
339 
340 public:
341  // --------------------------------------------------------------------- //
342  // SKELETON
343  // --------------------------------------------------------------------- //
344  /// Skeleton to be bound to this prim and its descendents that
345  /// possess a mapping and weighting to the joints of the identified
346  /// Skeleton.
347  ///
350 
351  /// See GetSkeletonRel(), and also
352  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
355 
356 public:
357  // --------------------------------------------------------------------- //
358  // BLENDSHAPETARGETS
359  // --------------------------------------------------------------------- //
360  /// Ordered list of all target blend shapes. This property is not
361  /// inherited hierarchically, and is expected to be authored directly on
362  /// the skinnable primitive to which the the blend shapes apply.
363  ///
366 
367  /// See GetBlendShapeTargetsRel(), and also
368  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
371 
372 public:
373  // ===================================================================== //
374  // Feel free to add custom code below this line, it will be preserved by
375  // the code generator.
376  //
377  // Just remember to:
378  // - Close the class declaration with };
379  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
380  // - Close the include guard with #endif
381  // ===================================================================== //
382  // --(BEGIN CUSTOM CODE)--
383 
384  /// Convenience function to get the jointIndices attribute as a primvar.
385  ///
386  /// \sa GetJointIndicesAttr, GetInheritedJointWeightsPrimvar
389 
390  /// Convenience function to create the jointIndices primvar, optionally
391  /// specifying elementSize.
392  /// If \p constant is true, the resulting primvar is configured
393  /// with 'constant' interpolation, and describes a rigid deformation.
394  /// Otherwise, the primvar is configured with 'vertex' interpolation,
395  /// and describes joint influences that vary per point.
396  ///
397  /// \sa CreateJointIndicesAttr(), GetJointIndicesPrimvar()
400  int elementSize=-1) const;
401 
402  /// Convenience function to get the jointWeights attribute as a primvar.
403  ///
404  /// \sa GetJointWeightsAttr, GetInheritedJointWeightsPrimvar
407 
408  /// Convenience function to create the jointWeights primvar, optionally
409  /// specifying elementSize.
410  /// If \p constant is true, the resulting primvar is configured
411  /// with 'constant' interpolation, and describes a rigid deformation.
412  /// Otherwise, the primvar is configured with 'vertex' interpolation,
413  /// and describes joint influences that vary per point.
414  ///
415  /// \sa CreateJointWeightsAttr(), GetJointWeightsPrimvar()
418  int elementSize=-1) const;
419 
420  /// Convenience method for defining joints influences that
421  /// make a primitive rigidly deformed by a single joint.
423  bool SetRigidJointInfluence(int jointIndex, float weight=1) const;
424 
425  /// Convenience method to query the Skeleton bound on this prim.
426  /// Returns true if a Skeleton binding is defined, and sets \p skel to
427  /// the target skel. The resulting Skeleton may still be invalid,
428  /// if the Skeleton has been explicitly *unbound*.
429  ///
430  /// This does not resolved inherited skeleton bindings.
432  bool GetSkeleton(UsdSkelSkeleton* skel) const;
433 
434  /// Convenience method to query the animation source bound on this prim.
435  /// Returns true if an animation source binding is defined, and sets
436  /// \p prim to the target prim. The resulting primitive may still be
437  /// invalid, if the prim has been explicitly *unbound*.
438  ///
439  /// This does not resolved inherited animation source bindings.
441  bool GetAnimationSource(UsdPrim* prim) const;
442 
443  /// Returns the skeleton bound at this prim, or one of its ancestors.
446 
447  /// Returns the animation source bound at this prim, or one of
448  /// its ancestors.
451 
452  /// Validate an array of joint indices.
453  /// This ensures that all indices are the in the range [0, numJoints).
454  /// Returns true if the indices are valid, or false otherwise.
455  /// If invalid and \p reason is non-null, an error message describing
456  /// the first validation error will be set.
459  size_t numJoints,
460  std::string* reason=nullptr);
461 };
462 
464 
465 #endif
USDSKEL_API bool SetRigidJointInfluence(int jointIndex, float weight=1) const
GLsizei GLenum const void * indices
Definition: glcorearb.h:406
USDSKEL_API UsdAttribute CreateJointIndicesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDSKEL_API UsdGeomPrimvar GetJointIndicesPrimvar() const
USDSKEL_API UsdRelationship GetSkeletonRel() const
USDSKEL_API UsdSkelSkeleton GetInheritedSkeleton() const
Returns the skeleton bound at this prim, or one of its ancestors.
static const UsdSchemaKind schemaKind
Definition: bindingAPI.h:61
USDSKEL_API UsdAttribute GetBlendShapesAttr() const
USDSKEL_API UsdGeomPrimvar GetJointWeightsPrimvar() const
Single Apply API schema.
virtual USDSKEL_API ~UsdSkelBindingAPI()
Destructor.
USDSKEL_API UsdRelationship GetAnimationSourceRel() const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDSKEL_API UsdSchemaKind _GetSchemaKind() const override
static USDSKEL_API UsdSkelBindingAPI Apply(const UsdPrim &prim)
USDSKEL_API UsdAttribute CreateJointsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDSKEL_API UsdPrim GetInheritedAnimationSource() const
USDSKEL_API bool GetSkeleton(UsdSkelSkeleton *skel) const
static USDSKEL_API UsdSkelBindingAPI Get(const UsdStagePtr &stage, const SdfPath &path)
USDSKEL_API UsdAttribute CreateGeomBindTransformAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDSKEL_API UsdAttribute CreateSkinningMethodAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
UsdSkelBindingAPI(const UsdPrim &prim=UsdPrim())
Definition: bindingAPI.h:67
USDSKEL_API UsdRelationship CreateBlendShapeTargetsRel() const
USDSKEL_API UsdAttribute GetGeomBindTransformAttr() const
static USDSKEL_API bool ValidateJointIndices(TfSpan< const int > indices, size_t numJoints, std::string *reason=nullptr)
USDSKEL_API UsdAttribute CreateBlendShapesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: span.h:70
static USDSKEL_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
USDSKEL_API UsdRelationship GetBlendShapeTargetsRel() const
USDSKEL_API UsdGeomPrimvar CreateJointIndicesPrimvar(bool constant, int elementSize=-1) const
USDSKEL_API bool GetAnimationSource(UsdPrim *prim) const
USDSKEL_API UsdRelationship CreateAnimationSourceRel() const
USDSKEL_API UsdRelationship CreateSkeletonRel() const
Definition: prim.h:116
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
USDSKEL_API UsdAttribute GetJointsAttr() const
#define USDSKEL_API
Definition: api.h:23
Definition: path.h:273
USDSKEL_API UsdGeomPrimvar CreateJointWeightsPrimvar(bool constant, int elementSize=-1) const
UsdSchemaKind
Definition: common.h:112
USDSKEL_API UsdAttribute CreateJointWeightsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDSKEL_API UsdAttribute GetJointIndicesAttr() const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
UsdSkelBindingAPI(const UsdSchemaBase &schemaObj)
Definition: bindingAPI.h:75
USDSKEL_API UsdAttribute GetJointWeightsAttr() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
Definition: type.h:47
static USDSKEL_API bool CanApply(const UsdPrim &prim, std::string *whyNot=nullptr)
USDSKEL_API UsdAttribute GetSkinningMethodAttr() const
Definition: value.h:146