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_RIGIDDYNAMIC
15#define PX_PHYSICS_NX_RIGIDDYNAMIC
16/** \addtogroup physics
17@{
18*/
19
20#include "PxRigidBody.h"
21
22#ifndef PX_DOXYGEN
23namespace physx
24{
25#endif
26
27/**
28\brief PxRigidDynamic represents a dynamic rigid simulation object in the physics SDK.
29
30<h3>Creation</h3>
31Instances of this class are created by calling #PxPhysics::createRigidDynamic() and deleted with #release().
32
33
34<h3>Visualizations</h3>
35\li #PxVisualizationParameter::eACTOR_AXES
36\li #PxVisualizationParameter::eBODY_AXES
37\li #PxVisualizationParameter::eBODY_MASS_AXES
38\li #PxVisualizationParameter::eBODY_LIN_VELOCITY
39\li #PxVisualizationParameter::eBODY_ANG_VELOCITY
40\li #PxVisualizationParameter::eBODY_JOINT_GROUPS
41
42@see PxRigidBody PxPhysics.createRigidDynamic() release()
43*/
44
45class PxRigidDynamic : public PxRigidBody
46{
47public:
48 // Runtime modifications
49
50
51/************************************************************************************************/
52/** @name Kinematic Actors
53*/
54
55 /**
56 \brief Moves kinematically controlled dynamic actors through the game world.
57
58 You set a dynamic actor to be kinematic using the PxRigidBodyFlag::eKINEMATIC flag
59 with setRigidBodyFlag().
60
61 The move command will result in a velocity that will move the body into
62 the desired pose. After the move is carried out during a single time step,
63 the velocity is returned to zero. Thus, you must continuously call
64 this in every time step for kinematic actors so that they move along a path.
65
66 This function simply stores the move destination until the next simulation
67 step is processed, so consecutive calls will simply overwrite the stored target variable.
68
69 The motion is always fully carried out.
70
71 \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.
72
73 <b>Sleeping:</b> This call wakes the actor if it is sleeping and will set the wake counter to #PxSceneDesc::wakeCounterResetValue.
74
75 \param[in] destination The desired pose for the kinematic actor, in the global frame. <b>Range:</b> rigid body transform.
76
77 @see getKinematicTarget() PxRigidBodyFlag setRigidBodyFlag()
78 */
79 virtual void setKinematicTarget(const PxTransform& destination) = 0;
80
81 /**
82 \brief Get target pose of a kinematically controlled dynamic actor.
83
84 \param[out] target Transform to write the target pose to. Only valid if the method returns true.
85 \return True if the actor is a kinematically controlled dynamic and the target has been set, else False.
86
87 @see setKinematicTarget() PxRigidBodyFlag setRigidBodyFlag()
88 */
89 virtual bool getKinematicTarget(PxTransform& target) = 0;
90
91/************************************************************************************************/
92/** @name Damping
93*/
94
95 /**
96 \brief Sets the linear damping coefficient.
97
98 Zero represents no damping. The damping coefficient must be nonnegative.
99
100 <b>Default:</b> 0.0
101
102 \param[in] linDamp Linear damping coefficient. <b>Range:</b> [0, PX_MAX_F32)
103
104 @see getLinearDamping() setAngularDamping()
105 */
106 virtual void setLinearDamping(PxReal linDamp) = 0;
107
108 /**
109 \brief Retrieves the linear damping coefficient.
110
111 \return The linear damping coefficient associated with this actor.
112
113 @see setLinearDamping() getAngularDamping()
114 */
115 virtual PxReal getLinearDamping() const = 0;
116
117 /**
118 \brief Sets the angular damping coefficient.
119
120 Zero represents no damping.
121
122 The angular damping coefficient must be nonnegative.
123
124 <b>Default:</b> 0.05
125
126 \param[in] angDamp Angular damping coefficient. <b>Range:</b> [0, PX_MAX_F32)
127
128 @see getAngularDamping() setLinearDamping()
129 */
130 virtual void setAngularDamping(PxReal angDamp) = 0;
131
132 /**
133 \brief Retrieves the angular damping coefficient.
134
135 \return The angular damping coefficient associated with this actor.
136
137 @see setAngularDamping() getLinearDamping()
138 */
139 virtual PxReal getAngularDamping() const = 0;
140
141/************************************************************************************************/
142/** @name Velocity
143*/
144
145 /**
146 \brief Lets you set the maximum angular velocity permitted for this actor.
147
148 For various internal computations, very quickly rotating actors introduce error
149 into the simulation, which leads to undesired results.
150
151 With this function, you can set the maximum angular velocity permitted for this rigid body.
152 Higher angular velocities are clamped to this value.
153
154 Note: The angular velocity is clamped to the set value <i>before</i> the solver, which means that
155 the limit may still be momentarily exceeded.
156
157 <b>Default:</b> 7.0
158
159 \param[in] maxAngVel Max allowable angular velocity for actor. <b>Range:</b> [0, PX_MAX_F32)
160
161 @see getMaxAngularVelocity()
162 */
163 virtual void setMaxAngularVelocity(PxReal maxAngVel) = 0;
164
165 /**
166 \brief Retrieves the maximum angular velocity permitted for this actor.
167
168 \return The maximum allowed angular velocity for this actor.
169
170 @see setMaxAngularVelocity
171 */
172 virtual PxReal getMaxAngularVelocity() const = 0;
173
174/************************************************************************************************/
175/** @name Sleeping
176*/
177
178 /**
179 \brief Returns true if this body is sleeping.
180
181 When an actor does not move for a period of time, it is no longer simulated in order to save time. This state
182 is called sleeping. However, because the object automatically wakes up when it is either touched by an awake object,
183 or one of its properties is changed by the user, the entire sleep mechanism should be transparent to the user.
184
185 In general, a dynamic rigid actor is guaranteed to be awake if at least one of the following holds:
186
187 \li The wake counter is positive (see #setWakeCounter()).
188 \li The linear or angular velocity is non-zero.
189 \li A non-zero force or torque has been applied.
190
191 If a dynamic rigid actor is sleeping, the following state is guaranteed:
192
193 \li The wake counter is zero.
194 \li The linear and angular velocity is zero.
195 \li There is no force update pending.
196
197 When an actor gets inserted into a scene, it will be considered asleep if all the points above hold, else it will be treated as awake.
198
199 If an actor is asleep after the call to PxScene::fetchResults() returns, it is guaranteed that the pose of the actor
200 was not changed. You can use this information to avoid updating the transforms of associated objects.
201
202 \note A kinematic actor is asleep unless a target pose has been set (in which case it will stay awake until the end of the next
203 simulation step where no target pose has been set anymore). The wake counter will get set to zero or to the reset value
204 #PxSceneDesc::wakeCounterResetValue in the case where a target pose has been set to be consistent with the definitions above.
205
206 \note It is invalid to use this method if the actor has not been added to a scene already.
207
208 \return True if the actor is sleeping.
209
210 @see isSleeping() wakeUp() putToSleep() getSleepThreshold()
211 */
212 virtual bool isSleeping() const = 0;
213
214
215 /**
216 \brief Sets the mass-normalized kinetic energy threshold below which an actor may go to sleep.
217
218 Actors whose kinetic energy divided by their mass is below this threshold will be candidates for sleeping.
219
220 <b>Default:</b> 5e-5f * PxTolerancesScale::speed * PxTolerancesScale::speed
221
222 \param[in] threshold Energy below which an actor may go to sleep. <b>Range:</b> [0, PX_MAX_F32)
223
224 @see isSleeping() getSleepThreshold() wakeUp() putToSleep() PxTolerancesScale
225 */
226 virtual void setSleepThreshold(PxReal threshold) = 0;
227
228 /**
229 \brief Returns the mass-normalized kinetic energy below which an actor may go to sleep.
230
231 \return The energy threshold for sleeping.
232
233 @see isSleeping() wakeUp() putToSleep() setSleepThreshold()
234 */
235 virtual PxReal getSleepThreshold() const = 0;
236
237 /**
238 \brief Sets the mass-normalized kinetic energy threshold below which an actor may participate in stabilization.
239
240 Actors whose kinetic energy divided by their mass is above this threshold will not participate in stabilization.
241
242 This value has no effect if PxSceneFlag::eENABLE_STABILIZATION was not enabled on the PxSceneDesc.
243
244 <b>Default:</b> 1e-5f * PxTolerancesScale::speed * PxTolerancesScale::speed
245
246 \param[in] threshold Energy below which an actor may participate in stabilization. <b>Range:</b> (0,inf]
247
248 @see getStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION
249 */
250 virtual void setStabilizationThreshold(PxReal threshold) = 0;
251
252 /**
253 \brief Returns the mass-normalized kinetic energy below which an actor may participate in stabilization.
254
255 Actors whose kinetic energy divided by their mass is above this threshold will not participate in stabilization.
256
257 \return The energy threshold for participating in stabilization.
258
259 @see setStabilizationThreshold() PxSceneFlag::eENABLE_STABILIZATION
260 */
261 virtual PxReal getStabilizationThreshold() const = 0;
262
263
264 /**
265 \brief Sets the wake counter for the actor.
266
267 The wake counter value determines the minimum amount of time until the body can be put to sleep. Please note
268 that a body will not be put to sleep if the energy is above the specified threshold (see #setSleepThreshold())
269 or if other awake bodies are touching it.
270
271 \note Passing in a positive value will wake the actor up automatically.
272
273 \note It is invalid to use this method for kinematic actors since the wake counter for kinematics is defined
274 based on whether a target pose has been set (see the comment in #isSleeping()).
275
276 \note It is invalid to use this method if PxActorFlag::eDISABLE_SIMULATION is set.
277
278 <b>Default:</b> 0.4 (which corresponds to 20 frames for a time step of 0.02)
279
280 \param[in] wakeCounterValue Wake counter value. <b>Range:</b> [0, PX_MAX_F32)
281
282 @see isSleeping() getWakeCounter()
283 */
284 virtual void setWakeCounter(PxReal wakeCounterValue) = 0;
285
286 /**
287 \brief Returns the wake counter of the actor.
288
289 \return The wake counter of the actor.
290
291 @see isSleeping() setWakeCounter()
292 */
293 virtual PxReal getWakeCounter() const = 0;
294
295 /**
296 \brief Wakes up the actor if it is sleeping.
297
298 The actor will get woken up and might cause other touching actors to wake up as well during the next simulation step.
299
300 \note This will set the wake counter of the actor to the value specified in #PxSceneDesc::wakeCounterResetValue.
301
302 \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.
303
304 \note It is invalid to use this method for kinematic actors since the sleep state for kinematics is defined
305 based on whether a target pose has been set (see the comment in #isSleeping()).
306
307 @see isSleeping() putToSleep()
308 */
309 virtual void wakeUp() = 0;
310
311 /**
312 \brief Forces the actor to sleep.
313
314 The actor will stay asleep during the next simulation step if not touched by another non-sleeping actor.
315
316 \note Any applied force will be cleared and the velocity and the wake counter of the actor will be set to 0.
317
318 \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.
319
320 \note It is invalid to use this method for kinematic actors since the sleep state for kinematics is defined
321 based on whether a target pose has been set (see the comment in #isSleeping()).
322
323 @see isSleeping() wakeUp()
324 */
325 virtual void putToSleep() = 0;
326
327/************************************************************************************************/
328
329 /**
330 \brief Sets the solver iteration counts for the body.
331
332 The solver iteration count determines how accurately joints and contacts are resolved.
333 If you are having trouble with jointed bodies oscillating and behaving erratically, then
334 setting a higher position iteration count may improve their stability.
335
336 If intersecting bodies are being depenetrated too violently, increase the number of velocity
337 iterations. More velocity iterations will drive the relative exit velocity of the intersecting
338 objects closer to the correct value given the restitution.
339
340 <b>Default:</b> 4 position iterations, 1 velocity iteration
341
342 \param[in] minPositionIters Number of position iterations the solver should perform for this body. <b>Range:</b> [1,255]
343 \param[in] minVelocityIters Number of velocity iterations the solver should perform for this body. <b>Range:</b> [1,255]
344
345 @see getSolverIterationCounts()
346 */
347 virtual void setSolverIterationCounts(PxU32 minPositionIters, PxU32 minVelocityIters = 1) = 0;
348
349 /**
350 \brief Retrieves the solver iteration counts.
351
352 @see setSolverIterationCounts()
353 */
354 virtual void getSolverIterationCounts(PxU32& minPositionIters, PxU32& minVelocityIters) const = 0;
355
356 /**
357 \brief Retrieves the force threshold for contact reports.
358
359 The contact report threshold is a force threshold. If the force between
360 two actors exceeds this threshold for either of the two actors, a contact report
361 will be generated according to the contact report threshold flags provided by
362 the filter shader/callback.
363 See #PxPairFlag.
364
365 The threshold used for a collision between a dynamic actor and the static environment is
366 the threshold of the dynamic actor, and all contacts with static actors are summed to find
367 the total normal force.
368
369 <b>Default:</b> PX_MAX_F32
370
371 \return Force threshold for contact reports.
372
373 @see setContactReportThreshold PxPairFlag PxSimulationFilterShader PxSimulationFilterCallback
374 */
375 virtual PxReal getContactReportThreshold() const = 0;
376
377 /**
378 \brief Sets the force threshold for contact reports.
379
380 See #getContactReportThreshold().
381
382 \param[in] threshold Force threshold for contact reports. <b>Range:</b> [0, PX_MAX_F32)
383
384 @see getContactReportThreshold PxPairFlag
385 */
386 virtual void setContactReportThreshold(PxReal threshold) = 0;
387
388 virtual const char* getConcreteTypeName() const { return "PxRigidDynamic"; }
389
390protected:
391 PX_INLINE PxRigidDynamic(PxType concreteType, PxBaseFlags baseFlags) : PxRigidBody(concreteType, baseFlags) {}
392 PX_INLINE PxRigidDynamic(PxBaseFlags baseFlags) : PxRigidBody(baseFlags) {}
393 virtual ~PxRigidDynamic() {}
394 virtual bool isKindOf(const char* name) const { return !strcmp("PxRigidDynamic", name) || PxRigidBody::isKindOf(name); }
395
396};
397
398PX_DEPRECATED PX_INLINE PxRigidDynamic* PxActor::isRigidDynamic() { return is<PxRigidDynamic>(); }
399PX_DEPRECATED PX_INLINE const PxRigidDynamic* PxActor::isRigidDynamic() const { return is<PxRigidDynamic>(); }
400
401
402#ifndef PX_DOXYGEN
403} // namespace physx
404#endif
405
406/** @} */
407#endif
408