@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts

@@ -1,11 +1,17 @@
 export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
+/**
+ * Which tree, and where it lives — one tree at a time, which is what an audit is.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_AUDIT_SETTINGS_STRUCT: WebGPUStruct;
 /**
  * Read every leaf's triangle back through the path the *intersector* uses.
  *
  * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
  * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
  * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
  *
  * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
  * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of
@@ -17,5 +23,6 @@ export const BLAS_AUDIT_WORKGROUP_SIZE: 64;
  * @type {ComputeShader}
  */
 export const shader_blas_audit_leaf_triangles: ComputeShader;
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
 import { ComputeShader } from "../../renderer/shader/ComputeShader.js";
 //# sourceMappingURL=shader_blas_audit_leaf_triangles.d.ts.map

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAqBA,2CAA4C;AA8D5C;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;8BArG2B,wCAAwC"}
+{"version":3,"file":"shader_blas_audit_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js"],"names":[],"mappings":"AAmBA,2CAA4C;AAE5C;;;;GAIG;AACH,yCAFU,YAAY,CAmBE;AA8DxB;;;;;;;;;;;;;;;;GAgBG;AACH,+CAFU,aAAa,CAMpB;6BA7G0B,4CAA4C;8BAd3C,wCAAwC"}

package/src/shade/playground/skinned_blas_refit/shader_blas_audit_leaf_triangles.js

@@ -15,16 +15,38 @@ import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../renderer/geometry/GEOMETRY_A
 import {
     MESHLET_METADATA_STRUCT
 } from "../../renderer/geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
-import {
-    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
-} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
+import { WebGPUStruct } from "../../renderer/shader/type/WebGPUStruct.js";
 
 export const BLAS_AUDIT_WORKGROUP_SIZE = 64;
 
+/**
+ * Which tree, and where it lives — one tree at a time, which is what an audit is.
+ *
+ * @type {WebGPUStruct}
+ */
+export const BLAS_AUDIT_SETTINGS_STRUCT = WebGPUStruct.from({
+    /**
+     * Leaves in this tree — one triangle each, so also its triangle count.
+     */
+    leaf_count: u32,
+    /**
+     * u32 word the tree's node 0 starts at inside the shared node arena.
+     */
+    node_word_offset: u32,
+    /**
+     * Word this tree's leaf list starts at inside the shared leaf-node arena.
+     */
+    leaf_nodes_offset: u32,
+    /**
+     * Row in the geometry table whose meshlets the leaves index into.
+     */
+    geometry_index: u32,
+}, "BlasAuditSettings");
+
 const resources = new ShaderResourceSetDescriptor();
 
 // per-dispatch, 16 bytes, read-only: immediate data rather than a uniform buffer
-resources.setImmediate("settings", BLAS_LEAF_BOUNDS_SETTINGS_STRUCT);
+resources.setImmediate("settings", BLAS_AUDIT_SETTINGS_STRUCT);
 resources.createGroup()
     .addStorageBuffer("leaf_nodes", WebGPUArray.from(u32), false)
     .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT), false)
@@ -87,7 +109,7 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
  * The refit computes a leaf's box with `geometry_read_triangle_bounds`; `ray_query_blas_nearest`
  * fetches the triangle it actually tests with `geometry_read_triangle_vertices`. Those are two
  * different functions over the same encoded payload, and nothing until now has held them against
- * each other on real data — only on a synthetic case in `blas_refit_leaf_bounds.spec.js`.
+ * each other on real data — only on a synthetic case in `chunk_geometry_read_triangle_bounds.spec.js`.
  *
  * If they disagree, a ray descends into a box, tests a triangle that is somewhere else, and misses.
  * Whole meshlets go absent while the tree itself checks out perfectly, which is exactly the shape of

