Document gfxalloc.c

include/functions.h

@@ -1258,8 +1258,8 @@ void* Graph_Alloc2(GraphicsContext* gfxCtx, size_t size);
 void Graph_OpenDisps(Gfx** dispRefs, GraphicsContext* gfxCtx, const char* file, int line);
 void Graph_CloseDisps(Gfx** dispRefs, GraphicsContext* gfxCtx, const char* file, int line);
 #endif
-Gfx* Gfx_Open(Gfx* gfx);
-Gfx* Gfx_Close(Gfx* gfx, Gfx* dst);
+Gfx* Gfx_Open(Gfx* gfxDisp);
+Gfx* Gfx_Close(Gfx* gfxDisp, Gfx* gfx);
 void* Gfx_Alloc(Gfx** gfxP, u32 size);
 ListAlloc* ListAlloc_Init(ListAlloc* this);
 void* ListAlloc_Alloc(ListAlloc* this, u32 size);

src/code/flg_set.c

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

src/code/gfxalloc.c

@@ -1,14 +1,37 @@
 #include "global.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.
+ * @returns a new graphics display list pointer.
+ *
+ * @note This is used to give WORK_DISP more memory to write instructions without increasing the WORK_DISP buffer size.
+ */
+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
+ * @returns gfxDisp's new position
+ */
+Gfx* Gfx_Close(Gfx* gfxDisp, Gfx* gfx) {
+    gSPBranchList(gfxDisp, gfx);
+    return gfx;
 }
 
+/**
+ * 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
+ * @returns start pointer to the allocated memory
+ */
 void* Gfx_Alloc(Gfx** gfxP, u32 size) {
     u8* ptr;
     Gfx* dst;

src/code/z_debug.c

@@ -280,18 +280,17 @@ 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* tempGfxDisp;
+    Gfx* lockedGfxDisp;
     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);
+    tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+    gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
+    GfxPrint_Open(&printer, tempGfxDisp);
 
     if ((OREG(0) == 1) || (OREG(0) == 8)) {
         DebugCamera_DrawScreenText(&printer);
@@ -305,10 +304,10 @@ void Debug_DrawText(GraphicsContext* gfxCtx) {
 
     sDebugCamTextEntryCount = 0;
 
-    gfx = GfxPrint_Close(&printer);
-    gSPEndDisplayList(gfx++);
-    Gfx_Close(opaStart, gfx);
-    POLY_OPA_DISP = gfx;
+    tempGfxDisp = GfxPrint_Close(&printer);
+    gSPEndDisplayList(tempGfxDisp++);
+    Gfx_Close(lockedGfxDisp, tempGfxDisp);
+    POLY_OPA_DISP = tempGfxDisp;
 
     CLOSE_DISPS(gfxCtx, "../z_debug.c", 664);
 

src/code/z_kankyo.c

@@ -972,18 +972,19 @@ 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* tempGfxDisp;
+            Gfx* lockedGfxDisp;
 
             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;
+            tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+            gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
+            Environment_PrintDebugInfo(play, &tempGfxDisp);
+
+            gSPEndDisplayList(tempGfxDisp++);
+            Gfx_Close(lockedGfxDisp, tempGfxDisp);
+            POLY_OPA_DISP = tempGfxDisp;
+
             CLOSE_DISPS(play->state.gfxCtx, "../z_kankyo.c", 1690);
         }
 #endif

src/code/z_message.c

@@ -3891,8 +3891,8 @@ void Message_DrawDebugText(PlayState* play, Gfx** p) {
 #endif
 
 void Message_Draw(PlayState* play) {
-    Gfx* plusOne;
-    Gfx* polyOpaP;
+    Gfx* tempGfxDisp;
+    Gfx* lockedGfxDisp;
 #if OOT_VERSION < GC_US
     s32 pad;
 #endif
@@ -3906,21 +3906,21 @@ 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;
+        tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+        gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
+        Message_DrawDebugText(play, &tempGfxDisp);
+        gSPEndDisplayList(tempGfxDisp++);
+        Gfx_Close(lockedGfxDisp, tempGfxDisp);
+        POLY_OPA_DISP = tempGfxDisp;
     }
 #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;
+    tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+    gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
+    Message_DrawMain(play, &tempGfxDisp);
+    gSPEndDisplayList(tempGfxDisp++);
+    Gfx_Close(lockedGfxDisp, tempGfxDisp);
+    POLY_OPA_DISP = tempGfxDisp;
     CLOSE_DISPS(play->state.gfxCtx, "../z_message_PAL.c", 3582);
 }
 

src/code/z_play.c

@@ -1157,11 +1157,11 @@ 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* tempGfxDisp;
+            Gfx* lockedGfxDisp;
 
-            gfxP = Gfx_Open(sp1CC);
-            gSPDisplayList(OVERLAY_DISP++, gfxP);
+            tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+            gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
 
             if ((this->transitionMode == TRANS_MODE_INSTANCE_RUNNING) ||
                 (this->transitionMode == TRANS_MODE_INSTANCE_WAIT) || (this->transitionCtx.transitionType >= 56)) {
@@ -1172,11 +1172,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, &tempGfxDisp);
+                this->transitionCtx.draw(&this->transitionCtx.instanceData, &tempGfxDisp);
             }
 
-            TransitionFade_Draw(&this->transitionFadeFlash, &gfxP);
+            TransitionFade_Draw(&this->transitionFadeFlash, &tempGfxDisp);
 
 #if PLATFORM_N64
             if (gVisMonoColor.a != 0)
