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