(svn r9554) -Documentation: add documentation to some map accessors.

This commit is contained in:
rubidium 2007-04-03 21:51:40 +00:00
parent d2634aaeec
commit a403f32e59
7 changed files with 259 additions and 24 deletions

View File

@ -1,10 +1,11 @@
/* $Id$ */
/** @file bridge_map.cpp */
/** @file bridge_map.cpp Map accessor functions for bridges. */
#include "stdafx.h"
#include "openttd.h"
#include "bridge_map.h"
#include "bridge.h"
#include "variables.h"

View File

@ -1,6 +1,6 @@
/* $Id$ */
/** @file bridge_map.h */
/** @file bridge_map.h Map accessor functions for bridges. */
#ifndef BRIDGE_MAP_H
#define BRIDGE_MAP_H
@ -55,6 +55,7 @@ static inline bool MayHaveBridgeAbove(TileIndex t)
/**
* checks if a bridge is set above the ground of this tile
* @param t The tile to analyze
* @pre MayHaveBridgeAbove(t)
* @return true if a bridge is detected above
*/
static inline bool IsBridgeAbove(TileIndex t)
@ -67,6 +68,7 @@ static inline bool IsBridgeAbove(TileIndex t)
/**
* Determines the type of bridge on a tile
* @param t The tile to analyze
* @pre IsBridgeTile(t)
* @return The bridge type
*/
static inline uint GetBridgeType(TileIndex t)
@ -79,6 +81,7 @@ static inline uint GetBridgeType(TileIndex t)
/**
* Get the direction pointing onto the bridge
* @param t The tile to analyze
* @pre IsBridgeTile(t)
* @return the above mentionned direction
*/
static inline DiagDirection GetBridgeRampDirection(TileIndex t)
@ -88,6 +91,12 @@ static inline DiagDirection GetBridgeRampDirection(TileIndex t)
}
/**
* Get the axis of the bridge that goes over the tile. Not the axis or the ramp.
* @param t The tile to analyze
* @pre IsBridgeAbove(t)
* @return the above mentioned axis
*/
static inline Axis GetBridgeAxis(TileIndex t)
{
assert(IsBridgeAbove(t));
@ -95,6 +104,12 @@ static inline Axis GetBridgeAxis(TileIndex t)
}
/**
* Get the transport type of the bridge's ramp.
* @param t The ramp tile to analyze
* @pre IsBridgeTile(t)
* @return the transport type of the bridge
*/
static inline TransportType GetBridgeTransportType(TileIndex t)
{
assert(IsBridgeTile(t));
@ -102,6 +117,12 @@ static inline TransportType GetBridgeTransportType(TileIndex t)
}
/**
* Does the bridge ramp lie in a snow or desert area?
* @param t The ramp tile to analyze
* @pre IsBridgeTile(t)
* @return true if and only if in a snow or desert area
*/
static inline bool HasBridgeSnowOrDesert(TileIndex t)
{
assert(IsBridgeTile(t));
@ -109,6 +130,12 @@ static inline bool HasBridgeSnowOrDesert(TileIndex t)
}
/**
* Sets whether the bridge ramp lies in a snow or desert area.
* @param t The ramp tile to set (un)make a snow/desert area
* @param snow_or_desert Make (true) or unmake the tile a snow/desert area
* @pre IsBridgeTile(t)
*/
static inline void SetBridgeSnowOrDesert(TileIndex t, bool snow_or_desert)
{
assert(IsBridgeTile(t));
@ -117,28 +144,43 @@ static inline void SetBridgeSnowOrDesert(TileIndex t, bool snow_or_desert)
/**
* Finds the end of a bridge in the specified direction starting at a middle tile
* @param t the bridge tile to find the bridge ramp for
* @param d the direction to search in
*/
TileIndex GetBridgeEnd(TileIndex, DiagDirection);
TileIndex GetBridgeEnd(TileIndex t, DiagDirection d);
/**
* Finds the northern end of a bridge starting at a middle tile
* @param t the bridge tile to find the bridge ramp for
*/
TileIndex GetNorthernBridgeEnd(TileIndex t);
/**
* Finds the southern end of a bridge starting at a middle tile
* @param t the bridge tile to find the bridge ramp for
*/
TileIndex GetSouthernBridgeEnd(TileIndex t);
/**
* Starting at one bridge end finds the other bridge end
* @param t the bridge ramp tile to find the other bridge ramp for
*/
TileIndex GetOtherBridgeEnd(TileIndex);
TileIndex GetOtherBridgeEnd(TileIndex t);
/**
* Get the height ('z') of a bridge in pixels.
* @param tile the bridge ramp tile to get the bridge height from
* @return the height of the bridge in pixels
*/
uint GetBridgeHeight(TileIndex tile);
uint GetBridgeFoundation(Slope tileh, Axis axis);
/**
* Remove the bridge over the given axis.
* @param t the tile to remove the bridge from
* @param a the axis of the bridge to remove
* @pre MayHaveBridgeAbove(t)
*/
static inline void ClearSingleBridgeMiddle(TileIndex t, Axis a)
{
assert(MayHaveBridgeAbove(t));
@ -146,12 +188,23 @@ static inline void ClearSingleBridgeMiddle(TileIndex t, Axis a)
}
/**
* Removes bridges from the given, that is bridges along the X and Y axis.
* @param t the tile to remove the bridge from
* @pre MayHaveBridgeAbove(t)
*/
static inline void ClearBridgeMiddle(TileIndex t)
{
ClearSingleBridgeMiddle(t, AXIS_X);
ClearSingleBridgeMiddle(t, AXIS_Y);
}
/**
* Set that there is a bridge over the given axis.
* @param t the tile to add the bridge to
* @param a the axis of the bridge to add
* @pre MayHaveBridgeAbove(t)
*/
static inline void SetBridgeMiddle(TileIndex t, Axis a)
{
assert(MayHaveBridgeAbove(t));
@ -159,6 +212,15 @@ static inline void SetBridgeMiddle(TileIndex t, Axis a)
}
/**
* Generic part to make a bridge ramp for both roads and rails.
* @param t the tile to make a bridge ramp
* @param o the new owner of the bridge ramp
* @param bridgetype the type of bridge this bridge ramp belongs to
* @param d the direction this ramp must be facing
* @param tt the transport type of the bridge
* @note this function should not be called directly.
*/
static inline void MakeBridgeRamp(TileIndex t, Owner o, uint bridgetype, DiagDirection d, TransportType tt)
{
SetTileType(t, MP_TUNNELBRIDGE);
@ -168,12 +230,27 @@ static inline void MakeBridgeRamp(TileIndex t, Owner o, uint bridgetype, DiagDir
_m[t].m5 = 1 << 7 | tt << 2 | d;
}
/**
* Make a bridge ramp for roads.
* @param t the tile to make a bridge ramp
* @param o the new owner of the bridge ramp
* @param bridgetype the type of bridge this bridge ramp belongs to
* @param d the direction this ramp must be facing
*/
static inline void MakeRoadBridgeRamp(TileIndex t, Owner o, uint bridgetype, DiagDirection d)
{
MakeBridgeRamp(t, o, bridgetype, d, TRANSPORT_ROAD);
_m[t].m3 = 0;
}
/**
* Make a bridge ramp for rails.
* @param t the tile to make a bridge ramp
* @param o the new owner of the bridge ramp
* @param bridgetype the type of bridge this bridge ramp belongs to
* @param d the direction this ramp must be facing
* @param r the rail type of the bridge
*/
static inline void MakeRailBridgeRamp(TileIndex t, Owner o, uint bridgetype, DiagDirection d, RailType r)
{
MakeBridgeRamp(t, o, bridgetype, d, TRANSPORT_RAIL);

View File

@ -1,6 +1,6 @@
/* $Id$ */
/** @file clear_map.h */
/** @file clear_map.h Map accessors for 'clear' tiles */
#ifndef CLEAR_MAP_H
#define CLEAR_MAP_H
@ -9,8 +9,8 @@
#include "tile.h"
#include "bridge_map.h"
/* ground type, m5 bits 2...4
* valid densities (bits 0...1) in comments after the enum
/**
* Ground types. Valid densities in comments after the enum.
*/
enum ClearGround {
CLEAR_GRASS = 0, ///< 0-3
@ -22,24 +22,48 @@ enum ClearGround {
};
/**
* Get the type of clear tile.
* @param t the tile to get the clear ground type of
* @pre IsTileType(t, MP_CLEAR)
* @return the ground type
*/
static inline ClearGround GetClearGround(TileIndex t)
{
assert(IsTileType(t, MP_CLEAR));
return (ClearGround)GB(_m[t].m5, 2, 3);
}
/**
* Set the type of clear tile.
* @param t the tile to set the clear ground type of
* @param ct the ground type
* @pre IsTileType(t, MP_CLEAR)
*/
static inline bool IsClearGround(TileIndex t, ClearGround ct)
{
return GetClearGround(t) == ct;
}
/**
* Get the density of a non-field clear tile.
* @param t the tile to get the density of
* @pre IsTileType(t, MP_CLEAR)
* @return the density
*/
static inline uint GetClearDensity(TileIndex t)
{
assert(IsTileType(t, MP_CLEAR));
return GB(_m[t].m5, 0, 2);
}
/**
* Increment the density of a non-field clear tile.
* @param t the tile to increment the density of
* @param d the amount to increment the density with
* @pre IsTileType(t, MP_CLEAR)
*/
static inline void AddClearDensity(TileIndex t, int d)
{
assert(IsTileType(t, MP_CLEAR)); // XXX incomplete
@ -47,18 +71,36 @@ static inline void AddClearDensity(TileIndex t, int d)
}
/**
* Get the counter used to advance to the next clear density/field type.
* @param t the tile to get the counter of
* @pre IsTileType(t, MP_CLEAR)
* @return the value of the counter
*/
static inline uint GetClearCounter(TileIndex t)
{
assert(IsTileType(t, MP_CLEAR));
return GB(_m[t].m5, 5, 3);
}
/**
* Increments the counter used to advance to the next clear density/field type.
* @param t the tile to increment the counter of
* @param c the amount to increment the counter with
* @pre IsTileType(t, MP_CLEAR)
*/
static inline void AddClearCounter(TileIndex t, int c)
{
assert(IsTileType(t, MP_CLEAR)); // XXX incomplete
_m[t].m5 += c << 5;
}
/**
* Sets the counter used to advance to the next clear density/field type.
* @param t the tile to set the counter of
* @param c the amount to set the counter to
* @pre IsTileType(t, MP_CLEAR)
*/
static inline void SetClearCounter(TileIndex t, uint c)
{
assert(IsTileType(t, MP_CLEAR)); // XXX incomplete
@ -66,7 +108,13 @@ static inline void SetClearCounter(TileIndex t, uint c)
}
/* Sets type and density in one go, also sets the counter to 0 */
/**
* Sets ground type and density in one go, also sets the counter to 0
* @param t the tile to set the ground type and density for
* @param type the new ground type of the tile
* @param density the density of the ground tile
* @pre IsTileType(t, MP_CLEAR)
*/
static inline void SetClearGroundDensity(TileIndex t, ClearGround type, uint density)
{
assert(IsTileType(t, MP_CLEAR)); // XXX incomplete
@ -74,49 +122,99 @@ static inline void SetClearGroundDensity(TileIndex t, ClearGround type, uint den
}
/**
* Get the field type (production stage) of the field
* @param t the field to get the type of
* @pre GetClearGround(t) == CLEAR_FIELDS
* @return the field type
*/
static inline uint GetFieldType(TileIndex t)
{
assert(GetClearGround(t) == CLEAR_FIELDS);
return GB(_m[t].m3, 0, 4);
}
/**
* Set the field type (production stage) of the field
* @param t the field to get the type of
* @param f the field type
* @pre GetClearGround(t) == CLEAR_FIELDS
*/
static inline void SetFieldType(TileIndex t, uint f)
{
assert(GetClearGround(t) == CLEAR_FIELDS); // XXX incomplete
SB(_m[t].m3, 0, 4, f);
}
static inline uint16 GetIndustryIndexOfField(TileIndex t)
/**
* Get the industry (farm) that made the field
* @param t the field to get creating industry of
* @pre GetClearGround(t) == CLEAR_FIELDS
* @return the industry that made the field
*/
static inline IndustryID GetIndustryIndexOfField(TileIndex t)
{
assert(GetClearGround(t) == CLEAR_FIELDS);
return _m[t].m2;
return(IndustryID) _m[t].m2;
}
static inline void SetIndustryIndexOfField(TileIndex t, uint16 i)
/**
* Set the industry (farm) that made the field
* @param t the field to get creating industry of
* @param i the industry that made the field
* @pre GetClearGround(t) == CLEAR_FIELDS
*/
static inline void SetIndustryIndexOfField(TileIndex t, IndustryID i)
{
assert(GetClearGround(t) == CLEAR_FIELDS);
_m[t].m2 = i;
}
/* Is used by tree tiles, too */
/**
* Is there a fence at the south eastern border?
* @param t the tile to check for fences
* @pre IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)
* @return 0 if there is no fence, otherwise the fence type
*/
static inline uint GetFenceSE(TileIndex t)
{
assert(IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES));
return GB(_m[t].m4, 2, 3);
}
/**
* Sets the type of fence (and whether there is one) for the south
* eastern border.
* @param t the tile to check for fences
* @param h 0 if there is no fence, otherwise the fence type
* @pre IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)
*/
static inline void SetFenceSE(TileIndex t, uint h)
{
assert(IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)); // XXX incomplete
SB(_m[t].m4, 2, 3, h);
}
/**
* Is there a fence at the south western border?
* @param t the tile to check for fences
* @pre IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)
* @return 0 if there is no fence, otherwise the fence type
*/
static inline uint GetFenceSW(TileIndex t)
{
assert(IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES));
return GB(_m[t].m4, 5, 3);
}
/**
* Sets the type of fence (and whether there is one) for the south
* western border.
* @param t the tile to check for fences
* @param h 0 if there is no fence, otherwise the fence type
* @pre IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)
*/
static inline void SetFenceSW(TileIndex t, uint h)
{
assert(IsTileType(t, MP_CLEAR) || IsTileType(t, MP_TREES)); // XXX incomplete
@ -124,6 +222,12 @@ static inline void SetFenceSW(TileIndex t, uint h)
}
/**
* Make a clear tile.
* @param t the tile to make a clear tile
* @param g the type of ground
* @param density the density of the grass/snow/desert etc
*/
static inline void MakeClear(TileIndex t, ClearGround g, uint density)
{
/* If this is a non-bridgeable tile, clear the bridge bits while the rest
@ -140,7 +244,13 @@ static inline void MakeClear(TileIndex t, ClearGround g, uint density)
}
static inline void MakeField(TileIndex t, uint field_type, uint16 industry)
/**
* Make a (farm) field tile.
* @param t the tile to make a farm field
* @param field_type the 'growth' level of the field
* @param industry the industry this tile belongs to
*/
static inline void MakeField(TileIndex t, uint field_type, IndustryID industry)
{
SetTileType(t, MP_CLEAR);
SetTileOwner(t, OWNER_NONE);

View File

@ -51,17 +51,35 @@ enum {
NUM_INDUSTRY_GFXES = 175,
};
/**
* Get the industry ID of the given tile
* @param t the tile to get the industry ID from
* @pre IsTileType(t, MP_INDUSTRY)
* @return the industry ID
*/
static inline IndustryID GetIndustryIndex(TileIndex t)
{
assert(IsTileType(t, MP_INDUSTRY));
return _m[t].m2;
}
/**
* Get the industry of the given tile
* @param t the tile to get the industry from
* @pre IsTileType(t, MP_INDUSTRY)
* @return the industry
*/
static inline Industry* GetIndustryByTile(TileIndex t)
{
return GetIndustry(GetIndustryIndex(t));
}
/**
* Is this industry tile fully built?
* @param t the tile to analyze
* @pre IsTileType(t, MP_INDUSTRY)
* @return true if and only if the industry tile is fully built
*/
static inline bool IsIndustryCompleted(TileIndex t)
{
assert(IsTileType(t, MP_INDUSTRY));
@ -106,18 +124,36 @@ static inline void SetIndustryConstructionStage(TileIndex tile, byte value)
SB(_m[tile].m1, 0, 2, value);
}
/**
* Get the industry graphics ID for the given industry tile
* @param t the tile to get the gfx for
* @pre IsTileType(t, MP_INDUSTRY)
* @return the gfx ID
*/
static inline IndustryGfx GetIndustryGfx(TileIndex t)
{
assert(IsTileType(t, MP_INDUSTRY));
return _m[t].m5;
}
/**
* Set the industry graphics ID for the given industry tile
* @param t the tile to set the gfx for
* @pre IsTileType(t, MP_INDUSTRY)
* @param gfx the graphics ID
*/
static inline void SetIndustryGfx(TileIndex t, IndustryGfx gfx)
{
assert(IsTileType(t, MP_INDUSTRY));
_m[t].m5 = gfx;
}
/**
* Make the given tile an industry tile
* @param t the tile to make an industry tile
* @param index the industry this tile belongs to
* @param gfx the graphics to use for the tile
*/
static inline void MakeIndustry(TileIndex t, IndustryID index, IndustryGfx gfx)
{
SetTileType(t, MP_INDUSTRY);
@ -157,7 +193,6 @@ static inline void SetIndustryConstructionCounter(TileIndex tile, byte value)
* as well as the completion bit.
* In fact, it is the same as restarting construction frmo ground up
* @param tile the tile to query
* @param generating_world whether generating a world or not
* @pre IsTileType(tile, MP_INDUSTRY)
*/
static inline void ResetIndustryConstructionStage(TileIndex tile)
@ -166,12 +201,14 @@ static inline void ResetIndustryConstructionStage(TileIndex tile)
_m[tile].m1 = 0;
}
/** Structure used to make a mapping from industry gfx to industry type */
struct IndustryTypeSolver {
IndustryGfx MinGfx;
IndustryGfx MaxGfx;
IndustryGfx MinGfx; ///< The first gfx index for the industry type
IndustryGfx MaxGfx; ///< The last gfx index for the industry type
};
static const IndustryTypeSolver industry_gfx_Solver [IT_END] = {
/** Mapping of industry gfx to industry type */
static const IndustryTypeSolver industry_gfx_Solver[IT_END] = {
{ 0, 6}, ///< IT_COAL_MINE
{ 7, 10}, ///< IT_POWER_STATION,
{ 11, 15}, ///< IT_SAWMILL,
@ -247,7 +284,7 @@ static inline byte GetIndustryAnimationState(TileIndex tile)
/**
* Set the animation state
* @param tile the tile to set the animation state of
* @param count the new animation state
* @param state the new animation state
* @pre IsTileType(tile, MP_INDUSTRY)
*/
static inline void SetIndustryAnimationState(TileIndex tile, byte state)

View File

@ -47,7 +47,7 @@ TrackBits GetAnyRoadTrackBits(TileIndex tile)
{
uint32 r;
// Don't allow local authorities to build roads through road depots or road stops.
/* Don't allow local authorities to build roads through road depots or road stops. */
if ((IsTileType(tile, MP_STREET) && IsTileDepotType(tile, TRANSPORT_ROAD)) || (IsTileType(tile, MP_STATION) && !IsDriveThroughStopTile(tile))) {
return TRACK_BIT_NONE;
}

View File

@ -173,10 +173,19 @@ static inline DiagDirection GetRoadDepotDirection(TileIndex t)
* - road tunnels: entrance is treated as road piece
* - bridge ramps: start of the ramp is treated as road piece
* - bridge middle parts: bridge itself is ignored
* @param tile the tile to get the road bits for
* @return the road bits of the given tile
*/
RoadBits GetAnyRoadBits(TileIndex);
RoadBits GetAnyRoadBits(TileIndex tile);
/**
* Get the accessible track bits for the given tile.
* Special behaviour:
* - road depots: no track bits
* - non-drive-through stations: no track bits
* @param tile the tile to get the track bits for
* @return the track bits for the given tile
*/
TrackBits GetAnyRoadTrackBits(TileIndex tile);

View File

@ -127,7 +127,7 @@ static inline byte GetLiftPosition(TileIndex t)
/**
* Set the position of the lift on this animated house
* @param t the tile
* @param pos, from 0 to 36
* @param pos from 0 to 36
*/
static inline void SetLiftPosition(TileIndex t, byte pos)
{
@ -315,7 +315,8 @@ static inline byte GetHouseRandomBits(TileIndex t)
/**
* Set the activated triggers bits for this house.
* This is required for newgrf house
* @param t the tile of this house
* @param t the tile of this house
* @param triggers the activated triggers
* @pre IsTileType(t, MP_HOUSE)
*/
static inline void SetHouseTriggers(TileIndex t, byte triggers)