diff options
| -rw-r--r-- | src/map.cpp | 33 | ||||
| -rw-r--r-- | src/map.h | 162 |
2 files changed, 166 insertions, 29 deletions
diff --git a/src/map.cpp b/src/map.cpp index 6156ecf8e..00e155c04 100644 --- a/src/map.cpp +++ b/src/map.cpp @@ -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, @@ -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! |