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

source code of qtquick3dphysics/src/3rdparty/PhysX/include/PxRigidDynamic.h