From f1f5b248c2a99f728d704b8840b6ccb2f9558986 Mon Sep 17 00:00:00 2001 From: rubidium Date: Mon, 13 Oct 2008 03:26:48 +0000 Subject: [PATCH] (svn r14461) -Document: add some doxygen comments (Albert) --- src/gfx_type.h | 5 +++-- src/landscape.cpp | 8 +++++++- src/landscape_type.h | 6 +++--- src/sprite.h | 8 +++++--- src/table/station_land.h | 27 +++++++++++++++++++++++++++ src/tile_cmd.h | 3 +++ src/tile_type.h | 2 +- src/viewport.cpp | 13 +++++++++++-- 8 files changed, 60 insertions(+), 12 deletions(-) diff --git a/src/gfx_type.h b/src/gfx_type.h index 039191a759..558519fb0c 100644 --- a/src/gfx_type.h +++ b/src/gfx_type.h @@ -12,9 +12,10 @@ typedef uint32 SpriteID; ///< The number of a sprite, without mapping bits and colortables +/** Combination of a palette sprite and a 'real' sprite */ struct PalSpriteID { - SpriteID sprite; - SpriteID pal; + SpriteID sprite; ///< The 'real' sprite + SpriteID pal; ///< The palette (use \c PAL_NONE) if not needed) }; typedef int32 CursorID; diff --git a/src/landscape.cpp b/src/landscape.cpp index 2e4e10c47a..2277bdff0c 100644 --- a/src/landscape.cpp +++ b/src/landscape.cpp @@ -67,7 +67,7 @@ const byte _tileh_to_sprite[32] = { SnowLine *_snow_line = NULL; /** - * Applys a foundation to a slope. + * Applies a foundation to a slope. * * @pre Foundation and slope must be valid combined. * @param f The #Foundation. @@ -473,6 +473,12 @@ TrackStatus GetTileTrackStatus(TileIndex tile, TransportType mode, uint sub_mode return _tile_type_procs[GetTileType(tile)]->get_tile_track_status_proc(tile, mode, sub_mode, side); } +/** + * Change the owner of a tile + * @param tile Tile to change + * @param old_owner Current owner of the tile + * @param new_owner New owner of the tile + */ void ChangeTileOwner(TileIndex tile, Owner old_owner, Owner new_owner) { _tile_type_procs[GetTileType(tile)]->change_tile_owner_proc(tile, old_owner, new_owner); diff --git a/src/landscape_type.h b/src/landscape_type.h index eb6b9e7a67..f1955f4d3d 100644 --- a/src/landscape_type.h +++ b/src/landscape_type.h @@ -5,10 +5,10 @@ #ifndef LANDSCAPE_TYPE_H #define LANDSCAPE_TYPE_H -typedef byte LandscapeID; +typedef byte LandscapeID; ///< Landscape type. @see LandscapeType -/* Landscape types */ -enum { +/** Landscape types */ +enum LandscapeType { LT_TEMPERATE = 0, LT_ARCTIC = 1, LT_TROPIC = 2, diff --git a/src/sprite.h b/src/sprite.h index 2b17554329..2fbef0c64c 100644 --- a/src/sprite.h +++ b/src/sprite.h @@ -23,8 +23,9 @@ * bounding box. Used especially for various multi-sprite buildings (like * depots or stations): */ +/** A tile child sprite and palette to draw for stations etc, with 3D bounding box */ struct DrawTileSeqStruct { - int8 delta_x; // 0x80 is sequence terminator + int8 delta_x; ///< \c 0x80 is sequence terminator int8 delta_y; int8 delta_z; byte size_x; @@ -33,9 +34,10 @@ struct DrawTileSeqStruct { PalSpriteID image; }; +/** Ground palette sprite of a tile, together with its child sprites */ struct DrawTileSprites { - PalSpriteID ground; - const DrawTileSeqStruct *seq; + PalSpriteID ground; ///< Palette and sprite for the ground + const DrawTileSeqStruct *seq; ///< Array of child sprites. Terminated with a terminator entry }; /** diff --git a/src/table/station_land.h b/src/table/station_land.h index 249b6f4824..0cad540d93 100644 --- a/src/table/station_land.h +++ b/src/table/station_land.h @@ -2,8 +2,30 @@ /** @file station_land.h Sprites to use and how to display them for station tiles. */ +/** + * Constructor macro for an image without a palette in a DrawTileSeqStruct array. + * @param dx Offset in x direction + * @param dy Offset in y direction + * @param dz Offset in z direction + * @param sx Size in x direction + * @param sy Size in y direction + * @param sz Size in z direction + * @param img Sprite to draw + */ #define TILE_SEQ_LINE(dx, dy, dz, sx, sy, sz, img) { dx, dy, dz, sx, sy, sz, {img, PAL_NONE} }, +/** + * Constructor macro for an image with a palette in a DrawTileSeqStruct array. + * @param dx Offset in x direction + * @param dy Offset in y direction + * @param dz Offset in z direction + * @param sx Size in x direction + * @param sy Size in y direction + * @param sz Size in z direction + * @param img Sprite to draw + * @param pal Paleltte sprite + */ #define TILE_SEQ_LINE_PAL(dx, dy, dz, sx, sy, sz, img, pal) { dx, dy, dz, sx, sy, sz, {img, pal} }, +/** Constructor macro for a terminating DrawTileSeqStruct entry in an array */ #define TILE_SEQ_END() { (byte)0x80, 0, 0, 0, 0, 0, {0, 0} } static const DrawTileSeqStruct _station_display_nothing[] = { @@ -995,6 +1017,11 @@ static const DrawTileSeqStruct _station_display_datas_0171[] = { #undef TILE_SEQ_LINE #undef TILE_SEQ_LINE_PAL +/** + * Constructor macro of a DrawTileSprites structure + * @param img Ground sprite without palette of the tile + * @param dtss Sequence child sprites of the tile + */ #define TILE_SPRITE_LINE(img, dtss) { {img, PAL_NONE}, dtss }, static const DrawTileSprites _station_display_datas_rail[] = { diff --git a/src/tile_cmd.h b/src/tile_cmd.h index fc6f568467..d106d5d797 100644 --- a/src/tile_cmd.h +++ b/src/tile_cmd.h @@ -102,6 +102,9 @@ typedef Foundation GetFoundationProc(TileIndex tile, Slope tileh); */ typedef CommandCost TerraformTileProc(TileIndex tile, uint32 flags, uint z_new, Slope tileh_new); +/** + * Set of callback functions for performing tile operations of a given tile type. + * @see TileType */ struct TileTypeProcs { DrawTileProc *draw_tile_proc; GetSlopeZProc *get_slope_z_proc; diff --git a/src/tile_type.h b/src/tile_type.h index 2d46a74d54..229dcee158 100644 --- a/src/tile_type.h +++ b/src/tile_type.h @@ -18,7 +18,7 @@ enum { /** - * The different type of a tile. + * The different types of tiles. * * Each tile belongs to one type, according whatever is build on it. * diff --git a/src/viewport.cpp b/src/viewport.cpp index c1e9e4d7b6..48045542ca 100644 --- a/src/viewport.cpp +++ b/src/viewport.cpp @@ -83,6 +83,7 @@ struct ChildScreenSpriteToDraw { int next; ///< next child to draw (-1 at the end) }; +/** Parent sprite that should be drawn */ struct ParentSpriteToDraw { SpriteID image; ///< sprite to draw SpriteID pal; ///< palette to use @@ -105,7 +106,7 @@ struct ParentSpriteToDraw { bool comparison_done; ///< Used during sprite sorting: true if sprite has been compared with all other sprites }; -/* Enumeration of multi-part foundations */ +/** Enumeration of multi-part foundations */ enum FoundationPart { FOUNDATION_PART_NONE = 0xFF, ///< Neither foundation nor groundsprite drawn yet. FOUNDATION_PART_NORMAL = 0, ///< First part (normal foundation or no foundation) @@ -119,13 +120,14 @@ typedef SmallVector ParentSpriteToDrawVector; typedef SmallVector ParentSpriteToSortVector; typedef SmallVector ChildScreenSpriteToDrawVector; +/** Data structure storing rendering information */ struct ViewportDrawer { DrawPixelInfo dpi; StringSpriteToDrawVector string_sprites_to_draw; TileSpriteToDrawVector tile_sprites_to_draw; ParentSpriteToDrawVector parent_sprites_to_draw; - ParentSpriteToSortVector parent_sprites_to_sort; + ParentSpriteToSortVector parent_sprites_to_sort; ///< Parent sprite pointer array used for sorting ChildScreenSpriteToDrawVector child_screen_sprites_to_draw; int *last_child; @@ -356,6 +358,12 @@ ViewPort *IsPtInWindowViewport(const Window *w, int x, int y) return NULL; } +/** + * Translate screen coordinate in a viewport to a tile coordinate + * @param vp Viewport that contains the (\a x, \a y) screen coordinate + * @param x Screen x coordinate + * @param y Screen y coordinate + * @return Tile coordinate */ static Point TranslateXYToTileCoord(const ViewPort *vp, int x, int y) { Point pt; @@ -1286,6 +1294,7 @@ static void ViewportDrawTileSprites(const TileSpriteToDrawVector *tstdv) } } +/** Sort parent sprites pointer array */ static void ViewportSortParentSprites(ParentSpriteToSortVector *psdv) { ParentSpriteToDraw **psdvend = psdv->End();