D3DIM keyed mip filtering repair — 2026-11-05
This advances D3D-LEGACY-TEXTURE-CAPS-AUDIT-20261013 for explicit DX7
COLORKEYENABLE=TRUE, COLORKEYBLENDENABLE=TRUE. Each matching texel becomes
zero RGBA before within-level point/bilinear sampling and between-level
interpolation. Application alpha-test, alpha-source and blend states then
operate normally. The renderer retains gradient-selected mip levels, its
unkeyed behavior and advertised capabilities.
Primary contract and boundary
The Microsoft DirectX 7 SDK D3DRENDERSTATETYPE reference
specifies that explicit D3DRENDERSTATE_COLORKEYBLENDENABLE TRUE makes matching
texture samples have zero alpha and zero color; the application supplies
alpha test/blend settings. The SDK Color Keying State
gives COLORKEYENABLE FALSE as its initial setting and requires the texture's
source key. It does not establish state 144's initial value or a FALSE-mode
filtered membership equation.
Doug Rogers' NVIDIA Color Key in Direct3D, pages 1–4 places key-to-alpha conversion before bilinear/trilinear filtering in its reproduced DDK pipeline. That older pipeline retains RGB; the explicit DX7 state above specifies zero RGB too. The paper's later DX6/TNT discussion does not establish universal DX7 implicit alpha testing, palette-alpha precedence, or FALSE/default filtering output. Capability definitions alone do not specify those pixels. Microsoft SetColorKey sets the key on a surface; this fixture explicitly sets each mip image's key.
Retrieved primary document hashes in run 20261105-d3dim-keyed-mip:
| File | SHA-256 |
|---|---|
| dx7-renderstates.html | 7bcb2f8393d9615e54150ac6c0fe2b79a5a849614a36de1eba3be51e08c97ff0 |
| dx7-colorkey.html | aecde726caa3027bbc66fed838a3d07d5e4008c65803d943f66e46b9b64efdbb |
| ColorKey.pdf | e6e1e2fdfbc3c90f7961ebca0e4cb828c64845c7c6c11e5794fd68acba75aded |
FALSE/untouched state 144 keyed mip draws retain the named
D3DIM:keyed mip filtering failure. Effective key plus DDPCAPS_ALPHA remains
explicitly unsupported. Encountering an unkeyed mip child from a keyed root
also fails explicitly; this repair does not invent inheritance. No native
Windows comparison establishes these remaining combinations.
Implementation
src/09ab-handlers-d3dim-core.wat now calls the existing keyed-tap sampler for
each selected mip image using that image's dimensions, pitch, format, palette
and native key. It removes a level-zero resample that would otherwise overwrite
the mip result. Existing LOD/derivative/interpolation calculations stay intact.
The GPU mip metadata seam additionally exposes each child's has-key flag;
lib/d3dim-gpu.js uploads the existing zero-RGBA decoded images throughout the
chain when explicit key blending is enabled. FALSE/default still falls back
to the native named failure, and unresolved alpha palettes remain rejected.
Public guest regression and results
test/test-d3dim-keyed-mip-public-web.js reuses the public guest x86 COM fixture.
It obtains the real DirectDraw7, Surface7 and Device7 interfaces and CALLs their
published vtables. CreateSurface/GetAttachedSurface build a five-image 16→1
chain; public Lock/Unlock fill X8R8G8B8 images; SetColorKey is called on every
image. Public state setters/getters, Clear, BeginScene, DrawPrimitive, EndScene
and Lock exercise production code. There are no extra Wasm test exports,
constructed surface records, fixed LODs or replacement samplers.
Twenty-one states cover transparent/opaque texels, distinct mip 1/2/3 and last-level clamping, MIN point/linear, MAG linear, MIP NONE/POINT/LINEAR, bilinear/trilinear mixed key coverage, application GREATER-zero and EQUAL-255 alpha tests, source-alpha blending, explicit diffuse alpha override, key disable/restore and unkeyed controls. Four held old/next state pairs add eight Worker observations, including key-state and alpha-test/blend transitions. The independent oracle converts keys before filtering. RGB tolerance is two byte values; direct WebGL also checks alpha. It accounts explicitly for the existing fixed-function shader's 1/16-pixel sampling bias versus software's integer centers; no bias was introduced by this repair. X in the DIB is not asserted as alpha.
The exact final fixture reproduces ten old failures on baseline modules from
d2d4cfa9940d3dde7a62fd3ecc3a32eb8c7913d1 (which includes the input baseline).
Software/direct WebGL fail inside public DrawPrimitive; queued Worker draws
return S_OK, capture a real production draw/state batch, then fail on the public
Lock fence with the Wasm unreachable retained in Worker logs. This distinction
is asserted rather than treating the queue as synchronous.
Both repaired shipped modules pass 242 observations: two software routes
with 21 each, four direct WebGL 1/2 routes with 21 each, and four real queued
RenderWorker WebGL 1/2 routes with 29 each. Each Worker reports 29 GPU draws,
29 readback fences, zero errors/fallbacks and zero native/fallback software
draws. Direct WebGL uses actual readPixels; Worker pixels arrive through the
production fence. Browser reports ANGLE Intel/Mesa UHD 620; launch requested
SwiftShader, so the renderer report is retained without claiming physical GPU
qualification or a Windows hardware comparison.
| Shipped module | Repaired SHA-256 |
|---|---|
| wine-assembly.wasm (2,171,424 bytes) | b1e7fad7a43aae382b9cd3aff51df383b782e5e8a1d285aef1fb847864dc326a |
| wine-assembly.compat.wasm (2,174,070 bytes) | 5ae40c5b05bc9b71423c2c2293804db3b6c7896fec8ea4bcf725103c0c157014 |
old-fail-final/result.json, new-pass-final/result.json and
unsupported-false/result.json retain fixture/module hashes, COM calls,
render observations and Worker statistics. FALSE still fails on all ten
repaired routes. Native-size 32×32 DIB captures are saved for every passing
observation. The worker personally inspected native-size-contact.png: eight
selected states across all ten routes, with unchanged 32×32 tiles and a JSON
mapping. Key black versus clear, selected child colors, mixed filtered coverage
and alpha rejection/blending are visible. These are generated fixtures; no
original game or native Windows run was performed. Multi-format keyed mips,
perspective keyed coverage and missing-key/alpha-palette negative matrices are
not new public-COM coverage here; existing unkeyed/native format tests remain.
Validation commands (from repository root):
flock /tmp/wine-build.lock bash tools/build.sh
node test/test-d3dim-keyed-mip-public-web.js --plan
KEYED_MIP_EVIDENCE=ABSOLUTE_RUN_DIR node test/test-d3dim-keyed-mip-public-web.js
KEYED_MIP_EVIDENCE=ABSOLUTE_RUN_DIR node test/test-d3dim-keyed-mip-public-web.js --unsupported-false
node test/test-d3dim-native-mip.js
node test/test-directdraw-mip-chain.js
node test/test-d3dim-indexed-texture.js
node test/test-gl-software-raster.js
The full build and listed focused regressions pass; native mip suite retains
38 production-path unkeyed observations and its FALSE trap check. To reproduce
the old failure, use --old-fail with KEYED_MIP_MODULE_DIR pointing at the
retained baseline modules. Browser runs used the local runtime/browser locks.
Evidence and remaining work
Evidence is ignored under scratch/runs/20261105-d3dim-keyed-mip/: source SHA,
relevant binary diff and new-file patches, unique baseline modules, primary
documents, logs, captures and JSON. No source-tree snapshot or game-media copy
was made. Intermediate new-pass01 read old modules before build completion;
new-pass02 exposed a fixture software-version guard, and new-pass03 exposed
the pre-existing GPU sampling bias. These are retained as failed preparation
attempts; final old/new runs use identical fixture hashes.
The next semantic blocker for a broader repair is primary/native evidence for FALSE/untouched state 144 filtered key membership, palette alpha precedence and key inheritance. This commit completes the explicit-TRUE repair and leaves those unsupported combinations visible.