psxrecomp/accuracy/axis5_gpu.md

Axis 5 — GPU Accuracy Findings & Fix Plan

Cross-reference of the psxrecomp GPU implementation against the in-tree Beetle/ Mednafen-PSX oracle (beetle-psx/mednafen/psx/gpu*.cpp, the byte-exact SW renderer) and nocash psx-spx. READ-ONLY research; no source modified.

Oracle note: in Beetle the software renderer is the hardware oracle; the rsx_intf_* GL/Vulkan paths are separate approximations and are NOT the comparison target. At upscale_shift==0, no PGXP, line_render_mode==0, Beetle SW = pure mednafen-PSX behavior.

Our files:

• runtime/src/gpu.c — GPU register/command front end (GPUSTAT, GP0/GP1 decode, VRAM transfers, display config, widescreen machinery).
• runtime/src/gpu_sw_renderer.c — software rasterizer (the default/oracle- comparable backend; also drives 24bpp display decode for the GL path).
• runtime/src/gpu_gl_renderer.c — OpenGL backend (FBO RGBA8 hi-res + R16UI native mirror + stencil mask).

---

1. What our implementation does

1.1 Front end — gpu.c

• GPUSTAT assembled bit-for-bit (gpu_read_gpustat, gpu.c:1216-1290): bits 0-3 texpage X, 4 texpage Y, 5-6 abr, 7-8 texmode, 9 dither, 10 dfe, 11 mask-set, 12 mask-check, 13 interlace field, 14 reverse, 15 tex-disable, 16-22 display mode, 23 display-off, 24 IRQ1, 25 DMA-req, 26 cmd-ready, 27 VRAM-send-ready, 28 DMA-block-ready, 29-30 DMA dir, 31 LCF.
• GP0 command set fully decoded (gpu.c:1585-2620): mono/shaded/textured tri+quad (0x20-0x3F), mono/shaded line + polyline (0x40-0x5F), variable rect / 1x1 dot / 8x8 / 16x16 sprites (0x60-0x7F), FBCopy/FBWrite/FBRead (0x80-0xDF), and env regs E1-E6. Word counts in gp0_command_word_count (gpu.c:2285).
• GP1 reset/display-config commands; GPUREAD packs two 16-bit texels per word from the active VRAM→CPU transfer (gpu.c:1294-1329).
• Quads are split into two triangles with winding (0,1,2)+(2,1,3) (gpu.c:1610-1611, 1663-1665). Textured quads detect an axis-aligned rectangle and route to the faster rect rasterizer (gpu.c:1755-1778).
• Large body of widescreen machinery (squash / native-wide / MMX6 tile reveal) layered on top; identity at 4:3 by design.

1.2 Software rasterizer — gpu_sw_renderer.c

• 1024×512 uint16_t VRAM (15-bit + mask bit). Optional SSAA mirror g_hr and a native-wide compositor surface.
• Semi-transparency: all 4 modes in blend_pixels (sw:211-246). Textured prims blend only when texel bit15 set; untextured always blend when the command's semi flag is set (put_opaque/put_textured, sw:253-313).
• Mask bit: set (force bit15) + check (skip if dest bit15) in the pixel writers and in sw_copy_rect (sw:260,286,654-657). Fill ignores mask.
• Texture window: psx-spx AND/OR formula (sw:324-327). CLUT 4/8/15-bpp fetch (texel_fetch, sw:319-357). Texel 0x0000 = transparent (skipped).
• Triangles: scanline rasterizer with float edge + attribute interpolation (raster_flat_triangle sw:682, raster_gouraud_triangle sw:746, textured sw:864, shaded-textured sw:989). Color interp in 5-bit space. Optional bilinear (texel_fetch_bilinear, opacity-weighted, Beetle- style) — opt-in, non-hardware.
• Lines: Bresenham (sw:1382, 1403), both endpoints plotted.
• Display: 15-bit→ARGB with 5→8 bit replication (c<<3)|(c>>2) (rgb555_to_argb, sw:1503).

1.3 GL backend — gpu_gl_renderer.c

