Document gfxalloc.c

include/gfxalloc.h

@@ -2,9 +2,33 @@
 #define GFXALLOC_H
 
 #include "ultra64.h"
+#include "gfx.h"
 
-Gfx* Gfx_Open(Gfx* gfx);
-Gfx* Gfx_Close(Gfx* gfx, Gfx* dst);
+Gfx* Gfx_Open(Gfx* gfxDisp);
+Gfx* Gfx_Close(Gfx* gfxDisp, Gfx* gfxAllocDisp);
 void* Gfx_Alloc(Gfx** gfxP, u32 size);
 
+/**
+ * Creates a new temporary graphics display list pointer, using the memory reserved by POLY_OPA_DISP
+ * POLY_OPA_DISP cannot be written to until GFX_ALLOC_CLOSE is called.
+ *
+ * @param gfxAllocDisp is the new temporary graphics display list pointer.
+ * @param tempGfx is an intermediate Gfx* variable that should not be touched.
+ * @param disp is the top level display list that is being given more memory.
+ */
+#define GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, disp)     \
+    gfxAllocDisp = Gfx_Open(tempGfx = POLY_OPA_DISP);   \
+    gSPDisplayList(disp++, gfxAllocDisp)
+
+/**
+ * Closes the graphics display list created by GFX_ALLOC_OPEN.
+ *
+ * @param gfxAllocDisp is the graphics display list pointer that was created with GFX_ALLOC_OPEN
+ * @param tempGfx is the same Gfx* variable that was passed into GFX_ALLOC_OPEN
+ */
+#define GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx)  \
+    gSPEndDisplayList(gfxAllocDisp++);          \
+    Gfx_Close(tempGfx, gfxAllocDisp);           \
+    POLY_OPA_DISP = gfxAllocDisp
+
 #endif

src/code/flg_set.c

