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