Recast Navigation
Navigation-mesh Toolset for Games
dtNavMesh Class Reference

A navigation mesh based on tiles of convex polygons. More...

#include <DetourNavMesh.h>

Public Member Functions

 dtNavMesh ()
 
 ~dtNavMesh ()
 
Initialization and Tile Management
dtStatus init (const dtNavMeshParams *params)
 Initializes the navigation mesh for tiled use. More...
 
dtStatus init (unsigned char *data, const int dataSize, const int flags)
 Initializes the navigation mesh for single tile use. More...
 
const dtNavMeshParamsgetParams () const
 The navigation mesh initialization params. More...
 
dtStatus addTile (unsigned char *data, int dataSize, int flags, dtTileRef lastRef, dtTileRef *result)
 Adds a tile to the navigation mesh. More...
 
dtStatus removeTile (dtTileRef ref, unsigned char **data, int *dataSize)
 Removes the specified tile from the navigation mesh. More...
 
Query Functions
void calcTileLoc (const float *pos, int *tx, int *ty) const
 Calculates the tile grid location for the specified world position. More...
 
const dtMeshTilegetTileAt (const int x, const int y, const int layer) const
 Gets the tile at the specified grid location. More...
 
int getTilesAt (const int x, const int y, dtMeshTile const **tiles, const int maxTiles) const
 Gets all tiles at the specified grid location. More...
 
dtTileRef getTileRefAt (int x, int y, int layer) const
 Gets the tile reference for the tile at specified grid location. More...
 
dtTileRef getTileRef (const dtMeshTile *tile) const
 Gets the tile reference for the specified tile. More...
 
const dtMeshTilegetTileByRef (dtTileRef ref) const
 Gets the tile for the specified tile reference. More...
 
int getMaxTiles () const
 The maximum number of tiles supported by the navigation mesh. More...
 
const dtMeshTilegetTile (int i) const
 Gets the tile at the specified index. More...
 
dtStatus getTileAndPolyByRef (const dtPolyRef ref, const dtMeshTile **tile, const dtPoly **poly) const
 Gets the tile and polygon for the specified polygon reference. More...
 
void getTileAndPolyByRefUnsafe (const dtPolyRef ref, const dtMeshTile **tile, const dtPoly **poly) const
 Returns the tile and polygon for the specified polygon reference. More...
 
bool isValidPolyRef (dtPolyRef ref) const
 Checks the validity of a polygon reference. More...
 
dtPolyRef getPolyRefBase (const dtMeshTile *tile) const
 Gets the polygon reference for the tile's base polygon. More...
 
dtStatus getOffMeshConnectionPolyEndPoints (dtPolyRef prevRef, dtPolyRef polyRef, float *startPos, float *endPos) const
 Gets the endpoints for an off-mesh connection, ordered by "direction of travel". More...
 
const dtOffMeshConnectiongetOffMeshConnectionByRef (dtPolyRef ref) const
 Gets the specified off-mesh connection. More...
 
State Management

These functions do not effect dtTileRef or dtPolyRef's.

dtStatus setPolyFlags (dtPolyRef ref, unsigned short flags)
 Sets the user defined flags for the specified polygon. More...
 
dtStatus getPolyFlags (dtPolyRef ref, unsigned short *resultFlags) const
 Gets the user defined flags for the specified polygon. More...
 
dtStatus setPolyArea (dtPolyRef ref, unsigned char area)
 Sets the user defined area for the specified polygon. More...
 
dtStatus getPolyArea (dtPolyRef ref, unsigned char *resultArea) const
 Gets the user defined area for the specified polygon. More...
 
int getTileStateSize (const dtMeshTile *tile) const
 Gets the size of the buffer required by storeTileState to store the specified tile's state. More...
 
dtStatus storeTileState (const dtMeshTile *tile, unsigned char *data, const int maxDataSize) const
 Stores the non-structural state of the tile in the specified buffer. More...
 
