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_TIREFRICTION_H
14#define PX_VEHICLE_TIREFRICTION_H
15/** \addtogroup vehicle
16 @{
17*/
18
19#include "foundation/PxSimpleTypes.h"
20
21#ifndef PX_DOXYGEN
22namespace physx
23{
24#endif
25
26class PxMaterial;
27
28/**
29\brief Driving surface type. Each PxMaterial is associated with a corresponding PxVehicleDrivableSurfaceType.
30@see PxMaterial, PxVehicleDrivableSurfaceToTireFrictionPairs
31*/
32struct PxVehicleDrivableSurfaceType
33{
34 enum
35 {
36 eSURFACE_TYPE_UNKNOWN=0xffffffff
37 };
38 PxU32 mType;
39};
40
41/**
42\brief Friction for each combination of driving surface type and tire type.
43@see PxVehicleDrivableSurfaceType, PxVehicleTireData::mType
44*/
45class PxVehicleDrivableSurfaceToTireFrictionPairs
46{
47public:
48
49 friend class VehicleSurfaceTypeHashTable;
50
51 enum
52 {
53 eMAX_NB_SURFACE_TYPES=256
54 };
55
56 /**
57 \brief Allocate the memory for a PxVehicleDrivableSurfaceToTireFrictionPairs instance
58 that can hold data for combinations of tire type and surface type with up to maxNbTireTypes types of tire and maxNbSurfaceTypes types of surface.
59
60 \param[in] maxNbTireTypes is the maximum number of allowed tire types.
61 \param[in] maxNbSurfaceTypes is the maximum number of allowed surface types. Must be less than or equal to eMAX_NB_SURFACE_TYPES
62
63 \return a PxVehicleDrivableSurfaceToTireFrictionPairs instance that can be reused later with new type and friction data.
64
65 @see setup
66 */
67 static PxVehicleDrivableSurfaceToTireFrictionPairs* allocate
68 (const PxU32 maxNbTireTypes, const PxU32 maxNbSurfaceTypes);
69
70 /**
71 \brief Set up a PxVehicleDrivableSurfaceToTireFrictionPairs instance for combinations of nbTireTypes tire types and nbSurfaceTypes surface types.
72
73 \param[in] nbTireTypes is the number of different types of tire. This value must be less than or equal to maxNbTireTypes specified in allocate().
74 \param[in] nbSurfaceTypes is the number of different types of surface. This value must be less than or equal to maxNbSurfaceTypes specified in allocate().
75 \param[in] drivableSurfaceMaterials is an array of PxMaterial pointers of length nbSurfaceTypes.
76 \param[in] drivableSurfaceTypes is an array of PxVehicleDrivableSurfaceType instances of length nbSurfaceTypes.
77
78 \note If the pointer to the PxMaterial that touches the tire is found in drivableSurfaceMaterials[x] then the surface type is drivableSurfaceTypes[x].mType
79 and the friction is the value that is set with setTypePairFriction(drivableSurfaceTypes[x].mType, PxVehicleTireData::mType, frictionValue).
80
81 \note A friction value of 1.0 will be assigned as default to each combination of tire and surface type. To override this use setTypePairFriction.
82 @see release, setTypePairFriction, getTypePairFriction, PxVehicleTireData.mType
83 */
84 void setup
85 (const PxU32 nbTireTypes, const PxU32 nbSurfaceTypes,
86 const PxMaterial** drivableSurfaceMaterials, const PxVehicleDrivableSurfaceType* drivableSurfaceTypes);
87
88 /**
89 \brief Deallocate a PxVehicleDrivableSurfaceToTireFrictionPairs instance
90 */
91 void release();
92
93 /**
94 \brief Set the friction for a specified pair of tire type and drivable surface type.
95
96 \param[in] surfaceType describes the surface type
97 \param[in] tireType describes the tire type.
98 \param[in] value describes the friction coefficient for the combination of surface type and tire type.
99 */
100 void setTypePairFriction(const PxU32 surfaceType, const PxU32 tireType, const PxReal value);
101
102 /**
103 \brief Return the friction for a specified combination of surface type and tire type.
104 \return The friction for a specified combination of surface type and tire type.
105 \note The final friction value used by the tire model is the value returned by getTypePairFriction
106 multiplied by the value computed from PxVehicleTireData::mFrictionVsSlipGraph
107 @see PxVehicleTireData::mFrictionVsSlipGraph
108 */
109 PxReal getTypePairFriction(const PxU32 surfaceType, const PxU32 tireType) const;
110
111 /**
112 \brief Return the maximum number of surface types
113 \return The maximum number of surface types
114 @see allocate
115 */
116 PxU32 getMaxNbSurfaceTypes() const {return mMaxNbSurfaceTypes;}
117
118 /**
119 \brief Return the maximum number of tire types
120 \return The maximum number of tire types
121 @see allocate
122 */
123 PxU32 getMaxNbTireTypes() const {return mMaxNbTireTypes;}
124
125private:
126
127 /**
128 \brief Ptr to base address of a 2d PxReal array with dimensions [mNbSurfaceTypes][mNbTireTypes]
129
130 \note Each element of the array describes the maximum friction provided by a surface type-tire type combination.
131 eg the friction corresponding to a combination of surface type x and tire type y is mPairs[x][y]
132 */
133 PxReal* mPairs;
134
135 /**
136 \brief Ptr to 1d array of material ptrs that is of length mNbSurfaceTypes.
137
138 \note If the PxMaterial that touches the tire corresponds to mDrivableSurfaceMaterials[x] then the drivable surface
139 type is mDrivableSurfaceTypes[x].mType and the friction for that contact is mPairs[mDrivableSurfaceTypes[x].mType][y],
140 assuming a tire type y.
141
142 \note If the PxMaterial that touches the tire is not found in mDrivableSurfaceMaterials then the friction is
143 mPairs[0][y], assuming a tire type y.
144 */
145 const PxMaterial** mDrivableSurfaceMaterials;
146
147 /**
148 \brief Ptr to 1d array of PxVehicleDrivableSurfaceType that is of length mNbSurfaceTypes.
149
150 \note If the PxMaterial that touches the tire is found in mDrivableSurfaceMaterials[x] then the drivable surface
151 type is mDrivableSurfaceTypes[x].mType and the friction for that contact is mPairs[mDrivableSurfaceTypes[x].mType][y],
152 assuming a tire type y.
153
154 \note If the PxMaterial that touches the tire is not found in mDrivableSurfaceMaterials then the friction is
155 mPairs[0][y], assuming a tire type y.
156 */
157 PxVehicleDrivableSurfaceType* mDrivableSurfaceTypes;
158
159 /**
160 \brief Number of different driving surface types.
161
162 \note mDrivableSurfaceMaterials and mDrivableSurfaceTypes are both 1d arrays of length mMaxNbSurfaceTypes.
163
164 \note mNbSurfaceTypes must be less than or equal to mMaxNbSurfaceTypes.
165 */
166 PxU32 mNbSurfaceTypes;
167
168 /**
169 \brief Maximum number of different driving surface types.
170
171 \note mMaxNbSurfaceTypes must be less than or equal to eMAX_NB_SURFACE_TYPES.
172 */
173 PxU32 mMaxNbSurfaceTypes;
174
175 /**
176 \brief Number of different tire types.
177
178 \note Tire types stored in PxVehicleTireData.mType
179 */
180 PxU32 mNbTireTypes;
181
182 /**
183 \brief Maximum number of different tire types.
184
185 \note Tire types stored in PxVehicleTireData.mType
186 */
187 PxU32 mMaxNbTireTypes;
188
189
190#if !defined(PX_P64)
191 PxU32 mPad[1];
192#else
193 PxU32 mPad[2];
194#endif
195
196 PxVehicleDrivableSurfaceToTireFrictionPairs(){}
197 ~PxVehicleDrivableSurfaceToTireFrictionPairs(){}
198};
199PX_COMPILE_TIME_ASSERT(0==(sizeof(PxVehicleDrivableSurfaceToTireFrictionPairs) & 15));
200
201#ifndef PX_DOXYGEN
202} // namespace physx
203#endif
204
205/** @} */
206#endif //PX_VEHICLE_TIREFRICTION_H
207