Frame loop
After boot, SYS_Main (exe/slus_004_22@0x8014AAC8) never returns. Every frame, from the title to the credits, is one pass through this loop. The loop owns the display, the controller read and the CD loader tick; game logic runs in the four callback threads of the scheduler. Primitive layouts: rendering.
The double-buffered frame
Section titled “The double-buffered frame”The display is double-buffered. Each buffer has a 144-byte render record at g_GfxDisplayFrames (exe/slus_004_22@0x80143D48). A record holds the display and draw environments, an 8-word ordering table and the arena in which the frame’s primitives are built. VRAM holds two 320 x 240 frame buffers, one at y = 0 and one at y = 0xF0. Each record draws into one buffer and displays the other.
While the GPU draws frame N from one record, the CPU builds frame N + 1 in the other. g_FrameBufferIndex (exe/slus_004_22@0x80143D44) selects the record being built and flips once per pass. The GPU starts early in the pass and runs in parallel with the controller read, the callbacks and the loader tick. The pass ends by waiting for the GPU. A picture appears one pass after the logic that built it.
Game code reaches the primitive arena through GFX_AddPrim (exe/slus_004_22@0x8014E5A0). Each call appends one primitive to one of eight layer chains. At the end of the pass SYS_SubmitFrame (exe/slus_004_22@0x8014B0F0) splices the eight chains into the record’s ordering table.
The callback threads
Section titled “The callback threads”CallbackRun (exe/slus_004_22@0x8014B73C) is the only place game code runs: up to four cooperative kernel threads, one per callback slot. Each runs until it calls CallbackWait (resume after n passes) or CallbackExit; control then returns to CallbackRun, which moves to the next slot. Nothing pre-empts a thread, so a thread that never yields freezes the game. Slot assignments: scheduler.
Order of one pass
Section titled “Order of one pass”SYS_Main runs these steps in order once per pass. The GPU work that step 5 starts overlaps steps 6 to 11; step 12 waits for it.
| Step | Call | Effect |
|---|---|---|
| 1 | VSync(2) |
wait until two vertical blanks have passed since the previous VSync call |
| 2 | rand() |
advance the PsyQ random state once |
| 3 | PutDispEnv, PutDrawEnv |
apply the environments of the record that the previous pass built |
| 4 | GFX_UploadPalette, GFX_UpdateTransferQueue |
copy the staged palette and the queued images to VRAM |
| 5 | DrawOTag |
start the GPU on the ordering table that the previous pass built |
| 6 | SYS_UpdateKeyState |
read controller 1 |
| 7 | SND_UpdateVoiceStatus (exe/slus_004_22@0x8015D044) |
refresh the status bytes of the 24 SPU voices |
| 8 | flip g_FrameBufferIndex; ClearOTagR; SYS_PrepareFrame |
select the other record and reset its table, layer chains and primitive cursor |
| 9 | reset-combo check on g_InputHeld |
request the soft reset when Select and Start have been held long enough |
| 10 | CallbackRun |
run every active callback thread until it yields |
| 11 | EMI_Update |
tick the CD loader or the XA audio player |
| 12 | g_SysLastVSync = VSync(1); DrawSync(0); SYS_SubmitFrame; g_FrameCount++ |
wait for the GPU, then link the new layer chains into the ordering table; count the pass |
VSync(2) caps the loop at one pass per two vertical blanks. On an NTSC display, which SYS_InitHardware (exe/slus_004_22@0x8014AD28) selects, that is 30 passes per second. A longer pass slows the game; frames are not dropped. [inferred] from the PsyQ VSync contract and the NTSC mode. The play clock agrees: Game_UpdateClock (emi/etc/game/00@0x80198CAC) adds one tick per main-loop pass and rolls 30 ticks into one second.
The GPU overlap with steps 6 to 11 follows from the PsyQ contract that DrawOTag starts a DMA and returns. [inferred]
Render records and the primitive arena
Section titled “Render records and the primitive arena”Fields of one 144-byte render record that the loop addresses:
| Offset | Size | Type | Meaning |
|---|---|---|---|
0x00 |
20 | DISPENV |
the display environment |
0x14 |
92 | DRAWENV |
the draw environment |
0x70 |
32 | u32[8] |
ordering table, 8 words, cleared in reverse by ClearOTagR |
0x8C |
4 | u32 |
the last word of the table, the address that DrawOTag receives |
SYS_PrepareFrame (exe/slus_004_22@0x8014B020) resets the record that is about to be built. For buffer index b it:
- sets the primitive cursor
g_GfxPrimCursorto0x80020000 + b * 0x9000; - seeds the eight layer chain heads from the packet table,
b * 0x20bytes in; - resets 56 cell records of 48 bytes at
D_80142CC0[inferred], which the area map engine uses; - sets
D_801459F8to0x800E4800andD_801459FCto0x800F5000, the area work window and the area code base.
GFX_AddPrim appends a primitive only while the cursor plus the primitive size stays below 0x80028FCC + b * 0x9000, so the arena of one buffer is 36,812 bytes. When it is full the call returns silently and the primitive is lost. Every sprite, window, glyph and map cell of a frame draws from this arena.
SYS_UpdateKeyState (exe/slus_004_22@0x8014AFC0) calls PadRead(0), which returns both ports in one 32-bit word. It stores the held buttons of each half, keeps the previous values, and computes the newly pressed bits as pad & (pad ^ previous). The rest of the game reads g_InputHeld (exe/slus_004_22@0x80145AA4) and g_InputPressed (exe/slus_004_22@0x80145AA8), which are the port 1 words. The port 2 half is stored, and no reader of it is known. [unknown]
Soft reset
Section titled “Soft reset”Holding Select and Start together returns the game to the first boot callback. The test is (g_InputHeld & (PADselect | PADstart)) == 0x900. A counter g_SysResetHoldFrames (exe/slus_004_22@0x80143F44) counts the passes in which it holds and clears when it stops. On the 61st pass in a row (about 2 seconds), and only if EMI_IsReady is true, the loop runs SND_Exit and CallbackStopAll, then CallbackRegister(0, SYS_StartFrontend). The game reloads FIRST.EMI and GAME.EMI and returns to the title without the logo. If the loader is busy, the reset waits.
Loader tick
Section titled “Loader tick”EMI_Update (exe/slus_004_22@0x80163010) looks at g_EmiServiceMode. In mode 1 it runs EMI_UpdateStream, the disc read for overlays and data. In mode 2 it runs SND_UpdateXA, the XA audio player. In any other mode it does nothing (loading, audio system).
Late frames
Section titled “Late frames”A random encounter does not start in a frame whose drawing ended late. SYS_CaptureDrawTime (exe/slus_004_22@0x8014B17C) is the DrawSync callback and stores VSync(1) in D_80143EFC. Area_CanStartEncounter (emi/etc/game/00@0x801B3EB0) returns 0 when D_80143EFC >= 0xF1 and g_GameRequestFlags bit 0 is clear. By the PsyQ contract VSync(1) returns the horizontal blanks elapsed since the last VSync call, so the limit is about 240 scan lines. [inferred]
Open questions
Section titled “Open questions”| Question | What would settle it |
|---|---|
| Whether a 21st queued VRAM upload overflows the 20-entry queue | Read the producers of D_80145A00 for a bound check |
| Any use of the port 2 controller | Search for readers of the high halves that SYS_UpdateKeyState writes |
| Real frame time and the CPU and GPU overlap | A timed run; static reading cannot measure it |
The unit of D_80143EFC |
The PsyQ VSync documentation, then compare with 0xF1 |
Sources and confidence
Section titled “Sources and confidence”- Confidence: medium. The order of the pass, the records and the limits are read in the code, but the frame rate, the GPU overlap and the unit of the late-frame value are
[inferred]from the PsyQ contract. - Evidence: the code of
SYS_Main,SYS_PrepareFrame,SYS_SubmitFrame,GFX_AddPrim,GFX_UpdateTransferQueue,SYS_UpdateKeyState,CallbackRunandEMI_Update; the play clock ofGame_UpdateClock.
Related
Section titled “Related”- Scheduler and tasks: what runs in each callback thread.
- Rendering: primitive layouts, layer order and drawing.
- Loading: what the loader tick does with a stream.
- Boot: how the first pass starts.