dtStatus restoreTileState (dtMeshTile *tile, const unsigned char *data, const int maxDataSize)
 Restores the state of the tile. More...
 
Encoding and Decoding

These functions are generally meant for internal use only.

dtPolyRef encodePolyId (unsigned int salt, unsigned int it, unsigned int ip) const
 Derives a standard polygon reference. More...
 
void decodePolyId (dtPolyRef ref, unsigned int &salt, unsigned int &it, unsigned int &ip) const
 Decodes a standard polygon reference. More...
 
unsigned int decodePolyIdSalt (dtPolyRef ref) const
 Extracts a tile's salt value from the specified polygon reference. More...
 
unsigned int decodePolyIdTile (dtPolyRef ref) const
 Extracts the tile's index from the specified polygon reference. More...
 
unsigned int decodePolyIdPoly (dtPolyRef ref) const
 Extracts the polygon's index (within its tile) from the specified polygon reference. More...
 

Friends

class dtNavMeshQuery
 

Description

A navigation mesh based on tiles of convex polygons.

The navigation mesh consists of one or more tiles defining three primary types of structural data:

A polygon mesh which defines most of the navigation graph. (See rcPolyMesh for its structure.) A detail mesh used for determining surface height on the polygon mesh. (See rcPolyMeshDetail for its structure.) Off-mesh connections, which define custom point-to-point edges within the navigation graph.

The general build process is as follows:

  1. Create rcPolyMesh and rcPolyMeshDetail data using the Recast build pipeline.
  2. Optionally, create off-mesh connection data.
  3. Combine the source data into a dtNavMeshCreateParams structure.
  4. Create a tile data array using dtCreateNavMeshData().
  5. Allocate at dtNavMesh object and initialize it. (For single tile navigation meshes, the tile data is loaded during this step.)
  6. For multi-tile navigation meshes, load the tile data using dtNavMesh::addTile().

Notes:

  • This class is usually used in conjunction with the dtNavMeshQuery class for pathfinding.
  • Technically, all navigation meshes are tiled. A 'solo' mesh is simply a navigation mesh initialized to have only a single tile.
  • This class does not implement any asynchronous methods. So the dtStatus result of all methods will always contain either a success or failure flag.
See also
dtNavMeshQuery, dtCreateNavMeshData, dtNavMeshCreateParams, dtAllocNavMesh, dtFreeNavMesh

Constructor & Destructor Documentation

◆ dtNavMesh()

dtNavMesh::dtNavMesh ( )

◆ ~dtNavMesh()

dtNavMesh::~dtNavMesh ( )

Member Function Documentation

◆ addTile()

dtStatus dtNavMesh::addTile ( unsigned char *  data,
int  dataSize,
int  flags,
dtTileRef  lastRef,
dtTileRef result 
)

Adds a tile to the navigation mesh.

Parameters
[in]dataData for the new tile mesh. (See: dtCreateNavMeshData)
[in]dataSizeData size of the new tile mesh.
[in]flagsTile flags. (See: dtTileFlags)
[in]lastRefThe desired reference for the tile. (When reloading a tile.) [opt] [Default: 0]
[out]resultThe tile reference. (If the tile was succesfully added.) [opt]
Returns
The status flags for the operation.

The add operation will fail if the data is in the wrong format, the allocated tile space is full, or there is a tile already at the specified reference.

The lastRef parameter is used to restore a tile with the same tile reference it had previously used. In this case the dtPolyRef's for the tile will be restored to the same values they were before the tile was removed.

The nav mesh assumes exclusive access to the data passed and will make changes to the dynamic portion of the data. For that reason the data should not be reused in other nav meshes until the tile has been successfully removed from this nav mesh.

See also
dtCreateNavMeshData, removeTile

◆ calcTileLoc()

void dtNavMesh::calcTileLoc ( const float *  pos,
int *  tx,
int *  ty 
) const

Calculates the tile grid location for the specified world position.

Parameters
[in]posThe world position for the query. [(x, y, z)]
[out]txThe tile's x-location. (x, y)
[out]tyThe tile's y-location. (x, y)

