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 |
41 | namespace physx |
42 | { |
43 | #endif |
44 | |
45 | class PxScene; |
46 | |
47 | /** |
48 | \brief Flags which control the behavior of a material. |
49 | |
50 | @see PxMaterial |
51 | */ |
52 | struct 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 | */ |
102 | typedef PxFlags<PxMaterialFlag::Enum,PxU16> PxMaterialFlags; |
103 | PX_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 | |
109 | When 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 | |
111 | Physics doesn't have any inherent combinations because the coefficients are determined empirically on a case by case |
112 | basis. However, simulating this with a pairwise lookup table is often impractical. |
113 | |
114 | For this reason the following combine behaviors are available: |
115 | |
116 | eAVERAGE |
117 | eMIN |
118 | eMULTIPLY |
119 | eMAX |
120 | |
121 | The effective combine mode for the pair is maximum(material0.combineMode, material1.combineMode). |
122 | |
123 | @see PxMaterial.setFrictionCombineMode() PxMaterial.getFrictionCombineMode() PxMaterial.setRestitutionCombineMode() PxMaterial.getFrictionCombineMode() |
124 | */ |
125 | struct 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 | */ |
143 | class PxMaterial : public PxBase |
144 | { |
145 | public: |
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 | |
335 | protected: |
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 | |