• Authoritative color = RGBA8 hi-res FBO; native R16UI mirror holds raw 1555 for texture sampling + CPU readback; 8-bit stencil mirrors bit15.
• Semi-transparency: all 4 modes via fixed-function blend (apply_psx_blend, gl:697-716; mode 2 = GL_FUNC_REVERSE_SUBTRACT). Correct STP-bit gating via two-pass discard for textured prims.
• Mask bit: implemented via stencil + alpha channel (set + check).
• Texture: in-shader CLUT against VRAM usampler; texture window exact; texel-0 transparent honored; nearest default + opt-in bilinear.
• CPU readback / GPUREAD: PACK shader → R16UI → glReadPixels; 15-bit exact.
• 24bpp display: delegated to the SW decode path.

---

2. Specific discrepancies vs Beetle + psx-spx

Ordered roughly by player-visible impact. Citations: gpu_*.c:line (ours) vs beetle-psx/mednafen/psx/<file>:line (oracle).

D1 — Dithering is completely absent (both renderers) — and the enable bit is decoded but dropped

• Oracle: 4×4 signed dither matrix {{-4,0,-3,1},{2,-2,3,-1},{-3,1,-4,0}, {3,-1,2,-2}} (gpu.cpp:79-85), applied (then >>3 + clamp to 5-bit) to Gouraud polygons, modulated-textured polygons, and lines whenever DitherEnabled (dtd = GP0 E1 bit 9) (gpu.cpp:644-665; gpu_polygon.cpp: 184-211; gpu_line.cpp:145-154). Sprites & raw copies are never dithered.
• Ours: dither_enabled is parsed from GP0(E1) (gpu.c:2071) and surfaced in GPUSTAT bit 9 (gpu.c:1244) but is never forwarded to either renderer. gpu_sw_renderer.c has no dither term anywhere; Gouraud/modulated colors are truncated >>3 with no matrix add. The GL backend likewise has no dither (confirmed; documented "the software path doesn't dither either").
• Effect: visible color banding on Gouraud-shaded surfaces and gradients (skies, lighting ramps, shadows) versus hardware; every dithered frame byte-diffs against the oracle. This is the single largest systematic SW/GL vs hardware divergence.

D2 — SW triangle rasterizer uses float interpolation + inclusive spans, not the PSX fixed-point half-open fill rule

• Oracle: 64-bit fixed-point edges (MakePolyXFP adds (1<<32) - (1<<11) — the sub-pixel bias that yields the PSX top-left rule; gpu_polygon.cpp: 24-43). X span is half-open [x_start, x_bound) (the do { } while(--w>0) loop, gpu_polygon.cpp:165-218), right clip inclusive of ClipX1 ((x+w) > clipx1+1, :143-144). Y spans are top-inclusive/bottom-exclusive (while(yi < yb), :460). Zero-height tri dropped (:272). Oversize reject: |Δx|>=1024 || |Δy|>=512 drops the primitive (:704-728).
• Ours: raster_*_triangle sort by Y, then interpolate edges and attributes in float and fill scanlines with inclusive bounds for (x = sx; x <= ex; x++) (sw:719, 822, 935, 1079); Y loop is inclusive for (y = y0; y <= y2; y++) (sw:693 etc.). No top-left bias, no half-open right/bottom edge, no oversize rejection (only a area2==0 degenerate guard, sw:953).
• Effect: shared triangle edges are filled by both triangles → seam double-draw (visible with semi-transparency: doubled-darkened/brightened edges) and ±1px coverage drift versus hardware on every polygon edge. The inclusive right/bottom edge is the classic "one pixel too wide" PSX rasterizer error. Float interpolation also rounds differently than the fixed-point DDA, shifting interior texel/color sampling.

D3 — Gouraud / textured attribute interpolation is per-scanline float, not the PSX divided-difference fixed-point DDA

• Oracle: attributes carried as fixed-point with a +0.5 seed bias at the core vertex (COORD_MF_INT(v.r) + (1<<(COORD_FBS-1)), gpu_polygon.cpp: 311-313) and stepped by integer AddIDeltas_DX; read out >>24 (:167-169). Texture U/V identical scheme (:294-295).
• Ours: float barycentric-ish interpolation along edges then along the span (sw:795-833 gouraud, sw:937-942 textured). UV truncated (int)fu & 0xFF (sw:942). No +0.5 seed, no fixed-point step.
• Effect: color/texel values drift by up to a few LSB across a polygon vs hardware; combined with D1 (no dither) gradients look both banded and slightly mis-sloped. Texture sampling can pick a neighboring texel at span edges. Lower impact than D1/D2 but contributes to per-pixel diffs.

