psxrecomp/docs/internal/GL_RENDERER_HANDOFF.md

OpenGL Renderer — Handoff

Branch: feat/gl-renderer (both psxrecomp and TombaRecomp). Last commits this session: 0631538..45cc5c3 (psxrecomp). Status: v2 architecture, opt-in, rendering cleanly on every screen tested. Software renderer is still the committed default; OpenGL is selected per-game via [video] renderer = "opengl". TombaRecomp game.toml has LOCAL (uncommitted) overrides (renderer = "opengl", texture_filtering = "bilinear", supersampling = 2) for testing — do NOT commit those; committed defaults are software / nearest.

Goal: a hardware (OpenGL) renderer as a selectable option alongside software, enabling higher internal-resolution scaling without the software renderer's per-pixel CPU cost. Make it default-with-software-fallback only after broad visual validation.

---

Architecture (v2 — "GPU-authoritative VRAM")

• Facade + vtable. gpu.c calls gr_* (gpu_render.h/.c); a GpuRenderBackend vtable dispatches to software (sw_*) or OpenGL (glb_*). gr_set_backend() picks at startup from the config.
• GL backend in runtime/src/gpu_gl_renderer.c (+ runtime/include/gpu_gl_renderer.h). The single authoritative VRAM is the hr FBO (s_hr_tex, RGBA8, 1024·S × 512·S, + depth24/stencil8); internal scale S comes from [video] supersampling (GL-side; the SW hi-res mirror is forced off under GL).
• Mask bit exact: FBO alpha carries bit15; the stencil buffer mirrors it (bit0). check_mask = stencil test EQUAL 0; writing 1 under check uses GL_INVERT. Textured prims/copies/uploads draw in two passes split by the texel STP bit so each pass writes one known stencil value.
• Coherency model (all state in gpu_gl_renderer.c):
  • s_up_pending: CPU→VRAM writes land in the CPU array immediately and accumulate a pending rect; flush_cpu_upload() quad-blits the rect into the hr FBO (and subimages the raw mirror directly) before the next GPU op, present, or readback.
  • s_pack_dirty: hr-FBO content not yet re-encoded into the native R16UI raw mirror (s_raw_tex) — the texture-sampling source and readback surface. pack_flush() runs a scissored PACK pass over the union before any textured draw that samples a dirty page/CLUT.
  • s_gpu_dirty: CPU array stale; ensure_cpu() = flush + pack + full readback. Used by GPUREAD, A0 mask-check reads, vram peek, screenshots, 24-bit present.
• Texture sampling (Beetle-PSX model, structure studied from beetle-psx-libretro rsx/):
  • Per-primitive uv sampling bounds (u_limits), clamped in the fragment shader when no texture window is active. Filtered neighbours and S>1 interpolation overshoot can never read outside the prim's own texture rect. Rect prims pass exact bounds ([u0, u1-1] forward); triangles compute min/max with the exclusive max edge backed off for axis-aligned (2D) uv mappings; uv ranges crossing a 256 wrap boundary widen to the full page.
  • Bilinear (texture_filtering = "bilinear"): nearest texel is the base (cutout + STP authority), neighbours toward the sub-texel offset, per-texel opacity weights with renormalised colour, discard iff opacity < 0.5. The SW renderer's bilinear uses the same formulation (GL/SW parity); SW nearest is untouched.
  • Sample-grid alignment: all draw shaders shift positions by u_shift = 0.5/S − 1/64 so GL's center-sample grid matches the PS1 integer DDA (fixes striped/squished fonts). Beetle instead uses a +0.001 uv epsilon and truncation — coarser; we keep u_shift.
• GPU ops: fills (scissored clear, wrap-split 4 ways), copy_rect (hr→scratch blit + masked quad back), all triangle/rect/line prims, batched CPU→VRAM uploads. Blending via glBlendFuncSeparate — alpha (mask bit) is never blended.
• Present: one deterministic path per depth. 15-bit always blits the display rect from the hr FBO (4:3 letterboxed); 24-bit FMV syncs and presents the CPU conversion (letterboxed). The old per-frame FBO-vs-CPU alternation (menu jitter) is structurally gone.
• Init is all-or-nothing: any shader/FBO failure → clean fallback to pure software.

Verified (2026-06-12 session)