◆ decodePolyId()

void dtNavMesh::decodePolyId ( dtPolyRef  ref,
unsigned int &  salt,
unsigned int &  it,
unsigned int &  ip 
) const
inline

Decodes a standard polygon reference.

Note
This function is generally meant for internal use only.
Parameters
[in]refThe polygon reference to decode.
[out]saltThe tile's salt value.
[out]itThe index of the tile.
[out]ipThe index of the polygon within the tile.
See also
encodePolyId

◆ decodePolyIdPoly()

unsigned int dtNavMesh::decodePolyIdPoly ( dtPolyRef  ref) const
inline

Extracts the polygon's index (within its tile) from the specified polygon reference.

Note
This function is generally meant for internal use only.
Parameters
[in]refThe polygon reference.
See also
encodePolyId

◆ decodePolyIdSalt()

unsigned int dtNavMesh::decodePolyIdSalt ( dtPolyRef  ref) const
inline

Extracts a tile's salt value from the specified polygon reference.

Note
This function is generally meant for internal use only.
Parameters
[in]refThe polygon reference.
See also
encodePolyId

◆ decodePolyIdTile()

unsigned int dtNavMesh::decodePolyIdTile ( dtPolyRef  ref) const
inline

Extracts the tile's index from the specified polygon reference.

Note
This function is generally meant for internal use only.
Parameters
[in]refThe polygon reference.
See also
encodePolyId

◆ encodePolyId()

dtPolyRef dtNavMesh::encodePolyId ( unsigned int  salt,
unsigned int  it,
unsigned int  ip 
) const
inline

Derives a standard polygon reference.

Note
This function is generally meant for internal use only.
Parameters
[in]saltThe tile's salt value.
[in]itThe index of the tile.
[in]ipThe index of the polygon within the tile.

◆ getMaxTiles()

int dtNavMesh::getMaxTiles ( ) const

The maximum number of tiles supported by the navigation mesh.

Returns
The maximum number of tiles supported by the navigation mesh.

◆ getOffMeshConnectionByRef()

const dtOffMeshConnection * dtNavMesh::getOffMeshConnectionByRef ( dtPolyRef  ref) const

Gets the specified off-mesh connection.

Parameters
[in]refThe polygon reference of the off-mesh connection.
Returns
The specified off-mesh connection, or null if the polygon reference is not valid.

◆ getOffMeshConnectionPolyEndPoints()

dtStatus dtNavMesh::getOffMeshConnectionPolyEndPoints ( dtPolyRef  prevRef,
dtPolyRef  polyRef,
float *  startPos,
float *  endPos 
) const

Gets the endpoints for an off-mesh connection, ordered by "direction of travel".

Parameters
[in]prevRefThe reference of the polygon before the connection.
[in]polyRefThe reference of the off-mesh connection polygon.
[out]startPosThe start position of the off-mesh connection. [(x, y, z)]
[out]endPosThe end position of the off-mesh connection. [(x, y, z)]
Returns
The status flags for the operation.

Off-mesh connections are stored in the navigation mesh as special 2-vertex polygons with a single edge. At least one of the vertices is expected to be inside a normal polygon. So an off-mesh connection is "entered" from a normal polygon at one of its endpoints. This is the polygon identified by the prevRef parameter.

◆ getParams()

const dtNavMeshParams * dtNavMesh::getParams ( ) const

The navigation mesh initialization params.

Note
The parameters are created automatically when the single tile initialization is performed.

◆ getPolyArea()

dtStatus dtNavMesh::getPolyArea ( dtPolyRef  ref,
unsigned char *  resultArea 
) const

Gets the user defined area for the specified polygon.

Parameters
[in]refThe polygon reference.
[out]resultAreaThe area id for the polygon.
Returns
The status flags for the operation.

◆ getPolyFlags()

dtStatus dtNavMesh::getPolyFlags ( dtPolyRef  ref,
unsigned short *  resultFlags 
) const

