psxrecomp/docs/PERFORMANCE_CAMPAIGN.md

OpenGL performance campaign

Tracking: central Beads beads-jod2, beneath beads-eio.3 (psxrecomp framework). Branch: perf/opengl-burndown-20260904. Starting revision: bf61b1054313e1c80d5c2bf1b14a1e50f2e54b8a. This is the audited integration revision, not a claim about a shipped release.

Objective and constraints

Improve sustained guest speed, frame consistency, and resource use at identical settings and correctness. OpenGL is the primary renderer. Vulkan completeness is a separate qualification exercise, never a substitute for an OpenGL fix. Use GPT-5.5 agents for bounded implementation and independent adversarial review of their code, measurements, and acceptance claims.

The primary route is Ape Escape, Crabby Beach, approaching and facing the water. Inspect existing ApeEscapeRecomp/saves/scph1001 states before choosing one; preserve originals and record BIOS, state hash, scene, and input sequence. Add quiet gameplay, facing away, and a transition, plus Tomba 2 and Mega Man X6 regression routes. Compare guest speed, game-produced frames, and host presents separately to avoid treating original-game slowdown as host overload.

Test unrestricted, 50%, and 25% host CPU budgets, with affinity recorded as a separate variable. Never change guest clocks to simulate hardware. CPU throttling does not emulate older caches, memory bandwidth, or integrated graphics. Real acceptance targets are an older 2-core/4-thread integrated-graphics PC and a Deck-class handheld, with desktop and supported-platform regression coverage.

Work packages

This table defines the approved work, not its live issue status. Beads owns status and dependencies; experiment results belong in the evidence ledger.

ID	Work and candidate experiments	Required evidence
P0-1	Repeatable route runner, artifact/config identity, machine-readable A/B reports	Same guest work, reproducible baseline, measured noise
P0-2	Release flags, effective settings, overlay inventory, cache rejection and compiler failures	Clean-install Windows/Linux behavior without development caches
P1-1	Unused audio/GPU histories, memory observers, tracing/logging, diagnostic allocations	Measured saved work; retain functional observers and cheap health counters
P1-2	GL batch breaks, texture/CLUT dependencies, packing, readbacks, uploads, buffer streaming	Identical order, masks, blending, texture feedback, VRAM and enhanced output
P1-3	Swap blocking, pacer ownership, spinning, refresh/focus, interpolation and audio delivery	No speed drift, latency regression or new underruns
P1-4	Overlay discovery, validation, loading, fallback, compilation contention and cache growth	Correct identity across replacement, self-modification, restore and cold installs
P2-1	Generated code, dispatch, continuations, state traffic, interpreter, lookup/linking	Exceptions, delay slots, resumes and invalidation across all execution tiers
P2-2	RAM/MMIO, aliases, observers, cycle publication, deadlines and idle detection	Exact cycle charges, side effects and event ordering
P2-3	GTE/PGXP state copies, inactive hooks and shadow validation	Exact GTE state and unchanged enabled enhancements
P2-4	SPU/resampling, CD/XA, MDEC, DMA, disc/decompression/card I/O; SIMD/batching/prefetch	Audio, IRQs, backpressure, decode output and completion timing
P2-5	Allocation, bandwidth, locality, texture caches, mods/UI, rewind, netplay	Bounded memory, enabled-feature parity and inexpensive inactive paths
P2-6	PGO/LTO, compiler options, code layout, portable SIMD and build costs	Multi-title gains, arithmetic parity and portable release artifacts
P3-1	Threads, helper processes and GPU compute for attributed hotspots	End-to-end constrained-host gains including all transfer/sync costs
P3-2	Software renderer hotspots and separate Vulkan qualification	Explicit coverage gaps; OpenGL acceptance remains mandatory
P4-1	Release integration and recurring performance gates	Clean-install route, correctness and resource checks on shipped artifacts

Complete broad attribution before concentrating implementation on the largest cost. Every area receives a measured disposition, including already optimized, rejected, or deferred with a concrete missing prerequisite. Do not infer impact from source size, suggestive names, or another console's bottlenecks.

Measurement and acceptance

Follow HOST_OPTIMIZATION_CONTRACT.md. Use at least three interleaved A/B pairs with all raw results, minima, medians, discard reasons, a preregistered primary metric, and the 5% retention gate for added complexity. Use forced faithful/candidate selectors where practical.

Separate warm-cache throughput (fixed guest work; no compiler activity) from first-use and transition campaigns where compilation/loading is the subject. The latter must be explicitly labeled and must not be represented as satisfying the quiet-host warm-cache gate. Use 120-second paced windows for stutter. Record source and artifact hashes, generated code, BIOS, toolchain, effective settings, overlay contents, power state, pacing owner and instrumentation.

Attribute CPU samples and thread waits, GL scene/present time, readback/upload bytes, execution tiers, device work, audio underruns, memory, allocations, page faults and I/O. Expensive profiling is for attribution; final timing must also run without it. Missing or reset counters must never become zero-cost evidence.

Compare deterministic guest state at intermediate checkpoints, including cycles, deadlines, pending exceptions, device state, RAM/VRAM/SPU RAM and overlay identity. Add rendered-output/audio comparisons and candidate hit witnesses. Exercise invalidation, aliases, exceptions, DMA, save/load, rewind and netplay as affected. Do not claim parity from a fallback that silently avoids the candidate.

For offload, specify ownership, immutable inputs, publication deadlines, bounded queues, backpressure, cancellation and restore before coding. Compare inline against one worker first. No races on guest memory, altered device ordering, or implicit cross-thread GL context use. Count IPC, copying, driver contention, memory and synchronization in the gain, especially on low-core-count/iGPU hosts.

Initial evidence and completion

Source inspection found always-on audio PCM history and GP0 history, potential GL full-VRAM readback, and multiple VRAM copies. These are hypotheses, not measured causes of Crabby Beach slowdown. Widescreen overhang detection is functional; its census already has a gate. Vulkan already has a staging cache. Cycle batching, event deadlines, sparse probes, MDEC SIMD and GPU-direct GL presentation already exist and must not be proposed as new work without audit.

Append accepted, rejected and incomplete experiments to an evidence ledger with raw-data links. Keep issue status in central Beads and record landed commits. Do not close the campaign until every work package has a disposition and accepted improvements reach validated title releases. Target sustained real-time execution at preserved settings on the selected hardware, without new correctness, audio, or pacing failures. Record hardware limitations rather than hiding them.