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 dtNavMeshParams *	getParams () 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 dtMeshTile *	getTileAt (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...

void	queryTiles (const float mins[3], const float maxs[3], dtTileCallback callback, void *userdata) const

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 dtMeshTile *	getTileByRef (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 dtMeshTile *	getTile (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 dtOffMeshConnection *	getOffMeshConnectionByRef (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, navAreaMask areaMask)
	Sets the user defined flags for the specified polygon. More...

dtStatus	getPolyFlags (dtPolyRef ref, navAreaMask *resultFlags) const
	Gets the user defined flags for the specified polygon. More...

dtStatus	addPolyTeamCost (dtPolyRef ref, dtTeam team, float cost)

dtStatus	setPolyTeamCost (dtPolyRef ref, dtTeam team, float cost)

dtStatus	getPolyTeamCost (dtPolyRef ref, dtTeam team, float *costResult) const

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...

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:

Create rcPolyMesh and rcPolyMeshDetail data using the Recast build pipeline.
Optionally, create off-mesh connection data.
Combine the source data into a dtNavMeshCreateParams structure.
Create a tile data array using dtCreateNavMeshData().
Allocate at dtNavMesh object and initialize it. (For single tile navigation meshes, the tile data is loaded during this step.)
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 ( )

Member Function Documentation

dtStatus dtNavMesh::addPolyTeamCost	(	dtPolyRef	ref,
		dtTeam	team,
		float	cost
	)

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

Adds a tile to the navigation mesh.

Parameters

[in]	data	Data for the new tile mesh. (See: dtCreateNavMeshData)
[in]	dataSize	Data size of the new tile mesh.
[in]	flags	Tile flags. (See: dtTileFlags)
[in]	lastRef	The desired reference for the tile. (When reloading a tile.) [opt] [Default: 0]
[out]	result	The 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.

See also: dtCreateNavMeshData, removeTile

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

Calculates the tile grid location for the specified world position.

Parameters

[in]	pos	The world position for the query. [(x, y, z)]
[out]	tx	The tile's x-location. (x, y)
[out]	ty	The tile's y-location. (x, y)

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]	ref	The polygon reference to decode.
[out]	salt	The tile's salt value.
[out]	it	The index of the tile.
[out]	ip	The index of the polygon within the tile.

See also: encodePolyId

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] ref The polygon reference.

See also: encodePolyId

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] ref The polygon reference.

See also: encodePolyId

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] ref The polygon reference.

See also: 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]	salt	The tile's salt value.
[in]	it	The index of the tile.
[in]	ip	The index of the polygon within the tile.

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.

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

Gets the specified off-mesh connection.

Parameters

[in] ref The polygon reference of the off-mesh connection.

Returns: The specified off-mesh connection, or null if the polygon reference is not valid.

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]	prevRef	The reference of the polygon before the connection.
[in]	polyRef	The reference of the off-mesh connection polygon.
[out]	startPos	The start position of the off-mesh connection. [(x, y, z)]
[out]	endPos	The 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.

const dtNavMeshParams * dtNavMesh::getParams ( ) const

The navigation mesh initialization params.

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

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

Gets the user defined flags for the specified polygon.

Parameters

[in]	ref	The polygon reference.
[out]	resultFlags	The polygon flags.

Returns: The status flags for the operation.

dtPolyRef dtNavMesh::getPolyRefBase ( const dtMeshTile * tile ) const

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

Parameters

[in] tile The 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.
}

dtStatus dtNavMesh::getPolyTeamCost	(	dtPolyRef	ref,
		dtTeam	team,
		float *	costResult
	)		const

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

Gets the tile at the specified index.

Parameters

[in] i The tile index. [Limit: 0 >= index < getMaxTiles()]

Returns: The tile at the specified index.

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]	ref	The reference for the a polygon.
[out]	tile	The tile containing the polygon.
[out]	poly	The polygon.

Returns: The status flags for the operation.

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]	ref	A known valid reference for a polygon.
[out]	tile	The tile containing the polygon.
[out]	poly	The 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.

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

Gets the tile at the specified grid location.

Parameters

[in]	x	The tile's x-location. (x, y, layer)
[in]	y	The tile's y-location. (x, y, layer)
[in]	layer	The tile's layer. (x, y, layer)

Returns: The tile, or null if the tile does not exist.

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

Gets the tile for the specified tile reference.

Parameters

[in] ref The tile reference of the tile to retrieve.

Returns: The tile for the specified reference, or null if the reference is invalid.

dtTileRef dtNavMesh::getTileRef ( const dtMeshTile * tile ) const

Gets the tile reference for the specified tile.

Parameters

[in] tile The tile.

Returns: The tile reference of the tile.

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

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

Parameters

[in]	x	The tile's x-location. (x, y, layer)
[in]	y	The tile's y-location. (x, y, layer)
[in]	layer	The tile's layer. (x, y, layer)

Returns: The tile reference of the tile, or 0 if there is none.

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]	x	The tile's x-location. (x, y)
[in]	y	The tile's y-location. (x, y)
[out]	tiles	A pointer to an array of tiles that will hold the result.
[in]	maxTiles	The 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.

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] tile The tile.

Returns: The size of the buffer required to store the state.

See also: storeTileState

dtStatus dtNavMesh::init ( const dtNavMeshParams * params )

Initializes the navigation mesh for tiled use.

Parameters

[in] params Initialization parameters.

Returns: The status flags for the operation.

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

Initializes the navigation mesh for single tile use.

Parameters

[in]	data	Data of the new tile. (See: dtCreateNavMeshData)
[in]	dataSize	The data size of the new tile.
[in]	flags	The tile flags. (See: dtTileFlags)

Returns: The status flags for the operation.

See also: dtCreateNavMeshData

bool dtNavMesh::isValidPolyRef ( dtPolyRef ref ) const

Checks the validity of a polygon reference.

Parameters

[in] ref The polygon reference to check.

Returns: True if polygon reference is valid for the navigation mesh.

void dtNavMesh::queryTiles	(	const float	mins[3],
		const float	maxs[3],
		dtTileCallback	callback,
		void *	userdata
	)		const

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

Removes the specified tile from the navigation mesh.

Parameters

[in]	ref	The reference of the tile to remove.
[out]	data	Data associated with deleted tile.
[out]	dataSize	Size 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

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

Restores the state of the tile.

Parameters

[in]	tile	The tile.
[in]	data	The new state. (Obtained from storeTileState.)
[in]	maxDataSize	The 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

dtStatus dtNavMesh::setPolyFlags	(	dtPolyRef	ref,
		navAreaMask	areaMask
	)

Sets the user defined flags for the specified polygon.

Parameters

[in]	ref	The polygon reference.
[in]	areaMask	The new flags for the polygon.

Returns: The status flags for the operation.

dtStatus dtNavMesh::setPolyTeamCost	(	dtPolyRef	ref,
		dtTeam	team,
		float	cost
	)

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]	tile	The tile.
[out]	data	The buffer to store the tile's state in.
[in]	maxDataSize	The 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

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

Public Member Functions

Description

Constructor & Destructor Documentation

Member Function Documentation