@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/texture/encode/ENCODE_NOTES_2026_09_02.md

@@ -0,0 +1,462 @@
+# GPU block encoder — notes
+
+**Date:** 2026-09-02
+**Scope:** `src/shade/renderer/texture/encode/`, `src/format/texture/bc/`, the software device's copy
+validation, and one fix to `texture_write_level`.
+
+This is §4.5 of [`COMPRESSED_TEXTURE_PLAN_2026_09_01.md`](../COMPRESSED_TEXTURE_PLAN_2026_09_01.md):
+runtime compression, generalised. A sampleable texture in, a block-compressed texture out, on the
+device. It is not §4.4's Basis transcoder, and it is not wired to the asset layer, the texture role
+or the preference list: the caller names a target format, and that is the whole interface.
+
+---
+
+## 1. What landed
+
+- **The framework**, carried by BC4: [`texture_encode`](texture_encode.js) records one compute
+  dispatch over every level of a source texture and one `copyBufferToTexture` per level into a new
+  texture of the requested format. [`texture_encode_layout`](texture_encode_layout.js) lays the
+  block buffer out with rows padded to 256 bytes before anything runs, and writes the level table the
+  shader reads. [`texture_encode_shader`](texture_encode_shader.js) is the registry: an implemented
+  target answers with its shader, a planned one is refused as "not implemented yet", anything else
+  as "not a target". Nothing is approximated by a neighbour.
+- **Eight shaders over five fits.** [`chunk_bc4_encode_block`](chunk_bc4_encode_block.js) for
+  `bc4-r-unorm` and, through its signed entry point over `[-127, 127]`, `bc4-r-snorm`; the same
+  chunk twice over for `bc5-rg-unorm` and `bc5-rg-snorm`;
+  [`chunk_bc1_encode_block`](chunk_bc1_encode_block.js) for `bc1-rgba-unorm` and its sRGB twin —
+  the RGB line fit that BC7 builds on; [`chunk_bc7_encode_block_mode6`](chunk_bc7_encode_block_mode6.js)
+  for `bc7-rgba-unorm` and its twin, mode 6 only;
+  [`chunk_bc6h_encode_block_mode11`](chunk_bc6h_encode_block_mode11.js) for `bc6h-rgb-ufloat`,
+  mode 11 only, the same line fitted in the half-float bit domain; and
+  [`chunk_astc_encode_block_4x4_rgb`](chunk_astc_encode_block_4x4_rgb.js) for `astc-4x4-unorm`
+  and its twin, the one-partition RGB block step 9f derived. The registry lists `astc-6x6` and
+  `astc-8x8` with their twins as planned and refuses them by name.
+- **The test harness** at every device-free tier: the encoder against an exhaustive optimum in the
+  WGSL emulator, the whole kernel against the encoder run directly over each level's image, the
+  orchestration on the software device with the copies executing over host-written bytes.
+- **A playground** on real hardware, [`playground/texture_encode`](../../../playground/texture_encode/README.md),
+  which read the texture back through the GPU's own decoder and found four things the device-free
+  tiers could not — §5 below.
+
+What did not land: BC7's partitioned modes, BC6H's two-region modes, ASTC's 6×6 and 8×8 footprints
+and its RGBA endpoint mode. The framework is the part that had to be right first.
+
+---
+
+## 2. The reading, source by source
+
+What each was read for, what was taken, what was rejected. Fetched on 2026-09-02, not recalled.
+
+### Ignacio Castaño, ludicon.com/castano
+
+- **"BC1 Compression Revisited" (2022).** Cluster fit: colours projected on a line and sorted, so the
+  index assignments worth solving are the 969 order-preserving partitions of sixteen texels into
+  four clusters, each solved by least squares in closed form; a weighted variant merges equal texels
+  and halves that count. The best-fit line "seems to work best", power iteration for it "is very
+  sensitive to the initial approximation". *Taken:* least squares given an assignment as the core of
+  every fit here, and the observation that the assignment, not the solve, is where quality is
+  decided — which the BC4 search in §3 is built on. *Deferred:* cluster fit itself, for BC1; in one
+  dimension the same ground is covered by the endpoint search, and measured against an exhaustive
+  optimum it is within 0.06 dB.
+- **"Normal Map Compression Revisited" (2026).** BC5 is two BC4 blocks; the hardware "expands the 8
+  bit endpoints to 16 bits via bit replication and performs the interpolation with 16 bits of
+  precision, so in practice you often get something like 10-11 bits of effective precision".
+  Signed formats "are rarely used" because a unorm source re-quantised to snorm loses precision.
+  *Taken:* the 16-bit claim, confirmed on hardware and quantified in §5; the reason the snorm targets
+  are a separate path and not a first one.
+- **"GPU Texture Compression Everywhere" (2025).** Not an encoder post: how to get a compute
+  shader's output into a compressed texture on each API — a temporary buffer bound as an unpack
+  buffer on GL, block-texel views on Vulkan, relaxed casting on D3D12, a blit on Metal. *Taken:* the
+  confirmation that WebGPU's only route, buffer then copy, is the shape every API ends up with.
+- **"Hardware Image Compression" (2026).** Fixed-rate hardware compression against Spark's
+  encoders, with RMSE per format on the author's set: BC4 High 1.71, BC5 High 3.04, BC7 High 4.21,
+  ASTC 5.36; Spark's BC7 at about 42 MP/s on an M4 Pro at 2048². *Taken:* calibration for what a
+  real-time encoder's quality and speed look like.
+- **"Choosing Texture Formats for WebGPU applications" (2026), "Spark 1.3 and spark.js" (2025).**
+  Positioning: ship web images, transcode to block formats at load. Quality reported in SSIMULACRA2.
+  *Taken:* nothing technical; both are the case for this subsystem existing.
+- **van Waveren & Castaño, "Real-Time DXT Compression" / "Real-Time Normal Map DXT Compression"
+  (2007, 2008).** Bounding-box endpoints inset by 1/16 of the range for colour and 1/32 for alpha,
+  index by thresholds along the line, no least squares; the GPU implementation "is not
+  bit-equivalent" to the CPU one. *Taken:* the inset-box as the baseline every fit here has to beat,
+  and the expectation that a device's f32 will not reproduce f64's choices — §5 measures it.
+  *Rejected:* stopping there; least squares plus the search is worth 2 dB on the mask fixture.
+
+### Spark.js (Ludicon)
+
+Asked for specifically. It is a JavaScript package exposing a subset of the Spark codecs as WGSL
+compute shaders — BC7, ASTC, ETC2, BC1, BC5, EAC — behind `encodeTexture(source, {format, mips,
+srgb, normal})`, with the format given as a channel mask or a WebGPU name. **Its shaders are not
+open**: the JavaScript is MIT, the shaders are under an EULA, free for non-commercial use or under
+$100,000 lifetime revenue. So there is nothing to take as code, and nothing about the encoders'
+internals is published beyond hints — register-pressure work, lookup tables replaced by "int16
+vectorization", mode-selection heuristics. What is applicable is the API shape (a format, a mip
+flag, an sRGB flag, a normal-map flag) and the existence proof that WGSL compute encoders reach BC7
+and ASTC at load-time rates in a browser. Reported honestly: a reference point and a competitor,
+not a source.
+
+### Krzysztof Narkowicz, "Real-Time BC6H Compression on GPU" (GDC 2016, GPURealTimeBC6H)
+
+Mode 11 only in the fast path, modes 2 and 6 in quality; everything in log2 space; bounding-box
+endpoints, texels ordered along the box diagonal, least squares; 10-bit quantisation; the 32
+partitions searched by distance to two lines. 0.02 ms and 0.53 ms for a 256²×6 cube map. *Taken:*
+the whole recipe, for stage 4 — it is also what betsy ports.
+
+### betsy (Matias Goldberg), `technical_doc_advanced.md`
+
+Thread mappings per format: BC1 one thread per block, from stb_dxt; BC4 four threads per block
+merged with `atomicOr`; BC5 as two BC4 dispatches and a stitch; ETC1/ETC2/EAC with many threads per
+block reducing over candidates. The input "must use raw RGBA8, not sRGB gamma correction". *Taken:*
+one thread per block for the fits, and the sRGB rule, arrived at independently in §3. *Rejected:*
+the four-thread BC4 with atomics — the fit here wants all sixteen texels in one lane — and the
+intermediate integer texture, which WebGPU does not need since a buffer copies straight in.
+
+### Microsoft DirectXTex, `BC7Encode.hlsl`
+
+Three passes: modes 4/5/6 with sixteen threads per block, one per texel; modes 1/3/7 and then 0/2
+with sixty-four threads per block, one per partition; endpoints by min/max reduction only; every
+p-bit combination tried; a `uint4` of error, mode, partition and rotation between passes. *Taken:*
+the p-bit enumeration and the lane-per-partition shape for the partitioned modes, where subgroup
+reductions will pay. *Rejected:* min/max endpoints without refinement — measured on BC4, the
+refinement is what separates a bounding box from an optimum.
+
+### Intel ISPC Texture Compressor
+
+Archived by Intel in September 2024. The README publishes no algorithm; the accompanying paper
+(not fetched) describes PCA initialisation, iterative least-squares refinement and pruned partition
+search. *Taken:* the recipe, which every encoder above shares.
+
+### Rich Geldreich, `bc7enc_rdo` / `rgbcx`
+
+BC4 has `encode_bc4_hq` with a search radius (default 3) around the extremes and both palette
+modes. BC1 has levels 0–18: the low ones against stb_dxt, with "fast all-integer PCA approximation",
+"2 least squares passes", then three-colour blocks and "transparent texels for black". *Taken:* the
+radius search and both modes for BC4 — the hierarchical search here is that idea with a wider reach;
+for BC1, two least-squares passes and a 5:6:5 search, as `etc1s_to_bc1.js` already does. *Rejected:*
+RDO, which trades quality for LZ-compressibility of a file; this encoder's output is VRAM.
+
+### Binomial, "Analytical real-time encoders" (bc7f)
+
+One-shot: covariance, per-channel variance and correlation predict which BC7 mode family is worth
+considering; error is modelled in closed form (orthogonal least-squares residual, quantisation
+noise, weight error) rather than by trial encoding. Strictly bounded, slightly below `bc7e` level 1
+in PSNR, but using every mode and partition. *Taken:* the direction for BC7 mode selection beyond
+mode 6 — predict, do not trial. Not needed for the single-subset mode.
+
+### QuickBC7 (Computers & Graphics 137, 2026)
+
+A Calinski–Harabasz index as a fast error estimate for partition selection, with a lookup table of
+candidate partitions and luma/alpha statistics to prune modes; a speedup over etcpak 2.0 at similar
+quality. *Noted* for BC7's partitioned modes.
+
+### ARM astcenc, Docs
+
+Presets from `-fastest` to `-exhaustive`; store as few channels as possible; normals as `rrrg` with
+`.ga` sampling; "for color data it is nearly always a perceptual quality win to use sRGB input source
+textures that are then compressed using the ASTC sRGB compression mode". *Noted* for stage 5.
+
+### niepp, ComputeASTC (D3D11 compute, 2021 write-up)
+
+One thread per block; single partition; no dual plane; fixed quantisation (weights QUANT_12 with
+256-level endpoints for RGB, QUANT_6 for RGBA); endpoints by "max accumulation" rather than PCA, for
+speed; BISE done in the shader; 34.2 dB against astcenc fast's 37 dB on 220 game textures; 1.97 ms
+for a 1024² chain on an iPhone 12. *Taken:* the shape for stage 5 — the tree's `astc_block.js`
+already writes the block this produces, with a placement search that beats fixed quantisation.
+
+### Tellusim GPU encoder
+
+Published numbers on an M1 Max at 1024×512: BC1 39.8 dB in 0.4 ms, BC7 48.3 dB in 1.0 ms, ASTC 4×4
+45.0 dB in 2.2 ms. *Taken:* calibration.
+
+### The WebGPU rules, from Dawn's `CommandValidation.cpp` and the device
+
+`copySize` must be a multiple of the block in both axes, bounded by the *physical* mip size;
+`bytesPerRow` a multiple of 256; the rest is in §5.
+
+---
+
+## 3. The state of the art, for a compute shader specifically
+
+The constraints differ from an offline SIMD encoder's, and the reading above agrees on what they
+imply:
+
+1. **One invocation, one block, everything in registers.** Sixteen texels and a handful of
+   candidate scores fit; the block never touches shared memory. Every real-time encoder read here
+   does this for the single-subset fits. Lanes are spent across *candidates* only where the
+   candidates are many and independent — BC7's 64 partitions, BC6H's 32 — and there a lane per
+   candidate with a subgroup reduction to pick the winner is the shape, which is where the engine's
+   subgroup-first rule pays and where stage 3's partition search will use it.
+2. **A fixed budget, no adaptive depth.** A lane that finishes early only waits. So the search is a
+   fixed candidate set: least squares with a fixed number of rounds, then a fixed grid of integer
+   endpoint pairs. Trial-encoding modes until one is good enough is the offline habit; predicting
+   the mode from block statistics (bc7f, QuickBC7) is the compute one.
+3. **Scoring is cheap; the assignment is the problem.** Least squares answers the best line for the
+   assignment it was given, and the assignment it was given came from the seed. On the mask fixture
+   the least-squares answer sits 3 dB below the optimum because a shorter line, with an outlying
+   texel handed to the hard 255, is in a different basin. A five-by-five grid at spacings of eight,
+   two and one — 75 scores, each sixteen texels — finds it, and costs nothing measurable at 650
+   MP/s.
+4. **Fit in the stored space; sRGB is a tag.** `bc7-rgba-unorm` and `-srgb` are the same bytes
+   (plan §5.3, WebGPU's format table, DXGI's `_SRGB` twins). The encoder reads the stored values —
+   an sRGB source is bound through a linear-twin view — and fits them. Whether the error metric
+   should be in linear light instead was asked, and measured on BC4 over the three fixtures:
+
+   | fixture | PSNR, stored space | PSNR, linear light |
+   |---|---|---|
+   | smooth | 51.89 dB | 51.62 dB |
+   | rough | 42.57 dB | 43.02 dB |
+   | mask | 54.65 dB | 51.44 dB |
+
+   The bytes are identical either way; only the reading differs, by under a decibel on continuous
+   content and by three on the mask, where a one-level error near white is a large linear step. The
+   stored space is the one every encoder above fits in, it is closer to perceptually uniform, and it
+   is what the hardware decodes before its own sRGB curve — so the metric stays there, and the
+   number is recorded rather than assumed.
+5. **The decoder you test against is not the decoder that runs.** The specification writes BC4's
+   interpolation in real arithmetic and leaves the precision to the implementation. §5 has what one
+   implementation does; the point for an encoder is that ±1 against a specification decoder is
+   noise, and anything beyond ±2 on real content is a wrong block.
+
+---
+
+## 4. The design
+
+- **No per-dispatch state.** The shader carries no immediates and no uniforms: a flat `u32` level
+  table in a storage buffer says how many levels, how many blocks, and for each level its mip, size,
+  block counts, first block, word offset and row stride. One dispatch covers the whole chain; each
+  invocation finds its level by a linear scan of at most fourteen records. This is also what lets
+  the playground run in a browser build that offers no immediate data at all.
+- **A two-dimensional workgroup grid** over a flat block index, because one dimension is capped at
+  `maxComputeWorkgroupsPerDimension`; the shader reads the row length from `num_workgroups`.
+- **Rows padded up front.** `texture_encode_layout` pads every level's rows to 256 bytes and starts
+  every level at a 256-aligned offset, so the encoder writes to the stride the copy reads.
+- **Copies sized in whole blocks**, against the physical mip size — the 2×2 and 1×1 tails are one
+  4×4 block each. §5 explains why this is written down.
+- **The block layout is one statement in two languages.** `bc4_write_block.js` under `format/` is
+  the JavaScript packer, which the UASTC→BC5 transcoder now uses too; `chunk_bc4_pack_block` is the
+  WGSL one; the emulator spec hands both the same endpoints and indices five hundred times and
+  requires the same bytes.
+- **Concrete modules.** One chunk per format, one shader per format, a registry that maps a name
+  to a shader. No template conditionals, no factories.
+- **The BC4 fit**, in [`chunk_bc4_encode_block`](chunk_bc4_encode_block.js): extremes, two rounds
+  of least squares, the 75-candidate search, in both palette modes, the six-value line seeded over
+  the interior texels only; every score against the decoder's rounded palette with the nearest
+  step checked against its neighbours.
+- **BC5 is two BC4 blocks**, red then green, and nothing else — the shader calls the BC4 chunk
+  twice and writes four words.
+- **The signed formats are the same fit in a different domain**, and the brief was right that
+  they are a path and not a tag: the endpoints are two's-complement bytes decoded over
+  `[-127, 127]` with `-128` read as `-127`, and the six-value mode's hard entries are the domain's
+  extremes. The BC4 chunk's fit takes the domain's bounds as arguments; `bc4_encode_block` calls
+  it over `[0, 255]` and `bc4_encode_block_snorm` over `[-127, 127]` from a sampler's `[-1, 1]`,
+  and the pack takes the two's complement, which is the identity for the unsigned domain. Two more
+  shaders, no more fitting code. Castaño's point stands — a unorm asset re-quantised to signed
+  loses a level — and it is the caller's decision, which is why the shader reads a signed source
+  as the sampler delivers it rather than converting one.
+- **The BC1 fit**, in [`chunk_bc1_encode_block`](chunk_bc1_encode_block.js): the principal axis by
+  four rounds of power iteration seeded with the box diagonal; the extreme projections as the ends;
+  two rounds of least squares with the weights `0, 1/3, 2/3, 1` shared across channels, the
+  assignment by distance to the four real points rather than by projection; then 5:6:5
+  quantisation and coordinate descent over the six stored components, twice, against the decoder's
+  truncated-thirds palette. A flat block searches each channel's pair of stored values for the
+  one-third mix nearest the colour — `stb_dxt`'s optimal-match tables, computed. The three-colour
+  mode is never written: its fourth index is a hole, not a lower-quality texel.
+- **BC7 mode 6**, in [`chunk_bc7_encode_block_mode6`](chunk_bc7_encode_block_mode6.js): the BC1
+  fit in four dimensions with sixteen points on the line and eight-bit ends — the 4×4 covariance's
+  principal axis, extreme projections, two rounds of least squares with BC7's own uneven weights,
+  then the four parity combinations rounded to and scored, one round of coordinate descent over the
+  eight stored components in steps of two (a second round was measured and moved nothing), and the
+  anchor honoured by writing the block the other way up when texel 0 lands in the upper half. Alpha
+  counts like any other channel. The block is packed by [`chunk_bc7_pack_mode6`](chunk_bc7_pack_mode6.js)
+  and held byte for byte against the tree's own `bc7_write_block`. Mode search across the
+  partitioned modes is a separate chunk for a later day, and the shader would call it instead;
+  nothing about the bytes changes.
+- **BC6H mode 11**, in [`chunk_bc6h_encode_block_mode11`](chunk_bc6h_encode_block_mode11.js): the
+  line is fitted in the half-float bit domain, because that is where the decoder interpolates —
+  an endpoint is a half's bit pattern quantised to ten bits, unquantised to sixteen, interpolated
+  with BC7's weights, scaled by 31/64 and read back as a half — so the palette is linear in bit
+  patterns, which is a log-like scale, and an error measured there is a relative one. That is
+  Narkowicz's `f32tof16` before anything else, arrived at from the format's own decode. The
+  conversion to half bits is written out, ties to even, rather than taken from `pack2x16float`,
+  and the spec holds it against `Float16Array` over the whole range and at every midpoint. One
+  region only: a block holding the sun and its surround has no line that serves both, and the
+  two-region modes are where that goes.
+- **ASTC 4×4**, in [`chunk_astc_encode_block_4x4_rgb`](chunk_astc_encode_block_4x4_rgb.js): the
+  one corner of ASTC this tree can already read and write — block mode `0x53`, one partition,
+  colour endpoint mode 8, six eight-bit endpoints, sixteen three-bit weights — with the BC1 line
+  fitted under ASTC's own arithmetic. Two things there are not BC1's: the interpolation widens the
+  ends to sixteen bits and rounds, which the direct form disagrees with on a texel in twenty
+  (§9.17), so every score uses the specification's form; and mode 8's rule that a pair whose second
+  sum is below its first is swapped *and blue-contracted* by the decoder, so such a pair is written
+  the other way up with its weights inverted (`astc_order_endpoints`, in WGSL). Eight weight levels
+  over eight-bit ends sit between BC1 and BC7 mode 6, and measure so. The pack is held byte for
+  byte against `astc_write_block`, and the test decoder was widened to the three-bit block mode.
+  RGB only: mode 8 carries no alpha, and the RGBA mode with its two-bit weights is a later chunk,
+  as are the 6×6 and 8×8 footprints, whose block modes, weight grids and partition seeds the tree
+  does not have yet.
+- **One thing the emulator taught.** `var copy = original; copy[channel] = value;` mutates
+  `original` in the emulator, which aliases vectors on assignment, and not on a device. The BC1
+  chunk builds a vector with one component replaced through `select` instead, so the same text
+  means the same thing on both. The kernel spec's byte-for-byte equality against the chunk is what
+  caught it.
+
+---
+
+## 5. What the hardware said
+
+NVIDIA Lovelace through Dawn, 2026-09-02, via the playground.
+
+**The copies.** A 2×2 level copied as 2×2 is refused: `copySize.width (2) is not a multiple of
+compressed texture format block width (4)`. `copyBufferToTexture`, `copyTextureToBuffer` and
+`writeTexture` alike. The extent is the level's physical size, rounded up to blocks — 4×4 for the
+tail — and a compressed texture whose *base* size is not a multiple of the block cannot be created
+at all. This is WebGPU's rule, not Vulkan's edge allowance, and the software device was wrong about
+it in the Vulkan direction until this afternoon.
+
+**Which means `texture_write_level` had been failing on hardware since step 3.** It wrote each level
+at its logical extent, so every BC chain's 2×2 and 1×1 levels were refused — silently, because a
+validation error does not throw and §9.13's playground counted exceptions. Fixed alongside, with
+the spec that had asserted the wrong extent now asserting the right one.
+
+**The encode.** 512² with ten levels, 21,847 blocks: 5.3 ms wall from record to done, 212 ms on the
+first run with the pipeline compile. 2048² with twelve levels, 349,527 blocks: **8.6 ms**, or
+650 MP/s, buffer copy and readback wait included. Validation clean; every level's blocks read back
+from the texture byte-identical to the block buffer.
+
+**The device against the emulator**, level 0 of the 512² source: 13,675 of 16,384 blocks identical.
+Of the 2,709 that differ, 2,428 decode to the same error, 120 better on the device, 161 worse —
+f32 breaking ties that f64 broke the other way. No difference in the picture. BC1 is steadier:
+16,380 of 16,384 identical on the correlated source, 16,379 on the independent one.
+
+**BC5 and BC1 on the same device**, 512² with ten levels, level 0:
+
+| target | source | PSNR, CPU decoder | PSNR, hardware | hardware − CPU decoder | wall |
+|---|---|---|---|---|---|
+| `bc5-rg-unorm` | smooth, rough | 45.24 dB | 44.69 dB | ≤ 3 | 4.1 ms |
+| `bc1-rgba-unorm` | correlated colour | 41.53 dB | 41.51 dB | ≤ 3 | 7.2 ms |
+| `bc1-rgba-unorm` | three unrelated channels | 31.55 dB | 31.53 dB | ≤ 3 | 4.3 ms |
+
+The hardware's BC1 decode sits within three levels of the truncated-thirds decoder everywhere, and
+its PSNR against the source is within 0.02 dB of the CPU decoder's: whatever this device does with
+BC1's thirds, it is much nearer the specification's arithmetic than its BC4 weights are.
+
+**The signed formats on the same device**, from a normal map stored as signed bytes, 512² with
+ten levels: `bc5-rg-snorm` 31.43 dB at level 0 against `bc5-rg-unorm`'s 37.40 on the same map
+stored unsigned — the 6.02 dB a halved peak costs for the same absolute error, so the same fit —
+with the hardware's picture within 0.55 dB of the CPU decoder's and 16,005 of 16,384 blocks
+identical to the emulator. The signed decoder's arithmetic holds on this hardware to the same
+rounding as the unsigned one's: worst samples of 5 to 7 on the widest spans.
+
+**BC6H mode 11 on the same device**, from the HDR fixture as `rgba16float`, 512² with ten levels:
+47.05 dB over half-float bits at level 0, the hardware decode **identical to the CPU decoder on
+every sample of every level** — the format requires a bit-accurate decoder and this device is one —
+16,383 of 16,384 blocks identical to the emulator, 3.6 ms. The worst sample is 2,413 bit patterns
+off, at the sun's edge, where one line cannot hold a texel of 400 and one of 0.1 in the same block;
+that is what the two-region modes are for.
+
+**ASTC was not seen on hardware.** This device reports fourteen compressed formats, all BC, as
+§9.16 found; the playground refuses the target by name before creating a texture. The ASTC
+encoder rests on the CPU decoder alone — the one §9.17 held against the reference encoder's blocks
+before trusting — and on the byte cross-check against the writer that reproduced those blocks. An
+ASTC device is the first thing to point this at.
+
+**BC7 mode 6 on the same device** is the clean case: the hardware decode is **identical to the CPU
+decoder on every sample of every level**, because BC7's interpolation is fully specified — integer
+weights out of 64, `+32`, `>> 6` — and this device implements exactly that. 512² correlated colour
+with a cut-out alpha: 46.04 dB by either decoder, 3.6 ms; 2048² of three unrelated channels:
+33.41 dB, 8.2 ms for 349,527 blocks, which is no slower than BC4 — the wall time is overhead, not
+the kernel. 16,231 of 16,384 level-0 blocks identical to the emulator.
+
+**The hardware decoder.** Read at full precision, a BC4 palette entry on this device is
+`A + (B − A) · c / 257` over 16-bit endpoints `A = 257a`, with
+
+| mode | c, by index 2..7 |
+|---|---|
+| eight-value | 36, 72, 113, 144, 185, 221 |
+| six-value | 48, 96, 161, 209, then 0 and 255 |
+
+against the specification's 1/7ths and 1/5ths. Rounded to eight bits, over every pair of endpoints
+and every index, it agrees with the CPU decoder on 62.6% of entries, is one level off on 22.9%, two
+on 8.3%, and up to seven on 0.04% — the widest six-value spans. On real content the two decodes
+differ by at most one level everywhere except the 4×4 mip, where one texel differs by two, and the
+picture the hardware shows is 0.6 dB below what the specification decoder predicts (52.66 against
+53.23 dB at 2048²). The encoder keeps scoring against the specification: a vendor's weights would be
+wrong on the next vendor, and the cost is under a decibel.
+
+---
+
+## 6. Quality, pinned
+
+In the emulator, on the three 64×64 fixtures, against the source:
+
+| fixture | this encoder | bounding line | floor in the spec |
+|---|---|---|---|
+| smooth | 51.89 dB, worst 2 | 51.79 dB | 51.5 dB, 2 |
+| rough | 42.57 dB, worst 7 | 42.21 dB | 42 dB, 8 |
+| mask | 54.65 dB, worst 8 | 52.68 dB | 54 dB, 10 |
+
+And against an exhaustive search over every endpoint pair in both modes, on a 24×24 crop of each:
+within 0.5 dB, which the spec asserts; the mask crop lands at 212 against the optimum's 211 in
+summed squared error, which is the whole of what the fixed budget leaves on the table.
+
+BC1, on the two 64×64 colour fixtures, and BC5 on a rough heightfield's normal map at 24×20:
+
+| fixture | this encoder | inset bounding box | floor in the spec |
+|---|---|---|---|
+| BC1, correlated colour | 40.32 dB, worst 18 | 25.34 dB | 40 dB, 20 |
+| BC1, three unrelated channels | 30.56 dB, worst 65 | 24.25 dB | 30 dB, 70 |
+| BC5, normal map | 38.04 dB, worst 11 | — | 37.5 dB, 13 |
+
+The bounding-box baseline is the 2007 form, along the axis diagonal; the correlated fixture's blue
+runs against its red and no box diagonal follows that, which is the case the principal axis exists
+for. A flat block decodes within one level of its colour where rounding to 5:6:5 alone leaves it
+two off, and every block is opaque.
+
+BC7 mode 6, over all four channels of the 64×64 fixtures:
+
+| fixture | this encoder | floor in the spec |
+|---|---|---|
+| correlated colour, opaque | 44.88 dB, worst 17 | 44.5 dB, 20 |
+| correlated colour, cut out by the mask | 44.26 dB, worst 16 | 44 dB, 20 |
+| three unrelated channels, opaque | 32.39 dB, worst 65 | 32 dB, 70 |
+
+Over the three channels it shares with BC1 on the correlated fixture: 43.93 against 40.32 dB, and
+the spec requires at least three decibels of that margin. What remains between this and an offline
+BC7 encoder is the partitioned modes — the mask's edges are the blocks a second subset would fit —
+and that is the next quality step rather than a change to this one.
+
+ASTC 4×4, over the three channels of the colour fixtures:
+
+| fixture | this encoder | floor in the spec |
+|---|---|---|
+| correlated colour | 43.25 dB, worst 19 | 43 dB, 22 |
+| three unrelated channels | 31.09 dB, worst 65 | 30.5 dB, 70 |
+
+Between BC1's 40.32 and 30.56 and BC7 mode 6's 44.88 and 32.39 on the same pictures, which is
+where eight weight levels over eight-bit ends sit between four over 5:6:5 and sixteen over eight
+bits; the spec requires at least two decibels over BC1. A flat block decodes exactly.
+
+BC6H mode 11, on the 64×64 HDR fixture — the correlated colour in linear light over fourteen stops
+with a sun of 400: **45.11 dB over half-float bits** (peak the largest finite half) and **0.0775
+stops** RMS log error, the figure the real-time BC6H literature reports; floors of 44.5 dB and 0.09
+stops in the spec. A flat block decodes within sixteen bit patterns of its value across the whole
+range, which is the ten-bit quantum.
+
+---
+
+## 7. Not done, and named
+
+- `astc-6x6-unorm`, `astc-8x8-unorm` and their `-srgb` twins: listed as targets, refused as
+  unimplemented. They need the block modes, weight grids and partition seeds of the larger
+  footprints, none of which the tree holds; the 4×4 path is the shape they would take.
+- BC7's modes other than 6, BC6H's modes other than 11, and ASTC's partitions, dual plane and
+  RGBA endpoint mode. Every block is the single-region mode; the partitioned and dual-plane modes
+  are where the remaining quality is, and a mode search is a separate chunk the shader would call
+  instead.
+- ASTC on a device. None in reach samples it.
+- BC6H's signed format, `bc6h-rgb-float`, which is not in WebGPU's format table as a target here.
+- BC1's three-colour mode, and with it any use of a source's alpha: a cut-out wants BC7.
+- The consumer side: nothing calls `texture_encode` but the specs and the playground. A
+  `TextureManager` path that encodes a decoded image on upload is the plan's §4.1 third kind and is
+  deliberately not here.
+- Timestamp queries in the playground: the numbers are wall time from record to done, and say so.

