Planeshift
Classes | Public Member Functions

dtNavMeshQuery Class Reference

Provides the ability to perform pathfinding related queries against a navigation mesh. More...

#include <DetourNavMeshQuery.h>

List of all members.

Classes

struct  dtQueryData

Public Member Functions

 dtNavMeshQuery ()
dtStatus init (const dtNavMesh *nav, const int maxNodes)
 Initializes the query object.
 ~dtNavMeshQuery ()
Standard Pathfinding Functions
dtStatus findPath (dtPolyRef startRef, dtPolyRef endRef, const float *startPos, const float *endPos, const dtQueryFilter *filter, dtPolyRef *path, int *pathCount, const int maxPath) const
 Finds a path from the start polygon to the end polygon.
dtStatus findStraightPath (const float *startPos, const float *endPos, const dtPolyRef *path, const int pathSize, float *straightPath, unsigned char *straightPathFlags, dtPolyRef *straightPathRefs, int *straightPathCount, const int maxStraightPath) const
 Finds the straight path from the start to the end position within the polygon corridor.
Sliced Pathfinding Functions

Common use case:

  1. Call initSlicedFindPath() to initialize the sliced path query.
  2. Call updateSlicedFindPath() until it returns complete.
  3. Call finalizeSlicedFindPath() to get the path.
dtStatus initSlicedFindPath (dtPolyRef startRef, dtPolyRef endRef, const float *startPos, const float *endPos, const dtQueryFilter *filter)
 Intializes a sliced path query.
dtStatus updateSlicedFindPath (const int maxIter, int *doneIters)
 Updates an in-progress sliced path query.
dtStatus finalizeSlicedFindPath (dtPolyRef *path, int *pathCount, const int maxPath)
 Finalizes and returns the results of a sliced path query.
dtStatus finalizeSlicedFindPathPartial (const dtPolyRef *existing, const int existingSize, dtPolyRef *path, int *pathCount, const int maxPath)
 Finalizes and returns the results of an incomplete sliced path query, returning the path to the furthest polygon on the existing path that was visited during the search.
Dijkstra Search Functions
dtStatus findPolysAroundCircle (dtPolyRef startRef, const float *centerPos, const float radius, const dtQueryFilter *filter, dtPolyRef *resultRef, dtPolyRef *resultParent, float *resultCost, int *resultCount, const int maxResult) const
 Finds the polygons along the navigation graph that touch the specified circle.
dtStatus findPolysAroundShape (dtPolyRef startRef, const float *verts, const int nverts, const dtQueryFilter *filter, dtPolyRef *resultRef, dtPolyRef *resultParent, float *resultCost, int *resultCount, const int maxResult) const
 Finds the polygons along the naviation graph that touch the specified convex polygon.
Local Query Functions
dtStatus findNearestPoly (const float *center, const float *extents, const dtQueryFilter *filter, dtPolyRef *nearestRef, float *nearestPt) const
 Finds the polygon nearest to the specified center point.
dtStatus queryPolygons (const float *center, const float *extents, const dtQueryFilter *filter, dtPolyRef *polys, int *polyCount, const int maxPolys) const
 Finds polygons that overlap the search box.
dtStatus findLocalNeighbourhood (dtPolyRef startRef, const float *centerPos, const float radius, const dtQueryFilter *filter, dtPolyRef *resultRef, dtPolyRef *resultParent, int *resultCount, const int maxResult) const
 Finds the non-overlapping navigation polygons in the local neighbourhood around the center position.
dtStatus moveAlongSurface (dtPolyRef startRef, const float *startPos, const float *endPos, const dtQueryFilter *filter, float *resultPos, dtPolyRef *visited, int *visitedCount, const int maxVisitedSize) const
 Moves from the start to the end position constrained to the navigation mesh.
dtStatus raycast (dtPolyRef startRef, const float *startPos, const float *endPos, const dtQueryFilter *filter, float *t, float *hitNormal, dtPolyRef *path, int *pathCount, const int maxPath) const
 Casts a 'walkability' ray along the surface of the navigation mesh from the start position toward the end position.
