Changeset - r7546:849b3995d99e
[Not reviewed]
master
0 2 0
rubidium - 17 years ago 2007-09-09 10:21:27
rubidium@openttd.org
(svn r11066) -Documentation [FS#1091]: of map.*. Patch by Progman.
2 files changed with 166 insertions and 29 deletions:
src/map.h
149
13
0 comments (0 inline, 0 general)
src/map.cpp
Show inline comments
 
@@ -26,7 +26,7 @@ Tile *_m = NULL;          ///< Tiles of 
 
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, TileIn
 
}
 
#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
 
	{ 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, Til
 
}
 

	
 

	
 
/**
 
/*!
 
 * 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, TileIn
 
}
 

	
 

	
 
/**
 
/*!
 
 * 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
 
}
 

	
 

	
 
/**
 
/*!
 
 * 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 
 
	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,
src/map.h
Show inline comments
 
@@ -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 ToTileIndexD
 

	
 

	
 
#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 ToTileIndexD
 
	#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 TileIndexDi
 
	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); 
 
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); ///< s
 
		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 TileOffsByDi
 
	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 TileOffsByDi
 
	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!
0 comments (0 inline, 0 general)