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#ifndef PX_VEHICLE_SDK_H
31#define PX_VEHICLE_SDK_H
32/** \addtogroup vehicle
33 @{
34*/
35
36#include "foundation/Px.h"
37#include "common/PxTypeInfo.h"
38
39#if !PX_DOXYGEN
40namespace physx
41{
42#endif
43
44class PxPhysics;
45class PxSerializationRegistry;
46
47/**
48\brief Initialize the PhysXVehicle library.
49
50Call this before using any of the vehicle functions.
51
52\param physics The PxPhysics instance.
53\param serializationRegistry PxSerializationRegistry instance, if NULL vehicle serialization is not supported.
54
55\note This function must be called after PxFoundation and PxPhysics instances have been created.
56\note If a PxSerializationRegistry instance is specified then PhysXVehicle is also dependent on PhysXExtensions.
57
58@see PxCloseVehicleSDK
59*/
60PX_C_EXPORT bool PX_CALL_CONV PxInitVehicleSDK(PxPhysics& physics, PxSerializationRegistry* serializationRegistry = NULL);
61
62
63/**
64\brief Shut down the PhysXVehicle library.
65
66Call this function as part of the physx shutdown process.
67
68\param serializationRegistry PxSerializationRegistry instance, if non-NULL must be the same as passed into PxInitVehicleSDK.
69
70\note This function must be called prior to shutdown of PxFoundation and PxPhysics.
71\note If the PxSerializationRegistry instance is specified this function must additionally be called prior to shutdown of PhysXExtensions.
72
73@see PxInitVehicleSDK
74*/
75PX_C_EXPORT void PX_CALL_CONV PxCloseVehicleSDK(PxSerializationRegistry* serializationRegistry = NULL);
76
77
78/**
79\brief This number is the maximum number of wheels allowed for a vehicle.
80*/
81#define PX_MAX_NB_WHEELS (20)
82
83
84/**
85\brief Compiler setting to enable recording of telemetry data
86
87@see PxVehicleUpdateSingleVehicleAndStoreTelemetryData, PxVehicleTelemetryData
88*/
89#define PX_DEBUG_VEHICLE_ON (1)
90
91
92/**
93@see PxVehicleDrive4W, PxVehicleDriveTank, PxVehicleDriveNW, PxVehicleNoDrive, PxVehicleWheels::getVehicleType
94*/
95struct PxVehicleTypes
96{
97 enum Enum
98 {
99 eDRIVE4W=0,
100 eDRIVENW,
101 eDRIVETANK,
102 eNODRIVE,
103 eUSER1,
104 eUSER2,
105 eUSER3,
106 eMAX_NB_VEHICLE_TYPES
107 };
108};
109
110
111/**
112\brief An enumeration of concrete vehicle classes inheriting from PxBase.
113\note This enum can be used to identify a vehicle object stored in a PxCollection.
114@see PxBase, PxTypeInfo, PxBase::getConcreteType
115*/
116struct PxVehicleConcreteType
117{
118 enum Enum
119 {
120 eVehicleNoDrive = PxConcreteType::eFIRST_VEHICLE_EXTENSION,
121 eVehicleDrive4W,
122 eVehicleDriveNW,
123 eVehicleDriveTank
124 };
125};
126
127
128/**
129\brief Set the basis vectors of the vehicle simulation
130
131Default values PxVec3(0,1,0), PxVec3(0,0,1)
132
133Call this function before using PxVehicleUpdates unless the default values are correct.
134*/
135void PxVehicleSetBasisVectors(const PxVec3& up, const PxVec3& forward);
136
137
138/**
139@see PxVehicleSetUpdateMode
140*/
141struct PxVehicleUpdateMode
142{
143 enum Enum
144 {
145 eVELOCITY_CHANGE,
146 eACCELERATION
147 };
148};
149
150
151/**
152\brief Set the effect of PxVehicleUpdates to be either to modify each vehicle's rigid body actor
153
154with an acceleration to be applied in the next PhysX SDK update or as an immediate velocity modification.
155
156Default behavior is immediate velocity modification.
157
158Call this function before using PxVehicleUpdates for the first time if the default is not the desired behavior.
159
160@see PxVehicleUpdates
161*/
162void PxVehicleSetUpdateMode(PxVehicleUpdateMode::Enum vehicleUpdateMode);
163
164/**
165
166\brief Set threshold angles that are used to determine if a wheel hit is to be resolved by vehicle suspension or by rigid body collision.
167
168
169\note ^
170 N ___
171 |**
172 **
173 **
174 %%% %%% **
175 %%% %%% ** /
176 /
177 %%% %%% /
178 /
179 %%% %%% /
180 C /
181 %%% | ** %%% /
182 | ** /
183 %%% | **%%%/
184 | X**
185 %%% | %%% / **_| ^
186 | / D
187 %%% | %%% /
188 | /
189 | /
190 | /
191 |
192 ^ |
193 S \|/
194
195The diagram above depicts a wheel centered at "C" that has hit an inclined plane at point "X".
196The inclined plane has unit normal "N", while the suspension direction has unit vector "S".
197The unit vector from the wheel center to the hit point is "D".
198Hit points are analyzed by comparing the unit vectors D and N with the suspension direction S.
199This analysis is performed in the contact modification callback PxVehicleModifyWheelContacts (when enabled) and in
200PxVehicleUpdates (when non-blocking sweeps are enabled).
201If the angle between D and S is less than pointRejectAngle the hit is accepted by the suspension in PxVehicleUpdates and rejected
202by the contact modification callback PxVehicleModifyWheelContacts.
203If the angle between -N and S is less than normalRejectAngle the hit is accepted by the suspension in PxVehicleUpdates and rejected
204by the contact modification callback PxVehicleModifyWheelContacts.
205
206\param pointRejectAngle is the threshold angle used when comparing the angle between D and S.
207
208\param normalRejectAngle is the threshold angle used when comparing the angle between -N and S.
209
210\note PxVehicleUpdates ignores the rejection angles for raycasts and for sweeps that return blocking hits.
211
212\note Both angles have default values of Pi/4.
213
214@see PxVehicleSuspensionSweeps, PxVehicleModifyWheelContacts
215*/
216void PxVehicleSetSweepHitRejectionAngles(const PxF32 pointRejectAngle, const PxF32 normalRejectAngle);
217
218
219/**
220\brief Determine the maximum acceleration experienced by PxRigidDynamic instances that are found to be in contact
221with a wheel.
222
223\note Newton's Third Law states that every force has an equal and opposite force. As a consequence, forces applied to
224the suspension must be applied to dynamic objects that lie under the wheel. This can lead to instabilities, particularly
225when a heavy wheel is driving on a light object. The value of maxHitActorAcceleration clamps the applied force so that it never
226generates an acceleration greater than the specified value.
227
228\note Default value of maxHitActorAcceleration is PX_MAX_REAL
229*/
230void PxVehicleSetMaxHitActorAcceleration(const PxF32 maxHitActorAcceleration);
231
232#if !PX_DOXYGEN
233} // namespace physx
234#endif
235
236/** @} */
237#endif //PX_VEHICLE_SDK_H
238

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