package/src/shade/playground/skinned_blas_refit/verify_clone_leaves.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The leaf audit, on a skinned clone: its tree as the frame's refit left it, against the deformed
+ * triangles the intersector fetches for those leaves now.
+ *
+ * `verify_leaf_triangles` needs a target, and a clone's owner handle lives inside the skinning
+ * context. Every copy of a geometry shares one shape, so the clone's target is its source's with
+ * the clone's own node address substituted — and that address is what the published lookup holds
+ * for the clone's geometry row.
+ *
+ * The refit and this audit run a frame apart at most, so a leaf may be a little larger than its
+ * triangle; a leaf that is *somewhere else* is a leaf the frame did not refit. The pattern of those
+ * is the point: reported as runs of leaf ordinals and as the workgroups of 64 they fall in.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance]
+ * @returns {Promise<object>}
+ */
+export function verify_clone_leaves({ renderer, scene, mesh, tolerance }: {
+    renderer: Renderer;
+    scene: Scene;
+    mesh: SkinnedMesh;
+    tolerance?: number;
+}): Promise<object>;
+//# sourceMappingURL=verify_clone_leaves.d.ts.map

package/src/shade/playground/skinned_blas_refit/verify_clone_leaves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify_clone_leaves.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_clone_leaves.js"],"names":[],"mappings":"AAsDA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAN6B,QAAQ;IACX,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAsD3B"}

package/src/shade/playground/skinned_blas_refit/verify_clone_leaves.js

