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#ifndef PX_VEHICLE_UPDATE_H
14#define PX_VEHICLE_UPDATE_H
15/** \addtogroup vehicle
16 @{
17*/
18
19#include "vehicle/PxVehicleSDK.h"
20#include "vehicle/PxVehicleTireFriction.h"
21#include "foundation/PxSimpleTypes.h"
22#include "foundation/PxMemory.h"
23#include "foundation/PxTransform.h"
24#include "PxBatchQueryDesc.h"
25
26#ifndef PX_DOXYGEN
27namespace physx
28{
29#endif
30
31 class PxBatchQuery;
32 class PxVehicleWheels;
33 class PxVehicleDrivableSurfaceToTireFrictionPairs;
34 class PxVehicleTelemetryData;
35
36 /**
37 \brief Structure containing data describing the non-persistent state of each suspension/wheel/tire unit.
38 This structure is filled out in PxVehicleUpdates and PxVehicleUpdateSingleVehicleAndStoreTelemetryData
39 @see PxVehicleUpdates, PxVehicleUpdateSingleVehicleAndStoreTelemetryData
40 */
41 struct PxWheelQueryResult
42 {
43 PxWheelQueryResult()
44 {
45 PxMemZero(this, sizeof(PxWheelQueryResult));
46 isInAir=true;
47 tireSurfaceType = (PxU32)PxVehicleDrivableSurfaceType::eSURFACE_TYPE_UNKNOWN;
48 localPose = PxTransform(PxIdentity);
49 }
50
51 /**
52 \brief Start point of suspension line raycast used in raycast completed immediately before PxVehicleUpdates.
53 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then (0,0,0) is stored.
54 @see PxVehicle4WSuspensionRaycasts
55 */
56 PxVec3 suspLineStart;
57
58 /**
59 \brief Directions of suspension line raycast used in raycast completed immediately before PxVehicleUpdates.
60 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then (0,0,0) is stored.
61 @see PxVehicle4WSuspensionRaycasts
62 */
63 PxVec3 suspLineDir;
64
65 /**
66 \brief Lengths of suspension line raycast used in raycast completed immediately before PxVehicleUpdates.
67 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then 0 is stored.
68 @see PxVehicle4WSuspensionRaycasts
69 */
70 PxReal suspLineLength;
71
72 /**
73 \brief If suspension travel limits forbid the wheel from touching the drivable surface then isInAir is true.
74 \note If the wheel can be placed on the contact plane of the most recent suspension line raycast then isInAir is false.
75 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then isInAir
76 is computed using the contact plane that was hit by the most recent suspension line raycast.
77 */
78 bool isInAir;
79
80 /**
81 \brief PxActor instance of the driving surface under the corresponding vehicle wheel.
82 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireContactActor is NULL.
83 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then NULL is stored.
84 */
85 PxActor* tireContactActor;
86
87 /**
88 \brief PxShape instance of the driving surface under the corresponding vehicle wheel.
89 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireContactShape is NULL.
90 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then NULL is stored.
91 */
92 PxShape* tireContactShape;
93
94 /**
95 \brief PxMaterial instance of the driving surface under the corresponding vehicle wheel.
96 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireSurfaceMaterial is NULL.
97 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then NULL is stored.
98 */
99 const PxMaterial* tireSurfaceMaterial;
100
101 /**
102 \brief Surface type integer that corresponds to the mapping between tireSurfaceMaterial and integer as
103 described in PxVehicleDrivableSurfaceToTireFrictionPairs.
104 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireSurfaceType is
105 PxVehicleDrivableSurfaceType::eSURFACE_TYPE_UNKNOWN.
106 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then
107 PxVehicleDrivableSurfaceType::eSURFACE_TYPE_UNKNOWN is stored.
108 @see PxVehicleDrivableSurfaceToTireFrictionPairs
109 */
110 PxU32 tireSurfaceType;
111
112 /**
113 \brief Point on the drivable surface hit by the most recent suspension raycast.
114 \note If suspension travel limits forbid the wheel from touching the drivable surface then the contact point is (0,0,0).
115 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then (0,0,0) is stored.
116 */
117 PxVec3 tireContactPoint;
118
119 /**
120 \brief Normal on the drivable surface at the hit point of the most recent suspension raycast.
121 \note If suspension travel limits forbid the wheel from touching the drivable surface then the contact normal is (0,0,0).
122 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then (0,0,0) is stored.
123 */
124 PxVec3 tireContactNormal;
125
126 /**
127 \brief Friction experienced by the tire for the combination of tire type and surface type after accounting
128 for the friction vs slip graph.
129 \note If suspension travel limits forbid the wheel from touching the drivable surface then the tire friction is 0.
130 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
131 stored tire friction is the value computed in PxVehicleUpdates that immediately followed the last raycast.
132 @see PxVehicleDrivableSurfaceToTireFrictionPairs, PxVehicleTireData
133 */
134 PxReal tireFriction;
135
136 /**
137 \brief Compression of the suspension spring.
138 \note If suspension travel limits forbid the wheel from touching the drivable surface then the jounce is -PxVehicleSuspensionData.mMaxDroop
139 The jounce can never exceed PxVehicleSuspensionData.mMaxCompression. Positive values result when the suspension is compressed from
140 the rest position, while negative values mean the suspension is elongated from the rest position.
141 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
142 suspension compression is computed using the contact plane that was hit by the most recent suspension line raycast.
143 */
144 PxReal suspJounce;
145
146 /**
147 \brief Magnitude of force applied by the suspension spring along the direction of suspension travel.
148 \note If suspension travel limits forbid the wheel from touching the drivable surface then the force is 0
149 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
150 suspension spring force is computed using the contact plane that was hit by the most recent suspension line raycast.
151 @see PxVehicleWheelsSimData::getSuspTravelDirection
152 */
153 PxReal suspSpringForce;
154
155 /**
156 \brief Forward direction of the wheel/tire accounting for steer/toe/camber angle projected on to the contact plane of the drivable surface.
157 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireLongitudinalDir is (0,0,0)
158 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
159 tire longitudinal direction is computed using the contact plane that was hit by the most recent suspension line raycast.
160 */
161 PxVec3 tireLongitudinalDir;
162
163 /**
164 \brief Lateral direction of the wheel/tire accounting for steer/toe/camber angle projected on to the contact plan of the drivable surface.
165 \note If suspension travel limits forbid the wheel from touching the drivable surface then tireLateralDir is (0,0,0)
166 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
167 tire lateral direction is computed using the contact plane that was hit by the most recent suspension line raycast.
168 */
169 PxVec3 tireLateralDir;
170
171 /**
172 \brief Longitudinal slip of the tire.
173 \note If suspension travel limits forbid the wheel from touching the drivable surface then longitudinalSlip is 0.0
174 \note The longitudinal slip is approximately (w*r - vz) / PxAbs(vz) where w is the angular speed of the wheel, r is the radius of the wheel, and
175 vz component of rigid body velocity computed at the wheel base along the longitudinal direction of the tire.
176 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
177 tire longitudinal slip is computed using the contact plane that was hit by the most recent suspension line raycast.
178 */
179 PxReal longitudinalSlip;
180
181 /**
182 \brief Lateral slip of the tire.
183 \note If suspension travel limits forbid the wheel from touching the drivable surface then lateralSlip is 0.0
184 \note The lateral slip angle is approximately PxAtan(vx / PxAbs(vz)) where vx and vz are the components of rigid body velocity at the wheel base
185 along the wheel's lateral and longitudinal directions, respectively.
186 \note If no raycast for the corresponding suspension was performed immediately prior to PxVehicleUpdates then the
187 tire lateral slip is computed using the contact plane that was hit by the most recent suspension line raycast.
188 */
189 PxReal lateralSlip;
190
191 /**
192 \brief Steer angle of the wheel about the "up" vector accounting for input steer and toe and, if applicable, Ackermann steer correction.
193 @see PxVehicleWheelData::mToeAngle
194 */
195 PxReal steerAngle;
196
197 /**
198 \brief Local pose of the wheel.
199 */
200 PxTransform localPose;
201 };
202
203 struct PxVehicleWheelQueryResult
204 {
205 /**
206 \brief Pointer to an PxWheelQueryResult buffer of length nbWheelQueryResults
207 The wheelQueryResults buffer must persist until the end of PxVehicleUpdates
208 A NULL pointer is permitted.
209 The wheelQueryResults buffer is left unmodified in PxVehicleUpdates for vehicles with sleeping rigid bodies
210 whose control inputs indicate they should remain inert.
211 @see PxVehicleUpdates
212 */
213 PxWheelQueryResult* wheelQueryResults;
214
215 /**
216 \brief The length of the wheelQueryResults buffer. This value corresponds to the
217 number of wheels in the associated vehicle in PxVehicleUpdates.
218 */
219 PxU32 nbWheelQueryResults;
220 };
221
222 /**
223 \brief Structure containing data that is computed for a wheel during concurrent calls to PxVehicleUpdates
224 but which cannot be safely concurrently applied.
225
226 @see PxVehicleUpdates, PxVehiclePostUpdates, PxVehicleConcurrentUpdate
227 */
228 struct PxVehicleWheelConcurrentUpdateData
229 {
230 friend class PxVehicleUpdate;
231
232 PxVehicleWheelConcurrentUpdateData()
233 : localPose(PxTransform(PxIdentity)),
234 hitActor(NULL),
235 hitActorForce(PxVec3(0,0,0)),
236 hitActorForcePosition(PxVec3(0,0,0))
237 {
238 }
239
240 private:
241
242 PxTransform localPose;
243 PxRigidDynamic* hitActor;
244 PxVec3 hitActorForce;
245 PxVec3 hitActorForcePosition;
246 };
247
248 /**
249 \brief Structure containing data that is computed for a vehicle and its wheels during concurrent calls to PxVehicleUpdates
250 but which cannot be safely concurrently applied.
251
252 @see PxVehicleUpdates, PxVehiclePostUpdates, PxVehicleWheelConcurrentUpdateData
253 */
254
255 struct PxVehicleConcurrentUpdateData
256 {
257 friend class PxVehicleUpdate;
258
259 PxVehicleConcurrentUpdateData()
260 : concurrentWheelUpdates(NULL),
261 nbConcurrentWheelUpdates(0),
262 linearMomentumChange(PxVec3(0,0,0)),
263 angularMomentumChange(PxVec3(0,0,0)),
264 staySleeping(false),
265 wakeup(false)
266 {
267 }
268
269 /**
270 \brief Pointer to an PxVehicleWheelConcurrentUpdate buffer of length nbConcurrentWheelUpdates
271 The concurrentWheelUpdates buffer must persist until the end of PxVehiclePostUpdates
272 A NULL pointer is not permitted.
273 @see PxVehicleUpdates, PxVehiclePostUpdates
274 */
275 PxVehicleWheelConcurrentUpdateData* concurrentWheelUpdates;
276
277 /**
278 \brief The length of the concurrentWheelUpdates buffer. This value corresponds to the
279 number of wheels in the associated vehicle passed to PxVehicleUpdates.
280 */
281 PxU32 nbConcurrentWheelUpdates;
282
283 private:
284
285 PxVec3 linearMomentumChange;
286 PxVec3 angularMomentumChange;
287 bool staySleeping;
288 bool wakeup;
289 };
290
291 /**
292 \brief Perform raycasts for all suspension lines for all vehicles.
293
294 \param[in] batchQuery is a PxBatchQuery instance used to specify shader data and functions for the raycast scene queries.
295
296 \param[in] nbVehicles is the number of vehicles in the vehicles array.
297
298 \param[in] vehicles is an array of all vehicles that are to have a raycast issued from each wheel.
299
300 \param[in] nbSceneQueryResults must be greater than or equal to the total number of wheels of all the vehicles in the vehicles array; that is,
301 sceneQueryResults must have dimensions large enough for one raycast hit result per wheel for all the vehicles in the vehicles array.
302
303 \param[in] sceneQueryResults must persist without being overwritten until the end of the next PxVehicleUpdates call.
304
305 \param[in] vehiclesToRaycast is an array of bools of length nbVehicles that is used to decide if raycasts will be performed for the corresponding vehicle
306 in the vehicles array. If vehiclesToRaycast[i] is true then suspension line raycasts will be performed for vehicles[i]. If vehiclesToRaycast[i] is
307 false then suspension line raycasts will not be performed for vehicles[i].
308
309 \note If vehiclesToRaycast is NULL then raycasts are performed for all vehicles in the vehicles array.
310
311 \note If vehiclesToRaycast[i] is false then the vehicle stored in vehicles[i] will automatically use the raycast hit planes recorded by the most recent
312 suspension line raycasts for that vehicle. For vehicles far from the camera or not visible on the screen it can be
313 optimal to only perform suspension line raycasts every Nth update rather than every single update. The accuracy of the cached contact plane
314 naturally diminishes as N increase, meaning that wheels might start to hover or intersect the ground for large values of N or even with values close to 1 in
315 conjunction with large vehicle speeds and/or geometry that has low spatial coherence.
316
317 \note Calling setToRestState invalidates any cached hit planes. Prior to calling PxVehicleUpdates each vehicle needs to perform suspension line raycasts
318 at least once after instantiation and at least once after calling setToRestState.
319
320 \note Each raycast casts along the suspension travel direction from the position of the top of the wheel at maximum suspension compression
321 to the position of the base of the wheel at maximum droop. Raycasts that start inside a PxShape are subsequently ignored by the
322 corresponding vehicle.
323
324 @see PxVehicleDrive4W::setToRestState, PxVehicleDriveNW::setToRestState, PxVehicleDriveTank::setToRestState, PxVehicleNoDrive::setToRestState
325 */
326 void PxVehicleSuspensionRaycasts
327 (PxBatchQuery* batchQuery, const PxU32 nbVehicles, PxVehicleWheels** vehicles, const PxU32 nbSceneQueryResults, PxRaycastQueryResult* sceneQueryResults, const bool* vehiclesToRaycast = NULL);
328
329
330 /**
331 \brief Update an array of vehicles by either applying an acceleration to the rigid body actor associated with
332 each vehicle or by an immediate update of the velocity of the actor.
333
334 \note The update mode (acceleration or velocity change) can be selected with PxVehicleSetUpdateMode.
335
336 \param[in] timestep is the timestep of the update
337
338 \param[in] gravity is the value of gravitational acceleration
339
340 \param[in] vehicleDrivableSurfaceToTireFrictionPairs describes the mapping between each PxMaterial ptr and an integer representing a
341 surface type. It also stores the friction value for each combination of surface and tire type.
342
343 \param[in] nbVehicles is the number of vehicles pointers in the vehicles array
344
345 \param[in, out] vehicles is an array of length nbVehicles containing all vehicles to be updated by the specified timestep
346
347 \param[out] vehicleWheelQueryResults is an array of length nbVehicles storing the wheel query results of each corresponding vehicle and wheel in the
348 vehicles array. A NULL pointer is permitted.
349
350 \param[out] vehicleConcurrentUpdates is an array of length nbVehicles. It is only necessary to specify vehicleConcurrentUpdates if PxVehicleUpdates is
351 called concurrently. The element vehicleWheelQueryResults[i] of the array stores data that is computed for vehicle[i] during PxVehicleUpdates but which
352 cannot be safely written when concurrently called. The data computed and stored in vehicleConcurrentUpdates must be passed to PxVehiclePostUpdates, where
353 it is applied to all relevant actors in sequence. A NULL pointer is permitted.
354
355 \note The vehicleWheelQueryResults buffer must persist until the end of PxVehicleUpdates.
356
357 \note The vehicleWheelQueryResults buffer is left unmodified for vehicles with sleeping rigid bodies whose control inputs indicate they should remain inert.
358
359 \note If PxVehicleUpdates is called concurrently then vehicleConcurrentUpdates must be specified. Do not specify vehicleConcurrentUpdates is PxVehicleUpdates
360 is not called concurrently.
361
362 \note The vehicleConcurrentUpdates buffer must persist until the end of PxVehiclePostUpdate.
363
364 \note If any vehicle has one or more disabled wheels (PxVehicleWheelsSimData::disableWheel) then the disabled wheels must not be associated
365 with a PxShape (PxVehicleWheelsSimData::setWheelShapeMapping); the differential of the vehicle must be configured so that no drive torque
366 is delivered to a disabled wheel; and the wheel must have zero rotation speed (PxVehicleWheelsDynData::setWheelRotationSpeed)
367
368 \note PxVehicleUpdates may be called concurrently provided all concurrent calls to PxVehicleUpdates involve only vehicles in the scene specified by PxVehicleUpdateSetScene.
369 PxVehicleUpdates must never run concurrently with PxVehicleUpdateSingleVehicleAndStoreTelemetryData.
370
371 @see PxVehicleSetUpdateMode, PxVehicleWheelsSimData::disableWheel, PxVehicleWheelsSimData::setWheelShapeMapping, PxVehicleWheelsDynData::setWheelRotationSpeed,
372 PxVehiclePostUpdates
373 */
374 void PxVehicleUpdates(
375 const PxReal timestep, const PxVec3& gravity,
376 const PxVehicleDrivableSurfaceToTireFrictionPairs& vehicleDrivableSurfaceToTireFrictionPairs,
377 const PxU32 nbVehicles, PxVehicleWheels** vehicles, PxVehicleWheelQueryResult* vehicleWheelQueryResults, PxVehicleConcurrentUpdateData* vehicleConcurrentUpdates = NULL);
378
379
380 /**
381 \brief Apply actor changes that were computed in concurrent calls to PxVehicleUpdates but which could not be safely applied due to the concurrency.
382
383 \param[in] vehicleConcurrentUpdates is an array of length nbVehicles where vehicleConcurrentUpdates[i] contains data describing actor changes that
384 were computed for vehicles[i] during concurrent calls to PxVehicleUpdates.
385
386 \param[in] nbVehicles is the number of vehicles pointers in the vehicles array
387
388 \param[in, out] vehicles is an array of length nbVehicles containing all vehicles that were partially updated in concurrent calls to PxVehicleUpdates.
389
390 @see PxVehicleUpdates
391 */
392 void PxVehiclePostUpdates(
393 const PxVehicleConcurrentUpdateData* vehicleConcurrentUpdates, const PxU32 nbVehicles, PxVehicleWheels** vehicles);
394
395
396 /**
397 \brief Shift the origin of vehicles by the specified vector.
398
399 Call this method to adjust the internal data structures of vehicles to reflect the shifted origin location
400 (the shift vector will get subtracted from all world space spatial data).
401
402 \note It is the user's responsibility to keep track of the summed total origin shift and adjust all input/output to/from PhysXVehicle accordingly.
403
404 \note This call will not automatically shift the PhysX scene and its objects. You need to call PxScene::shiftOrigin() seperately to keep the systems in sync.
405
406 \param[in] shift is the translation vector to shift the origin by.
407
408 \param[in] nbVehicles is the number of vehicles in the vehicles array.
409
410 \param[in, out] vehicles is an array of all vehicles that should be updated to map to the new scene origin.
411 */
412 void PxVehicleShiftOrigin(const PxVec3& shift, const PxU32 nbVehicles, PxVehicleWheels** vehicles);
413
414#if PX_DEBUG_VEHICLE_ON
415 /**
416 \brief Update an single vehicle by either applying an acceleration to the rigid body actor associated with
417 each vehicle or by an immediate update of the velocity of the actor. Also record telemetry data from the
418 vehicle so that it may be visualized or queried.
419
420 \note The update mode (acceleration or velocity change) can be selected with PxVehicleSetUpdateMode.
421
422 \param[in] timestep is the timestep of the update
423
424 \param[in] gravity is the value of gravitational acceleration
425
426 \param[in] vehicleDrivableSurfaceToTireFrictionPairs describes the mapping between each PxMaterial ptr and an integer representing a
427 surface type. It also stores the friction value for each combination of surface and tire type.
428
429 \param[in, out] focusVehicle is the vehicle to be updated and have its telemetry data recorded
430
431 \param[out] vehicleWheelQueryResults is an array of length 1 storing the wheel query results of each wheel of the vehicle/
432 A NULL pointer is permitted.
433
434 \param[out] telemetryData is the data structure used to record telemetry data during the update for later query or visualization
435
436 \note The vehicleWheelQueryResults buffer must persist until the end of PxVehicleUpdates
437
438 \note The vehicleWheelQueryResults buffer is left unmodified for vehicles with sleeping rigid bodies whose control inputs indicate they should remain inert.
439
440 \note PxVehicleUpdateSingleVehicleAndStoreTelemetryData is not thread-safe. As a consequence, it must run sequentially and never concurrently with PxVehicleUpdates
441
442 @see PxVehicleSetUpdateMode, PxVehicleTelemetryData
443 */
444 void PxVehicleUpdateSingleVehicleAndStoreTelemetryData
445 (const PxReal timestep, const PxVec3& gravity,
446 const PxVehicleDrivableSurfaceToTireFrictionPairs& vehicleDrivableSurfaceToTireFrictionPairs,
447 PxVehicleWheels* focusVehicle, PxVehicleWheelQueryResult* vehicleWheelQueryResults,
448 PxVehicleTelemetryData& telemetryData);
449#endif
450
451#ifndef PX_DOXYGEN
452} // namespace physx
453#endif
454
455/** @} */
456#endif //PX_VEHICLE_UPDATE_H
457