(svn r11065) -Documentation [FS#1186]: of the dirty marking/repainting subsystem. Patch by Progman.

14 files changed, 187 insertions, 10 deletions

diff --git a/src/clear_cmd.cpp b/src/clear_cmd.cpp
index 1fd1ba304..047f003c3 100644
--- a/src/clear_cmd.cpp
+++ b/src/clear_cmd.cpp
@@ -47,7 +47,14 @@ struct TerraformerState {
 	int modheight_count;                                         ///< amount of entries in "modheight".
 	int tile_table_count;                                        ///< amount of entries in "tile_table".
 
-	TileIndex tile_table[TERRAFORMER_TILE_TABLE_SIZE];           ///< Dirty tiles, i.e. at least one corner changed.
+	/**
+	 * Dirty tiles, i.e.\ at least one corner changed.
+	 *
+	 * This array contains the tiles which are or will be marked as dirty.
+	 *
+	 * @ingroup dirty
+	 */
+	TileIndex tile_table[TERRAFORMER_TILE_TABLE_SIZE];
 	TerraformerHeightMod modheight[TERRAFORMER_MODHEIGHT_SIZE];  ///< Height modifications.
 };
 
@@ -106,6 +113,7 @@ static void TerraformSetHeightOfTile(TerraformerState *ts, TileIndex tile, int h
  *
  * @param ts TerraformerState.
  * @param tile Tile.
+ * @ingroup dirty
  */
 static void TerraformAddDirtyTile(TerraformerState *ts, TileIndex tile)
 {
@@ -128,6 +136,7 @@ static void TerraformAddDirtyTile(TerraformerState *ts, TileIndex tile)
  *
  * @param ts TerraformerState.
  * @param tile Tile.
+ * @ingroup dirty
  */
 static void TerraformAddDirtyTileAround(TerraformerState *ts, TileIndex tile)
 {
diff --git a/src/functions.h b/src/functions.h
index bcefb13c6..c3e7a3a70 100644
--- a/src/functions.h
+++ b/src/functions.h
@@ -103,7 +103,18 @@ StringID RealAllocateName(const char *name, byte skip, bool check_double);
 void ConvertNameArray();
 
 /* misc functions */
+/**
+ * Mark a tile given by its coordinate dirty for repaint.
+ *
+ * @ingroup dirty
+ */
 void MarkTileDirty(int x, int y);
+
+/**
+ * Mark a tile given by its index dirty for repaint.
+ *
+ * @ingroup dirty
+ */
 void MarkTileDirtyByTile(TileIndex tile);
 void InvalidateWindow(WindowClass cls, WindowNumber number);
 void InvalidateWindowWidget(WindowClass cls, WindowNumber number, byte widget_index);
@@ -124,6 +135,12 @@ bool ScrollMainWindowTo(int x, int y, bool instant = false);
 void DrawSprite(SpriteID img, SpriteID pal, int x, int y);
 bool EnsureNoVehicle(TileIndex tile);
 bool EnsureNoVehicleOnGround(TileIndex tile);
+
+/**
+ * Mark all viewports dirty for repaint.
+ *
+ * @ingroup dirty
+ */
 void MarkAllViewportsDirty(int left, int top, int right, int bottom);
 void ShowCostOrIncomeAnimation(int x, int y, int z, Money cost);
 void ShowFeederIncomeAnimation(int x, int y, int z, Money cost);
diff --git a/src/gfx.cpp b/src/gfx.cpp
index 25c60dba0..8a1b9741c 100644
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -48,6 +48,14 @@ static void GfxMainBlitter(const Sprite *sprite, int x, int y, BlitterMode mode)
 FontSize _cur_fontsize;
 static FontSize _last_fontsize;
 static uint8 _cursor_backup[64 * 64 * 4];
+
+/**
+ * The rect for repaint.
+ *
+ * This rectangle defines the area which should be repaint by the video driver.
+ *
+ * @ingroup dirty
+ */
 static Rect _invalid_rect;
 static const byte *_color_remap_ptr;
 static byte _string_colorremap[3];
@@ -269,7 +277,8 @@ void DrawStringCenterUnderlineTruncated(int xl, int xr, int y, StringID str, uin
 	GfxFillRect((xl + xr - w) / 2, y + 10, (xl + xr + w) / 2, y + 10, _string_colorremap[1]);
 }
 
-/** 'Correct' a string to a maximum length. Longer strings will be cut into
+/**
+ * 'Correct' a string to a maximum length. Longer strings will be cut into
  * additional lines at whitespace characters if possible. The string parameter
  * is modified with terminating characters mid-string which are the
  * placeholders for the newlines.
@@ -284,7 +293,8 @@ void DrawStringCenterUnderlineTruncated(int xl, int xr, int y, StringID str, uin
  * @param maxw the maximum width the string can have on one line
  * @return return a 32bit wide number consisting of 2 packed values:
  *  0 - 15 the number of lines ADDED to the string
- * 16 - 31 the fontsize in which the length calculation was done at */
+ * 16 - 31 the fontsize in which the length calculation was done at
+ */
 uint32 FormatStringLinebreaks(char *str, int maxw)
 {
 	FontSize size = _cur_fontsize;
@@ -919,6 +929,11 @@ void RedrawScreenRect(int left, int top, int right, int bottom)
 	_video_driver->MakeDirty(left, top, right - left, bottom - top);
 }
 
+/*!
+ * Repaints the rectangle blocks which are marked as 'dirty'.
+ *
+ * @see SetDirtyBlocks
+ */
 void DrawDirtyBlocks()
 {
 	byte *b = _dirty_blocks;
@@ -1003,7 +1018,21 @@ void DrawDirtyBlocks()
 	}
 }
 
-
+/*!
+ * This function extends the internal _invalid_rect rectangle as it
+ * now contains the rectangle defined by the given parameters. Note
+ * the point (0,0) is top left.
+ *
+ * @param left The left edge of the rectangle
+ * @param top The top edge of the rectangle
+ * @param right The right edge of the rectangle
+ * @param bottom The bottm edge of the rectangle
+ * @see DrawDirtyBlocks
+ *
+ * @todo The name of the function should be called like @c AddDirtyBlock as
+ *       it neither set a dirty rect nor add several dirty rects although
+ *       the function name is in plural. (Progman)
+ */
 void SetDirtyBlocks(int left, int top, int right, int bottom)
 {
 	byte *b;
@@ -1041,6 +1070,11 @@ void SetDirtyBlocks(int left, int top, int right, int bottom)
 	} while (--height != 0);
 }
 
+/*!
+ * This function mark the whole screen as dirty. This results in repainting
+ * the whole screen. Use this with care as this function will break the
+ * idea about marking only parts of the screen as 'dirty'.
+ */
 void MarkWholeScreenDirty()
 {
 	SetDirtyBlocks(0, 0, _screen.width, _screen.height);
diff --git a/src/gfx.h b/src/gfx.h
index b48a7ba8f..f54c1fcd9 100644
--- a/src/gfx.h
+++ b/src/gfx.h
@@ -2,6 +2,36 @@
 
 /** @file gfx.h */
 
+/**
+ * @defgroup dirty Dirty
+ *
+ * Handles the repaint of some part of the screen.
+ *
+ * Some places in the code are called functions which makes something "dirty".
+ * This has nothing to do with making a Tile or Window darker or less visible.
+ * This term comes from memory caching and is used to define an object must
+ * be repaint. If some data of an object (like a Tile, Window, Vehicle, whatever)
+ * are changed which are so extensive the object must be repaint its marked
+ * as "dirty". The video driver repaint this object instead of the whole screen
+ * (this is btw. also possible if needed). This is used to avoid a
+ * flickering of the screen by the video driver constantly repainting it.
+ *
+ * This whole mechanism is controlled by an rectangle defined in #_invalid_rect. This
+ * rectangle defines the area on the screen which must be repaint. If a new object
+ * needs to be repainted this rectangle is extended to 'catch' the object on the
+ * screen. At some point (which is normaly uninteressted for patch writers) this
+ * rectangle is send to the video drivers method
+ * VideoDriver::MakeDirty and it is truncated back to an empty rectangle. At some
+ * later point (which is uninteressted, too) the video driver
+ * repaints all these saved rectangle instead of the whole screen and drop the
+ * rectangle informations. Then a new round begins by marking objects "dirty".
+ *
+ * @see VideoDriver::MakeDirty
+ * @see _invalid_rect
+ * @see _screen
+ */
+
+
 #ifndef GFX_H
 #define GFX_H
 
@@ -244,8 +274,26 @@ uint32 FormatStringLinebreaks(char *str, int maxw);
 void LoadStringWidthTable();
 void DrawStringMultiCenter(int x, int y, StringID str, int maxw);
 uint DrawStringMultiLine(int x, int y, StringID str, int maxw, int maxh = -1);
+
+/**
+ * Let the dirty blocks repainting by the video driver.
+ *
+ * @ingroup dirty
+ */
 void DrawDirtyBlocks();
+
+/**
+ * Set a new dirty block.
+ *
+ * @ingroup dirty
+ */
 void SetDirtyBlocks(int left, int top, int right, int bottom);
+
+/**
+ * Marks the whole screen as dirty.
+ *
+ * @ingroup dirty
+ */
 void MarkWholeScreenDirty();
 
 void GfxInitPalettes();
diff --git a/src/signs.cpp b/src/signs.cpp
index 0004a65d8..d4ef7f763 100644
--- a/src/signs.cpp
+++ b/src/signs.cpp
@@ -60,10 +60,12 @@ void UpdateAllSignVirtCoords()
 }
 
 /**
+ * Marks the region of a sign as dirty.
  *
- * Marks the region of a sign as dirty
+ * This function marks the sign in all viewports as dirty for repaint.
  *
  * @param si Pointer to the Sign
+ * @ingroup dirty
  */
 static void MarkSignDirty(Sign *si)
 {
diff --git a/src/station.h b/src/station.h
index bbae591d6..fefca32fa 100644
--- a/src/station.h
+++ b/src/station.h
@@ -173,7 +173,19 @@ public:
 	virtual ~Station();
 
 	void AddFacility(byte new_facility_bit, TileIndex facil_xy);
+
+	/**
+	 * Mark the sign of a station dirty for repaint.
+	 *
+	 * @ingroup dirty
+	 */
 	void MarkDirty() const;
+
+	/**
+	 * Marks the tiles of the station as dirty.
+	 *
+	 * @ingroup dirty
+	 */
 	void MarkTilesDirty(bool cargo_change) const;
 	bool TileBelongsToRailStation(TileIndex tile) const;
 	uint GetPlatformLength(TileIndex tile, DiagDirection dir) const;
diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
index 4f75d932f..6e9993f8a 100644
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -375,7 +375,14 @@ void UpdateAllStationVirtCoord()
 	}
 }
 
-// Update the station virt coords while making the modified parts dirty.
+/**
+ * Update the station virt coords while making the modified parts dirty.
+ *
+ * This function updates the virt coords and mark the modified parts as dirty
+ *
+ * @param st The station to update the virt coords
+ * @ingroup dirty
+ */
 static void UpdateStationVirtCoordDirty(Station *st)
 {
 	st->MarkDirty();
diff --git a/src/texteff.cpp b/src/texteff.cpp
index e754a2f28..2bdd05c3d 100644
--- a/src/texteff.cpp
+++ b/src/texteff.cpp
@@ -256,7 +256,15 @@ void DrawChatMessage()
 	_chatmessage_dirty = false;
 }
 
-/** Text Effects */
+/* Text Effects */
+/**
+ * Mark the area of the text effect as dirty.
+ *
+ * This function marks the area of a text effect as dirty for repaint.
+ *
+ * @param te The TextEffect to mark the area dirty
+ * @ingroup dirty
+ */
 static void MarkTextEffectAreaDirty(TextEffect *te)
 {
 	/* Width and height of the text effect are doubled, so they are correct in both zoom out levels 1x and 2x. */
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
index 5759189d2..c2d87cb6c 100644
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -256,8 +256,12 @@ static bool IsCloseToTown(TileIndex tile, uint dist)
 }
 
 /**
- * Marks the town sign as needing a repaint
- * @param t Town requesting repaint
+ * Marks the town sign as needing a repaint.
+ *
+ * This function marks the area of the sign of a town as dirty for repaint.
+ *
+ * @param t Town requesting town sign for repaint
+ * @ingroup dirty
  */
 static void MarkTownSignDirty(Town *t)
 {
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index 4728f10dc..8d257b1a8 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -1491,7 +1491,7 @@ void AgeVehicle(Vehicle *v)
 		ShowVehicleGettingOld(v, STR_01A0_IS_GETTING_OLD);
 	} else if (age == 0) {
 		ShowVehicleGettingOld(v, STR_01A1_IS_GETTING_VERY_OLD);
-	} else if ((age % 366) == 0) {
+	} else if (age > 0 && (age % 366) == 0) {
 		ShowVehicleGettingOld(v, STR_01A2_IS_GETTING_VERY_OLD_AND);
 	}
 }
