Converting to and from PathEngine's Position Representation

Most of the API methods dealing with positions use the cPosition representation.
This explicitly specifies a position on the surface of a ground mesh in such a way as to enable operations relating to that position to be performed efficiently and unambiguously. (See Representing Positions on the Ground.)

Converting from world coordinates to cPosition

The following methods provide the general form of this functionality:

• iMesh::positionFor3DPoint()
• iMesh::positionNear3DPoint()

The positionFor3DPoint methods are provided for converting from 'anchor' style representations.
The positionNear3DPoint method is provided for converting clicked positions or other arbitrary 3d positions such as positions of objects that have been placed freely in 3d.

The following methods provide the same functionality, but enable the resulting point to be restricted to to a specified 'section' of the mesh:

• iMesh::positionInSectionFor3DPoint()
• iMesh::positionInSectionNear3DPoint()

The following method is then an extended version of the positionNear3DPoint() methods, providing similar functionality to positionInSectionNear3DPoint(), but with the posibility to obtain multiple points when there are multiple (locally unconnected) pieces of ground mesh near the query position:

• iMesh::resolvePositionsNear3DPoint()

The following method is also supplied to support the specific case of 'anchor' resolution at content time in cases where terrain stand-in geometry is being used and there is no access to the terrain detail at that point:

• iMesh::positionFor3DPoint_ExcludeTerrain()

Sections can be set up with the PE_FaceAttribute_SectionID face attribute.

Obtaining positions from horizontal coordinates only

When a particular sectionID value is known to contain only non-overlapping geometry (i.e. geometry with only one Z value per horizontal position), iMesh::positionInSection() can be used to obtain a position in that section from horizontal coordinates only.

Obtaining positions for obstacle placement

iMesh::positionInSectionInShape() is provided specifically to help find a position for obstacle placement in the case where the natural obstacle origin falls outside the mesh.
After a position has been found with this method the obstacle shape coordinates can be modified to enable the obstacle to be rooted at the found position.

Obtaining positions in unobstructed space

It is important to be aware that the methods for resolving positions from 3D space all return a position on the pathfinding ground surface, but with the possibility for this resolved position to then be obstructed (either by the mesh external boundary expansion, or by expanded placed obstacles).

In many cases, for example when you want a position to start pathfinding or for use as a pathfinding target, it is necessary to find a position that is both on the pathfinding ground surface and inside pathfinding unobstructed space.

(For more explanation of the difference between pathfinding ground, and unobstructed space, see The PathEngine Movement Model.)

In addition to position resolution on the ground mesh, PathEngine then also provides methods for finding nearby positions within pathfinding unobstructed space, for this purpose.
Please refer to Collision Queries for further details and API reference for this additional step, where this is required.

Generating random positions

The following methods enable positions on the ground to be generated randomly:

• iMesh::generateRandomPosition()
• iMesh::generateRandomPositionLocally()
• iMesh::generateRandomPositionInSection()

Traversal through the ground mesh

You can also build cPosition instances based on known start positions and linear traversals through the ground mesh.

iMesh::testLineCollision_XY() performs a collision test through the ground mesh to horizontal target coords, and then returns a cell for the target point (if there is no collision).

iMesh::getCellForEndOfLine() just performs a traversal to the target coords, ignoring collision, and also returns a cell for the target point (if the traversal does not exit the mesh).

In each case the cell value can then be used, in conjunction with the horizontal target coords, to manually construct a cPosition instance for the target position.

Converting back from cPosition to world coordinates

The following methods enable ground height to be determined at a given position on the ground:

• iMesh::heightAtPosition()
• iMesh::heightAtPositionF()
• iMesh::heightAtPositionWithPrecision()

Applying scaling and translation

It some cases it may be necessary to choose a scale for PathEngine coordinates that differs from the scale used for general world coordinates in game.
In this case scaling and translation can be applied at the same time as converting to and from PathEngines position representation.

When to convert between position representations

Because PathEngine's cPosition representation is unambiguous with respect to placement on overlapping layers of geometry, it is preferable to maintain agent positions in this representation and just generate a 3d position when this is needed for rendering, physical interactions, and so forth.

Performance considerations

A 'terrain callback' mechanism is provided for ground meshes that include terrain areas with a lot of height detail, enabling the heightAtPosition queries to be directed back to client supplied terrain callback functions for queried positions that fall on terrain areas.
These client supplied functions can take advantage of the specific nature of client side terrain representations such as faces being organised in a grip, and so on, to provide the best possible performance for mapping ground positions back to world coordinates.
(Refer to Working with Terrain for more details about this mechanism.)

In cases where ground meshes include a lot of height detail, and for some reason the terrain callback mechanism cannot be used, you can tell PathEngine to generate additional partitioning information to speed up the heightAtPosition queries.
To do this just set the 'partitionTranslationTo3D' option to 'true' when calling loadMeshFromBuffer_WithOptions().
For a mesh with lots of height detail this option was measured to reduce times for the heightAtPosition queries by 88%, at the cost of a 7% increase in memory use when loading the mesh.