gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-02-02 20:34:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

(svn r14491) -Documentation: updates/additions of doxygen docs (Alberth)

Browse Source
This commit is contained in:
rubidium 2008-10-19 15:39:12 +00:00
parent 15eb140d28
commit d832626bb9
15 changed files with 191 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
src/cargo_type.h
View File

@ -7,7 +7,8 @@
typedef byte CargoID;
enum {
/** Available types of cargo */
enum CargoTypes {
/* Temperate */
CT_PASSENGERS = 0,
CT_COAL = 1,
@ -54,6 +55,7 @@ enum {
CT_INVALID = 0xFF
};
/** Array for storing amounts of accepted cargo */
typedef uint AcceptedCargo[NUM_CARGO];
#endif /* OPENTTD_H */
#endif /* CARGO_TYPE_H */

45
src/landscape.cpp
View File

@ -2,6 +2,8 @@
/** @file landscape.cpp Functions related to the landscape (slopes etc.). */
/** @defgroup SnowLineGroup Snowline functions and data structures */
#include "stdafx.h"
#include "openttd.h"
#include "bridge_map.h"
@ -44,18 +46,21 @@ extern const TileTypeProcs
_tile_type_tunnelbridge_procs,
_tile_type_unmovable_procs;
/** Tile callback functions for each type of tile.
* @ingroup TileCallbackGroup
* @see TileType */
const TileTypeProcs * const _tile_type_procs[16] = {
&_tile_type_clear_procs,
&_tile_type_rail_procs,
&_tile_type_road_procs,
&_tile_type_town_procs,
&_tile_type_trees_procs,
&_tile_type_station_procs,
&_tile_type_water_procs,
&_tile_type_dummy_procs,
&_tile_type_industry_procs,
&_tile_type_tunnelbridge_procs,
&_tile_type_unmovable_procs,
&_tile_type_clear_procs, ///< Callback functions for MP_CLEAR tiles
&_tile_type_rail_procs, ///< Callback functions for MP_RAILWAY tiles
&_tile_type_road_procs, ///< Callback functions for MP_ROAD tiles
&_tile_type_town_procs, ///< Callback functions for MP_HOUSE tiles
&_tile_type_trees_procs, ///< Callback functions for MP_TREES tiles
&_tile_type_station_procs, ///< Callback functions for MP_STATION tiles
&_tile_type_water_procs, ///< Callback functions for MP_WATER tiles
&_tile_type_dummy_procs, ///< Callback functions for MP_VOID tiles
&_tile_type_industry_procs, ///< Callback functions for MP_INDUSTRY tiles
&_tile_type_tunnelbridge_procs, ///< Callback functions for MP_TUNNELBRIDGE tiles
&_tile_type_unmovable_procs, ///< Callback functions for MP_UNMOVABLE tiles
};
/* landscape slope => sprite */
@ -64,6 +69,13 @@ const byte _tileh_to_sprite[32] = {
0, 0, 0, 0, 0, 0, 0, 16, 0, 0, 0, 17, 0, 15, 18, 0,
};
/**
* Description of the snow line throughout the year.
*
* If it is \c NULL, a static snowline height is used, as set by \c _settings_game.game_creation.snow_line.
* Otherwise it points to a table loaded from a newGRF file, that describes the variable snowline
* @ingroup SnowLineGroup
* @see GetSnowLine() GameCreationSettings */
SnowLine *_snow_line = NULL;
/**
@ -360,7 +372,11 @@ static bool HasFoundationNE(TileIndex tile, Slope slope_here, uint z_here)
return (z_N_here > z_N) || (z_E_here > z_E);
}
/**
* Draw foundation \a f at tile \a ti. Updates \a ti.
* @param ti Tile to draw foundation on
* @param f Foundation to draw
*/
void DrawFoundation(TileInfo *ti, Foundation f)
{
if (!IsFoundation(f)) return;
@ -508,6 +524,7 @@ void GetTileDesc(TileIndex tile, TileDesc *td)
/**
* Has a snow line table already been loaded.
* @return true if the table has been loaded already.
* @ingroup SnowLineGroup
*/
bool IsSnowLineSet(void)
{
@ -517,6 +534,7 @@ bool IsSnowLineSet(void)
/**
* Set a variable snow line, as loaded from a newgrf file.
* @param table the 12 * 32 byte table containing the snowline for each day
* @ingroup SnowLineGroup
*/
void SetSnowLine(byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS])
{
@ -533,6 +551,7 @@ void SetSnowLine(byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS])
/**
* Get the current snow line, either variable or static.
* @return the snow line height.
* @ingroup SnowLineGroup
*/
byte GetSnowLine(void)
{
@ -546,6 +565,7 @@ byte GetSnowLine(void)
/**
* Get the highest possible snow line height, either variable or static.
* @return the highest snow line height.
* @ingroup SnowLineGroup
*/
byte HighestSnowLine(void)
{
@ -554,6 +574,7 @@ byte HighestSnowLine(void)
/**
* Clear the variable snow line table and free the memory.
* @ingroup SnowLineGroup
*/
void ClearSnowLine(void)
{

10
src/landscape.h
View File

@ -11,13 +11,15 @@
#include "direction_type.h"
enum {
SNOW_LINE_MONTHS = 12,
SNOW_LINE_DAYS = 32,
SNOW_LINE_MONTHS = 12, ///< Number of months in the snow line table.
SNOW_LINE_DAYS = 32, ///< Number of days in each month in the snow line table.
};
/** Structure describing the height of the snow line each day of the year
* @ingroup SnowLineGroup */
struct SnowLine {
byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS];
byte highest_value;
byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS]; ///< Height of the snow line each day of the year
byte highest_value; ///< Highest snow line of the year
};
bool IsSnowLineSet(void);

3
src/rail_cmd.cpp
View File

@ -2468,7 +2468,8 @@ int TicksToLeaveDepot(const Vehicle *v)
return 0; // make compilers happy
}
/** Tile callback routine when vehicle enters tile
* @see vehicle_enter_tile_proc */
static VehicleEnterTileStatus VehicleEnter_Track(Vehicle *v, TileIndex tile, int x, int y)
{
byte fract_coord;

36
src/road_cmd.cpp
View File

@ -43,7 +43,10 @@
#include "table/sprites.h"
#include "table/strings.h"
/**
* Verify whether a road vehicle is available.
* @return \c true if at least one road vehicle is available, \c false if not
*/
bool RoadVehiclesAreBuilt()
{
const Vehicle* v;
@ -1156,6 +1159,7 @@ static void DrawRoadBits(TileInfo *ti)
}
}
/** Tile callback function for rendering a road tile to the screen */
static void DrawTile_Road(TileInfo *ti)
{
switch (GetRoadTileType(ti->tile)) {
@ -1630,20 +1634,20 @@ static CommandCost TerraformTile_Road(TileIndex tile, uint32 flags, uint z_new,
return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
}
/** Tile callback functions for road tiles */
extern const TileTypeProcs _tile_type_road_procs = {
DrawTile_Road, /* draw_tile_proc */
GetSlopeZ_Road, /* get_slope_z_proc */
ClearTile_Road, /* clear_tile_proc */
GetAcceptedCargo_Road, /* get_accepted_cargo_proc */
GetTileDesc_Road, /* get_tile_desc_proc */
GetTileTrackStatus_Road, /* get_tile_track_status_proc */
ClickTile_Road, /* click_tile_proc */
AnimateTile_Road, /* animate_tile_proc */
TileLoop_Road, /* tile_loop_clear */
ChangeTileOwner_Road, /* change_tile_owner_clear */
NULL, /* get_produced_cargo_proc */
VehicleEnter_Road, /* vehicle_enter_tile_proc */
GetFoundation_Road, /* get_foundation_proc */
TerraformTile_Road, /* terraform_tile_proc */
DrawTile_Road, // draw_tile_proc
GetSlopeZ_Road, // get_slope_z_proc
ClearTile_Road, // clear_tile_proc
GetAcceptedCargo_Road, // get_accepted_cargo_proc
GetTileDesc_Road, // get_tile_desc_proc
GetTileTrackStatus_Road, // get_tile_track_status_proc
ClickTile_Road, // click_tile_proc
AnimateTile_Road, // animate_tile_proc
TileLoop_Road, // tile_loop_clear
ChangeTileOwner_Road, // change_tile_owner_clear
NULL, // get_produced_cargo_proc
VehicleEnter_Road, // vehicle_enter_tile_proc
GetFoundation_Road, // get_foundation_proc
TerraformTile_Road, // terraform_tile_proc
};

9
src/station.cpp
View File

@ -321,6 +321,15 @@ bool StationRect::BeforeAddRect(TileIndex tile, int w, int h, StationRectMode mo
BeforeAddTile(tile, mode) && BeforeAddTile(TILE_ADDXY(tile, w - 1, h - 1), mode);
}
/**
* Check whether station tiles of the given station id exist in the given rectangle
* @param st_id Station ID to look for in the rectangle
* @param left_a Minimal tile X edge of the rectangle
* @param top_a Minimal tile Y edge of the rectangle
* @param right_a Maximal tile X edge of the rectangle (inclusive)
* @param bottom_a Maximal tile Y edge of the rectangle (inclusive)
* @return \c true if a station tile with the given \a st_id exists in the rectangle, \c false otherwise
*/
/*static*/ bool StationRect::ScanForStationTiles(StationID st_id, int left_a, int top_a, int right_a, int bottom_a)
{
TileIndex top_left = TileXY(left_a, top_a);

5
src/station_base.h
View File

@ -107,6 +107,7 @@ struct StationRect : public Rect {
StationRect& operator = (Rect src);
};
/** Station data structure */
struct Station : PoolItem<Station, StationID, &_Station_pool> {
public:
RoadStop *GetPrimaryRoadStop(RoadStopType type) const
@ -150,13 +151,13 @@ public:
uint8 num_specs;
StationSpecList *speclist;
Date build_date;
Date build_date; ///< Date of construction
uint64 airport_flags; ///< stores which blocks on the airport are taken. was 16 bit earlier on, then 32
byte last_vehicle_type;
std::list<Vehicle *> loading_vehicles;
GoodsEntry goods[NUM_CARGO];
GoodsEntry goods[NUM_CARGO]; ///< Goods at this station
uint16 random_bits;
byte waiting_triggers;

17
src/station_map.h
View File

@ -14,6 +14,10 @@
typedef byte StationGfx;
/** Get Station ID from a tile
* @pre Tile \t must be part of the station
* @param t Tile to query station ID from
* @return Station ID of the station at \a t */
static inline StationID GetStationIndex(TileIndex t)
{
assert(IsTileType(t, MP_STATION));
@ -97,16 +101,29 @@ static inline bool IsAirport(TileIndex t)
bool IsHangar(TileIndex t);
/**
* Is the station at \a t a truck stop?
* @param t Tile to check
* @return \c true if station is a truck stop, \c false otherwise */
static inline bool IsTruckStop(TileIndex t)
{
return GetStationType(t) == STATION_TRUCK;
}
/**
* Is the station at \a t a bus stop?
* @param t Tile to check
* @return \c true if station is a bus stop, \c false otherwise */
static inline bool IsBusStop(TileIndex t)
{
return GetStationType(t) == STATION_BUS;
}
/**
* Is the station at \a t a road station?
* @pre Tile at \a t is a station tile
* @param t Tile to check
* @return \c true if station at the tile is a bus top or a truck stop, \c false otherwise */
static inline bool IsRoadStop(TileIndex t)
{
assert(IsTileType(t, MP_STATION));

1
src/station_type.h
View File

@ -14,6 +14,7 @@ struct StationSpec;
static const StationID INVALID_STATION = 0xFFFF;
/** Station types */
enum StationType {
STATION_RAIL,
STATION_AIRPORT,

77
src/tile_cmd.h
View File

@ -39,34 +39,53 @@ enum VehicleEnterTileStatus {
};
DECLARE_ENUM_AS_BIT_SET(VehicleEnterTileStatus);
/** Tile information, used while rendering the tile */
struct TileInfo {
uint x;
uint y;
Slope tileh;
TileIndex tile;
uint z;
uint x; ///< X position of the tile in unit coordinates
uint y; ///< Y position of the tile in unit coordinates
Slope tileh; ///< Slope of the tile
TileIndex tile; ///< Tile index
uint z; ///< Height
};
/** Tile description for the 'land area information' tool */
struct TileDesc {
StringID str;
Owner owner[4];
StringID owner_type[4];
Date build_date;
StringID station_class;
StringID station_name;
const char *grf;
uint64 dparam[2];
StringID str; ///< Description of the tile
Owner owner[4]; ///< Name of the owner(s)
StringID owner_type[4]; ///< Type of each owner
Date build_date; ///< Date of construction of tile contents
StringID station_class; ///< Class of station
StringID station_name; ///< Type of station within the class
const char *grf; ///< newGRF used for the tile contents
uint64 dparam[2]; ///< Parameters of the \a str string
};
/**
* Tile callback function signature for drawing a tile and its contents to the screen
* @param ti Information about the tile to draw
*/
typedef void DrawTileProc(TileInfo *ti);
typedef uint GetSlopeZProc(TileIndex tile, uint x, uint y);
typedef CommandCost ClearTileProc(TileIndex tile, byte flags);
/**
* Tile callback function signature for obtaining accepted carog of a tile
* @param tile Tile queried for its accepted cargo
* @param res Storage destination of the cargo accepted
*/
typedef void GetAcceptedCargoProc(TileIndex tile, AcceptedCargo res);
/**
* Tile callback function signature for obtaining a tile description
* @param tile Tile being queried
* @param td Storage pointer for returned tile description
*/
typedef void GetTileDescProc(TileIndex tile, TileDesc *td);
/**
* GetTileTrackStatusProcs return a value that contains the possible tracks
* Tile callback function signature for getting the possible tracks
* that can be taken on a given tile by a given transport.
*
* The return value contains the existing trackdirs and signal states.
*
* see track_func.h for usage of TrackStatus.
@ -77,6 +96,12 @@ typedef void GetTileDescProc(TileIndex tile, TileDesc *td);
* @return the track status information
*/
typedef TrackStatus GetTileTrackStatusProc(TileIndex tile, TransportType mode, uint sub_mode, DiagDirection side);
/**
* Tile callback function signature for obtaining the produced cargo of a tile.
* @param tile Tile being queried
* @param b Destination array of produced cargo
*/
typedef void GetProducedCargoProc(TileIndex tile, CargoID *b);
typedef void ClickTileProc(TileIndex tile);
typedef void AnimateTileProc(TileIndex tile);
@ -88,9 +113,11 @@ typedef VehicleEnterTileStatus VehicleEnterTileProc(Vehicle *v, TileIndex tile,
typedef Foundation GetFoundationProc(TileIndex tile, Slope tileh);
/**
* Called when a tile is affected by a terraforming operation.
* The function has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype.
* With DC_EXEC in flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself).
* Tile callback function signature of the terraforming callback.
*
* The function is called when a tile is affected by a terraforming operation.
* It has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype.
* With DC_EXEC in \a flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself).
*
* @note The terraforming has not yet taken place. So GetTileZ() and GetTileSlope() refer to the landscape before the terraforming operation.
*
@ -106,20 +133,20 @@ typedef CommandCost TerraformTileProc(TileIndex tile, uint32 flags, uint z_new,
* Set of callback functions for performing tile operations of a given tile type.
* @see TileType */
struct TileTypeProcs {
DrawTileProc *draw_tile_proc;
DrawTileProc *draw_tile_proc; ///< Called to render the tile and its contents to the screen
GetSlopeZProc *get_slope_z_proc;
ClearTileProc *clear_tile_proc;
GetAcceptedCargoProc *get_accepted_cargo_proc;
GetTileDescProc *get_tile_desc_proc;
GetTileTrackStatusProc *get_tile_track_status_proc;
ClickTileProc *click_tile_proc;
GetAcceptedCargoProc *get_accepted_cargo_proc; ///< Return accepted cargo of the tile
GetTileDescProc *get_tile_desc_proc; ///< Get a description of a tile (for the 'land area information' tool)
GetTileTrackStatusProc *get_tile_track_status_proc; ///< Get available tracks and status of a tile
ClickTileProc *click_tile_proc; ///< Called when tile is clicked
AnimateTileProc *animate_tile_proc;
TileLoopProc *tile_loop_proc;
ChangeTileOwnerProc *change_tile_owner_proc;
GetProducedCargoProc *get_produced_cargo_proc;
VehicleEnterTileProc *vehicle_enter_tile_proc;
GetProducedCargoProc *get_produced_cargo_proc; ///< Return produced cargo of the tile
VehicleEnterTileProc *vehicle_enter_tile_proc; ///< Called when a vehicle enters a tile
GetFoundationProc *get_foundation_proc;
TerraformTileProc *terraform_tile_proc;
TerraformTileProc *terraform_tile_proc; ///< Called when a terraforming operation is about to take place
};
extern const TileTypeProcs * const _tile_type_procs[16];

14
src/tile_map.cpp
View File

@ -7,6 +7,11 @@
#include "tile_map.h"
#include "core/math_func.hpp"
/**
* Return the slope of a given tile
* @param tile Tile to compute slope of
* @param h If not \c NULL, pointer to storage of z height
* @return Slope of the tile, except for the HALFTILE part */
Slope GetTileSlope(TileIndex tile, uint *h)
{
uint a;
@ -42,6 +47,10 @@ Slope GetTileSlope(TileIndex tile, uint *h)
return (Slope)r;
}
/**
* Get bottom height of the tile
* @param tile Tile to compute height of
* @return Minimum height of the tile */
uint GetTileZ(TileIndex tile)
{
if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) return 0;
@ -54,7 +63,10 @@ uint GetTileZ(TileIndex tile)
return h * TILE_HEIGHT;
}
/**
* Get top height of the tile
* @param tile Tile to compute height of
* @return Maximum height of the tile */
uint GetTileMaxZ(TileIndex t)
{
if (TileX(t) == MapMaxX() || TileY(t) == MapMaxY()) return 0;

15
src/town_cmd.cpp
View File

@ -224,6 +224,7 @@ static uint GetSlopeZ_Town(TileIndex tile, uint x, uint y)
return GetTileMaxZ(tile);
}
/** Tile callback routine */
static Foundation GetFoundation_Town(TileIndex tile, Slope tileh)
{
return FlatteningFoundation(tileh);
@ -399,7 +400,7 @@ static void MakeSingleHouseBigger(TileIndex tile)
MarkTileDirtyByTile(tile);
}
/** Make the house advances in its construction stages until completion
/** Make the house advance in its construction stages until completion
* @param tile TileIndex of house
*/
static void MakeTownHouseBigger(TileIndex tile)
@ -412,6 +413,8 @@ static void MakeTownHouseBigger(TileIndex tile)
}
/**
* Tile callback function.
*
* Periodic tic handler for houses and town
* @param tile been asked to do its stuff
*/
@ -507,7 +510,7 @@ static void TileLoop_Town(TileIndex tile)
}
/**
* Unused handler
* Dummy tile callback function for handling tile clicks in towns
* @param tile unused
*/
static void ClickTile_Town(TileIndex tile)
@ -2002,7 +2005,12 @@ static bool BuildTownHouse(Town *t, TileIndex tile)
return false;
}
/**
* Update data structures when a house is removed
* @param tile Tile of the house
* @param t Town owning the house
* @param house House type
*/
static void DoClearTownHouseHelper(TileIndex tile, Town *t, HouseID house)
{
assert(IsTileType(tile, MP_HOUSE));
@ -2601,6 +2609,7 @@ static CommandCost TerraformTile_Town(TileIndex tile, uint32 flags, uint z_new,
return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
}
/** Tile callback functions for a town */
extern const TileTypeProcs _tile_type_town_procs = {
DrawTile_Town, // draw_tile_proc
GetSlopeZ_Town, // get_slope_z_proc

9
src/transport_type.h
View File

@ -7,6 +7,7 @@
typedef uint16 UnitID;
/** Available types of transport */
enum TransportType {
/* These constants are for now linked to the representation of bridges
* and tunnels, so they can be used by GetTileTrackStatus_TunnelBridge.
@ -15,10 +16,10 @@ enum TransportType {
* the values for road and rail.
*/
TRANSPORT_BEGIN = 0,
TRANSPORT_RAIL = TRANSPORT_BEGIN,
TRANSPORT_ROAD,
TRANSPORT_WATER,
TRANSPORT_AIR,
TRANSPORT_RAIL = TRANSPORT_BEGIN, ///< Transport by train
TRANSPORT_ROAD, ///< Transport by road vehicle
TRANSPORT_WATER, ///< Transport over water
TRANSPORT_AIR, ///< Transport through air
TRANSPORT_END,
INVALID_TRANSPORT = 0xff,
};

12
src/vehicle.cpp
View File

@ -1779,7 +1779,10 @@ void MarkSingleVehicleDirty(const Vehicle *v)
MarkAllViewportsDirty(v->left_coord, v->top_coord, v->right_coord + 1, v->bottom_coord + 1);
}
/* returns true if staying in the same tile */
/**
* Get position information of a vehicle when moving one pixel in the direction it is facing
* @param v Vehicle to move
* @return Position information after the move */
GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v)
{
static const int8 _delta_coord[16] = {
@ -1870,7 +1873,12 @@ Trackdir GetVehicleTrackdir(const Vehicle *v)
}
/**
* Returns some meta-data over the to be entered tile.
* Call the tile callback function for a vehicle entering a tile
* @param v Vehicle entering the tile
* @param tile Tile entered
* @param x X position
* @param y Y position
* @return Some meta-data over the to be entered tile.
* @see VehicleEnterTileStatus to see what the bits in the return value mean.
*/
uint32 VehicleEnterTile(Vehicle *v, TileIndex tile, int x, int y)

9
src/vehicle_func.h
View File

@ -75,14 +75,13 @@ bool CanBuildVehicleInfrastructure(VehicleType type);
void CcCloneVehicle(bool success, TileIndex tile, uint32 p1, uint32 p2);
/** Position information of a vehicle after it moved */
struct GetNewVehiclePosResult {
int x, y;
TileIndex old_tile;
TileIndex new_tile;
int x, y; ///< x and y position of the vehicle after moving
TileIndex old_tile; ///< Current tile of the vehicle
TileIndex new_tile; ///< Tile of the vehicle after moving
};
/* returns true if staying in the same tile */
GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v);
Direction GetDirectionTowards(const Vehicle *v, int x, int y);