source: GTP/trunk/App/Games/Jungle_Rumble/src/physic/physics/include/NxMaterial.h @ 1378

Revision 1378, 12.5 KB checked in by giegl, 18 years ago (diff)

GTPD - Jungle Rumble - integrate into GTP SVN structure
Line 
1#ifndef NX_PHYSICS_NXMATERIAL
2#define NX_PHYSICS_NXMATERIAL
3/*----------------------------------------------------------------------------*\
4|
5|                                               Public Interface to NovodeX Technology
6|
7|                                                            www.novodex.com
8|
9\*----------------------------------------------------------------------------*/
10/** \addtogroup physics
11  @{
12*/
13
14#include "NxMaterialDesc.h"
15
16class NxScene;
17
18/**
19\brief Class for describing a shape's surface properties.
20
21<h3>Creation</h3>
22
23Example material creation:
24\include NxMaterial_Create.cpp
25
26You can create a material which has different friction coefficients depending on the direction that
27a body in contact is trying to move in. This is called anisotropic friction.
28
29<h3>Anisotropic Friction</h3>
30
31Anisotropic friction is useful for modelling things like sledges, skis etc
32
33When you create an anisotropic material you specify the default friction parameters and also friction parameters for the V axis.
34The friction parameters for the V axis are applied to motion along the direction of anisotrpopy (dirOfAnisotropy).
35
36Anisotropic Material Example:
37\include NxMaterial_Aniso.cpp
38
39<h3>Default Material</h3>
40
41You can change the properties of the default material by querying for material index 0.
42
43Default Material Example:
44\include NxMaterial_ChangeDefault.cpp
45
46<h3>Visulizations:</h3>
47\li #NX_VISUALIZE_CONTACT_POINT
48\li #NX_VISUALIZE_CONTACT_NORMAL
49\li #NX_VISUALIZE_CONTACT_ERROR
50\li #NX_VISUALIZE_CONTACT_FORCE
51
52@see NxMaterialDesc NxScene.createMaterial
53*/
54class NxMaterial
55        {
56        protected:
57        NX_INLINE                                       NxMaterial() : userData(NULL)           {}
58        virtual                                         ~NxMaterial()   {}
59
60        public:
61        /**
62        \brief The ID of the material can be retrieved using this function.       
63       
64        Materials are associated with mesh faces and shapes using 16 bit identifiers of type NxMaterialIndex rather
65        than pointers.
66
67        If you release a material while its material ID is still in use by shapes or meshes, the material usage
68        of these objects becomes undefined as the material index gets recycled.
69
70        \return The material index for this material.
71
72        <b>Platform:</b>
73        \li PC SW: Yes
74        \li PPU  : Yes
75        \li PS3  : Yes
76        \li XB360: Yes
77
78        @see NxMaterialIndex NxTriangleMeshDesc.materialIndices NxShapeDesc.materialIndex NxShape.setMaterial()
79        */
80        virtual         NxMaterialIndex getMaterialIndex() = 0;
81
82        /**
83        \brief Loads the entire state of the material from a descriptor with a single call.
84
85        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
86
87        \param[in] desc The descriptor used to set this objects state.
88
89        <b>Platform:</b>
90        \li PC SW: Yes
91        \li PPU  : Yes
92        \li PS3  : Yes
93        \li XB360: Yes
94
95        @see saveToDesc NxMaterialDesc
96        */
97        virtual         void                    loadFromDesc(const NxMaterialDesc& desc) = 0;
98
99        /**
100        \brief Saves the state of the material into a descriptor.
101        Does not fill out the spring field, this must be queried separately using getSpring().
102
103        \param[out] desc The descriptor used to retrieve this objects state.
104
105        <b>Platform:</b>
106        \li PC SW: Yes
107        \li PPU  : Yes
108        \li PS3  : Yes
109        \li XB360: Yes
110
111        @see loadFromDesc NxMaterialDesc
112        */
113        virtual         void                    saveToDesc(NxMaterialDesc& desc) const  = 0;
114
115        /**
116        \brief retrieves owner scene
117
118        \return The scene which this material belongs to.
119
120        <b>Platform:</b>
121        \li PC SW: Yes
122        \li PPU  : Yes
123        \li PS3  : Yes
124        \li XB360: Yes
125
126        @see NxScene
127        */
128        virtual         NxScene&                getScene() = 0;
129
130        /**
131        \brief Sets the coefficient of dynamic friction.
132       
133        The coefficient of dynamic friction should be in [0, 1] and also be less or equal to staticFriction.
134        If the flag NX_MF_ANISOTROPIC is set, then this value is used for the primary direction of anisotropy (U axis)
135
136        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
137
138        \param[in] coef Coefficient of dynamic friction. <b>Range:</b> [0,1]
139
140        <b>Platform:</b>
141        \li PC SW: Yes
142        \li PPU  : Yes
143        \li PS3  : Yes
144        \li XB360: Yes
145
146        @see NxMaterialDesc.dynamicFriction getDynamicFriction()
147        */
148        virtual         void                    setDynamicFriction(NxReal coef) = 0;
149
150        /**
151        \brief Retrieves the DynamicFriction value.
152
153        \return The coefficient of dynamic friction.
154
155        <b>Platform:</b>
156        \li PC SW: Yes
157        \li PPU  : Yes
158        \li PS3  : Yes
159        \li XB360: Yes
160
161        @see setDynamicFriction NxMaterialDesc.dynamicFriction
162        */
163        virtual         NxReal                  getDynamicFriction() const = 0;
164
165        /**
166        \brief Sets the coefficient of static friction
167       
168        The coefficient of static friction should be in the range [0, +inf]
169        if flags & NX_MF_ANISOTROPIC is set, then this value is used for the primary direction of anisotropy (U axis)
170
171        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
172
173        \param[in] coef Coefficient of static friction. <b>Range:</b> [0,inf]
174
175        <b>Platform:</b>
176        \li PC SW: Yes
177        \li PPU  : Yes
178        \li PS3  : Yes
179        \li XB360: Yes
180
181        @see getStaticFriction() NxMaterialDesc.staticFriction
182        */
183        virtual         void                    setStaticFriction(NxReal coef) = 0;
184
185        /**
186        \brief Retrieves the coefficient of static friction.
187        \return The coefficient of static friction.
188
189        <b>Platform:</b>
190        \li PC SW: Yes
191        \li PPU  : Yes
192        \li PS3  : Yes
193        \li XB360: Yes
194
195        @see setStaticFriction NxMaterialDesc.staticFriction
196        */
197        virtual         NxReal                  getStaticFriction() const = 0;
198
199        /**
200        \brief Sets the coefficient of restitution
201       
202        A coefficient of 0 makes the object bounce as little as possible, higher values up to 1.0 result in more bounce.
203
204        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
205
206        \param[in] rest Coefficient of restitution. <b>Range:</b> [0,1]
207
208        <b>Platform:</b>
209        \li PC SW: Yes
210        \li PPU  : Yes
211        \li PS3  : Yes
212        \li XB360: Yes
213
214        @see getRestitution() NxMaterialDesc.restitution
215        */
216        virtual         void                    setRestitution(NxReal rest) = 0;
217
218        /**
219        \brief Retrieves the coefficient of restitution.
220
221        See #setRestitution.
222
223        \return The coefficient of restitution.
224
225        <b>Platform:</b>
226        \li PC SW: Yes
227        \li PPU  : Yes
228        \li PS3  : Yes
229        \li XB360: Yes
230
231        @see setRestitution() NxMaterialDesc.restitution
232        */
233        virtual         NxReal                  getRestitution() const = 0;
234
235        /**
236        \brief Sets the dynamic friction coefficient along the secondary (V) axis.
237
238        This is used when anisotropic friction is being applied. ie the NX_MF_ANISOTROPIC flag is set.
239
240        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
241
242        \param[in] coef Coefficient of dynamic friction in the V axis. <b>Range:</b> [0,1]
243
244        <b>Platform:</b>
245        \li PC SW: Yes
246        \li PPU  : Yes
247        \li PS3  : Yes
248        \li XB360: Yes
249
250        @see getDynamicFrictionV() NxMaterialDesc.dynamicFrictionV setFlags()
251        */
252        virtual         void                    setDynamicFrictionV(NxReal coef) = 0;
253
254        /**
255        \brief Retrieves the dynamic friction coefficient for the V direction.
256       
257        See #setDynamicFrictionV.
258
259        \return The coefficient if dynamic friction in the V direction.
260
261        <b>Platform:</b>
262        \li PC SW: Yes
263        \li PPU  : Yes
264        \li PS3  : Yes
265        \li XB360: Yes
266
267        @see setDynamicFrictionV() NxMaterialDesc.dynamicFrictionV
268        */
269        virtual         NxReal                  getDynamicFrictionV() const = 0;
270
271        /**
272        \brief Sets the static friction coefficient along the secondary (V) axis.
273
274        This is used when anisotropic friction is being applied. ie the NX_MF_ANISOTROPIC flag is set.
275
276        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
277
278        \param[in] coef Coefficient of static friction in the V axis. <b>Range:</b> [0,inf]
279
280        <b>Platform:</b>
281        \li PC SW: Yes
282        \li PPU  : Yes
283        \li PS3  : Yes
284        \li XB360: Yes
285
286        @see getStaticFrictionV() NxMaterialDesc.staticFrictionV setFlags()
287        */
288        virtual         void                    setStaticFrictionV(NxReal coef) = 0;
289
290        /**
291        \brief Retrieves the static friction coefficient for the V direction.
292
293        \return The coefficient of static friction in the V direction.
294
295        <b>Platform:</b>
296        \li PC SW: Yes
297        \li PPU  : Yes
298        \li PS3  : Yes
299        \li XB360: Yes
300
301        @see setStaticFrictionV() NxMaterialDesc.staticFrictionV
302        */
303        virtual         NxReal                  getStaticFrictionV() const = 0;
304
305        /**
306        \brief Sets the shape space direction (unit vector) of anisotropy.
307
308        This is used when anisotropic friction is being applied. ie the NX_MF_ANISOTROPIC flag is set.
309
310        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
311
312        \param[in] vec Shape space direction of anistropy. <b>Range:</b> direction vector
313
314        <b>Platform:</b>
315        \li PC SW: Yes
316        \li PPU  : Yes
317        \li PS3  : Yes
318        \li XB360: Yes
319
320        @see getDirOfAnisotropy() NxMaterialDesc.dirOfAnisotropy setFlags()
321        */
322        virtual         void                    setDirOfAnisotropy(const NxVec3 &vec) = 0;
323
324        /**
325        \brief Retrieves the direction of anisotropy value.
326
327        \return The direction of anisotropy.
328
329        <b>Platform:</b>
330        \li PC SW: Yes
331        \li PPU  : Yes
332        \li PS3  : Yes
333        \li XB360: Yes
334
335        @see setDirOfAnisotropy() NxMaterialDesc.dirOfAnisotropy setFlags()
336        */
337        virtual         NxVec3                  getDirOfAnisotropy() const = 0;
338
339        /**
340        \brief Sets the flags, a combination of the bits defined by the enum ::NxMaterialFlag .
341
342        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
343
344        \param[in] flags #NxMaterialFlag combination.
345
346        <b>Platform:</b>
347        \li PC SW: Yes
348        \li PPU  : Partial
349        \li PS3  : Yes
350        \li XB360: Yes
351
352        @see getFlags() NxMaterialFlag
353        */
354        virtual         void                    setFlags(NxU32 flags) = 0;
355
356        /**
357        \brief Retrieves the flags. See #NxMaterialFlag.
358
359        \return The material flags.
360
361        <b>Platform:</b>
362        \li PC SW: Yes
363        \li PPU  : Partial
364        \li PS3  : Yes
365        \li XB360: Yes
366
367        @see NxMaterialFlag setFlags()
368        */
369        virtual         NxU32                   getFlags() const = 0;
370
371        /**
372        \brief Sets the friction combine mode.
373       
374        See the enum ::NxCombineMode .
375
376        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
377
378        \param[in] combMode Friction combine mode to set for this material. See #NxCombineMode.
379
380        <b>Platform:</b>
381        \li PC SW: Yes
382        \li PPU  : No
383        \li PS3  : Yes
384        \li XB360: Yes
385
386        @see NxCombineMode getFrictionCombineMode setStaticFriction() setDynamicFriction()
387        */
388        virtual         void                    setFrictionCombineMode(NxCombineMode combMode) = 0;
389
390        /**
391        \brief Retrieves the friction combine mode.
392       
393        See #setFrictionCombineMode.
394
395        \return The friction combine mode for this material.
396
397        <b>Platform:</b>
398        \li PC SW: Yes
399        \li PPU  : No
400        \li PS3  : Yes
401        \li XB360: Yes
402
403        @see NxCombineMode setFrictionCombineMode()
404        */
405        virtual         NxCombineMode   getFrictionCombineMode() const = 0;
406
407        /**
408        \brief Sets the restitution combine mode.
409       
410        See the enum ::NxCombineMode .
411
412        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
413
414        \param[in] combMode Restitution combine mode for this material. See #NxCombineMode.
415
416        <b>Platform:</b>
417        \li PC SW: Yes
418        \li PPU  : No
419        \li PS3  : Yes
420        \li XB360: Yes
421
422        @see NxCombineMode getRestitutionCombineMode() setRestitution()
423        */
424        virtual         void                    setRestitutionCombineMode(NxCombineMode combMode) = 0;
425
426        /**
427        \brief Retrieves the restitution combine mode.
428       
429        See #setRestitutionCombineMode.
430
431        \return The coefficient of restitution combine mode for this material.
432
433        <b>Platform:</b>
434        \li PC SW: Yes
435        \li PPU  : No
436        \li PS3  : Yes
437        \li XB360: Yes
438
439        @see NxCombineMode setRestitutionCombineMode getRestitution()
440        */
441        virtual         NxCombineMode   getRestitutionCombineMode() const = 0;
442
443        /**
444        \brief Sets the additional spring property for materials with the NX_MF_SPRING_CONTACT flag.
445
446        <b>Sleeping:</b> Does <b>NOT</b> wake any actors which may be affected.
447
448        \param[in] desc Used to set the spring properties of this material. <b>Range:</b> See #NxSpringDesc
449
450        <b>Platform:</b>
451        \li PC SW: Yes
452        \li PPU  : No
453        \li PS3  : Yes
454        \li XB360: Yes
455
456        @see getSpring() setFlags() NxSpringDesc NxMaterialDesc.spring
457        */
458        virtual         void                    setSpring(const NxSpringDesc &desc) = 0;
459
460        /**
461        \brief Gets the additional spring property for materials with the NX_MF_SPRING_CONTACT flag.
462
463        \return Spring properties for this material. See #NxSpringDesc.
464
465        <b>Platform:</b>
466        \li PC SW: Yes
467        \li PPU  : No
468        \li PS3  : Yes
469        \li XB360: Yes
470
471        @see NxSpringDesc NxMaterialDesc.spring setSpring()
472        */
473        virtual         NxSpringDesc    getSpring() const = 0;
474
475        //public variables:
476                                void*                   userData;       //!< user can assign this to whatever, usually to create a 1:1 relationship with a user object.
477        };
478
479
480//typedef NxMaterial * NxMaterialIndex;   //legacy support (problematic because the size used to be 2 bytes)
481
482/** @} */
483#endif
484
485
486//AGCOPYRIGHTBEGIN
487///////////////////////////////////////////////////////////////////////////
488// Copyright © 2005 AGEIA Technologies.
489// All rights reserved. www.ageia.com
490///////////////////////////////////////////////////////////////////////////
491//AGCOPYRIGHTEND
492
Note: See TracBrowser for help on using the repository browser.