btHeightfieldTerrainShape simulates a 2D heightfield terrain More...

#include <btHeightfieldTerrainShape.h>

Inheritance diagram for btHeightfieldTerrainShape:

Collaboration diagram for btHeightfieldTerrainShape:

[legend]

Classes
struct	Range

Public Member Functions
	BT_DECLARE_ALIGNED_ALLOCATOR ()

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const float *heightfieldData, btScalar minHeight, btScalar maxHeight, int upAxis, bool flipQuadEdges)
	preferred constructors More...

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const double *heightfieldData, btScalar minHeight, btScalar maxHeight, int upAxis, bool flipQuadEdges)

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const short *heightfieldData, btScalar heightScale, btScalar minHeight, btScalar maxHeight, int upAxis, bool flipQuadEdges)

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const unsigned char *heightfieldData, btScalar heightScale, btScalar minHeight, btScalar maxHeight, int upAxis, bool flipQuadEdges)

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const void *heightfieldData, btScalar heightScale, btScalar minHeight, btScalar maxHeight, int upAxis, PHY_ScalarType heightDataType, bool flipQuadEdges)
	legacy constructor More...

	btHeightfieldTerrainShape (int heightStickWidth, int heightStickLength, const void *heightfieldData, btScalar maxHeight, int upAxis, bool useFloatData, bool flipQuadEdges)
	legacy constructor More...

virtual	~btHeightfieldTerrainShape ()

void	setUseDiamondSubdivision (bool useDiamondSubdivision=true)

void	setUseZigzagSubdivision (bool useZigzagSubdivision=true)
	could help compatibility with Ogre heightfields. See https://code.google.com/p/bullet/issues/detail?id=625 More...

void	setFlipTriangleWinding (bool flipTriangleWinding)

virtual void	getAabb (const btTransform &t, btVector3 &aabbMin, btVector3 &aabbMax) const
	getAabb returns the axis aligned bounding box in the coordinate frame of the given transform t. More...

virtual void	processAllTriangles (btTriangleCallback *callback, const btVector3 &aabbMin, const btVector3 &aabbMax) const
	process all triangles within the provided axis-aligned bounding box More...

virtual void	calculateLocalInertia (btScalar mass, btVector3 &inertia) const

virtual void	setLocalScaling (const btVector3 &scaling)

virtual const btVector3 &	getLocalScaling () const

void	getVertex (int x, int y, btVector3 &vertex) const
	this returns the vertex in bullet-local coordinates More...

void	performRaycast (btTriangleCallback *callback, const btVector3 &raySource, const btVector3 &rayTarget) const
	Performs a raycast using a hierarchical Bresenham algorithm. More...

void	buildAccelerator (int chunkSize=16)
	Builds a grid data structure storing the min and max heights of the terrain in chunks. More...

void	clearAccelerator ()

int	getUpAxis () const

virtual const char *	getName () const

void	setUserValue3 (btScalar value)

btScalar	getUserValue3 () const

const struct btTriangleInfoMap *	getTriangleInfoMap () const

struct btTriangleInfoMap *	getTriangleInfoMap ()

void	setTriangleInfoMap (btTriangleInfoMap *map)

const unsigned char *	getHeightfieldRawData () const

Public Member Functions inherited from btConcaveShape
	BT_DECLARE_ALIGNED_ALLOCATOR ()

	btConcaveShape ()

virtual	~btConcaveShape ()

virtual void	processAllTriangles (btTriangleCallback *callback, const btVector3 &aabbMin, const btVector3 &aabbMax) const =0

virtual btScalar	getMargin () const

virtual void	setMargin (btScalar collisionMargin)

Public Member Functions inherited from btCollisionShape
	BT_DECLARE_ALIGNED_ALLOCATOR ()

	btCollisionShape ()

virtual	~btCollisionShape ()

virtual void	getAabb (const btTransform &t, btVector3 &aabbMin, btVector3 &aabbMax) const =0
	getAabb returns the axis aligned bounding box in the coordinate frame of the given transform t. More...

virtual void	getBoundingSphere (btVector3 &center, btScalar &radius) const

virtual btScalar	getAngularMotionDisc () const
	getAngularMotionDisc returns the maximum radius needed for Conservative Advancement to handle time-of-impact with rotations. More...

virtual btScalar	getContactBreakingThreshold (btScalar defaultContactThresholdFactor) const

