mirror
/
OpenTTD
mirror of https://github.com/OpenTTD/OpenTTD
1
0
Fork 0
Code Issues

(svn r20890) -Doc: Make documentation accessible to doxygen.

release/1.1
alberth 2010-10-02 19:55:13 +00:00
parent 6a9b205670
commit 7c312f602c
2 changed files with 120 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

104
src/pathfinder/npf/aystar.cpp
View File

@ -7,14 +7,12 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>. * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/ */
/** @file aystar.cpp Implementation of A*. */ /** @file aystar.cpp Implementation of A*.
*
/* * This file has the core function for %AyStar.
* This file has the core function for AyStar * %AyStar is a fast path finding routine and is used for things like AI path finding and Train path finding.
* AyStar is a fast pathfinding routine and is used for things like * For more information about %AyStar (A* Algorithm), you can look at
* AI_pathfinding and Train_pathfinding. * <A HREF='http://en.wikipedia.org/wiki/A-star_search_algorithm'>http://en.wikipedia.org/wiki/A-star_search_algorithm</A>.
* For more information about AyStar (A* Algorithm), you can look at
* http://en.wikipedia.org/wiki/A-star_search_algorithm
*/ */
/* /*
@ -29,15 +27,21 @@
#include "../../core/alloc_func.hpp" #include "../../core/alloc_func.hpp"
#include "aystar.h" #include "aystar.h"
/* This looks in the Hash if a node exists in ClosedList /**
* If so, it returns the PathNode, else NULL */ * This looks in the hash whether a node exists in the closed list.
* @param node Node to search.
* @return The #PathNode if it is available, else \c NULL
*/
PathNode *AyStar::ClosedListIsInList(const AyStarNode *node) PathNode *AyStar::ClosedListIsInList(const AyStarNode *node)
{ {
return (PathNode*)this->closedlist_hash.Get(node->tile, node->direction); return (PathNode*)this->closedlist_hash.Get(node->tile, node->direction);
} }
/* This adds a node to the ClosedList /**
* It makes a copy of the data */ * This adds a node to the closed list.
* It makes a copy of the data.
* @param node Node to add to the closed list.
*/
void AyStar::ClosedListAdd(const PathNode *node) void AyStar::ClosedListAdd(const PathNode *node)
{ {
/* Add a node to the ClosedList */ /* Add a node to the ClosedList */
@ -46,16 +50,21 @@ void AyStar::ClosedListAdd(const PathNode *node)
this->closedlist_hash.Set(node->node.tile, node->node.direction, new_node); this->closedlist_hash.Set(node->node.tile, node->node.direction, new_node);
} }
/* Checks if a node is in the OpenList /**
* If so, it returns the OpenListNode, else NULL */ * Check whether a node is in the open list.
* @param node Node to search.
* @return If the node is available, it is returned, else \c NULL is returned.
*/
OpenListNode *AyStar::OpenListIsInList(const AyStarNode *node) OpenListNode *AyStar::OpenListIsInList(const AyStarNode *node)
{ {
return (OpenListNode*)this->openlist_hash.Get(node->tile, node->direction); return (OpenListNode*)this->openlist_hash.Get(node->tile, node->direction);
} }
/* Gets the best node from OpenList /**
* returns the best node, or NULL of none is found * Gets the best node from the open list.
* Also it deletes the node from the OpenList */ * It deletes the returned node from the open list.
* @returns the best node available, or \c NULL of none is found.
*/
OpenListNode *AyStar::OpenListPop() OpenListNode *AyStar::OpenListPop()
{ {
/* Return the item the Queue returns.. the best next OpenList item. */ /* Return the item the Queue returns.. the best next OpenList item. */
@ -67,8 +76,10 @@ OpenListNode *AyStar::OpenListPop()
return res; return res;
} }
/* Adds a node to the OpenList /**
* It makes a copy of node, and puts the pointer of parent in the struct */ * Adds a node to the open list.
* It makes a copy of node, and puts the pointer of parent in the struct.
*/
void AyStar::OpenListAdd(PathNode *parent, const AyStarNode *node, int f, int g) void AyStar::OpenListAdd(PathNode *parent, const AyStarNode *node, int f, int g)
{ {
/* Add a new Node to the OpenList */ /* Add a new Node to the OpenList */
@ -82,8 +93,8 @@ void AyStar::OpenListAdd(PathNode *parent, const AyStarNode *node, int f, int g)
this->openlist_queue.Push(new_node, f); this->openlist_queue.Push(new_node, f);
} }
/* /**
* Checks one tile and calculate his f-value * Checks one tile and calculate its f-value
*/ */
void AyStar::CheckTile(AyStarNode *current, OpenListNode *parent) void AyStar::CheckTile(AyStarNode *current, OpenListNode *parent)
{ {
@ -138,16 +149,14 @@ void AyStar::CheckTile(AyStarNode *current, OpenListNode *parent)
} }
} }
/* /**
* This function is the core of AyStar. It handles one item and checks * This function is the core of %AyStar. It handles one item and checks
* his neighbour items. If they are valid, they are added to be checked too. * his neighbour items. If they are valid, they are added to be checked too.
* return values: * @return Possible values:
* AYSTAR_EMPTY_OPENLIST : indicates all items are tested, and no path * - #AYSTAR_EMPTY_OPENLIST : indicates all items are tested, and no path has been found.
* has been found. * - #AYSTAR_LIMIT_REACHED : Indicates that the max_nodes limit has been reached.
* AYSTAR_LIMIT_REACHED : Indicates that the max_nodes limit has been * - #AYSTAR_FOUND_END_NODE : indicates we found the end. Path_found now is true, and in path is the path found.
* reached. * - #AYSTAR_STILL_BUSY : indicates we have done this tile, did not found the path yet, and have items left to try.
* AYSTAR_FOUND_END_NODE : indicates we found the end. Path_found now is true, and in path is the path found.
* AYSTAR_STILL_BUSY : indicates we have done this tile, did not found the path yet, and have items left to try.
*/ */
int AyStar::Loop() int AyStar::Loop()
{ {
@ -191,7 +200,7 @@ int AyStar::Loop()
} }
} }
/* /**
* This function frees the memory it allocated * This function frees the memory it allocated
*/ */
void AyStar::Free() void AyStar::Free()
@ -206,8 +215,8 @@ void AyStar::Free()
#endif #endif
} }
/* /**
* This function make the memory go back to zero * This function make the memory go back to zero.
* This function should be called when you are using the same instance again. * This function should be called when you are using the same instance again.
*/ */
void AyStar::Clear() void AyStar::Clear()
@ -224,15 +233,14 @@ void AyStar::Clear()
#endif #endif
} }
/* /**
* This is the function you call to run AyStar. * This is the function you call to run AyStar.
* return values: * @return Possible values:
* AYSTAR_FOUND_END_NODE : indicates we found an end node. * - #AYSTAR_FOUND_END_NODE : indicates we found an end node.
* AYSTAR_NO_PATH : indicates that there was no path found. * - #AYSTAR_NO_PATH : indicates that there was no path found.
* AYSTAR_STILL_BUSY : indicates we have done some checked, that we did not found the path yet, and that we still have items left to try. * - #AYSTAR_STILL_BUSY : indicates we have done some checked, that we did not found the path yet, and that we still have items left to try.
* When the algorithm is done (when the return value is not AYSTAR_STILL_BUSY) * @note When the algorithm is done (when the return value is not #AYSTAR_STILL_BUSY) #Clear() is called automatically.
* this->Clear() is called. Note that when you stop the algorithm halfway, * When you stop the algorithm halfway, you should call #Clear() yourself!
* you should still call Clear() yourself!
*/ */
int AyStar::Main() int AyStar::Main()
{ {
@ -261,12 +269,13 @@ int AyStar::Main()
} }
} }
/* /**
* Adds a node from where to start an algorithm. Multiple nodes can be added * Adds a node from where to start an algorithm. Multiple nodes can be added
* if wanted. You should make sure that clear() is called before adding nodes * if wanted. You should make sure that #Clear() is called before adding nodes
* if the AyStar has been used before (though the normal main loop calls * if the #AyStar has been used before (though the normal main loop calls
* clear() automatically when the algorithm finishes * #Clear() automatically when the algorithm finishes.
* g is the cost for starting with this node. * @param start_node Node to start with.
* @param g the cost for starting with this node.
*/ */
void AyStar::AddStartNode(AyStarNode *start_node, uint g) void AyStar::AddStartNode(AyStarNode *start_node, uint g)
{ {
@ -279,8 +288,7 @@ void AyStar::AddStartNode(AyStarNode *start_node, uint g)
/** /**
* Initialize an #AyStar. You should fill all appropriate fields before * Initialize an #AyStar. You should fill all appropriate fields before
* calling #Init (see the declaration of #AyStar for which fields are * calling #Init (see the declaration of #AyStar for which fields are internal).
* internal.
*/ */
void AyStar::Init(Hash_HashProc hash, uint num_buckets) void AyStar::Init(Hash_HashProc hash, uint num_buckets)
{ {

117
src/pathfinder/npf/aystar.h
View File

@ -9,11 +9,10 @@
/** /**
* @file aystar.h * @file aystar.h
* This file has the header for AyStar * This file has the header for %AyStar.
* AyStar is a fast pathfinding routine and is used for things like * %AyStar is a fast path finding routine and is used for things like AI path finding and Train path finding.
* AI_pathfinding and Train_pathfinding.
* For more information about AyStar (A* Algorithm), you can look at * For more information about AyStar (A* Algorithm), you can look at
* http://en.wikipedia.org/wiki/A-star_search_algorithm * <A HREF='http://en.wikipedia.org/wiki/A-star_search_algorithm'>http://en.wikipedia.org/wiki/A-star_search_algorithm</A>.
*/ */
#ifndef AYSTAR_H #ifndef AYSTAR_H
@ -24,87 +23,98 @@
#include "../../track_type.h" #include "../../track_type.h"
//#define AYSTAR_DEBUG //#define AYSTAR_DEBUG
/** Return status of #AyStar methods. */
enum AystarStatus { enum AystarStatus {
AYSTAR_FOUND_END_NODE, AYSTAR_FOUND_END_NODE, ///< An end node was found.
AYSTAR_EMPTY_OPENLIST, AYSTAR_EMPTY_OPENLIST, ///< All items are tested, and no path has been found.
AYSTAR_STILL_BUSY, AYSTAR_STILL_BUSY, ///< Some checking was done, but no path found yet, and there are still items left to try.
AYSTAR_NO_PATH, AYSTAR_NO_PATH, ///< No path to the goal was found.
AYSTAR_LIMIT_REACHED, AYSTAR_LIMIT_REACHED, ///< The #max_nodes limit has been reached, aborting search.
AYSTAR_DONE AYSTAR_DONE, ///< Not an end-tile, or wrong direction.
}; };
static const int AYSTAR_INVALID_NODE = -1; static const int AYSTAR_INVALID_NODE = -1; ///< Item is not valid (for example, not walkable).
/** Node in the search. */
struct AyStarNode { struct AyStarNode {
TileIndex tile; TileIndex tile;
Trackdir direction; Trackdir direction;
uint user_data[2]; uint user_data[2];
}; };
/* The resulting path has nodes looking like this. */ /** A path of nodes. */
struct PathNode { struct PathNode {
AyStarNode node; AyStarNode node;
/* The parent of this item */ PathNode *parent; ///< The parent of this item.
PathNode *parent;
}; };
/* For internal use only /**
* We do not save the h-value, because it is only needed to calculate the f-value. * Internal node.
* h-value should _always_ be the distance left to the end-tile. */ * @note We do not save the h-value, because it is only needed to calculate the f-value.
* h-value should \em always be the distance left to the end-tile.
*/
struct OpenListNode { struct OpenListNode {
int g; int g;
PathNode path; PathNode path;
}; };
struct AyStar; struct AyStar;
/*
* This function is called to check if the end-tile is found /**
* return values can be: * Check whether the end-tile is found.
* AYSTAR_FOUND_END_NODE : indicates this is the end tile * @param aystar %AyStar search algorithm data.
* AYSTAR_DONE : indicates this is not the end tile (or direction was wrong) * @param current Node to examone.
*/ * @note The 2nd parameter should be #OpenListNode, and \em not #AyStarNode. #AyStarNode is
/* * part of #OpenListNode and so it could be accessed without any problems.
* The 2nd parameter should be OpenListNode, and NOT AyStarNode. AyStarNode is * The good part about #OpenListNode is, and how AIs use it, that you can
* part of OpenListNode and so it could be accessed without any problems.
* The good part about OpenListNode is, and how AIs use it, that you can
* access the parent of the current node, and so check if you, for example * access the parent of the current node, and so check if you, for example
* don't try to enter the file tile with a 90-degree curve. So please, leave * don't try to enter the file tile with a 90-degree curve. So please, leave
* this an OpenListNode, it works just fine -- TrueLight * this an #OpenListNode, it works just fine -- TrueLight
* @return Status of the node:
* - #AYSTAR_FOUND_END_NODE : indicates this is the end tile
* - #AYSTAR_DONE : indicates this is not the end tile (or direction was wrong)
*/ */
typedef int32 AyStar_EndNodeCheck(AyStar *aystar, OpenListNode *current); typedef int32 AyStar_EndNodeCheck(AyStar *aystar, OpenListNode *current);
/* /**
* This function is called to calculate the G-value for AyStar Algorithm. * Calculate the G-value for the %AyStar algorithm.
* return values can be: * @return G value of the node:
* AYSTAR_INVALID_NODE : indicates an item is not valid (e.g.: unwalkable) * - #AYSTAR_INVALID_NODE : indicates an item is not valid (e.g.: unwalkable)
* Any value >= 0 : the g-value for this tile * - Any value >= 0 : the g-value for this tile
*/ */
typedef int32 AyStar_CalculateG(AyStar *aystar, AyStarNode *current, OpenListNode *parent); typedef int32 AyStar_CalculateG(AyStar *aystar, AyStarNode *current, OpenListNode *parent);
/* /**
* This function is called to calculate the H-value for AyStar Algorithm. * Calculate the H-value for the %AyStar algorithm.
* Mostly, this must result the distance (Manhattan way) between the * Mostly, this must return the distance (Manhattan way) between the current point and the end point.
* current point and the end point * @return The h-value for this tile (any value >= 0)
* return values can be:
* Any value >= 0 : the h-value for this tile
*/ */
typedef int32 AyStar_CalculateH(AyStar *aystar, AyStarNode *current, OpenListNode *parent); typedef int32 AyStar_CalculateH(AyStar *aystar, AyStarNode *current, OpenListNode *parent);
/* /**
* This function request the tiles around the current tile and put them in tiles_around * This function requests the tiles around the current tile and put them in #tiles_around.
* tiles_around is never resetted, so if you are not using directions, just leave it alone. * #tiles_around is never reset, so if you are not using directions, just leave it alone.
* Warning: never add more tiles_around than memory allocated for it. * \warning Never add more tiles_around than memory allocated for it.
*/ */
typedef void AyStar_GetNeighbours(AyStar *aystar, OpenListNode *current); typedef void AyStar_GetNeighbours(AyStar *aystar, OpenListNode *current);
/* /**
* If the End Node is found, this function is called. * If the End Node is found, this function is called.
* It can do, for example, calculate the route and put that in an array * It can do, for example, calculate the route and put that in an array.
*/ */
typedef void AyStar_FoundEndNode(AyStar *aystar, OpenListNode *current); typedef void AyStar_FoundEndNode(AyStar *aystar, OpenListNode *current);
/**
* %AyStar search algorithm struct.
* Before calling #Init(), fill #CalculateG, #CalculateH, #GetNeighbours, #EndNodeCheck, and #FoundEndNode.
* If you want to change them after calling #Init(), first call #Free() !
*
* The #user_path, #user_target, and #user_data[10] are intended to be used by the user routines. The data not accessed by the #AyStar code itself.
* The user routines can change any moment they like.
*/
struct AyStar { struct AyStar {
/* These fields should be filled before initting the AyStar, but not changed /* These fields should be filled before initing the AyStar, but not changed
* afterwards (except for user_data and user_path)! (free and init again to change them) */ * afterwards (except for user_data and user_path)! (free and init again to change them) */
/* These should point to the application specific routines that do the /* These should point to the application specific routines that do the
@ -115,24 +125,19 @@ struct AyStar {
AyStar_EndNodeCheck *EndNodeCheck; AyStar_EndNodeCheck *EndNodeCheck;
AyStar_FoundEndNode *FoundEndNode; AyStar_FoundEndNode *FoundEndNode;
/* These are completely untouched by AyStar, they can be accesed by /* These are completely untouched by AyStar, they can be accessed by
* the application specific routines to input and output data. * the application specific routines to input and output data.
* user_path should typically contain data about the resulting path * user_path should typically contain data about the resulting path
* afterwards, user_target should typically contain information about * afterwards, user_target should typically contain information about
* what where looking for, and user_data can contain just about * what you where looking for, and user_data can contain just about
* everything */ * everything */
void *user_path; void *user_path;
void *user_target; void *user_target;
uint user_data[10]; uint user_data[10];
/* How many loops are there called before Main() gives byte loops_per_tick; ///< How many loops are there called before Main() gives control back to the caller. 0 = until done.
* control back to the caller. 0 = until done */ uint max_path_cost; ///< If the g-value goes over this number, it stops searching, 0 = infinite.
byte loops_per_tick; uint max_search_nodes; ///< The maximum number of nodes that will be expanded, 0 = infinite.
/* If the g-value goes over this number, it stops searching
* 0 = infinite */
uint max_path_cost;
/* The maximum amount of nodes that will be expanded, 0 = infinite */
uint max_search_nodes;
/* These should be filled with the neighbours of a tile by /* These should be filled with the neighbours of a tile by
* GetNeighbours */ * GetNeighbours */