summaryrefslogtreecommitdiff
path: root/yapf
diff options
context:
space:
mode:
authorKUDr <kudr@openttd.org>2006-05-29 18:39:42 +0000
committerKUDr <kudr@openttd.org>2006-05-29 18:39:42 +0000
commited48b38619492a4018ac014d203718db689f69b2 (patch)
treecca7f9d507723ce078f410649f6ba598ccdb0523 /yapf
parent301f4ac856088ac32f89b791479fbb0dfb4f911b (diff)
downloadopenttd-ed48b38619492a4018ac014d203718db689f69b2.tar.xz
(svn r5018) [YAPF] Added some comments to YAPF implementation.
Diffstat (limited to 'yapf')
-rw-r--r--yapf/unittest/test_yapf.h15
-rw-r--r--yapf/yapf_base.hpp33
-rw-r--r--yapf/yapf_common.hpp66
-rw-r--r--yapf/yapf_costcache.hpp29
-rw-r--r--yapf/yapf_costrail.hpp8
-rw-r--r--yapf/yapf_destrail.hpp16
-rw-r--r--yapf/yapf_rail.cpp22
-rw-r--r--yapf/yapf_road.cpp39
-rw-r--r--yapf/yapf_ship.cpp19
9 files changed, 172 insertions, 75 deletions
diff --git a/yapf/unittest/test_yapf.h b/yapf/unittest/test_yapf.h
index ca4b21de0..558ea4667 100644
--- a/yapf/unittest/test_yapf.h
+++ b/yapf/unittest/test_yapf.h
@@ -132,9 +132,9 @@ typedef CTestYapfNodeT<CNodeKey2> CYapfNode2;
template <class Types>
struct CYapfTestBaseT
{
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
typedef typename Types::Map Map;
int m_x1, m_y1;
@@ -155,9 +155,13 @@ struct CYapfTestBaseT
m_td1 = td1;
}
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
FORCEINLINE char TransportTypeChar() const {return 'T';}
+ /** Called by YAPF to move from the given node to the next tile. For each
+ * reachable trackdir on the new tile creates new node, initializes it
+ * and adds it to the open list by calling Yapf().AddNewNode(n) */
FORCEINLINE void PfFollowNode(Node& org)
{
int x_org = org.m_key.m_x;
@@ -191,6 +195,7 @@ struct CYapfTestBaseT
}
}
+ /// Called when YAPF needs to place origin nodes into open list
FORCEINLINE void PfSetStartupNodes()
{
Node& n1 = Yapf().CreateNewNode();
@@ -201,6 +206,9 @@ struct CYapfTestBaseT
Yapf().AddStartupNode(n1);
}
+ /** Called by YAPF to calculate the cost from the origin to the given node.
+ * Calculates only the cost of given node, adds it to the parent node cost
+ * and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n)
{
// base tile cost depending on distance
@@ -216,6 +224,8 @@ struct CYapfTestBaseT
return true;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
int dx = abs(n.m_key.m_x - m_x2);
@@ -227,6 +237,7 @@ struct CYapfTestBaseT
return true;
}
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest = (n.m_key.m_x == m_x2) && (n.m_key.m_y == m_y2);
diff --git a/yapf/yapf_base.hpp b/yapf/yapf_base.hpp
index c504fc468..04eefb885 100644
--- a/yapf/yapf_base.hpp
+++ b/yapf/yapf_base.hpp
@@ -45,34 +45,34 @@ extern int _total_pf_time_us;
template <class Types>
class CYapfBaseT {
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList NodeList; ///< our node list
typedef typename NodeList::Titem Node; ///< this will be our node type
typedef typename Node::Key Key; ///< key to hash tables
- NodeList m_nodes; ///< node list multi-container
+ NodeList m_nodes; ///< node list multi-container
protected:
- Node* m_pBestDestNode; ///< pointer to the destination node found at last round
- Node* m_pBestIntermediateNode;
- const YapfSettings *m_settings;
- int m_max_search_nodes;
- Vehicle* m_veh;
+ Node* m_pBestDestNode; ///< pointer to the destination node found at last round
+ Node* m_pBestIntermediateNode; ///< here should be node closest to the destination if path not found
+ const YapfSettings *m_settings; ///< current settings (_patches.yapf)
+ int m_max_search_nodes; ///< maximum number of nodes we are allowed to visit before we give up
+ Vehicle* m_veh; ///< vehicle that we are trying to drive
- int m_stats_cost_calcs;
- int m_stats_cache_hits;
+ int m_stats_cost_calcs; ///< stats - how many node's costs were calculated
+ int m_stats_cache_hits; ///< stats - how many node's costs were reused from cache
public:
- CPerformanceTimer m_perf_cost;
- CPerformanceTimer m_perf_slope_cost;
- CPerformanceTimer m_perf_ts_cost;
- CPerformanceTimer m_perf_other_cost;
+ CPerformanceTimer m_perf_cost; ///< stats - total CPU time of this run
+ CPerformanceTimer m_perf_slope_cost; ///< stats - slope calculation CPU time
+ CPerformanceTimer m_perf_ts_cost; ///< stats - GetTrackStatus() CPU time
+ CPerformanceTimer m_perf_other_cost; ///< stats - other CPU time
public:
- int m_num_steps; ///< this is there for debugging purposes (hope it doesn't hurt)
+ int m_num_steps; ///< this is there for debugging purposes (hope it doesn't hurt)
public:
- // default constructor
+ /// default constructor
FORCEINLINE CYapfBaseT()
: m_pBestDestNode(NULL)
, m_pBestIntermediateNode(NULL)
@@ -90,12 +90,15 @@ public:
{
}
+ /// default destructor
~CYapfBaseT() {}
protected:
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /// return current settings (can be custom - player based - but later)
FORCEINLINE const YapfSettings& PfGetSettings() const
{
return *m_settings;
diff --git a/yapf/yapf_common.hpp b/yapf/yapf_common.hpp
index e4d937a57..127c73210 100644
--- a/yapf/yapf_common.hpp
+++ b/yapf/yapf_common.hpp
@@ -3,28 +3,31 @@
#ifndef YAPF_COMMON_HPP
#define YAPF_COMMON_HPP
-
+/** YAPF origin provider base class - used when origin is one tile / multiple trackdirs */
template <class Types>
class CYapfOriginTileT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
- TileIndex m_orgTile;
- TrackdirBits m_orgTrackdirs;
+ TileIndex m_orgTile; ///< origin tile
+ TrackdirBits m_orgTrackdirs; ///< origin trackdir mask
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /// Set origin tile / trackdir mask
void SetOrigin(TileIndex tile, TrackdirBits trackdirs)
{
m_orgTile = tile;
m_orgTrackdirs = trackdirs;
}
+ /// Called when YAPF needs to place origin nodes into open list
void PfSetStartupNodes()
{
for (TrackdirBits tdb = m_orgTrackdirs; tdb != TRACKDIR_BIT_NONE; tdb = (TrackdirBits)KillFirstBit2x64(tdb)) {
@@ -36,25 +39,28 @@ public:
}
};
+/** YAPF origin provider base class - used when there are two tile/trackdir origins */
template <class Types>
class CYapfOriginTileTwoWayT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
- TileIndex m_orgTile;
- Trackdir m_orgTd;
- TileIndex m_revTile;
- Trackdir m_revTd;
- int m_reverse_penalty;
- bool m_treat_first_red_two_way_signal_as_eol;
-
+ TileIndex m_orgTile; ///< first origin tile
+ Trackdir m_orgTd; ///< first origin trackdir
+ TileIndex m_revTile; ///< second (reversed) origin tile
+ Trackdir m_revTd; ///< second (reversed) origin trackdir
+ int m_reverse_penalty; ///< penalty to be added for using the reversed origin
+ bool m_treat_first_red_two_way_signal_as_eol; ///< in some cases (leaving station) we need to handle first two-way signal differently
+
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /// set origin (tiles, trackdirs, etc.)
void SetOrigin(TileIndex tile, Trackdir td, TileIndex tiler = INVALID_TILE, Trackdir tdr = INVALID_TRACKDIR, int reverse_penalty = 0, bool treat_first_red_two_way_signal_as_eol = true)
{
m_orgTile = tile;
@@ -65,6 +71,7 @@ public:
m_treat_first_red_two_way_signal_as_eol = treat_first_red_two_way_signal_as_eol;
}
+ /// Called when YAPF needs to place origin nodes into open list
void PfSetStartupNodes()
{
if (m_orgTile != INVALID_TILE && m_orgTd != INVALID_TRACKDIR) {
@@ -80,25 +87,28 @@ public:
}
}
+ /// return true if first two-way signal should be treated as dead end
FORCEINLINE bool TreatFirstRedTwoWaySignalAsEOL()
{
return Yapf().PfGetSettings().rail_firstred_twoway_eol && m_treat_first_red_two_way_signal_as_eol;
}
};
+/** YAPF destination provider base class - used when destination is single tile / multiple trackdirs */
template <class Types>
class CYapfDestinationTileT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
- TileIndex m_destTile;
- TrackdirBits m_destTrackdirs;
+ TileIndex m_destTile; ///< destination tile
+ TrackdirBits m_destTrackdirs; ///< destination trackdir mask
public:
+ /// set the destination tile / more trackdirs
void SetDestination(TileIndex tile, TrackdirBits trackdirs)
{
m_destTile = tile;
@@ -106,15 +116,19 @@ public:
}
protected:
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest = (n.m_key.m_tile == m_destTile) && ((m_destTrackdirs & TrackdirToTrackdirBits(n.GetTrackdir())) != TRACKDIR_BIT_NONE);
return bDest;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
inline bool PfCalcEstimate(Node& n)
{
int dx = abs(TileX(n.GetTile()) - TileX(m_destTile));
@@ -128,14 +142,18 @@ public:
}
};
+/** YAPF template that uses Ttypes template argument to determine all YAPF
+* components (base classes) from which the actual YAPF is composed.
+* For example classes consult: CYapfRail_TypesT template and its instantiations:
+* CYapfRail1, CYapfRail2, CYapfRail3, CYapfAnyDepotRail1, CYapfAnyDepotRail2, CYapfAnyDepotRail3 */
template <class Ttypes>
class CYapfT
- : public Ttypes::PfBase
- , public Ttypes::PfCost
- , public Ttypes::PfCache
- , public Ttypes::PfOrigin
- , public Ttypes::PfDestination
- , public Ttypes::PfFollow
+ : public Ttypes::PfBase ///< Instance of CYapfBaseT - main YAPF loop and support base class
+ , public Ttypes::PfCost ///< Cost calculation provider base class
+ , public Ttypes::PfCache ///< Segment cost cache provider
+ , public Ttypes::PfOrigin ///< Origin (tile or two-tile origin)
+ , public Ttypes::PfDestination ///< Destination detector and distance (estimate) calculation provider
+ , public Ttypes::PfFollow ///< Node follower (stepping provider)
{
};
diff --git a/yapf/yapf_costcache.hpp b/yapf/yapf_costcache.hpp
index 4947e6cef..ee4029e0c 100644
--- a/yapf/yapf_costcache.hpp
+++ b/yapf/yapf_costcache.hpp
@@ -11,14 +11,18 @@ template <class Types>
class CYapfSegmentCostCacheNoneT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ /** Called by YAPF to attach cached or local segment cost data to the given node.
+ * @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
return false;
};
+ /** Called by YAPF to flush the cached segment cost data back into cache storage.
+ * Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{
};
@@ -33,9 +37,9 @@ template <class Types>
class CYapfSegmentCostCacheLocalT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
typedef typename Node::CachedData CachedData;
typedef typename CachedData::Key CacheKey;
typedef CArrayT<CachedData> LocalCache;
@@ -43,9 +47,12 @@ public:
protected:
LocalCache m_local_cache;
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to attach cached or local segment cost data to the given node.
+ * @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
CacheKey key(n.GetKey());
@@ -53,13 +60,19 @@ public:
return false;
};
+ /** Called by YAPF to flush the cached segment cost data back into cache storage.
+ * Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{
};
};
-
+/** Base class for segment cost cache providers. Contains global counter
+* of track layout changes and static notification function called whenever
+* the track layout changes. It is implemented as base class because it needs
+* to be shared between all rail YAPF types (one shared counter, one notification
+* function. */
struct CSegmentCostCacheBase
{
static int s_rail_change_counter;
@@ -76,7 +89,6 @@ struct CSegmentCostCacheBase
of the segment (origin tile and exit-dir from this tile).
Different CYapfCachedCostT types can share the same type of CSegmentCostCacheT.
Look at CYapfRailSegment (yapf_node_rail.hpp) for the segment example */
-
template <class Tsegment>
struct CSegmentCostCacheT
: public CSegmentCostCacheBase
@@ -116,7 +128,7 @@ class CYapfSegmentCostCacheGlobalT
{
public:
typedef CYapfSegmentCostCacheLocalT<Types> Tlocal;
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
typedef typename Node::Key Key; ///< key to hash tables
typedef typename Node::CachedData CachedData;
@@ -128,6 +140,7 @@ protected:
FORCEINLINE CYapfSegmentCostCacheGlobalT() : m_global_cache(stGetGlobalCache()) {};
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
FORCEINLINE static Cache*& stGlobalCachePtr() {static Cache* pC = NULL; return pC;}
@@ -159,6 +172,8 @@ protected:
}
public:
+ /** Called by YAPF to attach cached or local segment cost data to the given node.
+ * @return true if globally cached data were used or false if local data was used */
FORCEINLINE bool PfNodeCacheFetch(Node& n)
{
if (!Yapf().CanUseGlobalCache(n)) {
@@ -171,6 +186,8 @@ public:
return found;
};
+ /** Called by YAPF to flush the cached segment cost data back into cache storage.
+ * Current cache implementation doesn't use that. */
FORCEINLINE void PfNodeCacheFlush(Node& n)
{
};
diff --git a/yapf/yapf_costrail.hpp b/yapf/yapf_costrail.hpp
index 3c01e47d0..d8ebe3f5e 100644
--- a/yapf/yapf_costrail.hpp
+++ b/yapf/yapf_costrail.hpp
@@ -10,10 +10,10 @@ class CYapfCostRailT
, public CostRailSettings
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
typedef typename Node::CachedData CachedData;
protected:
@@ -33,6 +33,7 @@ protected:
pen[i] = p0 + i * (p1 + i * p2);
}
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
@@ -140,6 +141,9 @@ public:
public:
FORCEINLINE void SetMaxCost(int max_cost) {m_max_cost = max_cost;}
+ /** Called by YAPF to calculate the cost from the origin to the given node.
+ * Calculates only the cost of given node, adds it to the parent node cost
+ * and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n)
{
assert(!n.flags_u.flags_s.m_targed_seen);
diff --git a/yapf/yapf_destrail.hpp b/yapf/yapf_destrail.hpp
index a0e3e922d..c7b3a63a0 100644
--- a/yapf/yapf_destrail.hpp
+++ b/yapf/yapf_destrail.hpp
@@ -25,18 +25,22 @@ class CYapfDestinationAnyDepotRailT
: public CYapfDestinationRailBase
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest = IsTileDepotType(n.GetLastTile(), TRANSPORT_RAIL);
return bDest;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
n.m_estimate = n.m_cost;
@@ -49,15 +53,16 @@ class CYapfDestinationTileOrStationRailT
: public CYapfDestinationRailBase
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
TileIndex m_destTile;
TrackdirBits m_destTrackdirs;
StationID m_dest_station_id;
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
static TileIndex CalcStationCenterTile(StationID station)
@@ -85,6 +90,7 @@ public:
CYapfDestinationRailBase::SetDestination(v);
}
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest;
@@ -99,6 +105,8 @@ public:
return bDest;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
static int dg_dir_to_x_offs[] = {-1, 0, 1, 0};
diff --git a/yapf/yapf_rail.cpp b/yapf/yapf_rail.cpp
index 67d3d781f..7f0b11e27 100644
--- a/yapf/yapf_rail.cpp
+++ b/yapf/yapf_rail.cpp
@@ -17,15 +17,19 @@ template <class Types>
class CYapfFollowAnyDepotRailT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to move from the given node to the next tile. For each
+ * reachable trackdir on the new tile creates new node, initializes it
+ * and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
{
TrackFollower F(Yapf().GetVehicle());
@@ -33,6 +37,7 @@ public:
Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
}
+ /// return debug report character to identify the transportation type
FORCEINLINE char TransportTypeChar() const {return 't';}
static bool stFindNearestDepotTwoWay(Vehicle *v, TileIndex t1, Trackdir td1, TileIndex t2, Trackdir td2, int max_distance, int reverse_penalty, TileIndex* depot_tile, bool* reversed)
@@ -75,15 +80,19 @@ template <class Types>
class CYapfFollowRailT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to move from the given node to the next tile. For each
+ * reachable trackdir on the new tile creates new node, initializes it
+ * and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
{
TrackFollower F(Yapf().GetVehicle());
@@ -91,6 +100,7 @@ public:
Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
}
+ /// return debug report character to identify the transportation type
FORCEINLINE char TransportTypeChar() const {return 't';}
static Trackdir stChooseRailTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackdirBits trackdirs)
diff --git a/yapf/yapf_road.cpp b/yapf/yapf_road.cpp
index dd3529aff..7dee8ab3a 100644
--- a/yapf/yapf_road.cpp
+++ b/yapf/yapf_road.cpp
@@ -10,12 +10,13 @@ template <class Types>
class CYapfCostRoadT
{
public:
- typedef typename Types::Tpf Tpf;
- typedef typename Types::TrackFollower TrackFollower;
+ typedef typename Types::Tpf Tpf; ///< pathfinder (derived from THIS class)
+ typedef typename Types::TrackFollower TrackFollower; ///< track follower helper
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
int SlopeCost(TileIndex tile, TileIndex next_tile, Trackdir trackdir)
@@ -62,6 +63,9 @@ protected:
}
public:
+ /** Called by YAPF to calculate the cost from the origin to the given node.
+ * Calculates only the cost of given node, adds it to the parent node cost
+ * and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n)
{
int segment_cost = 0;
@@ -118,19 +122,23 @@ template <class Types>
class CYapfDestinationAnyDepotRoadT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest = IsTileDepotType(n.m_segment_last_tile, TRANSPORT_ROAD);
return bDest;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
FORCEINLINE bool PfCalcEstimate(Node& n)
{
n.m_estimate = n.m_cost;
@@ -143,10 +151,10 @@ template <class Types>
class CYapfDestinationTileRoadT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
TileIndex m_destTile;
@@ -160,15 +168,19 @@ public:
}
protected:
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /// Called by YAPF to detect if node ends in the desired destination
FORCEINLINE bool PfDetectDestination(Node& n)
{
bool bDest = (n.m_segment_last_tile == m_destTile) && ((m_destTrackdirs & TrackdirToTrackdirBits(n.m_segment_last_td)) != TRACKDIR_BIT_NONE);
return bDest;
}
+ /** Called by YAPF to calculate cost estimate. Calculates distance to the destination
+ * adds it to the actual cost from origin and stores the sum to the Node::m_estimate */
inline bool PfCalcEstimate(Node& n)
{
static int dg_dir_to_x_offs[] = {-1, 0, 1, 0};
@@ -201,16 +213,20 @@ template <class Types>
class CYapfFollowRoadT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to move from the given node to the next tile. For each
+ * reachable trackdir on the new tile creates new node, initializes it
+ * and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
{
TrackFollower F;
@@ -218,6 +234,7 @@ public:
Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
}
+ /// return debug report character to identify the transportation type
FORCEINLINE char TransportTypeChar() const {return 'r';}
static Trackdir stChooseRoadTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir)
diff --git a/yapf/yapf_ship.cpp b/yapf/yapf_ship.cpp
index c19f6bbdd..86d20c9f1 100644
--- a/yapf/yapf_ship.cpp
+++ b/yapf/yapf_ship.cpp
@@ -9,15 +9,19 @@ template <class Types>
class CYapfFollowShipT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::TrackFollower TrackFollower;
- typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Types::NodeList::Titem Node; ///< this will be our node type
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
FORCEINLINE Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to move from the given node to the next tile. For each
+ * reachable trackdir on the new tile creates new node, initializes it
+ * and adds it to the open list by calling Yapf().AddNewNode(n) */
inline void PfFollowNode(Node& old_node)
{
TrackFollower F;
@@ -25,6 +29,7 @@ public:
Yapf().AddMultipleNodes(&old_node, F.m_new_tile, F.m_new_td_bits);
}
+ /// return debug report character to identify the transportation type
FORCEINLINE char TransportTypeChar() const {return 'w';}
static Trackdir ChooseShipTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks)
@@ -80,14 +85,18 @@ template <class Types>
class CYapfCostShipT
{
public:
- typedef typename Types::Tpf Tpf;
+ typedef typename Types::Tpf Tpf; ///< the pathfinder class (derived from THIS class)
typedef typename Types::NodeList::Titem Node; ///< this will be our node type
- typedef typename Node::Key Key; ///< key to hash tables
+ typedef typename Node::Key Key; ///< key to hash tables
protected:
+ /// to access inherited path finder
Tpf& Yapf() {return *static_cast<Tpf*>(this);}
public:
+ /** Called by YAPF to calculate the cost from the origin to the given node.
+ * Calculates only the cost of given node, adds it to the parent node cost
+ * and stores the result into Node::m_cost member */
FORCEINLINE bool PfCalcCost(Node& n)
{
// base tile cost depending on distance