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', and is essentially just a triangulation of the parts of the terrain not cut by building external shapes.

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 are marked with the 'sectionID' face attribute.
(See Face Attributes.)

The most common setup is to use just one single terrain layer, marked by a sectionID face attribute value of zero, but meshes with multiple terrain layers are also supported.

Creating and registering terrain callbacks

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

Callbacks can be registered after a mesh is loaded, and before any preprocess is generated, using iMesh::setTerrainCallBack(), with the index passed in to this method specifying the sectionID for which height queries should be directed through the registered callback.

Height queries for ground with sectionID values not having registered callbacks are treated in the same way as height queries for ground without any sectionID assigned, i.e. these are processed based on the actual ground mesh geometry present.

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.