void	calculateTemporalAabb (const btTransform &curTrans, const btVector3 &linvel, const btVector3 &angvel, btScalar timeStep, btVector3 &temporalAabbMin, btVector3 &temporalAabbMax) const
	calculateTemporalAabb calculates the enclosing aabb for the moving object over interval [0..timeStep) result is conservative More...

bool	isPolyhedral () const

bool	isConvex2d () const

bool	isConvex () const

bool	isNonMoving () const

bool	isConcave () const

bool	isCompound () const

bool	isSoftBody () const

bool	isInfinite () const
	isInfinite is used to catch simulation error (aabb check) More...

virtual void	setLocalScaling (const btVector3 &scaling)=0

virtual const btVector3 &	getLocalScaling () const =0

virtual void	calculateLocalInertia (btScalar mass, btVector3 &inertia) const =0

virtual const char *	getName () const =0

int	getShapeType () const

virtual btVector3	getAnisotropicRollingFrictionDirection () const
	the getAnisotropicRollingFrictionDirection can be used in combination with setAnisotropicFriction See Bullet/Demos/RollingFrictionDemo for an example More...

virtual void	setMargin (btScalar margin)=0

virtual btScalar	getMargin () const =0

void	setUserPointer (void *userPtr)
	optional user data pointer More...

void *	getUserPointer () const

void	setUserIndex (int index)

int	getUserIndex () const

void	setUserIndex2 (int index)

int	getUserIndex2 () const

virtual int	calculateSerializeBufferSize () const

virtual const char *	serialize (void dataBuffer, btSerializer serializer) const
	fills the dataBuffer and returns the struct name (and 0 on failure) More...

virtual void	serializeSingleShape (btSerializer *serializer) const