diff --git a/src/vehicle.h b/src/vehicle.h
index c9a805593..509a87e4c 100644
--- a/src/vehicle.h
+++ b/src/vehicle.h
@@ -384,6 +384,11 @@ public:
 
 	/**
 	 * Marks the vehicles to be redrawn and updates cached variables
+	 *
+	 * This method marks the area of the vehicle on the screen as dirty.
+	 * It can be use to repaint the vehicle.
+	 *
+	 * @ingroup dirty
 	 */
 	virtual void MarkDirty() {}
 
diff --git a/src/viewport.cpp b/src/viewport.cpp
index 50297c1c5..f52c8b6ed 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -1440,6 +1440,14 @@ void UpdateViewportPosition(Window *w)
 	}
 }
 
+/**
+ * Marks a viewport as dirty for repaint.
+ *
+ * @param vp The viewport to mark as dirty
+ * @todo documents the missing parameters @c left, @c top, @c right and @c bottom
+ * @todo detailed description missing
+ * @ingroup dirty
+ */
 static void MarkViewportDirty(const ViewPort *vp, int left, int top, int right, int bottom)
 {
 	right -= vp->virtual_left;
@@ -1505,6 +1513,14 @@ void MarkTileDirty(int x, int y)
 	);
 }
 
+/**
+ * Marks the selected tiles as dirty.
+ *
+ * This function marks the selected tiles as dirty for repaint
+ *
+ * @note Documentation may be wrong (Progman)
+ * @ingroup dirty
+ */
 static void SetSelectionTilesDirty()
 {
 	int y_size, x_size;
diff --git a/src/water_cmd.cpp b/src/water_cmd.cpp
index c0f620cbf..2e381e3eb 100644
--- a/src/water_cmd.cpp
+++ b/src/water_cmd.cpp
@@ -183,6 +183,15 @@ static CommandCost RemoveShiplift(TileIndex tile, uint32 flags)
 	return CommandCost(_price.clear_water * 2);
 }
 
+/**
+ * Marks the tiles around a tile as dirty.
+ *
+ * This functions marks the tiles around a given tile as dirty for repaint.
+ *
+ * @param tile The center of the tile where all other tiles are marked as dirty
+ * @ingroup dirty
+ * @see TerraformAddDirtyTileAround
+ */
 static void MarkTilesAroundDirty(TileIndex tile)
 {
 	MarkTileDirtyByTile(TILE_ADDXY(tile, 0, 1));
diff --git a/src/window.h b/src/window.h
index 8af918631..593016807 100644
--- a/src/window.h
+++ b/src/window.h
@@ -565,6 +565,12 @@ enum WindowFlags {
 /* window.cpp */
 void CallWindowEventNP(Window *w, int event);
 void CallWindowTickEvent();
+
+/**
+ * Marks the window as dirty for repaint.
+ *
+ * @ingroup dirty
+ */
 void SetWindowDirty(const Window *w);
 void SendWindowMessage(WindowClass wnd_class, WindowNumber wnd_num, int msg, int wparam, int lparam);
 void SendWindowMessageClass(WindowClass wnd_class, int msg, int wparam, int lparam);