Working with Terrain

If you're working with terrain surfaces you'll usually already have some kind of height field data structure that can efficiently provide information about the height at a given point on your terrain.
In this case it is wasteful for PathEngine to repeat this representation internally, particularly since the memory footprint for terrain height fields can be quite significant.

Terrain callbacks

The terrain callback feature enables you to strip out height details from the terrain parts of your ground mesh and provide a callback object to enable PathEngine to query your application-specific terrain representation instead.

The 'Thainesford' mesh provided with the SDK provides an example of a mesh representing a ground surface that connects terrain areas with the internal floors of buildings.
Notice that the terrain part of this mesh doesn't contain any 'internal vertices', but is simply a triangulation of the points at which the buildings connect to the terrain.

Terrain layers

Terrain surfaces are assumed to be two dimensional surfaces that can be expressed in terms of a single height value for a given pair of x and y coordinates.
PathEngine supports multiple 'terrain layers', for cases where multiple terrain surfaces need to coexist at the same x,y position.

Marking terrain areas in a ground mesh

Terrain areas should be marked with the 'sectionID' face attribute.
(See Face Attributes.)

Creating and registering terrain callbacks

Terrain callbacks derive from Interface iTerrainCallBack, and must support this (very straightforward) interface.

Callbacks must be registered after a mesh is loaded, and before any preprocess is generated.
Use iMesh::setTerrainCallBack() to register callbacks.
The index passed in to this method corresponds with the 'sectionID' attribute used to mark terrain parts of the mesh.
So the callback registered for terrain layer 0 will be called by PathEngine to resolve heights for parts of the mesh that have been assigned a 'sectionID' of zero and so on.

If a callback is not assigned to a sectionID that is present in a mesh then the height of the polygons will be used as if there was no terrain layer assigned.

Querying terrain layer at a position on the ground

iMesh::getSectionID() can be used to obtain the terrain layer (sectionID) for a given position if required.

Obtaining points on a terrain

iMesh::positionInSection(), and iMesh::generateRandomPositionInSection() can be used to obtain positions on a specific terrain layer (or with a specific sectionID).

Terrain and the testbed

There is currently no method provided for rendering terrain under the testbed. The terrain mechanism is set up specifically for client-side representation of the terrain.
When using the testbed with a mesh that includes terrain areas, just don't register any terrain callbacks. You will then be able to examine paths, expanded areas, and so on on the surface of the ground mesh as usual.