Moving to Release 5

Description

Issues when moving from major release 4 to major release 5.

Syntactical changes

A number of interface methods have been removed or renamed.
These changes will simply cause your application to fail to compile with release 5 until the calling code has been updated accordingly.
The required changes to the calling code are generally straightforward, and are detailed below.

Const specifiers have been added for a load of methods, to provide a consistent constness paradigm at the API level.

Changed semantics for failed pathfinding requests

Failed pathfinding requests now return a null pointer instead of an iPath object with size 0.

Care must be taken, therefore, when moving to release 5, to audit all pathfinding calls to ensure that checks are in place for the null pointer return value, and that code does not subsequently call against a null iPath pointer.

The following logic could have been used before this change:

iPath* path = mesh->findShortestPath(shape, 0, start, goal);
if(path->size() > 1)
{
    //.. a path has been found, with non-zero length
}
        

When called against release 5 this code will crash in the case of failure to find a path from start to goal, and should be replaced with the following:

iPath* path = mesh->findShortestPath(shape, 0, start, goal);
if(path && path->size() > 1)
{
    //.. a path has been found, with non-zero length
}
        

Situations in which a null iPath pointer can be used safely

Note that it is safe to call advance along path methods on iAgent with null paths. In this case the methods will return with no effect.

It is also safe to call iMesh::savePath() with a null pointer for the path parameter.
In this case, however, be aware that no data will be written to the output stream, so make sure that any file handling code handles this case gracefully.
(iMesh::loadPath() will then return a null pointer when passed the empty buffer.)

Why was this changed?

This change was made to simplify representation of invalid paths in application side agent representations, and to enable the same value to be used on initialisation of these agent representations and after pathfinding failure.
The change also avoids any cost associated with setting up a path object in the case of pathfinding failure.

Troubleshooting compile errors when moving to release 5

Some common compile errors follow, together with explanations and action to take:

error C2259: 'cErrorHandler' : cannot instantiate abstract class
This is because handle() virtual method now takes char *const* instead of const char**. Simply update the method signature in your error handler concrete class correspondingly.

error C2660: 'iPathEngine::loadMeshFromBuffer' : function does not take 3 arguments
Add an additional argument for the options, set to zero to specify no options, i.e. that default behaviour is required.

error C2039: 'generatePreprocessFor' : is not a member of 'iMesh'
Use generateCollisionPreprocessFor and generatePathfindPreprocessFor instead.
Unlike generatePreprocessFor, however, these should only be called if preprocess is not already present, so you may need to use something like the following:

if(!mesh->shapeCanCollide(shape))
{
	mesh->generateCollisionPreprocessFor(shape, 0);
}
if(!mesh->shapeCanPathfind(shape))
{
	mesh->generatePathfindPreprocessFor(shape, 0);
}

error C2039: 'findClosestUnobstructedPoint' : is not a member of 'iMesh'
error C2039: 'findClosestUnobstructedPoint' : is not a member of 'iAgent'
These have been renamed to 'findClosestUnobstructedPosition'.

error C2039: 'testCollisionAgainstShape' : is not a member of 'iAgent'
This has been renamed to 'testCollisionDirectlyAgainstPlacedShape'.

A detailed list of interface breaking changes:

Throughout the API

Attribute sets previously passed as 'const char**' are now passed as 'char *const*'.

iPathEngine

getReleaseNumber() renamed to getReleaseNumbers(), and semantics changed
loadMeshFromBuffer_WithOptions() removed, loadMeshFromBuffer() now takes an options argument
flushCachedMemory() and flushPreprocess() removed

iShape

getVertices() has been renamed to size()
getVertex() has been renamed to vertex()

iMesh

getTerrainLayer() removed, use getSectionID()
positionOnTerrain() removed, use positionInSection()
generateRandomPositionOnTerrain() removed, use generateRandomPositionInSection()
getNumberOfTerrainLayers() removed, use getNumberOfSections()
getGroundNormal() replaced by get3DFaceNormal(), taking a 3d face index
get3DFaceAttribute() added taking a 3d face index and attribute index
get3DFaceUserData() removed, use get3DFaceAttriute()
storeFixedObstacle, retrieveFixedObstacle, getNumberOfFixedObstacles, retrieveFixedObstacleByIndex renamed to replace "FixedObstacle" with "NamedObstacle"
storeAnchorWithOrientation and retrieveAnchorWithOrientation renamed to storeAnchor and retrieveAnchor, replacing the existing methods with those names
convertLegacyPosition removed
burnContextInToBaseCircuits renamed to burnContextObstaclesIntoMesh
generatePreprocessFor removed, use generateCollisionPreprocessFor and generatePathfindPreprocessFor instead
(but note that these cannot be called when preprocess is already present)
releasePreprocessFor renamed to releaseAllPreprocessFor
findClosestUnobstructedPoint renamed to findClosestUnobstructedPosition

iAgent

testCollisionAgainstShape renamed to testCollisionDirectlyAgainstPlacedShape
isMoveable removed
findClosestUnobstructedPoint renamed to findClosestUnobstructedPosition

iCollisionContext

size() and empty() removed
(to avoid confusion between directly added agents and agents in added obstacle sets)

iPath

getNumberOfPositions() removed, use size()
getPositionInPath() removed, use position()

iTestBed

getReleaseNumber() has been removed, use iPathEngine::getReleaseNumbers()
drawBaseCircuits() has been renamed to drawBurntInObstacles