1 | // |
2 | // Redistribution and use in source and binary forms, with or without |
3 | // modification, are permitted provided that the following conditions |
4 | // are met: |
5 | // * Redistributions of source code must retain the above copyright |
6 | // notice, this list of conditions and the following disclaimer. |
7 | // * Redistributions in binary form must reproduce the above copyright |
8 | // notice, this list of conditions and the following disclaimer in the |
9 | // documentation and/or other materials provided with the distribution. |
10 | // * Neither the name of NVIDIA CORPORATION nor the names of its |
11 | // contributors may be used to endorse or promote products derived |
12 | // from this software without specific prior written permission. |
13 | // |
14 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY |
15 | // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
16 | // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR |
17 | // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR |
18 | // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
19 | // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
20 | // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
21 | // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY |
22 | // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
23 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
24 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
25 | // |
26 | // Copyright (c) 2008-2021 NVIDIA Corporation. All rights reserved. |
27 | // Copyright (c) 2004-2008 AGEIA Technologies, Inc. All rights reserved. |
28 | // Copyright (c) 2001-2004 NovodeX AG. All rights reserved. |
29 | |
30 | |
31 | #ifndef PX_PHYSICS_NX_ARTICULATION_JOINT |
32 | #define PX_PHYSICS_NX_ARTICULATION_JOINT |
33 | /** \addtogroup physics |
34 | @{ */ |
35 | |
36 | #include "PxPhysXConfig.h" |
37 | #include "common/PxBase.h" |
38 | #include "solver/PxSolverDefs.h" |
39 | |
40 | #if !PX_DOXYGEN |
41 | namespace physx |
42 | { |
43 | #endif |
44 | |
45 | class PxArticulationJointImpl; |
46 | |
47 | /** |
48 | \brief The type of joint drive to use for the articulation joint. |
49 | |
50 | Two drive models are currently supported. in the TARGET model, the drive spring displacement will be determined |
51 | as the rotation vector from the relative quaternion beetween child and parent, and the target quaternion. |
52 | |
53 | In the ERROR model, the drive spring displacement will be taken directly from the imaginary part of the relative |
54 | quaternion. This drive model requires more computation on the part of the application, but allows driving the joint |
55 | with a spring displacement that is more than a complete rotation. |
56 | |
57 | @see PxArticulationJoint |
58 | */ |
59 | |
60 | struct PxArticulationJointDriveType |
61 | { |
62 | enum Enum |
63 | { |
64 | eTARGET = 0, // use the quaternion as the drive target |
65 | eERROR = 1 // use the vector part of the quaternion as the drive error. |
66 | }; |
67 | }; |
68 | |
69 | class PxArticulationJointBase : public PxBase |
70 | { |
71 | public: |
72 | /** |
73 | \brief get the parent articulation link to which this articulation joint belongs |
74 | |
75 | \return the articulation link to which this joint belongs |
76 | */ |
77 | virtual PxArticulationLink& getParentArticulationLink() const = 0; |
78 | |
79 | /** |
80 | \brief set the joint pose in the parent frame |
81 | |
82 | \param[in] pose the joint pose in the parent frame |
83 | <b>Default:</b> the identity matrix |
84 | |
85 | @see getParentPose() |
86 | */ |
87 | virtual void setParentPose(const PxTransform& pose) = 0; |
88 | |
89 | /** |
90 | \brief get the joint pose in the parent frame |
91 | |
92 | \return the joint pose in the parent frame |
93 | |
94 | @see setParentPose() |
95 | */ |
96 | virtual PxTransform getParentPose() const = 0; |
97 | |
98 | /** |
99 | \brief get the child articulation link to which this articulation joint belongs |
100 | |
101 | \return the articulation link to which this joint belongs |
102 | */ |
103 | virtual PxArticulationLink& getChildArticulationLink() const = 0; |
104 | |
105 | /** |
106 | \brief set the joint pose in the child frame |
107 | |
108 | \param[in] pose the joint pose in the child frame |
109 | <b>Default:</b> the identity matrix |
110 | |
111 | @see getChildPose() |
112 | */ |
113 | virtual void setChildPose(const PxTransform& pose) = 0; |
114 | |
115 | /** |
116 | \brief get the joint pose in the child frame |
117 | |
118 | \return the joint pose in the child frame |
119 | |
120 | @see setChildPose() |
121 | */ |
122 | virtual PxTransform getChildPose() const = 0; |
123 | |
124 | virtual PxArticulationJointImpl* getImpl() = 0; |
125 | virtual const PxArticulationJointImpl* getImpl() const = 0; |
126 | |
127 | virtual ~PxArticulationJointBase() {} |
128 | |
129 | private: |
130 | protected: |
131 | PX_INLINE PxArticulationJointBase(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags) {} |
132 | PX_INLINE PxArticulationJointBase(PxBaseFlags baseFlags) : PxBase(baseFlags) {} |
133 | |
134 | virtual bool isKindOf(const char* name) const { return !::strcmp(s1: "PxArticulationJointBase" , s2: name) || PxBase::isKindOf(superClass: name); } |
135 | }; |
136 | |
137 | |
138 | |
139 | /** |
140 | \brief a joint between two links in an articulation. |
141 | |
142 | The joint model is very similar to a PxSphericalJoint with swing and twist limits, |
143 | and an implicit drive model. |
144 | |
145 | @see PxArticulation PxArticulationLink |
146 | */ |
147 | |
148 | class PxArticulationJoint : public PxArticulationJointBase |
149 | { |
150 | public: |
151 | |
152 | /** |
153 | \brief set the target drive |
154 | |
155 | This is the target position for the joint drive, measured in the parent constraint frame. |
156 | |
157 | \param[in] orientation the target orientation for the joint |
158 | <b>Range:</b> a unit quaternion |
159 | <b>Default:</b> the identity quaternion |
160 | |
161 | @see getTargetOrientation() |
162 | */ |
163 | virtual void setTargetOrientation(const PxQuat& orientation) = 0; |
164 | |
165 | /** |
166 | \brief get the target drive position |
167 | |
168 | \return the joint drive target position |
169 | |
170 | @see setTargetOrientation() |
171 | */ |
172 | virtual PxQuat getTargetOrientation() const = 0; |
173 | |
174 | /** |
175 | \brief set the target drive velocity |
176 | |
177 | This is the target velocity for the joint drive, measured in the parent constraint frame |
178 | |
179 | \param[in] velocity the target velocity for the joint |
180 | <b>Default:</b> the zero vector |
181 | |
182 | @see getTargetVelocity() |
183 | */ |
184 | virtual void setTargetVelocity(const PxVec3& velocity) = 0; |
185 | |
186 | /** |
187 | \brief get the target drive velocity |
188 | |
189 | \return the target velocity for the joint |
190 | |
191 | @see setTargetVelocity() |
192 | */ |
193 | virtual PxVec3 getTargetVelocity() const = 0; |
194 | |
195 | /** |
196 | \brief set the drive type |
197 | |
198 | \param[in] driveType the drive type for the joint |
199 | <b>Default:</b> PxArticulationJointDriveType::eTARGET |
200 | |
201 | @see getDriveType() |
202 | */ |
203 | virtual void setDriveType(PxArticulationJointDriveType::Enum driveType) = 0; |
204 | |
205 | /** |
206 | \brief get the drive type |
207 | |
208 | \return the drive type |
209 | |
210 | @see setDriveType() |
211 | */ |
212 | virtual PxArticulationJointDriveType::Enum getDriveType() const = 0; |
213 | |
214 | /** |
215 | \brief set the drive strength of the joint acceleration spring. |
216 | |
217 | The acceleration generated by the spring drive is proportional to |
218 | this value and the angle between the drive target position and the |
219 | current position. |
220 | |
221 | \param[in] spring the spring strength of the joint |
222 | <b>Range:</b> [0, PX_MAX_F32)<br> |
223 | <b>Default:</b> 0.0 |
224 | |
225 | @see getStiffness() |
226 | */ |
227 | virtual void setStiffness(PxReal spring) = 0; |
228 | |
229 | /** |
230 | \brief get the drive strength of the joint acceleration spring |
231 | |
232 | \return the spring strength of the joint |
233 | |
234 | @see setStiffness() |
235 | */ |
236 | virtual PxReal getStiffness() const = 0; |
237 | |
238 | /** |
239 | \brief set the damping of the joint acceleration spring |
240 | |
241 | The acceleration generated by the spring drive is proportional to |
242 | this value and the difference between the angular velocity of the |
243 | joint and the target drive velocity. |
244 | |
245 | \param[in] damping the damping of the joint drive |
246 | <b>Range:</b> [0, PX_MAX_F32)<br> |
247 | <b>Default:</b> 0.0 |
248 | |
249 | @see getDamping() |
250 | */ |
251 | virtual void setDamping(PxReal damping) = 0; |
252 | |
253 | /** |
254 | \brief get the damping of the joint acceleration spring |
255 | |
256 | @see setDamping() |
257 | */ |
258 | virtual PxReal getDamping() const = 0; |
259 | |
260 | /** |
261 | \brief set the internal compliance |
262 | |
263 | Compliance determines the extent to which the joint resists acceleration. |
264 | |
265 | There are separate values for resistance to accelerations caused by external |
266 | forces such as gravity and contact forces, and internal forces generated from |
267 | other joints. |
268 | |
269 | A low compliance means that forces have little effect, a compliance of 1 means |
270 | the joint does not resist such forces at all. |
271 | |
272 | \param[in] compliance the compliance to internal forces |
273 | <b> Range: (0, 1]</b> |
274 | <b> Default:</b> 0.0 |
275 | |
276 | @see getInternalCompliance() |
277 | */ |
278 | virtual void setInternalCompliance(PxReal compliance) = 0; |
279 | |
280 | /** |
281 | \brief get the internal compliance |
282 | |
283 | \return the compliance to internal forces |
284 | |
285 | @see setInternalCompliance() |
286 | */ |
287 | virtual PxReal getInternalCompliance() const = 0; |
288 | |
289 | /** |
290 | \brief get the drive external compliance |
291 | |
292 | Compliance determines the extent to which the joint resists acceleration. |
293 | |
294 | There are separate values for resistance to accelerations caused by external |
295 | forces such as gravity and contact forces, and internal forces generated from |
296 | other joints. |
297 | |
298 | A low compliance means that forces have little effect, a compliance of 1 means |
299 | the joint does not resist such forces at all. |
300 | |
301 | \param[in] compliance the compliance to external forces |
302 | <b> Range: (0, 1]</b> |
303 | <b> Default:</b> 0.0 |
304 | |
305 | @see getExternalCompliance() |
306 | */ |
307 | virtual void setExternalCompliance(PxReal compliance) = 0; |
308 | |
309 | /** |
310 | \brief get the drive external compliance |
311 | |
312 | \return the compliance to external forces |
313 | |
314 | @see setExternalCompliance() |
315 | */ |
316 | virtual PxReal getExternalCompliance() const = 0; |
317 | |
318 | /** |
319 | \brief set the extents of the cone limit. The extents are measured in the frame |
320 | of the parent. |
321 | |
322 | Note that very small or highly elliptical limit cones may result in jitter. |
323 | |
324 | \param[in] zLimit the allowed extent of rotation around the z-axis |
325 | \param[in] yLimit the allowed extent of rotation around the y-axis |
326 | <b> Range:</b> ( (0, Pi), (0, Pi) ) |
327 | <b> Default:</b> (Pi/4, Pi/4) |
328 | |
329 | \note Please note the order of zLimit and yLimit. |
330 | */ |
331 | virtual void setSwingLimit(PxReal zLimit, PxReal yLimit) = 0; |
332 | |
333 | /** |
334 | \brief get the extents for the swing limit cone |
335 | |
336 | \param[out] zLimit the allowed extent of rotation around the z-axis |
337 | \param[out] yLimit the allowed extent of rotation around the y-axis |
338 | |
339 | \note Please note the order of zLimit and yLimit. |
340 | |
341 | @see setSwingLimit() |
342 | */ |
343 | virtual void getSwingLimit(PxReal& zLimit, PxReal& yLimit) const = 0; |
344 | |
345 | /** |
346 | \brief set the tangential spring for the limit cone |
347 | <b> Range:</b> ([0, PX_MAX_F32), [0, PX_MAX_F32)) |
348 | <b> Default:</b> (0.0, 0.0) |
349 | */ |
350 | virtual void setTangentialStiffness(PxReal spring) = 0; |
351 | |
352 | /** |
353 | \brief get the tangential spring for the swing limit cone |
354 | |
355 | \return the tangential spring |
356 | |
357 | @see setTangentialStiffness() |
358 | */ |
359 | virtual PxReal getTangentialStiffness() const = 0; |
360 | |
361 | /** |
362 | \brief set the tangential damping for the limit cone |
363 | <b> Range:</b> ([0, PX_MAX_F32), [0, PX_MAX_F32)) |
364 | <b> Default:</b> (0.0, 0.0) |
365 | */ |
366 | virtual void setTangentialDamping(PxReal damping) = 0; |
367 | |
368 | /** |
369 | \brief get the tangential damping for the swing limit cone |
370 | |
371 | \return the tangential damping |
372 | |
373 | @see setTangentialDamping() |
374 | */ |
375 | virtual PxReal getTangentialDamping() const = 0; |
376 | |
377 | /** |
378 | \brief set the contact distance for the swing limit |
379 | |
380 | The contact distance should be less than either limit angle. |
381 | |
382 | <b> Range:</b> [0, Pi] |
383 | <b> Default:</b> 0.05 radians |
384 | |
385 | @see getSwingLimitContactDistance() |
386 | */ |
387 | virtual void setSwingLimitContactDistance(PxReal contactDistance) = 0; |
388 | |
389 | /** |
390 | \brief get the contact distance for the swing limit |
391 | |
392 | \return the contact distance for the swing limit cone |
393 | |
394 | @see setSwingLimitContactDistance() |
395 | */ |
396 | virtual PxReal getSwingLimitContactDistance() const = 0; |
397 | |
398 | /** |
399 | \brief set the flag which enables the swing limit |
400 | |
401 | \param[in] enabled whether the limit is enabled |
402 | <b>Default:</b> false |
403 | |
404 | @see getSwingLimitEnabled() |
405 | */ |
406 | virtual void setSwingLimitEnabled(bool enabled) = 0; |
407 | |
408 | /** |
409 | \brief get the flag which enables the swing limit |
410 | |
411 | \return whether the swing limit is enabled |
412 | |
413 | @see setSwingLimitEnabled() |
414 | */ |
415 | virtual bool getSwingLimitEnabled() const = 0; |
416 | |
417 | /** |
418 | \brief set the bounds of the twistLimit |
419 | |
420 | \param[in] lower the lower extent of the twist limit |
421 | \param[in] upper the upper extent of the twist limit |
422 | <b> Range: (-Pi, Pi)</b> |
423 | <b> Default:</b> (-Pi/4, Pi/4) |
424 | |
425 | The lower limit value must be less than the upper limit if the limit is enabled |
426 | |
427 | @see getTwistLimit() |
428 | */ |
429 | virtual void setTwistLimit(PxReal lower, PxReal upper) = 0; |
430 | |
431 | /** |
432 | \brief get the bounds of the twistLimit |
433 | |
434 | \param[out] lower the lower extent of the twist limit |
435 | \param[out] upper the upper extent of the twist limit |
436 | |
437 | @see setTwistLimit() |
438 | */ |
439 | virtual void getTwistLimit(PxReal &lower, PxReal &upper) const = 0; |
440 | |
441 | /** |
442 | \brief set the flag which enables the twist limit |
443 | |
444 | \param[in] enabled whether the twist limit is enabled |
445 | <b>Default:</b> false |
446 | |
447 | @see getTwistLimitEnabled() |
448 | */ |
449 | virtual void setTwistLimitEnabled(bool enabled) = 0; |
450 | |
451 | /** |
452 | \brief get the twistLimitEnabled flag |
453 | |
454 | \return whether the twist limit is enabled |
455 | |
456 | @see setTwistLimitEnabled() |
457 | */ |
458 | virtual bool getTwistLimitEnabled() const = 0; |
459 | |
460 | /** |
461 | \brief set the contact distance for the swing limit |
462 | |
463 | The contact distance should be less than half the distance between the upper and lower limits. |
464 | |
465 | <b> Range:</b> [0, Pi) |
466 | <b> Default:</b> 0.05 radians |
467 | |
468 | @see getTwistLimitContactDistance() |
469 | */ |
470 | virtual void setTwistLimitContactDistance(PxReal contactDistance) = 0; |
471 | |
472 | /** |
473 | \brief get the contact distance for the swing limit |
474 | |
475 | \return the contact distance for the twist limit |
476 | |
477 | @see setTwistLimitContactDistance() |
478 | */ |
479 | virtual PxReal getTwistLimitContactDistance() const = 0; |
480 | |
481 | virtual const char* getConcreteTypeName() const { return "PxArticulationJoint" ; } |
482 | |
483 | protected: |
484 | PX_INLINE PxArticulationJoint(PxType concreteType, PxBaseFlags baseFlags) : PxArticulationJointBase(concreteType, baseFlags) {} |
485 | PX_INLINE PxArticulationJoint(PxBaseFlags baseFlags) : PxArticulationJointBase(baseFlags) {} |
486 | virtual ~PxArticulationJoint() {} |
487 | virtual bool isKindOf(const char* name) const { return !::strcmp(s1: "PxArticulationJoint" , s2: name) || PxArticulationJointBase::isKindOf(name); } |
488 | }; |
489 | |
490 | #if !PX_DOXYGEN |
491 | } // namespace physx |
492 | #endif |
493 | |
494 | /** @} */ |
495 | #endif |
496 | |