Graphics and Display

Graphics and Display

Graphics work is easiest to reason about when guest memory, display state, GE behavior, and host presentation remain separate.

Frame path

flowchart LR
    A["Guest writes<br/>VRAM / framebuffer"] --> B["Display state<br/>selects and latches"]
    B --> C["GE consumes<br/>commands + state"]
    C --> D["Render target<br/>software or Vulkan"]
    D --> E["Host viewport<br/>resizable window"]
    E --> F["Presentation filter<br/>NEAREST or LINEAR"]

Loading

Dimension	Current meaning
Guest framebuffer	Native PSP-visible 480x272 memory surface.
Internal render target	Backend-dependent scale used during rendering.
Host window	Current SDL path starts resizable at 960x544.
Presentation filter	NEAREST only for exact positive integer, uniform scaling; LINEAR otherwise.

The 960x544 start is 2x-style host presentation, not native PSP window sizing. A true selectable 480x272/1x host mode is not implemented.

Code map

Path	Role
src/rt/ge.c	Software GE comparison rasterizer.
src/rt/gpu_sdl3vk/	SDL3/Vulkan initialization, presentation, and GPU GE processing.
src/rt/recomp.h	Shared guest state and memory interfaces used by both paths.

SR_GPU_GE=1 selects the Vulkan GE path; SR_GPU_GE=0 selects the software comparison path. Agreement between these paths can localize a bug, but neither is an external PSP oracle.

Filtering and open defects

PR #71 selects NEAREST only for exact positive integer, uniform source-to-viewport scaling in both dimensions. Fractional, non-integer, non-uniform, or invalid extents use LINEAR.

State	Item
✅ Merged	Integer-uniform presentation filtering policy.
🔴 Open · #69	Transient main-menu model/render corruption remains reproducible; its root cause is not established.
🔴 Open	Mid-game portrait/profile images remain absent.

Diagnose in order

1. Did the guest write the intended memory span?
2. Did display state select the intended framebuffer?
3. Did GE consume the correct command and state sequence?
4. Did guest VRAM and host-visible data synchronize at the expected boundary?
5. Did the renderer present without another conversion or scaling error?

Warning

A screenshot is a symptom, not a diagnosis. Use source-owned capture/selftests and bounded visual routes where available; do not publish commercial screenshots or framebuffer dumps.

Research: Display and VBLANK · GE pipeline · VRAM coherency · GE list synchronization

Continue with Debugging and Verification and Testing.