@@ -68,21 +68,19 @@ void FlagSet_Update(PlayState* play) {
 
     GraphicsContext* gfxCtx = play->state.gfxCtx;
     Input* input = &play->state.input[0];
-    Gfx* gfx;
-    Gfx* polyOpa;
+    Gfx* gfxAllocDisp;
+    Gfx* tempGfx;
 
     OPEN_DISPS(gfxCtx, "../flg_set.c", 131);
 
     {
         GfxPrint printer;
         s32 pad;
 
-        polyOpa = POLY_OPA_DISP;
-        gfx = Gfx_Open(polyOpa);
-        gSPDisplayList(OVERLAY_DISP++, gfx);
+        GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
 
         GfxPrint_Init(&printer);
-        GfxPrint_Open(&printer, gfx);
+        GfxPrint_Open(&printer, gfxAllocDisp);
         GfxPrint_SetColor(&printer, 250, 50, 50, 255);
         GfxPrint_SetPos(&printer, 4, 13);
         GfxPrint_Printf(&printer, entries[entryIdx].name);
@@ -167,12 +165,10 @@ void FlagSet_Update(PlayState* play) {
             timer--;
         }
 
-        gfx = GfxPrint_Close(&printer);
+        gfxAllocDisp = GfxPrint_Close(&printer);
         GfxPrint_Destroy(&printer);
 
-        gSPEndDisplayList(gfx++);
-        Gfx_Close(polyOpa, gfx);
-        POLY_OPA_DISP = gfx;
+        GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
     }
 
     if (CHECK_BTN_ALL(input->press.button, BTN_L)) {

src/code/game.c

@@ -164,32 +164,31 @@ void GameState_DrawInputDisplay(u16 input, Gfx** gfxP) {
 #endif
 
 void GameState_Draw(GameState* gameState, GraphicsContext* gfxCtx) {
-    Gfx* newDList;
-    Gfx* polyOpaP;
+    Gfx* gfxAllocDisp;
+    Gfx* tempGfx;
 
     OPEN_DISPS(gfxCtx, "../game.c", 746);
 
-    newDList = Gfx_Open(polyOpaP = POLY_OPA_DISP);
-    gSPDisplayList(OVERLAY_DISP++, newDList);
+    GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
 
     if (R_ENABLE_FB_FILTER == 1) {
-        GameState_SetFBFilter(&newDList);
+        GameState_SetFBFilter(&gfxAllocDisp);
     }
 
 #if OOT_DEBUG
     sLastButtonPressed = gameState->input[0].press.button | gameState->input[0].cur.button;
     if (R_DISABLE_INPUT_DISPLAY == 0) {
-        GameState_DrawInputDisplay(sLastButtonPressed, &newDList);
+        GameState_DrawInputDisplay(sLastButtonPressed, &gfxAllocDisp);
     }
 
     if (R_ENABLE_AUDIO_DBG & 1) {
         s32 pad;
         GfxPrint printer;
 
         GfxPrint_Init(&printer);
-        GfxPrint_Open(&printer, newDList);
+        GfxPrint_Open(&printer, gfxAllocDisp);
         AudioDebug_Draw(&printer);
-        newDList = GfxPrint_Close(&printer);
+        gfxAllocDisp = GfxPrint_Close(&printer);
         GfxPrint_Destroy(&printer);
     }
 #endif
@@ -206,9 +205,7 @@ void GameState_Draw(GameState* gameState, GraphicsContext* gfxCtx) {
         R_ENABLE_ARENA_DBG = 0;
     }
 
-    gSPEndDisplayList(newDList++);
-    Gfx_Close(polyOpaP, newDList);
-    POLY_OPA_DISP = newDList;
+    GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
 
     CLOSE_DISPS(gfxCtx, "../game.c", 800);
 
@@ -237,23 +234,20 @@ void GameState_SetFrameBuffer(GraphicsContext* gfxCtx) {
 }
 
 void func_800C49F4(GraphicsContext* gfxCtx) {
-    Gfx* newDlist;
-    Gfx* polyOpaP;
+    Gfx* gfxAllocDisp;
+    Gfx* tempGfx;
 
     OPEN_DISPS(gfxCtx, "../game.c", 846);
 
-    newDlist = Gfx_Open(polyOpaP = POLY_OPA_DISP);
-    gSPDisplayList(OVERLAY_DISP++, newDlist);
+    GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
 
 #if PLATFORM_N64
     if (D_80121212 != 0) {
-        func_801C6EA0(&newDlist);
+        func_801C6EA0(&gfxAllocDisp);
     }
 #endif
 
-    gSPEndDisplayList(newDlist++);
-    Gfx_Close(polyOpaP, newDlist);
-    POLY_OPA_DISP = newDlist;
+    GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
 
     CLOSE_DISPS(gfxCtx, "../game.c", 865);
 }

src/code/gfxalloc.c

@@ -1,23 +1,49 @@
-#include "global.h"
+#include "ultra64.h"
+#include "gfxalloc.h"
 
-Gfx* Gfx_Open(Gfx* gfx) {
-    return gfx + 1;
+/**
+ * Creates a new temporary graphics display list pointer, using the memory reserved by gfxDisp
+ *
+ * @param gfxDisp is the display list yielding memory. It cannot be written to until Gfx_Close is called.
+ * @return a new graphics display list pointer.
+ *
+ * @note This is used to take memory allocated to a larger display buffer and use it for a smaller display buffer.
+ * For example, space in POLY_OPA_DISP can be reserved for WORK_DISP and OVERLAY_DISP task data.
+ */
+Gfx* Gfx_Open(Gfx* gfxDisp) {
+    // reserve space for a gSPBranchList command when Gfx_Close is called
+    return gfxDisp + 1;
 }
 
-Gfx* Gfx_Close(Gfx* gfx, Gfx* dst) {
-    gSPBranchList(gfx, dst);
-    return dst;
+/**
+ * Closes the graphics display list created by Gfx_Open.
+ *
+ * @param gfxDisp is the display list yielding memory.
+ * @param gfx is the graphics display list pointer that was created with Gfx_Open
+ * @return gfxDisp's new position.
+ *
+ * @note gfxDisp must be updated after the call with the return value of this function to complete the operation.
+ */
+Gfx* Gfx_Close(Gfx* gfxDisp, Gfx* gfxAllocDisp) {
+    gSPBranchList(gfxDisp, gfxAllocDisp);
+    return gfxAllocDisp;
 }
 
+/**
+ * Allocates a fixed size block of memory for graphics data on a graphics display list
+ *
+ * @param gfxP is a pointer to a graphics display list pointer
+ * @param size is the number of bytes to reserve
+ * @return the start pointer to the allocated memory
+ */
 void* Gfx_Alloc(Gfx** gfxP, u32 size) {
     u8* ptr;
     Gfx* dst;
 
     size = ALIGN8(size);
-
     ptr = (u8*)(*gfxP + 1);
-
     dst = (Gfx*)(ptr + size);
+
     gSPBranchList(*gfxP, dst);
 
     *gfxP = dst;

src/code/z_debug.c

@@ -281,18 +281,16 @@ void Regs_DrawEditor(GfxPrint* printer) {
  * Draws the Reg Editor and Debug Camera text on screen
  */
 void Debug_DrawText(GraphicsContext* gfxCtx) {
-    Gfx* gfx;
-    Gfx* opaStart;
+    Gfx* gfxAllocDisp;
+    Gfx* tempGfx;
     GfxPrint printer;
     s32 pad;
 
     OPEN_DISPS(gfxCtx, "../z_debug.c", 628);
 
     GfxPrint_Init(&printer);
-    opaStart = POLY_OPA_DISP;
-    gfx = Gfx_Open(POLY_OPA_DISP);
-    gSPDisplayList(OVERLAY_DISP++, gfx);
-    GfxPrint_Open(&printer, gfx);
+    GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
+    GfxPrint_Open(&printer, gfxAllocDisp);
 
     if ((OREG(0) == 1) || (OREG(0) == 8)) {
         DebugCamera_DrawScreenText(&printer);
@@ -306,10 +304,8 @@ void Debug_DrawText(GraphicsContext* gfxCtx) {
 
     sDebugCamTextEntryCount = 0;
 
-    gfx = GfxPrint_Close(&printer);
-    gSPEndDisplayList(gfx++);
-    Gfx_Close(opaStart, gfx);
-    POLY_OPA_DISP = gfx;
+    gfxAllocDisp = GfxPrint_Close(&printer);
+    GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
 
     CLOSE_DISPS(gfxCtx, "../z_debug.c", 664);
 

src/code/z_demo.c

@@ -2217,18 +2217,14 @@ void CutsceneHandler_RunScript(PlayState* play, CutsceneContext* csCtx) {
     if (gSaveContext.save.cutsceneIndex >= 0xFFF0) {
 #if OOT_DEBUG
         if (BREG(0) != 0) {
-            Gfx* displayList;
-            Gfx* prevDisplayList;
+            Gfx* gfxAllocDisp;
+            Gfx* tempGfx;
 
             OPEN_DISPS(play->state.gfxCtx, "../z_demo.c", 4101);
 
-            prevDisplayList = POLY_OPA_DISP;
-            displayList = Gfx_Open(POLY_OPA_DISP);
-            gSPDisplayList(OVERLAY_DISP++, displayList);
-            Cutscene_DrawDebugInfo(play, &displayList, csCtx);
-            gSPEndDisplayList(displayList++);
-            Gfx_Close(prevDisplayList, displayList);
-            POLY_OPA_DISP = displayList;
+            GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
+            Cutscene_DrawDebugInfo(play, &gfxAllocDisp, csCtx);
+            GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
 
             CLOSE_DISPS(play->state.gfxCtx, "../z_demo.c", 4108);
         }

src/code/z_kankyo.c

@@ -981,18 +981,15 @@ void Environment_Update(PlayState* play, EnvironmentContext* envCtx, LightContex
 
 #if OOT_DEBUG
         if (R_ENABLE_ARENA_DBG != 0 || CREG(2) != 0) {
-            Gfx* displayList;
-            Gfx* prevDisplayList;
+            Gfx* gfxAllocDisp;
+            Gfx* tempGfx;
 
             OPEN_DISPS(play->state.gfxCtx, "../z_kankyo.c", 1682);
 
-            prevDisplayList = POLY_OPA_DISP;
-            displayList = Gfx_Open(POLY_OPA_DISP);
-            gSPDisplayList(OVERLAY_DISP++, displayList);
-            Environment_PrintDebugInfo(play, &displayList);
-            gSPEndDisplayList(displayList++);
-            Gfx_Close(prevDisplayList, displayList);
-            POLY_OPA_DISP = displayList;
+            GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
+            Environment_PrintDebugInfo(play, &gfxAllocDisp);
+            GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
+
             CLOSE_DISPS(play->state.gfxCtx, "../z_kankyo.c", 1690);
         }
 #endif

src/code/z_message.c

@@ -3973,8 +3973,8 @@ void Message_DrawDebugText(PlayState* play, Gfx** p) {
 #endif
 
 void Message_Draw(PlayState* play) {
-    Gfx* plusOne;
-    Gfx* polyOpaP;
+    Gfx* gfxAllocDisp;
+    Gfx* tempGfx;
 #if OOT_VERSION < GC_US
     s32 pad;
 #endif
@@ -3988,21 +3988,15 @@ void Message_Draw(PlayState* play) {
     watchVar = gSaveContext.save.info.scarecrowLongSongSet;
     Message_DrawDebugVariableChanged(&watchVar, play->state.gfxCtx);
     if (BREG(0) != 0 && play->msgCtx.textId != 0) {
-        plusOne = Gfx_Open(polyOpaP = POLY_OPA_DISP);
-        gSPDisplayList(OVERLAY_DISP++, plusOne);
-        Message_DrawDebugText(play, &plusOne);
-        gSPEndDisplayList(plusOne++);
-        Gfx_Close(polyOpaP, plusOne);
-        POLY_OPA_DISP = plusOne;
+        GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
+        Message_DrawDebugText(play, &gfxAllocDisp);
+        GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
     }
 #endif
 
-    plusOne = Gfx_Open(polyOpaP = POLY_OPA_DISP);
-    gSPDisplayList(OVERLAY_DISP++, plusOne);
-    Message_DrawMain(play, &plusOne);
-    gSPEndDisplayList(plusOne++);
-    Gfx_Close(polyOpaP, plusOne);
-    POLY_OPA_DISP = plusOne;
+    GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
+    Message_DrawMain(play, &gfxAllocDisp);
+    GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
     CLOSE_DISPS(play->state.gfxCtx, "../z_message_PAL.c", 3582);
 }
 

src/code/z_play.c

@@ -1159,11 +1159,10 @@ void Play_Draw(PlayState* this) {
         gSPSegment(POLY_OPA_DISP++, 0x01, this->billboardMtx);
 
         if (!OOT_DEBUG || (R_HREG_MODE != HREG_MODE_PLAY) || R_PLAY_DRAW_COVER_ELEMENTS) {
-            Gfx* gfxP;
-            Gfx* sp1CC = POLY_OPA_DISP;
+            Gfx* gfxAllocDisp;
+            Gfx* tempGfx;
 
-            gfxP = Gfx_Open(sp1CC);
-            gSPDisplayList(OVERLAY_DISP++, gfxP);
+            GFX_ALLOC_OPEN(gfxAllocDisp, tempGfx, OVERLAY_DISP);
 
             if ((this->transitionMode == TRANS_MODE_INSTANCE_RUNNING) ||
                 (this->transitionMode == TRANS_MODE_INSTANCE_WAIT) || (this->transitionCtx.transitionType >= 56)) {
@@ -1174,11 +1173,11 @@ void Play_Draw(PlayState* this) {
 
                 SET_FULLSCREEN_VIEWPORT(&view);
 
-                View_ApplyTo(&view, VIEW_ALL, &gfxP);
-                this->transitionCtx.draw(&this->transitionCtx.instanceData, &gfxP);
+                View_ApplyTo(&view, VIEW_ALL, &gfxAllocDisp);
+                this->transitionCtx.draw(&this->transitionCtx.instanceData, &gfxAllocDisp);
             }
 
-            TransitionFade_Draw(&this->transitionFadeFlash, &gfxP);
+            TransitionFade_Draw(&this->transitionFadeFlash, &gfxAllocDisp);
 
 #if PLATFORM_N64
             if (gVisMonoColor.a != 0)
@@ -1187,12 +1186,10 @@ void Play_Draw(PlayState* this) {
 #endif
             {
                 gPlayVisMono.vis.primColor.rgba = gVisMonoColor.rgba;
-                VisMono_Draw(&gPlayVisMono, &gfxP);
+                VisMono_Draw(&gPlayVisMono, &gfxAllocDisp);
             }
 
-            gSPEndDisplayList(gfxP++);
-            Gfx_Close(sp1CC, gfxP);
-            POLY_OPA_DISP = gfxP;
+            GFX_ALLOC_CLOSE(gfxAllocDisp, tempGfx);
         }
 
         if (gTransitionTileState == TRANS_TILE_READY) {