From 11fc21458342f3694e4fb48b8bbab92d82a704c1 Mon Sep 17 00:00:00 2001 From: David Williams Date: Thu, 9 Dec 2010 21:39:35 +0000 Subject: [PATCH] Documentation for pathfinder. --- library/PolyVoxCore/include/AStarPathfinder.h | 76 +++++++++++++++++-- .../PolyVoxCore/include/AStarPathfinder.inl | 4 +- .../include/PolyVoxImpl/AStarPathfinderImpl.h | 4 + 3 files changed, 76 insertions(+), 8 deletions(-) diff --git a/library/PolyVoxCore/include/AStarPathfinder.h b/library/PolyVoxCore/include/AStarPathfinder.h index a057fb0b..c09f4092 100644 --- a/library/PolyVoxCore/include/AStarPathfinder.h +++ b/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 bool aStarDefaultVoxelValidator(const Volume* 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 struct AStarPathfinderParams { @@ -73,31 +86,80 @@ namespace PolyVox { } - //The volume data. + /// This is the volume through which the AStarPathfinder must find a path. Volume* 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* 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*, 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 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 class AStarPathfinder { diff --git a/library/PolyVoxCore/include/AStarPathfinder.inl b/library/PolyVoxCore/include/AStarPathfinder.inl index 402e1349..32015743 100644 --- a/library/PolyVoxCore/include/AStarPathfinder.inl +++ b/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 bool aStarDefaultVoxelValidator(const Volume* volData, const Vector3DInt16& v3dPos) diff --git a/library/PolyVoxCore/include/PolyVoxImpl/AStarPathfinderImpl.h b/library/PolyVoxCore/include/PolyVoxImpl/AStarPathfinderImpl.h index acd64d2e..7f137ce4 100644 --- a/library/PolyVoxCore/include/PolyVoxImpl/AStarPathfinderImpl.h +++ b/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 };