From af9f81b6a8c1b23031341237f5a5cfdd3930f81e Mon Sep 17 00:00:00 2001 From: KUDr Date: Mon, 29 May 2006 18:39:42 +0000 Subject: (svn r5018) [YAPF] Added some comments to YAPF implementation. --- yapf/unittest/test_yapf.h | 15 +++++++++-- yapf/yapf_base.hpp | 33 +++++++++++++----------- yapf/yapf_common.hpp | 66 ++++++++++++++++++++++++++++++----------------- yapf/yapf_costcache.hpp | 29 ++++++++++++++++----- yapf/yapf_costrail.hpp | 8 ++++-- yapf/yapf_destrail.hpp | 16 +++++++++--- yapf/yapf_rail.cpp | 22 +++++++++++----- yapf/yapf_road.cpp | 39 ++++++++++++++++++++-------- yapf/yapf_ship.cpp | 19 ++++++++++---- 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 CYapfNode2; template 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(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 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(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 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(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 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(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 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(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 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 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 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 LocalCache; @@ -43,9 +47,12 @@ public: protected: LocalCache m_local_cache; + /// to access inherited path finder FORCEINLINE Tpf& Yapf() {return *static_cast(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 struct CSegmentCostCacheT : public CSegmentCostCacheBase @@ -116,7 +128,7 @@ class CYapfSegmentCostCacheGlobalT { public: typedef CYapfSegmentCostCacheLocalT 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(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(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(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(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 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(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 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(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 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(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 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(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 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(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 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(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 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(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 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(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 -- cgit v1.2.3-54-g00ecf