dtStatus findDistanceToWall (dtPolyRef startRef, const float *centerPos, const float maxRadius, const dtQueryFilter *filter, float *hitDist, float *hitPos, float *hitNormal) const
 Finds the distance from the specified position to the nearest polygon wall.
dtStatus getPolyWallSegments (dtPolyRef ref, const dtQueryFilter *filter, float *segmentVerts, dtPolyRef *segmentRefs, int *segmentCount, const int maxSegments) const
 Returns the segments for the specified polygon, optionally including portals.
dtStatus findRandomPoint (const dtQueryFilter *filter, float(*frand)(), dtPolyRef *randomRef, float *randomPt) const
 Returns random location on navmesh. Polygons are chosen weighted by area. The search runs in linear related to number of polygon.
dtStatus findRandomPointAroundCircle (dtPolyRef startRef, const float *centerPos, const float maxRadius, const dtQueryFilter *filter, float(*frand)(), dtPolyRef *randomRef, float *randomPt) const
 Returns random location on navmesh within the reach of specified location. Polygons are chosen weighted by area. The search runs in linear related to number of polygon. The location is not exactly constrained by the circle, but it limits the visited polygons.
dtStatus closestPointOnPoly (dtPolyRef ref, const float *pos, float *closest) const
 Finds the closest point on the specified polygon.
dtStatus closestPointOnPolyBoundary (dtPolyRef ref, const float *pos, float *closest) const
 Returns a point on the boundary closest to the source point if the source point is outside the polygon's xz-bounds.
dtStatus getPolyHeight (dtPolyRef ref, const float *pos, float *height) const
 Gets the height of the polygon at the provided position using the height detail. (Most accurate.)
Miscellaneous Functions
bool isValidPolyRef (dtPolyRef ref, const dtQueryFilter *filter) const
 Returns true if the polygon reference is valid and passes the filter restrictions.
bool isInClosedList (dtPolyRef ref) const
 Returns true if the polygon reference is in the closed list.
class dtNodePoolgetNodePool () const
 Gets the node pool.
const dtNavMeshgetAttachedNavMesh () const
 Gets the navigation mesh the query object is using.

Detailed Description

Provides the ability to perform pathfinding related queries against a navigation mesh.

Definition at line 121 of file DetourNavMeshQuery.h.


Constructor & Destructor Documentation

dtNavMeshQuery::dtNavMeshQuery ( )
dtNavMeshQuery::~dtNavMeshQuery ( )

Member Function Documentation

dtStatus dtNavMeshQuery::closestPointOnPoly ( dtPolyRef  ref,
const float pos,
float closest 
) const

Finds the closest point on the specified polygon.

Parameters:
[in]refThe reference id of the polygon.
[in]posThe position to check. [(x, y, z)]
[out]closestThe closest point on the polygon. [(x, y, z)]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::closestPointOnPolyBoundary ( dtPolyRef  ref,
const float pos,
float closest 
) const

Returns a point on the boundary closest to the source point if the source point is outside the polygon's xz-bounds.

Parameters:
[in]refThe reference id to the polygon.
[in]posThe position to check. [(x, y, z)]
[out]closestThe closest point. [(x, y, z)]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::finalizeSlicedFindPath ( dtPolyRef path,
int pathCount,
const int  maxPath 
)

Finalizes and returns the results of a sliced path query.

Parameters:
[out]pathAn ordered list of polygon references representing the path. (Start to end.) [(polyRef) * pathCount]
[out]pathCountThe number of polygons returned in the path array.
[in]maxPathThe max number of polygons the path array can hold. [Limit: >= 1]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::finalizeSlicedFindPathPartial ( const dtPolyRef existing,
const int  existingSize,
dtPolyRef path,
int pathCount,
const int  maxPath 
)

Finalizes and returns the results of an incomplete sliced path query, returning the path to the furthest polygon on the existing path that was visited during the search.

