From c2dc4a4adbe8b68dbb0e134dc68f651172af8530 Mon Sep 17 00:00:00 2001 From: rubidium Date: Mon, 17 Sep 2007 16:56:15 +0000 Subject: [PATCH] (svn r11124) -Documentation: of tree_map.h and tree_cmd.cpp. Patch by Progman. --- src/tree_cmd.cpp | 63 +++++++++++++- src/tree_map.h | 210 +++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 245 insertions(+), 28 deletions(-) diff --git a/src/tree_cmd.cpp b/src/tree_cmd.cpp index 52010a2051..7fc3770cb9 100644 --- a/src/tree_cmd.cpp +++ b/src/tree_cmd.cpp @@ -21,12 +21,28 @@ #include "variables.h" #include "genworld.h" +/** + * List of tree placer algorithm. + * + * This enumeration defines all possible tree placer algorithm in the game. + */ enum TreePlacer { - TP_NONE, - TP_ORIGINAL, - TP_IMPROVED, + TP_NONE, ///< No tree placer algorithm + TP_ORIGINAL, ///< The original algorithm + TP_IMPROVED, ///< A 'improved' algorithm }; +/** + * Get a random TreeType for the given tile based on a given seed + * + * This function returns a random TreeType which can be placed on the given tile. + * The seed for randomness must be less or equal 256, use #GB on the value of Random() + * to get such a value. + * + * @param tile The tile to get a random TreeType from + * @param seed The seed for randomness, must be less or equal 256 + * @return The random tree type + */ static TreeType GetRandomTreeType(TileIndex tile, uint seed) { switch (_opt.landscape) { @@ -48,6 +64,15 @@ static TreeType GetRandomTreeType(TileIndex tile, uint seed) } } +/** + * Make a random tree tile of the given tile + * + * Create a new tree-tile for the given tile. The second parameter is used for + * randomness like type and number of trees. + * + * @param tile The tile to make a tree-tile from + * @param r The randomness value from a Random() value + */ static void PlaceTree(TileIndex tile, uint32 r) { TreeType tree = GetRandomTreeType(tile, GB(r, 24, 8)); @@ -66,6 +91,15 @@ static void PlaceTree(TileIndex tile, uint32 r) } } +/** + * Place some amount of trees around a given tile. + * + * This function adds some trees around a given tile. As this function use + * the Random() call it depends on the random how many trees are actually placed + * around the given tile. + * + * @param tile The center of the trees to add + */ static void DoPlaceMoreTrees(TileIndex tile) { uint i; @@ -87,6 +121,11 @@ static void DoPlaceMoreTrees(TileIndex tile) } } +/** + * Place more trees on the map. + * + * This function add more trees to the map. + */ static void PlaceMoreTrees() { uint i = ScaleByMapSize(GB(Random(), 0, 5) + 25); @@ -97,7 +136,12 @@ static void PlaceMoreTrees() /** * Place a tree at the same height as an existing tree. - * This gives cool effects to the map. + * + * Add a new tree around the given tile which is at the same + * height or at some offset (2 units) of it. + * + * @param tile The base tile to add a new tree somewhere around + * @param height The height (like the one from the tile) */ void PlaceTreeAtSameHeight(TileIndex tile, uint height) { @@ -127,6 +171,11 @@ void PlaceTreeAtSameHeight(TileIndex tile, uint height) } } +/** + * Place some trees randomly + * + * This function just place some trees randomly on the map. + */ void PlaceTreesRandomly() { uint i, j, ht; @@ -183,6 +232,12 @@ void PlaceTreesRandomly() } } +/** + * Place new trees. + * + * This function takes care of the selected tree placer algorithm and + * place randomly the trees for a new game. + */ void GenerateTrees() { uint i, total; diff --git a/src/tree_map.h b/src/tree_map.h index e57848bc52..d1749fb579 100644 --- a/src/tree_map.h +++ b/src/tree_map.h @@ -7,54 +7,123 @@ #include "macros.h" +/** + * List of tree types along all landscape types. + * + * This enumeration contains a list of the different tree types along + * all landscape types. The values for the enumerations may be used for + * offsets from the grfs files. These points to the start of + * the tree list for a landscape. See the TREE_COUNT_* enumerations + * for the amount of different trees for a specific landscape. + * + * @note TREE_INVALID may be 0xFF according to the coding style, not -1 (Progman) + */ enum TreeType { - TREE_INVALID = -1, - TREE_TEMPERATE = 0, - TREE_SUB_ARCTIC = 12, - TREE_RAINFOREST = 20, - TREE_CACTUS = 27, - TREE_SUB_TROPICAL = 28, - TREE_TOYLAND = 32 + TREE_INVALID = -1, ///< An invalid tree + TREE_TEMPERATE = 0x00, ///< temperate tree + TREE_SUB_ARCTIC = 0x0C, ///< tree on a sub_arctic landscape + TREE_RAINFOREST = 0x14, ///< tree on the 'green part' on a sub-tropical map + TREE_CACTUS = 0x1B, ///< a catus for the 'desert part' on a sub-tropical map + TREE_SUB_TROPICAL = 0x1C, ///< tree on a sub-tropical map, non-rainforest, non-desert + TREE_TOYLAND = 0x20, ///< tree on a toyland map }; +/** + * Counts the number of treetypes for each landscape. + * + * This list contains the counts of different treetypes for each landscape. This list contains + * 5 entries instead of 4 (as there are only 4 landscape types) as the sub tropic landscape + * got two types of area, one for normal trees and one only for cacti. + */ enum { - TREE_COUNT_TEMPERATE = TREE_SUB_ARCTIC - TREE_TEMPERATE, - TREE_COUNT_SUB_ARCTIC = TREE_RAINFOREST - TREE_SUB_ARCTIC, - TREE_COUNT_RAINFOREST = TREE_CACTUS - TREE_RAINFOREST, - TREE_COUNT_SUB_TROPICAL = TREE_SUB_TROPICAL - TREE_CACTUS, - TREE_COUNT_TOYLAND = 9 + TREE_COUNT_TEMPERATE = TREE_SUB_ARCTIC - TREE_TEMPERATE, ///< number of treetypes on a temperate map + TREE_COUNT_SUB_ARCTIC = TREE_RAINFOREST - TREE_SUB_ARCTIC, ///< number of treetypes on a sub arctic map + TREE_COUNT_RAINFOREST = TREE_CACTUS - TREE_RAINFOREST, ///< number of treetypes for the 'green part' of a sub tropic map + TREE_COUNT_SUB_TROPICAL = TREE_SUB_TROPICAL - TREE_CACTUS, ///< number of treetypes for the 'desert part' of a sub tropic map + TREE_COUNT_TOYLAND = 9 ///< number of treetypes on a toyland map }; -/* ground type, m2 bits 4...5 - * valid densities (bits 6...7) in comments after the enum */ +/** + * Enumeration for ground types of tiles with trees. + * + * This enumeration defines the ground types for tiles with trees on it. + */ enum TreeGround { - TREE_GROUND_GRASS = 0, ///< 0 - TREE_GROUND_ROUGH = 1, ///< 0 - TREE_GROUND_SNOW_DESERT = 2 ///< 0-3 for snow, 3 for desert + TREE_GROUND_GRASS = 0, ///< normal grass + TREE_GROUND_ROUGH = 1, ///< some rough tile + TREE_GROUND_SNOW_DESERT = 2 ///< a desert or snow tile, depend on landscape }; +/** + * Returns the treetype of a tile. + * + * This function returns the treetype of a given tile. As there are more + * possible treetypes for a tile in a game as the enumeration #TreeType defines + * this function may be return a value which isn't catch by an entry of the + * enumeration #TreeType. But there is no problem known about it. + * + * @param t The tile to get the treetype from + * @return The treetype of the given tile with trees + * @pre Tile t must be of type MP_TREES + */ static inline TreeType GetTreeType(TileIndex t) { assert(IsTileType(t, MP_TREES)); return (TreeType)_m[t].m3; } - +/** + * Returns the groundtype for tree tiles. + * + * This function returns the groundtype of a tile with trees. + * + * @param t The tile to get the groundtype from + * @return The groundtype of the tile + * @pre Tile must be of type MP_TREES + */ static inline TreeGround GetTreeGround(TileIndex t) { assert(IsTileType(t, MP_TREES)); return (TreeGround)GB(_m[t].m2, 4, 2); } - +/** + * Returns the 'density' of a tile with trees. + * + * This function returns the density of a tile which got trees. Note + * that this value doesn't count the number of trees on a tile, use + * #GetTreeCount instead. This function instead returns some kind of + * groundtype of the tile. As the map-array is finite in size and + * the informations about the trees must be saved somehow other + * informations about a tile must be saved somewhere encoded in the + * tile. So this function returns the density of a tile for sub arctic + * and sub tropical games. This means for sub arctic the type of snowline + * (0 to 3 for all 4 types of snowtiles) and for sub tropical the value + * 3 for a desert (and 0 for non-desert). The functionname is not read as + * "get the tree density of a tile" but "get the density of a tile which got trees". + * + * @param t The tile to get the 'density' + * @pre Tile must be of type MP_TREES + * @see GetTreeCount + */ static inline uint GetTreeDensity(TileIndex t) { assert(IsTileType(t, MP_TREES)); return GB(_m[t].m2, 6, 2); } - +/** + * Set the density and ground type of a tile with trees. + * + * This functions saves the ground type and the density which belongs to it + * for a given tile. + * + * @param t The tile to set the density and ground type + * @param g The ground type to save + * @param d The density to save with + * @pre Tile must be of type MP_TREES + */ static inline void SetTreeGroundDensity(TileIndex t, TreeGround g, uint d) { assert(IsTileType(t, MP_TREES)); // XXX incomplete @@ -62,64 +131,157 @@ static inline void SetTreeGroundDensity(TileIndex t, TreeGround g, uint d) SB(_m[t].m2, 6, 2, d); } - +/** + * Returns the number of trees on a tile. + * + * This function returns the number of trees of a tile (1-4). + * The tile must be contains at least one tree or be more specific: it must be + * of type MP_TREES. + * + * @param t The index to get the number of trees + * @return The number of trees (1-4) + * @pre Tile must be of type MP_TREES + */ static inline uint GetTreeCount(TileIndex t) { assert(IsTileType(t, MP_TREES)); return GB(_m[t].m5, 6, 2); } +/** + * Add a amount to the tree-count value of a tile with trees. + * + * This function add a value to the tree-count value of a tile. This + * value may be negative to reduce the tree-counter. If the resulting + * value reach 0 it doesn't get converted to a "normal" tile. + * + * @param t The tile to change the tree amount + * @param c The value to add (or reduce) on the tree-count value + * @pre Tile must be of type MP_TREES + */ static inline void AddTreeCount(TileIndex t, int c) { assert(IsTileType(t, MP_TREES)); // XXX incomplete _m[t].m5 += c << 6; } +/** + * Sets the tree amount of a tile. + * + * This function directly sets the amount of trees of a tile. + * + * @param t The tile to set the amount of trees + * @param c The number of trees + * @pre Tile must be of type MP_TREES + */ static inline void SetTreeCount(TileIndex t, uint c) { assert(IsTileType(t, MP_TREES)); // XXX incomplete SB(_m[t].m5, 6, 2, c); } - +/** + * Returns the tree growth status. + * + * This function returns the tree growth status of a tile with trees. + * + * @param t The tile to get the tree growth status + * @return The tree growth status + * @pre Tile must be of type MP_TREES + */ static inline uint GetTreeGrowth(TileIndex t) { assert(IsTileType(t, MP_TREES)); return GB(_m[t].m5, 0, 3); } +/** + * Add a value to the tree growth status. + * + * This function adds a value to the tree grow status of a tile. + * + * @param t The tile to add the value on + * @param a The value to add on the tree growth status + * @pre Tile must be of type MP_TREES + */ static inline void AddTreeGrowth(TileIndex t, int a) { assert(IsTileType(t, MP_TREES)); // XXX incomplete _m[t].m5 += a; } +/** + * Sets the tree growth status of a tile. + * + * This function sets the tree growth status of a tile directly with + * the given value. + * + * @param t The tile to change the tree growth status + * @param g The new value + * @pre Tile must be of type MP_TREES + */ static inline void SetTreeGrowth(TileIndex t, uint g) { assert(IsTileType(t, MP_TREES)); // XXX incomplete SB(_m[t].m5, 0, 3, g); } - +/** + * Get the tick counter of a tree tile. + * + * Returns the saved tick counter of a given tile. + * + * @param t The tile to get the counter value from + * @pre Tile must be of type MP_TREES + */ static inline uint GetTreeCounter(TileIndex t) { assert(IsTileType(t, MP_TREES)); return GB(_m[t].m2, 0, 4); } +/** + * Add a value on the tick counter of a tree-tile + * + * This function adds a value on the tick counter of a tree-tile. + * + * @param t The tile to add the value on + * @param a The value to add on the tick counter + * @pre Tile must be of type MP_TREES + */ static inline void AddTreeCounter(TileIndex t, int a) { assert(IsTileType(t, MP_TREES)); // XXX incomplete _m[t].m2 += a; } +/** + * Set the tick counter for a tree-tile + * + * This function sets directly the tick counter for a tree-tile. + * + * @param t The tile to set the tick counter + * @param c The new tick counter value + * @pre Tile must be of type MP_TREES + */ static inline void SetTreeCounter(TileIndex t, uint c) { assert(IsTileType(t, MP_TREES)); // XXX incomplete SB(_m[t].m2, 0, 4, c); } - +/** + * Make a tree-tile. + * + * This functions change the tile to a tile with trees and all informations which belongs to it. + * + * @param t The tile to make a tree-tile from + * @param type The type of the tree + * @param set the number of trees + * @param growth the growth status + * @param ground the ground type + * @param density the density (not the number of trees) + */ static inline void MakeTree(TileIndex t, TreeType type, uint count, uint growth, TreeGround ground, uint density) { SetTileType(t, MP_TREES);