Gets the user defined flags for the specified polygon.

Parameters
[in]refThe polygon reference.
[out]resultFlagsThe polygon flags.
Returns
The status flags for the operation.

◆ getPolyRefBase()

dtPolyRef dtNavMesh::getPolyRefBase ( const dtMeshTile tile) const

Gets the polygon reference for the tile's base polygon.

Parameters
[in]tileThe tile.
Returns
The polygon reference for the base polygon in the specified tile.

Example use case:

const dtPolyRef base = navmesh->getPolyRefBase(tile);
for (int i = 0; i < tile->header->polyCount; ++i)
{
const dtPoly* p = &tile->polys[i];
const dtPolyRef ref = base | (dtPolyRef)i;
// Use the reference to access the polygon data.
}
unsigned int dtPolyRef
A handle to a polygon within a navigation mesh tile.
Definition: DetourNavMesh.h:48
Defines a polygon within a dtMeshTile object.
Definition: DetourNavMesh.h:156

◆ getTile()

const dtMeshTile * dtNavMesh::getTile ( int  i) const

Gets the tile at the specified index.

Parameters
[in]iThe tile index. [Limit: 0 >= index < getMaxTiles()]
Returns
The tile at the specified index.

◆ getTileAndPolyByRef()

dtStatus dtNavMesh::getTileAndPolyByRef ( const dtPolyRef  ref,
const dtMeshTile **  tile,
const dtPoly **  poly 
) const

Gets the tile and polygon for the specified polygon reference.

Parameters
[in]refThe reference for the a polygon.
[out]tileThe tile containing the polygon.
[out]polyThe polygon.
Returns
The status flags for the operation.

◆ getTileAndPolyByRefUnsafe()

void dtNavMesh::getTileAndPolyByRefUnsafe ( const dtPolyRef  ref,
const dtMeshTile **  tile,
const dtPoly **  poly 
) const

Returns the tile and polygon for the specified polygon reference.

Parameters
[in]refA known valid reference for a polygon.
[out]tileThe tile containing the polygon.
[out]polyThe polygon.
Warning
Only use this function if it is known that the provided polygon reference is valid. This function is faster than getTileAndPolyByRef, but it does not validate the reference.

◆ getTileAt()

const dtMeshTile * dtNavMesh::getTileAt ( const int  x,
const int  y,
const int  layer 
) const

Gets the tile at the specified grid location.

Parameters
[in]xThe tile's x-location. (x, y, layer)
[in]yThe tile's y-location. (x, y, layer)
[in]layerThe tile's layer. (x, y, layer)
Returns
The tile, or null if the tile does not exist.

◆ getTileByRef()

const dtMeshTile * dtNavMesh::getTileByRef ( dtTileRef  ref) const

Gets the tile for the specified tile reference.

Parameters
[in]refThe tile reference of the tile to retrieve.
Returns
The tile for the specified reference, or null if the reference is invalid.

◆ getTileRef()

dtTileRef dtNavMesh::getTileRef ( const dtMeshTile tile) const

Gets the tile reference for the specified tile.

Parameters
[in]tileThe tile.
Returns
The tile reference of the tile.

◆ getTileRefAt()

dtTileRef dtNavMesh::getTileRefAt ( int  x,
int  y,
int  layer 
) const

Gets the tile reference for the tile at specified grid location.

Parameters
[in]xThe tile's x-location. (x, y, layer)
[in]yThe tile's y-location. (x, y, layer)
[in]layerThe tile's layer. (x, y, layer)
Returns
The tile reference of the tile, or 0 if there is none.

◆ getTilesAt()

int dtNavMesh::getTilesAt ( const int  x,
const int  y,
dtMeshTile const **  tiles,
const int  maxTiles 
) const

Gets all tiles at the specified grid location.

(All layers.)

Parameters
[in]xThe tile's x-location. (x, y)
[in]yThe tile's y-location. (x, y)
[out]tilesA pointer to an array of tiles that will hold the result.
[in]maxTilesThe maximum tiles the tiles parameter can hold.
Returns
The number of tiles returned in the tiles array.

