From 4df90cddee54ca1fa8c76caf3c14a7194d24dd07 Mon Sep 17 00:00:00 2001 From: yexo Date: Tue, 26 Jan 2010 23:25:28 +0000 Subject: (svn r18922) -Doc: add doxygen documentation to all functions in station_map.h --- src/station_map.h | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 185 insertions(+), 7 deletions(-) (limited to 'src/station_map.h') diff --git a/src/station_map.h b/src/station_map.h index 55d5c4139..35b5c55c8 100644 --- a/src/station_map.h +++ b/src/station_map.h @@ -18,12 +18,14 @@ #include "station_func.h" #include "rail.h" -typedef byte StationGfx; +typedef byte StationGfx; ///< Index of station graphics. @see _station_display_datas -/** Get Station ID from a tile - * @pre Tile \t must be part of the station +/** + * Get StationID from a tile * @param t Tile to query station ID from - * @return Station ID of the station at \a t */ + * @pre IsTileType(t, MP_STATION) + * @return Station ID of the station at \a t + */ static inline StationID GetStationIndex(TileIndex t) { assert(IsTileType(t, MP_STATION)); @@ -277,54 +279,116 @@ static inline DiagDirection GetRoadStopDir(TileIndex t) } } +/** + * Is tile \a t part of an oilrig? + * @param t Tile to check + * @pre IsTileType(t, MP_STATION) + * @return \c true if the tile is an oilrig tile + */ static inline bool IsOilRig(TileIndex t) { return GetStationType(t) == STATION_OILRIG; } +/** + * Is tile \a t a dock tile? + * @param t Tile to check + * @pre IsTileType(t, MP_STATION) + * @return \c true if the tile is a dock + */ static inline bool IsDock(TileIndex t) { return GetStationType(t) == STATION_DOCK; } +/** + * Is tile \a t a dock tile? + * @param t Tile to check + * @return \c true if the tile is a dock + */ static inline bool IsDockTile(TileIndex t) { return IsTileType(t, MP_STATION) && GetStationType(t) == STATION_DOCK; } +/** + * Is tile \a t a buoy tile? + * @param t Tile to check + * @pre IsTileType(t, MP_STATION) + * @return \c true if the tile is a buoy + */ static inline bool IsBuoy(TileIndex t) { return GetStationType(t) == STATION_BUOY; } +/** + * Is tile \a t a buoy tile? + * @param t Tile to check + * @return \c true if the tile is a buoy + */ static inline bool IsBuoyTile(TileIndex t) { return IsTileType(t, MP_STATION) && IsBuoy(t); } +/** + * Is tile \a t an hangar tile? + * @param t Tile to check + * @return \c true if the tile is an hangar + */ static inline bool IsHangarTile(TileIndex t) { return IsTileType(t, MP_STATION) && IsHangar(t); } - +/** + * Get the rail direction of a rail station. + * @param t Tile to query + * @pre HasStationRail(t) + * @return The direction of the rails on tile \a t. + */ static inline Axis GetRailStationAxis(TileIndex t) { assert(HasStationRail(t)); return HasBit(GetStationGfx(t), 0) ? AXIS_Y : AXIS_X; } - +/** + * Get the rail track of a rail station tile. + * @param t Tile to query + * @pre HasStationRail(t) + * @return The rail track of the rails on tile \a t. + */ static inline Track GetRailStationTrack(TileIndex t) { return AxisToTrack(GetRailStationAxis(t)); } +/** + * Get the trackbits of a rail station tile. + * @param t Tile to query + * @pre HasStationRail(t) + * @return The trackbits of the rails on tile \a t. + */ static inline TrackBits GetRailStationTrackBits(TileIndex t) { return AxisToTrackBits(GetRailStationAxis(t)); } +/** + * Check if tile is compatible with a railstation tile. The two tiles + * are compatible if all of the following are true: + * \li both tiles are rail station tiles + * \li the railtype of \a t1 is compatible with the railtype of \a t2 + * \li the tracks on \a t1 and \a t2 are in the same direction + * \li both tiles belong to the same station + * \li \a t1 is not blocked (@see IsStationTileBlocked) + * @param t1 First tile to compare + * @param t2 Second tile to compare + * @pre IsRailStationTile(t2) + * @return true if the two tiles are compatible + */ static inline bool IsCompatibleTrainStationTile(TileIndex t1, TileIndex t2) { assert(IsRailStationTile(t2)); @@ -371,7 +435,13 @@ static inline TrackBits GetStationReservationTrackBits(TileIndex t) return HasStationReservation(t) ? GetRailStationTrackBits(t) : TRACK_BIT_NONE; } - +/** + * Get the direction of a dock. + * @param t Tile to query + * @pre IsDock(t) + * @pre \a t is the land part of the dock + * @return The direction of the dock on tile \a t. + */ static inline DiagDirection GetDockDirection(TileIndex t) { StationGfx gfx = GetStationGfx(t); @@ -379,6 +449,13 @@ static inline DiagDirection GetDockDirection(TileIndex t) return (DiagDirection)(gfx); } +/** + * Get the tileoffset from this tile a ship should target to get to this dock. + * @param t Tile to query + * @pre IsTileType(t, MP_STATION) + * @pre IsBuoy(t) || IsOilRig(t) || IsDock(t) + * @return The offset from this tile that should be used as destination for ships. + */ static inline TileIndexDiffC GetDockOffset(TileIndex t) { static const TileIndexDiffC buoy_offset = {0, 0}; @@ -399,36 +476,72 @@ static inline TileIndexDiffC GetDockOffset(TileIndex t) return dock_offset[GetDockDirection(t)]; } +/** + * Is there a custom rail station spec on this tile? + * @param t Tile to query + * @pre HasStationTileRail(t) + * @return True if this station is part of a newgrf station. + */ static inline bool IsCustomStationSpecIndex(TileIndex t) { assert(HasStationTileRail(t)); return _m[t].m4 != 0; } +/** + * Set the custom station spec for this tile. + * @param t Tile to set the stationspec of. + * @pre HasStationTileRail(t) + */ static inline void SetCustomStationSpecIndex(TileIndex t, byte specindex) { assert(HasStationTileRail(t)); _m[t].m4 = specindex; } +/** + * Get the custom station spec for this tile. + * @param t Tile to query + * @pre HasStationTileRail(t) + * @return The custom station spec of this tile. + */ static inline uint GetCustomStationSpecIndex(TileIndex t) { assert(HasStationTileRail(t)); return _m[t].m4; } +/** + * Set the random bits for a station tile. + * @param t Tile to set random bits for + * @pre IsTileType(t, MP_STATION) + */ static inline void SetStationTileRandomBits(TileIndex t, byte random_bits) { assert(IsTileType(t, MP_STATION)); SB(_m[t].m3, 4, 4, random_bits); } +/** + * Get the random bits of a station tile. + * @param t Tile to query + * @pre IsTileType(t, MP_STATION) + * @return The random bits for this station tile. + */ static inline byte GetStationTileRandomBits(TileIndex t) { assert(IsTileType(t, MP_STATION)); return GB(_m[t].m3, 4, 4); } +/** + * Make the given tile a station tile. + * @param t the tile to make a station tile + * @param o the owner of the station + * @param sid the station to which this tile belongs + * @param st the type this station tile + * @param section the StationGfx to be used for this tile + */ static inline void MakeStation(TileIndex t, Owner o, StationID sid, StationType st, byte section) { SetTileType(t, MP_STATION); @@ -442,6 +555,15 @@ static inline void MakeStation(TileIndex t, Owner o, StationID sid, StationType _me[t].m7 = 0; } +/** + * Make the given tile a rail station tile. + * @param t the tile to make a rail station tile + * @param o the owner of the station + * @param sid the station to which this tile belongs + * @param a the axis of this tile + * @param section the StationGfx to be used for this tile + * @param rt the railtype of this tile + */ static inline void MakeRailStation(TileIndex t, Owner o, StationID sid, Axis a, byte section, RailType rt) { MakeStation(t, o, sid, STATION_RAIL, section + a); @@ -449,6 +571,15 @@ static inline void MakeRailStation(TileIndex t, Owner o, StationID sid, Axis a, SetRailStationReservation(t, false); } +/** + * Make the given tile a rail waypoint tile. + * @param t the tile to make a rail waypoint + * @param o the owner of the waypoint + * @param sid the waypoint to which this tile belongs + * @param a the axis of this tile + * @param section the StationGfx to be used for this tile + * @param rt the railtype of this tile + */ static inline void MakeRailWaypoint(TileIndex t, Owner o, StationID sid, Axis a, byte section, RailType rt) { MakeStation(t, o, sid, STATION_WAYPOINT, section + a); @@ -456,6 +587,15 @@ static inline void MakeRailWaypoint(TileIndex t, Owner o, StationID sid, Axis a, SetRailStationReservation(t, false); } +/** + * Make the given tile a roadstop tile. + * @param t the tile to make a roadstop + * @param o the owner of the roadstop + * @param sid the station to which this tile belongs + * @param rst the type of roadstop to make this tile + * @param rt the roadtypes on this tile + * @param d the direction of the roadstop + */ static inline void MakeRoadStop(TileIndex t, Owner o, StationID sid, RoadStopType rst, RoadTypes rt, DiagDirection d) { MakeStation(t, o, sid, (rst == ROADSTOP_BUS ? STATION_BUS : STATION_TRUCK), d); @@ -464,6 +604,17 @@ static inline void MakeRoadStop(TileIndex t, Owner o, StationID sid, RoadStopTyp SetRoadOwner(t, ROADTYPE_TRAM, o); } +/** + * Make the given tile a drivethrough roadstop tile. + * @param t the tile to make a roadstop + * @param station the owner of the roadstop + * @param road the owner of the road + * @param tram the owner of the tram + * @param sid the station to which this tile belongs + * @param rst the type of roadstop to make this tile + * @param rt the roadtypes on this tile + * @param d the direction of the roadstop + */ static inline void MakeDriveThroughRoadStop(TileIndex t, Owner station, Owner road, Owner tram, StationID sid, RoadStopType rst, RoadTypes rt, Axis a) { MakeStation(t, station, sid, (rst == ROADSTOP_BUS ? STATION_BUS : STATION_TRUCK), GFX_TRUCK_BUS_DRIVETHROUGH_OFFSET + a); @@ -472,11 +623,24 @@ static inline void MakeDriveThroughRoadStop(TileIndex t, Owner station, Owner ro SetRoadOwner(t, ROADTYPE_TRAM, tram); } +/** + * Make the given tile an airport tile. + * @param t the tile to make a airport + * @param o the owner of the airport + * @param sid the station to which this tile belongs + * @param section the StationGfx to be used for this tile + */ static inline void MakeAirport(TileIndex t, Owner o, StationID sid, byte section) { MakeStation(t, o, sid, STATION_AIRPORT, section); } +/** + * Make the given tile a buoy tile. + * @param t the tile to make a buoy + * @param sid the station to which this tile belongs + * @param wc the type of water on this tile + */ static inline void MakeBuoy(TileIndex t, StationID sid, WaterClass wc) { /* Make the owner of the buoy tile the same as the current owner of the @@ -486,6 +650,14 @@ static inline void MakeBuoy(TileIndex t, StationID sid, WaterClass wc) SetWaterClass(t, wc); } +/** + * Make the given tile a dock tile. + * @param t the tile to make a dock + * @param o the owner of the dock + * @param sid the station to which this tile belongs + * @param d the direction of the dock + * @param wc the type of water on this tile + */ static inline void MakeDock(TileIndex t, Owner o, StationID sid, DiagDirection d, WaterClass wc) { MakeStation(t, o, sid, STATION_DOCK, d); @@ -493,6 +665,12 @@ static inline void MakeDock(TileIndex t, Owner o, StationID sid, DiagDirection d SetWaterClass(t + TileOffsByDiagDir(d), wc); } +/** + * Make the given tile an oilrig tile. + * @param t the tile to make an oilrig + * @param sid the station to which this tile belongs + * @param wc the type of water on this tile + */ static inline void MakeOilrig(TileIndex t, StationID sid, WaterClass wc) { MakeStation(t, OWNER_NONE, sid, STATION_OILRIG, 0); -- cgit v1.2.3-54-g00ecf