mirror of
https://github.com/recastnavigation/recastnavigation.git
synced 2026-11-18 13:56:00 +00:00
Detour: Detail API documentation covering the DetourCommon.h and DetourNavMeshQuery.h files
This commit is contained in:
@@ -27,6 +27,38 @@
|
||||
#include "DetourAssert.h"
|
||||
#include <new>
|
||||
|
||||
/// @class dtQueryFilter
|
||||
///
|
||||
/// <b>The Default Implmentation</b>
|
||||
///
|
||||
/// At construction: All area costs default to 1.0. All flags are included
|
||||
/// and none are excluded.
|
||||
///
|
||||
/// If a polygon has both an include and an exclude flag, it will be excluded.
|
||||
///
|
||||
/// The way filtering works, a navigation mesh polygon must have at least one flag
|
||||
/// set to ever be considered by a query. So a polygon with no flags will never
|
||||
/// be considered.
|
||||
///
|
||||
/// Setting the include flags to 0 will result in all polygons being excluded.
|
||||
///
|
||||
/// <b>Custom Implementations</b>
|
||||
///
|
||||
/// DT_VIRTUAL_QUERYFILTER must be defined in order to extend this class.
|
||||
///
|
||||
/// Implement a custom query filter by overriding the virtual passFilter()
|
||||
/// and getCost() functions. If this is done, both functions should be as
|
||||
/// fast as possible. Use cached local copies of data rather than accessing
|
||||
/// your own objects where possible.
|
||||
///
|
||||
/// Custom implementations do not need to adhere to the flags or cost logic
|
||||
/// used by the default implementation.
|
||||
///
|
||||
/// In order for A* searches to work properly, the cost should be proportional to
|
||||
/// the travel distance. Implementing a cost modifier less than 1.0 is likely
|
||||
/// to lead to problems during pathfinding.
|
||||
///
|
||||
/// @see dtNavMeshQuery
|
||||
|
||||
dtQueryFilter::dtQueryFilter() :
|
||||
m_includeFlags(0xffff),
|
||||
@@ -86,6 +118,23 @@ void dtFreeNavMeshQuery(dtNavMeshQuery* navmesh)
|
||||
}
|
||||
|
||||
//////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// @class dtNavMeshQuery
|
||||
///
|
||||
/// For methods that support undersized buffers, if the buffer is too small
|
||||
/// to hold the entire result set the return status of the method will include
|
||||
/// the #DT_BUFFER_TOO_SMALL flag.
|
||||
///
|
||||
/// Constant member functions can be used by multiple clients without side
|
||||
/// effects. (E.g. No change to the closed list. No impact on an in-progress
|
||||
/// sliced path query. Etc.)
|
||||
///
|
||||
/// Walls and portals: A @e wall is a polygon segment that is
|
||||
/// considered impassable. A @e portal is a passable segment between polygons.
|
||||
/// A portal may be treated as a wall based on the dtQueryFilter used for a query.
|
||||
///
|
||||
/// @see dtNavMesh, dtQueryFilter, #dtAllocNavMeshQuery(), #dtAllocNavMeshQuery()
|
||||
|
||||
dtNavMeshQuery::dtNavMeshQuery() :
|
||||
m_tinyNodePool(0),
|
||||
m_nodePool(0),
|
||||
@@ -107,6 +156,12 @@ dtNavMeshQuery::~dtNavMeshQuery()
|
||||
dtFree(m_openList);
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// Must be the first function called after construction, before other
|
||||
/// functions are used.
|
||||
///
|
||||
/// This function can be used multiple times.
|
||||
dtStatus dtNavMeshQuery::init(const dtNavMesh* nav, const int maxNodes)
|
||||
{
|
||||
m_nav = nav;
|
||||
@@ -161,6 +216,15 @@ dtStatus dtNavMeshQuery::init(const dtNavMesh* nav, const int maxNodes)
|
||||
}
|
||||
|
||||
//////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// Uses the detail polygons to find the surface height. (Most accurate.)
|
||||
///
|
||||
/// @p pos does not have to be within the bounds of the polygon or navigation mesh.
|
||||
///
|
||||
/// See closestPointOnPolyBoundary() for a limited but faster option.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::closestPointOnPoly(dtPolyRef ref, const float* pos, float* closest) const
|
||||
{
|
||||
dtAssert(m_nav);
|
||||
@@ -257,6 +321,17 @@ void dtNavMeshQuery::closestPointOnPolyInTile(const dtMeshTile* tile, const dtPo
|
||||
}
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// Much faster than closestPointOnPoly().
|
||||
///
|
||||
/// If the provided position lies within the polygon's xz-bounds (above or below),
|
||||
/// then @p pos and @p closest will be equal.
|
||||
///
|
||||
/// The height of @p closest will be the polygon boundary. The height detail is not used.
|
||||
///
|
||||
/// @p pos does not have to be within the bounds of the polybon or the navigation mesh.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::closestPointOnPolyBoundary(dtPolyRef ref, const float* pos, float* closest) const
|
||||
{
|
||||
dtAssert(m_nav);
|
||||
@@ -304,7 +379,11 @@ dtStatus dtNavMeshQuery::closestPointOnPolyBoundary(dtPolyRef ref, const float*
|
||||
return DT_SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// Will return #DT_FAILURE if the provided position is outside the xz-bounds
|
||||
/// of the polygon.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::getPolyHeight(dtPolyRef ref, const float* pos, float* height) const
|
||||
{
|
||||
dtAssert(m_nav);
|
||||
@@ -353,6 +432,12 @@ dtStatus dtNavMeshQuery::getPolyHeight(dtPolyRef ref, const float* pos, float* h
|
||||
return DT_FAILURE | DT_INVALID_PARAM;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// @note If the search box does not intersect any polygons the search will
|
||||
/// return #DT_SUCCESS, but @p nearestRef will be zero. So if in doubt, check
|
||||
/// @p nearestRef before using @p nearestPt.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findNearestPoly(const float* center, const float* extents,
|
||||
const dtQueryFilter* filter,
|
||||
dtPolyRef* nearestRef, float* nearestPt) const
|
||||
@@ -519,6 +604,15 @@ int dtNavMeshQuery::queryPolygonsInTile(const dtMeshTile* tile, const float* qmi
|
||||
}
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// If no polygons are found, the function will return #DT_SUCCESS with a
|
||||
/// @p polyCount of zero.
|
||||
///
|
||||
/// If @p polys is too small to hold the entire result set, then the array will
|
||||
/// be filled to capacity. The method of choosing which polygons from the
|
||||
/// full set are included in the partial result set is undefined.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::queryPolygons(const float* center, const float* extents,
|
||||
const dtQueryFilter* filter,
|
||||
dtPolyRef* polys, int* polyCount, const int maxPolys) const
|
||||
@@ -559,6 +653,17 @@ dtStatus dtNavMeshQuery::queryPolygons(const float* center, const float* extents
|
||||
return DT_SUCCESS;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// If the end polygon cannot be reached through the navigation graph,
|
||||
/// the last polygon in the path will be the nearest the end polygon.
|
||||
///
|
||||
/// If the path array is to small to hold the full result, it will be filled as
|
||||
/// far as possible from the start polygon toward the end polygon.
|
||||
///
|
||||
/// The start and end positions are used to calculate traversal costs.
|
||||
/// (The y-values impact the result.)
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findPath(dtPolyRef startRef, dtPolyRef endRef,
|
||||
const float* startPos, const float* endPos,
|
||||
const dtQueryFilter* filter,
|
||||
@@ -769,6 +874,14 @@ dtStatus dtNavMeshQuery::findPath(dtPolyRef startRef, dtPolyRef endRef,
|
||||
return status;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// @warning Calling any non-slice methods before calling finalizeSlicedFindPath()
|
||||
/// or finalizeSlicedFindPathPartial() may result in corrupted data!
|
||||
///
|
||||
/// The @p filter pointer is stored and used for the duration of the sliced
|
||||
/// path query.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::initSlicedFindPath(dtPolyRef startRef, dtPolyRef endRef,
|
||||
const float* startPos, const float* endPos,
|
||||
const dtQueryFilter* filter)
|
||||
@@ -1134,7 +1247,23 @@ dtStatus dtNavMeshQuery::finalizeSlicedFindPathPartial(const dtPolyRef* existing
|
||||
return DT_SUCCESS | details;
|
||||
}
|
||||
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// This method peforms what is often called 'string pulling'.
|
||||
///
|
||||
/// The start position is clamped to the first polygon in the path, and the
|
||||
/// end position is clamped to the last. So the start and end positions should
|
||||
/// normally be within or very near the first and last polygons respectively.
|
||||
///
|
||||
/// The returned polygon references represent the reference id of the polygon
|
||||
/// that is entered at the associated path position. The reference id associated
|
||||
/// with the end point will always be zero. This allows, for example, matching
|
||||
/// off-mesh link points to their representative polygons.
|
||||
///
|
||||
/// If the provided result buffers are too small for the entire result set,
|
||||
/// they will be filled as far as possible from the start toward the end
|
||||
/// position.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findStraightPath(const float* startPos, const float* endPos,
|
||||
const dtPolyRef* path, const int pathSize,
|
||||
float* straightPath, unsigned char* straightPathFlags, dtPolyRef* straightPathRefs,
|
||||
@@ -1378,6 +1507,26 @@ dtStatus dtNavMeshQuery::findStraightPath(const float* startPos, const float* en
|
||||
return DT_SUCCESS | ((n >= maxStraightPath) ? DT_BUFFER_TOO_SMALL : 0);
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// This method is optimized for small delta movement and a small number of
|
||||
/// polygons. If used for too great a distance, the result set will form an
|
||||
/// incomplete path.
|
||||
///
|
||||
/// @p resultPos will equal the @p endPos if the end is reached.
|
||||
/// Otherwise the closest reachable position will be returned.
|
||||
///
|
||||
/// @p resultPos is not projected onto the surface of the navigation
|
||||
/// mesh. Use #getPolyHeight if this is needed.
|
||||
///
|
||||
/// This method treats the end position in the same manner as
|
||||
/// the #raycast method. (As a 2D point.) See that method's documentation
|
||||
/// for details.
|
||||
///
|
||||
/// If the @p visited array is too small to hold the entire result set, it will
|
||||
/// be filled as far as possible from the start position toward the end
|
||||
/// position.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::moveAlongSurface(dtPolyRef startRef, const float* startPos, const float* endPos,
|
||||
const dtQueryFilter* filter,
|
||||
float* resultPos, dtPolyRef* visited, int* visitedCount, const int maxVisitedSize) const
|
||||
@@ -1696,6 +1845,44 @@ dtStatus dtNavMeshQuery::getEdgeMidPoint(dtPolyRef from, const dtPoly* fromPoly,
|
||||
return DT_SUCCESS;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// This method is meant to be used for quick, short distance checks.
|
||||
///
|
||||
/// If the path array is too small to hold the result, it will be filled as
|
||||
/// far as possible from the start postion toward the end position.
|
||||
///
|
||||
/// <b>Using the Hit Parameter (t)</b>
|
||||
///
|
||||
/// If the hit parameter is a very high value (FLT_MAX), then the ray has hit
|
||||
/// the end position. In this case the path represents a valid corridor to the
|
||||
/// end position and the value of @p hitNormal is undefined.
|
||||
///
|
||||
/// If the hit parameter is zero, then the start position is on the wall that
|
||||
/// was hit and the value of @p hitNormal is undefined.
|
||||
///
|
||||
/// If 0 < t < 1.0 then the following applies:
|
||||
///
|
||||
/// @code
|
||||
/// distanceToHitBorder = distanceToEndPosition * t
|
||||
/// hitPoint = startPos + (endPos - startPos) * t
|
||||
/// @endcode
|
||||
///
|
||||
/// <b>Use Case Restriction</b>
|
||||
///
|
||||
/// The raycast ignores the y-value of the end position. (2D check.) This
|
||||
/// places significant limits on how it can be used. For example:
|
||||
///
|
||||
/// Consider a scene where there is a main floor with a second floor balcony
|
||||
/// that hangs over the main floor. So the first floor mesh extends below the
|
||||
/// balcony mesh. The start position is somewhere on the first floor. The end
|
||||
/// position is on the balcony.
|
||||
///
|
||||
/// The raycast will search toward the end position along the first floor mesh.
|
||||
/// If it reaches the end position's xz-coordinates it will indicate FLT_MAX
|
||||
/// (no wall hit), meaning it reached the end position. This is one example of why
|
||||
/// this method is meant for short distance checks.
|
||||
///
|
||||
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
|
||||
@@ -1877,6 +2064,35 @@ dtStatus dtNavMeshQuery::raycast(dtPolyRef startRef, const float* startPos, cons
|
||||
return status;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// At least one result array must be provided.
|
||||
///
|
||||
/// The order of the result set is from least to highest cost to reach the polygon.
|
||||
///
|
||||
/// A common use case for this method is to perform Dijkstra searches.
|
||||
/// Candidate polygons are found by searching the graph beginning at the start polygon.
|
||||
///
|
||||
/// If a polygon is not found via the graph search, even if it intersects the
|
||||
/// search circle, it will not be included in the result set. For example:
|
||||
///
|
||||
/// polyA is the start polygon.
|
||||
/// polyB shares an edge with polyA. (Is adjacent.)
|
||||
/// polyC shares an edge with polyB, but not with polyA
|
||||
/// Even if the search circle overlaps polyC, it will not be included in the
|
||||
/// result set unless polyB is also in the set.
|
||||
///
|
||||
/// The value of the center point is used as the start position for cost
|
||||
/// calculations. It is not projected onto the surface of the mesh, so its
|
||||
/// y-value will effect the costs.
|
||||
///
|
||||
/// Intersection tests occur in 2D. All polygons and the search circle are
|
||||
/// projected onto the xz-plane. So the y-value of the center point does not
|
||||
/// effect intersection tests.
|
||||
///
|
||||
/// If the result arrays are to small to hold the entire result set, they will be
|
||||
/// filled to capacity.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findPolysAroundCircle(dtPolyRef startRef, const float* centerPos, const float radius,
|
||||
const dtQueryFilter* filter,
|
||||
dtPolyRef* resultRef, dtPolyRef* resultParent, float* resultCost,
|
||||
@@ -2030,6 +2246,28 @@ dtStatus dtNavMeshQuery::findPolysAroundCircle(dtPolyRef startRef, const float*
|
||||
return status;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// The order of the result set is from least to highest cost.
|
||||
///
|
||||
/// At least one result array must be provided.
|
||||
///
|
||||
/// A common use case for this method is to perform Dijkstra searches.
|
||||
/// Candidate polygons are found by searching the graph beginning at the start
|
||||
/// polygon.
|
||||
///
|
||||
/// The same intersection test restrictions that apply to findPolysAroundCircle()
|
||||
/// method apply to this method.
|
||||
///
|
||||
/// The 3D centroid of the search polygon is used as the start position for cost
|
||||
/// calculations.
|
||||
///
|
||||
/// Intersection tests occur in 2D. All polygons are projected onto the
|
||||
/// xz-plane. So the y-values of the vertices do not effect intersection tests.
|
||||
///
|
||||
/// If the result arrays are is too small to hold the entire result set, they will
|
||||
/// be filled to capacity.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findPolysAroundShape(dtPolyRef startRef, const float* verts, const int nverts,
|
||||
const dtQueryFilter* filter,
|
||||
dtPolyRef* resultRef, dtPolyRef* resultParent, float* resultCost,
|
||||
@@ -2188,6 +2426,28 @@ dtStatus dtNavMeshQuery::findPolysAroundShape(dtPolyRef startRef, const float* v
|
||||
return status;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// This method is optimized for a small search radius and small number of result
|
||||
/// polygons.
|
||||
///
|
||||
/// Candidate polygons are found by searching the navigation graph beginning at
|
||||
/// the start polygon.
|
||||
///
|
||||
/// The same intersection test restrictions that apply to the findPolysAroundCircle
|
||||
/// mehtod applies to this method.
|
||||
///
|
||||
/// The value of the center point is used as the start point for cost calculations.
|
||||
/// It is not projected onto the surface of the mesh, so its y-value will effect
|
||||
/// the costs.
|
||||
///
|
||||
/// Intersection tests occur in 2D. All polygons and the search circle are
|
||||
/// projected onto the xz-plane. So the y-value of the center point does not
|
||||
/// effect intersection tests.
|
||||
///
|
||||
/// If the result arrays are is too small to hold the entire result set, they will
|
||||
/// be filled to capacity.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findLocalNeighbourhood(dtPolyRef startRef, const float* centerPos, const float radius,
|
||||
const dtQueryFilter* filter,
|
||||
dtPolyRef* resultRef, dtPolyRef* resultParent,
|
||||
@@ -2392,6 +2652,17 @@ static void insertInterval(dtSegInterval* ints, int& nints, const int maxInts,
|
||||
nints++;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// If the @p segmentRefs parameter is provided, then all polygon segments will be returned.
|
||||
/// Otherwise only the wall segments are returned.
|
||||
///
|
||||
/// A segment that is normally a portal will be included in the result set as a
|
||||
/// wall if the @p filter results in the neighbor polygon becoomming impassable.
|
||||
///
|
||||
/// The @p segmentVerts and @p segmentRefs buffers should normally be sized for the
|
||||
/// maximum segments per polygon of the source navigation mesh.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::getPolyWallSegments(dtPolyRef ref, const dtQueryFilter* filter,
|
||||
float* segmentVerts, dtPolyRef* segmentRefs, int* segmentCount,
|
||||
const int maxSegments) const
|
||||
@@ -2532,6 +2803,16 @@ dtStatus dtNavMeshQuery::getPolyWallSegments(dtPolyRef ref, const dtQueryFilter*
|
||||
return status;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// @p hitPos is not adjusted using the height detail data.
|
||||
///
|
||||
/// @p hitDist will equal the search radius if there is no wall within the
|
||||
/// radius. In this case the values of @p hitPos and @p hitNormal are
|
||||
/// undefined.
|
||||
///
|
||||
/// The normal will become unpredicable if @p hitDist is a very small number.
|
||||
///
|
||||
dtStatus dtNavMeshQuery::findDistanceToWall(dtPolyRef startRef, const float* centerPos, const float maxRadius,
|
||||
const dtQueryFilter* filter,
|
||||
float* hitDist, float* hitPos, float* hitNormal) const
|
||||
@@ -2728,6 +3009,11 @@ bool dtNavMeshQuery::isValidPolyRef(dtPolyRef ref, const dtQueryFilter* filter)
|
||||
return true;
|
||||
}
|
||||
|
||||
/// @par
|
||||
///
|
||||
/// The closed list is the list of polygons that were fully evaluated during
|
||||
/// the last navigation graph search. (A* or Dijkstra)
|
||||
///
|
||||
bool dtNavMeshQuery::isInClosedList(dtPolyRef ref) const
|
||||
{
|
||||
if (!m_nodePool) return false;
|
||||
|
||||
Reference in New Issue
Block a user