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_RIGIDBODY
15#define PX_PHYSICS_NX_RIGIDBODY
16/** \addtogroup physics
17@{
18*/
19
20#include "PxRigidActor.h"
21#include "PxForceMode.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28
29/**
30\brief Collection of flags describing the behavior of a rigid body.
31
32@see PxRigidBody.setRigidBodyFlag(), PxRigidBody.getRigidBodyFlags()
33*/
34
35struct PxRigidBodyFlag
36{
37 enum Enum
38 {
39
40 /**
41 \brief Enables kinematic mode for the actor.
42
43 Kinematic actors are special dynamic actors that are not
44 influenced by forces (such as gravity), and have no momentum. They are considered to have infinite
45 mass and can be moved around the world using the setKinematicTarget() method. They will push
46 regular dynamic actors out of the way. Kinematics will not collide with static or other kinematic objects.
47
48 Kinematic actors are great for moving platforms or characters, where direct motion control is desired.
49
50 You can not connect Reduced joints to kinematic actors. Lagrange joints work ok if the platform
51 is moving with a relatively low, uniform velocity.
52
53 <b>Sleeping:</b>
54 \li Setting this flag on a dynamic actor will put the actor to sleep and set the velocities to 0.
55 \li If this flag gets cleared, the current sleep state of the actor will be kept.
56
57 \note kinematic actors are incompatible with CCD so raising this flag will automatically clear eENABLE_CCD
58
59 @see PxRigidDynamic.setKinematicTarget()
60 */
61 eKINEMATIC = (1<<0), //!< Enable kinematic mode for the body.
62
63 /**
64 \brief Use the kinematic target transform for scene queries.
65
66 If this flag is raised, then scene queries will treat the kinematic target transform as the current pose
67 of the body (instead of using the actual pose). Without this flag, the kinematic target will only take
68 effect with respect to scene queries after a simulation step.
69
70 @see PxRigidDynamic.setKinematicTarget()
71 */
72 eUSE_KINEMATIC_TARGET_FOR_SCENE_QUERIES = (1<<1),
73
74 /**
75 \brief Enables swept integration for the actor.
76
77 If this flag is raised and CCD is enabled on the scene, then this body will be simulated by the CCD system to ensure that collisions are not missed due to
78 high-speed motion. Note individual shape pairs still need to enable PxPairFlag::eDETECT_CCD_CONTACT in the collision filtering to enable the CCD to respond to
79 individual interactions.
80
81 \note kinematic actors are incompatible with CCD so this flag will be cleared automatically when raised on a kinematic actor
82
83 */
84 eENABLE_CCD = (1<<2), //!< Enable CCD for the body.
85
86 /**
87 \brief Enabled CCD in swept integration for the actor.
88
89 If this flag is raised and CCD is enabled, CCD interactions will simulate friction. By default, friction is disabled in CCD interactions because
90 CCD friction has been observed to introduce some simulation artifacts. CCD friction was enabled in previous versions of the SDK. Raising this flag will result in behavior
91 that is a closer match for previous versions of the SDK.
92
93 \note This flag requires PxRigidBodyFlag::eENABLE_CCD to be raised to have any effect.
94 */
95 eENABLE_CCD_FRICTION = (1<<3)
96 };
97};
98
99/**
100\deprecated
101\brief A legacy typedef. PxRigidDynamicFlag has been deprecated in favor of PxRigidBodyFlag. Retained for compatibility with old API only.
102
103@see PxRigidBodyFlag
104*/
105
106typedef PX_DEPRECATED PxRigidBodyFlag PxRigidDynamicFlag;
107
108/**
109\brief collection of set bits defined in PxRigidBodyFlag.
110
111@see PxRigidBodyFlag
112*/
113typedef PxFlags<PxRigidBodyFlag::Enum,PxU8> PxRigidBodyFlags;
114PX_FLAGS_OPERATORS(PxRigidBodyFlag::Enum,PxU8)
115
116/**
117\brief collection of set bits defined in PxRigidDynamicFlag.
118\deprecated PxRigidDynamicFlag is deprecated. Please use PxRigidBodyFlag
119*/
120typedef PxFlags<PxRigidDynamicFlag::Enum,PxU8> PxRigidDynamicFlags;
121
122
123/**
124\brief PxRigidBody is a base class shared between dynamic rigid body objects.
125
126@see PxRigidActor
127*/
128
129class PxRigidBody : public PxRigidActor
130{
131public:
132 // Runtime modifications
133
134/************************************************************************************************/
135/** @name Mass Manipulation
136*/
137
138 /**
139 \brief Sets the pose of the center of mass relative to the actor.
140
141 \note Changing this transform will not move the actor in the world!
142
143 \note Setting an unrealistic center of mass which is a long way from the body can make it difficult for
144 the SDK to solve constraints. Perhaps leading to instability and jittering bodies.
145
146 <b>Default:</b> the identity transform
147
148 \param[in] pose Mass frame offset transform relative to the actor frame. <b>Range:</b> rigid body transform.
149
150 @see getCMassLocalPose() PxRigidBodyDesc.massLocalPose
151 */
152 virtual void setCMassLocalPose(const PxTransform& pose) = 0;
153
154
155 /**
156 \brief Retrieves the center of mass pose relative to the actor frame.
157
158 \return The center of mass pose relative to the actor frame.
159
160 @see setCMassLocalPose() PxRigidBodyDesc.massLocalPose
161 */
162 virtual PxTransform getCMassLocalPose() const = 0;
163
164
165 /**
166 \brief Sets the mass of a dynamic actor.
167
168 The mass must be non-negative.
169
170 setMass() does not update the inertial properties of the body, to change the inertia tensor
171 use setMassSpaceInertiaTensor() or the PhysX extensions method #PxRigidBodyExt::updateMassAndInertia().
172
173 \note A value of 0 is interpreted as infinite mass.
174 \note Values of 0 are not permitted for instances of PxArticulationLink but are permitted for instances of PxRigidDynamic.
175
176 <b>Default:</b> 1.0
177
178 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
179
180 \param[in] mass New mass value for the actor. <b>Range:</b> [0, PX_MAX_F32)
181
182 @see getMass() PxRigidBodyDesc.mass setMassSpaceInertiaTensor()
183 */
184 virtual void setMass(PxReal mass) = 0;
185
186 /**
187 \brief Retrieves the mass of the actor.
188
189 \note A value of 0 is interpreted as infinite mass.
190
191 \return The mass of this actor.
192
193 @see setMass() PxRigidBodyDesc.mass setMassSpaceInertiaTensor()
194 */
195 virtual PxReal getMass() const = 0;
196
197 /**
198 \brief Retrieves the inverse mass of the actor.
199
200 \return The inverse mass of this actor.
201
202 @see setMass() PxRigidBodyDesc.mass setMassSpaceInertiaTensor()
203 */
204 virtual PxReal getInvMass() const = 0;
205
206 /**
207 \brief Sets the inertia tensor, using a parameter specified in mass space coordinates.
208
209 Note that such matrices are diagonal -- the passed vector is the diagonal.
210
211 If you have a non diagonal world/actor space inertia tensor(3x3 matrix). Then you need to
212 diagonalize it and set an appropriate mass space transform. See #setCMassLocalPose().
213
214 The inertia tensor elements must be non-negative.
215
216 \note A value of 0 in an element is interpreted as infinite inertia along that axis.
217 \note Values of 0 are not permitted for instances of PxArticulationLink but are permitted for instances of PxRigidDynamic.
218
219 <b>Default:</b> (1.0, 1.0, 1.0)
220
221 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
222
223 \param[in] m New mass space inertia tensor for the actor.
224
225 @see PxRigidBodyDesc.massSpaceInertia getMassSpaceInertia() setMass() setCMassLocalPose()
226 */
227 virtual void setMassSpaceInertiaTensor(const PxVec3& m) = 0;
228
229 /**
230 \brief Retrieves the diagonal inertia tensor of the actor relative to the mass coordinate frame.
231
232 This method retrieves a mass frame inertia vector.
233
234 \return The mass space inertia tensor of this actor.
235
236 \note A value of 0 in an element is interpreted as infinite inertia along that axis.
237
238 @see PxRigidBodyDesc.massSpaceInertia setMassSpaceInertiaTensor() setMass() setCMassLocalPose()
239 */
240 virtual PxVec3 getMassSpaceInertiaTensor() const = 0;
241
242 /**
243 \brief Retrieves the diagonal inverse inertia tensor of the actor relative to the mass coordinate frame.
244
245 This method retrieves a mass frame inverse inertia vector.
246
247 \note A value of 0 in an element is interpreted as infinite inertia along that axis.
248
249 \return The mass space inverse inertia tensor of this actor.
250
251 @see PxRigidBodyDesc.massSpaceInertia setMassSpaceInertiaTensor() setMass() setCMassLocalPose()
252 */
253 virtual PxVec3 getMassSpaceInvInertiaTensor() const = 0;
254
255
256/************************************************************************************************/
257/** @name Velocity
258*/
259
260
261 /**
262 \brief Retrieves the linear velocity of an actor.
263
264 \return The linear velocity of the actor.
265
266 @see PxRigidDynamic.setLinearVelocity() getAngularVelocity()
267 */
268 virtual PxVec3 getLinearVelocity() const = 0;
269
270 /**
271 \brief Sets the linear velocity of the actor.
272
273 Note that if you continuously set the velocity of an actor yourself,
274 forces such as gravity or friction will not be able to manifest themselves, because forces directly
275 influence only the velocity/momentum of an actor.
276
277 <b>Default:</b> (0.0, 0.0, 0.0)
278
279 <b>Sleeping:</b> This call wakes the actor if it is sleeping, the autowake parameter is true (default) or the
280 new velocity is non-zero
281
282 \note It is invalid to use this method if PxActorFlag::eDISABLE_SIMULATION is set.
283
284 \param[in] linVel New linear velocity of actor. <b>Range:</b> velocity vector
285 \param[in] autowake Whether to wake the object up if it is asleep and the velocity is non-zero. If true and the current wake counter value is smaller than #PxSceneDesc::wakeCounterResetValue it will get increased to the reset value.
286
287 @see getLinearVelocity() setAngularVelocity()
288 */
289 virtual void setLinearVelocity(const PxVec3& linVel, bool autowake = true ) = 0;
290
291
292
293 /**
294 \brief Retrieves the angular velocity of the actor.
295
296 \return The angular velocity of the actor.
297
298 @see PxRigidDynamic.setAngularVelocity() getLinearVelocity()
299 */
300 virtual PxVec3 getAngularVelocity() const = 0;
301
302
303 /**
304 \brief Sets the angular velocity of the actor.
305
306 Note that if you continuously set the angular velocity of an actor yourself,
307 forces such as friction will not be able to rotate the actor, because forces directly influence only the velocity/momentum.
308
309 <b>Default:</b> (0.0, 0.0, 0.0)
310
311 <b>Sleeping:</b> This call wakes the actor if it is sleeping, the autowake parameter is true (default) or the
312 new velocity is non-zero
313
314 \note It is invalid to use this method if PxActorFlag::eDISABLE_SIMULATION is set.
315
316 \param[in] angVel New angular velocity of actor. <b>Range:</b> angular velocity vector
317 \param[in] autowake Whether to wake the object up if it is asleep and the velocity is non-zero. If true and the current wake
318 counter value is smaller than #PxSceneDesc::wakeCounterResetValue it will get increased to the reset value.
319
320 @see getAngularVelocity() setLinearVelocity()
321 */
322 virtual void setAngularVelocity(const PxVec3& angVel, bool autowake = true ) = 0;
323
324
325/************************************************************************************************/
326/** @name Forces
327*/
328
329 /**
330 \brief Applies a force (or impulse) defined in the global coordinate frame to the actor at its center of mass.
331
332 <b>This will not induce a torque</b>.
333
334 ::PxForceMode determines if the force is to be conventional or impulsive.
335
336 Each actor has an acceleration and a velocity change accumulator which are directly modified using the modes PxForceMode::eACCELERATION
337 and PxForceMode::eVELOCITY_CHANGE respectively. The modes PxForceMode::eFORCE and PxForceMode::eIMPULSE also modify these same
338 accumulators and are just short hand for multiplying the vector parameter by inverse mass and then using PxForceMode::eACCELERATION and
339 PxForceMode::eVELOCITY_CHANGE respectively.
340
341
342 \note It is invalid to use this method if the actor has not been added to a scene already or if PxActorFlag::eDISABLE_SIMULATION is set.
343
344 \note The force modes PxForceMode::eIMPULSE and PxForceMode::eVELOCITY_CHANGE can not be applied to articulation links.
345
346 \note if this is called on an articulation link, only the link is updated, not the entire articulation.
347
348 \note see #PxRigidBodyExt::computeVelocityDeltaFromImpulse for details of how to compute the change in linear velocity that
349 will arise from the application of an impulsive force, where an impulsive force is applied force multiplied by a timestep.
350
351 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the autowake parameter is true (default) or the force is non-zero.
352
353 \param[in] force Force/Impulse to apply defined in the global frame.
354 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode)
355 \param[in] autowake Specify if the call should wake up the actor if it is currently asleep. If true and the current wake counter value is smaller than #PxSceneDesc::wakeCounterResetValue it will get increased to the reset value.
356
357 @see PxForceMode addTorque
358 */
359 virtual void addForce(const PxVec3& force, PxForceMode::Enum mode = PxForceMode::eFORCE, bool autowake = true) = 0;
360
361 /**
362 \brief Applies an impulsive torque defined in the global coordinate frame to the actor.
363
364 ::PxForceMode determines if the torque is to be conventional or impulsive.
365
366 Each actor has an angular acceleration and an angular velocity change accumulator which are directly modified using the modes
367 PxForceMode::eACCELERATION and PxForceMode::eVELOCITY_CHANGE respectively. The modes PxForceMode::eFORCE and PxForceMode::eIMPULSE
368 also modify these same accumulators and are just short hand for multiplying the vector parameter by inverse inertia and then
369 using PxForceMode::eACCELERATION and PxForceMode::eVELOCITY_CHANGE respectively.
370
371
372 \note It is invalid to use this method if the actor has not been added to a scene already or if PxActorFlag::eDISABLE_SIMULATION is set.
373
374 \note The force modes PxForceMode::eIMPULSE and PxForceMode::eVELOCITY_CHANGE can not be applied to articulation links.
375
376 \note if this called on an articulation link, only the link is updated, not the entire articulation.
377
378 \note see #PxRigidBodyExt::computeVelocityDeltaFromImpulse for detatils of how to compute the change in angular velocity that
379 will arise from the application of an impulsive torque, where an impulsive torque is an applied torque multiplied by a timestep.
380
381 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the autowake parameter is true (default) or the torque is non-zero.
382
383 \param[in] torque Torque to apply defined in the global frame. <b>Range:</b> torque vector
384 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode).
385 \param[in] autowake whether to wake up the object if it is asleep. If true and the current wake counter value is smaller than #PxSceneDesc::wakeCounterResetValue it will get increased to the reset value.
386
387 @see PxForceMode addForce()
388 */
389 virtual void addTorque(const PxVec3& torque, PxForceMode::Enum mode = PxForceMode::eFORCE, bool autowake = true) = 0;
390
391 /**
392 \brief Clears the accumulated forces (sets the accumulated force back to zero).
393
394 Each actor has an acceleration and a velocity change accumulator which are directly modified using the modes PxForceMode::eACCELERATION
395 and PxForceMode::eVELOCITY_CHANGE respectively. The modes PxForceMode::eFORCE and PxForceMode::eIMPULSE also modify these same
396 accumulators (see PxRigidBody::addForce() for details); therefore the effect of calling clearForce(PxForceMode::eFORCE) is equivalent to calling
397 clearForce(PxForceMode::eACCELERATION), and the effect of calling clearForce(PxForceMode::eIMPULSE) is equivalent to calling
398 clearForce(PxForceMode::eVELOCITY_CHANGE).
399
400 ::PxForceMode determines if the cleared force is to be conventional or impulsive.
401
402 \note The force modes PxForceMode::eIMPULSE and PxForceMode::eVELOCITY_CHANGE can not be applied to articulation links.
403
404 \note It is invalid to use this method if the actor has not been added to a scene already or if PxActorFlag::eDISABLE_SIMULATION is set.
405
406 \param[in] mode The mode to use when clearing the force/impulse(see #PxForceMode)
407
408 @see PxForceMode addForce
409 */
410 virtual void clearForce(PxForceMode::Enum mode = PxForceMode::eFORCE) = 0;
411
412 /**
413 \brief Clears the impulsive torque defined in the global coordinate frame to the actor.
414
415 ::PxForceMode determines if the cleared torque is to be conventional or impulsive.
416
417 Each actor has an angular acceleration and a velocity change accumulator which are directly modified using the modes PxForceMode::eACCELERATION
418 and PxForceMode::eVELOCITY_CHANGE respectively. The modes PxForceMode::eFORCE and PxForceMode::eIMPULSE also modify these same
419 accumulators (see PxRigidBody::addTorque() for details); therefore the effect of calling clearTorque(PxForceMode::eFORCE) is equivalent to calling
420 clearTorque(PxForceMode::eACCELERATION), and the effect of calling clearTorque(PxForceMode::eIMPULSE) is equivalent to calling
421 clearTorque(PxForceMode::eVELOCITY_CHANGE).
422
423 \note The force modes PxForceMode::eIMPULSE and PxForceMode::eVELOCITY_CHANGE can not be applied to articulation links.
424
425 \note It is invalid to use this method if the actor has not been added to a scene already or if PxActorFlag::eDISABLE_SIMULATION is set.
426
427 \param[in] mode The mode to use when clearing the force/impulse(see #PxForceMode).
428
429 @see PxForceMode addTorque
430 */
431 virtual void clearTorque(PxForceMode::Enum mode = PxForceMode::eFORCE) = 0;
432
433 /**
434 \deprecated
435 \brief Raises or clears a particular dynamic rigid body flag.
436
437 See the list of flags #PxRigidBodyFlag
438
439 <b>Default:</b> no flags are set
440
441 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
442
443 \param[in] flag The PxRigidDynamic flag to raise(set) or clear. See #PxRigidDynamicFlag #PxRigidBodyFlag.
444 \param[in] value The new boolean value for the flag.
445
446 @see PxRigidDynamicFlag getRigidDynamicFlags()
447 */
448 PX_DEPRECATED virtual void setRigidDynamicFlag(PxRigidDynamicFlag::Enum flag, bool value) = 0;
449 PX_DEPRECATED virtual void setRigidDynamicFlags(PxRigidDynamicFlags inFlags) = 0;
450
451 /**
452 \brief Raises or clears a particular rigid body flag.
453
454 See the list of flags #PxRigidBodyFlag
455
456 <b>Default:</b> no flags are set
457
458 <b>Sleeping:</b> Does <b>NOT</b> wake the actor up automatically.
459
460 \param[in] flag The PxRigidBody flag to raise(set) or clear. See #PxRigidBodyFlag.
461 \param[in] value The new boolean value for the flag.
462
463 @see PxRigidBodyFlag getRigidBodyFlags()
464 */
465
466 virtual void setRigidBodyFlag(PxRigidBodyFlag::Enum flag, bool value) = 0;
467 virtual void setRigidBodyFlags(PxRigidBodyFlags inFlags) = 0;
468
469 /**
470 \deprecated
471 \brief Reads the PxRigidBody flags.
472
473 See the list of flags #PxRigidBodyFlag
474
475 \return The values of the PxRigidBody flags.
476
477 @see PxRigidDynamicFlag setRigidDynamicFlag()
478 */
479 PX_DEPRECATED virtual PxRigidDynamicFlags getRigidDynamicFlags() const = 0;
480
481 /**
482 \brief Reads the PxRigidBody flags.
483
484 See the list of flags #PxRigidBodyFlag
485
486 \return The values of the PxRigidBody flags.
487
488 @see PxRigidBodyFlag setRigidBodyFlag()
489 */
490 virtual PxRigidBodyFlags getRigidBodyFlags() const = 0;
491
492 /**
493 \brief Sets the CCD minimum advance coefficient.
494
495 The CCD minimum advance coefficient is a value in the range [0, 1] that is used to control the minimum amount of time a body is integrated when
496 it has a CCD contact. The actual minimum amount of time that is integrated depends on various properties, including the relative speed and collision shapes
497 of the bodies involved in the contact. From these properties, a numeric value is calculated that determines the maximum distance (and therefore maximum time)
498 which these bodies could be integrated forwards that would ensure that these bodies did not pass through each-other. This value is then scaled by CCD minimum advance
499 coefficient to determine the amount of time that will be consumed in the CCD pass.
500
501 <b>Things to consider:</b>
502 A large value (approaching 1) ensures that the objects will always advance some time. However, larger values increase the chances of objects gently drifting through each-other in
503 scenes which the constraint solver can't converge, e.g. scenes where an object is being dragged through a wall with a constraint.
504 A value of 0 ensures that the pair of objects stop at the exact time-of-impact and will not gently drift through each-other. However, with very small/thin objects initially in
505 contact, this can lead to a large amount of time being dropped and increases the chances of jamming. Jamming occurs when the an object is persistently in contact with an object
506 such that the time-of-impact is 0, which results in no time being advanced for those objects in that CCD pass.
507
508 The chances of jamming can be reduced by increasing the number of CCD mass @see PxSceneDesc.ccdMaxPasses. However, increasing this number increases the CCD overhead.
509
510 \param[in] advanceCoefficient The CCD min advance coefficient. <b>Range:</b> [0, 1] <b>Default:</b> 0.15
511 */
512
513 virtual void setMinCCDAdvanceCoefficient(PxReal advanceCoefficient) = 0;
514
515 /**
516 \brief Gets the CCD minimum advance coefficient.
517
518 \return The value of the CCD min advance coefficient.
519
520 @see setMinCCDAdvanceCoefficient
521
522 */
523
524 virtual PxReal getMinCCDAdvanceCoefficient() const = 0;
525
526
527 /**
528 \brief Sets the maximum depenetration velocity permitted to be introduced by the solver.
529 This value controls how much velocity the solver can introduce to correct for penetrations in contacts.
530 \param[in] biasClamp The maximum velocity to de-penetrate by <b>Range:</b> (0, PX_MAX_F32].
531 */
532 virtual void setMaxDepenetrationVelocity(const PxReal biasClamp) = 0;
533
534 /**
535 \brief Returns the maximum depenetration velocity the solver is permitted to introduced.
536 This value controls how much velocity the solver can introduce to correct for penetrations in contacts.
537 \return The maximum penetration bias applied by the solver.
538 */
539 virtual PxReal getMaxDepenetrationVelocity() const = 0;
540
541
542
543protected:
544 PX_INLINE PxRigidBody(PxType concreteType, PxBaseFlags baseFlags) : PxRigidActor(concreteType, baseFlags) {}
545 PX_INLINE PxRigidBody(PxBaseFlags baseFlags) : PxRigidActor(baseFlags) {}
546 virtual ~PxRigidBody() {}
547 virtual bool isKindOf(const char* name)const { return !strcmp("PxRigidBody", name) || PxRigidActor::isKindOf(name); }
548};
549
550PX_DEPRECATED PX_INLINE PxRigidBody* PxActor::isRigidBody() { return is<PxRigidBody>(); }
551PX_DEPRECATED PX_INLINE const PxRigidBody* PxActor::isRigidBody() const { return is<PxRigidBody>(); }
552
553
554#ifndef PX_DOXYGEN
555} // namespace physx
556#endif
557
558/** @} */
559#endif
560