retroDE_ps2/docs/decisions/0012-ch347-clut-psmt8-sprite.md

0012 — Ch347: CLUT (PSMT8) textured-alpha sprites

Status: planned (synthetic brick buildable now; authentic acceptance gated on a real capture) Date: 2026-06-23

Goal

Extend the Ch344/Ch345a textured-alpha SPRITE path from PSMCT32-only to PSMT8 indexed (CLUT) textures: TEX0.PSM=0x13 → fetch 8-bit index from VRAM → CLUT → ABGR texel → MODULATE → source-over alpha. This is the first "real game" GS feature beyond the homebrew corpus (which is anomalously all-PSMCT32); PS2 titles lean on palettized textures to fit VRAM, so a richer free corpus (Ch347 target: a ScummVM-freeware capture, Beneath a Steel Sky) forces CLUT. Scope is PSMT8 only — PSMT4 (nibble/RMW) deferred unless census forces it.

Key finding: the CLUT machinery is ~95% already built (search-before-reimplement)

The platform already has, and PROVES for textured TRI/SPRITE DECAL (Ch296/297/299/314):

• clut_stub.sv — 256×32 CLUT RAM, two combinational read ports; one is already dedicated to the texture sampler (tex_read_idx→tex_read_data).
• clut_loader_stub.sv — VRAM→CLUT load FSM, CLD-mode policy, PSMCT32/PSMCT16 unpack, load_busy guards read2.
• gs_texel_addr.sv PSMT8 path — 1 byte/texel linear byte address; gs_swizzle_psmt8_stub.sv for swizzle.
• gs_texture_unit.sv (Ch296) — byte-lane extract from the 32-bit word + CLUT lookup; output is .tex_color.
• gs_stub already decodes TEX0 CLUT fields (CBP/CPSM/CSM/CSA/CLD) and the textured-DECAL gate already admits PSM 0x13/0x14.

Critically: the Ch344 half-rate sprite datapath captures s1_tex_color, and s1_tex_color IS the gs_texture_unit output (gs_stub.sv:4352) — i.e. already CLUT-decoded for PSMT8. So the CLUT decode happens upstream of the half-rate capture.

What actually needs doing

1. Relax the textured-alpha SPRITE eligibility gate (new_tex_abe_active, gs_stub.sv ~:5114): (tex0_psm==6'h00) → (tex0_psm==6'h00 || tex0_psm==6'h13) (PSMT8). PSMT4 (0x14) left out for v1.
2. Validate the timing — the one real risk. PSMT8 adds a byte-lane SELECT; under TEX_RD_REGISTERED=1 (the board config) the selector is realigned (SEL_DELAY). The Ch344 half-rate capture (ta_tex_q/ta_tex_q1, the 1-deep texel delay) was tuned to PSMCT32's registered-read latency. We must prove the CLUT-decoded texel is still valid at the frozen-beat capture for PSMT8 — a COMBINATIONAL-read TB would be a FALSE GREEN (this exact trap bit Ch344). Use a registered-read TB.
3. CLUT precondition: a TEX0_1 write with CLD≠0 must fire (loading clut_stub) before the sprite draws — same precondition as the proven indexed-DECAL path; declared, asserted in the TB.

Pre-fit synthetic TB (buildable NOW — no capture needed), proving Codex's 5 points

tb_gs_psmt8_alpha_sprite (registered-read model, SPRITE_TEX_ALPHA=1, TEX_RD_REGISTERED=1):

1. index fetch hits the right byte (PSMT8 linear address → correct VRAM byte lane);
2. CLUT maps index → ABGR (program clut_stub via a CLD≠0 TEX0 / loader);
3. the texel's alpha (from the CLUT entry) drives source-over against the dest;
4. no read2 collision regression (texel read on primary beat, dest on frozen beat, CLUT lookup is combinational — assert no overlap, incl. vs load_busy);
5. the PSMCT32 sprite path stays green (cross-check the existing tb_gs_textured_alpha_sprite + regression).

Acceptance for the synthetic brick: TB passes + full regression + quartus_syn 0-err. This banks the hardware without claiming authentic content.

Synthetic ≠ authentic — two separate labels (Codex)

The datapath proof (tb_gs_psmt8_alpha_sprite) proves index→CLUT→ABGR→source-over works. It is NOT authentic CLUT ingestion. Authentic PSMT8 additionally requires the emitted TEX0's CLUT-side fields to select a CLUT that is actually loaded and resident:

• Screening (DONE, Ch346): gs_texture_residency.py now decodes CBP/CPSM/CSM/CSA/CLD and, for indexed-PSM (0x13/0x14) candidates, REQUIRES a resident CLUT upload at CBP before the draw (epoch-tracked, same as the texture) — else REJECT. It also flags CLD=0 (no load trigger -> possibly-stale palette). So residency_ok() won't green-light a PSMT8 candidate whose palette isn't resident.
• Emission (capture-step TODO): the feeder/translator must carry the CLUT-side TEX0 fields. Today ps2_feeder.c's tex0 TBP TBW TW TH TFX grammar packs ONLY texture-side fields — it needs CBP/CPSM/CSM/CSA/ CLD added (and the fixture must upload the palette to CBP + a CLD!=0 TEX0 so clut_loader_stub fires). Build this around the exact Ch346-selected candidate, not speculatively.

Board-fit guardrail (Codex guardrail 1) — RESOLVED

The "missing HDMI IO_STANDARD" the synth smoke reported was a FALSE alarm: the assignments are present + correct in the QSF (with an -entity qualifier); the scaffold check's regexes were EOL-anchored and didn't tolerate the qualifier. Fixed 3 checks in sim/Makefile (VIRTUAL_PIN + HDMI/ADV7513 IO_STANDARD). The QSF carries the full 77-source list (incl. osd/qsys platform modules under USE_QSYS_TOP) so the owner's board fit is unaffected. NOTE: quartus_syn_only itself is a reduced smoke (files.f, 115 entries) that OMITS the platform modules, so it can't fully elaborate the de25 top — a pre-existing smoke-scope limitation, not a board-fit blocker. Quartus analyzed the Ch347 gs_stub change clean (the 7 elaboration errors are all unrelated platform entities).

Authentic acceptance (gated on the capture — do NOT commit the target until it exists)

1. Capture a Beneath a Steel Sky (ScummVM-freeware) GS dump.
2. gs_texture_residency.py (Ch346) picks a RESIDENT, plausible PSMT8 candidate WITH a resident CLUT — prefer a no-wrap footprint so we don't repeat the Ch345b wrap-mode ambiguity.
3. Extend ps2_feeder.c/translator with CLUT-side TEX0 fields + palette upload; emit the scene; software reference pixel-diffs; then board fit (after confirming the board profile's clut_load_busy wiring).

Provenance: all dump-derived content stays LOCAL/gitignored, same discipline as the cube/sprite fixtures.