From 187a021b304ffb1bac01579d8c46ac8f4aae075d Mon Sep 17 00:00:00 2001 From: Anders Jenbo Date: Mon, 30 Mar 2020 11:31:36 +0200 Subject: [PATCH] More documentation from sanctuary/notes (#2026) --- Source/automap.cpp | 8 +++++++- Source/control.cpp | 41 ++++++++++++++++++++++++++++++----------- Source/diablo.cpp | 9 ++++++++- Source/effects.cpp | 2 ++ Source/gamemenu.cpp | 5 +++++ Source/gmenu.cpp | 3 ++- Source/inv.cpp | 18 +++++++++++++++++- Source/itemdat.cpp | 4 ++++ Source/minitext.cpp | 9 ++++++++- Source/multi.cpp | 8 ++++++++ Source/objdat.cpp | 6 ++++-- Source/scrollrt.h | 2 +- Source/textdat.cpp | 1 + 13 files changed, 97 insertions(+), 19 deletions(-) diff --git a/Source/automap.cpp b/Source/automap.cpp index d94d87bb0..f4c6286e7 100644 --- a/Source/automap.cpp +++ b/Source/automap.cpp @@ -5,13 +5,19 @@ */ #include "all.h" -// BUGFIX: only the first 256 elements are ever read +/** + * Maps from tile_id to automap type. + * BUGFIX: only the first 256 elements are ever read + */ WORD automaptype[512]; static int AutoMapX; static int AutoMapY; +/** Specifies whether the automap is enabled. */ BOOL automapflag; char AmShiftTab[31]; +/** Tracks the explored areas of the map. */ BOOLEAN automapview[DMAXX][DMAXY]; +/** Specifies the scale of the automap. */ int AutoMapScale; int AutoMapXOfs; int AutoMapYOfs; diff --git a/Source/control.cpp b/Source/control.cpp index 30f4ebf9a..176bf0da2 100644 --- a/Source/control.cpp +++ b/Source/control.cpp @@ -63,6 +63,7 @@ BOOL panbtndown; BYTE *pTalkPanel; BOOL spselflag; +/** Maps from font index to smaltext.cel frame number. */ const BYTE fontframe[128] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, @@ -73,6 +74,12 @@ const BYTE fontframe[128] = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 40, 66, 41, 67, 0 }; + +/** + * Maps from smaltext.cel frame number to character width. Note, the + * character width may be distinct from the frame width, which is 13 for every + * smaltext.cel frame. + */ const BYTE fontkern[68] = { 8, 10, 7, 9, 8, 7, 6, 8, 8, 3, 3, 8, 6, 11, 9, 10, 6, 9, 9, 6, @@ -83,36 +90,36 @@ const BYTE fontkern[68] = { 4, 4, 9, 6, 6, 12, 3, 7 }; /** - * Line height for info box when displaying 1, 2, 3, 4 and 5 lines respectivly + * Line start position for info box text when displaying 1, 2, 3, 4 and 5 lines respectivly */ const int lineOffsets[5][5] = { { SCREENXY(177, 434), - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32 + 180, + SCREENXY(-64, -128), + SCREENXY(-64, -128), + SCREENXY(-64, -128), + SCREENXY(116, -128), }, { SCREENXY(177, 422), SCREENXY(177, 446), - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32, + SCREENXY(-64, -128), + SCREENXY(-64, -128), + SCREENXY(-64, -128), }, { SCREENXY(177, 416), SCREENXY(177, 434), SCREENXY(177, 452), - BUFFER_WIDTH * 32, - BUFFER_WIDTH * 32, + SCREENXY(-64, -128), + SCREENXY(-64, -128), }, { SCREENXY(177, 412), SCREENXY(177, 427), SCREENXY(177, 441), SCREENXY(177, 456), - BUFFER_WIDTH * 32, + SCREENXY(-64, -128), }, { SCREENXY(177, 410), @@ -122,6 +129,12 @@ const int lineOffsets[5][5] = { SCREENXY(177, 457), } }; + +/** + * Maps ASCII character code to font index, as used by the + * small, medium and large sized fonts; which corresponds to smaltext.cel, + * medtexts.cel and bigtgold.cel respectively. + */ const BYTE gbFontTransTbl[256] = { // clang-format off '\0', 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, @@ -145,6 +158,7 @@ const BYTE gbFontTransTbl[256] = { /* data */ +/** Maps from spell_id to spelicon.cel frame number. */ char SpellITbl[MAX_SPELLS] = { 1, 1, @@ -184,6 +198,7 @@ char SpellITbl[MAX_SPELLS] = { 36, 30, }; +/** Maps from panel_button_id to the position and dimensions of a panel button. */ int PanBtnPos[8][5] = { // clang-format off { PANEL_LEFT + 9, PANEL_TOP + 9, 71, 19, 1 }, // char button @@ -196,7 +211,9 @@ int PanBtnPos[8][5] = { { PANEL_LEFT + 527, PANEL_TOP + 91, 33, 32, 1 }, // friendly fire button // clang-format on }; +/** Maps from panel_button_id to hotkey name. */ char *PanBtnHotKey[8] = { "'c'", "'q'", "Tab", "Esc", "'i'", "'b'", "Enter", NULL }; +/** Maps from panel_button_id to panel button description. */ char *PanBtnStr[8] = { "Character Information", "Quests log", @@ -207,6 +224,7 @@ char *PanBtnStr[8] = { "Send Message", "Player Attack" }; +/** Maps from attribute_id to the rectangle on screen used for attribute increment buttons. */ RECT32 ChrBtnsRect[4] = { { 137, 138, 41, 22 }, { 137, 166, 41, 22 }, @@ -214,6 +232,7 @@ RECT32 ChrBtnsRect[4] = { { 137, 223, 41, 22 } }; +/** Maps from spellbook page number and position to spell_id. */ int SpellPages[6][7] = { { SPL_NULL, SPL_FIREBOLT, SPL_CBOLT, SPL_HBOLT, SPL_HEAL, SPL_HEALOTHER, SPL_FLAME }, { SPL_RESURRECT, SPL_FIREWALL, SPL_TELEKINESIS, SPL_LIGHTNING, SPL_TOWN, SPL_FLASH, SPL_STONE }, diff --git a/Source/diablo.cpp b/Source/diablo.cpp index 7a167b4be..df156c0a7 100644 --- a/Source/diablo.cpp +++ b/Source/diablo.cpp @@ -43,6 +43,10 @@ int color_cycle_timer; /* rdata */ +/** + * Specifies whether to give the game exclusive access to the + * screen, as needed for efficient rendering in fullscreen mode. + */ BOOL fullscreen = TRUE; #ifdef _DEBUG int showintrodebug = 1; @@ -62,6 +66,7 @@ int frameend; int framerate; int framestart; #endif +/** Specifies whether players are in non-PvP mode. */ BOOL FriendlyMode = TRUE; /** Default quick messages */ char *spszMsgTbl[4] = { @@ -1238,7 +1243,9 @@ void diablo_pause_game() } } -/* NOTE: `return` must be used instead of `break` to be bin exact as C++ */ +/** + * @internal `return` must be used instead of `break` to be bin exact as C++ + */ void PressChar(int vkey) { if (gmenu_is_active() || control_talk_last_key(vkey) || sgnTimeoutCurs != 0 || deathflag) { diff --git a/Source/effects.cpp b/Source/effects.cpp index d8c0b09b9..9285a0121 100644 --- a/Source/effects.cpp +++ b/Source/effects.cpp @@ -8,7 +8,9 @@ int sfxdelay; int sfxdnum; +/** A handle to the current sound effect playing. */ HANDLE sghStream; +/** Specifies the sound file and the playback state of the current sound effect. */ TSFX *sgpStreamSFX; /** diff --git a/Source/gamemenu.cpp b/Source/gamemenu.cpp index 1545fa205..b761e8d49 100644 --- a/Source/gamemenu.cpp +++ b/Source/gamemenu.cpp @@ -5,6 +5,7 @@ */ #include "all.h" +/** Contains the game menu items of the single player menu. */ TMenuItem sgSingleMenu[6] = { // clang-format off // dwFlags, pszStr, fnMenu @@ -16,6 +17,7 @@ TMenuItem sgSingleMenu[6] = { { GMENU_ENABLED, NULL, NULL } // clang-format on }; +/** Contains the game menu items of the multi player menu. */ TMenuItem sgMultiMenu[5] = { // clang-format off // dwFlags, pszStr, fnMenu @@ -37,8 +39,11 @@ TMenuItem sgOptionsMenu[6] = { { GMENU_ENABLED , NULL, NULL } // clang-format on }; +/** Specifies the menu names for music enabled and disabled. */ char *music_toggle_names[] = { "Music", "Music Disabled" }; +/** Specifies the menu names for sound enabled and disabled. */ char *sound_toggle_names[] = { "Sound", "Sound Disabled" }; +/** Specifies the menu names for colour cycling disabled and enabled. */ char *color_cycling_toggle_names[] = { "Color Cycling Off", "Color Cycling On" }; void gamemenu_on() diff --git a/Source/gmenu.cpp b/Source/gmenu.cpp index 3ba56654a..778fa1209 100644 --- a/Source/gmenu.cpp +++ b/Source/gmenu.cpp @@ -34,7 +34,8 @@ const BYTE lfontframe[127] = { 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 20, 0, 21, 0 }; -/* Maps from bigtgold.cel frame number to character width. */ + +/** Maps from bigtgold.cel frame number to character width. */ const BYTE lfontkern[56] = { 18, 33, 21, 26, 28, 19, 19, 26, 25, 11, 12, 25, 19, 34, 28, 32, 20, 32, 28, 20, diff --git a/Source/inv.cpp b/Source/inv.cpp index 023e0ea27..affddfdac 100644 --- a/Source/inv.cpp +++ b/Source/inv.cpp @@ -10,6 +10,22 @@ BYTE *pInvCels; BOOL drawsbarflag; int sgdwLastTime; // check name +/** + * Maps from inventory slot to screen position. The inventory slots are + * arranged as follows: + * 00 01 + * 02 03 06 + * 07 08 19 20 13 14 + * 09 10 21 22 15 16 + * 11 12 23 24 17 18 + * 04 05 + * 25 26 27 28 29 30 31 32 33 34 + * 35 36 37 38 39 40 41 42 43 44 + * 45 46 47 48 49 50 51 52 53 54 + * 55 56 57 58 59 60 61 62 63 64 + * 65 66 67 68 69 70 71 72 + * @see graphics/inv/inventory.png + */ const InvXY InvRect[73] = { // clang-format off // X, Y @@ -90,7 +106,7 @@ const InvXY InvRect[73] = { }; /* data */ - +/** Specifies the starting inventory slots for placement of 2x2 items. */ int AP2x2Tbl[10] = { 8, 28, 6, 26, 4, 24, 2, 22, 0, 20 }; void FreeInvGFX() diff --git a/Source/itemdat.cpp b/Source/itemdat.cpp index ee9c14337..2def88407 100644 --- a/Source/itemdat.cpp +++ b/Source/itemdat.cpp @@ -5,6 +5,7 @@ */ #include "all.h" +/** Contains the data related to each item ID. */ ItemDataStruct AllItemsList[] = { // clang-format off // iRnd, iClass, iLoc, iCurs, itype, iItemId, iName, iSName, iMinMLvl, iDurability, iMinDam, iMaxDam, iMinAC, iMaxAC, iMinStr, iMinMag, iMinDex, iFlags, iMiscId, iSpell, iUsable, iValue, iMaxValue @@ -168,6 +169,7 @@ ItemDataStruct AllItemsList[] = { // clang-format on }; +/** Contains the data related to each item prefix. */ const PLStruct PL_Prefix[] = { // clang-format off // PLName, PLPower, PLParam1, PLParam2, PLMinLvl, PLIType, PLGOE, PLDouble, PLOk, PLMinVal, PLMaxVal, PLMultVal @@ -258,6 +260,7 @@ const PLStruct PL_Prefix[] = { // clang-format on }; +/** Contains the data related to each item suffix. */ const PLStruct PL_Suffix[] = { // clang-format off // PLName, PLPower, PLParam1, PLParam2, PLMinLvl, PLIType, PLGOE, PLDouble, PLOk, PLMinVal, PLMaxVal, PLMultVal @@ -360,6 +363,7 @@ const PLStruct PL_Suffix[] = { // clang-format on }; +/** Contains the data related to each unique item ID. */ const UItemStruct UniqueItemList[] = { // clang-format off // UIName, UIItemId, UIMinLvl, UINumPL, UIValue, UIPower1, UIParam1, UIParam2, UIPower2, UIParam3, UIParam4, UIPower3, UIParam5, UIParam6, UIPower4, UIParam7, UIParam8, UIPower5, UIParam9, UIParam10, UIPower6, UIParam11, UIParam12 diff --git a/Source/minitext.cpp b/Source/minitext.cpp index c89d31251..54ca65f17 100644 --- a/Source/minitext.cpp +++ b/Source/minitext.cpp @@ -14,6 +14,7 @@ int sgLastScroll; BYTE *pMedTextCels; BYTE *pTextBoxCels; +/** Maps from font index to medtexts.cel frame number. */ const BYTE mfontframe[127] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, @@ -29,6 +30,11 @@ const BYTE mfontframe[127] = { 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 48, 0, 49, 0 }; +/** + * Maps from medtexts.cel frame number to character width. Note, the + * character width may be distinct from the frame width, which is 22 for every + * medtexts.cel frame. + */ const BYTE mfontkern[56] = { 5, 15, 10, 13, 14, 10, 9, 13, 11, 5, 5, 11, 10, 16, 13, 16, 10, 15, 12, 10, @@ -41,7 +47,8 @@ const BYTE mfontkern[56] = { /* data */ /** - * Positive numbers will delay scrolling 1 out of n frames, negative numbers will scroll 1+(-n) pixels. + * Text scroll speeds. Positive numbers will delay scrolling 1 out of n frames, + * negative numbers will scroll 1+(-n) pixels. */ int qscroll_spd_tbl[9] = { 2, 4, 6, 8, 0, -1, -2, -3, -4 }; diff --git a/Source/multi.cpp b/Source/multi.cpp index 6de6af8f8..c4c9f4a42 100644 --- a/Source/multi.cpp +++ b/Source/multi.cpp @@ -28,6 +28,10 @@ int sglTimeoutStart; int sgdwPlayerLeftReasonTbl[MAX_PLRS]; TBuffer sgLoPriBuf; DWORD sgdwGameLoops; +/** + * Specifies the maximum number of players in a game, where 1 + * represents a single player game and 4 represents a multi player game. + */ BYTE gbMaxPlayers; BOOLEAN sgbTimeout; char szPlayerName[128]; @@ -35,6 +39,10 @@ BYTE gbDeltaSender; BOOL sgbNetInited; int player_state[MAX_PLRS]; +/** + * Contains the set of supported event types supported by the multiplayer + * event handler. + */ const int event_types[3] = { EVENT_TYPE_PLAYER_LEAVE_GAME, EVENT_TYPE_PLAYER_CREATE_GAME, diff --git a/Source/objdat.cpp b/Source/objdat.cpp index 070be9f62..a835be14a 100644 --- a/Source/objdat.cpp +++ b/Source/objdat.cpp @@ -1,5 +1,6 @@ #include "all.h" +/** Maps from dun_object_id to object_id. */ int ObjTypeConv[113] = { 0, 4, @@ -116,6 +117,7 @@ int ObjTypeConv[113] = { 94 }; +/** Contains the data related to each object ID. */ ObjDataStruct AllObjects[99] = { // clang-format off // oload, ofindex, ominlvl, omaxlvl, olvltype, otheme, oquest, oAnimFlag, oAnimDelay, oAnimLen, oAnimWidth, oSolidFlag, oMissFlag, oLightFlag, oBreak, oSelFlag, oTrapFlag @@ -221,8 +223,8 @@ ObjDataStruct AllObjects[99] = { // clang-format on }; -// might be const -char *ObjMasterLoadList[56] = { +/** Maps from object_graphic_id to object CEL name. */ +char *ObjMasterLoadList[56] = { // might be const "L1Braz", "L1Doors", "Lever", diff --git a/Source/scrollrt.h b/Source/scrollrt.h index 56d69dfa2..4d265c806 100644 --- a/Source/scrollrt.h +++ b/Source/scrollrt.h @@ -30,7 +30,7 @@ void DrawAndBlit(); /* data */ -/* used in 1.00 debug */ +/** used in 1.00 debug */ extern char *szMonModeAssert[18]; extern char *szPlrModeAssert[12]; diff --git a/Source/textdat.cpp b/Source/textdat.cpp index dbf7898a1..7df9be0d7 100644 --- a/Source/textdat.cpp +++ b/Source/textdat.cpp @@ -2,6 +2,7 @@ /* todo: move text out of struct */ +/** Contains the data related to each speech ID. */ const TextDataStruct alltext[] = { #ifdef SPAWN { "Nice try... ", 0, 0, TSFX_TAVERN36 },