cPosition

The cPosition class definition is provided (in SDKRoot/code/externalAPI/i_pathengine.h) as follows:

class cPosition
{
public:
    cPosition() : cell(-1) {}
    cPosition(int32_t x, int32_t y, int32_t cell) : x(x), y(y), cell(cell) {}
    int32_t x, y, cell;
    bool operator==(const cPosition& rhs) const
    {
        if(cell == -1)
            return cell == rhs.cell;
        return cell == rhs.cell && x == rhs.x && y == rhs.y;
    }
    bool operator!=(const cPosition& rhs) const
    {
        return !((*this) == rhs);
    }
};
        

This class is provided as a POD (plain old data) class so that the client application can avoid the overhead of virtual functions and memory management when working with objects of this class.

It is intended for this definition to remain unchanged as PathEngine evolves.

It is also intended that the binary value of a cPosition object will remain the same for a given position on a given mesh, as far as possible across different versions of pathengine.
This means that cPosition objects can effectively be made persistent directly by the client application, by simply streaming the binary value of the class data members to persistent storage.

When making cPosition objects persistent in this way it's important to ensure that you save a 'mapping to 2D' out with each ground mesh. Otherwise, changes to the code that generates this mapping can invalidate your persistent positions.

Data members

The 'x' and 'y' members are simply the X and Y coordinates of the position.
(See PathEngine Coordinates)

The 'cell' member specify the cell in a mesh that contains that position.
This values disambiguates between overlapping geometry at a given horizontal position.
But note that this relates to an internal 2d mesh derived from the original 3d mesh, so the cell index does not correspond to polygon indices in that original mesh.

A cell index of -1 indicates an 'explicitly invalid' position.
This is sometimes used by functions in the interface that return a position to indicate failure.
(For example iMesh::positionFor3DPoint().)

Note that cPositions cannot be constructed directly from x, and y coordinates by the client application, because the cell member depends on PathEngine's internal positioning of a ground mesh.

Interop

The equivalent class in the Microsoft CLR interface (for C Sharp or Visual Basic) is PathEngine.Position.