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_NXMATERIAL
15#define PX_PHYSICS_NXMATERIAL
16/** \addtogroup physics
17@{
18*/
19
20#include "PxPhysXConfig.h"
21#include "common/PxBase.h"
22
23#ifndef PX_DOXYGEN
24namespace physx
25{
26#endif
27
28class PxScene;
29
30/**
31\brief Flags which control the behavior of a material.
32
33@see PxMaterial
34*/
35struct PxMaterialFlag
36{
37 enum Enum
38 {
39
40 /**
41 If this flag is set, friction computations are always skipped between shapes with this material and any other shape.
42 */
43 eDISABLE_FRICTION = 1 << 0,
44
45 /**
46 The difference between "normal" and "strong" friction is that the strong friction feature
47 remembers the "friction error" between simulation steps. The friction is a force trying to
48 hold objects in place (or slow them down) and this is handled in the solver. But since the
49 solver is only an approximation, the result of the friction calculation can include a small
50 "error" - e.g. a box resting on a slope should not move at all if the static friction is in
51 action, but could slowly glide down the slope because of a small friction error in each
52 simulation step. The strong friction counter-acts this by remembering the small error and
53 taking it to account during the next simulation step.
54
55 However, in some cases the strong friction could cause problems, and this is why it is
56 possible to disable the strong friction feature by setting this flag. One example is
57 raycast vehicles, that are sliding fast across the surface, but still need a precise
58 steering behavior. It may be a good idea to reenable the strong friction when objects
59 are coming to a rest, to prevent them from slowly creeping down inclines.
60
61 Note: This flag only has an effect if the PxMaterialFlag::eDISABLE_FRICTION bit is 0.
62 */
63 eDISABLE_STRONG_FRICTION = 1 << 1
64 };
65};
66
67/**
68\brief collection of set bits defined in PxMaterialFlag.
69
70@see PxMaterialFlag
71*/
72typedef PxFlags<PxMaterialFlag::Enum,PxU16> PxMaterialFlags;
73PX_FLAGS_OPERATORS(PxMaterialFlag::Enum,PxU16)
74
75
76/**
77\brief enumeration that determines the way in which two material properties will be combined to yield a friction or restitution coefficient for a collision.
78
79When two actors come in contact with each other, they each have materials with various coefficients, but we only need a single set of coefficients for the pair.
80
81Physics doesn't have any inherent combinations because the coefficients are determined empirically on a case by case
82basis. However, simulating this with a pairwise lookup table is often impractical.
83
84For this reason the following combine behaviors are available:
85
86eAVERAGE
87eMIN
88eMULTIPLY
89eMAX
90
91The effective combine mode for the pair is maximum(material0.combineMode, material1.combineMode).
92
93@see PxMaterial.setFrictionCombineMode() PxMaterial.getFrictionCombineMode() PxMaterial.setRestitutionCombineMode() PxMaterial.getFrictionCombineMode()
94*/
95struct PxCombineMode
96{
97 enum Enum
98 {
99 eAVERAGE = 0, //!< Average: (a + b)/2
100 eMIN = 1, //!< Minimum: minimum(a,b)
101 eMULTIPLY = 2, //!< Multiply: a*b
102 eMAX = 3, //!< Maximum: maximum(a,b)
103 eN_VALUES = 4, //!< This is not a valid combine mode, it is a sentinel to denote the number of possible values. We assert that the variable's value is smaller than this.
104 ePAD_32 = 0x7fffffff //!< This is not a valid combine mode, it is to assure that the size of the enum type is big enough.
105 };
106};
107
108/**
109\brief Material class to represent a set of surface properties.
110
111@see PxPhysics.createMaterial
112*/
113class PxMaterial : public PxBase
114{
115public:
116
117 /**
118 \brief Decrements the reference count of a material and releases it if the new reference count is zero.
119
120 The material is destroyed when the application's reference is released and all shapes referencing the material are destroyed.
121
122 @see PxPhysics.createMaterial()
123 */
124 virtual void release() = 0;
125
126 /**
127 \brief Returns the reference count of the material.
128
129 At creation, the reference count of the material is 1. Every shape referencing this material increments the
130 count by 1. When the reference count reaches 0, and only then, the material gets destroyed automatically.
131
132 \return the current reference count.
133 */
134 virtual PxU32 getReferenceCount() const = 0;
135
136 /**
137 \brief Sets the coefficient of dynamic friction.
138
139 The coefficient of dynamic friction should be in [0, PX_MAX_F32). If set to greater than staticFriction, the effective value of staticFriction will be increased to match.
140
141 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
142
143 \param[in] coef Coefficient of dynamic friction. <b>Range:</b> [0, PX_MAX_F32)
144
145 @see getDynamicFriction()
146 */
147 virtual void setDynamicFriction(PxReal coef) = 0;
148
149 /**
150 \brief Retrieves the DynamicFriction value.
151
152 \return The coefficient of dynamic friction.
153
154 @see setDynamicFriction
155 */
156 virtual PxReal getDynamicFriction() const = 0;
157
158 /**
159 \brief Sets the coefficient of static friction
160
161 The coefficient of static friction should be in the range [0, PX_MAX_F32)
162
163 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
164
165 \param[in] coef Coefficient of static friction. <b>Range:</b> [0, PX_MAX_F32)
166
167 @see getStaticFriction()
168 */
169 virtual void setStaticFriction(PxReal coef) = 0;
170
171 /**
172 \brief Retrieves the coefficient of static friction.
173 \return The coefficient of static friction.
174
175 @see setStaticFriction
176 */
177 virtual PxReal getStaticFriction() const = 0;
178
179 /**
180 \brief Sets the coefficient of restitution
181
182 A coefficient of 0 makes the object bounce as little as possible, higher values up to 1.0 result in more bounce.
183
184 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
185
186 \param[in] rest Coefficient of restitution. <b>Range:</b> [0,1]
187
188 @see getRestitution()
189 */
190 virtual void setRestitution(PxReal rest) = 0;
191
192 /**
193 \brief Retrieves the coefficient of restitution.
194
195 See #setRestitution.
196
197 \return The coefficient of restitution.
198
199 @see setRestitution()
200 */
201 virtual PxReal getRestitution() const = 0;
202
203 /**
204 \brief Raises or clears a particular material flag.
205
206 See the list of flags #PxMaterialFlag
207
208 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
209
210 \param[in] flag The PxMaterial flag to raise(set) or clear.
211
212 @see getFlags() PxMaterialFlag
213 */
214 virtual void setFlag(PxMaterialFlag::Enum flag, bool) = 0;
215
216
217 /**
218 \brief sets all the material flags.
219
220 See the list of flags #PxMaterialFlag
221
222 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
223
224 */
225 virtual void setFlags( PxMaterialFlags inFlags ) = 0;
226
227 /**
228 \brief Retrieves the flags. See #PxMaterialFlag.
229
230 \return The material flags.
231
232 @see PxMaterialFlag setFlags()
233 */
234 virtual PxMaterialFlags getFlags() const = 0;
235
236 /**
237 \brief Sets the friction combine mode.
238
239 See the enum ::PxCombineMode .
240
241 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
242
243 \param[in] combMode Friction combine mode to set for this material. See #PxCombineMode.
244
245 @see PxCombineMode getFrictionCombineMode setStaticFriction() setDynamicFriction()
246 */
247 virtual void setFrictionCombineMode(PxCombineMode::Enum combMode) = 0;
248
249 /**
250 \brief Retrieves the friction combine mode.
251
252 See #setFrictionCombineMode.
253
254 \return The friction combine mode for this material.
255
256 @see PxCombineMode setFrictionCombineMode()
257 */
258 virtual PxCombineMode::Enum getFrictionCombineMode() const = 0;
259
260 /**
261 \brief Sets the restitution combine mode.
262
263 See the enum ::PxCombineMode .
264
265 <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
266
267 \param[in] combMode Restitution combine mode for this material. See #PxCombineMode.
268
269 @see PxCombineMode getRestitutionCombineMode() setRestitution()
270 */
271 virtual void setRestitutionCombineMode(PxCombineMode::Enum combMode) = 0;
272
273 /**
274 \brief Retrieves the restitution combine mode.
275
276 See #setRestitutionCombineMode.
277
278 \return The coefficient of restitution combine mode for this material.
279
280 @see PxCombineMode setRestitutionCombineMode getRestitution()
281 */
282 virtual PxCombineMode::Enum getRestitutionCombineMode() const = 0;
283
284 //public variables:
285 void* userData; //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
286
287 virtual const char* getConcreteTypeName() const { return "PxMaterial"; }
288
289protected:
290 PX_INLINE PxMaterial(PxType concreteType, PxBaseFlags baseFlags) : PxBase(concreteType, baseFlags), userData(NULL) {}
291 PX_INLINE PxMaterial(PxBaseFlags baseFlags) : PxBase(baseFlags) {}
292 virtual ~PxMaterial() {}
293 virtual bool isKindOf(const char* name) const { return !strcmp("PxMaterial", name) || PxBase::isKindOf(name); }
294
295};
296
297#ifndef PX_DOXYGEN
298} // namespace physx
299#endif
300
301/** @} */
302#endif
303