@@ -1185,12 +1185,12 @@ void Play_Draw(PlayState* this) {
 #endif
             {
                 gPlayVisMono.vis.primColor.rgba = gVisMonoColor.rgba;
-                VisMono_Draw(&gPlayVisMono, &gfxP);
+                VisMono_Draw(&gPlayVisMono, &tempGfxDisp);
             }
 
-            gSPEndDisplayList(gfxP++);
-            Gfx_Close(sp1CC, gfxP);
-            POLY_OPA_DISP = gfxP;
+            gSPEndDisplayList(tempGfxDisp++);
+            Gfx_Close(lockedGfxDisp, tempGfxDisp);
+            POLY_OPA_DISP = tempGfxDisp;
         }
 
         if (gTransitionTileState == TRANS_TILE_READY) {

src/overlays/actors/ovl_En_Mag/z_en_mag.c

@@ -803,20 +803,19 @@ void EnMag_DrawInner(Actor* thisx, PlayState* play, Gfx** gfxP) {
 
 void EnMag_Draw(Actor* thisx, PlayState* play) {
     s32 pad;
-    Gfx* gfx;
-    Gfx* gfxRef;
+    Gfx* tempGfxDisp;
+    Gfx* lockedGfxDisp;
 
     OPEN_DISPS(play->state.gfxCtx, "../z_en_mag.c", 1151);
 
-    gfxRef = POLY_OPA_DISP;
-    gfx = Gfx_Open(gfxRef);
-    gSPDisplayList(OVERLAY_DISP++, gfx);
+    tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+    gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
 
-    EnMag_DrawInner(thisx, play, &gfx);
+    EnMag_DrawInner(thisx, play, &tempGfxDisp);
 
-    gSPEndDisplayList(gfx++);
-    Gfx_Close(gfxRef, gfx);
-    POLY_OPA_DISP = gfx;
+    gSPEndDisplayList(tempGfxDisp++);
+    Gfx_Close(lockedGfxDisp, tempGfxDisp);
+    POLY_OPA_DISP = tempGfxDisp;
 
     CLOSE_DISPS(play->state.gfxCtx, "../z_en_mag.c", 1161);
 }

src/overlays/misc/ovl_kaleido_scope/z_kaleido_debug.c

@@ -98,8 +98,8 @@ void KaleidoScope_DrawDebugEditor(PlayState* play) {
     static s32 heldDBtnTimer = 0;
     PauseContext* pauseCtx = &play->pauseCtx;
     Input* input = &play->state.input[0];
-    Gfx* gfx;
-    Gfx* gfxRef;
+    Gfx* tempGfxDisp;
+    Gfx* lockedGfxDisp;
     s16 spD8[4];
     s16 slot;
     s16 i;
@@ -123,15 +123,14 @@ void KaleidoScope_DrawDebugEditor(PlayState* play) {
     gDPSetCombineLERP(POLY_OPA_DISP++, 0, 0, 0, PRIMITIVE, TEXEL0, 0, PRIMITIVE, 0, 0, 0, 0, PRIMITIVE, TEXEL0, 0,
                       PRIMITIVE, 0);
 
-    gfxRef = POLY_OPA_DISP;
-    gfx = Gfx_Open(gfxRef);
-    gSPDisplayList(OVERLAY_DISP++, gfx);
+    tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+    gSPDisplayList(OVERLAY_DISP++, tempGfxDisp);
 
-    KaleidoScope_DrawDebugEditorText(&gfx);
+    KaleidoScope_DrawDebugEditorText(&tempGfxDisp);
 
-    gSPEndDisplayList(gfx++);
-    Gfx_Close(gfxRef, gfx);
-    POLY_OPA_DISP = gfx;
+    gSPEndDisplayList(tempGfxDisp++);
+    Gfx_Close(lockedGfxDisp, tempGfxDisp);
+    POLY_OPA_DISP = tempGfxDisp;
 
     gDPPipeSync(POLY_OPA_DISP++);
     gDPSetPrimColor(POLY_OPA_DISP++, 0, 0, 255, 0, 0, 255);

src/overlays/misc/ovl_kaleido_scope/z_kaleido_scope.c

@@ -832,25 +832,24 @@ static PreRender sPlayerPreRender;
 static void* sPreRenderCvg;
 
 void KaleidoScope_SetupPlayerPreRender(PlayState* play) {
-    Gfx* gfx;
-    Gfx* gfxRef;
+    Gfx* tempGfxDisp;
+    Gfx* lockedGfxDisp;
     void* fbuf;
 
     fbuf = play->state.gfxCtx->curFrameBuffer;
 
     OPEN_DISPS(play->state.gfxCtx, "../z_kaleido_scope_PAL.c", 496);
 
-    gfxRef = POLY_OPA_DISP;
-    gfx = Gfx_Open(gfxRef);
-    gSPDisplayList(WORK_DISP++, gfx);
+    tempGfxDisp = Gfx_Open(lockedGfxDisp = POLY_OPA_DISP);
+    gSPDisplayList(WORK_DISP++, tempGfxDisp);
 
     PreRender_SetValues(&sPlayerPreRender, PAUSE_EQUIP_PLAYER_WIDTH, PAUSE_EQUIP_PLAYER_HEIGHT, fbuf, NULL);
-    PreRender_SaveFramebuffer(&sPlayerPreRender, &gfx);
-    PreRender_DrawCoverage(&sPlayerPreRender, &gfx);
+    PreRender_SaveFramebuffer(&sPlayerPreRender, &tempGfxDisp);
+    PreRender_DrawCoverage(&sPlayerPreRender, &tempGfxDisp);
 
-    gSPEndDisplayList(gfx++);
-    Gfx_Close(gfxRef, gfx);
-    POLY_OPA_DISP = gfx;
+    gSPEndDisplayList(tempGfxDisp++);
+    Gfx_Close(lockedGfxDisp, tempGfxDisp);
+    POLY_OPA_DISP = tempGfxDisp;
 
     R_GRAPH_TASKSET00_FLAGS |= 1;