D3DIM GPU present

How a DX5-7 frame drawn on the GPU reaches the screen without first being read back into the guest's DirectDraw DIB.

Since GPU stream v2 slice D2 the D3DIM GPU path is the WAT producer src/09abg-d3dim-gps.wat. It writes the shared v2 ring (docs/gpu-stream-v2.md), which an executor drains: WebGL in a browser, lib/gpu-stream-software.js headless. The old JS WebGL executor lib/d3dim-gpu.js (D3DIMGpu, its DXP3 record kind 4 in d3d-command-stream.js, PARKED_LIMIT, _materialize, _gammaRamp) was deleted in D2c. Since D4 (retire/d3dim-20261117) the producer is the only D3DIM path: the WAT software rasterizer's draw entries, the d3dim_gpu_enable/set_d3dim_gpu_present switches and the render Worker's D3DIM replay are gone. The executor is WebGL, software or null. lib/d3dim-render-worker.js remains only to replay software OpenGL.

Why

UT348 on D3DDrv, windowed, Threads mode, ran at 13-16 fps against 31 on its OpenGL renderer. Its present is Blt(primary <- back), not Flip, and each one was a full synchronous readback:

None of those pixels was ever read by the guest. They existed only to be shown.

Pixel ownership

The DIB stays the truth for every surface except two:

A parked frame is the GPU-resident result of a Blt(primary <- render target) that was shown from the GPU. While it is parked, the primary's DIB is stale. It holds whatever was there before, and the park slots hold the pixels the guest asked for.

The producer block ($D3DIM_GPS +8) records:

Present

Eligibility. $d3dim_gpu_try_present (src/09ab) runs at the top of the Blt handler, before any fence. It answers 1 only when all of these hold:

What it does. It writes a 48-byte DXP3 descriptor (dst, src, dst rect, src x/y, hwnd, CPU-present sequence, exclusive) and calls 0x2000A through $d3dim_gpu_call. That call goes only to the producer ($d3g_blt_present), never to the host. The producer:

  1. copies the rect into its park slot's RT;
  2. emits PRESENT with that RT, the client-relative dst_x/dst_y, the gamma LUT id and the CPU-present stamp;
  3. kicks the ring asynchronously.

On success the Blt returns DD_OK with no CPU copy, no dx_present and no fence. A Flip on the GPU (0x20003) swaps the chain's DIBs, lets the colour targets follow them, and PRESENTs the new front, again with no readback.

Page. The executor's PRESENT goes to the page's Presenter as a kind:'gpu', api:'d3dim' frame layer: the same _dxFrameLayer slot that DirectDraw and OpenGL use, so the single back-canvas rule (docs/js-libraries.md) holds.

Staleness. Every $dx_present bumps a CPU-present sequence ($D3DIM_LAZY_SHARED +24), and PRESENT carries it as its stamp. A GPU frame whose stamp is older is dropped, so a later DIB present always wins over a GPU frame, whichever order they arrive in.

_presentBestDxOffscreen (the "guess which surface is the screen" fallback) does nothing while a frame is parked, because the primary's DIB is stale then.

Gamma

$d3g_gamma uploads the process gamma ramp as a 256x1 lookup texture once per gamma generation. An identity ramp, or none, gives LUT id 0: a plain copy. The parked pixels are never gamma-corrected, so a CPU reader gets the pixels the guest drew.

Readback triggers (materialization)

A parked frame lands in its DIB ($d3g_materialize: one READBACK per parked rect, oldest first) only when a CPU reader of the primary's bytes asks. Every readback is charged to a site (d3dim_gps_stat 16 + site, printed by test/run.js --d3dim-gpu as [d3dim-gps] readback sites):

The next Blt(primary <- back) re-parks the frame without materializing, because the destination is overwritten. A global fence (length 0) does not materialize.

A draw or clear the producer cannot lower traps ($d3g_decline, fail-fast): there is no software rasterizer left to fall back to. The reason is counted first (d3dim_gps_stat 35 + reason, printed as [d3dim-gps] decline reasons) and logged as 0x44334744 + reason. A malformed primitive (bad type, vertex type or count) is a counted no-op (stat 14), as before:

Reason Index
texture not uploadable 1
Z function out of range 2
blend factor out of range 3
no depth surface 4
clear target not creatable 5
clear background without texture words 6

Stage-0 operands follow the software rasterizer's rule ($d3dim_stage_operation): ARG1 is diffuse for DIFFUSE/CURRENT and the texture otherwise, and ARG2 is the texture only for TEXTURE. So TFACTOR, SPECULAR or a modified selector reads the same operand on either path and no longer declines (index 0 is unused since D2c).

Switches

Switch Effect
(none, CLI) The WAT producer always. Executor: WebGL with --headless-gl, else the software executor. --d3dim-renderer=webgl|software|null picks one. --d3dim-gpu is accepted and does nothing.
?d3d-renderer=software (page) The same producer on the software executor instead of WebGL. ?d3dim-gpu=0 and ?no-d3dim-gpu-present are gone; frames always present from the executor.
?no-lazy-sync (page) Turns off lazy Lock: a Lock of a GPU-owned surface reads back eagerly instead of arming the range.

Cooperative threads (d3dim_gpu_cooperative_enable) are not eligible for the Blt present.

Known risks