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_EXTENSIONS_RIGIDBODY_H
15#define PX_PHYSICS_EXTENSIONS_RIGIDBODY_H
16/** \addtogroup extensions
17 @{
18*/
19
20#include "PxPhysXConfig.h"
21#include "PxRigidBody.h"
22#include "PxQueryReport.h"
23#include "PxFiltering.h"
24#include "PxQueryFiltering.h"
25#include "PxScene.h"
26#include "PxClient.h"
27
28#ifndef PX_DOXYGEN
29namespace physx
30{
31#endif
32
33class PxScene;
34
35/**
36\brief utility functions for use with PxRigidBody and subclasses
37
38@see PxRigidBody PxRigidDynamic PxArticulationLink
39*/
40
41class PxRigidBodyExt
42{
43public:
44 /**
45 \brief Computation of mass properties for a rigid body actor
46
47 To simulate a dynamic rigid actor, the SDK needs a mass and an inertia tensor.
48
49 This method offers functionality to compute the necessary mass and inertia properties based on the shapes declared in
50 the PxRigidBody descriptor and some additionally specified parameters. For each shape, the shape geometry,
51 the shape positioning within the actor and the specified shape density are used to compute the body's mass and
52 inertia properties.
53
54 <ul>
55 <li>Shapes without PxShapeFlag::eSIMULATION_SHAPE set are ignored unless includeNonSimShapes is true.</li>
56 <li>Shapes with plane, triangle mesh or heightfield geometry and PxShapeFlag::eSIMULATION_SHAPE set are not allowed for PxRigidBody collision.</li>
57 </ul>
58
59 This method will set the mass, center of mass, and inertia tensor
60
61 if no collision shapes are found, the inertia tensor is set to (1,1,1) and the mass to 1
62
63 if massLocalPose is non-NULL, the rigid body's center of mass parameter will be set
64 to the user provided value (massLocalPose) and the inertia tensor will be resolved at that point.
65
66 \note If all shapes of the actor have the same density then the overloaded method updateMassAndInertia() with a single density parameter can be used instead.
67
68 \param[in,out] body The rigid body.
69 \param[in] shapeDensities The per shape densities. There must be one entry for each shape which has the PxShapeFlag::eSIMULATION_SHAPE set (or for all shapes if includeNonSimShapes is set to true). Other shapes are ignored. The density values must be greater than 0.
70 \param[in] shapeDensityCount The number of provided density values.
71 \param[in] massLocalPose The center of mass relative to the actor frame. If set to null then (0,0,0) is assumed.
72 \param[in] includeNonSimShapes True if all kind of shapes (PxShapeFlag::eSCENE_QUERY_SHAPE, PxShapeFlag::eTRIGGER_SHAPE, PxShapeFlag::ePARTICLE_DRAIN) should be taken into account.
73 \return Boolean. True on success else false.
74
75 @see PxRigidBody::setMassLocalPose PxRigidBody::setMassSpaceInertia PxRigidBody::setMass
76 */
77 static bool updateMassAndInertia(PxRigidBody& body, const PxReal* shapeDensities, PxU32 shapeDensityCount, const PxVec3* massLocalPose = NULL, bool includeNonSimShapes = false);
78
79
80 /**
81 \brief Computation of mass properties for a rigid body actor
82
83 See previous method for details.
84
85 \param[in,out] body The rigid body.
86 \param[in] density The density of the body. Used to compute the mass of the body. The density must be greater than 0.
87 \param[in] massLocalPose The center of mass relative to the actor frame. If set to null then (0,0,0) is assumed.
88 \param[in] includeNonSimShapes True if all kind of shapes (PxShapeFlag::eSCENE_QUERY_SHAPE, PxShapeFlag::eTRIGGER_SHAPE, PxShapeFlag::ePARTICLE_DRAIN) should be taken into account.
89 \return Boolean. True on success else false.
90
91 @see PxRigidBody::setMassLocalPose PxRigidBody::setMassSpaceInertia PxRigidBody::setMass
92 */
93 static bool updateMassAndInertia(PxRigidBody& body, PxReal density, const PxVec3* massLocalPose = NULL, bool includeNonSimShapes = false);
94
95
96 /**
97 \brief Computation of mass properties for a rigid body actor
98
99 This method sets the mass, inertia and center of mass of a rigid body. The mass is set to the sum of all user-supplied
100 shape mass values, and the inertia and center of mass are computed according to the rigid body's shapes and the per shape mass input values.
101
102 If no collision shapes are found, the inertia tensor is set to (1,1,1)
103
104 \note If a single mass value should be used for the actor as a whole then the overloaded method setMassAndUpdateInertia() with a single mass parameter can be used instead.
105
106 @see updateMassAndInertia for more details.
107
108 \param[in,out] body The the rigid body for which to set the mass and centre of mass local pose properties.
109 \param[in] shapeMasses The per shape mass values. There must be one entry for each shape which has the PxShapeFlag::eSIMULATION_SHAPE set. Other shapes are ignored. The mass values must be greater than 0.
110 \param[in] shapeMassCount The number of provided mass values.
111 \param[in] massLocalPose The center of mass relative to the actor frame. If set to null then (0,0,0) is assumed.
112 \param[in] includeNonSimShapes True if all kind of shapes (PxShapeFlag::eSCENE_QUERY_SHAPE, PxShapeFlag::eTRIGGER_SHAPE, PxShapeFlag::ePARTICLE_DRAIN) should be taken into account.
113 \return Boolean. True on success else false.
114
115 @see PxRigidBody::setCMassLocalPose PxRigidBody::setMassSpaceInertia PxRigidBody::setMass
116 */
117 static bool setMassAndUpdateInertia(PxRigidBody& body, const PxReal* shapeMasses, PxU32 shapeMassCount, const PxVec3* massLocalPose = NULL, bool includeNonSimShapes = false);
118
119
120 /**
121 \brief Computation of mass properties for a rigid body actor
122
123 This method sets the mass, inertia and center of mass of a rigid body. The mass is set to the user-supplied
124 value, and the inertia and center of mass are computed according to the rigid body's shapes and the input mass.
125
126 If no collision shapes are found, the inertia tensor is set to (1,1,1)
127
128 @see updateMassAndInertia for more details.
129
130 \param[in,out] body The the rigid body for which to set the mass and centre of mass local pose properties.
131 \param[in] mass The mass of the body. Must be greater than 0.
132 \param[in] massLocalPose The center of mass relative to the actor frame. If set to null then (0,0,0) is assumed.
133 \param[in] includeNonSimShapes True if all kind of shapes (PxShapeFlag::eSCENE_QUERY_SHAPE, PxShapeFlag::eTRIGGER_SHAPE, PxShapeFlag::ePARTICLE_DRAIN) should be taken into account.
134 \return Boolean. True on success else false.
135
136 @see PxRigidBody::setCMassLocalPose PxRigidBody::setMassSpaceInertia PxRigidBody::setMass
137 */
138 static bool setMassAndUpdateInertia(PxRigidBody& body, PxReal mass, const PxVec3* massLocalPose = NULL, bool includeNonSimShapes = false);
139
140
141 /**
142 \brief Applies a force (or impulse) defined in the global coordinate frame, acting at a particular
143 point in global coordinates, to the actor.
144
145 Note that if the force does not act along the center of mass of the actor, this
146 will also add the corresponding torque. Because forces are reset at the end of every timestep,
147 you can maintain a total external force on an object by calling this once every frame.
148
149 \note if this call is used to apply a force or impulse to an articulation link, only the link is updated, not the entire
150 articulation
151
152 ::PxForceMode determines if the force is to be conventional or impulsive. Only eFORCE and eIMPULSE are supported, as the
153 force required to produce a given velocity change or acceleration is underdetermined given only the desired change at a
154 given point.
155
156 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the wakeup parameter is true (default).
157
158 \param[in] body The rigid body to apply the force to.
159 \param[in] force Force/impulse to add, defined in the global frame. <b>Range:</b> force vector
160 \param[in] pos Position in the global frame to add the force at. <b>Range:</b> position vector
161 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode).
162 \param[in] wakeup Specify if the call should wake up the actor.
163
164 @see PxForceMode
165 @see addForceAtLocalPos() addLocalForceAtPos() addLocalForceAtLocalPos()
166 */
167 static void addForceAtPos(PxRigidBody& body, const PxVec3& force, const PxVec3& pos, PxForceMode::Enum mode = PxForceMode::eFORCE, bool wakeup = true);
168
169 /**
170 \brief Applies a force (or impulse) defined in the global coordinate frame, acting at a particular
171 point in local coordinates, to the actor.
172
173 Note that if the force does not act along the center of mass of the actor, this
174 will also add the corresponding torque. Because forces are reset at the end of every timestep, you can maintain a
175 total external force on an object by calling this once every frame.
176
177 \note if this call is used to apply a force or impulse to an articulation link, only the link is updated, not the entire
178 articulation
179
180 ::PxForceMode determines if the force is to be conventional or impulsive. Only eFORCE and eIMPULSE are supported, as the
181 force required to produce a given velocity change or acceleration is underdetermined given only the desired change at a
182 given point.
183
184 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the wakeup parameter is true (default).
185
186 \param[in] body The rigid body to apply the force to.
187 \param[in] force Force/impulse to add, defined in the global frame. <b>Range:</b> force vector
188 \param[in] pos Position in the local frame to add the force at. <b>Range:</b> position vector
189 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode).
190 \param[in] wakeup Specify if the call should wake up the actor.
191
192 @see PxForceMode
193 @see addForceAtPos() addLocalForceAtPos() addLocalForceAtLocalPos()
194 */
195 static void addForceAtLocalPos(PxRigidBody& body, const PxVec3& force, const PxVec3& pos, PxForceMode::Enum mode = PxForceMode::eFORCE, bool wakeup = true);
196
197 /**
198 \brief Applies a force (or impulse) defined in the actor local coordinate frame, acting at a
199 particular point in global coordinates, to the actor.
200
201 Note that if the force does not act along the center of mass of the actor, this
202 will also add the corresponding torque. Because forces are reset at the end of every timestep, you can maintain a
203 total external force on an object by calling this once every frame.
204
205 \note if this call is used to apply a force or impulse to an articulation link, only the link is updated, not the entire
206 articulation
207
208 ::PxForceMode determines if the force is to be conventional or impulsive. Only eFORCE and eIMPULSE are supported, as the
209 force required to produce a given velocity change or acceleration is underdetermined given only the desired change at a
210 given point.
211
212 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the wakeup parameter is true (default).
213
214 \param[in] body The rigid body to apply the force to.
215 \param[in] force Force/impulse to add, defined in the local frame. <b>Range:</b> force vector
216 \param[in] pos Position in the global frame to add the force at. <b>Range:</b> position vector
217 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode).
218 \param[in] wakeup Specify if the call should wake up the actor.
219
220 @see PxForceMode
221 @see addForceAtPos() addForceAtLocalPos() addLocalForceAtLocalPos()
222 */
223 static void addLocalForceAtPos(PxRigidBody& body, const PxVec3& force, const PxVec3& pos, PxForceMode::Enum mode = PxForceMode::eFORCE, bool wakeup = true);
224
225 /**
226 \brief Applies a force (or impulse) defined in the actor local coordinate frame, acting at a
227 particular point in local coordinates, to the actor.
228
229 Note that if the force does not act along the center of mass of the actor, this
230 will also add the corresponding torque. Because forces are reset at the end of every timestep, you can maintain a
231 total external force on an object by calling this once every frame.
232
233 \note if this call is used to apply a force or impulse to an articulation link, only the link is updated, not the entire
234 articulation
235
236 ::PxForceMode determines if the force is to be conventional or impulsive. Only eFORCE and eIMPULSE are supported, as the
237 force required to produce a given velocity change or acceleration is underdetermined given only the desired change at a
238 given point.
239
240 <b>Sleeping:</b> This call wakes the actor if it is sleeping and the wakeup parameter is true (default).
241
242 \param[in] body The rigid body to apply the force to.
243 \param[in] force Force/impulse to add, defined in the local frame. <b>Range:</b> force vector
244 \param[in] pos Position in the local frame to add the force at. <b>Range:</b> position vector
245 \param[in] mode The mode to use when applying the force/impulse(see #PxForceMode).
246 \param[in] wakeup Specify if the call should wake up the actor.
247
248 @see PxForceMode
249 @see addForceAtPos() addForceAtLocalPos() addLocalForceAtPos()
250 */
251 static void addLocalForceAtLocalPos(PxRigidBody& body, const PxVec3& force, const PxVec3& pos, PxForceMode::Enum mode = PxForceMode::eFORCE, bool wakeup = true);
252
253 /**
254 \brief Computes the velocity of a point given in world coordinates if it were attached to the
255 specified body and moving with it.
256
257 \param[in] body The rigid body the point is attached to.
258 \param[in] pos Position we wish to determine the velocity for, defined in the global frame. <b>Range:</b> position vector
259 \return The velocity of point in the global frame.
260
261 @see getLocalPointVelocity()
262 */
263 static PxVec3 getVelocityAtPos(const PxRigidBody& body, const PxVec3& pos);
264
265 /**
266 \brief Computes the velocity of a point given in local coordinates if it were attached to the
267 specified body and moving with it.
268
269 \param[in] body The rigid body the point is attached to.
270 \param[in] pos Position we wish to determine the velocity for, defined in the local frame. <b>Range:</b> position vector
271 \return The velocity of point in the local frame.
272
273 @see getLocalPointVelocity()
274 */
275 static PxVec3 getLocalVelocityAtLocalPos(const PxRigidBody& body, const PxVec3& pos);
276
277 /**
278 \brief Computes the velocity of a point (offset from the origin of the body) given in world coordinates if it were attached to the
279 specified body and moving with it.
280
281 \param[in] body The rigid body the point is attached to.
282 \param[in] pos Position (offset from the origin of the body) we wish to determine the velocity for, defined in the global frame. <b>Range:</b> position vector
283 \return The velocity of point (offset from the origin of the body) in the global frame.
284
285 @see getLocalPointVelocity()
286 */
287 static PxVec3 getVelocityAtOffset(const PxRigidBody& body, const PxVec3& pos);
288
289
290 /**
291 \brief Performs a linear sweep through space with the body's geometry objects.
292
293 \note Supported geometries are: box, sphere, capsule, convex. Other geometry types will be ignored.
294 \note If eTOUCH is returned from the filter callback, it will trigger an error and the hit will be discarded.
295
296 The function sweeps all shapes attached to a given rigid body through space and reports the nearest
297 object in the scene which intersects any of of the shapes swept paths.
298 Information about the closest intersection is written to a #PxSweepHit structure.
299
300 \param[in] body The rigid body to sweep.
301 \param[in] scene The scene object to process the query.
302 \param[in] unitDir Normalized direction of the sweep.
303 \param[in] distance Sweep distance. Needs to be larger than 0.
304 \param[in] outputFlags Specifies which properties should be written to the hit information.
305 \param[out] closestHit Closest hit result.
306 \param[out] shapeIndex Index of the body shape that caused the closest hit.
307 \param[in] filterData If any word in filterData.data is non-zero then filterData.data will be used for filtering,
308 otherwise shape->getQueryFilterData() will be used instead.
309 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
310 \param[in] cache Cached hit shape (optional). Ray is tested against cached shape first then against the scene.
311 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
312 \param[in] inflation This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal.
313
314 \return True if a blocking hit was found.
315
316 @see PxScene PxQueryFlags PxFilterData PxBatchQueryPreFilterShader PxBatchQueryPostFilterShader PxSweepHit
317 */
318 static bool linearSweepSingle(
319 PxRigidBody& body, PxScene& scene, const PxVec3& unitDir, const PxReal distance,
320 PxHitFlags outputFlags,
321 PxSweepHit& closestHit, PxU32& shapeIndex,
322 const PxQueryFilterData& filterData = PxQueryFilterData(),
323 PxQueryFilterCallback* filterCall = NULL,
324 const PxQueryCache* cache = NULL,
325 const PxReal inflation=0.0f);
326
327 /**
328 \brief Performs a linear sweep through space with the body's geometry objects, returning all overlaps.
329
330 \note Supported geometries are: box, sphere, capsule, convex. Other geometry types will be ignored.
331
332 This function sweeps all shapes attached to a given rigid body through space and reports all
333 objects in the scene that intersect any of the shapes' swept paths until there are no more objects to report
334 or a blocking hit is encountered.
335
336 \param[in] body The rigid body to sweep.
337 \param[in] scene The scene object to process the query.
338 \param[in] unitDir Normalized direction of the sweep.
339 \param[in] distance Sweep distance. Needs to be larger than 0.
340 \param[in] outputFlags Specifies which properties should be written to the hit information.
341 \param[out] touchHitBuffer Raycast hit information buffer. If the buffer overflows, an arbitrary subset of touch hits
342 is returned (typically the query should be restarted with a larger buffer).
343 \param[out] touchHitShapeIndices After the query is completed, touchHitShapeIndices[i] will contain the body index that caused the hit stored in hitBuffer[i]
344 \param[in] touchHitBufferSize Size of both touch hit buffers in elements.
345 \param[out] block Closest blocking hit is returned via this reference.
346 \param[out] blockingShapeIndex Set to -1 if if a blocking hit was not found, otherwise set to closest blocking hit shape index. The touching hits are reported separately in hitBuffer.
347 \param[out] overflow Set to true if touchHitBuffer didn't have enough space for all results. Touch hits will be incomplete if overflow occurred. Possible solution is to restart the query with a larger buffer.
348 \param[in] filterData If any word in filterData.data is non-zero then filterData.data will be used for filtering,
349 otherwise shape->getQueryFilterData() will be used instead.
350 \param[in] filterCall Custom filtering logic (optional). Only used if the corresponding #PxQueryFlag flags are set. If NULL, all hits are assumed to be blocking.
351 \param[in] cache Cached hit shape (optional). Ray is tested against cached shape first then against the scene.
352 Note: Filtering is not executed for a cached shape if supplied; instead, if a hit is found, it is assumed to be a blocking hit.
353 \param[in] inflation This parameter creates a skin around the swept geometry which increases its extents for sweeping. The sweep will register a hit as soon as the skin touches a shape, and will return the corresponding distance and normal.
354
355 \return the number of touching hits. If overflow is set to true, the results are incomplete. In case of overflow there are also no guarantees that all touching hits returned are closer than the blocking hit.
356
357 @see PxScene PxQueryFlags PxFilterData PxBatchQueryPreFilterShader PxBatchQueryPostFilterShader PxSweepHit
358 */
359 static PxU32 linearSweepMultiple(
360 PxRigidBody& body, PxScene& scene, const PxVec3& unitDir, const PxReal distance,
361 PxHitFlags outputFlags,
362 PxSweepHit* touchHitBuffer, PxU32* touchHitShapeIndices, PxU32 touchHitBufferSize,
363 PxSweepHit& block, PxI32& blockingShapeIndex, bool& overflow,
364 const PxQueryFilterData& filterData = PxQueryFilterData(),
365 PxQueryFilterCallback* filterCall = NULL,
366 const PxQueryCache* cache = NULL, const PxReal inflation = 0.0f);
367
368
369 /**
370 \brief Compute the change to linear and angular velocity that would occur if an impulsive force and torque were to be applied to a specified rigid body.
371
372 The rigid body is left unaffected unless a subsequent independent call is executed that actually applies the computed changes to velocity and angular velocity.
373
374 \note if this call is used to determine the velocity delta for an articulation link, only the mass properties of the link are taken into account.
375
376 @see PxRigidBody::getLinearVelocity, PxRigidBody::setLinearVelocity, PxRigidBody::getAngularVelocity, PxRigidBody::setAngularVelocity
377
378 \param[in] body The body under consideration.
379 \param[in] impulsiveForce The impulsive force that would be applied to the specified rigid body.
380 \param[in] impulsiveTorque The impulsive torque that would be applied to the specified rigid body.
381 \param[out] deltaLinearVelocity The change in linear velocity that would arise if impulsiveForce was to be applied to the specified rigid body.
382 \param[out] deltaAngularVelocity The change in angular velocity that would arise if impulsiveTorque was to be applied to the specified rigid body.
383 */
384 static void computeVelocityDeltaFromImpulse(const PxRigidBody& body, const PxVec3& impulsiveForce, const PxVec3& impulsiveTorque, PxVec3& deltaLinearVelocity, PxVec3& deltaAngularVelocity);
385
386 /**
387 \brief Computes the linear and angular velocity change vectors for a given impulse at a world space position taking a mass and inertia scale into account
388
389 This function is useful for extracting the respective linear and angular velocity changes from a contact or joint when the mass/inertia ratios have been adjusted.
390
391 \note if this call is used to determine the velocity delta for an articulation link, only the mass properties of the link are taken into account.
392
393 \param[in] body The rigid body
394 \param[in] globalPose The body's world space transform
395 \param[in] point The point in world space where the impulse is applied
396 \param[in] impulse The impulse vector in world space
397 \param[in] invMassScale The inverse mass scale
398 \param[in] invInertiaScale The inverse inertia scale
399 \param[out] deltaLinearVelocity The linear velocity change
400 \param[out] deltaAngularVelocity The angular velocity change
401 */
402
403 static void computeVelocityDeltaFromImpulse(const PxRigidBody& body, const PxTransform& globalPose, const PxVec3& point, const PxVec3& impulse, const PxReal invMassScale,
404 const PxReal invInertiaScale, PxVec3& deltaLinearVelocity, PxVec3& deltaAngularVelocity);
405
406 /**
407 \brief Computes the linear and angular impulse vectors for a given impulse at a world space position taking a mass and inertia scale into account
408
409 This function is useful for extracting the respective linear and angular impulses from a contact or joint when the mass/inertia ratios have been adjusted.
410
411 \param[in] body The rigid body
412 \param[in] globalPose The body's world space transform
413 \param[in] point The point in world space where the impulse is applied
414 \param[in] impulse The impulse vector in world space
415 \param[in] invMassScale The inverse mass scale
416 \param[in] invInertiaScale The inverse inertia scale
417 \param[out] linearImpulse The linear impulse
418 \param[out] angularImpulse The angular impulse
419 */
420 static void computeLinearAngularImpulse(const PxRigidBody& body, const PxTransform& globalPose, const PxVec3& point, const PxVec3& impulse, const PxReal invMassScale,
421 const PxReal invInertiaScale, PxVec3& linearImpulse, PxVec3& angularImpulse);
422
423
424};
425
426#ifndef PX_DOXYGEN
427} // namespace physx
428#endif
429
430/** @} */
431#endif
432