Documentation for pathfinder.

library/PolyVoxCore/include/AStarPathfinder.h

@@ -42,9 +42,22 @@ namespace PolyVox
 	extern const POLYVOXCORE_API Vector3DInt16 arrayPathfinderEdges[12];
 	extern const POLYVOXCORE_API Vector3DInt16 arrayPathfinderCorners[8];
 
+	/// This function provides the default method for checking whether a given voxel
+	/// is vaid for the path computed by the AStarPathfinder.
 	template <typename VoxelType>
 	bool aStarDefaultVoxelValidator(const Volume<VoxelType>* volData, const Vector3DInt16& v3dPos);
 
+	/// Provides a configuration for the AStarPathfinder.
+	////////////////////////////////////////////////////////////////////////////////
+	/// This structure stores the AStarPathfinder%s configuration options, because this
+	/// is simpler than providing a large number of get/set properties within the 
+	/// AStarPathfinder itself. In order to create an instance of this structure you
+	/// must provide at least a volume, a start and end point, and a list to store
+	/// the result. All the other option have sensible default values which can
+	/// optionally be changed for more precise control over the pathfinder's behaviour.
+	///
+	/// \sa AStarPathfinder
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	struct AStarPathfinderParams
 	{
@@ -73,31 +86,80 @@ namespace PolyVox
 		{
 		}
 
-		//The volume data.
+		/// This is the volume through which the AStarPathfinder must find a path.
 		Volume<VoxelType>* volume;
 
+		/// The start point for the pathfinding algorithm.
 		Vector3DInt16 start;
+		
+		/// The end point for the pathfinding algorithm.
 		Vector3DInt16 end;
 
-		//The resulting path
+		/// The resulting path will be stored as a series of points in
+		/// this list. Any existing contents will be cleared.
 		std::list<Vector3DInt16>* result;
 
-		//The requied connectivity
+		/// The AStarPathfinder performs its search by examining the neighbours
+		/// of each voxel it encounters. This property controls the meaning of
+		/// neighbour - e.g. whether two voxels must share a face, edge, or corner.
 		Connectivity connectivity;
 
-		//Bias applied to h()
+		/// For each voxel the pathfinder tracks its distance to the start (known as g())
+		/// and estimates its distance to the end (known as h()). Increasing or decreasing
+		/// h() has an effect on the way the pathfinder behaves. If h() is an underestimate
+		/// of the true distance then the pathfinder will act more like a greedy search -
+		/// always finding the shortest path but taking longer to do so. If h() is an over
+		/// estimate then the pathfinder will behave more like a best-first search - returning
+		/// a potentially suboptimal path but finding it more quickly. The hBias is multiplied
+		/// by the estimated h() value to control this behaviour.
 		float hBias;
 
-		//Max number of nodes to examine
+		/// Volumes can be pretty huge (millions of voxels) and processing each one of these
+		/// can take a long time. In A* terminology each voxel is a node, and this property
+		/// controls the maximum number of nodes that will be considered when finding the path,
+		/// before giving up and throwing an exception because a path can't be found.
 		uint32_t maxNumberOfNodes;
 
-		//Used to determine whether a given voxel is valid.
+		/// This function is called to determine whether the path can pass though a given voxel. The
+		/// default behaviour is specified by aStarDefaultVoxelValidator(), but users can specify thier
+		/// own criteria if desired. For example, if you always want a path to follow a surface then
+		/// you could check to ensure that the voxel above is empty and the voxel below is solid.
+		///
+		/// \sa aStarDefaultVoxelValidator
 		polyvox_function<bool (const Volume<VoxelType>*, const Vector3DInt16&)> isVoxelValidForPath;
 
-		//Progress callback
+		/// This function is called by the AStarPathfinder to report on its progress in getting to
+		/// the goal. The progress is reported by computing the distance from the closest node found
+		/// so far to the end node, and comparing this with the distance from the start node to the
+		/// end node. This progress value is guarenteed to never decrease, but it may stop increasing
+		///for short periods of time. It may even stop increasing altogether if a path cannot be found.
 		polyvox_function<void (float)> progressCallback;
 	};
 
+	/// The AStarPathfinder compute a path from one point in the volume to another.
+	////////////////////////////////////////////////////////////////////////////////
+	/// A* is a well known pathfinding algorithm commonly used in computer games. It
+	/// takes as input a pair of points in the world, and works out a path between
+	/// them which avoids obstacles and adheres to other user defined criteria. The
+	/// resulting path is usually the shortest possible, but a less optimal path can
+	/// be exchanged for reduced computation time.
+	///
+	/// For an excellent overview of the A* algorithm please see Amit Patel's Game 
+	/// Programming page here: http://theory.stanford.edu/~amitp/GameProgramming/ 
+	/// Much of this class is based on the principles described in those pages.
+	///
+	/// Usage of this class if very strightforward. You create an instance of it
+	/// by passing an instance of the AStarPathfinderParams structure to the constructor.
+	/// The details of the AStarPathfinderParams and the options it provides are described
+	/// in the documentation for that class.
+	///
+	/// Next you call the execute() function and wait for it to return. If a path is
+	/// found then this is stored in the list which was set as the 'result' field of
+	/// the AStarPathfinderParams. If a path cannot be found then an exception of type
+	/// std::runtime_error is thrown.
+	///
+	/// \sa AStarPathfinderParams
+	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	class AStarPathfinder
 	{

library/PolyVoxCore/include/AStarPathfinder.inl

@@ -26,7 +26,9 @@ freely, subject to the following restrictions:
 namespace PolyVox
 {
 	////////////////////////////////////////////////////////////////////////////////
-	// aStarDefaultVoxelValidator free function
+	/// Using this function, a voxel is considered valid for the path if it is inside the
+	/// volume and if its density is below that returned by the voxel's getDensity() function.
+	/// \return true is the voxel is valid for the path
 	////////////////////////////////////////////////////////////////////////////////
 	template <typename VoxelType>
 	bool aStarDefaultVoxelValidator(const Volume<VoxelType>* volData, const Vector3DInt16& v3dPos)

library/PolyVoxCore/include/PolyVoxImpl/AStarPathfinderImpl.h

@@ -35,10 +35,14 @@ namespace PolyVox
 	class ClosedNodesContainer;
 	class ThermiteGameLogic;
 
+	/// The Connectivity of a voxel determines how many neighbours it has.
 	enum Connectivity
 	{
+		/// Each voxel has six neighbours, which are those sharing a face.
 		SixConnected,
+		/// Each voxel has 18 neighbours, which are those sharing a face or an edge.
 		EighteenConnected,
+		/// Each voxel has 26 neighbours, which are those sharing a face, edge, or corner.
 		TwentySixConnected
 	};