Parameters:
[out]existingAn array of polygon references for the existing path.
[out]existingSizeThe number of polygon in the existing array.
[out]pathAn ordered list of polygon references representing the path. (Start to end.) [(polyRef) * pathCount]
[out]pathCountThe number of polygons returned in the path array.
[in]maxPathThe max number of polygons the path array can hold. [Limit: >= 1]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findDistanceToWall ( dtPolyRef  startRef,
const float centerPos,
const float  maxRadius,
const dtQueryFilter filter,
float hitDist,
float hitPos,
float hitNormal 
) const

Finds the distance from the specified position to the nearest polygon wall.

Parameters:
[in]startRefThe reference id of the polygon containing centerPos.
[in]centerPosThe center of the search circle. [(x, y, z)]
[in]maxRadiusThe radius of the search circle.
[in]filterThe polygon filter to apply to the query.
[out]hitDistThe distance to the nearest wall from centerPos.
[out]hitPosThe nearest position on the wall that was hit. [(x, y, z)]
[out]hitNormalThe normalized ray formed from the wall point to the source point. [(x, y, z)]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findLocalNeighbourhood ( dtPolyRef  startRef,
const float centerPos,
const float  radius,
const dtQueryFilter filter,
dtPolyRef resultRef,
dtPolyRef resultParent,
int resultCount,
const int  maxResult 
) const

Finds the non-overlapping navigation polygons in the local neighbourhood around the center position.

Parameters:
[in]startRefThe reference id of the polygon where the search starts.
[in]centerPosThe center of the query circle. [(x, y, z)]
[in]radiusThe radius of the query circle.
[in]filterThe polygon filter to apply to the query.
[out]resultRefThe reference ids of the polygons touched by the circle.
[out]resultParentThe reference ids of the parent polygons for each result. Zero if a result polygon has no parent. [opt]
[out]resultCountThe number of polygons found.
[in]maxResultThe maximum number of polygons the result arrays can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findNearestPoly ( const float center,
const float extents,
const dtQueryFilter filter,
dtPolyRef nearestRef,
float nearestPt 
) const

Finds the polygon nearest to the specified center point.

Parameters:
[in]centerThe center of the search box. [(x, y, z)]
[in]extentsThe search distance along each axis. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[out]nearestRefThe reference id of the nearest polygon.
[out]nearestPtThe nearest point on the polygon. [opt] [(x, y, z)]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findPath ( dtPolyRef  startRef,
dtPolyRef  endRef,
const float startPos,
const float endPos,
const dtQueryFilter filter,
dtPolyRef path,
int pathCount,
const int  maxPath 
) const

Finds a path from the start polygon to the end polygon.

Parameters:
[in]startRefThe refrence id of the start polygon.
[in]endRefThe reference id of the end polygon.
[in]startPosA position within the start polygon. [(x, y, z)]
[in]endPosA position within the end polygon. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[out]pathAn ordered list of polygon references representing the path. (Start to end.) [(polyRef) * pathCount]
[out]pathCountThe number of polygons returned in the path array.
[in]maxPathThe maximum number of polygons the path array can hold. [Limit: >= 1]
dtStatus dtNavMeshQuery::findPolysAroundCircle ( dtPolyRef  startRef,
const float centerPos,
const float  radius,
const dtQueryFilter filter,
dtPolyRef resultRef,
dtPolyRef resultParent,
float resultCost,
int resultCount,
const int  maxResult 
) const

Finds the polygons along the navigation graph that touch the specified circle.

Parameters:
[in]startRefThe reference id of the polygon where the search starts.
[in]centerPosThe center of the search circle. [(x, y, z)]
[in]radiusThe radius of the search circle.
[in]filterThe polygon filter to apply to the query.
[out]resultRefThe reference ids of the polygons touched by the circle. [opt]
[out]resultParentThe reference ids of the parent polygons for each result. Zero if a result polygon has no parent. [opt]
[out]resultCostThe search cost from centerPos to the polygon. [opt]
[out]resultCountThe number of polygons found. [opt]
[in]maxResultThe maximum number of polygons the result arrays can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findPolysAroundShape ( dtPolyRef  startRef,
const float verts,
const int  nverts,
const dtQueryFilter filter,
dtPolyRef resultRef,
dtPolyRef resultParent,
float resultCost,
int resultCount,
const int  maxResult 
) const

