dave/openttd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
alberth
2010-10-02 19:55:13 +00:00
parent 6a9b205670
commit 7c312f602c
2 changed files with 120 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -9,11 +9,10 @@
/**
* @file aystar.h
* This file has the header for AyStar
* AyStar is a fast pathfinding routine and is used for things like
* AI_pathfinding and Train_pathfinding.
* For more information about AyStar (A* Algorithm), you can look at
* http://en.wikipedia.org/wiki/A-star_search_algorithm
* This file has the header for %AyStar.
* %AyStar is a fast path finding routine and is used for things like AI path finding and Train path finding.
* For more information about AyStar (A* Algorithm), you can look at
* <A HREF='http://en.wikipedia.org/wiki/A-star_search_algorithm'>http://en.wikipedia.org/wiki/A-star_search_algorithm</A>.
*/
#ifndef AYSTAR_H
@@ -24,87 +23,98 @@
#include "../../track_type.h"
//#define AYSTAR_DEBUG
/** Return status of #AyStar methods. */
enum AystarStatus {
AYSTAR_FOUND_END_NODE,
AYSTAR_EMPTY_OPENLIST,
AYSTAR_STILL_BUSY,
AYSTAR_NO_PATH,
AYSTAR_LIMIT_REACHED,
AYSTAR_DONE
AYSTAR_FOUND_END_NODE, ///< An end node was found.
AYSTAR_EMPTY_OPENLIST, ///< All items are tested, and no path has been found.
AYSTAR_STILL_BUSY, ///< Some checking was done, but no path found yet, and there are still items left to try.
AYSTAR_NO_PATH, ///< No path to the goal was found.
AYSTAR_LIMIT_REACHED, ///< The #max_nodes limit has been reached, aborting search.
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 {
TileIndex tile;
Trackdir direction;
uint user_data[2];
};
/* The resulting path has nodes looking like this. */
/** A path of nodes. */
struct PathNode {
AyStarNode node;
/* The parent of this item */
PathNode *parent;
PathNode *parent; ///< The parent of this item.
};
/* For internal use only
* We do not save the h-value, because it is only needed to calculate the f-value.
* h-value should _always_ be the distance left to the end-tile. */
/**
* Internal node.
* @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 {
int g;
PathNode path;
};
struct AyStar;
/*
* This function is called to check if the end-tile is found
* return values can be:
* AYSTAR_FOUND_END_NODE : indicates this is the end tile
* AYSTAR_DONE : indicates this is not the end tile (or direction was wrong)
*/
/*
* The 2nd parameter should be OpenListNode, and NOT AyStarNode. AyStarNode is
* 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
/**
* Check whether the end-tile is found.
* @param aystar %AyStar search algorithm data.
* @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 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
* 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);
/*
* This function is called to calculate the G-value for AyStar Algorithm.
* return values can be:
* AYSTAR_INVALID_NODE : indicates an item is not valid (e.g.: unwalkable)
* Any value >= 0 : the g-value for this tile
/**
* Calculate the G-value for the %AyStar algorithm.
* @return G value of the node:
* - #AYSTAR_INVALID_NODE : indicates an item is not valid (e.g.: unwalkable)
* - Any value >= 0 : the g-value for this tile
*/
typedef int32 AyStar_CalculateG(AyStar *aystar, AyStarNode *current, OpenListNode *parent);
/*
* This function is called to calculate the H-value for AyStar Algorithm.
* Mostly, this must result the distance (Manhattan way) between the
* current point and the end point
* return values can be:
* Any value >= 0 : the h-value for this tile
/**
* Calculate the H-value for the %AyStar algorithm.
* Mostly, this must return the distance (Manhattan way) between the current point and the end point.
* @return The h-value for this tile (any value >= 0)
*/
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
* tiles_around is never resetted, so if you are not using directions, just leave it alone.
* Warning: never add more tiles_around than memory allocated for it.
/**
* This function requests the tiles around the current tile and put them in #tiles_around.
* #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.
*/
typedef void AyStar_GetNeighbours(AyStar *aystar, OpenListNode *current);
/*
/**
* 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);
/**
* %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 {
/* 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) */
/* These should point to the application specific routines that do the
@@ -115,24 +125,19 @@ struct AyStar {
AyStar_EndNodeCheck *EndNodeCheck;
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.
* user_path should typically contain data about the resulting path
* 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 */
void *user_path;
void *user_target;
uint user_data[10];
/* How many loops are there called before Main() gives
* control back to the caller. 0 = until done */
byte loops_per_tick;
/* 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;
byte loops_per_tick; ///< How many loops are there called before Main() gives 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.
uint max_search_nodes; ///< The maximum number of nodes that will be expanded, 0 = infinite.
/* These should be filled with the neighbours of a tile by
* GetNeighbours */