@@ -0,0 +1,127 @@
+import { verify_leaf_triangles } from "./verify_leaf_triangles.js";
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {number} offset
+ * @param {number} size
+ * @returns {Promise<ArrayBuffer>}
+ */
+async function read_back(device, buffer, offset, size) {
+    const staging = device.createBuffer({
+        label: 'audit/readback',
+        size,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    const encoder = device.createCommandEncoder({ label: 'audit/readback' });
+
+    encoder.copyBufferToBuffer(buffer, offset, staging, 0, size);
+
+    device.queue.submit([encoder.finish()]);
+
+    await staging.mapAsync(GPUMapMode.READ);
+
+    const copy = staging.getMappedRange().slice(0);
+
+    staging.unmap();
+    staging.destroy();
+
+    return copy;
+}
+
+/**
+ * Contiguous runs of a sorted list of integers, as `[first, last]` pairs.
+ *
+ * @param {number[]} values
+ * @returns {number[][]}
+ */
+function runs_of(values) {
+    const runs = [];
+
+    for (const value of values) {
+        const last = runs[runs.length - 1];
+
+        if (last !== undefined && last[1] === value - 1) {
+            last[1] = value;
+        } else {
+            runs.push([value, value]);
+        }
+    }
+
+    return runs;
+}
+
+/**
+ * The leaf audit, on a skinned clone: its tree as the frame's refit left it, against the deformed
+ * triangles the intersector fetches for those leaves now.
+ *
+ * `verify_leaf_triangles` needs a target, and a clone's owner handle lives inside the skinning
+ * context. Every copy of a geometry shares one shape, so the clone's target is its source's with
+ * the clone's own node address substituted — and that address is what the published lookup holds
+ * for the clone's geometry row.
+ *
+ * The refit and this audit run a frame apart at most, so a leaf may be a little larger than its
+ * triangle; a leaf that is *somewhere else* is a leaf the frame did not refit. The pattern of those
+ * is the point: reported as runs of leaf ordinals and as the workgroups of 64 they fall in.
+ *
+ * @param {object} options
+ * @param {Renderer} options.renderer
+ * @param {Scene} options.scene
+ * @param {SkinnedMesh} options.mesh a mesh whose clone is being deformed
+ * @param {number} [options.tolerance]
+ * @returns {Promise<object>}
+ */
+export async function verify_clone_leaves({ renderer, scene, mesh, tolerance = 1e-3 }) {
+    const graphics = renderer.graphics;
+    const device = graphics.device;
+    const geometries = graphics.geometries;
+    const blas = geometries.blas;
+
+    const scene_context = renderer.scenes.obtain(scene);
+
+    const geometry_index = scene_context.skinning.obtain_geometry_index(mesh);
+
+    const source_target = blas.get_refit_target(geometries.get_metadata(mesh.geometry));
+
+    if (source_target === undefined) {
+        throw new Error('the source geometry has no resident tree');
+    }
+
+    const address = new Uint32Array(
+        await read_back(device, blas.buffer_metadata, geometry_index * 4, 4)
+    )[0];
+
+    const target = {
+        ...source_target,
+        node_word_offset: address * 8,
+    };
+
+    const audit = await verify_leaf_triangles({ renderer, target, geometry_index, tolerance });
+
+    const escaped = audit.escaped_leaves;
+
+    const workgroups = [...new Set(escaped.map(leaf => leaf >> 6))];
+
+    const result = {
+        geometry_index,
+        address,
+        leaf_count: audit.leaf_count,
+        escaped: audit.escaped,
+        worst: audit.worst,
+        // the shape of the failure, if any
+        escaped_runs: runs_of(escaped).slice(0, 20),
+        escaped_run_count: runs_of(escaped).length,
+        workgroups_hit: workgroups.length,
+        workgroup_runs: runs_of(workgroups).slice(0, 20),
+        examples: audit.examples,
+        verdict: audit.escaped === 0
+            ? `pass — all ${audit.leaf_count} of the clone's leaves bound their deformed triangle`
+            : `FAIL — ${audit.escaped} of ${audit.leaf_count} leaves of the clone's tree do not bound `
+            + `their deformed triangle, in ${runs_of(escaped).length} runs over ${workgroups.length} workgroups`,
+    };
+
+    console.log(result.verdict, result);
+
+    return result;
+}

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js"],"names":[],"mappings":"AA4DA;;;;;;;;;;;GAWG;AACH;IAV6B,QAAQ;IACT,KAAK,GAAtB,MAAM;IACW,MAAM,GAAvB,MAAM;IAIU,cAAc,EAA9B,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAmI3B"}
+{"version":3,"file":"verify_leaf_triangles.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;;GAWG;AACH;IAV6B,QAAQ;IACT,KAAK,GAAtB,MAAM;IACW,MAAM,GAAvB,MAAM;IAIU,cAAc,EAA9B,MAAM;IACW,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAsI3B"}

package/src/shade/playground/skinned_blas_refit/verify_leaf_triangles.js

@@ -3,9 +3,6 @@ import {
     BVH_NODE_BOUNDS_WORD,
     BVH_NODE_STRIDE_WORDS
 } from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
-import {
-    BLAS_LEAF_BOUNDS_SETTINGS_STRUCT
-} from "../../renderer/geometry/bvh/shader_blas_refit_leaf_bounds.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { shader_blas_audit_leaf_triangles } from "./shader_blas_audit_leaf_triangles.js";
 
@@ -149,6 +146,7 @@ export async function verify_leaf_triangles({
     let worst = 0;
 
     const examples = [];
+    const escaped_leaves = [];
 
     for (let i = 0; i < leaf_count; i++) {
         const base = leaves[i] * BVH_NODE_STRIDE_WORDS + BVH_NODE_BOUNDS_WORD;
@@ -169,6 +167,7 @@ export async function verify_leaf_triangles({
 
         if (error > tolerance) {
             escaped += 1;
+            escaped_leaves.push(i);
 
             if (examples.length < 5) {
                 examples.push({
@@ -187,6 +186,7 @@ export async function verify_leaf_triangles({
     const result = {
         leaf_count,
         escaped,
+        escaped_leaves,
         worst: +worst.toFixed(5),
         examples,
         verdict: escaped === 0

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA4F3B"}
+{"version":3,"file":"verify_skinned_blas_refit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;GAeG;AACH;IAP6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACC,IAAI;IACR,SAAS,GAA1B,MAAM;IACJ,QAAQ,MAAM,CAAC,CAkF3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAJ6B,QAAQ;IACD,QAAQ;IAC/B,QAAQ,MAAM,CAAC,CA8F3B"}

package/src/shade/playground/skinned_blas_refit/verify_skinned_blas_refit.js

@@ -6,7 +6,7 @@ import {
     BVH_NODE_STRIDE_WORDS
 } from "../../renderer/gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
 import { bvh2_check_containment } from "../../renderer/geometry/bvh/bvh2_check_bounds.js";
-import { record_blas_refit } from "../../renderer/geometry/bvh/record_blas_refit.js";
+import { GPUBLASRefitBatch } from "../../renderer/geometry/bvh/GPUBLASRefitBatch.js";
 import { BVH2_NODE_STRUCT } from "../../renderer/shader/chunk/bvh/BVH2_NODE_STRUCT.js";
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 
@@ -26,7 +26,7 @@ const BVH_NULL_NODE = 0xffffffff;
  *   - `shader_meshlet_bounds_reduce` atomically merges every deformed vertex into the clone's
  *     geometry-metadata bounding box. It exists for the rasterizer's culling and knows nothing
  *     about trees.
- *   - {@link record_blas_refit} takes each leaf triangle's box and climbs the tree. The root node
+ *   - {@link GPUBLASRefitBatch} takes each leaf triangle's box and climbs the tree. The root node
  *     ends up bounding every triangle.
  *
  * Same vertices, same frame, two paths that share no code. They have to agree, and a stale BLAS
@@ -296,17 +296,19 @@ export async function verify_leaf_correspondence({ renderer, geometry }) {
 
     const cmd = ShadeGPUCommandContext.create(graphics, 'verify/leaf correspondence');
 
-    record_blas_refit(cmd, {
-        blas: geometries.blas,
-        geometries,
-        owner: metadata,
-        geometry_index: metadata.index,
-    });
+    // a batch of one: the source geometry, refitted from its own undeformed vertices
+    const batch = new GPUBLASRefitBatch(device);
+
+    batch.set_entries([{ owner: metadata, geometry_index: metadata.index }]);
+
+    batch.record(cmd, { blas: geometries.blas, geometries });
 
     cmd.finish();
 
     await device.queue.onSubmittedWorkDone();
 
+    batch.destroy();
+
     const region = new Float32Array(await read_back(
         device,
         geometries.blas.buffer_data,

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

@@ -0,0 +1,109 @@
+# 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.

package/src/shade/playground/texture_encode/index.html

@@ -0,0 +1,133 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — GPU block encoder</title>
+    <style>
+        :root {
+            color-scheme: dark;
+            --line: #2b3038;
+            --text: #d6dae0;
+            --muted: #8b939f;
+            --pass: #55c46a;
+            --fail: #ff6b6b;
+            --warn: #e5b54a;
+        }
+
+        html, body { margin: 0; background: #0d0f12; color: var(--text); font: 13px/1.5 system-ui, -apple-system, Segoe UI, sans-serif; }
+
+        main { padding: 16px 20px; max-width: 1400px; }
+
+        h1 { font-size: 15px; margin: 0 0 4px; }
+
+        p.note { color: var(--muted); margin: 0 0 12px; max-width: 90ch; }
+
+        .row { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: 8px 0; }
+
+        button, select, input {
+            font: inherit;
+            padding: 5px 11px;
+            border-radius: 6px;
+            border: 1px solid var(--line);
+            background: #1c1f25;
+            color: var(--text);
+        }
+
+        button { cursor: pointer; }
+
+        #status { font-size: 12px; color: var(--muted); }
+        #status.pass { color: var(--pass); }
+        #status.fail { color: var(--fail); }
+        #status.warn { color: var(--warn); }
+
+        #report {
+            margin: 8px 0 0;
+            white-space: pre;
+            font: 11.5px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace;
+        }
+
+        .panels { display: flex; gap: 12px; flex-wrap: wrap; margin-top: 12px; }
+
+        .panel { display: flex; flex-direction: column; gap: 4px; }
+
+        .panel span { font-size: 11.5px; color: var(--muted); }
+
+        canvas { border: 1px solid var(--line); background: #000; cursor: crosshair; touch-action: none; }
+
+        #readout {
+            min-height: 1.5em;
+            margin: 6px 0 0;
+            white-space: pre;
+            font: 11.5px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace;
+        }
+    </style>
+</head>
+<body>
+<main>
+    <h1>GPU block encoder — tier 8, a real device</h1>
+
+    <p class="note">
+        A texture goes in, a block-compressed texture comes out, on the device: one compute dispatch
+        over every level, one <code>copyBufferToTexture</code> per level. This page proves the parts
+        no device-free tier can: that <code>createTexture</code> takes the format, that the copies
+        take the padded rows, that the blocks the shader wrote are the blocks the texture holds, and
+        — by reading the texture back through the hardware's own decoder — that the picture is the
+        picture.
+    </p>
+
+    <div class="row">
+        <label>Target <select id="format">
+            <option value="bc4-r-unorm">bc4-r-unorm — red</option>
+            <option value="bc5-rg-unorm">bc5-rg-unorm — red and green</option>
+            <option value="bc1-rgba-unorm">bc1-rgba-unorm — RGB</option>
+            <option value="bc7-rgba-unorm">bc7-rgba-unorm — RGBA, mode 6</option>
+            <option value="bc6h-rgb-ufloat">bc6h-rgb-ufloat — HDR RGB, mode 11</option>
+            <option value="astc-4x4-unorm">astc-4x4-unorm — RGB, one partition (needs an ASTC device)</option>
+            <option value="bc4-r-snorm">bc4-r-snorm — red, signed</option>
+            <option value="bc5-rg-snorm">bc5-rg-snorm — red and green, signed</option>
+        </select></label>
+        <label>Source <select id="source">
+            <option value="512">synthetic 512x512 (smooth / rough / mask in R, G, B — channels unrelated)</option>
+            <option value="correlated512">synthetic 512x512, correlated colour (a photograph's case)</option>
+            <option value="normal512">synthetic 512x512, a normal map in red and green (signed bytes for a signed target)</option>
+            <option value="hdr512">synthetic 512x512, HDR: the correlated colour over fourteen stops with a sun (for BC6H)</option>
+            <option value="2048">synthetic 2048x2048 — for timing</option>
+        </select></label>
+        <input id="file" type="file" accept="image/*">
+        <button id="run">Encode</button>
+        <button id="probe">Probe hardware decoder</button>
+    </div>
+
+    <div id="device" class="note">…</div>
+    <div id="status">waiting for a device</div>
+    <pre id="report"></pre>
+
+    <div class="panels">
+        <div class="panel"><span>source, the channels the format carries</span><canvas id="source_view"></canvas></div>
+        <div class="panel"><span>hardware decode of the encoded texture</span><canvas id="decoded_view"></canvas></div>
+        <div class="panel"><span>FLIP, hardware decode against the source (magma: black is unseen, yellow is certain)</span><canvas id="difference_view"></canvas></div>
+    </div>
+
+    <div id="readout"></div>
+
+    <p class="note">
+        The three panels share one view: the wheel zooms about the pointer, a drag pans, a double
+        click refits. The circle is the same texel on all three, and the line above is what each
+        panel holds there.
+    </p>
+</main>
+
+<script type="module">
+    import { start } from './main.js';
+
+    start().catch(error => {
+        const status = document.getElementById('status');
+
+        status.className = 'fail';
+        status.textContent = String(error?.message ?? error);
+
+        console.error(error);
+    });
+</script>
+</body>
+</html>

package/src/shade/playground/texture_encode/main.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Stand the page up.
+ *
+ * @returns {Promise<void>}
+ */
+export function start(): Promise<void>;
+/**
+ * One level of a source image, as bytes and as the sampler the harness compares with.
+ */
+export type SourceLevel = {
+    width: number;
+    height: number;
+    /**
+     * `width * height * 4` bytes of the texel format — `rgba8unorm`,
+     * `rgba8snorm`, or the half floats of `rgba16float` for an HDR level, in which case it is
+     * `width * height * 8` bytes
+     */
+    rgba: Uint8Array;
+    /**
+     * `width * height * 3` linear RGB floats, present for an HDR level
+     */
+    hdr?: Float32Array;
+};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/texture_encode/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/texture_encode/main.js"],"names":[],"mappings":"AA+xBA;;;;GAIG;AACH,yBAFa,QAAQ,IAAI,CAAC,CAmnBzB;;;;;WAhyCa,MAAM;YACN,MAAM;;;;;;UACN,UAAU;;;;UAGV,YAAY"}