gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-03-06 14:27:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

(svn r11066) -Documentation [FS#1091]: of map.*. Patch by Progman.

Browse Source
This commit is contained in:
rubidium 2007-09-09 10:21:27 +00:00
parent 65f9a0f21a
commit ed3b1d398a
2 changed files with 166 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
src/map.cpp
View File

@ -26,7 +26,7 @@ Tile *_m = NULL; ///< Tiles of the map
TileExtended *_me = NULL; ///< Extended Tiles of the map
/**
/*!
* (Re)allocates a map with the given dimension
* @param size_x the width of the map along the NE/SW edge
* @param size_y the 'height' of the map along the SE/NW edge
@ -97,9 +97,9 @@ TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
}
#endif
/**
/*!
* Scales the given value by the map size, where the given value is
* for a 256 by 256 map
* for a 256 by 256 map.
* @param n the value to scale
* @return the scaled size
*/
@ -112,7 +112,7 @@ uint ScaleByMapSize(uint n)
}
/**
/*!
* Scales the given value by the maps circumference, where the given
* value is for a 256 by 256 map
* @param n the value to scale
@ -128,13 +128,14 @@ uint ScaleByMapSize1D(uint n)
}
/**
/*!
* This function checks if we add addx/addy to tile, if we
* do wrap around the edges. For example, tile = (10,2) and
* addx = +3 and addy = -4. This function will now return
* INVALID_TILE, because the y is wrapped. This is needed in
* for example, farmland. When the tile is not wrapped,
* the result will be tile + TileDiffXY(addx, addy)
* do wrap around the edges. For example, tile = (10,2) and
* addx = +3 and addy = -4. This function will now return
* INVALID_TILE, because the y is wrapped. This is needed in
* for example, farmland. When the tile is not wrapped,
* the result will be tile + TileDiffXY(addx, addy)
*
* @param tile the 'starting' point of the adding
* @param addx the amount of tiles in the X direction to add
* @param addy the amount of tiles in the Y direction to add
@ -172,7 +173,7 @@ extern const TileIndexDiffC _tileoffs_by_dir[] = {
{ 0, -1} ///< DIR_NW
};
/**
/*!
* Gets the Manhattan distance between the two given tiles.
* The Manhattan distance is the sum of the delta of both the
* X and Y component.
@ -189,7 +190,7 @@ uint DistanceManhattan(TileIndex t0, TileIndex t1)
}
/**
/*!
* Gets the 'Square' distance between the two given tiles.
* The 'Square' distance is the square of the shortest (straight line)
* distance between the two tiles.
@ -206,7 +207,7 @@ uint DistanceSquare(TileIndex t0, TileIndex t1)
}
/**
/*!
* Gets the biggest distance component (x or y) between the two given tiles.
* Also known as L-Infinity-Norm.
* @param t0 the start tile
@ -221,7 +222,7 @@ uint DistanceMax(TileIndex t0, TileIndex t1)
}
/**
/*!
* Gets the biggest distance component (x or y) between the two given tiles
* plus the Manhattan distance, i.e. two times the biggest distance component
* and once the smallest component.
@ -236,7 +237,7 @@ uint DistanceMaxPlusManhattan(TileIndex t0, TileIndex t1)
return dx > dy ? 2 * dx + dy : 2 * dy + dx;
}
/**
/*!
* Param the minimum distance to an edge
* @param tile the tile to get the distance from
* @return the distance from the edge in tiles
@ -252,7 +253,7 @@ uint DistanceFromEdge(TileIndex tile)
return minl < minh ? minl : minh;
}
/**
/*!
* Function performing a search around a center tile and going outward, thus in circle.
* Although it really is a square search...
* Every tile will be tested by means of the callback function proc,

162
src/map.h
View File

@ -45,9 +45,25 @@ struct TileExtended {
byte m7; ///< Primarily used for newgrf support
};
/**
* Pointer to the tile-array.
*
* This variable points to the tile-array which contains the tiles of
* the map.
*/
extern Tile *_m;
/**
* Pointer to the extended tile-array.
*
* This variable points to the extended tile-array which contains the tiles
* of the map.
*/
extern TileExtended *_me;
/**
* Allocate a new map with the given size.
*/
void AllocateMap(uint size_x, uint size_y);
/**
@ -109,18 +125,56 @@ static inline uint MapMaxY()
return MapSizeY() - 1;
}
/* Scale a number relative to the map size */
uint ScaleByMapSize(uint); // Scale relative to the number of tiles
uint ScaleByMapSize1D(uint); // Scale relative to the circumference of the map
/**
* Scales relative to the number of tiles.
*/
uint ScaleByMapSize(uint);
/**
* Scale relative to the circumference of the map.
*/
uint ScaleByMapSize1D(uint);
/**
* The index/ID of a Tile.
*/
typedef uint32 TileIndex;
/**
* An offset value between to tiles.
*
* This value is used fro the difference between
* to tiles. It can be added to a tileindex to get
* the resulting tileindex of the start tile applied
* with this saved difference.
*
* @see TileDiffXY(int, int)
*/
typedef int32 TileIndexDiff;
/**
* Returns the TileIndex of a coordinate.
*
* @param x The x coordinate of the tile
* @param y The y coordinate of the tile
* @return The TileIndex calculated by the coordinate
*/
static inline TileIndex TileXY(uint x, uint y)
{
return (y * MapSizeX()) + x;
}
/**
* Calculates an offset for the given coordinate(-offset).
*
* This function calculate an offset value which can be added to an
* #TileIndex. The coordinates can be negative.
*
* @param x The offset in x direction
* @param y The offset in y direction
* @return The resulting offset value of the given coordinate
* @see ToTileIndexDiff(TileIndexDiffC)
*/
static inline TileIndexDiff TileDiffXY(int x, int y)
{
/* Multiplication gives much better optimization on MSVC than shifting.
@ -167,12 +221,27 @@ static inline uint TileY(TileIndex tile)
return tile >> MapLogX();
}
/**
* A pair-construct of a TileIndexDiff.
*
* This can be used to save the difference between to
* tiles as a pair of x and y value.
*/
struct TileIndexDiffC {
int16 x;
int16 y;
int16 x; ///< The x value of the coordinate
int16 y; ///< The y value of the coordinate
};
/**
* Return the offset between to tiles from a TileIndexDiffC struct.
*
* This function works like #TileDiffXY(int, int) and returns the
* difference between two tiles.
*
* @param tidc The coordinate of the offset as TileIndexDiffC
* @return The difference between two tiles.
* @see TileDiffXY(int, int)
*/
static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
{
return (tidc.y << MapLogX()) + tidc.x;
@ -180,6 +249,13 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
#ifndef _DEBUG
/**
* Adds to tiles together.
*
* @param x One tile
* @param y An other tile to add
* @return The resulting tile(index)
*/
#define TILE_ADD(x,y) ((x) + (y))
#else
extern TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
@ -187,10 +263,26 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
#define TILE_ADD(x, y) (TileAdd((x), (y), #x " + " #y, __FILE__, __LINE__))
#endif
/**
* Adds a given offset to a tile.
*
* @param tile The tile to add an offset on it
* @param x The x offset to add to the tile
* @param y The y offset to add to the tile
*/
#define TILE_ADDXY(tile, x, y) TILE_ADD(tile, TileDiffXY(x, y))
/**
* Adds an offset to a tile and check if we are still on the map.
*/
uint TileAddWrap(TileIndex tile, int addx, int addy);
/**
* Returns the TileIndexDiffC offset from a DiagDirection.
*
* @param dir The given direction
* @return The offset as TileIndexDiffC value
*/
static inline TileIndexDiffC TileIndexDiffCByDiagDir(DiagDirection dir)
{
extern const TileIndexDiffC _tileoffs_by_diagdir[DIAGDIR_END];
@ -198,9 +290,15 @@ static inline TileIndexDiffC TileIndexDiffCByDiagDir(DiagDirection dir)
assert(IsValidDiagDirection(dir));
return _tileoffs_by_diagdir[dir];
}
/* Returns tile + the diff given in diff. If the result tile would end up
/**
* Add a TileIndexDiffC to a TileIndex and returns the new one.
*
* Returns tile + the diff given in diff. If the result tile would end up
* outside of the map, INVALID_TILE is returned instead.
*
* @param tile The base tile to add the offset on
* @param diff The offset to add on the tile
* @return The resulting TileIndex
*/
static inline TileIndex AddTileIndexDiffCWrap(TileIndex tile, TileIndexDiffC diff)
{
@ -236,7 +334,16 @@ uint DistanceMax(TileIndex, TileIndex); ///< also known as L-Infinity-Norm
uint DistanceMaxPlusManhattan(TileIndex, TileIndex); ///< Max + Manhattan
uint DistanceFromEdge(TileIndex); ///< shortest distance from any edge of the map
/**
* Starts a loop which iterates to a square of tiles
*
* This macro starts 2 nested loops which iterates over a square of tiles.
*
* @param var The name of the variable which contains the current tile
* @param w The width (x-width) of the square
* @param h The heigth (y-width) of the square
* @param tile The start tile of the square
*/
#define BEGIN_TILE_LOOP(var, w, h, tile) \
{ \
int h_cur = h; \
@ -244,12 +351,22 @@ uint DistanceFromEdge(TileIndex); ///< shortest distance from any edge of the ma
do { \
int w_cur = w; \
do {
/**
* Ends the square-loop used before
*
* @see BEGIN_TILE_LOOP
*/
#define END_TILE_LOOP(var, w, h, tile) \
} while (++var, --w_cur != 0); \
} while (var += TileDiffXY(0, 1) - (w), --h_cur != 0); \
}
/**
* Convert a DiagDirection to a TileIndexDiff
*
* @param dir The DiagDirection
* @return The resulting TileIndexDiff
* @see TileIndexDiffCByDiagDir
*/
static inline TileIndexDiff TileOffsByDiagDir(DiagDirection dir)
{
extern const TileIndexDiffC _tileoffs_by_diagdir[DIAGDIR_END];
@ -258,6 +375,12 @@ static inline TileIndexDiff TileOffsByDiagDir(DiagDirection dir)
return ToTileIndexDiff(_tileoffs_by_diagdir[dir]);
}
/**
* Convert a Direction to a TileIndexDiff.
*
* @param dir The direction to convert from
* @return The resulting TileIndexDiff
*/
static inline TileIndexDiff TileOffsByDir(Direction dir)
{
extern const TileIndexDiffC _tileoffs_by_dir[DIR_END];
@ -266,11 +389,24 @@ static inline TileIndexDiff TileOffsByDir(Direction dir)
return ToTileIndexDiff(_tileoffs_by_dir[dir]);
}
/**
* A callback function type for searching tiles.
*
* @param tile The tile to test
* @param data additional data for the callback function to use
* @return A boolean value, depend on the definition of the function.
*/
typedef bool TestTileOnSearchProc(TileIndex tile, uint32 data);
/**
* Searches for some cirumstances of a tile around a given tile with a helper function.
*/
bool CircularTileSearch(TileIndex tile, uint size, TestTileOnSearchProc proc, uint32 data);
/* Approximation of the length of a straight track, relative to a diagonal
* track (ie the size of a tile side). #defined instead of const so it can
/** Approximation of the length of a straight track, relative to a diagonal
* track (ie the size of a tile side).
*
* #defined instead of const so it can
* stay integer. (no runtime float operations) Is this needed?
* Watch out! There are _no_ brackets around here, to prevent intermediate
* rounding! Be careful when using this!