summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorrubidium <rubidium@openttd.org>2007-09-09 10:13:17 +0000
committerrubidium <rubidium@openttd.org>2007-09-09 10:13:17 +0000
commit65f9a0f21a1379107683f7b5f2fc0c82f22a4cb6 (patch)
tree43502b2af33d4a35c7e2e2fbd6f29b3cc60b4ba8 /src
parentef4d248325114b5cc3fb864f7105b44a7784be50 (diff)
downloadopenttd-65f9a0f21a1379107683f7b5f2fc0c82f22a4cb6.tar.xz
(svn r11065) -Documentation [FS#1186]: of the dirty marking/repainting subsystem. Patch by Progman.
Diffstat (limited to 'src')
-rw-r--r--src/clear_cmd.cpp11
-rw-r--r--src/functions.h17
-rw-r--r--src/gfx.cpp40
-rw-r--r--src/gfx.h48
-rw-r--r--src/signs.cpp4
-rw-r--r--src/station.h12
-rw-r--r--src/station_cmd.cpp9
-rw-r--r--src/texteff.cpp10
-rw-r--r--src/town_cmd.cpp8
-rw-r--r--src/vehicle.cpp2
-rw-r--r--src/vehicle.h5
-rw-r--r--src/viewport.cpp16
-rw-r--r--src/water_cmd.cpp9
-rw-r--r--src/window.h6
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);