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 |
40 | namespace 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 | */ |
50 | struct 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 | |
63 | typedef PxFlags<PxRigidDynamicLockFlag::Enum, PxU8> PxRigidDynamicLockFlags; |
64 | PX_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> |
70 | Instances 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 | |
83 | class PxRigidDynamic : public PxRigidBody |
84 | { |
85 | public: |
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 | |
375 | protected: |
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 | |