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

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