Pause docs: misc docs (#2636)

* doc `KaleidoScope_SetCursorPos`

* doc bug in `KaleidoScope_DrawWorldMap`

* fix anonymous enum

* `D_808321A8` -> `sSavedButtonStatus`

* s16 decimal for `sVtxPageMapDungeonQuads``X/Y/Width/Height`

* Use `LANGUAGE_` enum for indexing language-indexed regs

4 files changed, 94 insertions, 85 deletions

diff --git a/src/code/z_construct.c b/src/code/z_construct.c
index 0f737145e..26d5d092a 100644
--- a/src/code/z_construct.c
+++ b/src/code/z_construct.c
@@ -270,18 +270,18 @@ void Regs_InitDataImpl(void) {
     YREG(47) = 0;
 
 #if OOT_NTSC
-    R_KALEIDO_UNK1(0) = -45;
-    R_KALEIDO_UNK1(1) = -48;
-    R_KALEIDO_UNK2(0) = 16;
-    R_KALEIDO_UNK2(1) = 22;
-    R_KALEIDO_UNK3(0) = -55;
-    R_KALEIDO_UNK3(1) = -53;
-    R_KALEIDO_UNK4(0) = 43;
-    R_KALEIDO_UNK4(1) = 47;
-    R_KALEIDO_UNK5(0) = -33;
-    R_KALEIDO_UNK5(1) = -42;
-    R_KALEIDO_UNK6(0) = -33;
-    R_KALEIDO_UNK6(1) = -37;
+    R_KALEIDO_UNK1(LANGUAGE_JPN) = -45;
+    R_KALEIDO_UNK1(LANGUAGE_ENG) = -48;
+    R_KALEIDO_UNK2(LANGUAGE_JPN) = 16;
+    R_KALEIDO_UNK2(LANGUAGE_ENG) = 22;
+    R_KALEIDO_UNK3(LANGUAGE_JPN) = -55;
+    R_KALEIDO_UNK3(LANGUAGE_ENG) = -53;
+    R_KALEIDO_UNK4(LANGUAGE_JPN) = 43;
+    R_KALEIDO_UNK4(LANGUAGE_ENG) = 47;
+    R_KALEIDO_UNK5(LANGUAGE_JPN) = -33;
+    R_KALEIDO_UNK5(LANGUAGE_ENG) = -42;
+    R_KALEIDO_UNK6(LANGUAGE_JPN) = -33;
+    R_KALEIDO_UNK6(LANGUAGE_ENG) = -37;
 #else
     // Same as above, although these regs are now unused for PAL versions
     YREG(48) = -45;
@@ -369,24 +369,24 @@ void Regs_InitDataImpl(void) {
     ZREG(47) = 1;
 
 #if OOT_NTSC
-    R_START_LABEL_DD(0) = 86;
-    R_START_LABEL_DD(1) = 100;
+    R_START_LABEL_DD(LANGUAGE_JPN) = 86;
+    R_START_LABEL_DD(LANGUAGE_ENG) = 100;
     R_START_LABEL_WIDTH = 0;
     R_START_LABEL_HEIGHT = 0;
-    R_START_LABEL_Y(0) = 21;
-    R_START_LABEL_Y(1) = 20;
-    R_START_LABEL_X(0) = 122;
-    R_START_LABEL_X(1) = 120;
+    R_START_LABEL_Y(LANGUAGE_JPN) = 21;
+    R_START_LABEL_Y(LANGUAGE_ENG) = 20;
+    R_START_LABEL_X(LANGUAGE_JPN) = 122;
+    R_START_LABEL_X(LANGUAGE_ENG) = 120;
 #else
-    R_START_LABEL_DD(0) = 100;
-    R_START_LABEL_DD(1) = 89;
-    R_START_LABEL_DD(2) = 92;
-    R_START_LABEL_Y(0) = 20;
-    R_START_LABEL_Y(1) = 20;
-    R_START_LABEL_Y(2) = 20;
-    R_START_LABEL_X(0) = 120;
-    R_START_LABEL_X(1) = 119;
-    R_START_LABEL_X(2) = 119;
+    R_START_LABEL_DD(LANGUAGE_ENG) = 100;
+    R_START_LABEL_DD(LANGUAGE_GER) = 89;
+    R_START_LABEL_DD(LANGUAGE_FRA) = 92;
+    R_START_LABEL_Y(LANGUAGE_ENG) = 20;
+    R_START_LABEL_Y(LANGUAGE_GER) = 20;
+    R_START_LABEL_Y(LANGUAGE_FRA) = 20;
+    R_START_LABEL_X(LANGUAGE_ENG) = 120;
+    R_START_LABEL_X(LANGUAGE_GER) = 119;
+    R_START_LABEL_X(LANGUAGE_FRA) = 119;
 #endif
 
     R_PAUSE_QUEST_MEDALLION_SHINE_TIME(0) = 1;
@@ -528,14 +528,14 @@ void Regs_InitDataImpl(void) {
     WREG(7) = 0;
 
 #if OOT_NTSC
-    R_B_LABEL_SCALE(0) = 100;
-    R_B_LABEL_SCALE(1) = 109;
-    R_B_LABEL_X(0) = 151;
-    R_B_LABEL_X(1) = 148;
-    R_B_LABEL_Y(0) = 23;
-    R_B_LABEL_Y(1) = 22;
-    R_A_LABEL_Z(0) = -380;
-    R_A_LABEL_Z(1) = -350;
+    R_B_LABEL_SCALE(LANGUAGE_JPN) = 100;
+    R_B_LABEL_SCALE(LANGUAGE_ENG) = 109;
+    R_B_LABEL_X(LANGUAGE_JPN) = 151;
+    R_B_LABEL_X(LANGUAGE_ENG) = 148;
+    R_B_LABEL_Y(LANGUAGE_JPN) = 23;
+    R_B_LABEL_Y(LANGUAGE_ENG) = 22;
+    R_A_LABEL_Z(LANGUAGE_JPN) = -380;
+    R_A_LABEL_Z(LANGUAGE_ENG) = -350;
 #else
     // Same as above, although these regs are now unused in PAL versions
     WREG(8) = 100;
@@ -570,36 +570,36 @@ void Regs_InitDataImpl(void) {
     WREG(36) = 0;
 
 #if OOT_PAL
-    R_B_LABEL_SCALE(0) = 100;
-    R_B_LABEL_SCALE(1) = 99;
-    R_B_LABEL_SCALE(2) = 109;
-    R_B_LABEL_X(0) = B_BUTTON_X - 9;
-    R_B_LABEL_X(1) = B_BUTTON_X - 11;
-    R_B_LABEL_X(2) = B_BUTTON_X - 12;
-    R_B_LABEL_Y(0) = B_BUTTON_Y + 6;
-    R_B_LABEL_Y(1) = B_BUTTON_Y + 5;
-    R_B_LABEL_Y(2) = B_BUTTON_Y + 5;
-    R_A_LABEL_Z(0) = -380;
-    R_A_LABEL_Z(1) = -360;
-    R_A_LABEL_Z(2) = -350;
-    R_KALEIDO_UNK1(0) = -48;
-    R_KALEIDO_UNK1(1) = 16;
-    R_KALEIDO_UNK1(2) = -62;
-    R_KALEIDO_UNK2(0) = 22;
-    R_KALEIDO_UNK2(1) = -84;
-    R_KALEIDO_UNK2(2) = 20;
-    R_KALEIDO_UNK3(0) = -53;
-    R_KALEIDO_UNK3(1) = 40;
-    R_KALEIDO_UNK3(2) = -64;
-    R_KALEIDO_UNK4(0) = 47;
-    R_KALEIDO_UNK4(1) = -84;
-    R_KALEIDO_UNK4(2) = 44;
-    R_KALEIDO_UNK5(0) = -42;
-    R_KALEIDO_UNK5(1) = 32;
-    R_KALEIDO_UNK5(2) = -45;
-    R_KALEIDO_UNK6(0) = -37;
-    R_KALEIDO_UNK6(1) = 30;
-    R_KALEIDO_UNK6(2) = -50;
+    R_B_LABEL_SCALE(LANGUAGE_ENG) = 100;
+    R_B_LABEL_SCALE(LANGUAGE_GER) = 99;
+    R_B_LABEL_SCALE(LANGUAGE_FRA) = 109;
+    R_B_LABEL_X(LANGUAGE_ENG) = B_BUTTON_X - 9;
+    R_B_LABEL_X(LANGUAGE_GER) = B_BUTTON_X - 11;
+    R_B_LABEL_X(LANGUAGE_FRA) = B_BUTTON_X - 12;
+    R_B_LABEL_Y(LANGUAGE_ENG) = B_BUTTON_Y + 6;
+    R_B_LABEL_Y(LANGUAGE_GER) = B_BUTTON_Y + 5;
+    R_B_LABEL_Y(LANGUAGE_FRA) = B_BUTTON_Y + 5;
+    R_A_LABEL_Z(LANGUAGE_ENG) = -380;
+    R_A_LABEL_Z(LANGUAGE_GER) = -360;
+    R_A_LABEL_Z(LANGUAGE_FRA) = -350;
+    R_KALEIDO_UNK1(LANGUAGE_ENG) = -48;
+    R_KALEIDO_UNK1(LANGUAGE_GER) = 16;
+    R_KALEIDO_UNK1(LANGUAGE_FRA) = -62;
+    R_KALEIDO_UNK2(LANGUAGE_ENG) = 22;
+    R_KALEIDO_UNK2(LANGUAGE_GER) = -84;
+    R_KALEIDO_UNK2(LANGUAGE_FRA) = 20;
+    R_KALEIDO_UNK3(LANGUAGE_ENG) = -53;
+    R_KALEIDO_UNK3(LANGUAGE_GER) = 40;
+    R_KALEIDO_UNK3(LANGUAGE_FRA) = -64;
+    R_KALEIDO_UNK4(LANGUAGE_ENG) = 47;
+    R_KALEIDO_UNK4(LANGUAGE_GER) = -84;
+    R_KALEIDO_UNK4(LANGUAGE_FRA) = 44;
+    R_KALEIDO_UNK5(LANGUAGE_ENG) = -42;
+    R_KALEIDO_UNK5(LANGUAGE_GER) = 32;
+    R_KALEIDO_UNK5(LANGUAGE_FRA) = -45;
+    R_KALEIDO_UNK6(LANGUAGE_ENG) = -37;
+    R_KALEIDO_UNK6(LANGUAGE_GER) = 30;
+    R_KALEIDO_UNK6(LANGUAGE_FRA) = -50;
 #endif
 
     R_DGN_MINIMAP_X = 204;
diff --git a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_item.c b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_item.c
index 7e23b361d..a1dda5799 100644
--- a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_item.c
+++ b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_item.c
@@ -110,7 +110,14 @@ void KaleidoScope_DrawAmmoCount(PauseContext* pauseCtx, GraphicsContext* gfxCtx,
     CLOSE_DISPS(gfxCtx, "../z_kaleido_item.c", 116);
 }
 
+/**
+ * Set the cursor to the position of `vtx[index]`.
+ * The position indicates the cursor's top-left.
+ *
+ * @see KaleidoScope_UpdateCursorVtx where this position is used to update all cursor quads.
+ */
 void KaleidoScope_SetCursorPos(PauseContext* pauseCtx, u16 index, Vtx* vtx) {
+    // PAUSE_QUAD_CURSOR_TL
     pauseCtx->cursorVtx[0].v.ob[0] = vtx[index].v.ob[0];
     pauseCtx->cursorVtx[0].v.ob[1] = vtx[index].v.ob[1];
 }
diff --git a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_map.c b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_map.c
index cf2b225af..f454594b4 100644
--- a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_map.c
+++ b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_map.c
@@ -589,7 +589,13 @@ void KaleidoScope_DrawWorldMap(PlayState* play, GraphicsContext* gfxCtx) {
                 PAGE_BG_QUADS + WORLD_MAP_QUAD_POINT_FIRST + pauseCtx->cursorPoint[PAUSE_WORLD_MAP];
             KaleidoScope_SetCursorPos(pauseCtx, pauseCtx->cursorSlot[PAUSE_MAP] * 4, pauseCtx->mapPageVtx);
         } else {
+
+            //! @bug This causes a weird DMA request in `KaleidoScope_UpdateNamePanel`,
+            //! either for unintended data or outside the intended segment.
+            // This isn't a visual issue in practice because drawing the texture loaded in
+            // `KaleidoScope_UpdateNamePanel` is only done under `cursorSpecialPos == 0`.
             pauseCtx->cursorItem[PAUSE_MAP] = gSaveContext.worldMapArea + 0x18;
+
             if (pauseCtx->cursorSpecialPos == PAUSE_CURSOR_PAGE_LEFT) {
                 if (pauseCtx->stickAdjX > 30) {
                     pauseCtx->cursorSpecialPos = 0;
diff --git a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope.c b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope.c
index 99a0b5ff5..97fd16e70 100644
--- a/src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope.c
+++ b/src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope.c
@@ -63,7 +63,7 @@
 #define KALEIDO_COLOR_CURSOR_UNK_B 50
 #endif
 
-typedef enum {
+typedef enum VtxPageInit {
     /* 0 */ VTX_PAGE_ITEM,
     /* 1 */ VTX_PAGE_EQUIP,
     /* 2 */ VTX_PAGE_MAP_DUNGEON,
@@ -932,7 +932,7 @@ static void* sPromptChoiceTexs[][2] = {
 //! non-static, but we make it static here to match the bss order and patch the relocation section later in the build
 //! as our relocation generator does count COMMON symbols.
 
-static u8 D_808321A8[5];
+static u8 sSavedButtonStatus[5];
 static PreRender sPlayerPreRender;
 void* sPreRenderCvg;
 
@@ -2256,8 +2256,7 @@ static u8 sPageBgColorBlue[][4] = {
 static s16 sVtxPageItemQuadsX[CLAMP_MIN(VTX_PAGE_ITEM_QUADS, 1)] = { 0 };
 static s16 sVtxPageEquipQuadsX[CLAMP_MIN(VTX_PAGE_EQUIP_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapDungeonQuadsX[VTX_PAGE_MAP_DUNGEON_QUADS] = {
-    0xFFDC, 0x000C, 0xFFEE, 0x0046, 0x0046, 0x0046, 0xFFA8, 0xFFA8, 0xFFA8,
-    0xFFA8, 0xFFA8, 0xFFA8, 0xFFA8, 0xFFA8, 0xFF96, 0xFFC2, 0xFFD8,
+    -36, 12, -18, 70, 70, 70, -88, -88, -88, -88, -88, -88, -88, -88, -106, -62, -40,
 };
 static s16 sVtxPageQuestQuadsX[CLAMP_MIN(VTX_PAGE_QUEST_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapWorldQuadsX[VTX_PAGE_MAP_WORLD_QUADS] = {
@@ -2304,8 +2303,7 @@ static s16 sVtxPagePromptQuadsX[VTX_PAGE_PROMPT_QUADS] = {
 static s16 sVtxPageItemQuadsWidth[CLAMP_MIN(VTX_PAGE_ITEM_QUADS, 1)] = { 0 };
 static s16 sVtxPageEquipQuadsWidth[CLAMP_MIN(VTX_PAGE_EQUIP_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapDungeonQuadsWidth[VTX_PAGE_MAP_DUNGEON_QUADS] = {
-    0x0030, 0x0030, 0x0060, 0x0018, 0x0018, 0x0018, 0x0018, 0x0018, 0x0018,
-    0x0018, 0x0018, 0x0018, 0x0018, 0x0018, 0x0010, 0x0010, 0x0018,
+    48, 48, 96, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 24, 16, 16, 24,
 };
 static s16 sVtxPageQuestQuadsWidth[CLAMP_MIN(VTX_PAGE_QUEST_QUADS, 1)] = { 0 };
 static s16 sVtxPagePromptQuadsWidth[VTX_PAGE_PROMPT_QUADS] = {
@@ -2318,8 +2316,7 @@ static s16 sVtxPagePromptQuadsWidth[VTX_PAGE_PROMPT_QUADS] = {
 static s16 sVtxPageItemQuadsY[CLAMP_MIN(VTX_PAGE_ITEM_QUADS, 1)] = { 0 };
 static s16 sVtxPageEquipQuadsY[CLAMP_MIN(VTX_PAGE_EQUIP_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapDungeonQuadsY[VTX_PAGE_MAP_DUNGEON_QUADS] = {
-    0x001C, 0x001C, 0x002E, 0x001C, 0xFFFE, 0xFFE0, 0x0032, 0x0024, 0x0016,
-    0x0008, 0xFFFA, 0xFFEC, 0xFFDE, 0xFFD0, 0x0012, 0x0012, 0x0032,
+    28, 28, 46, 28, -2, -32, 50, 36, 22, 8, -6, -20, -34, -48, 18, 18, 50,
 };
 static s16 sVtxPageQuestQuadsY[CLAMP_MIN(VTX_PAGE_QUEST_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapWorldQuadsY[VTX_PAGE_MAP_WORLD_QUADS] = {
@@ -2366,8 +2363,7 @@ static s16 sVtxPagePromptQuadsY[VTX_PAGE_PROMPT_QUADS] = {
 static s16 sVtxPageItemQuadsHeight[CLAMP_MIN(VTX_PAGE_ITEM_QUADS, 1)] = { 0 };
 static s16 sVtxPageEquipQuadsHeight[CLAMP_MIN(VTX_PAGE_EQUIP_QUADS, 1)] = { 0 };
 static s16 sVtxPageMapDungeonQuadsHeight[VTX_PAGE_MAP_DUNGEON_QUADS] = {
-    0x0055, 0x0055, 0x0010, 0x0018, 0x0018, 0x0018, 0x0010, 0x0010, 0x0010,
-    0x0010, 0x0010, 0x0010, 0x0010, 0x0010, 0x0010, 0x0010, 0x0018,
+    85, 85, 16, 24, 24, 24, 16, 16, 16, 16, 16, 16, 16, 16, 16, 16, 24,
 };
 static s16 sVtxPageQuestQuadsHeight[CLAMP_MIN(VTX_PAGE_QUEST_QUADS, 1)] = { 0 };
 static s16 sVtxPagePromptQuadsHeight[VTX_PAGE_PROMPT_QUADS] = {
@@ -3669,11 +3665,11 @@ void KaleidoScope_Update(PlayState* play) {
 
     switch (pauseCtx->state) {
         case PAUSE_STATE_INIT:
-            D_808321A8[0] = gSaveContext.buttonStatus[0];
-            D_808321A8[1] = gSaveContext.buttonStatus[1];
-            D_808321A8[2] = gSaveContext.buttonStatus[2];
-            D_808321A8[3] = gSaveContext.buttonStatus[3];
-            D_808321A8[4] = gSaveContext.buttonStatus[4];
+            sSavedButtonStatus[0] = gSaveContext.buttonStatus[0];
+            sSavedButtonStatus[1] = gSaveContext.buttonStatus[1];
+            sSavedButtonStatus[2] = gSaveContext.buttonStatus[2];
+            sSavedButtonStatus[3] = gSaveContext.buttonStatus[3];
+            sSavedButtonStatus[4] = gSaveContext.buttonStatus[4];
 
             pauseCtx->cursorX[PAUSE_MAP] = 0;
             pauseCtx->cursorSlot[PAUSE_MAP] = pauseCtx->cursorPoint[PAUSE_MAP] = pauseCtx->dungeonMapSlot =
@@ -4691,11 +4687,11 @@ void KaleidoScope_Update(PlayState* play) {
                     break;
             }
 
-            gSaveContext.buttonStatus[0] = D_808321A8[0];
-            gSaveContext.buttonStatus[1] = D_808321A8[1];
-            gSaveContext.buttonStatus[2] = D_808321A8[2];
-            gSaveContext.buttonStatus[3] = D_808321A8[3];
-            gSaveContext.buttonStatus[4] = D_808321A8[4];
+            gSaveContext.buttonStatus[0] = sSavedButtonStatus[0];
+            gSaveContext.buttonStatus[1] = sSavedButtonStatus[1];
+            gSaveContext.buttonStatus[2] = sSavedButtonStatus[2];
+            gSaveContext.buttonStatus[3] = sSavedButtonStatus[3];
+            gSaveContext.buttonStatus[4] = sSavedButtonStatus[4];
             interfaceCtx->unk_1FA = interfaceCtx->unk_1FC = 0;
             PRINTF_COLOR_YELLOW();
             PRINTF("i=%d  LAST_TIME_TYPE=%d\n", i, gSaveContext.prevHudVisibilityMode);