Finds the polygons along the naviation graph that touch the specified convex polygon.

Parameters:
[in]startRefThe reference id of the polygon where the search starts.
[in]vertsThe vertices describing the convex polygon. (CCW) [(x, y, z) * nverts]
[in]nvertsThe number of vertices in the polygon.
[in]filterThe polygon filter to apply to the query.
[out]resultRefThe reference ids of the polygons touched by the search polygon. [opt]
[out]resultParentThe reference ids of the parent polygons for each result. Zero if a result polygon has no parent. [opt]
[out]resultCostThe search cost from the centroid point to the polygon. [opt]
[out]resultCountThe number of polygons found.
[in]maxResultThe maximum number of polygons the result arrays can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findRandomPoint ( const dtQueryFilter filter,
float(*)()  frand,
dtPolyRef randomRef,
float randomPt 
) const

Returns random location on navmesh. Polygons are chosen weighted by area. The search runs in linear related to number of polygon.

Parameters:
[in]filterThe polygon filter to apply to the query.
[in]frandFunction returning a random number [0..1).
[out]randomRefThe reference id of the random location.
[out]randomPtThe random location.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findRandomPointAroundCircle ( dtPolyRef  startRef,
const float centerPos,
const float  maxRadius,
const dtQueryFilter filter,
float(*)()  frand,
dtPolyRef randomRef,
float randomPt 
) const

Returns random location on navmesh within the reach of specified location. Polygons are chosen weighted by area. The search runs in linear related to number of polygon. The location is not exactly constrained by the circle, but it limits the visited polygons.

Parameters:
[in]startRefThe reference id of the polygon where the search starts.
[in]centerPosThe center of the search circle. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[in]frandFunction returning a random number [0..1).
[out]randomRefThe reference id of the random location.
[out]randomPtThe random location. [(x, y, z)]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::findStraightPath ( const float startPos,
const float endPos,
const dtPolyRef path,
const int  pathSize,
float straightPath,
unsigned char *  straightPathFlags,
dtPolyRef straightPathRefs,
int straightPathCount,
const int  maxStraightPath 
) const

Finds the straight path from the start to the end position within the polygon corridor.

Parameters:
[in]startPosPath start position. [(x, y, z)]
[in]endPosPath end position. [(x, y, z)]
[in]pathAn array of polygon references that represent the path corridor.
[in]pathSizeThe number of polygons in the path array.
[out]straightPathPoints describing the straight path. [(x, y, z) * straightPathCount].
[out]straightPathFlagsFlags describing each point. (See: dtStraightPathFlags) [opt]
[out]straightPathRefsThe reference id of the polygon that is being entered at each point. [opt]
[out]straightPathCountThe number of points in the straight path.
[in]maxStraightPathThe maximum number of points the straight path arrays can hold. [Limit: > 0]
Returns:
The status flags for the query.
const dtNavMesh* dtNavMeshQuery::getAttachedNavMesh ( ) const [inline]

Gets the navigation mesh the query object is using.

Returns:
The navigation mesh the query object is using.

Definition at line 418 of file DetourNavMeshQuery.h.

class dtNodePool* dtNavMeshQuery::getNodePool ( ) const [inline]

Gets the node pool.

Returns:
The node pool.

Definition at line 414 of file DetourNavMeshQuery.h.

dtStatus dtNavMeshQuery::getPolyHeight ( dtPolyRef  ref,
const float pos,
float height 
) const

Gets the height of the polygon at the provided position using the height detail. (Most accurate.)

Parameters:
[in]refThe reference id of the polygon.
[in]posA position within the xz-bounds of the polygon. [(x, y, z)]
[out]heightThe height at the surface of the polygon.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::getPolyWallSegments ( dtPolyRef  ref,
const dtQueryFilter filter,
float segmentVerts,
dtPolyRef segmentRefs,
int segmentCount,
const int  maxSegments 
) const

Returns the segments for the specified polygon, optionally including portals.

