HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
driveAPI.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 USDPHYSICS_GENERATED_DRIVEAPI_H
8 #define USDPHYSICS_GENERATED_DRIVEAPI_H
9 
10 /// \file usdPhysics/driveAPI.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdPhysics/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
18 
19 #include "pxr/base/vt/value.h"
20 
21 #include "pxr/base/gf/vec3d.h"
22 #include "pxr/base/gf/vec3f.h"
23 #include "pxr/base/gf/matrix4d.h"
24 
25 #include "pxr/base/tf/token.h"
26 #include "pxr/base/tf/type.h"
27 
29 
30 class SdfAssetPath;
31 
32 // -------------------------------------------------------------------------- //
33 // PHYSICSDRIVEAPI //
34 // -------------------------------------------------------------------------- //
35 
36 /// \class UsdPhysicsDriveAPI
37 ///
38 /// The PhysicsDriveAPI when applied to any joint primitive will drive
39 /// the joint towards a given target. The PhysicsDriveAPI is a multipleApply
40 /// schema: drive can be set per axis "transX", "transY", "transZ", "rotX",
41 /// "rotY", "rotZ" or its "linear" for prismatic joint or "angular" for revolute
42 /// joints. Setting these as a multipleApply schema TfToken name will
43 /// define the degree of freedom the DriveAPI is applied to. Each drive is an
44 /// implicit force-limited damped spring:
45 /// Force or acceleration = stiffness * (targetPosition - position)
46 /// + damping * (targetVelocity - velocity)
47 ///
48 /// For any described attribute \em Fallback \em Value or \em Allowed \em Values below
49 /// that are text/tokens, the actual token is published and defined in \ref UsdPhysicsTokens.
50 /// So to set an attribute to the value "rightHanded", use UsdPhysicsTokens->rightHanded
51 /// as the value.
52 ///
54 {
55 public:
56  /// Compile time constant representing what kind of schema this class is.
57  ///
58  /// \sa UsdSchemaKind
60 
61  /// Construct a UsdPhysicsDriveAPI on UsdPrim \p prim with
62  /// name \p name . Equivalent to
63  /// UsdPhysicsDriveAPI::Get(
64  /// prim.GetStage(),
65  /// prim.GetPath().AppendProperty(
66  /// "drive:name"));
67  ///
68  /// for a \em valid \p prim, but will not immediately throw an error for
69  /// an invalid \p prim
71  const UsdPrim& prim=UsdPrim(), const TfToken &name=TfToken())
72  : UsdAPISchemaBase(prim, /*instanceName*/ name)
73  { }
74 
75  /// Construct a UsdPhysicsDriveAPI on the prim held by \p schemaObj with
76  /// name \p name. Should be preferred over
77  /// UsdPhysicsDriveAPI(schemaObj.GetPrim(), name), as it preserves
78  /// SchemaBase state.
80  const UsdSchemaBase& schemaObj, const TfToken &name)
81  : UsdAPISchemaBase(schemaObj, /*instanceName*/ name)
82  { }
83 
84  /// Destructor.
86  virtual ~UsdPhysicsDriveAPI();
87 
88  /// Return a vector of names of all pre-declared attributes for this schema
89  /// class and all its ancestor classes. Does not include attributes that
90  /// may be authored by custom/extended methods of the schemas involved.
92  static const TfTokenVector &
93  GetSchemaAttributeNames(bool includeInherited=true);
94 
95  /// Return a vector of names of all pre-declared attributes for this schema
96  /// class and all its ancestor classes for a given instance name. Does not
97  /// include attributes that may be authored by custom/extended methods of
98  /// the schemas involved. The names returned will have the proper namespace
99  /// prefix.
101  static TfTokenVector
102  GetSchemaAttributeNames(bool includeInherited, const TfToken &instanceName);
103 
104  /// Returns the name of this multiple-apply schema instance
105  TfToken GetName() const {
106  return _GetInstanceName();
107  }
108 
109  /// Return a UsdPhysicsDriveAPI holding the prim adhering to this
110  /// schema at \p path on \p stage. If no prim exists at \p path on
111  /// \p stage, or if the prim at that path does not adhere to this schema,
112  /// return an invalid schema object. \p path must be of the format
113  /// <path>.drive:name .
114  ///
115  /// This is shorthand for the following:
116  ///
117  /// \code
118  /// TfToken name = SdfPath::StripNamespace(path.GetToken());
119  /// UsdPhysicsDriveAPI(
120  /// stage->GetPrimAtPath(path.GetPrimPath()), name);
121  /// \endcode
122  ///
124  static UsdPhysicsDriveAPI
125  Get(const UsdStagePtr &stage, const SdfPath &path);
126 
127  /// Return a UsdPhysicsDriveAPI with name \p name holding the
128  /// prim \p prim. Shorthand for UsdPhysicsDriveAPI(prim, name);
130  static UsdPhysicsDriveAPI
131  Get(const UsdPrim &prim, const TfToken &name);
132 
133  /// Return a vector of all named instances of UsdPhysicsDriveAPI on the
134  /// given \p prim.
136  static std::vector<UsdPhysicsDriveAPI>
137  GetAll(const UsdPrim &prim);
138 
139  /// Checks if the given name \p baseName is the base name of a property
140  /// of PhysicsDriveAPI.
142  static bool
143  IsSchemaPropertyBaseName(const TfToken &baseName);
144 
145  /// Checks if the given path \p path is of an API schema of type
146  /// PhysicsDriveAPI. If so, it stores the instance name of
147  /// the schema in \p name and returns true. Otherwise, it returns false.
149  static bool
151 
152  /// Returns true if this <b>multiple-apply</b> API schema can be applied,
153  /// with the given instance name, \p name, to the given \p prim. If this
154  /// schema can not be a applied the prim, this returns false and, if
155  /// provided, populates \p whyNot with the reason it can not be applied.
156  ///
157  /// Note that if CanApply returns false, that does not necessarily imply
158  /// that calling Apply will fail. Callers are expected to call CanApply
159  /// before calling Apply if they want to ensure that it is valid to
160  /// apply a schema.
161  ///
162  /// \sa UsdPrim::GetAppliedSchemas()
163  /// \sa UsdPrim::HasAPI()
164  /// \sa UsdPrim::CanApplyAPI()
165  /// \sa UsdPrim::ApplyAPI()
166  /// \sa UsdPrim::RemoveAPI()
167  ///
169  static bool
170  CanApply(const UsdPrim &prim, const TfToken &name,
171  std::string *whyNot=nullptr);
172 
173  /// Applies this <b>multiple-apply</b> API schema to the given \p prim
174  /// along with the given instance name, \p name.
175  ///
176  /// This information is stored by adding "PhysicsDriveAPI:<i>name</i>"
177  /// to the token-valued, listOp metadata \em apiSchemas on the prim.
178  /// For example, if \p name is 'instance1', the token
179  /// 'PhysicsDriveAPI:instance1' is added to 'apiSchemas'.
180  ///
181  /// \return A valid UsdPhysicsDriveAPI object is returned upon success.
182  /// An invalid (or empty) UsdPhysicsDriveAPI object is returned upon
183  /// failure. See \ref UsdPrim::ApplyAPI() for
184  /// conditions resulting in failure.
185  ///
186  /// \sa UsdPrim::GetAppliedSchemas()
187  /// \sa UsdPrim::HasAPI()
188  /// \sa UsdPrim::CanApplyAPI()
189  /// \sa UsdPrim::ApplyAPI()
190  /// \sa UsdPrim::RemoveAPI()
191  ///
193  static UsdPhysicsDriveAPI
194  Apply(const UsdPrim &prim, const TfToken &name);
195 
196 protected:
197  /// Returns the kind of schema this class belongs to.
198  ///
199  /// \sa UsdSchemaKind
201  UsdSchemaKind _GetSchemaKind() const override;
202 
203 private:
204  // needs to invoke _GetStaticTfType.
205  friend class UsdSchemaRegistry;
207  static const TfType &_GetStaticTfType();
208 
209  static bool _IsTypedSchema();
210 
211  // override SchemaBase virtuals.
213  const TfType &_GetTfType() const override;
214 
215 public:
216  // --------------------------------------------------------------------- //
217  // TYPE
218  // --------------------------------------------------------------------- //
219  /// Drive spring is for the acceleration at the joint (rather
220  /// than the force).
221  ///
222  /// | ||
223  /// | -- | -- |
224  /// | Declaration | `uniform token physics:type = "force"` |
225  /// | C++ Type | TfToken |
226  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Token |
227  /// | \ref SdfVariability "Variability" | SdfVariabilityUniform |
228  /// | \ref UsdPhysicsTokens "Allowed Values" | force, acceleration |
230  UsdAttribute GetTypeAttr() const;
231 
232  /// See GetTypeAttr(), 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 CreateTypeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
239 
240 public:
241  // --------------------------------------------------------------------- //
242  // MAXFORCE
243  // --------------------------------------------------------------------- //
244  /// Maximum force that can be applied to drive. Units:
245  /// if linear drive: mass*DIST_UNITS/second/second
246  /// if angular drive: mass*DIST_UNITS*DIST_UNITS/second/second
247  /// inf means not limited. Must be non-negative.
248  ///
249  ///
250  /// | ||
251  /// | -- | -- |
252  /// | Declaration | `float physics:maxForce = inf` |
253  /// | C++ Type | float |
254  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
257 
258  /// See GetMaxForceAttr(), and also
259  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
260  /// If specified, author \p defaultValue as the attribute's default,
261  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
262  /// the default for \p writeSparsely is \c false.
264  UsdAttribute CreateMaxForceAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
265 
266 public:
267  // --------------------------------------------------------------------- //
268  // TARGETPOSITION
269  // --------------------------------------------------------------------- //
270  /// Target value for position. Units:
271  /// if linear drive: distance
272  /// if angular drive: degrees.
273  ///
274  /// | ||
275  /// | -- | -- |
276  /// | Declaration | `float physics:targetPosition = 0` |
277  /// | C++ Type | float |
278  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
281 
282  /// See GetTargetPositionAttr(), and also
283  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
284  /// If specified, author \p defaultValue as the attribute's default,
285  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
286  /// the default for \p writeSparsely is \c false.
288  UsdAttribute CreateTargetPositionAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
289 
290 public:
291  // --------------------------------------------------------------------- //
292  // TARGETVELOCITY
293  // --------------------------------------------------------------------- //
294  /// Target value for velocity. Units:
295  /// if linear drive: distance/second
296  /// if angular drive: degrees/second.
297  ///
298  /// | ||
299  /// | -- | -- |
300  /// | Declaration | `float physics:targetVelocity = 0` |
301  /// | C++ Type | float |
302  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
305 
306  /// See GetTargetVelocityAttr(), and also
307  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
308  /// If specified, author \p defaultValue as the attribute's default,
309  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
310  /// the default for \p writeSparsely is \c false.
312  UsdAttribute CreateTargetVelocityAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
313 
314 public:
315  // --------------------------------------------------------------------- //
316  // DAMPING
317  // --------------------------------------------------------------------- //
318  /// Damping of the drive. Units:
319  /// if linear drive: mass/second
320  /// If angular drive: mass*DIST_UNITS*DIST_UNITS/second/degrees.
321  ///
322  /// | ||
323  /// | -- | -- |
324  /// | Declaration | `float physics:damping = 0` |
325  /// | C++ Type | float |
326  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
329 
330  /// See GetDampingAttr(), and also
331  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
332  /// If specified, author \p defaultValue as the attribute's default,
333  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
334  /// the default for \p writeSparsely is \c false.
336  UsdAttribute CreateDampingAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
337 
338 public:
339  // --------------------------------------------------------------------- //
340  // STIFFNESS
341  // --------------------------------------------------------------------- //
342  /// Stiffness of the drive. Units:
343  /// if linear drive: mass/second/second
344  /// if angular drive: mass*DIST_UNITS*DIST_UNITS/degrees/second/second.
345  ///
346  /// | ||
347  /// | -- | -- |
348  /// | Declaration | `float physics:stiffness = 0` |
349  /// | C++ Type | float |
350  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
353 
354  /// See GetStiffnessAttr(), and also
355  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
356  /// If specified, author \p defaultValue as the attribute's default,
357  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
358  /// the default for \p writeSparsely is \c false.
360  UsdAttribute CreateStiffnessAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
361 
362 public:
363  // ===================================================================== //
364  // Feel free to add custom code below this line, it will be preserved by
365  // the code generator.
366  //
367  // Just remember to:
368  // - Close the class declaration with };
369  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
370  // - Close the include guard with #endif
371  // ===================================================================== //
372  // --(BEGIN CUSTOM CODE)--
373 };
374 
376 
377 #endif
static USDPHYSICS_API std::vector< UsdPhysicsDriveAPI > GetAll(const UsdPrim &prim)
USDPHYSICS_API UsdAttribute CreateStiffnessAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDPHYSICS_API UsdSchemaKind _GetSchemaKind() const override
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
USDPHYSICS_API UsdAttribute GetDampingAttr() const
static USDPHYSICS_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
const TfToken & _GetInstanceName() const
USDPHYSICS_API UsdAttribute CreateDampingAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: token.h:70
USDPHYSICS_API UsdAttribute GetTargetPositionAttr() const
static USDPHYSICS_API bool CanApply(const UsdPrim &prim, const TfToken &name, std::string *whyNot=nullptr)
static USDPHYSICS_API bool IsSchemaPropertyBaseName(const TfToken &baseName)
UsdPhysicsDriveAPI(const UsdPrim &prim=UsdPrim(), const TfToken &name=TfToken())
Definition: driveAPI.h:70
static USDPHYSICS_API UsdPhysicsDriveAPI Apply(const UsdPrim &prim, const TfToken &name)
static USDPHYSICS_API bool IsPhysicsDriveAPIPath(const SdfPath &path, TfToken *name)
USDPHYSICS_API UsdAttribute GetMaxForceAttr() const
static const UsdSchemaKind schemaKind
Definition: driveAPI.h:59
USDPHYSICS_API UsdAttribute CreateTypeAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
Definition: prim.h:116
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
GLuint const GLchar * name
Definition: glcorearb.h:786
Definition: path.h:273
USDPHYSICS_API UsdAttribute GetStiffnessAttr() const
USDPHYSICS_API UsdAttribute CreateTargetVelocityAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
#define USDPHYSICS_API
Definition: api.h:23
UsdSchemaKind
Definition: common.h:112
USDPHYSICS_API UsdAttribute GetTypeAttr() const
virtual USDPHYSICS_API ~UsdPhysicsDriveAPI()
Destructor.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
static USDPHYSICS_API UsdPhysicsDriveAPI Get(const UsdStagePtr &stage, const SdfPath &path)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
Definition: type.h:47
UsdPhysicsDriveAPI(const UsdSchemaBase &schemaObj, const TfToken &name)
Definition: driveAPI.h:79
USDPHYSICS_API UsdAttribute CreateMaxForceAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
TfToken GetName() const
Returns the name of this multiple-apply schema instance.
Definition: driveAPI.h:105
USDPHYSICS_API UsdAttribute GetTargetVelocityAttr() const
Definition: value.h:146
Multiple Apply API Schema.
USDPHYSICS_API UsdAttribute CreateTargetPositionAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const