D4 — SW Gouraud blend math is at 5-bit (correct direction) but mode-0 average lacks the oracle's low-bit truncation semantics; GL blends at 8-bit

• Oracle mode 0 (B/2+F/2): ((F + B) - ((F^B)&0x0421)) >> 1 — strips the per-channel low bit before halving = floor, no rounding (gpu_common.h:28-31). Modes 1/2/3 use branch-free saturating 15-bit math (gpu_common.h:34-69), mode 3 = (F>>2)&0x1CE7 for F/4.
• Ours (SW): blend_pixels does straightforward per-channel (b+f)>>1, min(31), max(0), b+(f>>2) (sw:211-246). For mode 0 (b+f)>>1 equals the oracle's floor only when the discarded low bits don't change the channel sum carry — generally equal at 5-bit per channel, but our halving is on the summed 5-bit channels directly (matches), so SW mode-0 is effectively the same value. Modes 1/2/3 match. Net: SW blend is close-to-exact.
• Ours (GL): blends in RGBA8 with CONSTANT_ALPHA 0.5/0.25 then re-quantizes >>3 at PACK — sub-LSB differences from hardware's 5-bit halving (gl audit). Minor but non-zero.
• Effect: SW essentially faithful; GL has occasional ±1/31 channel error on blended pixels. Low priority relative to D1/D2.

D5 — Mono-quad / textured-quad triangle split winding may flip shared-edge fill vs hardware scan order

• Oracle: draws the quad as two tris but with its own core-vertex / Y-sort per tri and half-open edges, so the shared diagonal is covered exactly once.
• Ours: split (0,1,2) + (2,1,3) (gpu.c:1610-1611). Combined with the inclusive-span bug (D2) the shared edge is drawn by both halves. For Gouraud quads the diagonal interpolation can also differ because each half re-sorts vertices independently in float.
• Effect: visible diagonal seam on semi-transparent quads; couples with D2. Fixing D2 (half-open spans) largely resolves this.

D6 — Sprite (rect) flip + texture-window interaction not modeled

• Oracle: sprites honor GP0(E1) bits 0x3000 SpriteFlip — FlipX sets u_inc=-1 and forces u|=1; FlipY v_inc=-1 (gpu_sprite.cpp:29-40), with a documented low-bit-of-u quirk. Sprites clip inclusively (ClipX1+1, half-open loop) and are never dithered (use the zero dither cell).
• Ours: textured rects/sprites step U/V forward only (sw:1207-1233, u + col/s); no flip handling, and texture-window is applied via texel_fetch (OK) but the sprite path computes its own uv limits for filtering. The 8x8/16x16 sprite handlers always step forward.
• Effect: games using hardware sprite-flip render mirrored sprites incorrectly (wrong texels / shifted by the u|=1 quirk). Many 2D titles flip sprites for character facing; this is a real correctness gap. Lower frequency than D1/D2 but visible where used.

D7 — Rectangle/sprite size & coordinate clamping differs slightly

• Oracle: variable-rect size w = cb & 0x3FF, h = (cb>>16)&0x1FF; coords sign-extended to 11 bits then offset added (gpu_sprite.cpp:147-173).
• Ours mono rect: w = cmd & 0xFFFF then clamp to 1023 / 511 (gpu.c:1898-1901) — should mask &0x3FF/&0x1FF like the textured-rect path (gpu.c:1919-1920) and the oracle, not clamp a full 16-bit value.
• Effect: edge case; a rect width in 0x400-0xFFFF would be clamped to 1023 instead of wrapped/masked. Rare. Low priority.

D8 — GPUSTAT bit 25 (DMA-request) and bit 26/28 (ready) are constant, not FIFO-derived