Parameters:
[in]refThe reference id of the polygon.
[in]filterThe polygon filter to apply to the query.
[out]segmentVertsThe segments. [(ax, ay, az, bx, by, bz) * segmentCount]
[out]segmentRefsThe reference ids of each segment's neighbor polygon. Or zero if the segment is a wall. [opt] [(parentRef) * segmentCount]
[out]segmentCountThe number of segments returned.
[in]maxSegmentsThe maximum number of segments the result arrays can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::init ( const dtNavMesh nav,
const int  maxNodes 
)

Initializes the query object.

Parameters:
[in]navPointer to the dtNavMesh object to use for all queries.
[in]maxNodesMaximum number of search nodes. [Limits: 0 < value <= 65536]
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::initSlicedFindPath ( dtPolyRef  startRef,
dtPolyRef  endRef,
const float startPos,
const float endPos,
const dtQueryFilter filter 
)

Intializes a sliced path query.

Parameters:
[in]startRefThe refrence id of the start polygon.
[in]endRefThe reference id of the end polygon.
[in]startPosA position within the start polygon. [(x, y, z)]
[in]endPosA position within the end polygon. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
Returns:
The status flags for the query.
bool dtNavMeshQuery::isInClosedList ( dtPolyRef  ref) const

Returns true if the polygon reference is in the closed list.

Parameters:
[in]refThe reference id of the polygon to check.
Returns:
True if the polygon is in closed list.
bool dtNavMeshQuery::isValidPolyRef ( dtPolyRef  ref,
const dtQueryFilter filter 
) const

Returns true if the polygon reference is valid and passes the filter restrictions.

Parameters:
[in]refThe polygon reference to check.
[in]filterThe filter to apply.
dtStatus dtNavMeshQuery::moveAlongSurface ( dtPolyRef  startRef,
const float startPos,
const float endPos,
const dtQueryFilter filter,
float resultPos,
dtPolyRef visited,
int visitedCount,
const int  maxVisitedSize 
) const

Moves from the start to the end position constrained to the navigation mesh.

Parameters:
[in]startRefThe reference id of the start polygon.
[in]startPosA position of the mover within the start polygon. [(x, y, x)]
[in]endPosThe desired end position of the mover. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[out]resultPosThe result position of the mover. [(x, y, z)]
[out]visitedThe reference ids of the polygons visited during the move.
[out]visitedCountThe number of polygons visited during the move.
[in]maxVisitedSizeThe maximum number of polygons the visited array can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::queryPolygons ( const float center,
const float extents,
const dtQueryFilter filter,
dtPolyRef polys,
int polyCount,
const int  maxPolys 
) const

Finds polygons that overlap the search box.

Parameters:
[in]centerThe center of the search box. [(x, y, z)]
[in]extentsThe search distance along each axis. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[out]polysThe reference ids of the polygons that overlap the query box.
[out]polyCountThe number of polygons in the search result.
[in]maxPolysThe maximum number of polygons the search result can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::raycast ( dtPolyRef  startRef,
const float startPos,
const float endPos,
const dtQueryFilter filter,
float t,
float hitNormal,
dtPolyRef path,
int pathCount,
const int  maxPath 
) const

Casts a 'walkability' ray along the surface of the navigation mesh from the start position toward the end position.

Parameters:
[in]startRefThe reference id of the start polygon.
[in]startPosA position within the start polygon representing the start of the ray. [(x, y, z)]
[in]endPosThe position to cast the ray toward. [(x, y, z)]
[out]tThe hit parameter. (FLT_MAX if no wall hit.)
[out]hitNormalThe normal of the nearest wall hit. [(x, y, z)]
[in]filterThe polygon filter to apply to the query.
[out]pathThe reference ids of the visited polygons. [opt]
[out]pathCountThe number of visited polygons. [opt]
[in]maxPathThe maximum number of polygons the path array can hold.
Returns:
The status flags for the query.
dtStatus dtNavMeshQuery::updateSlicedFindPath ( const int  maxIter,
int doneIters 
)

Updates an in-progress sliced path query.

Parameters:
[in]maxIterThe maximum number of iterations to perform.
[out]doneItersThe actual number of iterations completed. [opt]
Returns:
The status flags for the query.

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