DHeightfield
From ODE Wiki
Contents |
Introduction
dHeightfield is a regular grid heightfield collider. It can be used for heightmap terrains, but also for deformable animated water surfaces.
Heightfield Data
The dHeightfieldData is a storage class, similar to the dTrimeshData class, that holds all geom properties and optionally height sample data.
dGeomHeightfieldDataCreate
dHeightfieldDataID dGeomHeightfieldDataCreate()
Allocates a new dHeightfieldDataID and returns it. You must call dGeomHeightfieldDataDestroy to destroy it after the geom has been removed. The dHeightfieldDataID value is used when specifying a data format type.
dGeomHeightfieldDataBuild*
There are four functions to easily build a heightfield from an array of height values of different data types. They all have the same parameters, except the data type of the pHeightData pointer is different:
void dGeomHeightfieldDataBuildByte(dHeightfieldDataID d,
const unsigned char *pHeightData,
...
void dGeomHeightfieldDataBuildShort(dHeightfieldDataID d,
const short *pHeightData,
...
void dGeomHeightfieldDataBuildSingle(dHeightfieldDataID d,
const float *pHeightData,
...
void dGeomHeightfieldDataBuildDouble(dHeightfieldDataID d,
const double *pHeightData,
int bCopyHeightData,
dReal width,
dReal depth,
int widthSamples,
int depthSamples,
dReal scale,
dReal offset,
dReal thickness,
int bWrap)
Loads heightfield sample data into the HeightfieldData structure. Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data. These calls all take the same parameters as listed below; the only difference is the data type pointed to by pHeightData.
dHeightfieldDataID is the heightfield data storage object, from dGeomHeightfieldDataCreate()
pHeightData is a pointer to the height data
bCopyHeightData specifies whether the height data should be copied to a local store. If zero, the data is accessed by reference and so must persist throughout the lifetime of the heightfield
width is the world space heightfield dimension on the geom's local X axis
depth is the world space heightfield dimension on the geom's local Z axis
widthSamples specifies the number of vertices to sample along the width of the heightfield. Each vertex has a corresponding height value which forms the overall shape. Naturally this value must be at least two or more
nDepthSamples specifies the number of vertices to sample along the z-axis
scale is the vertical sample height multiplier, a uniform scale applied to all raw height data
offset is the vertical sample offset, applied to the scaled height data
thickness thickness of world space AABB padding added to lowest point of AABB (prevents objects falling through very thin heightfields)
bWrap sample wrapping mode (0=finite, 1=infinite). If non-zero the heightfield will infinitely tile in both directions along the local X and Z axes. If zero the heightfield is bounded from zero to width in the local X axis, and zero to depth in the local Z axis
dGeomHeightfieldDataBuildCallback
void dGeomHeightfieldDataBuildCallback(dHeightfieldDataID d,
void *pUserData,
dHeightfieldGetHeight *pCallback,
dReal width,
dReal depth,
int widthSamples,
int depthSamples,
dReal scale,
dReal offset,
dReal thickness,
int bWrap)
Configures a dHeightfieldDataID to use a callback to retrieve height data. Before a dHeightfieldDataID can be used by a geom it must be configured to specify the format of the height data.
This call specifies that the heightfield data is computed by the user and it should use the given callback when determining the height of a given element of its shape. The callback function is called while the simulation runs, and returns the value of the heightmap ("y" value) at a given (x,z) position.
dHeightfieldDataID is the heightfield data storage object
pUserData is a pointer for arbitrary user-defined data to pass to the callback
pCallback is the callback function, of type dReal (void *userdata, int x, int z)
width specifies the total 'width' of the heightfield along the geom's local x axis
depth specifies the total 'depth' of the heightfield along the geom's local z axis
scale is the vertical sample height multiplier, a uniform scale applied to all raw height data
offset is the vertical sample offset, applied to the scaled height data
thickness thickness of world space AABB padding added to lowest point of AABB (prevents objects falling through very thin heightfields)
bWrap sample wrapping mode (0=finite, 1=infinite). If non-zero the heightfield will infinitely tile in both directions along the local X and Z axes. If zero the heightfield is bounded from zero to width in the local X axis, and zero to depth in the local Z axis
dGeomHeightfieldDataSetBounds
void dGeomHeightfieldDataSetBounds(dHeightfieldDataID d, dReal min_height, dReal max_height)
These comments were from before I updated this section from the v0.9 header file. I don't know if these still apply or not, but they yield information which is not in the header comments, so may be useful.
Sets the minimum and maximum height sample bounds in sample space.
dHeightfield does not automatically detect the sample data minimum and maximum height bounds, this must be done manually (for added flexibility and allows the user to control the process).
The default vertical sample bounds are infinite, so when the sample bounds are known, call this function for improved performance.
Below comments were taken from the v0.9 header file.
This call allows you to set explicit min / max values after initial creation typically for callback heightfields which default to +/- infinity, or those whose data has changed. This must be set prior to binding with a geom, as the the AABB is not recomputed after its first generation.
The minimum and maximum values are used to compute the AABB for the heightfield which is used for early rejection of collisions. A close fit will yield a more efficient collision check.
min_height is the new minimum height value. Scale, offset and thickness is then applied.
max_height is the new maximum height value. Scale, offset and thickness is then applied.
dGeomHeightfieldDataDestroy
void dGeomHeightfieldDataDestroy(dHeightfieldDataID d)
Destroys height field data structure.
Heightfield Geom
dCreateHeightfield
dGeomID dCreateHeightfield(dSpaceID space, dHeightfieldDataID data, int bPlaceable)
Uses the information in the given dHeightfieldDataID to construct a geom representing a heightfield in a collision space.
dSpaceID is the collision space to add the geom to
dHeightfieldDataID is the heightfield data container ID
bPlaceable defines whether this geom can be transformed in the world using the usual functions such as dGeomSetPosition and dGeomSetRotation. If the geom is not set as placeable, then it uses a fixed orientation where the global Y axis represents the dynamic 'height' of the heightfield.
dGeomHeightfieldSetHeightfieldData
void dGeomHeightfieldSetHeightfieldData(dGeomID g, dHeightfieldDataID Data)
Sets the heightfield data to be used on this geom.
dGeomHeightfieldGetHeightfieldData
dHeightfieldDataID dGeomHeightfieldGetHeightfieldData(dGeomID g)
Returns the heightfield data container ID.
dGeomHeightfieldPointDepth
dReal dGeomHeightfieldPointDepth(dGeomID g, dReal x, dReal y, dReal z)
[todo]
