summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorsmatz <smatz@openttd.org>2010-01-18 14:58:32 +0000
committersmatz <smatz@openttd.org>2010-01-18 14:58:32 +0000
commita39a446e8faf99568eb8924535fd0034db00bb8e (patch)
treeb042afa6a471188d704e48567abe817f70fd1c72
parenta1f28ec88bf3987236fb1b9df9c9dbe8c68419b7 (diff)
downloadopenttd-a39a446e8faf99568eb8924535fd0034db00bb8e.tar.xz
(svn r18861) -Doc: more doxygen documentation in genworld files
-rw-r--r--src/genworld.cpp20
-rw-r--r--src/genworld.h16
-rw-r--r--src/genworld_gui.cpp100
3 files changed, 75 insertions, 61 deletions
diff --git a/src/genworld.cpp b/src/genworld.cpp
index 9f479210b..973bf89ff 100644
--- a/src/genworld.cpp
+++ b/src/genworld.cpp
@@ -48,10 +48,12 @@ void StartupDisasters();
void InitializeGame(uint size_x, uint size_y, bool reset_date, bool reset_settings);
-/* Please only use this variable in genworld.h and genworld.cpp and
+/**
+ * Please only use this variable in genworld.h and genworld.cpp and
* nowhere else. For speed improvements we need it to be global, but
* in no way the meaning of it is to use it anywhere else besides
- * in the genworld.h and genworld.cpp! -- TrueLight */
+ * in the genworld.h and genworld.cpp! -- TrueLight
+ */
GenWorldInfo _gw;
/** Rights for the map generation */
@@ -61,6 +63,7 @@ ThreadMutex *_genworld_paint_mutex = ThreadMutex::New();
/**
* Tells if the world generation is done in a thread or not.
+ * @return the 'threaded' status
*/
bool IsGenerateWorldThreaded()
{
@@ -91,7 +94,7 @@ static void CleanupGeneration()
/**
* The internal, real, generate function.
*/
-static void _GenerateWorld(void *arg)
+static void _GenerateWorld(void *)
{
try {
_generating_world = true;
@@ -190,7 +193,8 @@ static void _GenerateWorld(void *arg)
/**
* Set here the function, if any, that you want to be called when landscape
- * generation is done.
+ * generation is done.
+ * @param proc callback procedure
*/
void GenerateWorldSetCallback(GWDoneProc *proc)
{
@@ -199,7 +203,8 @@ void GenerateWorldSetCallback(GWDoneProc *proc)
/**
* Set here the function, if any, that you want to be called when landscape
- * generation is aborted.
+ * generation is aborted.
+ * @param proc callback procedure
*/
void GenerateWorldSetAbortCallback(GWAbortProc *proc)
{
@@ -208,7 +213,7 @@ void GenerateWorldSetAbortCallback(GWAbortProc *proc)
/**
* This will wait for the thread to finish up his work. It will not continue
- * till the work is done.
+ * till the work is done.
*/
void WaitTillGeneratedWorld()
{
@@ -235,6 +240,7 @@ void AbortGeneratingWorld()
/**
* Is the generation being aborted?
+ * @return the 'aborted' status
*/
bool IsGeneratingWorldAborted()
{
@@ -261,7 +267,7 @@ void HandleGeneratingWorldAbortion()
/**
* Generate a world.
- * @param mode The mode of world generation (see GenerateWorldModes).
+ * @param mode The mode of world generation (see GenWorldMode).
* @param size_x The X-size of the map.
* @param size_y The Y-size of the map.
* @param reset_settings Whether to reset the game configuration (used for restart)
diff --git a/src/genworld.h b/src/genworld.h
index 591f6ef61..a4399097e 100644
--- a/src/genworld.h
+++ b/src/genworld.h
@@ -14,11 +14,10 @@
#include "company_type.h"
-/*
- * Order of these enums has to be the same as in lang/english.txt
- * Otherwise you will get inconsistent behaviour.
- */
+/** Constants related to world generation */
enum {
+ /* Order of these enums has to be the same as in lang/english.txt
+ * Otherwise you will get inconsistent behaviour. */
LG_ORIGINAL = 0, ///< The original landscape generator
LG_TERRAGENESIS = 1, ///< TerraGenesis Perlin landscape generator
@@ -27,7 +26,7 @@ enum {
GENWORLD_REDRAW_TIMEOUT = 200, ///< Timeout between redraws
};
-/* Modes for GenerateWorld */
+/** Modes for GenerateWorld */
enum GenWorldMode {
GWM_NEWGAME = 0, ///< Generate a map for a new game
GWM_EMPTY = 1, ///< Generate an empty map (sea-level)
@@ -35,9 +34,10 @@ enum GenWorldMode {
GWM_HEIGHTMAP = 3, ///< Generate a newgame from a heightmap
};
-typedef void GWDoneProc();
-typedef void GWAbortProc();
+typedef void GWDoneProc(); ///< Procedure called when the genworld process finishes
+typedef void GWAbortProc(); ///< Called when genworld is aborted
+/** Properties of current genworld process */
struct GenWorldInfo {
bool active; ///< Is generating world active
bool abort; ///< Whether to abort the thread ASAP
@@ -52,6 +52,7 @@ struct GenWorldInfo {
class ThreadObject *thread; ///< The thread we are in (can be NULL)
};
+/** Current stage of world generation process */
enum GenWorldProgress {
GWP_MAP_INIT, ///< Initialize/allocate the map, start economy
GWP_LANDSCAPE, ///< Create the landscape
@@ -68,6 +69,7 @@ enum GenWorldProgress {
/**
* Check if we are currently in the process of generating a world.
+ * @return are we generating world?
*/
static inline bool IsGeneratingWorld()
{
diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp
index 970c34add..c5432bcd1 100644
--- a/src/genworld_gui.cpp
+++ b/src/genworld_gui.cpp
@@ -40,15 +40,18 @@
* In what 'mode' the GenerateLandscapeWindowProc is.
*/
enum GenenerateLandscapeWindowMode {
- GLWM_GENERATE,
- GLWM_HEIGHTMAP,
- GLWM_SCENARIO,
- GLWM_END
+ GLWM_GENERATE, ///< Generate new game
+ GLWM_HEIGHTMAP, ///< Load from heightmap
+ GLWM_SCENARIO, ///< Generate flat land
};
extern void SwitchToMode(SwitchMode new_mode);
extern void MakeNewgameSettingsLive();
+/**
+ * Changes landscape type and sets genworld window dirty
+ * @param landscape new landscape type
+ */
static inline void SetNewLandscapeType(byte landscape)
{
_settings_newgame.game_creation.landscape = landscape;
@@ -56,51 +59,53 @@ static inline void SetNewLandscapeType(byte landscape)
SetWindowClassesDirty(WC_GENERATE_LANDSCAPE);
}
+/** Widgets of GenerateLandscapeWindow */
enum GenerateLandscapeWindowWidgets {
- GLAND_TEMPERATE,
- GLAND_ARCTIC,
- GLAND_TROPICAL,
- GLAND_TOYLAND,
-
- GLAND_MAPSIZE_X_PULLDOWN,
- GLAND_MAPSIZE_Y_PULLDOWN,
-
- GLAND_TOWN_PULLDOWN,
- GLAND_INDUSTRY_PULLDOWN,
-
- GLAND_RANDOM_EDITBOX,
- GLAND_RANDOM_BUTTON,
-
- GLAND_GENERATE_BUTTON,
-
- GLAND_START_DATE_DOWN,
- GLAND_START_DATE_TEXT,
- GLAND_START_DATE_UP,
-
- GLAND_SNOW_LEVEL_DOWN,
- GLAND_SNOW_LEVEL_TEXT,
- GLAND_SNOW_LEVEL_UP,
-
- GLAND_TREE_PULLDOWN,
- GLAND_LANDSCAPE_PULLDOWN,
- GLAND_HEIGHTMAP_NAME_TEXT,
- GLAND_HEIGHTMAP_NAME_SPACER,
- GLAND_HEIGHTMAP_SIZE_TEXT,
- GLAND_HEIGHTMAP_ROTATION_PULLDOWN,
-
- GLAND_TERRAIN_PULLDOWN,
- GLAND_WATER_PULLDOWN,
- GLAND_SMOOTHNESS_PULLDOWN,
- GLAND_VARIETY_PULLDOWN,
-
- GLAND_BORDER_TYPES,
- GLAND_BORDERS_RANDOM,
- GLAND_WATER_NW,
- GLAND_WATER_NE,
- GLAND_WATER_SE,
- GLAND_WATER_SW,
+ GLAND_TEMPERATE, ///< Button with icon "Temperate"
+ GLAND_ARCTIC, ///< Button with icon "Arctic"
+ GLAND_TROPICAL, ///< Button with icon "Tropical"
+ GLAND_TOYLAND, ///< Button with icon "Toyland"
+
+ GLAND_MAPSIZE_X_PULLDOWN, ///< Dropdown 'map X size'
+ GLAND_MAPSIZE_Y_PULLDOWN, ///< Dropdown 'map Y size'
+
+ GLAND_TOWN_PULLDOWN, ///< Dropdown 'No. of towns'
+ GLAND_INDUSTRY_PULLDOWN, ///< Dropdown 'No. of industries'
+
+ GLAND_RANDOM_EDITBOX, ///< 'Random seed' editbox
+ GLAND_RANDOM_BUTTON, ///< 'Randomise' button
+
+ GLAND_GENERATE_BUTTON, ///< 'Generate' button
+
+ GLAND_START_DATE_DOWN, ///< Decrease start year
+ GLAND_START_DATE_TEXT, ///< Start year
+ GLAND_START_DATE_UP, ///< Increase start year
+
+ GLAND_SNOW_LEVEL_DOWN, ///< Docrease snow level
+ GLAND_SNOW_LEVEL_TEXT, ///< Snow level
+ GLAND_SNOW_LEVEL_UP, ///< Increase snow level
+
+ GLAND_TREE_PULLDOWN, ///< Dropdown 'Tree algorithm'
+ GLAND_LANDSCAPE_PULLDOWN, ///< Dropdown 'Land generator'
+
+ GLAND_HEIGHTMAP_NAME_TEXT, ///< Heightmap name
+ GLAND_HEIGHTMAP_NAME_SPACER, ///< Spacer used for aligning items in the second column nicely
+ GLAND_HEIGHTMAP_SIZE_TEXT, ///< Size of heightmap
+ GLAND_HEIGHTMAP_ROTATION_PULLDOWN, ///< Dropdown 'Heightmap rotation'
+
+ GLAND_TERRAIN_PULLDOWN, ///< Dropdown 'Terrain type'
+ GLAND_WATER_PULLDOWN, ///< Dropdown 'Sea level'
+ GLAND_SMOOTHNESS_PULLDOWN, ///< Dropdown 'Smoothness'
+ GLAND_VARIETY_PULLDOWN, ///< Dropdown 'Variety distribution'
+
+ GLAND_BORDERS_RANDOM, ///< 'Random'/'Manual' borders
+ GLAND_WATER_NW, ///< NW 'Water'/'Freeform'
+ GLAND_WATER_NE, ///< NE 'Water'/'Freeform'
+ GLAND_WATER_SE, ///< SE 'Water'/'Freeform'
+ GLAND_WATER_SW, ///< SW 'Water'/'Freeform'
};
+/** Widgets of GenerateLandscapeWindow when generating world */
static const NWidgetPart _nested_generate_landscape_widgets[] = {
NWidget(NWID_HORIZONTAL),
NWidget(WWT_CLOSEBOX, COLOUR_BROWN),
@@ -133,7 +138,7 @@ static const NWidgetPart _nested_generate_landscape_widgets[] = {
NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_QUANTITY_OF_SEA_LAKES, STR_NULL), SetFill(1, 1),
NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_TREE_PLACER, STR_NULL), SetFill(1, 1),
NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_VARIETY, STR_NULL), SetFill(1, 1),
- NWidget(WWT_TEXT, COLOUR_ORANGE, GLAND_BORDER_TYPES), SetDataTip(STR_MAPGEN_BORDER_TYPE, STR_NULL), SetFill(1, 1),
+ NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_BORDER_TYPE, STR_NULL), SetFill(1, 1),
EndContainer(),
/* Widgets at the right of the labels. */
NWidget(NWID_VERTICAL, NC_EQUALSIZE), SetPIP(0, 4, 0),
@@ -213,6 +218,7 @@ static const NWidgetPart _nested_generate_landscape_widgets[] = {
EndContainer(),
};
+/** Widgets of GenerateLandscapeWindow when loading heightmap */
static const NWidgetPart _nested_heightmap_load_widgets[] = {
/* Window header. */
NWidget(NWID_HORIZONTAL),