[gascarcella]

For dw2003recomp issue #78 (the widescreen field). The game's PR moves its pin here.

Why

The first game's field draws streamed 128x128 map tiles from 12 VRAM slots, exactly what a 320-wide screen shows. A 16:9 picture needs 3 more slots, and the 1 MB VRAM has no room left (x 640-1023 is full). The game also needs to know how far past the screen's edges the wide canvas shows, so its 2D can draw that far.

What

• port_video_vram_extend() makes gpu.c's VRAM 1024x1024 in Psy-Q's 2 MB layout:
  • getTPage already puts y's bit 9 into the texture page's bit 11, and getClut puts it into the CLUT's bit 15. The game reaches rows 512-1023 with its own macros, with no new shim API.
  • Transfers, fills and copies wrap at the VRAM's height.
  • Only textures and CLUTs live there. The drawing area and the display stay in rows 0-511.
  • Without the call, everything is as before: the texel masks are no-ops for a page in rows 0-511, and the new bits are dropped as before.
• The hardware renderer:
  • Its VRAM copy (the mirror, which every texel comes from) has 1024 rows. The target keeps 512.
  • A transfer, fill or copy is drawn into the target only where it reaches the target's rows. A copy from or into the extra rows takes its destination from the VRAM.
  • The texture keys and the wide canvas's mirroring follow the VRAM's height.
• Save states: the extra rows are a block of their own (gpu_vram_ext), present only when extended.
• port_video_widescreen_pad() returns the canvas's columns past each side of the display, as of the last vsync: 53 at 16:9, 32 at 16:10, and 0 while the picture is 4:3.
• Docs: DECISIONS (new entry "More texture room: Psy-Q's 2 MB VRAM layout, textures only"), PORT "Rendering", RUNTIME, GAME_CONTRACT, psyq/README.md.
• Test: tests/psyq/psyq_test.c test_vram_extend. Before the extension, page y 512 and CLUT row 1012 read rows 0 and 500. After it, they read rows 512 and 1012, and a transfer there leaves rows 0-511 alone.

Gates

• tests/psyq_test.py (2341 checks, -O0 and -O2), tests/shim_test.py, tests/hello_test.py, tests/hello_test.py --menu --gpu, psyq/check.sh --compile: pass.
• Against dw2003recomp with the disc (RTX 4070 Ti SUPER), with its field widescreen changes:
  • tests/port/render_gpu.py passes. Its VRAM check compares the rasteriser's whole target with the software VRAM every 10 vsyncs; the battle and the new field widescreen checks pass too.
  • run.py, savestate.py, mods.py --only widescreen and settings.py pass.
  • scripts/build.sh --check matches.
  • A mid-field save state with the extension on resumes to the same GPU picture byte for byte.
  • The owner played the field widescreen and confirmed it works.
• Not run here: the Windows cross-build (CI runs it).

🤖 Generated with Claude Code