package/src/shade/renderer/texture/encode/chunk_astc_encode_block_4x4_rgb.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Encode sixteen RGB texels as one ASTC 4x4 block: one partition, eight-bit endpoints, three-bit
+ * weights.
+ *
+ * **The one corner of ASTC this tree can already read.** Step 9f derived this block's layout from
+ * the specification and beat the reference encoder with it; step 9h inverted the packings. What is
+ * ported here is the encoder's part: the same RGB line as BC1's, fitted under ASTC's own
+ * arithmetic, which is not BC1's in two places that each cost a level if ignored:
+ *
+ * 1. **The interpolation.** ASTC widens each eight-bit endpoint to sixteen by replication,
+ *    interpolates there with a `+32` round, and takes the top eight bits. Against the direct form
+ *    that disagrees on one texel in twenty, always by a level, so every score here is the
+ *    specification's form — `astc_interpolate` in `astc_block.js`, in WGSL.
+ * 2. **The endpoint order.** Colour endpoint mode 8 compares the two ends by the sum of their
+ *    channels and, when the second's is below the first's, *swaps them and blue-contracts both* —
+ *    a different picture, not a mirrored one, recorded by no bit. So a fitted pair whose sums come
+ *    out the wrong way round is written the other way up with its weights inverted, which decodes
+ *    identically; that is `astc_order_endpoints`, in WGSL.
+ *
+ * Eight weight levels, unevenly spaced — `0, 9, 18, 27, 37, 46, 55, 64` of 64 — over eight-bit
+ * ends: between BC1 and BC7 mode 6 in what it can hold, at BC7's eight bits a texel. The fit is
+ * the principal axis, the extreme projections, two rounds of least squares with those weights, and
+ * one round of coordinate descent over the six stored bytes against the decoder's palette. Alpha
+ * is not read: mode 8 carries none, and a cut-out wants the RGBA mode, which is a later chunk.
+ *
+ * This is the only target here that no device in reach can sample, so it rests on the CPU decoder
+ * alone — the decoder that §9.17 held against the reference encoder's blocks before trusting it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_astc_encode_block_4x4_rgb: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_astc_encode_block_4x4_rgb.d.ts.map

package/src/shade/renderer/texture/encode/chunk_astc_encode_block_4x4_rgb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_astc_encode_block_4x4_rgb.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/texture/encode/chunk_astc_encode_block_4x4_rgb.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8CAFU,SAAS,CAsRZ;0BArTmB,oCAAoC"}