From aa284fd531a9beee460c6c04a51d3738c2e3a19e Mon Sep 17 00:00:00 2001 From: rubidium Date: Wed, 18 Apr 2007 18:20:31 +0000 Subject: [PATCH] (svn r9670) -Documentation: add documentation to some the _map files. --- src/station_map.cpp | 7 ++- src/tunnel_map.cpp | 19 +++++++ src/unmovable_map.h | 129 ++++++++++++++++++++++++++++++++++++++------ src/void_map.h | 4 ++ 4 files changed, 141 insertions(+), 18 deletions(-) diff --git a/src/station_map.cpp b/src/station_map.cpp index afe9d6ad69..d1552a0820 100644 --- a/src/station_map.cpp +++ b/src/station_map.cpp @@ -6,7 +6,12 @@ #include "openttd.h" #include "station_map.h" - +/** + * Get the station type (rail, airport, truck etc) for the given tile. + * @param t the tile to get the station type of. + * @pre IsTileType(t, MP_STATION) + * @return the station type of the given tile. + */ StationType GetStationType(TileIndex t) { assert(IsTileType(t, MP_STATION)); diff --git a/src/tunnel_map.cpp b/src/tunnel_map.cpp index db5cedaa98..d0788b951b 100644 --- a/src/tunnel_map.cpp +++ b/src/tunnel_map.cpp @@ -7,6 +7,12 @@ #include "tile.h" #include "tunnel_map.h" +/** + * Gets the other end of the tunnel. Where a vehicle would reappear when it + * enters at the given tile. + * @param tile the tile to search from. + * @return the tile of the other end of the tunnel. + */ TileIndex GetOtherTunnelEnd(TileIndex tile) { DiagDirection dir = GetTunnelDirection(tile); @@ -26,6 +32,13 @@ TileIndex GetOtherTunnelEnd(TileIndex tile) } +/** + * Is there a tunnel in the way in the given direction? + * @param tile the tile to search from. + * @param z the 'z' to search on. + * @param dir the direction to start searching to. + * @return true if and only if there is a tunnel. + */ static bool IsTunnelInWayDir(TileIndex tile, uint z, DiagDirection dir) { TileIndexDiff delta = TileOffsByDiagDir(dir); @@ -42,6 +55,12 @@ static bool IsTunnelInWayDir(TileIndex tile, uint z, DiagDirection dir) GetTunnelDirection(tile) == dir; } +/** + * Is there a tunnel in the way in any direction? + * @param tile the tile to search from. + * @param z the 'z' to search on. + * @return true if and only if there is a tunnel. + */ bool IsTunnelInWay(TileIndex tile, uint z) { return diff --git a/src/unmovable_map.h b/src/unmovable_map.h index 256c35717b..0decbf94e4 100644 --- a/src/unmovable_map.h +++ b/src/unmovable_map.h @@ -6,88 +6,152 @@ #define UNMOVABLE_MAP_H enum { - HQ_NUM_TILE = 4, - HQ_NUM_SIZE = 5 + HQ_NUM_TILE = 4, ///< Number of HQ tiles + HQ_NUM_SIZE = 5 ///< Number of stages of an HQ }; +/** Types of unmovable structure */ enum UnmovableType { - UNMOVABLE_TRANSMITTER = 0, - UNMOVABLE_LIGHTHOUSE = 1, - UNMOVABLE_STATUE = 2, - UNMOVABLE_OWNED_LAND = 3, - UNMOVABLE_HQ_NORTH = 0x80, - UNMOVABLE_HQ_WEST = 0x81, - UNMOVABLE_HQ_EAST = 0x82, - UNMOVABLE_HQ_SOUTH = 0x83, + UNMOVABLE_TRANSMITTER = 0, ///< The large antenna + UNMOVABLE_LIGHTHOUSE = 1, ///< The nice lighthouse + UNMOVABLE_STATUE = 2, ///< Statue in towns + UNMOVABLE_OWNED_LAND = 3, ///< Owned land 'flag' + UNMOVABLE_HQ_NORTH = 0x80, ///< Offset for the northern HQ tile + UNMOVABLE_HQ_WEST = 0x81, ///< Offset for the western HQ tile + UNMOVABLE_HQ_EAST = 0x82, ///< Offset for the eastern HQ tile + UNMOVABLE_HQ_SOUTH = 0x83, ///< Offset for the southern HQ tile + /** End of the HQ (rather end + 1 for IS_INT_INSIDE) */ UNMOVABLE_HQ_END = UNMOVABLE_HQ_NORTH + HQ_NUM_SIZE * HQ_NUM_TILE }; +/** + * Gets the UnmovableType of the given unmovable tile + * @param t the tile to get the type from. + * @pre IsTileType(t, MP_UNMOVABLE) + * @return the type. + */ static inline UnmovableType GetUnmovableType(TileIndex t) { assert(IsTileType(t, MP_UNMOVABLE)); return (UnmovableType)_m[t].m5; } - +/** + * Does the given tile have a transmitter? + * @param t the tile to inspect. + * @return true if and only if the tile has a transmitter. + */ static inline bool IsTransmitterTile(TileIndex t) { - return - IsTileType(t, MP_UNMOVABLE) && - GetUnmovableType(t) == UNMOVABLE_TRANSMITTER; + return IsTileType(t, MP_UNMOVABLE) && GetUnmovableType(t) == UNMOVABLE_TRANSMITTER; } - +/** + * Is this unmovable tile an 'owned land' tile? + * @param t the tile to inspect. + * @pre IsTileType(t, MP_UNMOVABLE) + * @return true if and only if the tile is an 'owned land' tile. + */ static inline bool IsOwnedLand(TileIndex t) { assert(IsTileType(t, MP_UNMOVABLE)); return GetUnmovableType(t) == UNMOVABLE_OWNED_LAND; } +/** + * Is the given tile (pre-)owned by someone (the little flags)? + * @param t the tile to inspect. + * @return true if and only if the tile is an 'owned land' tile. + */ static inline bool IsOwnedLandTile(TileIndex t) { return IsTileType(t, MP_UNMOVABLE) && IsOwnedLand(t); } +/** + * Is this unmovable tile a HQ tile? + * @param t the tile to inspect. + * @pre IsTileType(t, MP_UNMOVABLE) + * @return true if and only if the tile is a HQ tile. + */ static inline bool IsCompanyHQ(TileIndex t) { + assert(IsTileType(t, MP_UNMOVABLE)); return IS_INT_INSIDE(GetUnmovableType(t), UNMOVABLE_HQ_NORTH, UNMOVABLE_HQ_END); } +/** + * Is this unmovable tile a statue? + * @param t the tile to inspect. + * @pre IsTileType(t, MP_UNMOVABLE) + * @return true if and only if the tile is a statue. + */ static inline bool IsStatue(TileIndex t) { assert(IsTileType(t, MP_UNMOVABLE)); return GetUnmovableType(t) == UNMOVABLE_STATUE; } +/** + * Is the given tile a statue? + * @param t the tile to inspect. + * @return true if and only if the tile is a statue. + */ static inline bool IsStatueTile(TileIndex t) { return IsTileType(t, MP_UNMOVABLE) && IsStatue(t); } +/** + * Get the town of the given statue tile. + * @param t the tile of the statue. + * @pre IsStatueTile(t) + * @return the town the given statue is in. + */ static inline TownID GetStatueTownID(TileIndex t) { - assert(IsStatue(t)); + assert(IsStatueTile(t)); return _m[t].m2; } +/** + * Get the 'stage' of the HQ. + * @param t a tile of the HQ. + * @pre IsTileType(t, MP_UNMOVABLE) && IsCompanyHQ(t) + * @return the 'stage' of the HQ. + */ static inline byte GetCompanyHQSize(TileIndex t) { assert(IsTileType(t, MP_UNMOVABLE) && IsCompanyHQ(t)); return GB(_m[t].m5, 2, 3); } +/** + * Get the 'section' (including stage) of the HQ. + * @param t a tile of the HQ. + * @pre IsTileType(t, MP_UNMOVABLE) && IsCompanyHQ(t) + * @return the 'section' of the HQ. + */ static inline byte GetCompanyHQSection(TileIndex t) { assert(IsTileType(t, MP_UNMOVABLE) && IsCompanyHQ(t)); return GB(_m[t].m5, 0, 5); } - +/** + * Enlarge the given HQ to the given size. If the new size + * is larger than the current size, nothing happens. + * @param t the tile of the HQ. + * @param size the new size of the HQ. + * @pre t is the northern tile of the HQ + */ static inline void EnlargeCompanyHQ(TileIndex t, byte size) { + assert(GB(GetCompanyHQSection(t), 0, 2) == 0); + size *= 4; if (size <= _m[t].m5 - UNMOVABLE_HQ_NORTH) return; @@ -98,6 +162,13 @@ static inline void EnlargeCompanyHQ(TileIndex t, byte size) } +/** + * Make an Unmovable tile. + * @note do not use this function directly. Use one of the other Make* functions. + * @param t the tile to make unmovable. + * @param u the unmovable type of the tile. + * @param o the new owner of the tile. + */ static inline void MakeUnmovable(TileIndex t, UnmovableType u, Owner o) { SetTileType(t, MP_UNMOVABLE); @@ -109,27 +180,51 @@ static inline void MakeUnmovable(TileIndex t, UnmovableType u, Owner o) } +/** + * Make a transmitter tile. + * @param t the tile to make a transmitter. + */ static inline void MakeTransmitter(TileIndex t) { MakeUnmovable(t, UNMOVABLE_TRANSMITTER, OWNER_NONE); } +/** + * Make a lighthouse tile. + * @param t the tile to make a transmitter. + */ static inline void MakeLighthouse(TileIndex t) { MakeUnmovable(t, UNMOVABLE_LIGHTHOUSE, OWNER_NONE); } +/** + * Make a statue tile. + * @param t the tile to make a statue. + * @param o the owner of the statue. + * @param town_id the town the statue was built in. + */ static inline void MakeStatue(TileIndex t, Owner o, TownID town_id) { MakeUnmovable(t, UNMOVABLE_STATUE, o); _m[t].m2 = town_id; } +/** + * Make an 'owned land' tile. + * @param t the tile to make an 'owned land' tile. + * @param o the owner of the land. + */ static inline void MakeOwnedLand(TileIndex t, Owner o) { MakeUnmovable(t, UNMOVABLE_OWNED_LAND, o); } +/** + * Make an HQ with the give tile as it's northern tile. + * @param t the tile to make the northern tile of a HQ. + * @param o the owner of the HQ. + */ static inline void MakeCompanyHQ(TileIndex t, Owner o) { MakeUnmovable(t + TileDiffXY(0, 0), UNMOVABLE_HQ_NORTH, o); diff --git a/src/void_map.h b/src/void_map.h index a5a14684bb..aae2848214 100644 --- a/src/void_map.h +++ b/src/void_map.h @@ -5,6 +5,10 @@ #ifndef VOID_MAP_H #define VOID_MAP_H +/** + * Make a nice void tile ;) + * @param t the tile to make void + */ static inline void MakeVoid(TileIndex t) { SetTileType(t, MP_VOID);