GPU stream v2: migration plan for D3DIM, D3D9/D3D8 and OpenGL

Companion to gpu-stream-v2.md. Glide is done (e412a3780, b54590f1b). The goal is one common path for every graphics API:

WAT lowering → v2 ring → render Worker (webgl | software | null | later webgpu / C)
→ PRESENT with no CPU readback

Pixels come back to the CPU only through READBACK, and only when the guest touches them in 2D.

File:line references are from the 2026-11-14 planning pass. Re-check them before relying on them.

Order: D3DIM, then D3D9 together with D3D8, then GL.

D3DIM goes first for three reasons:

D3D9 drives about 80% of the executor growth (vertex shader stage, buffers, LAYOUT, CUBE, stencil, queries, render target used as a texture). It should land on a contract that D3DIM has already settled.

0. Core executor contract (cross-API)

The design goal is a minimal surface, so backends are easy to replace.

Interface. open(ring), execute(record), a present sink, close, and stats. A consumer-written capability block in the ring header holds fields such as max texture size, VS-IR yes/no, sampler count, stencil, and depth formats. WAT derives the caps the guest sees from this block. It replaces API-specific cap opcodes such as D3D9 0x30005, 0x30017 and 0x3000a.

Ops. Keep the current 20 ops and add none. Grow fields instead:

Formats. The core set is A8B8G8R8 (texture and render target), D16 and D24S8. WAT converts everything else at UPLOAD and READBACK. That covers P8, L8, A8L8, L16, 565, 555, 1555, 4444, R8G8B8 and DXT1/3/5, and it includes Glide's RGB565 readback.

IR. There is one IR (09af ABI 1) for both stages, but the executor only sees a core subset:

Group In the core subset
Arithmetic mov add mul mad dp3 dp4 rcp rsq min max slt sge exp log lit dst lrp frc cmp abs nrm pow
Texture texld for 2D and cube, with projected, bias and lod forms; texkill
Other oDepth; a0-relative constant addressing
Inputs fragment position (for GL stipple and logic op)

WAT lowers everything else to the core subset before it reaches the executor:

Without this, every new backend would have to reimplement the 846 lines of d3d9-shader.js.

Glide-specific code to generalize in the executors:

Today Change
Fixed 64-byte layout (gpu-stream-webgl.js:17, gpu-stream-software.js:268) Real LAYOUT
blend !== 1 is refused (software.js:355) Accept it
_glideFragment; the Voodoo 12.4 W depth encoding gps_wdepth depth_mode 2 = depth from interpolated 1/rhw (W-buffering, for Glide and D3DIM). The exact Voodoo encoding only matters for LFB depth reads
Fog table, 64 entries indexed by log-w Kept. WAT bakes D3D and GL table fog into it
D3D9 and GL per-vertex and per-pixel fog Goes into the IR, not into RASTER
Glide half-pixel offset Becomes a vertex adjustment in WAT
VIEWPORT is unimplemented Implement it

1. D3DIM (DX2–7)

Lowering map. d3dim-gpu.js (1658 lines) moves to WAT:

Today (JS) v2
_target, _prepare, _upload: one render target per DIB, re-uploaded when the page watch sees CPU writes CREATE RT/DS at SetRenderTarget and CreateDevice. WAT keeps a gpu_id and an owner {DIB, GPU, both} per DxObject. A CPU write (page_watch, dx_surf_note_write) becomes an UPLOAD of the dirty rect
_draw: TL batch → d3d9-backend fixed function DRAW_UP with vs=0. WAT repacks the TL vertex into a LAYOUT, replicates flat-shade and provoking colour, and places the fog factor
Stage-0 colorop and alphaop Pixel-shader IR from the 09aj cascade (d3d_fixed_compile_cascade5)
Alpha test, blend, Z/W, cull, scissor RASTER
Colour key Alpha 0 at decode, texkill in the IR
_texture via d3dim_gpu_decode_texture UPLOAD as A8B8G8R8 once. Invalidate on surface write-seq, SetPalette, SetEntries or SetColorKey
_clear, d3dim_gpu_try_clear CLEAR with a rect
_flip (PBO readback, then DIB swap) WAT rotates gpu_id along with the DIB pointers (09a8:6743), marks the front buffer GPU-owned and emits PRESENT. No readback
present / parked frames (DXP3, 4686233ac) PRESENT with dst x/y. Parking becomes the general GPU-owned state, so PARKED_LIMIT and _materialize go away
_gammaRamp WAT uploads a 256x1 lookup table on each gamma generation

Readbacks:

Site Today v2
Flip with a Worker in flight (09a8:6728, $d3dim_worker_try_flip) Async full-frame readback on every Flip (TR2, dx_boids) Gone
Flip, synchronous (09a8:6738, then dx_present) Sync readback on every Flip Gone
Global $d3dim_worker_fence (reads every dirty render target) Readback per call. Callers: BltFast, GetDC, ReleaseDC, SetColorKey, SetPalette, palette SetEntries and Release, non-GPU viewport Clear, SetRenderTarget, surface release Only GetDC and BltFast of a GPU-owned surface need one. ReleaseDC becomes an UPLOAD. The palette, colour key and clear callers become cache invalidation or a CLEAR
Blt source or destination (d3dim_surface_fence), Lock (d3dim_lock_fence, lazy Lock) Ranged readback READBACK plus SYNC, only when the surface is GPU-owned and its DIB is stale
Blt(primary ← RT) present Already on the GPU (4686233ac); CLI and cooperative mode decline it PRESENT everywhere, including the CLI
Software-fallback draw Readback, then re-upload Counted slow path until D5

Slices:

Risks:

2. D3D9 and D3D8 (09ac shares the device and resource records)

Readbacks:

Risks:

3. OpenGL

WAT already has:

The v2 lowering reuses the 09a8g pipeline:

Slices:

Readbacks:

Site Under v2
glReadPixels Kept, as READBACK
CopyTex* (read back, then upload) COPY; the readback is unnecessary
glAccum Kept. WAT owns an accumulation buffer in guest memory
Publishing every present to a bitmap or single-buffer drawable READBACK only when GDI or the guest touches the drawable
GDI merged over the window READBACK, deferred until GDI actually draws
Software GL writing the DIB on every frame Gone: the software executor presents

Risks:

Cross-cutting