Detour: Added detail API documentation covering DetourNavMeshBuilder.h.

Plus some minor tweaks to other Detour documentation.

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

Detour/Include/DetourNavMeshBuilder.h

@@ -21,74 +21,128 @@
 
 #include "DetourAlloc.h"
 
-
+/// Represents the source data used to build an navigation mesh tile.
-/// The units of the parameters are specified in parenthesis as follows:
+/// @ingroup detour
-/// (vx) voxels, (wu) world units
 struct dtNavMeshCreateParams
 {
-	/// @name Navmesh vertices.
+
-	///@{
+	/// @name Polygon Mesh Attributes
-	const unsigned short* verts;			///< Array of vertices, each vertex has 3 components. (vx).
+	/// Used to create the base navigation graph.
-	int vertCount;							///< Vertex count
+	/// See #rcPolyMesh for details related to these attributes.
 	/// @{
 
-	/// @name Navmesh polygons
+	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;			///< Array of polygons, uses same format as rcPolyMesh.
+	const unsigned short* polys;			///< The polygon data. [Size: #polyCount * 2 * #nvp]
-	const unsigned short* polyFlags;		///< Array of flags per polygon.
+	const unsigned short* polyFlags;		///< The user defined flags assigned to each polygon. [Size: #polyCount]
-	const unsigned char* polyAreas;			///< Array of area ids per polygon.
+	const unsigned char* polyAreas;			///< The user defined area ids assigned to each polygon. [Size: #polyCount]
-	int polyCount;							///< Number of polygons
+	int polyCount;							///< Number of polygons in the mesh. [Limit: >= 1]
-	int nvp;								///< Number of verts per polygon.
+	int nvp;								///< Number maximum number of vertices per polygon. [Limit: >= 3]
+
 	/// @}
-
+	/// @name Height Detail Attributes (Optional)
-	/// @name Navmesh Detail (optional)
+	/// See #rcPolyMeshDetail for details related to these attributes.
 	/// @{
-	const unsigned int* detailMeshes;		///< Detail meshes, uses same format as rcPolyMeshDetail.
+
-	const float* detailVerts;				///< Detail mesh vertices, uses same format as rcPolyMeshDetail (wu).
+	const unsigned int* detailMeshes;		///< The height detail sub-mesh data. [Size: 4 * #polyCount]
-	int detailVertsCount;					///< Total number of detail vertices
+	const float* detailVerts;				///< The detail mesh vertices. [Size: 3 * #detailVertsCount] [Unit: wu]
-	const unsigned char* detailTris;		///< Array of detail tris per detail mesh.
+	int detailVertsCount;					///< The number of vertices in the detail mesh.
-	int detailTriCount;						///< Total number of detail triangles.
+	const unsigned char* detailTris;		///< The detail mesh triangles. [Size: 4 * #detailTriCount]
+	int detailTriCount;						///< The number of triangles in the detail mesh.
+
 	/// @}
-
+	/// @name Off-Mesh Connections Attributes (Optional)
-	/// @name Off-Mesh Connections.
+	/// 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.
 	/// @{
-	const float* offMeshConVerts;			///< Off-mesh connection vertices (wu).
+
-	const float* offMeshConRad;				///< Off-mesh connection radii (wu).
+	/// Off-mesh connection vertices. [(ax, ay, az, bx, by, bz) * #offMeshConCount] [Unit: wu]
-	const unsigned short* offMeshConFlags;	///< Off-mesh connection flags.
+	const float* offMeshConVerts;
-	const unsigned char* offMeshConAreas;	///< Off-mesh connection area ids.
+	/// Off-mesh connection radii. [Size: #offMeshConCount] [Unit: wu]
-	const unsigned char* offMeshConDir;		///< Off-mesh connection direction flags (1 = bidir, 0 = oneway).
+	const float* offMeshConRad;
-	const unsigned int* offMeshConUserID;	///< Off-mesh connection user id (optional).
+	/// User defined flags assigned to the off-mesh connections. [Size: #offMeshConCount]
-	int offMeshConCount;					///< Number of off-mesh connections
+	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.<br/>
+	/// #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
-	/// @name Tile location
+	/// @note The tile grid/layer data can be left at zero if the destination is a single tile mesh.
 	/// @{
-	unsigned int userId;					///< User ID bound to the tile.
+
-	int tileX, tileY, tileLayer;			///< Tile location (tile coords).
+	unsigned int userId;	///< The user defined id of the tile.
-	float bmin[3], bmax[3];					///< Tile bounds (wu).
+	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
-	/// @name Settings
 	/// @{
-	float walkableHeight;					///< Agent height (wu).
+
-	float walkableRadius;					///< Agent radius (wu).
+	float walkableHeight;	///< The agent height. [Unit: wu]
-	float walkableClimb;					///< Agent max climb (wu).
+	float walkableRadius;	///< The agent radius. [Unit: wu]
-	float cs;								///< Cell size (xz) (wu).
+	float walkableClimb;	///< The agent maximum traversable ledge. (Up/Down) [Unit: wu]
-	float ch;								///< Cell height (y) (wu).
+	float cs;				///< The xz-plane cell size of the polygon mesh. [Limit: > 0] [Unit: wu]
-	bool buildBvTree;						///< Flag indicating if BVTree for polygon query should be build.
+	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
+/// Swaps endianess of the tile data.
-/// endianess already. Call dtNavMeshHeaderSwapEndian() first on the data if the data is
+///  @param[in,out]	data		The tile data array.
-/// assumed to be in wrong endianess to start with. If converting from native endianess to foreign,
+///  @param[in]		dataSize	The size of the data array.
-/// call dtNavMeshHeaderSwapEndian() after the data has been swapped.
 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 <tt>init()</tt> function or the dtNavMesh::addTile()
+function.
+
+@see dtCreateNavMeshData
+
+*/

Detour/Source/DetourNavMesh.cpp

@@ -155,17 +155,35 @@ void dtFreeNavMesh(dtNavMesh* navmesh)
 
 //////////////////////////////////////////////////////////////////////////////////////////
 
-/// @class dtNavMesh
+/**
-///
+@class dtNavMesh
-/// This class is usually used in conjunction with the dtNavMeshQuery class.
+
-/// 
+The navigation mesh consists of one or more tiles defining three primary types of structural data:
-/// Technically, all navigation meshes are tiled. A 'solo' mesh is simply a navigation mesh initialized 
+
-/// to have only a single tile.
+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.)
-/// This class does not implement any asynchronous methods. So the ::dtStatus result of all methods will 
+Off-mesh connections, which define custom point-to-point edges within the navigation graph.
-/// always contain either a success or failure flag.
+
-/// 
+The general build process is as follows:
-/// @see dtNavMeshQuery, dtCreateNavMeshData(), dtNavMeshCreateParams, #dtAllocNavMesh, #dtFreeNavMesh
+
+-# 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),

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.