z_overlay and z_fbdemo_dlftbls (Transition overlay handling), clean up a lot of u32s used to store pointers (#1073)

* overlay matches

* prototypes

* fbdemo too

* virtual to physical

* names, cleanup, etc

* bss reordering

* uintptr stuff

* fixed now?

* one fix

* headers and such

* fixes'n'stuff

* XXX action

* docs of a sort

* useless error codes

* n

* format

* header? I barely know her!

Co-authored-by: petrie911 <petrie911@users.noreply.github.com>

10 files changed, 176 insertions, 28 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 88ec6c07b..84616f083 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -1060,7 +1060,7 @@ void Actor_SetScale(Actor* actor, f32 scale) {
 }
 
 void Actor_SetObjectDependency(PlayState* play, Actor* actor) {
-    gSegments[0x06] = PHYSICAL_TO_VIRTUAL(play->objectCtx.status[actor->objBankIndex].segment);
+    gSegments[0x06] = VIRTUAL_TO_PHYSICAL(play->objectCtx.status[actor->objBankIndex].segment);
 }
 
 void Actor_Init(Actor* actor, PlayState* play) {
diff --git a/src/code/z_effect_soft_sprite_old_init.c b/src/code/z_effect_soft_sprite_old_init.c
index bbdd528a4..4f24651d1 100644
--- a/src/code/z_effect_soft_sprite_old_init.c
+++ b/src/code/z_effect_soft_sprite_old_init.c
@@ -50,7 +50,7 @@ void EffectSs_DrawGEffect(PlayState* play, EffectSs* this, TexturePtr texture) {
     SkinMatrix_SetScale(&mfScale, scale, scale, scale);
     SkinMatrix_MtxFMtxFMult(&mfTrans, &play->billboardMtxF, &mfTrans11DA0);
     SkinMatrix_MtxFMtxFMult(&mfTrans11DA0, &mfScale, &mfResult);
-    gSegments[0x06] = PHYSICAL_TO_VIRTUAL(object);
+    gSegments[0x06] = VIRTUAL_TO_PHYSICAL(object);
     gSPSegment(POLY_XLU_DISP++, 0x06, object);
 
     mtx = SkinMatrix_MtxFToNewMtx(gfxCtx, &mfResult);
diff --git a/src/code/z_en_hy_code.c b/src/code/z_en_hy_code.c
index 5e32e5c95..19a52c1b4 100644
--- a/src/code/z_en_hy_code.c
+++ b/src/code/z_en_hy_code.c
@@ -84,7 +84,7 @@ EnDoor* EnHy_FindNearestDoor(Actor* actor, PlayState* play) {
 }
 
 void EnHy_ChangeObjectAndAnim(EnHy* enHy, PlayState* play, s16 animIndex) {
-    gSegments[6] = PHYSICAL_TO_VIRTUAL(play->objectCtx.status[enHy->animObjIndex].segment);
+    gSegments[6] = VIRTUAL_TO_PHYSICAL(play->objectCtx.status[enHy->animObjIndex].segment);
     EnHy_ChangeAnim(&enHy->skelAnime, animIndex);
 }
 
@@ -92,7 +92,7 @@ s32 EnHy_UpdateSkelAnime(EnHy* enHy, PlayState* play) {
     s32 isUpdated = false;
 
     if (enHy->actor.draw != NULL) {
-        gSegments[6] = PHYSICAL_TO_VIRTUAL(play->objectCtx.status[enHy->animObjIndex].segment);
+        gSegments[6] = VIRTUAL_TO_PHYSICAL(play->objectCtx.status[enHy->animObjIndex].segment);
         SkelAnime_Update(&enHy->skelAnime);
         isUpdated = true;
     }
@@ -119,7 +119,7 @@ s32 EnHy_Init(EnHy* enHy, PlayState* play, FlexSkeletonHeader* skeletonHeaderSeg
         enHy->actor.objBankIndex = enHy->skelLowerObjIndex;
         isInitialized = true;
         ActorShape_Init(&enHy->actor.shape, 0.0f, NULL, 0.0f);
-        gSegments[6] = PHYSICAL_TO_VIRTUAL(play->objectCtx.status[enHy->actor.objBankIndex].segment);
+        gSegments[6] = VIRTUAL_TO_PHYSICAL(play->objectCtx.status[enHy->actor.objBankIndex].segment);
         SkelAnime_InitFlex(play, &enHy->skelAnime, skeletonHeaderSeg, NULL, enHy->jointTable, enHy->morphTable,
                            ENHY_LIMB_MAX);
         EnHy_ChangeObjectAndAnim(enHy, play, animIndex);
diff --git a/src/code/z_fbdemo_circle.c b/src/code/z_fbdemo_circle.c
index 9cbc308be..2a8144ea4 100644
--- a/src/code/z_fbdemo_circle.c
+++ b/src/code/z_fbdemo_circle.c
@@ -13,7 +13,7 @@ Gfx D_801D0D00[] = {
 };
 
 //! @bug: TransitionCircle_Update should take an additional argument `s32 updateRate`
-const TransitionInit TransitionCircle_InitVars = {
+TransitionInit TransitionCircle_InitVars = {
     TransitionCircle_Init,   TransitionCircle_Destroy, (void*)TransitionCircle_Update, TransitionCircle_Draw,
     TransitionCircle_Start,  TransitionCircle_SetType, TransitionCircle_SetColor,      NULL,
     TransitionCircle_IsDone,
diff --git a/src/code/z_fbdemo_dlftbls.c b/src/code/z_fbdemo_dlftbls.c
index 7ebce9e69..9d3685a45 100644
--- a/src/code/z_fbdemo_dlftbls.c
+++ b/src/code/z_fbdemo_dlftbls.c
@@ -1,5 +1,54 @@
 #include "global.h"
+#include "initvars.h"
+#include "overlays/fbdemos/ovl_fbdemo_triforce/z_fbdemo_triforce.h"
+#include "overlays/fbdemos/ovl_fbdemo_wipe1/z_fbdemo_wipe1.h"
+#include "overlays/fbdemos/ovl_fbdemo_wipe3/z_fbdemo_wipe3.h"
+#include "overlays/fbdemos/ovl_fbdemo_wipe4/z_fbdemo_wipe4.h"
+#include "overlays/fbdemos/ovl_fbdemo_wipe5/z_fbdemo_wipe5.h"
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_fbdemo_dlftbls/func_80163C90.s")
+#define TRANSITION_OVERLAY(name, filename)                                                                       \
+    {                                                                                                            \
+        { 0, 0 }, SEGMENT_START(ovl_##filename), SEGMENT_END(ovl_##filename), SEGMENT_ROM_START(ovl_##filename), \
+            SEGMENT_ROM_END(ovl_##filename), &name##_InitVars, sizeof(name)                                      \
+    }
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_fbdemo_dlftbls/func_80163D80.s")
+#define TRANSITION_OVERLAY_INTERNAL(name) \
+    { { 0, 0 }, NULL, NULL, 0, 0, &name##_InitVars, sizeof(name) }
+
+#define TRANSITION_OVERLAY_UNSET \
+    { 0 }
+
+TransitionOverlay gTransitionOverlayTable[] = {
+    TRANSITION_OVERLAY_INTERNAL(TransitionFade),       TRANSITION_OVERLAY(TransitionTriforce, fbdemo_triforce),
+    TRANSITION_OVERLAY(TransitionWipe1, fbdemo_wipe1), TRANSITION_OVERLAY(TransitionWipe3, fbdemo_wipe3),
+    TRANSITION_OVERLAY(TransitionWipe4, fbdemo_wipe4), TRANSITION_OVERLAY_INTERNAL(TransitionCircle),
+    TRANSITION_OVERLAY(TransitionWipe5, fbdemo_wipe5),
+};
+
+void Transition_Init(TransitionContext* transitionCtx) {
+    TransitionOverlay* overlayEntry;
+    ptrdiff_t relocOffset;
+    TransitionInit* initInfo[1];
+
+    overlayEntry = &gTransitionOverlayTable[transitionCtx->fbdemoType];
+    TransitionOverlay_Load(overlayEntry);
+
+    relocOffset = (uintptr_t)Lib_PhysicalToVirtual(overlayEntry->loadInfo.addr) - (uintptr_t)overlayEntry->vramStart;
+    initInfo[0] = NULL;
+    initInfo[0] = (overlayEntry->initInfo != NULL) ? (TransitionInit*)((uintptr_t)overlayEntry->initInfo + relocOffset)
+                                                   : initInfo[0];
+
+    transitionCtx->init = initInfo[0]->init;
+    transitionCtx->destroy = initInfo[0]->destroy;
+    transitionCtx->start = initInfo[0]->start;
+    transitionCtx->isDone = initInfo[0]->isDone;
+    transitionCtx->draw = initInfo[0]->draw;
+    transitionCtx->update = initInfo[0]->update;
+    transitionCtx->setType = initInfo[0]->setType;
+    transitionCtx->setColor = initInfo[0]->setColor;
+    transitionCtx->setEnvColor = initInfo[0]->setEnvColor;
+}
+
+void Transition_Destroy(TransitionContext* transitionCtx) {
+    TransitionOverlay_Free(&gTransitionOverlayTable[transitionCtx->fbdemoType]);
+}
diff --git a/src/code/z_lib.c b/src/code/z_lib.c
index 03e6c395c..6466b337c 100644
--- a/src/code/z_lib.c
+++ b/src/code/z_lib.c
@@ -704,20 +704,30 @@ void* Lib_SegmentedToVirtual(void* ptr) {
 void* Lib_SegmentedToVirtualNull(void* ptr) {
     if (((uintptr_t)ptr >> 28) == 0) {
         return ptr;
+    } else {
+        return SEGMENTED_TO_VIRTUAL(ptr);
     }
-
-    return SEGMENTED_TO_VIRTUAL(ptr);
 }
 
-void* Lib_PhysicalToVirtual(void* ptr) {
+/*
+ * Converts a 32-bit virtual address (0x80XXXXXX) to a 24-bit physical address (0xXXXXXX). The NULL case accounts for
+ * the NULL virtual address being 0x00000000 and not 0x80000000. Used by transition overlays, which store their
+ * addresses in 24-bit fields.
+ */
+void* Lib_VirtualToPhysical(void* ptr) {
     if (ptr == NULL) {
         return NULL;
     } else {
-        return (void*)PHYSICAL_TO_VIRTUAL(ptr);
+        return (void*)VIRTUAL_TO_PHYSICAL(ptr);
     }
 }
 
-void* Lib_PhysicalToVirtualNull(void* ptr) {
+/*
+ * Converts a 24-bit physical address (0xXXXXXX) to a 32-bit virtual address (0x80XXXXXX). The NULL case accounts for
+ * the NULL virtual address being 0x00000000 and not 0x80000000. Used by transition overlays, which store their
+ * addresses in 24-bit fields.
+ */
+void* Lib_PhysicalToVirtual(void* ptr) {
     if (ptr == NULL) {
         return NULL;
     } else {
diff --git a/src/code/z_overlay.c b/src/code/z_overlay.c
index a358cefe6..2c8c8d6d7 100644
--- a/src/code/z_overlay.c
+++ b/src/code/z_overlay.c
@@ -1,14 +1,103 @@
+/**
+ * @file z_overlay.c
+ *
+ * Functions for handling transition overlays in memory
+ *
+ * Status codes returned from TransitionOverlay_Load and TransitionOverlay_Free:
+ *
+ * -1 : failed allocation or null reference
+ *  0 : successfully loaded/freed overlay
+ *  1 : successfully added/removed instance
+ *  2 : overlay is loaded but has no instances (?) TODO: Figure out why this exists
+ *  3 : internal overlay, so always loaded
+ */
+
 #include "global.h"
 #include "z64load.h"
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_801651B0.s")
+void* TransitionOverlay_VramToRam(TransitionOverlay* overlayEntry, void* vramAddr) {
+    void* loadedRamAddr = Lib_PhysicalToVirtual(overlayEntry->loadInfo.addr);
+
+    if ((loadedRamAddr != NULL) && (vramAddr >= overlayEntry->vramStart) && (vramAddr < overlayEntry->vramEnd)) {
+        return ((uintptr_t)loadedRamAddr - (uintptr_t)overlayEntry->vramStart) + (uintptr_t)vramAddr;
+    }
+    return vramAddr;
+}
+
+void TransitionOverlay_VramToRamArray(TransitionOverlay* overlayEntry, void** vramAddrs, s32 count) {
+    s32 i;
+
+    for (i = 0; i < count; i++) {
+        vramAddrs[i] = TransitionOverlay_VramToRam(overlayEntry, vramAddrs[i]);
+    }
+}
+
+s32 TransitionOverlay_Load(TransitionOverlay* overlayEntry) {
+    s32 count;
+    void* loadedRamAddr;
+
+    if (overlayEntry->vromStart == 0) {
+        return 3;
+    }
+    if (Lib_PhysicalToVirtual(overlayEntry->loadInfo.addr) == NULL) {
+        loadedRamAddr = ZeldaArena_Malloc(VRAM_PTR_SIZE(overlayEntry));
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_80165224.s")
+        if (loadedRamAddr == NULL) {
+            return -1;
+        }
+        Load2_LoadOverlay(overlayEntry->vromStart, overlayEntry->vromEnd, overlayEntry->vramStart,
+                          overlayEntry->vramEnd, loadedRamAddr);
+        overlayEntry->loadInfo.addr = Lib_VirtualToPhysical(loadedRamAddr);
+        overlayEntry->loadInfo.count = 1;
+        return 0;
+    } else {
+        count = overlayEntry->loadInfo.count;
+        if (count != 0) {
+            count++;
+            overlayEntry->loadInfo.count = count;
+            if (count == 0) {
+                return 2;
+            } else {
+                return 1;
+            }
+        }
+        return 2;
+    }
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_80165288.s")
+s32 TransitionOverlay_Free(TransitionOverlay* overlayEntry) {
+    s32 count;
+    void* loadedRamAddr;
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_8016537C.s")
+    if (overlayEntry->vromStart == 0) {
+        return 3;
+    }
+    loadedRamAddr = Lib_PhysicalToVirtual(overlayEntry->loadInfo.addr);
+    if (loadedRamAddr != NULL) {
+        count = overlayEntry->loadInfo.count;
+        if (count != 0) {
+            count--;
+            overlayEntry->loadInfo.count = count;
+            if (count == 0) {
+                ZeldaArena_Free(loadedRamAddr);
+                overlayEntry->loadInfo.addr = Lib_VirtualToPhysical(NULL);
+                return 0;
+            }
+            return 1;
+        }
+        return 2;
+    }
+    return -1;
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_80165438.s")
+void TransitionOverlay_ClearLoadInfo(TransitionOverlay* overlayEntry) {
+    overlayEntry->loadInfo.word = 0; // Equivalent to overlayEntry->loadInfo.count = 0, overlayEntry->loadInfo.addr = 0;
+}
 
-#pragma GLOBAL_ASM("asm/non_matchings/code/z_overlay/func_80165444.s")
+void TransitionOverlay_SetSegment(TransitionOverlay* overlayEntry, void* vramStart, void* vramEnd, uintptr_t vromStart,
+                                  uintptr_t vromEnd) {
+    overlayEntry->vramStart = vramStart;
+    overlayEntry->vramEnd = vramEnd;
+    overlayEntry->vromStart = vromStart;
+    overlayEntry->vromEnd = vromEnd;
+}
diff --git a/src/code/z_player_lib.c b/src/code/z_player_lib.c
index 0888be7c5..6f4198fc7 100644
--- a/src/code/z_player_lib.c
+++ b/src/code/z_player_lib.c
@@ -1107,7 +1107,7 @@ void Player_DrawGetItemImpl(PlayState* play, Player* player, Vec3f* refPos, s32
 
     OPEN_DISPS(play->state.gfxCtx);
 
-    gSegments[6] = PHYSICAL_TO_VIRTUAL(player->giObjectSegment);
+    gSegments[6] = VIRTUAL_TO_PHYSICAL(player->giObjectSegment);
 
     gSPSegment(POLY_OPA_DISP++, 0x06, player->giObjectSegment);
     gSPSegment(POLY_XLU_DISP++, 0x06, player->giObjectSegment);
@@ -1187,7 +1187,7 @@ void func_80127488(PlayState* play, Player* player, u8 alpha) {
 }
 
 void Player_DrawCouplesMask(PlayState* play, Player* player) {
-    gSegments[0xA] = PHYSICAL_TO_VIRTUAL(player->maskObjectSegment);
+    gSegments[0xA] = VIRTUAL_TO_PHYSICAL(player->maskObjectSegment);
     AnimatedMat_DrawOpa(play, Lib_SegmentedToVirtual(&object_mask_meoto_Matanimheader_001CD8));
 }
 
diff --git a/src/code/z_room.c b/src/code/z_room.c
index e198e95ed..eb615c409 100644
--- a/src/code/z_room.c
+++ b/src/code/z_room.c
@@ -105,7 +105,7 @@ s32 Room_HandleLoadCallbacks(PlayState* play, RoomContext* roomCtx) {
             roomCtx->unk31 = 0;
             roomCtx->curRoom.segment = roomCtx->activeRoomVram;
             // TODO: Segment number enum
-            gSegments[0x03] = PHYSICAL_TO_VIRTUAL(roomCtx->activeRoomVram);
+            gSegments[0x03] = VIRTUAL_TO_PHYSICAL(roomCtx->activeRoomVram);
 
             Scene_ProcessHeader(play, (SceneCmd*)roomCtx->curRoom.segment);
             func_80123140(play, GET_PLAYER(play));
@@ -130,7 +130,7 @@ s32 Room_HandleLoadCallbacks(PlayState* play, RoomContext* roomCtx) {
 void Room_Draw(PlayState* play, Room* room, u32 flags) {
     if (room->segment != NULL) {
         // TODO: Segment number enum
-        gSegments[0x03] = PHYSICAL_TO_VIRTUAL(room->segment);
+        gSegments[0x03] = VIRTUAL_TO_PHYSICAL(room->segment);
         roomDrawFuncs[room->mesh->type0.type](play, room, flags);
     }
     return;
diff --git a/src/code/z_scene.c b/src/code/z_scene.c
index 7b88d4520..c32a2271d 100644
--- a/src/code/z_scene.c
+++ b/src/code/z_scene.c
@@ -52,7 +52,7 @@ void Object_InitBank(GameState* gameState, ObjectContext* objectCtx) {
     objectCtx->spaceEnd = (void*)((u32)objectCtx->spaceStart + spaceSize);
     objectCtx->mainKeepIndex = Object_Spawn(objectCtx, GAMEPLAY_KEEP);
 
-    gSegments[0x04] = PHYSICAL_TO_VIRTUAL(objectCtx->status[objectCtx->mainKeepIndex].segment);
+    gSegments[0x04] = VIRTUAL_TO_PHYSICAL(objectCtx->status[objectCtx->mainKeepIndex].segment);
 }
 
 void Object_UpdateBank(ObjectContext* objectCtx) {
@@ -108,7 +108,7 @@ s32 Object_IsLoaded(ObjectContext* objectCtx, s32 index) {
 void Object_LoadAll(ObjectContext* objectCtx) {
     s32 i;
     s32 id;
-    u32 vromSize;
+    uintptr_t vromSize;
 
     for (i = 0; i < objectCtx->num; i++) {
         id = objectCtx->status[i].id;
@@ -124,7 +124,7 @@ void Object_LoadAll(ObjectContext* objectCtx) {
 
 void* func_8012F73C(ObjectContext* objectCtx, s32 iParm2, s16 id) {
     u32 addr;
-    u32 vromSize;
+    uintptr_t vromSize;
     RomFile* fileTableEntry;
 
     objectCtx->status[iParm2].id = -id;
@@ -224,7 +224,7 @@ void Scene_HeaderCmdSpecialFiles(PlayState* play, SceneCmd* cmd) {
     if (cmd->specialFiles.subKeepIndex != 0) {
         play->objectCtx.subKeepIndex = Object_Spawn(&play->objectCtx, cmd->specialFiles.subKeepIndex);
         // TODO: Segment number enum?
-        gSegments[0x05] = PHYSICAL_TO_VIRTUAL(play->objectCtx.status[play->objectCtx.subKeepIndex].segment);
+        gSegments[0x05] = VIRTUAL_TO_PHYSICAL(play->objectCtx.status[play->objectCtx.subKeepIndex].segment);
     }
 
     if (cmd->specialFiles.cUpElfMsgNum != 0) {
@@ -350,7 +350,7 @@ void Scene_LoadAreaTextures(PlayState* play, s32 fileIndex) {
         { SEGMENT_ROM_START(scene_texture_07), SEGMENT_ROM_END(scene_texture_07) },
         { SEGMENT_ROM_START(scene_texture_08), SEGMENT_ROM_END(scene_texture_08) },
     };
-    u32 vromStart = sceneTextureFiles[fileIndex].vromStart;
+    uintptr_t vromStart = sceneTextureFiles[fileIndex].vromStart;
     size_t size = sceneTextureFiles[fileIndex].vromEnd - vromStart;
 
     if (size != 0) {