@woosh/meep-engine 3.43.0 → 3.44.0

package/src/shade/playground/texture_encode/README.md

@@ -1,109 +1,129 @@
-# GPU block encoder
-
-A sampleable texture in, a block-compressed texture out, on the device — the runtime compression of
-the compressed-texture plan's §4.5, driven here on real hardware.
-
-This is tier 8 of the plan's testing ladder for the encoder, and the only tier with a GPU in it.
-Everything below runs device-free: the encoder chunk in the WGSL emulator against an exhaustive
-optimum, the whole kernel in the emulator against the chunk, the orchestration on the software
-device with its copies executing over host-written bytes. What none of that can answer is whether a
-real device takes the format and the padded rows, whether the texture ends up holding the blocks the
-shader wrote, and whether the hardware's own BC decoder agrees with the test decoder every number
-below is judged with.
-
-## Running it
-
-```bash
-npm run dev --workspace @woosh/meep-engine
-```
-
-Then open `/src/shade/playground/texture_encode/index.html`, pick a target and press **Encode**. The
-synthetic source is the three spec fixtures — smooth, rough, mask — in the red, green and blue
-channels at 512x512 with a CPU-built mip chain, so the numbers here can be held against the ones the
-specs pin. Any image file can be dropped in through the file input instead.
-
-The page does not use the renderer: the renderer's frame loop needs immediate data, which not every
-browser build offers, and the encoder needs no frame. A `GraphicsContext` and a command context over
-a bare device are enough to record the encode, and everything else is readback.
-
-## What it checks
-
-1. **The device accepts the work.** `createTexture` with the block format, one dispatch, one
-   `copyBufferToTexture` per level with rows padded to 256 bytes — inside a validation error scope,
-   so a refusal is a message rather than a black texture.
-2. **The texture holds the buffer.** Every level is copied back out with `copyTextureToBuffer` and
-   compared byte for byte with the block buffer the shader wrote.
-3. **The hardware decodes what the CPU decoder predicts.** Every level is read back through a
-   `textureLoad` pass — the GPU's own decoder — and compared texel for texel with the test
-   decoder. The specification writes BC4's interpolation in real arithmetic and leaves the
-   precision to the hardware, which the probe below found up to seven levels from the test decoder
-   on the widest six-value spans, so the verdict is the picture rather than a texel count: a level
-   whose hardware decode is decibels under the CPU decoder's reading of the same bytes, one
-   rounding forgiven, holds a wrong block. BC7 and BC6H decoders are bit-exact by specification and
-   matched on every sample.
-4. **The device against the emulator.** Level 0 is encoded a second time by the same chunk in the
-   WGSL emulator, in f64, and the blocks are compared. A block that differs is not wrong: the f32
-   arithmetic rounds a tie the other way, and the page says whether the device's choice decoded
-   better, worse or the same.
-
-And the numbers the specs already pin, on the same fixtures: PSNR and worst texel against the source,
-per level — once against the CPU decoder's reading of the blocks and once against the hardware's.
-
-The third panel is **FLIP** — the tree's own `sampler2d_flip_ldr`, the renderer's regression gate —
-of the hardware's picture against the source at level 0, drawn through the magma map: black where
-a viewer flipping between the two would see nothing, yellow where they certainly would. Its pooled
-mean and weighted median are in the report. It compares the displayed bytes, which for BC6H is the
-tone-mapped picture and for a signed format the mid-grey-centred one, because FLIP judges what is
-seen. It runs whatever the size: it is a CPU pass on the page's own thread, half a second at
-512x512 and twenty-two seconds at 2048x2048 here, the status says so while it runs, and the report
-line carries how long it took.
-
-The three panels share one view — the wheel zooms about the pointer, a drag pans, a double click
-refits — and one cursor: the open circle is the same texel on all three, and the line under the
-panels is what each holds there, in the format's own units, with the FLIP value beside them.
-
-**Probe hardware decoder** does the fourth check on its own, exhaustively: a 1024x1024 BC4 texture
-holding every pair of endpoints, read back at full precision, from which the interpolation weight at
-every index is fitted and the difference from the CPU decoder tabulated.
-
-## What it measured
-
-NVIDIA Lovelace through Dawn, 2026-09-02:
-
-| target | source | blocks | PSNR, CPU / hardware decode | wall, record to done | first run, with pipeline compile |
-|---|---|---|---|---|---|
-| `bc4-r-unorm` | 512x512, 10 levels | 21,847 | 53.15 / 52.59 dB | 5.3 ms | 212 ms |
-| `bc4-r-unorm` | 2048x2048, 12 levels | 349,527 | 53.23 / 52.66 dB | 8.6 ms (650 MP/s) | 21 ms |
-| `bc5-rg-unorm` | 512x512, 10 levels | 21,847 | 45.24 / 44.69 dB | 4.1 ms | 504 ms |
-| `bc1-rgba-unorm` | 512x512 correlated colour | 21,847 | 41.53 / 41.51 dB | 7.2 ms | 526 ms |
-| `bc1-rgba-unorm` | 512x512 unrelated channels | 21,847 | 31.55 / 31.53 dB | 4.3 ms | 316 ms |
-| `bc7-rgba-unorm` | 512x512 correlated colour, cut out | 21,847 | 46.04 / 46.04 dB | 3.6 ms | 257 ms |
-| `bc7-rgba-unorm` | 2048x2048 unrelated channels | 349,527 | 33.41 / 33.41 dB | 8.2 ms (682 MP/s) | 20 ms |
-| `bc5-rg-unorm` | 512x512 normal map | 21,847 | 37.40 / 37.01 dB | 4.3 ms | 397 ms |
-| `bc5-rg-snorm` | 512x512 normal map, signed bytes | 21,847 | 31.43 / 30.96 dB (peak 127) | 3.9 ms | 453 ms |
-| `bc6h-rgb-ufloat` | 512x512 HDR, fourteen stops and a sun | 21,847 | 47.05 / 47.05 dB (over half bits) | 3.6 ms | 364 ms |
-
-BC6H's hardware decode, like BC7's, matched the CPU decoder on every sample: the format requires a
-bit-accurate decoder.
-
-`astc-4x4-unorm` is on the list and refused by this device before a texture is created — it
-samples no ASTC format. An ASTC device is the first thing to point the page at.
-
-BC7's hardware decode matched the CPU decoder on every sample of every level: its interpolation is
-fully specified, where BC4's is left to the implementation.
-
-Validation clean. Every level's blocks read back from the texture byte-identical to the block
-buffer, the tails included. Against the source at 2048², level 0: 53.23 dB by the CPU decoder,
-52.66 dB as the hardware decodes it. The device and the f64 emulator chose the same block for 13,675
-of the 16,384 level-0 blocks of the 512² source; of the rest, 2,428 decode to the same error, 120
-better on the device, 161 worse.
-
-The hardware's BC4 decoder is `A + (B − A) · c / 257` over 16-bit endpoints, with c = 36, 72, 113,
-144, 185, 221 for the eight-value mode and 48, 96, 161, 209 for the six-value one. Rounded to eight
-bits it agrees with the CPU decoder on 62.6% of palette entries, is one level off on 22.9%, and up
-to seven off on 0.04% — the widest six-value spans.
-
-Two things this page found that no device-free tier had, both about the same rule: a copy of a
-compressed level is sized in whole blocks against the level's *physical* extent, so a 2x2 mip is
-copied as 4x4 and a 2x2 copy is refused. The encoder's copies were wrong that way for one run, and
-`texture_write_level` had been wrong that way for every BC chain's tail since it was written.
+# GPU block encoder
+
+A sampleable texture in, a block-compressed texture out, on the device — the runtime compression of
+the compressed-texture plan's §4.5, driven here on real hardware.
+
+This is tier 8 of the plan's testing ladder for the encoder, and the only tier with a GPU in it.
+Everything below runs device-free: the encoder chunk in the WGSL emulator against an exhaustive
+optimum, the whole kernel in the emulator against the chunk, the orchestration on the software
+device with its copies executing over host-written bytes. What none of that can answer is whether a
+real device takes the format and the padded rows, whether the texture ends up holding the blocks the
+shader wrote, and whether the hardware's own BC decoder agrees with the test decoder every number
+below is judged with.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+Then open `/src/shade/playground/texture_encode/index.html`, pick a target and press **Encode**. The
+synthetic source is the three spec fixtures — smooth, rough, mask — in the red, green and blue
+channels at 512x512 with a CPU-built mip chain, so the numbers here can be held against the ones the
+specs pin. Any image file can be dropped in through the file input instead.
+
+The page does not use the renderer: the renderer's frame loop needs immediate data, which not every
+browser build offers, and the encoder needs no frame. A `GraphicsContext` and a command context over
+a bare device are enough to record the encode, and everything else is readback.
+
+## What it checks
+
+1. **The device accepts the work.** `createTexture` with the block format, one dispatch, one
+   `copyBufferToTexture` per level with rows padded to 256 bytes — inside a validation error scope,
+   so a refusal is a message rather than a black texture.
+2. **The texture holds the buffer.** Every level is copied back out with `copyTextureToBuffer` and
+   compared byte for byte with the block buffer the shader wrote.
+3. **The hardware decodes what the CPU decoder predicts.** Every level is read back through a
+   `textureLoad` pass — the GPU's own decoder — and compared texel for texel with the test
+   decoder. The specification writes BC4's interpolation in real arithmetic and leaves the
+   precision to the hardware, which the probe below found up to seven levels from the test decoder
+   on the widest six-value spans, so the verdict is the picture rather than a texel count: a level
+   whose hardware decode is decibels under the CPU decoder's reading of the same bytes, one
+   rounding forgiven, holds a wrong block. BC7 and BC6H decoders are bit-exact by specification and
+   matched on every sample.
+4. **The device against the emulator.** Level 0 is encoded a second time by the same chunk in the
+   WGSL emulator, in f64, and the blocks are compared. A block that differs is not wrong: the f32
+   arithmetic rounds a tie the other way, and the page says whether the device's choice decoded
+   better, worse or the same.
+
+And the numbers the specs already pin, on the same fixtures: PSNR and worst texel against the source,
+per level — once against the CPU decoder's reading of the blocks and once against the hardware's.
+
+The third panel is **FLIP** — the tree's own `sampler2d_flip_ldr`, the renderer's regression gate —
+of the hardware's picture against the source at level 0, drawn through the magma map: black where
+a viewer flipping between the two would see nothing, yellow where they certainly would. Its pooled
+mean and weighted median are in the report. It compares the displayed bytes, which for BC6H is the
+tone-mapped picture and for a signed format the mid-grey-centred one, because FLIP judges what is
+seen. It runs whatever the size: it is a CPU pass on the page's own thread, half a second at
+512x512 and twenty-two seconds at 2048x2048 here, the status says so while it runs, and the report
+line carries how long it took.
+
+The three panels share one view — the wheel zooms about the pointer, a drag pans, a double click
+refits — and one cursor: the open circle is the same texel on all three, and the line under the
+panels is what each holds there, in the format's own units, with the FLIP value beside them.
+
+**Probe hardware decoder** does the fourth check on its own, exhaustively: a 1024x1024 BC4 texture
+holding every pair of endpoints, read back at full precision, from which the interpolation weight at
+every index is fitted and the difference from the CPU decoder tabulated.
+
+## What it measured
+
+NVIDIA Lovelace through Dawn, 2026-09-02:
+
+| target | source | blocks | PSNR, CPU / hardware decode | wall, record to done | first run, with pipeline compile |
+|---|---|---|---|---|---|
+| `bc4-r-unorm` | 512x512, 10 levels | 21,847 | 53.15 / 52.59 dB | 5.3 ms | 212 ms |
+| `bc4-r-unorm` | 2048x2048, 12 levels | 349,527 | 53.23 / 52.66 dB | 8.6 ms (650 MP/s) | 21 ms |
+| `bc5-rg-unorm` | 512x512, 10 levels | 21,847 | 45.24 / 44.69 dB | 4.1 ms | 504 ms |
+| `bc1-rgba-unorm` | 512x512 correlated colour | 21,847 | 41.52 / 41.50 dB | 5.2 ms | 360 ms |
+| `bc1-rgba-unorm` | 512x512 unrelated channels | 21,847 | 31.54 / 31.52 dB | 5.7 ms | 471 ms |
+| `bc7-rgba-unorm` | 512x512 correlated colour | 21,847 | 50.92 / 50.92 dB | 4.3 ms | 414 ms |
+| `bc7-rgba-unorm` | 2048x2048 unrelated channels | 349,527 | 40.13 / 40.13 dB | 6.8 ms (822 MP/s) | 682 ms |
+| `bc5-rg-unorm` | 512x512 normal map | 21,847 | 37.40 / 37.01 dB | 4.3 ms | 397 ms |
+| `bc5-rg-snorm` | 512x512 normal map, signed bytes | 21,847 | 31.43 / 30.96 dB (peak 127) | 3.9 ms | 453 ms |
+| `bc6h-rgb-ufloat` | 512x512 HDR, fourteen stops and a sun | 21,847 | 47.05 / 47.05 dB (over half bits) | 3.6 ms | 364 ms |
+
+The `bc1-rgba-unorm` and `bc7-rgba-unorm` rows are from 2026-10-10, each in a fresh browser
+profile, after the encoders' search was cut to fit (the plan's §9.20): PSNR moved by 0.01 dB for
+BC1 and by 0.01 to 0.08 dB for BC7, and the code before the cut gave the September figures to the
+hundredth the same day. The wall time does not show the cut. Record to done is mostly submission
+and readback at these sizes — the 2048x2048 BC7 encode read from 5.9 to 14.3 ms across that day's
+runs, before and after, and a 512x512 BC1 one from 3.2 to 6.5 — while by the plan's 4096²
+timings the cut saves about a millisecond of kernel on a 2048x2048 chain. BC7's first run is
+shorter, 293 to 308 ms before the cut and 210 to 238 after: a smaller shader to compile. The
+September 2048x2048 BC7 row's 20 ms first run is too short to hold a compile, so that pipeline had
+been built by an earlier run in the page; and its 512x512 row said "cut out" of a source that was
+the opaque correlated colour, the only one the page has.
+
+The `bc7-rgba-unorm` rows were measured again that evening, each in a fresh profile, once the
+encoder chose between mode 6 and the partitioned mode 1 by estimate (the plan's §9.20): 45.96 to
+50.92 dB on the correlated colour and 33.40 to 40.13 on the unrelated channels, the hardware decode
+equal to the CPU decoder's on every sample. The first run's compile is longer, 414 and 682 ms
+against 238 and 210: the shader is bigger. The device-against-emulator check was skipped on those
+runs, because a worktree's dev server does not serve the parser's wasm; the kernel's spec holds the
+shader to the chunk block for block in the emulator instead.
+
+BC6H's hardware decode, like BC7's, matched the CPU decoder on every sample: the format requires a
+bit-accurate decoder.
+
+`astc-4x4-unorm` is on the list and refused by this device before a texture is created — it
+samples no ASTC format. An ASTC device is the first thing to point the page at.
+
+BC7's hardware decode matched the CPU decoder on every sample of every level: its interpolation is
+fully specified, where BC4's is left to the implementation.
+
+Validation clean. Every level's blocks read back from the texture byte-identical to the block
+buffer, the tails included. Against the source at 2048², level 0: 53.23 dB by the CPU decoder,
+52.66 dB as the hardware decodes it. The device and the f64 emulator chose the same block for 13,675
+of the 16,384 level-0 blocks of the 512² source; of the rest, 2,428 decode to the same error, 120
+better on the device, 161 worse.
+
+The hardware's BC4 decoder is `A + (B − A) · c / 257` over 16-bit endpoints, with c = 36, 72, 113,
+144, 185, 221 for the eight-value mode and 48, 96, 161, 209 for the six-value one. Rounded to eight
+bits it agrees with the CPU decoder on 62.6% of palette entries, is one level off on 22.9%, and up
+to seven off on 0.04% — the widest six-value spans.
+
+Two things this page found that no device-free tier had, both about the same rule: a copy of a
+compressed level is sized in whole blocks against the level's *physical* extent, so a 2x2 mip is
+copied as 4x4 and a 2x2 copy is refused. The encoder's copies were wrong that way for one run, and
+`texture_write_level` had been wrong that way for every BC chain's tail since it was written.