== SoC Bullet - Bullet Upgrade to 2.76 ==
[blender.git] / extern / bullet2 / BulletCollision / CollisionShapes / btHeightfieldTerrainShape.h
1 /*
2 Bullet Continuous Collision Detection and Physics Library
3 Copyright (c) 2003-2009 Erwin Coumans  http://bulletphysics.org
4
5 This software is provided 'as-is', without any express or implied warranty.
6 In no event will the authors be held liable for any damages arising from the use of this software.
7 Permission is granted to anyone to use this software for any purpose, 
8 including commercial applications, and to alter it and redistribute it freely, 
9 subject to the following restrictions:
10
11 1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
12 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
13 3. This notice may not be removed or altered from any source distribution.
14 */
15
16 #ifndef HEIGHTFIELD_TERRAIN_SHAPE_H
17 #define HEIGHTFIELD_TERRAIN_SHAPE_H
18
19 #include "btConcaveShape.h"
20
21 ///btHeightfieldTerrainShape simulates a 2D heightfield terrain
22 /**
23   The caller is responsible for maintaining the heightfield array; this
24   class does not make a copy.
25
26   The heightfield can be dynamic so long as the min/max height values
27   capture the extremes (heights must always be in that range).
28
29   The local origin of the heightfield is assumed to be the exact
30   center (as determined by width and length and height, with each
31   axis multiplied by the localScaling).
32
33   \b NOTE: be careful with coordinates.  If you have a heightfield with a local
34   min height of -100m, and a max height of +500m, you may be tempted to place it
35   at the origin (0,0) and expect the heights in world coordinates to be
36   -100 to +500 meters.
37   Actually, the heights will be -300 to +300m, because bullet will re-center
38   the heightfield based on its AABB (which is determined by the min/max
39   heights).  So keep in mind that once you create a btHeightfieldTerrainShape
40   object, the heights will be adjusted relative to the center of the AABB.  This
41   is different to the behavior of many rendering engines, but is useful for
42   physics engines.
43
44   Most (but not all) rendering and heightfield libraries assume upAxis = 1
45   (that is, the y-axis is "up").  This class allows any of the 3 coordinates
46   to be "up".  Make sure your choice of axis is consistent with your rendering
47   system.
48
49   The heightfield heights are determined from the data type used for the
50   heightfieldData array.  
51
52    - PHY_UCHAR: height at a point is the uchar value at the
53        grid point, multipled by heightScale.  uchar isn't recommended
54        because of its inability to deal with negative values, and
55        low resolution (8-bit).
56
57    - PHY_SHORT: height at a point is the short int value at that grid
58        point, multipled by heightScale.
59
60    - PHY_FLOAT: height at a point is the float value at that grid
61        point.  heightScale is ignored when using the float heightfield
62        data type.
63
64   Whatever the caller specifies as minHeight and maxHeight will be honored.
65   The class will not inspect the heightfield to discover the actual minimum
66   or maximum heights.  These values are used to determine the heightfield's
67   axis-aligned bounding box, multiplied by localScaling.
68
69   For usage and testing see the TerrainDemo.
70  */
71 class btHeightfieldTerrainShape : public btConcaveShape
72 {
73 protected:
74         btVector3       m_localAabbMin;
75         btVector3       m_localAabbMax;
76         btVector3       m_localOrigin;
77
78         ///terrain data
79         int     m_heightStickWidth;
80         int m_heightStickLength;
81         btScalar        m_minHeight;
82         btScalar        m_maxHeight;
83         btScalar m_width;
84         btScalar m_length;
85         btScalar m_heightScale;
86         union
87         {
88                 unsigned char*  m_heightfieldDataUnsignedChar;
89                 short*          m_heightfieldDataShort;
90                 btScalar*                       m_heightfieldDataFloat;
91                 void*                   m_heightfieldDataUnknown;
92         };
93
94         PHY_ScalarType  m_heightDataType;       
95         bool    m_flipQuadEdges;
96   bool  m_useDiamondSubdivision;
97
98         int     m_upAxis;
99         
100         btVector3       m_localScaling;
101
102         virtual btScalar        getRawHeightFieldValue(int x,int y) const;
103         void            quantizeWithClamp(int* out, const btVector3& point,int isMax) const;
104         void            getVertex(int x,int y,btVector3& vertex) const;
105
106
107
108         /// protected initialization
109         /**
110           Handles the work of constructors so that public constructors can be
111           backwards-compatible without a lot of copy/paste.
112          */
113         void initialize(int heightStickWidth, int heightStickLength,
114                         void* heightfieldData, btScalar heightScale,
115                         btScalar minHeight, btScalar maxHeight, int upAxis,
116                         PHY_ScalarType heightDataType, bool flipQuadEdges);
117
118 public:
119         /// preferred constructor
120         /**
121           This constructor supports a range of heightfield
122           data types, and allows for a non-zero minimum height value.
123           heightScale is needed for any integer-based heightfield data types.
124          */
125         btHeightfieldTerrainShape(int heightStickWidth,int heightStickLength,
126                                   void* heightfieldData, btScalar heightScale,
127                                   btScalar minHeight, btScalar maxHeight,
128                                   int upAxis, PHY_ScalarType heightDataType,
129                                   bool flipQuadEdges);
130
131         /// legacy constructor
132         /**
133           The legacy constructor assumes the heightfield has a minimum height
134           of zero.  Only unsigned char or floats are supported.  For legacy
135           compatibility reasons, heightScale is calculated as maxHeight / 65535 
136           (and is only used when useFloatData = false).
137          */
138         btHeightfieldTerrainShape(int heightStickWidth,int heightStickLength,void* heightfieldData, btScalar maxHeight,int upAxis,bool useFloatData,bool flipQuadEdges);
139
140         virtual ~btHeightfieldTerrainShape();
141
142
143         void setUseDiamondSubdivision(bool useDiamondSubdivision=true) { m_useDiamondSubdivision = useDiamondSubdivision;}
144
145
146         virtual void getAabb(const btTransform& t,btVector3& aabbMin,btVector3& aabbMax) const;
147
148         virtual void    processAllTriangles(btTriangleCallback* callback,const btVector3& aabbMin,const btVector3& aabbMax) const;
149
150         virtual void    calculateLocalInertia(btScalar mass,btVector3& inertia) const;
151
152         virtual void    setLocalScaling(const btVector3& scaling);
153         
154         virtual const btVector3& getLocalScaling() const;
155         
156         //debugging
157         virtual const char*     getName()const {return "HEIGHTFIELD";}
158
159 };
160
161 #endif //HEIGHTFIELD_TERRAIN_SHAPE_H