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.

Creating and registering terrain callbacks

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

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.