• Oracle: bit 26 = InCmd==NONE && DrawTimeAvail>=0 && FIFO empty; bit 28 = CalcFIFOReadyBit(); bit 25 depends on the actual FIFO state and DMA dir (gpu.cpp:522-540, 1278-1324).
• Ours: bit 26 always 1, bit 28 always 1, bit 25 = 1 for dir 1/2/3 unconditionally (gpu.c:1266-1281). We process commands instantly so there is no FIFO occupancy to report.
• Effect: code that polls GPUSTAT for FIFO-full/busy before pushing more words never stalls — usually benign (we are "infinitely fast"), but games that gate timing on bit 26/28 transitions see no transition. Tied to the broader timing-axis work; not a pixel-accuracy issue.

D9 — LCF / vblank pacing via a poll-count fallback, not cycle-derived

• Ours: gpu_read_gpustat flips LCF and raises VBLANK after 1000 polls (gpu.c:1228-1236, GPUSTAT_POLL_VBLANK_THRESHOLD). This is an approximation to break BIOS spin loops, separate from the cycle-paced vblank.
• Effect: interlace-field bit 31 and vblank timing are not hardware-faithful (a heuristic). Belongs to the timing axis (FAITHFUL_TIMING_PLAN.md), flagged here for completeness.

D10 — Display path: 5→8 bit expansion differs from oracle scanout

• Oracle scanout (15bpp): (c & 0x1F) << 3 — low bits zero, NO replication (gpu.cpp:1373-1383). 24bpp packs 3 bytes across two words (:1351-1369).
• Ours: rgb555_to_argb replicates (c5<<3)|(c5>>2) (sw:1503-1509).
• Effect: our screen is marginally brighter in the low bits than the oracle's exact scanout. This is a present-time cosmetic choice (arguably better-looking) but means present-time RGB diffs vs the oracle's framebuffer output are non-zero. VRAM contents themselves are unaffected. Low priority; document as an intentional present-time deviation or gate behind the existing PSX_SCREEN LUT.

D11 — No oversize-primitive rejection

• Oracle: drops any tri/line whose vertex span exceeds 1024×512 (gpu_polygon.cpp:704-728; gpu_line.cpp:222-226).
• Ours: no such guard; a malformed/huge primitive rasterizes fully (slow, and can scribble across VRAM where hardware would have dropped it).
• Effect: rare; mainly a robustness/timing divergence. Low priority.

D12 — Textured-polygon texpage attribute did not update GPU draw-mode state — FIXED 2026-07-05

• Oracle: every textured polygon's texpage word is copied into the GPU draw-mode state before drawing — SetTPage(CB[4 + ((cc>>4)&1)] >> 16) runs for all GP0 0x20-0x3F with the texture bit (gpu.cpp:1070-1072). The poly's own word (not the last E1) selects its semi-transparency mode, and later rect/sprite prims (no texpage word) consume the state the poly left behind. Poly words cannot alter dither/draw-to-display (E1-only bits 9-10) nor texture-disable (bit 11 latches only under GP1(09h) TexDisableAllowChange).
• Ours (pre-fix): textured polys fetched texels from their own tpage but blended with the stale E1-set global semi_transparency, and never updated texpage_x/y/colors for subsequent rects.
• Effect: additive glows (mode 1 in the prim word) blended with whatever mode the last E1 set — Ape Escape's headlamp halos / siren flares / firework bursts rendered as dark blobs or black starbursts, intermittently (depends on OT bucket order, hence camera/distance). Proven on Ape attract frame 60052: nine op-0x2E quads at the artifact coords carried prim mode 1 vs E1 mode 0. Fixed in gpu.c set_tpage_from_poly(), called by all four textured poly handlers; all backends inherit via gr_set_semi_transparency.

Items that are FAITHFUL (no action)

• Semi-transparency 4-mode selection + STP-bit gating (SW and GL).
• Mask set/check including in copies (SW and GL).
• Texture window AND/OR formula; CLUT 4/8/15-bpp addressing; texel-0 transparency.
• Color modulation ×2-around-0x80 rule.
• GP0/GP1 command coverage and word counts match the oracle table.
• GL VRAM readback is 15-bit exact.

---

3. Prioritized fix list (player-visible impact first)

P1 — Implement dithering (D1). Add the 4×4 signed matrix and the dtd-gated apply (Gouraud + modulated-textured + lines; not sprites/copies) to BOTH renderers. Plumb dither_enabled from gp0_exec_draw_mode into gr_set_* (it is already decoded; just unused). SW: add matrix[y&3][x&3] before the >>3 truncation in the gouraud/textured span writers. GL: add the matrix in the fragment shader before the 5-bit pack. Highest visual payoff; removes the largest systematic oracle diff.

P2 — Fix SW rasterizer fill convention (D2 + D5 + D3). Replace the float scanline rasterizer with the PSX fixed-point edge DDA: half-open X spans (x < x_bound), top-inclusive/bottom-exclusive Y, the MakePolyXFP -(1<<11) top-left bias, and the +0.5 attribute seed. This removes shared-edge double-draw (visible on semi-transparent quads/triangles), the +1px right/bottom over-fill, and brings interior sampling in line with the oracle. This is the core "faithful rasterizer" item — biggest correctness win after dithering. (GL coverage stays ±1px by nature of the HW rasterizer; accept as documented, or move to a compute/SW-on-GPU rasterizer later.)

P3 — Sprite flip + exact sprite stepping (D6). Honor GP0(E1) FlipX/FlipY (u_inc=±1, the u|=1 FlipX quirk, v_inc=±1) in the SW sprite/rect path and GL. Needed for correct 2D character facing in sprite-heavy titles.

P4 — Oversize-primitive rejection (D11). Add the |Δx|>=1024 || |Δy|>=512 drop in the SW (and GL) primitive entry points to match the oracle and avoid runaway VRAM writes.

P5 — GPUSTAT FIFO/ready bits + LCF pacing (D8, D9). Derive bits 25/26/28 and LCF/vblank from the cycle/FIFO model rather than constants/poll-count. Cross-listed with the timing axis (FAITHFUL_TIMING_PLAN.md); do as part of that front, not in isolation.

P6 — Cleanups (D7, D4-GL, D10). Mask mono-rect size to 0x3FF/0x1FF (D7). Do GL mode-0/3 halving at 5-bit to drop the sub-LSB blend error (D4). Decide D10 (5→8 expansion): either match the oracle's <<3 scanout for diffability or keep replication as an explicit present-time option.

---

4. Validation method

Two independent processes share the JSON debug protocol (CLAUDE.md §16): psx-runtime (native, TCP 4500 on this wt/tomba2 worktree per build-t2; 4370 on master) and psx-beetle (oracle, TCP 4382/4380). Validate per the ring-buffer-first rule — query always-on state, never arm-then-capture.

1. VRAM byte-diff (primary). Drive both processes to the same scene (same input script, same frame count). Pull VRAM from each via vram_transfer_out / emu_read_ram (or glb_vram_diff / gl_renderer_fbo_peek on the GL side) and byte-compare the 1024×512×2 region. A faithful renderer is byte-identical to the Beetle SW oracle in the drawn region (mask bit included). Expect D1 (dither) and D2 (edges) to dominate the initial diff map; success = those regions collapse to zero after P1/P2. Diff per-primitive by single-stepping the GP0 stream if a whole-frame diff is too noisy.

2. Targeted GPU test ROMs. Run hardware GPU conformance ROMs on both:

   • Dithering on/off gradient tests (validates D1 matrix values + dtd gate).
   • Triangle/quad edge & fill-rule tests (validates D2 half-open + top-left).
   • Semi-transparency 4-mode swatches over a known backdrop (validates blend math, especially mode-0 floor and mode-2 clamp).
   • Mask-bit set/check tests (draw, set mask, overdraw, verify rejection).
   • Texture-window wrap + CLUT 4/8/15-bpp sampling grids.
   • Sprite FlipX/FlipY tests (validates D6). Byte-diff the resulting VRAM against Beetle for each ROM.

3. Per-primitive oracle agreement harness. Extend the existing GP0 capture (shaded-quad capture already exists, gpu.c:1632) into a general "replay one GP0 command into a scratch VRAM region on both backends and diff" tool, so each rule (edge, dither, blend, mask, flip) is pinned by a minimal regression case rather than a whole-scene screenshot. Per Rule 15, fix the tool if a diff can't be localized — do not infer correctness from two renderers agreeing.

4. Regression breadth. After each fix, re-run the diff harness across Tomba, Tomba2, MMX6 (and the BIOS shell) since the renderer is shared framework code; a faithful-rasterizer change must be validated on every title, not just the one under test.