• BIOS → intro FMV (24-bit) → title → memcard slot screen → save-block list all render clean under GL at S=1 and S=2 with bilinear on:
  • Title vertical line at VRAM x=640 — GONE.
  • Memory-card screens' cross seams (tile edges at 704/864/256/368) — GONE.
  • Menu text fully readable under bilinear.
• Root cause of all the black lines: the v1 bilinear base texel was floor(uv − 0.5) — one texel OUTSIDE the prim on top/left edges. With u0=v0=0 tiles (card wallpaper, title bg page seam) the neighbour wrapped to empty VRAM → texel 0 → whole edge column/row discarded. They were never coherency holes; both the FBO and (post-sync) CPU VRAM agreed.
• gl_vram_diff at a quiesced (static-screen) moment: 0 mismatches.
• Audio fade (below) built and boots clean; user feel-test still pending.

Diagnostics (debug TCP 4470, dev builds)

• gl_fbo_peek x= y= w= h= — read GPU-side VRAM rect (via pack) without writing CPU VRAM; returns pending/pack rects + gpu_dirty.
• gl_vram_diff — full-VRAM FBO-vs-CPU mismatch count/bbox/samples. Forces a full pack first so it reads FBO truth even if the raw-mirror invariant broke. Run it BEFORE any screenshot — screenshots ensure_cpu (CPU := FBO) and make the diff trivially clean.
• gl_coh_ring n= [frame_min=] — always-on coherency event ring: flushes, fills, copy src/dst, draw bboxes, packs, readbacks, presents, probe perturbations, each with rect + frame. The event AFTER a "flush" names the op that triggered it. Keep n ≤ ~2000 per query (TCP send budget).
• Caveats: peeks/diffs themselves flush pending uploads mid-frame (they're recorded in the ring as peek/diff events). Animated screens legitimately diverge mid-frame (gpu_dirty=1); only quiesced screens give clean diffs.

Open / deferred

1. User visual validation of the whole pass (incl. fullscreen letterbox
   • audio fade feel) — everything above was screenshot-verified only.
2. Gameplay smoke under GL this build (last session verified gameplay renders; this session's shader changes were validated on title/menu screens which exercise the same textured paths).
3. Mirrored-texture mappings: bilinear/limits keep the full inclusive range for mirrored rects (no exclusive-edge backoff); ±1 texel at exact-integer uv remains the documented 1/64-bias tradeoff. Beetle handles mirrors with a +1 uv offset (off_u/off_v in gpu_polygon_sub.cpp) — adopt if a mirrored sprite ever shows it.
4. Dirty-sub-rect readbacks (ensure_cpu is a full 1 MB read), dither (SW lacks it too), GL_LINES vs Bresenham edge cases.
5. S=4 unvalidated (S=2 verified this session).

Audio fade (shipped with this branch, main.cpp)

turbo_loads mutes sequenced load BGM (tempo is frame-bound; can't decouple). sdl_audio_update() ramps gain over 40 ms at mute/unmute edges with an 8-frame unmute hangover to debounce burst gaps. The fade tail is sized to the ramp and clamped to sdl_audio_buf (the first version overflowed the 2048-frame buffer and corrupted adjacent statics — wedged the boot before display enable).

Useful commands / paths

• Build: PATH=/c/msys64/mingw64/bin:$PATH cmake --build build-stable --target psx-runtime (from TombaRecomp/; GL source is in psxrecomp/runtime/).
• Run: ./build-stable/psx-runtime.exe --game game.toml (BIOS path baked).
• Debug: python ../psxrecomp/tools/debug_client.py --port 4470 <cmd>; screenshot_file path=...png (CPU-side render after FBO sync — native res, shows FBO truth; the window shows the S× blit).
• Input injection: press buttons=N frames=M is consumed faster than some screens poll — prefer set_input buttons=0xNNNN, sleep ~1–2 s, then clear_input. Circle (0x2000) = confirm in Tomba menus; Start (0x0008) skips the intro FMV.
• A/B vs software: sed -i 's/renderer = "opengl"/renderer = "software"/' game.toml.
• Beetle PSX GL reference (GPL — structure only, never copy code): psxrecomp/beetle-psx/rsx/rsx_lib_gl.cpp, rsx/shaders_gl/*.glsl.h, mednafen/psx/gpu_polygon_sub.cpp (uv limits, may_be_2d, mirror offsets).
• GP0 ring decode: python TombaRecomp/_shots/decode_frame.py <frame>.
• Attract demo auto-plays on cold boot (AP 97400 = canned demo).