From 82a5c863eb56042123ff03a92bbe0472ea4736ce Mon Sep 17 00:00:00 2001 From: Stephen Pratt Date: Mon, 19 Sep 2011 20:37:11 +0000 Subject: [PATCH] Detour: Added detail API documentation covering DetourNavMeshBuilder.h. Plus some minor tweaks to other Detour documentation. --- Detour/Include/DetourNavMesh.h | 4 +- Detour/Include/DetourNavMeshBuilder.h | 164 ++++++++++++++++--------- Detour/Source/DetourNavMesh.cpp | 40 ++++-- Detour/Source/DetourNavMeshBuilder.cpp | 13 ++ 4 files changed, 153 insertions(+), 68 deletions(-) diff --git a/Detour/Include/DetourNavMesh.h b/Detour/Include/DetourNavMesh.h index 7e21a27..e445fbd 100644 --- a/Detour/Include/DetourNavMesh.h +++ b/Detour/Include/DetourNavMesh.h @@ -64,7 +64,7 @@ static const unsigned short DT_EXT_LINK = 0x8000; /// A value that indicates the entity does not link to anything. static const unsigned int DT_NULL_LINK = 0xffffffff; -/// A flag that indicates that an off-mesh connection can be traversed in both directions. (Is bi-directional.) +/// A flag that indicates that an off-mesh connection can be traversed in both directions. (Is bidirectional.) static const unsigned int DT_OFFMESH_CON_BIDIR = 1; /// The maximum number of user defined area ids. @@ -254,7 +254,7 @@ struct dtMeshTile dtMeshTile* next; ///< The next free tile, or the next tile in the spatial grid. }; -/// Configutration parameters used to define multi-tile navigation meshes. +/// Configuration parameters used to define multi-tile navigation meshes. /// The values are used to allocate space during the initialization of a navigation mesh. /// @see dtNavMesh::init() /// @ingroup detour diff --git a/Detour/Include/DetourNavMeshBuilder.h b/Detour/Include/DetourNavMeshBuilder.h index fdb96ec..c80d171 100644 --- a/Detour/Include/DetourNavMeshBuilder.h +++ b/Detour/Include/DetourNavMeshBuilder.h @@ -21,74 +21,128 @@ #include "DetourAlloc.h" - -/// The units of the parameters are specified in parenthesis as follows: -/// (vx) voxels, (wu) world units +/// Represents the source data used to build an navigation mesh tile. +/// @ingroup detour struct dtNavMeshCreateParams { - /// @name Navmesh vertices. - ///@{ - const unsigned short* verts; ///< Array of vertices, each vertex has 3 components. (vx). - int vertCount; ///< Vertex count - ///@{ - /// @name Navmesh polygons - ///@{ - const unsigned short* polys; ///< Array of polygons, uses same format as rcPolyMesh. - const unsigned short* polyFlags; ///< Array of flags per polygon. - const unsigned char* polyAreas; ///< Array of area ids per polygon. - int polyCount; ///< Number of polygons - int nvp; ///< Number of verts per polygon. - ///@} + /// @name Polygon Mesh Attributes + /// Used to create the base navigation graph. + /// See #rcPolyMesh for details related to these attributes. + /// @{ - /// @name Navmesh Detail (optional) - ///@{ - const unsigned int* detailMeshes; ///< Detail meshes, uses same format as rcPolyMeshDetail. - const float* detailVerts; ///< Detail mesh vertices, uses same format as rcPolyMeshDetail (wu). - int detailVertsCount; ///< Total number of detail vertices - const unsigned char* detailTris; ///< Array of detail tris per detail mesh. - int detailTriCount; ///< Total number of detail triangles. - ///@} + const unsigned short* verts; ///< The polygon mesh vertices. [(x, y, z) * #vertCount] [Unit: vx] + int vertCount; ///< The number vertices in the polygon mesh. [Limit: >= 3] + const unsigned short* polys; ///< The polygon data. [Size: #polyCount * 2 * #nvp] + const unsigned short* polyFlags; ///< The user defined flags assigned to each polygon. [Size: #polyCount] + const unsigned char* polyAreas; ///< The user defined area ids assigned to each polygon. [Size: #polyCount] + int polyCount; ///< Number of polygons in the mesh. [Limit: >= 1] + int nvp; ///< Number maximum number of vertices per polygon. [Limit: >= 3] - /// @name Off-Mesh Connections. - ///@{ - const float* offMeshConVerts; ///< Off-mesh connection vertices (wu). - const float* offMeshConRad; ///< Off-mesh connection radii (wu). - const unsigned short* offMeshConFlags; ///< Off-mesh connection flags. - const unsigned char* offMeshConAreas; ///< Off-mesh connection area ids. - const unsigned char* offMeshConDir; ///< Off-mesh connection direction flags (1 = bidir, 0 = oneway). - const unsigned int* offMeshConUserID; ///< Off-mesh connection user id (optional). - int offMeshConCount; ///< Number of off-mesh connections - ///@} + /// @} + /// @name Height Detail Attributes (Optional) + /// See #rcPolyMeshDetail for details related to these attributes. + /// @{ - /// @name Tile location - ///@{ - unsigned int userId; ///< User ID bound to the tile. - int tileX, tileY, tileLayer; ///< Tile location (tile coords). - float bmin[3], bmax[3]; ///< Tile bounds (wu). - ///@} + const unsigned int* detailMeshes; ///< The height detail sub-mesh data. [Size: 4 * #polyCount] + const float* detailVerts; ///< The detail mesh vertices. [Size: 3 * #detailVertsCount] [Unit: wu] + int detailVertsCount; ///< The number of vertices in the detail mesh. + const unsigned char* detailTris; ///< The detail mesh triangles. [Size: 4 * #detailTriCount] + int detailTriCount; ///< The number of triangles in the detail mesh. - /// @name Settings - ///@{ - float walkableHeight; ///< Agent height (wu). - float walkableRadius; ///< Agent radius (wu). - float walkableClimb; ///< Agent max climb (wu). - float cs; ///< Cell size (xz) (wu). - float ch; ///< Cell height (y) (wu). - bool buildBvTree; ///< Flag indicating if BVTree for polygon query should be build. - ///@} + /// @} + /// @name Off-Mesh Connections Attributes (Optional) + /// Used to define a custom point-to-point edge within the navigation graph, an + /// off-mesh connection is a user defined traversable connection made up to two vertices, + /// at least one of which resides within a navigation mesh polygon. + /// @{ + + /// Off-mesh connection vertices. [(ax, ay, az, bx, by, bz) * #offMeshConCount] [Unit: wu] + const float* offMeshConVerts; + /// Off-mesh connection radii. [Size: #offMeshConCount] [Unit: wu] + const float* offMeshConRad; + /// User defined flags assigned to the off-mesh connections. [Size: #offMeshConCount] + const unsigned short* offMeshConFlags; + /// User defined area ids assigned to the off-mesh connections. [Size: #offMeshConCount] + const unsigned char* offMeshConAreas; + /// The permitted travel direction of the off-mesh connections. [Size: #offMeshConCount] + /// + /// 0 = Travel only from endpoint A to endpoint B.
+ /// #DT_OFFMESH_CON_BIDIR = Bidirectional travel. + const unsigned char* offMeshConDir; + /// The user defined ids of the off-mesh connection. [Size: #offMeshConCount] + const unsigned int* offMeshConUserID; + /// The number of off-mesh connections. [Limit: >= 0] + int offMeshConCount; + + /// @} + /// @name Tile Attributes + /// @note The tile grid/layer data can be left at zero if the destination is a single tile mesh. + /// @{ + + unsigned int userId; ///< The user defined id of the tile. + int tileX; ///< The tile's x-grid location within the multi-tile destination mesh. (Along the x-axis.) + int tileY; ///< The tile's y-grid location within the multi-tile desitation mesh. (Along the z-axis.) + int tileLayer; ///< The tile's layer within the layered destination mesh. [Limit: >= 0] (Along the y-axis.) + float bmin[3]; ///< The minimum bounds of the tile. [(x, y, z)] [Unit: wu] + float bmax[3]; ///< The maximum bounds of the tile. [(x, y, z)] [Unit: wu] + + /// @} + /// @name General Configuration Attributes + /// @{ + + float walkableHeight; ///< The agent height. [Unit: wu] + float walkableRadius; ///< The agent radius. [Unit: wu] + float walkableClimb; ///< The agent maximum traversable ledge. (Up/Down) [Unit: wu] + float cs; ///< The xz-plane cell size of the polygon mesh. [Limit: > 0] [Unit: wu] + float ch; ///< The y-axis cell height of the polygon mesh. [Limit: > 0] [Unit: wu] + + /// True if a bounding volume tree should be built for the tile. + /// @note The BVTree is not normally needed for layered navigation meshes. + bool buildBvTree; + + /// @} }; -/// Build navmesh data from given input data. +/// Builds navigation mesh tile data from the provided tile creation data. +/// @ingroup detour +/// @param[in] params Tile creation data. +/// @param[out] outData The resulting tile data. +/// @param[out] outDataSize The size of the tile data array. +/// @return True if the tile data was successfully created. bool dtCreateNavMeshData(dtNavMeshCreateParams* params, unsigned char** outData, int* outDataSize); -/// Swaps endianess of navmesh header. +/// Swaps the endianess of the tile data's header (#dtMeshHeader). +/// @param[in,out] data The tile data array. +/// @param[in] dataSize The size of the data array. bool dtNavMeshHeaderSwapEndian(unsigned char* data, const int dataSize); -/// Swaps endianess of the navmesh data. This function assumes that the header is in correct -/// endianess already. Call dtNavMeshHeaderSwapEndian() first on the data if the data is -/// assumed to be in wrong endianess to start with. If converting from native endianess to foreign, -/// call dtNavMeshHeaderSwapEndian() after the data has been swapped. +/// Swaps endianess of the tile data. +/// @param[in,out] data The tile data array. +/// @param[in] dataSize The size of the data array. bool dtNavMeshDataSwapEndian(unsigned char* data, const int dataSize); #endif // DETOURNAVMESHBUILDER_H + +// This section contains detailed documentation for members that don't have +// a source file. It reduces clutter in the main section of the header. + +/** + +@struct dtNavMeshCreateParams +@par + +This structure is used to marshal data between the Recast mesh generation pipeline and Detour navigation components. + +See the rcPolyMesh and rcPolyMeshDetail documentation for detailed information related to mesh structure. + +Units are usually in voxels (vx) or world units (wu). The units for voxels, grid size, and cell size +are all based on the values of #cs and #ch. + +The standard navigation mesh build process is to create tile data using dtCreateNavMeshData, then add the tile +to a navigation mesh using either the dtNavMesh single tile init() function or the dtNavMesh::addTile() +function. + +@see dtCreateNavMeshData + +*/ \ No newline at end of file diff --git a/Detour/Source/DetourNavMesh.cpp b/Detour/Source/DetourNavMesh.cpp index 8587c62..87d600a 100644 --- a/Detour/Source/DetourNavMesh.cpp +++ b/Detour/Source/DetourNavMesh.cpp @@ -155,17 +155,35 @@ void dtFreeNavMesh(dtNavMesh* navmesh) ////////////////////////////////////////////////////////////////////////////////////////// -/// @class dtNavMesh -/// -/// This class is usually used in conjunction with the dtNavMeshQuery class. -/// -/// 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 dtNavMeshQuery, dtCreateNavMeshData(), dtNavMeshCreateParams, #dtAllocNavMesh, #dtFreeNavMesh +/** +@class dtNavMesh + +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 dtNavMeshQuery, dtCreateNavMeshData, dtNavMeshCreateParams, #dtAllocNavMesh, #dtFreeNavMesh +*/ dtNavMesh::dtNavMesh() : m_tileWidth(0), diff --git a/Detour/Source/DetourNavMeshBuilder.cpp b/Detour/Source/DetourNavMeshBuilder.cpp index 7216443..cc614fd 100644 --- a/Detour/Source/DetourNavMeshBuilder.cpp +++ b/Detour/Source/DetourNavMeshBuilder.cpp @@ -242,6 +242,13 @@ static unsigned char classifyOffMeshPoint(const float* pt, const float* bmin, co // TODO: Better error handling. +/// @par +/// +/// The output data array is allocated using the detour allocator (dtAlloc()). The method +/// used to free the memory will be determined by how the tile is added to the navigation +/// mesh. +/// +/// @see dtNavMesh, dtNavMesh::addTile() bool dtCreateNavMeshData(dtNavMeshCreateParams* params, unsigned char** outData, int* outDataSize) { if (params->nvp > DT_VERTS_PER_POLYGON) @@ -666,6 +673,12 @@ bool dtNavMeshHeaderSwapEndian(unsigned char* data, const int /*dataSize*/) return true; } +/// @par +/// +/// @warning This function assumes that the header is in the correct endianess already. +/// Call #dtNavMeshHeaderSwapEndian() first on the data if the data is expected to be in wrong endianess +/// to start with. Call #dtNavMeshHeaderSwapEndian() after the data has been swapped if converting from +/// native to foreign endianess. bool dtNavMeshDataSwapEndian(unsigned char* data, const int /*dataSize*/) { // Make sure the data is in right format.