This function will not fail if the tiles array is too small to hold the entire result set. It will simply fill the array to capacity.

◆ getTileStateSize()

int dtNavMesh::getTileStateSize ( const dtMeshTile tile) const

Gets the size of the buffer required by storeTileState to store the specified tile's state.

Parameters
[in]tileThe tile.
Returns
The size of the buffer required to store the state.
See also
storeTileState

◆ init() [1/2]

dtStatus dtNavMesh::init ( const dtNavMeshParams params)

Initializes the navigation mesh for tiled use.

Parameters
[in]paramsInitialization parameters.
Returns
The status flags for the operation.

◆ init() [2/2]

dtStatus dtNavMesh::init ( unsigned char *  data,
const int  dataSize,
const int  flags 
)

Initializes the navigation mesh for single tile use.

Parameters
[in]dataData of the new tile. (See: dtCreateNavMeshData)
[in]dataSizeThe data size of the new tile.
[in]flagsThe tile flags. (See: dtTileFlags)
Returns
The status flags for the operation.
See also
dtCreateNavMeshData

◆ isValidPolyRef()

bool dtNavMesh::isValidPolyRef ( dtPolyRef  ref) const

Checks the validity of a polygon reference.

Parameters
[in]refThe polygon reference to check.
Returns
True if polygon reference is valid for the navigation mesh.

◆ removeTile()

dtStatus dtNavMesh::removeTile ( dtTileRef  ref,
unsigned char **  data,
int *  dataSize 
)

Removes the specified tile from the navigation mesh.

Parameters
[in]refThe reference of the tile to remove.
[out]dataData associated with deleted tile.
[out]dataSizeSize of the data associated with deleted tile.
Returns
The status flags for the operation.

This function returns the data for the tile so that, if desired, it can be added back to the navigation mesh at a later point.

See also
addTile

◆ restoreTileState()

dtStatus dtNavMesh::restoreTileState ( dtMeshTile tile,
const unsigned char *  data,
const int  maxDataSize 
)

Restores the state of the tile.

Parameters
[in]tileThe tile.
[in]dataThe new state. (Obtained from storeTileState.)
[in]maxDataSizeThe size of the state within the data buffer.
Returns
The status flags for the operation.

Tile state includes non-structural data such as polygon flags, area ids, etc.

Note
This function does not impact the tile's dtTileRef and dtPolyRef's.
See also
storeTileState

◆ setPolyArea()

dtStatus dtNavMesh::setPolyArea ( dtPolyRef  ref,
unsigned char  area 
)

Sets the user defined area for the specified polygon.

Parameters
[in]refThe polygon reference.
[in]areaThe new area id for the polygon. [Limit: < DT_MAX_AREAS]
Returns
The status flags for the operation.

◆ setPolyFlags()

dtStatus dtNavMesh::setPolyFlags ( dtPolyRef  ref,
unsigned short  flags 
)

Sets the user defined flags for the specified polygon.

Parameters
[in]refThe polygon reference.
[in]flagsThe new flags for the polygon.
Returns
The status flags for the operation.

◆ storeTileState()

dtStatus dtNavMesh::storeTileState ( const dtMeshTile tile,
unsigned char *  data,
const int  maxDataSize 
) const

Stores the non-structural state of the tile in the specified buffer.

(Flags, area ids, etc.)

Parameters
[in]tileThe tile.
[out]dataThe buffer to store the tile's state in.
[in]maxDataSizeThe size of the data buffer. [Limit: >= getTileStateSize]
Returns
The status flags for the operation.

Tile state includes non-structural data such as polygon flags, area ids, etc.

Note
The state data is only valid until the tile reference changes.
See also
getTileStateSize, restoreTileState

Friends And Related Function Documentation

◆ dtNavMeshQuery

friend class dtNavMeshQuery
friend

The documentation for this class was generated from the following files: