@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/playground/texture_encode/main.js

@@ -0,0 +1,1430 @@
+import { MAGMA_LUT } from "../../../core/color/colormap/MAGMA_LUT.js";
+import { FlipParameters } from "../../../engine/graphics/texture/sampler/compare/flip/FlipParameters.js";
+import { flip_pool } from "../../../engine/graphics/texture/sampler/compare/flip/flip_pool.js";
+import { sampler2d_flip_ldr } from "../../../engine/graphics/texture/sampler/compare/flip/sampler2d_flip_ldr.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { sampler2d_channel_apply_lut } from "../../../engine/graphics/texture/sampler/sampler2d_channel_apply_lut.js";
+import {
+    sampler2d_max_absolute_difference
+} from "../../../engine/graphics/texture/sampler/compare/sampler2d_max_absolute_difference.js";
+import { sampler2d_psnr } from "../../../engine/graphics/texture/sampler/compare/sampler2d_psnr.js";
+import {
+    decode_astc_4x4,
+    decode_bc1,
+    decode_bc4,
+    decode_bc4_snorm,
+    decode_bc5,
+    decode_bc5_snorm,
+    decode_bc6h_ufloat,
+    decode_bc7
+} from "../../../format/texture/basis/__fixtures__/decode_blocks.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GraphicsContext } from "../../renderer/GraphicsContext.js";
+import {
+    block_bytes,
+    encode_image_with_block_encoder
+} from "../../renderer/texture/encode/__fixtures__/encode_image_with_block_encoder.js";
+import {
+    color_correlated_image,
+    hdr_image,
+    mask_image,
+    normal_map_image,
+    rough_image,
+    smooth_image
+} from "../../renderer/texture/encode/__fixtures__/encode_test_images.js";
+import { chunk_astc_encode_block_4x4_rgb } from "../../renderer/texture/encode/chunk_astc_encode_block_4x4_rgb.js";
+import { chunk_bc1_encode_block } from "../../renderer/texture/encode/chunk_bc1_encode_block.js";
+import { chunk_bc4_encode_block } from "../../renderer/texture/encode/chunk_bc4_encode_block.js";
+import { chunk_bc6h_encode_block_mode11 } from "../../renderer/texture/encode/chunk_bc6h_encode_block_mode11.js";
+import { chunk_bc7_encode_block_mode6 } from "../../renderer/texture/encode/chunk_bc7_encode_block_mode6.js";
+import { texture_encode } from "../../renderer/texture/encode/texture_encode.js";
+import { texture_encode_level_blocks } from "../../renderer/texture/encode/texture_encode_layout.js";
+import { gpu_texture_compression_support } from "../../renderer/texture/format/gpu_texture_compression_support.js";
+import { texture_write_level } from "../../renderer/texture/texture_write_level.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+import { ComputeShaderEmulator } from "../../wgsl/emulator/ComputeShaderEmulator.js";
+import { create_panel_group } from "./panel_view.js";
+
+/**
+ * The GPU block encoder on a real device.
+ *
+ * **Drives the device directly, without the renderer.** The renderer's frame loop needs immediate
+ * data, which not every browser build offers, and nothing here needs a frame: the encoder is a
+ * dispatch and some copies recorded into a command context, and the proof is read back. What the
+ * device-free tiers established — the encoder's quality, the layout, the wiring — is taken as read;
+ * what this page adds is everything only hardware can answer:
+ *
+ * 1. `createTexture` accepts the block format, and `copyBufferToTexture` accepts the padded rows.
+ * 2. The blocks in the texture are the blocks the shader wrote — read back with
+ *    `copyTextureToBuffer` and compared byte for byte with the block buffer.
+ * 3. The hardware decodes them to the texels the test decoder predicts — read back through a
+ *    `textureLoad` pass, which is the GPU's own BC decoder speaking.
+ * 4. The device's f32 arithmetic lands on the blocks the f64 emulator chose, or on blocks no worse.
+ *
+ * Every number on the page is against the source image, through the quality harness the transcoders
+ * were held to.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * @param {string} id
+ * @returns {HTMLElement}
+ */
+function element(id) {
+    return document.getElementById(id);
+}
+
+/**
+ * Side of each of the three panels, CSS pixels
+ * @type {number}
+ */
+const PANEL_SIZE = 384;
+
+const PANEL_SOURCE = 0;
+const PANEL_HARDWARE = 1;
+const PANEL_FLIP = 2;
+
+/**
+ * How long to wait for a frame before going on without one, milliseconds. A document that is not
+ * shown runs no frames, and a run should not stand still until its tab is looked at.
+ *
+ * @type {number}
+ */
+const PAINT_FALLBACK_MS = 250;
+
+/**
+ * Resolves once the page has painted, or once the fallback has passed. A status set right before a
+ * long synchronous pass is never seen unless a frame goes by first.
+ *
+ * @returns {Promise<void>}
+ */
+function painted() {
+    return new Promise(resolve => {
+        const fallback = setTimeout(resolve, PAINT_FALLBACK_MS);
+
+        requestAnimationFrame(() => setTimeout(() => {
+            clearTimeout(fallback);
+            resolve();
+        }, 0));
+    });
+}
+
+/**
+ * One level of a source image, as bytes and as the sampler the harness compares with.
+ *
+ * @typedef {Object} SourceLevel
+ * @property {number} width
+ * @property {number} height
+ * @property {Uint8Array} rgba `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
+ * @property {Float32Array} [hdr] `width * height * 3` linear RGB floats, present for an HDR level
+ */
+
+/**
+ * A 2x2 box filter, per channel, rounded — the mip chain a source is given so every level of the
+ * encode has a truth to be judged against.
+ *
+ * @param {SourceLevel} level
+ * @returns {SourceLevel}
+ */
+function halve(level) {
+    const width = Math.max(1, level.width >> 1);
+    const height = Math.max(1, level.height >> 1);
+
+    if (level.hdr !== undefined) {
+        const hdr = new Float32Array(width * height * 3);
+
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                for (let c = 0; c < 3; c++) {
+                    const x0 = Math.min(x * 2, level.width - 1);
+                    const x1 = Math.min(x * 2 + 1, level.width - 1);
+                    const y0 = Math.min(y * 2, level.height - 1);
+                    const y1 = Math.min(y * 2 + 1, level.height - 1);
+
+                    hdr[(y * width + x) * 3 + c] = (
+                        level.hdr[(y0 * level.width + x0) * 3 + c]
+                        + level.hdr[(y0 * level.width + x1) * 3 + c]
+                        + level.hdr[(y1 * level.width + x0) * 3 + c]
+                        + level.hdr[(y1 * level.width + x1) * 3 + c]
+                    ) / 4;
+                }
+            }
+        }
+
+        return { width, height, hdr, rgba: hdr_bytes(hdr, width * height) };
+    }
+
+    const rgba = new Uint8Array(width * height * 4);
+
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            for (let c = 0; c < 4; c++) {
+                const x0 = Math.min(x * 2, level.width - 1);
+                const x1 = Math.min(x * 2 + 1, level.width - 1);
+                const y0 = Math.min(y * 2, level.height - 1);
+                const y1 = Math.min(y * 2 + 1, level.height - 1);
+
+                const sum = level.rgba[(y0 * level.width + x0) * 4 + c]
+                    + level.rgba[(y0 * level.width + x1) * 4 + c]
+                    + level.rgba[(y1 * level.width + x0) * 4 + c]
+                    + level.rgba[(y1 * level.width + x1) * 4 + c];
+
+                rgba[(y * width + x) * 4 + c] = Math.round(sum / 4);
+            }
+        }
+    }
+
+    return { width, height, rgba };
+}
+
+/**
+ * The bytes of an `rgba16float` level: each channel a half, alpha one.
+ *
+ * @param {Float32Array} hdr `texels * 3` linear floats
+ * @param {number} texels
+ * @returns {Uint8Array} `texels * 8`
+ */
+function hdr_bytes(hdr, texels) {
+    const halves = new Float16Array(texels * 4);
+
+    for (let i = 0; i < texels; i++) {
+        halves[i * 4] = hdr[i * 3];
+        halves[i * 4 + 1] = hdr[i * 3 + 1];
+        halves[i * 4 + 2] = hdr[i * 3 + 2];
+        halves[i * 4 + 3] = 1;
+    }
+
+    return new Uint8Array(halves.buffer);
+}
+
+/**
+ * The half-float bit patterns of linear values, which is the domain BC6H's error lives in.
+ *
+ * @param {Float32Array} values
+ * @returns {Uint16Array}
+ */
+function half_bits_of(values) {
+    const halves = new Float16Array(values.length);
+
+    for (let i = 0; i < values.length; i++) {
+        halves[i] = Math.min(65504, Math.max(0, values[i]));
+    }
+
+    return new Uint16Array(halves.buffer);
+}
+
+/**
+ * @param {SourceLevel} base
+ * @returns {SourceLevel[]} the full chain, base first
+ */
+function mip_chain(base) {
+    const levels = [base];
+
+    const count = texture_mip_level_count(base.width, base.height, 1, "2d");
+
+    for (let level = 1; level < count; level++) {
+        levels.push(halve(levels[level - 1]));
+    }
+
+    return levels;
+}
+
+/**
+ * The three fixture images the specs measure with, one per channel, at a size worth timing —
+ * three channels with nothing in common, which is the hard case for a colour format. Or, with
+ * `correlated`, the colour fixture whose channels move together, which is what a photograph is. Or,
+ * with `normal`, a tangent-space normal map in red and green — as unsigned bytes, or as the signed
+ * bytes a signed target reads, so the picture is the same picture either way rather than a ramp
+ * wrapped into a cliff by a change of sign.
+ *
+ * @param {number} size
+ * @param {'independent'|'correlated'|'normal'} kind
+ * @param {boolean} signed
+ * @returns {SourceLevel}
+ */
+function synthetic_source(size, kind, signed) {
+    const rgba = new Uint8Array(size * size * 4);
+
+    if (kind === 'hdr') {
+        const hdr = hdr_image(size, size);
+
+        return { width: size, height: size, hdr, rgba: hdr_bytes(hdr, size * size) };
+    }
+
+    if (kind === 'normal') {
+        const normals = normal_map_image(size, size, 3);
+
+        for (let i = 0; i < size * size; i++) {
+            for (let c = 0; c < 2; c++) {
+                const unorm = normals[i * 2 + c];
+
+                // the byte a signed format stores for the same direction: [-127, 127], wrapped
+                rgba[i * 4 + c] = signed ? (Math.round((unorm / 255) * 254 - 127) & 0xFF) : unorm;
+            }
+
+            rgba[i * 4 + 2] = signed ? 127 : 255;
+            rgba[i * 4 + 3] = signed ? 127 : 255;
+        }
+
+        return { width: size, height: size, rgba };
+    }
+
+    if (kind === 'correlated') {
+        const rgb = color_correlated_image(size, size);
+
+        for (let i = 0; i < size * size; i++) {
+            rgba[i * 4] = rgb[i * 3];
+            rgba[i * 4 + 1] = rgb[i * 3 + 1];
+            rgba[i * 4 + 2] = rgb[i * 3 + 2];
+            rgba[i * 4 + 3] = 255;
+        }
+
+        return { width: size, height: size, rgba };
+    }
+
+    const channels = [smooth_image(size, size), rough_image(size, size, 7), mask_image(size, size)];
+
+    for (let i = 0; i < size * size; i++) {
+        rgba[i * 4] = channels[0][i];
+        rgba[i * 4 + 1] = channels[1][i];
+        rgba[i * 4 + 2] = channels[2][i];
+        rgba[i * 4 + 3] = 255;
+    }
+
+    return { width: size, height: size, rgba };
+}
+
+/**
+ * @param {File} file
+ * @returns {Promise<SourceLevel>}
+ */
+async function file_source(file) {
+    const bitmap = await createImageBitmap(file);
+
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    const context = canvas.getContext('2d');
+
+    context.drawImage(bitmap, 0, 0);
+
+    const data = context.getImageData(0, 0, bitmap.width, bitmap.height);
+
+    return { width: bitmap.width, height: bitmap.height, rgba: new Uint8Array(data.data.buffer) };
+}
+
+/**
+ * The leading `count` channels of interleaved texels, re-interleaved on their own.
+ *
+ * @param {Uint8Array} data
+ * @param {number} stride channels per texel in `data`
+ * @param {number} count channels to keep
+ * @param {number} texels
+ * @returns {Uint8Array} `texels * count` bytes
+ */
+function leading_channels(data, stride, count, texels, signed = false) {
+    const out = data instanceof Float32Array
+        ? new Float32Array(texels * count)
+        : signed ? new Int8Array(texels * count) : new Uint8Array(texels * count);
+
+    for (let i = 0; i < texels; i++) {
+        for (let c = 0; c < count; c++) {
+            const value = data[i * stride + c];
+
+            // a signed format's byte is two's complement, and -128 reads as -127
+            out[i * count + c] = signed ? Math.max(-127, (value << 24) >> 24) : value;
+        }
+    }
+
+    return out;
+}
+
+/**
+ * What the page knows about each target it can encode to: how many of the source's channels the
+ * format carries, how the test decoder reads its blocks back to those channels, and how the same
+ * encoder runs in the emulator on the host.
+ *
+ * @type {Object<string, {channels: number, bytes_per_block: number, decode: (blocks: Uint8Array, width: number, height: number) => Uint8Array, emulate: () => Promise<(values: Uint8Array) => Uint8Array>}>}
+ */
+const FORMATS = {
+    'bc4-r-snorm': {
+        channels: 1,
+        bytes_per_block: 8,
+        signed: true,
+        decode: (blocks, width, height) => decode_bc4_snorm(blocks, width, height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc4_encode_block);
+
+            return values => {
+                const snorm = new Float32Array(16);
+
+                for (let i = 0; i < 16; i++) {
+                    snorm[i] = Math.max(-127, (values[i] << 24) >> 24) / 127;
+                }
+
+                return block_bytes(lib.bc4_encode_block_snorm(snorm));
+            };
+        },
+    },
+    'bc5-rg-snorm': {
+        channels: 2,
+        bytes_per_block: 16,
+        signed: true,
+        decode: (blocks, width, height) => decode_bc5_snorm(blocks, width, height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc4_encode_block);
+
+            return values => {
+                const out = new Uint8Array(16);
+
+                for (let channel = 0; channel < 2; channel++) {
+                    const snorm = new Float32Array(16);
+
+                    for (let i = 0; i < 16; i++) {
+                        snorm[i] = Math.max(-127, (values[i * 2 + channel] << 24) >> 24) / 127;
+                    }
+
+                    out.set(block_bytes(lib.bc4_encode_block_snorm(snorm)), channel * 8);
+                }
+
+                return out;
+            };
+        },
+    },
+    'bc4-r-unorm': {
+        channels: 1,
+        bytes_per_block: 8,
+        signed: false,
+        decode: (blocks, width, height) => decode_bc4(blocks, width, height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc4_encode_block);
+
+            return values => {
+                const unorm = new Float32Array(16);
+
+                for (let i = 0; i < 16; i++) {
+                    unorm[i] = values[i] / 255;
+                }
+
+                return block_bytes(lib.bc4_encode_block(unorm));
+            };
+        },
+    },
+    'bc5-rg-unorm': {
+        channels: 2,
+        bytes_per_block: 16,
+        signed: false,
+        decode: (blocks, width, height) => leading_channels(decode_bc5(blocks, width, height), 4, 2, width * height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc4_encode_block);
+
+            return values => {
+                const out = new Uint8Array(16);
+
+                for (let channel = 0; channel < 2; channel++) {
+                    const unorm = new Float32Array(16);
+
+                    for (let i = 0; i < 16; i++) {
+                        unorm[i] = values[i * 2 + channel] / 255;
+                    }
+
+                    out.set(block_bytes(lib.bc4_encode_block(unorm)), channel * 8);
+                }
+
+                return out;
+            };
+        },
+    },
+    'bc6h-rgb-ufloat': {
+        channels: 3,
+        bytes_per_block: 16,
+        signed: false,
+        hdr: true,
+        decode: (blocks, width, height) => decode_bc6h_ufloat(blocks, width, height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc6h_encode_block_mode11);
+
+            // handed floats rather than bytes: an HDR level's truth is its linear values
+            return values => {
+                const texels = [];
+
+                for (let i = 0; i < 16; i++) {
+                    texels.push(new Float32Array([values[i * 3], values[i * 3 + 1], values[i * 3 + 2]]));
+                }
+
+                return block_bytes(lib.bc6h_encode_block_mode11(texels));
+            };
+        },
+    },
+    'bc7-rgba-unorm': {
+        channels: 4,
+        bytes_per_block: 16,
+        signed: false,
+        decode: (blocks, width, height) => decode_bc7(blocks, width, height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc7_encode_block_mode6);
+
+            return values => {
+                const texels = [];
+
+                for (let i = 0; i < 16; i++) {
+                    texels.push(new Float32Array([values[i * 4] / 255, values[i * 4 + 1] / 255, values[i * 4 + 2] / 255, values[i * 4 + 3] / 255]));
+                }
+
+                return block_bytes(lib.bc7_encode_block_mode6(texels));
+            };
+        },
+    },
+    'astc-4x4-unorm': {
+        channels: 3,
+        bytes_per_block: 16,
+        signed: false,
+        decode: (blocks, width, height) => {
+            const blocks_x = Math.ceil(width / 4);
+            const blocks_y = Math.ceil(height / 4);
+
+            const out = new Uint8Array(width * height * 3);
+
+            for (let by = 0; by < blocks_y; by++) {
+                for (let bx = 0; bx < blocks_x; bx++) {
+                    const texels = decode_astc_4x4(blocks, (by * blocks_x + bx) * 16);
+
+                    if (texels === null) {
+                        throw new Error(`block ${by * blocks_x + bx} is not the shape the decoder reads`);
+                    }
+
+                    for (let i = 0; i < 16; i++) {
+                        const x = bx * 4 + (i & 3);
+                        const y = by * 4 + (i >> 2);
+
+                        if (x < width && y < height) {
+                            out.set(texels[i], (y * width + x) * 3);
+                        }
+                    }
+                }
+            }
+
+            return out;
+        },
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_astc_encode_block_4x4_rgb);
+
+            return values => {
+                const texels = [];
+
+                for (let i = 0; i < 16; i++) {
+                    texels.push(new Float32Array([values[i * 3] / 255, values[i * 3 + 1] / 255, values[i * 3 + 2] / 255]));
+                }
+
+                return block_bytes(lib.astc_encode_block_4x4_rgb(texels));
+            };
+        },
+    },
+    'bc1-rgba-unorm': {
+        channels: 3,
+        bytes_per_block: 8,
+        signed: false,
+        decode: (blocks, width, height) => leading_channels(decode_bc1(blocks, width, height), 4, 3, width * height),
+        emulate: async () => {
+            const lib = await ComputeShaderEmulator.fromCodeChunk(chunk_bc1_encode_block);
+
+            return values => {
+                const texels = [];
+
+                for (let i = 0; i < 16; i++) {
+                    texels.push(new Float32Array([values[i * 3] / 255, values[i * 3 + 1] / 255, values[i * 3 + 2] / 255]));
+                }
+
+                return block_bytes(lib.bc1_encode_block(texels));
+            };
+        },
+    },
+};
+
+/**
+ * Read one level of a block-compressed texture back through the hardware's decoder: a
+ * `textureLoad` per texel into a buffer of words.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUTexture} texture
+ * @param {number} level
+ * @param {number} width
+ * @param {number} height
+ * @param {'bytes'|'signed'|'float'|'exact_red'} mode `bytes` answers every channel rounded to
+ * eight-bit levels, `signed` the same as signed bytes, `float` every channel as the f32 the
+ * sampler delivers, and `exact_red` the red channel alone as f32 — the decoder produces more
+ * precision than eight bits, and the probe wants it
+ * @returns {Promise<Uint8Array|Int8Array|Float32Array>} interleaved RGBA, `width * height * 4`
+ * samples; or the red channel's `width * height` floats
+ */
+async function hardware_decode(device, texture, level, width, height, mode) {
+    const per_texel = mode === 'float' ? 4 : 1;
+
+    const store = {
+        bytes: 'out[at] = pack4x8unorm(texel);',
+        signed: 'out[at] = pack4x8snorm(texel);',
+        exact_red: 'out[at] = bitcast<u32>(texel.r);',
+        float: 'out[at * 4u] = bitcast<u32>(texel.r); out[at * 4u + 1u] = bitcast<u32>(texel.g); out[at * 4u + 2u] = bitcast<u32>(texel.b); out[at * 4u + 3u] = bitcast<u32>(texel.a);',
+    }[mode];
+
+    const module = device.createShaderModule({
+        code: `
+@group(0) @binding(0) var tex: texture_2d<f32>;
+@group(0) @binding(1) var<storage, read_write> out: array<u32>;
+@group(0) @binding(2) var<uniform> level: vec4<u32>;
+
+@compute @workgroup_size(8, 8, 1)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let size = textureDimensions(tex, i32(level.x));
+
+    if (id.x >= size.x || id.y >= size.y) {
+        return;
+    }
+
+    let texel = textureLoad(tex, vec2<i32>(id.xy), i32(level.x));
+    let at = id.y * size.x + id.x;
+
+    ${store}
+}
+`,
+    });
+
+    const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' } });
+
+    const byte_length = width * height * 4 * per_texel;
+
+    const out = device.createBuffer({ size: byte_length, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
+    const uniform = device.createBuffer({ size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+    const readback = device.createBuffer({ size: byte_length, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+
+    device.queue.writeBuffer(uniform, 0, new Uint32Array([level, 0, 0, 0]));
+
+    const bind_group = device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: texture.createView() },
+            { binding: 1, resource: { buffer: out } },
+            { binding: 2, resource: { buffer: uniform } },
+        ],
+    });
+
+    const encoder = device.createCommandEncoder();
+
+    const pass = encoder.beginComputePass();
+
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(0, bind_group);
+    pass.dispatchWorkgroups(Math.ceil(width / 8), Math.ceil(height / 8), 1);
+    pass.end();
+
+    encoder.copyBufferToBuffer(out, 0, readback, 0, byte_length);
+
+    device.queue.submit([encoder.finish()]);
+
+    await readback.mapAsync(GPUMapMode.READ);
+
+    const range = readback.getMappedRange().slice(0);
+
+    readback.unmap();
+
+    out.destroy();
+    uniform.destroy();
+    readback.destroy();
+
+    // the packing puts red in the low byte, which is where a little-endian byte view starts
+    if (mode === 'bytes') {
+        return new Uint8Array(range);
+    }
+
+    if (mode === 'signed') {
+        return new Int8Array(range);
+    }
+
+    return new Float32Array(range);
+}
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} source
+ * @param {number} byte_length
+ * @returns {Promise<Uint8Array>}
+ */
+async function read_buffer(device, source, byte_length) {
+    const readback = device.createBuffer({ size: byte_length, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+
+    const encoder = device.createCommandEncoder();
+
+    encoder.copyBufferToBuffer(source, 0, readback, 0, byte_length);
+
+    device.queue.submit([encoder.finish()]);
+
+    await readback.mapAsync(GPUMapMode.READ);
+
+    const bytes = new Uint8Array(readback.getMappedRange().slice(0));
+
+    readback.unmap();
+    readback.destroy();
+
+    return bytes;
+}
+
+/**
+ * The blocks of one level of a compressed texture, read back with the copy the encoder's copy is the
+ * inverse of.
+ *
+ * @param {GPUDevice} device
+ * @param {GPUTexture} texture
+ * @param {TextureEncodeLevel} level
+ * @param {number} bytes_per_block
+ * @returns {Promise<Uint8Array>} tightly packed
+ */
+async function read_texture_level(device, texture, level, bytes_per_block) {
+    const padded = level.bytes_per_row * level.blocks_y;
+
+    const readback = device.createBuffer({ size: padded, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+
+    const encoder = device.createCommandEncoder();
+
+    // sized in whole blocks, as the encoder's own copy is — the device refuses a 2x2 extent
+    encoder.copyTextureToBuffer(
+        { texture, mipLevel: level.level },
+        { buffer: readback, bytesPerRow: level.bytes_per_row, rowsPerImage: level.blocks_y },
+        [level.copy_width, level.copy_height, 1]
+    );
+
+    device.queue.submit([encoder.finish()]);
+
+    await readback.mapAsync(GPUMapMode.READ);
+
+    const bytes = new Uint8Array(readback.getMappedRange().slice(0));
+
+    readback.unmap();
+    readback.destroy();
+
+    const row_bytes = level.blocks_x * bytes_per_block;
+
+    const out = new Uint8Array(row_bytes * level.blocks_y);
+
+    for (let row = 0; row < level.blocks_y; row++) {
+        out.set(bytes.subarray(row * level.bytes_per_row, row * level.bytes_per_row + row_bytes), row * row_bytes);
+    }
+
+    return out;
+}
+
+/**
+ * Linear HDR values as display bytes: a Reinhard curve and a display gamma, so the sun clips and
+ * the shadows show.
+ *
+ * @param {Float32Array} values
+ * @returns {Uint8Array}
+ */
+function tonemap(values) {
+    const out = new Uint8Array(values.length);
+
+    for (let i = 0; i < values.length; i++) {
+        const v = Math.max(0, values[i]);
+
+        out[i] = Math.round(Math.min(1, (v / (1 + v)) ** (1 / 2.2)) * 255);
+    }
+
+    return out;
+}
+
+/**
+ * An HDR image through a block encoder that takes forty-eight floats, edge texels repeated.
+ *
+ * @param {(values: Float32Array) => Uint8Array} encode_block
+ * @param {Float32Array} image `width * height * 3`
+ * @param {number} width
+ * @param {number} height
+ * @returns {Uint8Array} tightly packed blocks
+ */
+function encode_hdr_image(encode_block, image, width, height) {
+    const blocks_x = Math.ceil(width / 4);
+    const blocks_y = Math.ceil(height / 4);
+
+    const out = new Uint8Array(blocks_x * blocks_y * 16);
+    const values = new Float32Array(48);
+
+    for (let by = 0; by < blocks_y; by++) {
+        for (let bx = 0; bx < blocks_x; bx++) {
+            for (let i = 0; i < 16; i++) {
+                const x = Math.min(bx * 4 + (i & 3), width - 1);
+                const y = Math.min(by * 4 + (i >> 2), height - 1);
+
+                for (let c = 0; c < 3; c++) {
+                    values[i * 3 + c] = image[(y * width + x) * 3 + c];
+                }
+            }
+
+            out.set(encode_block(values), (by * blocks_x + bx) * 16);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * The bytes a canvas shows for one, two or three interleaved channels: one as grey, two as red and
+ * green, three as colour — opaque RGBA, which is also what FLIP compares, since FLIP judges what is
+ * displayed.
+ *
+ * @param {ArrayLike<number>} data
+ * @param {number} channels
+ * @param {number} texels
+ * @param {number} gain
+ * @param {boolean} signed values in [-127, 127], shown with zero at mid grey
+ * @returns {Uint8Array} `texels * 4`
+ */
+function display_rgba(data, channels, texels, gain = 1, signed = false) {
+    const out = new Uint8Array(texels * 4);
+
+    for (let i = 0; i < texels; i++) {
+        for (let c = 0; c < 3; c++) {
+            const source = channels === 1 ? 0 : c;
+
+            const value = source < channels ? data[i * channels + source] : (signed ? -128 : 0);
+
+            out[i * 4 + c] = Math.min(255, (signed ? value + 128 : value) * gain);
+        }
+
+        out[i * 4 + 3] = 255;
+    }
+
+    return out;
+}
+
+/**
+ * Stand the page up.
+ *
+ * @returns {Promise<void>}
+ */
+export async function start() {
+    const status_element = element('status');
+    const report_element = element('report');
+    const readout_element = element('readout');
+
+    /**
+     * What each panel holds at a texel, for the line under the panels; set by the run that drew
+     * them, null before the first.
+     *
+     * @type {?function(number, number): string}
+     */
+    let describe_texel = null;
+
+    const panels = create_panel_group({
+        canvases: [element('source_view'), element('decoded_view'), element('difference_view')],
+        size: PANEL_SIZE,
+        on_cursor: texel => {
+            readout_element.textContent = texel === null || describe_texel === null ? '' : describe_texel(texel.x, texel.y);
+        }
+    });
+
+    /**
+     * @param {string} text
+     * @param {string} [kind]
+     */
+    function set_status(text, kind = '') {
+        status_element.textContent = text;
+        status_element.className = kind;
+    }
+
+    if (navigator.gpu === undefined) {
+        set_status('no WebGPU in this browser', 'fail');
+
+        return;
+    }
+
+    const adapter = await navigator.gpu.requestAdapter();
+
+    if (adapter === null) {
+        set_status('no WebGPU adapter', 'fail');
+
+        return;
+    }
+
+    // every compression family the adapter offers is asked for, so the encoder can be handed any
+    // of its targets; the encoder itself needs no feature at all
+    const requiredFeatures = ['texture-compression-bc', 'texture-compression-etc2', 'texture-compression-astc']
+        .filter(feature => adapter.features.has(feature));
+
+    const device = await adapter.requestDevice({ requiredFeatures });
+
+    const support = gpu_texture_compression_support(device);
+
+    element('device').textContent = `${adapter.info?.vendor ?? '?'} ${adapter.info?.architecture ?? ''}`
+        + ` — ${support.size} compressed formats sampleable, features: ${requiredFeatures.join(', ') || 'none'}`;
+
+    const graphics = new GraphicsContext(device);
+
+    /** @type {SourceLevel|null} */
+    let uploaded_source = null;
+
+    globalThis.device = device;
+
+    /**
+     * @param {SourceLevel} base
+     */
+    async function run(base) {
+        const format = element('format').value;
+
+        const info = FORMATS[format];
+
+        if (info === undefined) {
+            set_status(`${format} is not a format this page knows how to judge`, 'fail');
+
+            return;
+        }
+
+        if (!support.has(format)) {
+            set_status(`${format} cannot be sampled on this device, so the texture cannot be created`, 'fail');
+
+            return;
+        }
+
+        set_status(`encoding ${base.width}x${base.height} to ${format}…`);
+
+        const levels = mip_chain(base);
+
+        if (info.hdr === true && base.hdr === undefined) {
+            set_status(`${format} wants an HDR source; pick the HDR synthetic one`, 'fail');
+
+            return;
+        }
+
+        // a signed target reads a signed source: the same bytes, meaning [-1, 1] to the sampler;
+        // an HDR target reads halves
+        const source = device.createTexture({
+            label: 'source',
+            size: [base.width, base.height, 1],
+            format: info.hdr ? 'rgba16float' : (info.signed ? 'rgba8snorm' : 'rgba8unorm'),
+            mipLevelCount: levels.length,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+        });
+
+        for (let level = 0; level < levels.length; level++) {
+            texture_write_level(device.queue, source, level, levels[level].rgba);
+        }
+
+        const lines = [];
+
+        /**
+         * Record, submit and wait, answering with the result and the wall time.
+         *
+         * @returns {Promise<{result: TextureEncodeResult, blocks_copy: GPUBuffer, wall_ms: number}>}
+         */
+        async function encode_once() {
+            const cmd = ShadeGPUCommandContext.create(graphics, 'texture encode');
+
+            const started = performance.now();
+
+            const result = texture_encode(cmd, {
+                source,
+                format,
+                level_count: levels.length,
+                usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC,
+            });
+
+            // the block buffer is transient and goes back to the pool at finish, so it is copied out now
+            const blocks_copy = device.createBuffer({
+                size: result.layout.byte_length,
+                usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+            });
+
+            cmd.copyBufferToBuffer(result.blocks, 0, blocks_copy, 0, result.layout.byte_length);
+
+            cmd.finish();
+
+            await device.queue.onSubmittedWorkDone();
+
+            return { result, blocks_copy, wall_ms: performance.now() - started };
+        }
+
+        device.pushErrorScope('validation');
+
+        // twice: the first run compiles the pipeline, the second is what a second texture costs
+        const first = await encode_once();
+
+        first.result.texture.destroy();
+        first.blocks_copy.destroy();
+
+        const { result, blocks_copy, wall_ms } = await encode_once();
+
+        const validation = await device.popErrorScope();
+
+        if (validation !== null) {
+            set_status(`validation error: ${validation.message}`, 'fail');
+
+            lines.push(validation.message);
+            report_element.textContent = lines.join('\n');
+
+            return;
+        }
+
+        const texels = levels.reduce((sum, level) => sum + level.width * level.height, 0);
+
+        lines.push(`${format}  ${base.width}x${base.height}, ${levels.length} levels, ${result.layout.block_count} blocks`);
+        lines.push(`  wall time, record to done   ${wall_ms.toFixed(2)} ms   (${(texels / 1e6 / (wall_ms / 1000)).toFixed(1)} MP/s; first run with pipeline compile ${first.wall_ms.toFixed(1)} ms)`);
+        lines.push(`  block buffer                ${result.layout.byte_length} bytes, rows padded to ${result.layout.levels[0].bytes_per_row}`);
+        lines.push('');
+        lines.push('  level     size   PSNR dB  max   hw PSNR  hw max   texture==buffer   hw decode vs CPU decode');
+
+        const blocks = await read_buffer(device, blocks_copy, result.layout.byte_length);
+
+        blocks_copy.destroy();
+
+        let all_texture_match = true;
+        let hardware_mismatch_total = 0;
+        let hardware_max = 0;
+        let hardware_psnr_gap = 0;
+        let flip_line = '';
+
+        for (const level of result.layout.levels) {
+            const texel_count = level.width * level.height;
+
+            const truth = info.hdr
+                ? levels[level.level].hdr
+                : leading_channels(levels[level.level].rgba, 4, info.channels, texel_count, info.signed);
+
+            const level_blocks = texture_encode_level_blocks(result.layout, blocks, level.level);
+
+            const decoded = info.decode(level_blocks, level.width, level.height);
+
+            /*
+             What a sampler is measured over: bytes for an LDR format, and for BC6H the half-float
+             bit patterns, which is the domain its decoder interpolates in and a relative error in
+             value — with the largest finite half as the peak.
+            */
+            const measure = samples => info.hdr ? half_bits_of(samples) : samples;
+            const peak = info.hdr ? 0x7BFF : (info.signed ? 127 : 255);
+
+            // the PSNR of one level everywhere: no picture is credited as closer to the source than
+            // a rounding, so a level one decoder reproduces exactly still has a ratio to take
+            const rounding_psnr = 20 * Math.log10(peak);
+
+            const reference = new Sampler2D(measure(truth), info.channels, level.width, level.height);
+            const test = new Sampler2D(measure(decoded), info.channels, level.width, level.height);
+
+            const psnr = sampler2d_psnr(reference, test, info.channels, peak);
+            const max = sampler2d_max_absolute_difference(reference, test);
+
+            // 2. the texture holds the buffer's blocks
+            const from_texture = await read_texture_level(device, result.texture, level, result.layout.bytes_per_block);
+
+            let texture_match = from_texture.length === level_blocks.length;
+
+            for (let i = 0; texture_match && i < level_blocks.length; i++) {
+                texture_match = from_texture[i] === level_blocks[i];
+            }
+
+            all_texture_match = all_texture_match && texture_match;
+
+            // 3. the hardware decodes what the test decoder predicts
+            const hardware = leading_channels(
+                await hardware_decode(device, result.texture, level.level, level.width, level.height, info.hdr ? 'float' : (info.signed ? 'signed' : 'bytes')),
+                4, info.channels, texel_count, info.signed
+            );
+
+            const hardware_measured = measure(hardware);
+            const decoded_measured = measure(decoded);
+
+            let mismatches = 0;
+            let worst = 0;
+
+            for (let i = 0; i < hardware_measured.length; i++) {
+                const delta = Math.abs(hardware_measured[i] - decoded_measured[i]);
+
+                if (delta !== 0) {
+                    mismatches++;
+                }
+
+                worst = Math.max(worst, delta);
+            }
+
+            hardware_mismatch_total += mismatches;
+            hardware_max = Math.max(hardware_max, worst);
+
+            // what the GPU actually shows against the source — the number a user would see
+            const hardware_sampler = new Sampler2D(hardware_measured, info.channels, level.width, level.height);
+
+            const hardware_psnr = sampler2d_psnr(reference, hardware_sampler, info.channels, peak);
+            const hardware_worst = sampler2d_max_absolute_difference(reference, hardware_sampler);
+
+            /*
+             The gap is the CPU decoder's reading minus the hardware's, where the hardware is worse,
+             both held at the PSNR of a rounding. A tail level the CPU decoder reproduces exactly has
+             infinite PSNR, and against a hardware texel one level off the ratio is whatever the
+             ceiling makes it — a 200 dB ceiling read BC1's 1x1 level as a 150 dB gap. Under the
+             rounding ceiling that level is no gap at all, while a misread block on it stays tens of
+             decibels under.
+            */
+            hardware_psnr_gap = Math.max(hardware_psnr_gap, Math.min(psnr, rounding_psnr) - Math.min(hardware_psnr, rounding_psnr));
+
+            lines.push(
+                `  ${String(level.level).padStart(5)}  ${`${level.width}x${level.height}`.padStart(9)}`
+                + `  ${psnr.toFixed(2).padStart(7)}  ${String(max).padStart(3)}`
+                + `  ${hardware_psnr.toFixed(2).padStart(7)}  ${String(hardware_worst).padStart(6)}`
+                + `   ${texture_match ? 'yes' : 'NO '}             `
+                + `  ${mismatches} samples differ, worst ${worst}`
+            );
+
+            if (level.level === 0) {
+                const shown_truth = info.hdr ? tonemap(truth) : truth;
+                const shown_hardware = info.hdr ? tonemap(hardware) : hardware;
+
+                const truth_rgba = display_rgba(shown_truth, info.channels, texel_count, 1, info.signed);
+                const hardware_rgba = display_rgba(shown_hardware, info.channels, texel_count, 1, info.signed);
+
+                panels.set_picture(PANEL_SOURCE, truth_rgba, level.width, level.height);
+                panels.set_picture(PANEL_HARDWARE, hardware_rgba, level.width, level.height);
+
+                /*
+                 The third panel is FLIP: how likely a viewer flipping between the two pictures is
+                 to notice a difference, and where. A tint nobody would see scores low and a
+                 displaced edge scores high, which is what an amplified pixel difference gets
+                 backwards. It compares the displayed bytes — the tone-mapped picture for HDR, the
+                 mid-grey-centred one for a signed format — because that is what is seen. It is a
+                 CPU pass over the whole image, seconds at 2048x2048, so the status says what the
+                 page is doing and a frame goes by so that it shows.
+                */
+                set_status(`encoded; FLIP over ${level.width}x${level.height}…`);
+
+                await painted();
+
+                const flip_started = performance.now();
+
+                const error = sampler2d_flip_ldr(
+                    new Sampler2D(truth_rgba, 4, level.width, level.height),
+                    new Sampler2D(hardware_rgba, 4, level.width, level.height)
+                );
+
+                const flip_ms = performance.now() - flip_started;
+
+                // the readbacks of the other levels are awaited, so this one paints on its own
+                set_status(`FLIP done in ${flip_ms.toFixed(0)} ms; the other levels, then the emulator over level 0…`);
+
+                const pooled = flip_pool(error);
+
+                panels.set_picture(PANEL_FLIP, display_rgba(sampler2d_channel_apply_lut(error, 0, MAGMA_LUT, 3).data, 3, texel_count), level.width, level.height);
+
+                // the bytes the panels show at a texel, in the format's own units — a signed
+                // format's are shown about mid grey and an HDR one's tone-mapped — and FLIP there
+                const shown_channels = Math.min(info.channels, 3);
+
+                describe_texel = (x, y) => {
+                    const i = y * level.width + x;
+
+                    const bytes = rgba => Array.from(rgba.subarray(i * 4, i * 4 + shown_channels), byte => info.signed ? byte - 128 : byte).join(' ');
+
+                    return `texel ${x}, ${y}   source ${bytes(truth_rgba)}   hardware ${bytes(hardware_rgba)}${info.hdr ? '  (tone-mapped bytes)' : ''}   FLIP ${error.data[i].toFixed(4)}`;
+                };
+
+                flip_line = `  FLIP, level 0, hardware picture against the source at ${new FlipParameters().pixels_per_degree.toFixed(1)} pixels per degree:`
+                    + `  mean ${pooled.mean.toFixed(4)}, weighted median ${pooled.weighted_median.toFixed(4)}, max ${pooled.maximum.toFixed(4)}`
+                    + `  (${flip_ms.toFixed(0)} ms)`;
+            }
+        }
+
+        lines.push('');
+        lines.push(flip_line);
+
+        // 4. the device against the emulator, block by block, on level 0 — the emulator runs a
+        // block in a fraction of a millisecond, which is fine at 512x512 and a hang at 2048
+        lines.push('');
+
+        const emulator_limit = 32768;
+
+        if (base.width * base.height / 16 > emulator_limit) {
+            lines.push(`  device against the emulator: skipped above ${emulator_limit} blocks; use the 512x512 source`);
+        } else try {
+            const encode_block = await info.emulate();
+
+            const truth = info.hdr
+                ? levels[0].hdr
+                : leading_channels(levels[0].rgba, 4, info.channels, base.width * base.height, info.signed);
+
+            // the helper hands the encoder bytes; a signed encoder reads them as two's complement,
+            // and an HDR level is encoded from its floats directly
+            const emulated = info.hdr
+                ? encode_hdr_image(encode_block, truth, base.width, base.height)
+                : encode_image_with_block_encoder(
+                    encode_block, info.bytes_per_block, new Uint8Array(truth.buffer), base.width, base.height, info.channels
+                );
+
+            const gpu = texture_encode_level_blocks(result.layout, blocks, 0);
+
+            const bytes_per_block = info.bytes_per_block;
+            const block_count = gpu.length / bytes_per_block;
+
+            let identical = 0;
+            let gpu_better = 0;
+            let gpu_worse = 0;
+            let gpu_equal = 0;
+
+            const gpu_decoded = info.decode(gpu, base.width, base.height);
+            const emulated_decoded = info.decode(emulated, base.width, base.height);
+
+            for (let block = 0; block < block_count; block++) {
+                let same = true;
+
+                for (let i = 0; i < bytes_per_block; i++) {
+                    same = same && gpu[block * bytes_per_block + i] === emulated[block * bytes_per_block + i];
+                }
+
+                if (same) {
+                    identical++;
+
+                    continue;
+                }
+
+                // a different block is fine if it is no worse; the device's f32 rounds differently
+                const bx = block % Math.ceil(base.width / 4);
+                const by = Math.floor(block / Math.ceil(base.width / 4));
+
+                let gpu_error = 0;
+                let emulated_error = 0;
+
+                for (let y = by * 4; y < Math.min(by * 4 + 4, base.height); y++) {
+                    for (let x = bx * 4; x < Math.min(bx * 4 + 4, base.width); x++) {
+                        for (let c = 0; c < info.channels; c++) {
+                            const at = (y * base.width + x) * info.channels + c;
+
+                            gpu_error += (gpu_decoded[at] - truth[at]) ** 2;
+                            emulated_error += (emulated_decoded[at] - truth[at]) ** 2;
+                        }
+                    }
+                }
+
+                if (gpu_error < emulated_error) {
+                    gpu_better++;
+                } else if (gpu_error > emulated_error) {
+                    gpu_worse++;
+                } else {
+                    gpu_equal++;
+                }
+            }
+
+            lines.push(`  device against the emulator, level 0: ${identical} of ${block_count} blocks identical;`
+                + ` of the rest ${gpu_equal} equal in error, ${gpu_better} better on the device, ${gpu_worse} worse`);
+        } catch (error) {
+            lines.push(`  emulator comparison skipped: ${error.message}`);
+        }
+
+        report_element.textContent = lines.join('\n');
+
+        /*
+         The hardware's interpolation is not the specification's rounding — the probe below has the
+         exact weights — so a few levels against the CPU decoder on a wide-span block is the
+         decoder's arithmetic, not a wrong block. What a wrong block does is move whole texels by
+         tens, which shows up as the hardware's picture being decibels worse than the CPU decoder's
+         reading of the same bytes. So the verdict is that difference, per level, with nothing finer
+         than a rounding counted.
+        */
+        const verdict = all_texture_match && hardware_psnr_gap <= 1;
+
+        set_status(
+            verdict
+                ? `ok — texture holds the shader's blocks on every level; the hardware's picture is within ${hardware_psnr_gap.toFixed(2)} dB of the CPU decoder's, a rounding forgiven; samples within ${hardware_max} (${hardware_mismatch_total} differ)`
+                : `problem — texture matches buffer: ${all_texture_match}; the hardware's picture is ${hardware_psnr_gap.toFixed(2)} dB under the CPU decoder's, a rounding forgiven; samples up to ${hardware_max} apart`,
+            verdict ? 'pass' : 'fail'
+        );
+
+        globalThis.last_result = result;
+
+        source.destroy();
+    }
+
+    /**
+     * What the hardware's BC4 decoder actually computes, found rather than assumed.
+     *
+     * A 1024x1024 BC4 texture holds every pair of endpoints as one block each, with texels 0..7
+     * carrying indices 0..7 — so a hardware read of the texture is the whole decode table, 256 x
+     * 256 x 8 entries, read back at the precision the sampler delivers rather than rounded to eight
+     * bits. From that the interpolation weight at every index is fitted exactly, and the difference
+     * from the CPU decoder the specs judge with is tabulated. The specification writes the
+     * interpolation in real arithmetic and leaves the precision to the implementation; this is what
+     * one implementation chose.
+     */
+    async function probe_decoder() {
+        // 65536 pairs at 256 blocks a row is 256 rows of blocks: 1024 texels tall, not 512
+        const width = 1024;
+        const height = 1024;
+
+        const blocks_x = width / 4;
+
+        const blocks = new Uint8Array(blocks_x * (height / 4) * 8);
+
+        for (let first = 0; first < 256; first++) {
+            for (let second = 0; second < 256; second++) {
+                const block = first * 256 + second;
+
+                const at = block * 8;
+
+                blocks[at] = first;
+                blocks[at + 1] = second;
+
+                // texels 0..7 take indices 0..7 in order: eight three-bit fields, 24 bits, 3 bytes
+                const word = 0 | (1 << 3) | (2 << 6) | (3 << 9) | (4 << 12) | (5 << 15) | (6 << 18) | (7 << 21);
+
+                blocks[at + 2] = word & 0xFF;
+                blocks[at + 3] = (word >> 8) & 0xFF;
+                blocks[at + 4] = (word >> 16) & 0xFF;
+            }
+        }
+
+        const texture = device.createTexture({
+            label: 'decoder probe',
+            size: [width, height, 1],
+            format: 'bc4-r-unorm',
+            usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING,
+        });
+
+        texture_write_level(device.queue, texture, 0, blocks);
+
+        const exact = await hardware_decode(device, texture, 0, width, height, 'exact_red');
+
+        texture.destroy();
+
+        /**
+         * The hardware's value for one entry of one pair's palette, as the unorm it sampled.
+         *
+         * @param {number} first
+         * @param {number} second
+         * @param {number} index
+         * @returns {number}
+         */
+        const sampled = (first, second, index) => {
+            const block = first * 256 + second;
+
+            const x = (block % blocks_x) * 4 + (index & 3);
+            const y = Math.floor(block / blocks_x) * 4 + (index >> 2);
+
+            return exact[y * width + x];
+        };
+
+        const lines = [
+            'the hardware BC4 decoder, over every pair of endpoints:',
+            '',
+            '  the weight of the second endpoint at each index, fitted from the unrounded samples as',
+            '  value = A + (B - A) * w over 16-bit endpoints A = 257a. An interval is the set of weights',
+            '  every pair agrees with; an empty one would mean no single weight does.',
+            '',
+        ];
+
+        for (const [mode, indices] of [['eight-value (first > second)', [2, 3, 4, 5, 6, 7]], ['six-value (first <= second)', [2, 3, 4, 5]]]) {
+            for (const index of indices) {
+                let low = -Infinity;
+                let high = Infinity;
+
+                for (let first = 0; first < 256; first += 3) {
+                    for (let second = 0; second < 256; second += 3) {
+                        const eight = first > second;
+                        const wanted_eight = indices.length === 6;
+
+                        if (eight !== wanted_eight || Math.abs(first - second) < 32) {
+                            continue;
+                        }
+
+                        const A = first * 257;
+                        const B = second * 257;
+
+                        const w = (sampled(first, second, index) * 65535 - A) / (B - A);
+
+                        // the 16-bit value is within half a unit of what the hardware computed
+                        const tolerance = 0.51 / Math.abs(B - A);
+
+                        low = Math.max(low, w - tolerance);
+                        high = Math.min(high, w + tolerance);
+                    }
+                }
+
+                const mid = (low + high) / 2;
+
+                lines.push(
+                    `  ${mode} index ${index}: w = ${mid.toFixed(6)}`
+                    + `  (x257 = ${(mid * 257).toFixed(2)}, the specification's ${(indices.length === 6 ? (index - 1) / 7 : (index - 1) / 5).toFixed(6)})`
+                    + (high < low ? '  EMPTY' : '')
+                );
+            }
+        }
+
+        // and, rounded to eight bits, how far that is from the CPU decoder the specs judge with
+        const histogram = new Map();
+
+        for (let first = 0; first < 256; first++) {
+            for (let second = 0; second < 256; second++) {
+                const block = new Uint8Array(8);
+
+                block[0] = first;
+                block[1] = second;
+                block[2] = 0b10001000;
+                block[3] = 0b11000110;
+                block[4] = 0b11111010;
+
+                const reference = decode_bc4(block, 4, 2);
+
+                for (let index = 0; index < 8; index++) {
+                    const delta = Math.round(sampled(first, second, index) * 255) - reference[index];
+
+                    histogram.set(delta, (histogram.get(delta) ?? 0) + 1);
+                }
+            }
+        }
+
+        const total = 65536 * 8;
+
+        lines.push('');
+        lines.push('  hardware, rounded to eight bits, minus the CPU decoder, over every pair and index:');
+
+        for (const delta of [...histogram.keys()].sort((a, b) => a - b)) {
+            lines.push(`    ${String(delta).padStart(3)}: ${String(histogram.get(delta)).padStart(7)}  (${(100 * histogram.get(delta) / total).toFixed(2)}%)`);
+        }
+
+        report_element.textContent = lines.join('\n');
+
+        set_status('decoder probe done', 'pass');
+    }
+
+    element('probe').addEventListener('click', () => {
+        probe_decoder().catch(error => {
+            set_status(error.message, 'fail');
+
+            console.error(error);
+        });
+    });
+
+    element('run').addEventListener('click', () => {
+        const choice = element('source').value;
+
+        const kind = choice.startsWith('correlated') ? 'correlated'
+            : choice.startsWith('normal') ? 'normal'
+                : choice.startsWith('hdr') ? 'hdr'
+                    : 'independent';
+        const signed = FORMATS[element('format').value]?.signed === true;
+
+        const base = uploaded_source ?? synthetic_source(Number(choice.replace(/[a-z]+/, '')), kind, signed);
+
+        run(base).catch(error => {
+            set_status(error.message, 'fail');
+
+            console.error(error);
+        });
+    });
+
+    element('file').addEventListener('change', async event => {
+        const file = event.target.files[0];
+
+        if (file === undefined) {
+            return;
+        }
+
+        uploaded_source = await file_source(file);
+
+        set_status(`${file.name}: ${uploaded_source.width}x${uploaded_source.height} ready`, 'pass');
+    });
+
+    set_status('ready', 'pass');
+}