openttd-ottdgrfs: comparison src/tile.h

equal deleted inserted replaced

-:31fcaa5375a1
+:e72987579514
 #include "macros.h"
 #include "openttd.h"
 #include "map.h"
 #include "slope.h"
+/** Maximum allowed tile height */
+#define MAX_TILE_HEIGHT 15
+/** Maximum allowed snowline height */
+#define MAX_SNOWLINE_HEIGHT (MAX_TILE_HEIGHT - 2)
+/**
+* The different type of a tile.
+*
+* Each tile belongs to one type, according whatever is build on it.
+*
+* @note A railway with a crossing street is marked as MP_ROAD.
+*/
 enum TileType {
-	MP_CLEAR,
+	MP_CLEAR,               ///< A tile without any structures, i.e. grass, rocks, farm fields etc.
-	MP_RAILWAY,
+	MP_RAILWAY,             ///< A railway
-	MP_STREET,
+	MP_ROAD,                ///< A tile with road (or tram tracks)
-	MP_HOUSE,
+	MP_HOUSE,               ///< A house by a town
-	MP_TREES,
+	MP_TREES,               ///< Tile got trees
-	MP_STATION,
+	MP_STATION,             ///< A tile of a station
-	MP_WATER,
+	MP_WATER,               ///< Water tile
-	MP_VOID, // invisible tiles at the SW and SE border
+	MP_VOID,                ///< Invisible tiles at the SW and SE border
-	MP_INDUSTRY,
+	MP_INDUSTRY,            ///< Part of an industry
-	MP_TUNNELBRIDGE,
+	MP_TUNNELBRIDGE,        ///< Tunnel entry/exit and bridge heads
-	MP_UNMOVABLE,
+	MP_UNMOVABLE,           ///< Contains an object with cannot be removed like transmitters
 };
+/**
+* Additional infos of a tile on a tropic game.
+*
+* Each non-water tile in a tropic game is either a rainforest tile or a
+* desert one.
+*/
 enum TropicZone {
-	TROPICZONE_INVALID    = 0,
+	TROPICZONE_INVALID    = 0,      ///< Invalid tropiczone-type
-	TROPICZONE_DESERT     = 1,
+	TROPICZONE_DESERT     = 1,      ///< Tile is desert
-	TROPICZONE_RAINFOREST = 2,
+	TROPICZONE_RAINFOREST = 2,      ///< Rainforest tile
 };
 Slope GetTileSlope(TileIndex tile, uint *h);
 uint GetTileZ(TileIndex tile);
 uint GetTileMaxZ(TileIndex tile);
+/**
+* Returns the height of a tile
+*
+* This function returns the height of the northern corner of a tile.
+* This is saved in the global map-array. It does not take affect by
+* any slope-data of the tile.
+*
+* @param tile The tile to get the height from
+* @return the height of the tile
+* @pre tile < MapSize()
+*/
 static inline uint TileHeight(TileIndex tile)
 {
 	assert(tile < MapSize());
 	return GB(_m[tile].type_height, 0, 4);
 }
+/**
+* Sets the height of a tile.
+*
+* This function sets the height of the northern corner of a tile.
+*
+* @param tile The tile to change the height
+* @param height The new height value of the tile
+* @pre tile < MapSize()
+* @pre heigth <= MAX_TILE_HEIGHT
+*/
 static inline void SetTileHeight(TileIndex tile, uint height)
 {
 	assert(tile < MapSize());
-	assert(height < 16);
+	assert(height <= MAX_TILE_HEIGHT);
 	SB(_m[tile].type_height, 0, 4, height);
 }
+/**
+* Returns the height of a tile in pixels.
+*
+* This function returns the height of the northern corner of a tile in pixels.
+*
+* @param tile The tile to get the height
+* @return The height of the tile in pixel
+*/
 static inline uint TilePixelHeight(TileIndex tile)
 {
 	return TileHeight(tile) * TILE_HEIGHT;
 }
+/**
+* Get the tiletype of a given tile.
+*
+* @param tile The tile to get the TileType
+* @return The tiletype of the tile
+* @pre tile < MapSize()
+*/
 static inline TileType GetTileType(TileIndex tile)
 {
 	assert(tile < MapSize());
 	return (TileType)GB(_m[tile].type_height, 4, 4);
 }
+/**
+* Set the type of a tile
+*
+* This functions sets the type of a tile. If the type
+* MP_VOID is selected the tile must be at the south-west or
+* south-east edges of the map and vice versa.
+*
+* @param tile The tile to save the new type
+* @param type The type to save
+* @pre tile < MapSize()
+* @pre type MP_VOID <=> tile is on the south-east or south-west edge.
+*/
 static inline void SetTileType(TileIndex tile, TileType type)
 {
 	assert(tile < MapSize());
 	/* VOID tiles (and no others) are exactly allowed at the lower left and right
 	 * edges of the map */
 	assert((TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) == (type == MP_VOID));
 	SB(_m[tile].type_height, 4, 4, type);
 }
+/**
+* Checks if a tile is a give tiletype.
+*
+* This function checks if a tile got the given tiletype.
+*
+* @param tile The tile to check
+* @param type The type to check agains
+* @return true If the type matches agains the type of the tile
+*/
 static inline bool IsTileType(TileIndex tile, TileType type)
 {
 	return GetTileType(tile) == type;
 }
+/**
+* Returns the owner of a tile
+*
+* This function returns the owner of a tile. This cannot used
+* for tiles which type is one of MP_HOUSE, MP_VOID and MP_INDUSTRY
+* as no player owned any of these buildings.
+*
+* @param tile The tile to check
+* @return The owner of the tile
+* @pre tile < MapSize()
+* @pre The type of the tile must not be MP_HOUSE, MP_VOID and MP_INDUSTRY
+*/
 static inline Owner GetTileOwner(TileIndex tile)
 {
 	assert(tile < MapSize());
 	assert(!IsTileType(tile, MP_HOUSE));
 	assert(!IsTileType(tile, MP_VOID));
 	assert(!IsTileType(tile, MP_INDUSTRY));
 	return (Owner)_m[tile].m1;
 }
+/**
+* Sets the owner of a tile
+*
+* This function sets the owner status of a tile. Note that you cannot
+* set a owner for tiles of type MP_HOUSE, MP_VOID and MP_INDUSTRY.
+*
+* @param tile The tile to change the owner status.
+* @param owner The new owner.
+* @pre tile < MapSize()
+* @pre The type of the tile must not be MP_HOUSE, MP_VOID and MP_INDUSTRY
+*/
 static inline void SetTileOwner(TileIndex tile, Owner owner)
 {
 	assert(tile < MapSize());
 	assert(!IsTileType(tile, MP_HOUSE));
 	assert(!IsTileType(tile, MP_VOID));
 	assert(!IsTileType(tile, MP_INDUSTRY));
 	_m[tile].m1 = owner;
 }
+/**
+* Checks if a tile belongs to the given owner
+*
+* @param tile The tile to check
+* @param owner The owner to check agains
+* @return True if a tile belongs the the given owner
+*/
 static inline bool IsTileOwner(TileIndex tile, Owner owner)
 {
 	return GetTileOwner(tile) == owner;
 }

branch	noai
changeset 9694	e72987579514
parent 9574	698395509d12