Moving to Release 5.34

Description

Moving from release 5.33 to release 5.34.

There is some interface refactoring for release 5.34, and most projects will need some minor edits in order to compile with the new release headers.

Reaons for changes

The purpose of the interface changes is to improve interface consistency, avoid some 'unsafe' parameter passing involving pointers to buffers, and to support the interface mappings to Microsoft Common Language Runtime and Java Native Interface that have been added in 5.34.

Passing arrays in to the SDK

Arrays of values are passed in to the SDK through buffer pointer and buffer size pairs, to avoid the need to pass something like an STL vector directly. This hasn't changed, but the parameter arrangements for this kind of array passing has been standardised.

In all cases, arrays are now passed by a buffer pointer followed directly by an unsigned buffer element count.

In most cases this doesn't change the API, or just changes an existing buffer element count parameter from signed to unsigned, but some important exceptions are the methods related to shape construction, such as iMesh::shapeIsValid(), iMesh::newShape(), and iMesh::placeLargeStaticObstacle().

These methods previously passed the shape coordinate array as *number of shape points* followed by *pointer to coordinate data*, as follows:

int32_t array[]=
{
    8,20,
    20,8,
    20,-8,
    8,-20,
    -8,-20,
    -20,-8,
    -20,8,
    -8,20,
};
agentShape = pathengine->newShape(sizeof(array) / sizeof(*array) / 2, array);

These method calls will therefore need to be modified, as follows:

int32_t array[]=
{
    8,20,
    20,8,
    20,-8,
    8,-20,
    -8,-20,
    -20,-8,
    -20,8,
    -8,20,
};
agentShape = pathengine->newShape(array, sizeof(array) / sizeof(*array));

Passing 3D points

Some methods previously required passing 3D points as pointers to a buffer of point coordinates, with the implicit requirement that the pointer points to 3 valid elements. In each case, this has been replaced by 3 separate explicit x,y and z parameters.

So, code that previously we set up as follows:

int32_t coords[3];
coords[0] = p2D.x();
coords[1] = p2D.y();
coords[2] = 1500000;
p = mesh->positionFor3DPoint(coords);

can be replaced with something like the following (in the general case):

int32_t coords[3];
coords[0] = p2D.x();
coords[1] = p2D.y();
coords[2] = 1500000;
p = mesh->positionFor3DPoint(coords[0], coords[1], coords[2]);

or the individual coordinate values passed directly, as follows:

p = mesh->positionFor3DPoint(p2D.x(), p2D.y(), 1500000);

Colliding line coordinates

There is a similar change for the iCollisionInfo::getCollidingLine() method, which now provides four explicit coordinate out arguments instead of writing into an application supplied buffer.

So, code like the following:

iCollisionInfo* collisionInfo = agent->firstCollisionTo(context, target.x, target.y, target.cell);
int trys = 0;
while(collisionInfo && trys < 2)
{
    int32_t coords[4];
    collisionInfo->getCollidingLine(coords);
    //.... code that uses the coordinate data
}

will need to be changed to the following:

iCollisionInfo* collisionInfo = agent->firstCollisionTo(context, target.x, target.y, target.cell);
int trys = 0;
while(collisionInfo && trys < 2)
{
    int32_t coords[4];
    collisionInfo->getCollidingLine(coords[0], coords[1], coords[2], coords[3]);
    //.... code that uses the coordinate data
}

Some floating point method versions removed

Floating point versions of position from 3D point query methods have been removed in favour of the integer versions. (The floating point versions were previously just casting to integers and forwarding on to the integer versions, anyway.) Existing code can be adapted by casting explicitly from float to integer before calling in to these SDK methods.

Callbacks parameter types

Callback parameter type passing has been made more consistent.

Callbacks that are *required*, and only referenced for the duration of a single API method call are now always passed as references to callback objects, whereas callbacks that are option (with a zero pointer accepted), or that are retained after the API method call exits, are always passed as pointers to callback objects.

This means that some callback parameters may now need to be changed from pointer to reference type, or vice versa.

A noteable example is for output stream callbacks, when saving data, which were previously passed as a pointer but now passed as a reference. So code like the following:

p = std::ostringstream fileName;
fileName << "federationTile" << tileIndex << ".tok";
cFileOutputStream fos(fileName.str().c_str());
tileMesh->saveGround("tok", true, &fos);

Will need to be changed as follows:

p = std::ostringstream fileName;
fileName << "federationTile" << tileIndex << ".tok";
cFileOutputStream fos(fileName.str().c_str());
tileMesh->saveGround("tok", true, fos); // no dereference here

Array out parameters

Some API methods need to return arrays of elements. Previously this was handled by passing in a pointer to a buffer that must be large enough for the resulting array of data, but this is now handled through 'array receiver' callback objects.

See Passing Arrays for more details about this mechanism, but when updating existing source code that calls these methods what you basically need to do is to replace something like:

int32_t numberOfTileMeshes = federation->getNumberOfGroundTilesOverlapped(tileIndex, &tiling);
std::vector<int32_t> tileMeshIndices(numberOfTileMeshes);
federation->getGroundTilesOverlapped(tileIndex, &tiling, &tileMeshIndices[0], numberOfTileMeshes);

with:

cVectorReceiver<int32_t> tileMeshIndicesReceiver;
federation->getGroundTilesOverlapped(tileIndex, &tiling, tileMeshIndicesReceiver);
const std::vector<int32_t>& tileMeshIndices = tileMeshIndicesReceiver.vector; // or just use the receiver vector directly
int32_t numberOfTileMeshes = tileMeshIndices.size();

Path construction

The mesh::constructPath() method has been changed to use the standard array passing mechanism described above, so code like the following:

iPath* copiedPath = mesh->constructPath(visualisePath->getPositionArray(), visualisePath->getConnectionIndexArray(), visualisePath->size());

needs to be changed as follows:

iPath* copiedPath = mesh->constructPath(positionArray,  visualisePath->size(), connectionIndexArray, connectionIndexArray ? visualisePath->size() - 1 : 0);

Agent user data

Agent user data is now stored as a int64_t (signed 64 bit integer), instead of a void pointer. If you were previously casting an integer to a void pointer these casts can now be removed, but if you need to store a pointer, however, this pointer will now need to be cast to int64_t.

Error handler action values

Error handler actions are now named constants instead of class enumeration values. Enumeration values such as CONTINUE_IGNORE_IN_FUTURE should be replaced with PE_ErrorHandler_ContinueAndIgnoreInFuture, ABORT with PE_ErrorHandler_Abort, and so on.