Protected Member Functions
virtual btScalar	getRawHeightFieldValue (int x, int y) const
	This returns the "raw" (user's initial) height, not the actual height. More...

void	quantizeWithClamp (int *out, const btVector3 &point, int isMax) const
	given input vector, return quantized version More...

void	initialize (int heightStickWidth, int heightStickLength, const void *heightfieldData, btScalar heightScale, btScalar minHeight, btScalar maxHeight, int upAxis, PHY_ScalarType heightDataType, bool flipQuadEdges)
	protected initialization More...

Protected Attributes
btVector3	m_localAabbMin

btVector3	m_localAabbMax

btVector3	m_localOrigin

int	m_heightStickWidth
	terrain data More...

int	m_heightStickLength

btScalar	m_minHeight

btScalar	m_maxHeight

btScalar	m_width

btScalar	m_length

btScalar	m_heightScale

union {
const unsigned char * m_heightfieldDataUnsignedChar

const short * m_heightfieldDataShort

const float * m_heightfieldDataFloat

const double * m_heightfieldDataDouble

const void * m_heightfieldDataUnknown

};

PHY_ScalarType	m_heightDataType

bool	m_flipQuadEdges

bool	m_useDiamondSubdivision

bool	m_useZigzagSubdivision

bool	m_flipTriangleWinding

int	m_upAxis

btVector3	m_localScaling

btAlignedObjectArray< Range >	m_vboundsGrid

int	m_vboundsGridWidth

int	m_vboundsGridLength

int	m_vboundsChunkSize

btScalar	m_userValue3

struct btTriangleInfoMap *	m_triangleInfoMap

Protected Attributes inherited from btConcaveShape
btScalar	m_collisionMargin

Protected Attributes inherited from btCollisionShape
int	m_shapeType

void *	m_userPointer

int	m_userIndex

int	m_userIndex2

Detailed Description

btHeightfieldTerrainShape simulates a 2D heightfield terrain

The caller is responsible for maintaining the heightfield array; this class does not make a copy.

The heightfield can be dynamic so long as the min/max height values capture the extremes (heights must always be in that range).

The local origin of the heightfield is assumed to be the exact center (as determined by width and length and height, with each axis multiplied by the localScaling).

NOTE: be careful with coordinates. If you have a heightfield with a local min height of -100m, and a max height of +500m, you may be tempted to place it at the origin (0,0) and expect the heights in world coordinates to be -100 to +500 meters. Actually, the heights will be -300 to +300m, because bullet will re-center the heightfield based on its AABB (which is determined by the min/max heights). So keep in mind that once you create a btHeightfieldTerrainShape object, the heights will be adjusted relative to the center of the AABB. This is different to the behavior of many rendering engines, but is useful for physics engines.

Most (but not all) rendering and heightfield libraries assume upAxis = 1 (that is, the y-axis is "up"). This class allows any of the 3 coordinates to be "up". Make sure your choice of axis is consistent with your rendering system.

The heightfield heights are determined from the data type used for the heightfieldData array.

unsigned char: height at a point is the uchar value at the grid point, multipled by heightScale. uchar isn't recommended because of its inability to deal with negative values, and low resolution (8-bit).
short: height at a point is the short int value at that grid point, multipled by heightScale.
float or dobule: height at a point is the value at that grid point.

Whatever the caller specifies as minHeight and maxHeight will be honored. The class will not inspect the heightfield to discover the actual minimum or maximum heights. These values are used to determine the heightfield's axis-aligned bounding box, multiplied by localScaling.

For usage and testing see the TerrainDemo.

Definition at line 70 of file btHeightfieldTerrainShape.h.

Constructor & Destructor Documentation

◆ btHeightfieldTerrainShape() [1/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const float *	heightfieldData,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		bool	flipQuadEdges
	)

preferred constructors

Definition at line 20 of file btHeightfieldTerrainShape.cpp.

◆ btHeightfieldTerrainShape() [2/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const double *	heightfieldData,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		bool	flipQuadEdges
	)

Definition at line 31 of file btHeightfieldTerrainShape.cpp.

◆ btHeightfieldTerrainShape() [3/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const short *	heightfieldData,
		btScalar	heightScale,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		bool	flipQuadEdges
	)

Definition at line 41 of file btHeightfieldTerrainShape.cpp.

◆ btHeightfieldTerrainShape() [4/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const unsigned char *	heightfieldData,
		btScalar	heightScale,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		bool	flipQuadEdges
	)

Definition at line 51 of file btHeightfieldTerrainShape.cpp.

◆ btHeightfieldTerrainShape() [5/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const void *	heightfieldData,
		btScalar	heightScale,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		PHY_ScalarType	heightDataType,
		bool	flipQuadEdges
	)

legacy constructor

This constructor supports a range of heightfield data types, and allows for a non-zero minimum height value. heightScale is needed for any integer-based heightfield data types.

This legacy constructor considers PHY_FLOAT to mean btScalar. With BT_USE_DOUBLE_PRECISION, it will expect heightfieldData to be double-precision.

Definition at line 61 of file btHeightfieldTerrainShape.cpp.

◆ btHeightfieldTerrainShape() [6/6]

btHeightfieldTerrainShape::btHeightfieldTerrainShape	(	int	heightStickWidth,
		int	heightStickLength,
		const void *	heightfieldData,
		btScalar	maxHeight,
		int	upAxis,
		bool	useFloatData,
		bool	flipQuadEdges
	)

legacy constructor

The legacy constructor assumes the heightfield has a minimum height of zero. Only unsigned char or btScalar data are supported. For legacy compatibility reasons, heightScale is calculated as maxHeight / 65535 (and is only used when useFloatData = false).

Definition at line 77 of file btHeightfieldTerrainShape.cpp.

◆ ~btHeightfieldTerrainShape()

btHeightfieldTerrainShape::~btHeightfieldTerrainShape ( )

virtual

Definition at line 166 of file btHeightfieldTerrainShape.cpp.

Member Function Documentation

◆ BT_DECLARE_ALIGNED_ALLOCATOR()

btHeightfieldTerrainShape::BT_DECLARE_ALIGNED_ALLOCATOR ( )

◆ buildAccelerator()

void btHeightfieldTerrainShape::buildAccelerator ( int chunkSize = 16 )

Builds a grid data structure storing the min and max heights of the terrain in chunks.

if chunkSize is zero, that accelerator is removed. If you modify the heights, you need to rebuild this accelerator.

Definition at line 850 of file btHeightfieldTerrainShape.cpp.

◆ calculateLocalInertia()

void btHeightfieldTerrainShape::calculateLocalInertia	(	btScalar	mass,
		btVector3 &	inertia
	)		const

virtual

Implements btCollisionShape.

Definition at line 481 of file btHeightfieldTerrainShape.cpp.

◆ clearAccelerator()

void btHeightfieldTerrainShape::clearAccelerator ( )

Definition at line 948 of file btHeightfieldTerrainShape.cpp.

◆ getAabb()

void btHeightfieldTerrainShape::getAabb	(	const btTransform &	t,
		btVector3 &	aabbMin,
		btVector3 &	aabbMax
	)		const

virtual

getAabb returns the axis aligned bounding box in the coordinate frame of the given transform t.

Implements btCollisionShape.

Definition at line 171 of file btHeightfieldTerrainShape.cpp.

◆ getHeightfieldRawData()

const unsigned char * btHeightfieldTerrainShape::getHeightfieldRawData ( ) const

inline

Definition at line 244 of file btHeightfieldTerrainShape.h.

◆ getLocalScaling()

const btVector3 & btHeightfieldTerrainShape::getLocalScaling ( ) const

virtual

Implements btCollisionShape.

Definition at line 492 of file btHeightfieldTerrainShape.cpp.

◆ getName()

virtual const char * btHeightfieldTerrainShape::getName ( ) const

inlinevirtual

Implements btCollisionShape.

Definition at line 221 of file btHeightfieldTerrainShape.h.

◆ getRawHeightFieldValue()

btScalar btHeightfieldTerrainShape::getRawHeightFieldValue	(	int	x,
		int	y
	)		const

protectedvirtual

This returns the "raw" (user's initial) height, not the actual height.

The actual height needs to be adjusted to be relative to the center of the heightfield's AABB.

Definition at line 192 of file btHeightfieldTerrainShape.cpp.

◆ getTriangleInfoMap() [1/2]

struct btTriangleInfoMap * btHeightfieldTerrainShape::getTriangleInfoMap ( )

inline

Definition at line 236 of file btHeightfieldTerrainShape.h.

◆ getTriangleInfoMap() [2/2]

const struct btTriangleInfoMap * btHeightfieldTerrainShape::getTriangleInfoMap ( ) const

inline

Definition at line 232 of file btHeightfieldTerrainShape.h.

◆ getUpAxis()

int btHeightfieldTerrainShape::getUpAxis ( ) const

inline

Definition at line 216 of file btHeightfieldTerrainShape.h.

◆ getUserValue3()

btScalar btHeightfieldTerrainShape::getUserValue3 ( ) const

inline

Definition at line 228 of file btHeightfieldTerrainShape.h.

◆ getVertex()

void btHeightfieldTerrainShape::getVertex	(	int	x,
		int	y,
		btVector3 &	vertex
	)		const

this returns the vertex in bullet-local coordinates

Definition at line 233 of file btHeightfieldTerrainShape.cpp.

◆ initialize()

void btHeightfieldTerrainShape::initialize	(	int	heightStickWidth,
		int	heightStickLength,
		const void *	heightfieldData,
		btScalar	heightScale,
		btScalar	minHeight,
		btScalar	maxHeight,
		int	upAxis,
		PHY_ScalarType	heightDataType,
		bool	flipQuadEdges
	)

protected

protected initialization

Handles the work of constructors so that public constructors can be backwards-compatible without a lot of copy/paste.

Definition at line 98 of file btHeightfieldTerrainShape.cpp.

◆ performRaycast()

void btHeightfieldTerrainShape::performRaycast	(	btTriangleCallback *	callback,
		const btVector3 &	raySource,
		const btVector3 &	rayTarget
	)		const

Performs a raycast using a hierarchical Bresenham algorithm.

Does not allocate any memory by itself.

Definition at line 779 of file btHeightfieldTerrainShape.cpp.

◆ processAllTriangles()

void btHeightfieldTerrainShape::processAllTriangles	(	btTriangleCallback *	callback,
		const btVector3 &	aabbMin,
		const btVector3 &	aabbMax
	)		const

virtual

process all triangles within the provided axis-aligned bounding box

basic algorithm:

convert input aabb to local coordinates (scale down and shift for local origin)
convert input aabb to a range of heightfield grid points (quantize)
iterate over all triangles in that subset of the grid

Implements btConcaveShape.

Definition at line 340 of file btHeightfieldTerrainShape.cpp.

◆ quantizeWithClamp()

void btHeightfieldTerrainShape::quantizeWithClamp	(	int *	out,
		const btVector3 &	point,
		int	isMax
	)		const

protected

given input vector, return quantized version

This routine is basically determining the gridpoint indices for a given input vector, answering the question: "which gridpoint is closest to the provided point?".

"with clamp" means that we restrict the point to be in the heightfield's axis-aligned bounding box.

Definition at line 322 of file btHeightfieldTerrainShape.cpp.