@driftengine/assets 4.8.2 → 4.8.4

package/README.md

@@ -2,7 +2,7 @@
 
 Model readers for nine formats — `.blend` among them, read from the file's own DNA — and the streaming loader that uploads them.
 
-**Cost: 22.5 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 26.3 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/bc7Decode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One BC7 block into sixteen RGBA texels, exactly as the format defines it.
+ *
+ * **BC7 is the format to get bit-exact, and the one with no slack.** Eight modes, each a different
+ * split of 128 bits into partitions, endpoints, p-bits and indices; a field read one bit early
+ * shifts every field after it, and the picture that comes out is plausible noise rather than an
+ * error. Unlike BC1 to BC5, its interpolation is specified to the integer, so a decoder either
+ * agrees with the format to the byte or is wrong — `bcDecode.test.ts` holds it to that against an
+ * independent implementation, two random blocks a mode.
+ *
+ * A reserved mode — a first byte with no bit set — decodes to transparent black, which is what the
+ * format says a decoder returns for it.
+ *
+ * **Scratch lives at module scope**, because a phone without BC sampling decodes every block of
+ * every texture through here at load: a 2048² surface is 262,144 calls, and per-call arrays would
+ * be five allocations each. Not re-entrant, which nothing here needs; a worker has its own module.
+ */
+/**
+ * The two-subset partitions, a bit a pixel (pixel 0 lowest), 1 for the second subset.
+ *
+ * The format's own table, as published in the D3D11 BC7 specification; transcribed from
+ * `texture2ddecoder` 0.1.2 (MIT OR Apache-2.0) and held by `bcDecode.test.ts` to what the format
+ * says of it: pixel 0 in subset 0, and every anchor inside the subset it anchors.
+ */
+export declare const BC7_PARTITION2: readonly number[];
+/** The three-subset partitions, two bits a pixel (pixel 0 lowest). From the same source. */
+export declare const BC7_PARTITION3: readonly number[];
+/** The anchor pixel of the second subset of each two-subset partition. From the same source. */
+export declare const BC7_ANCHOR2: readonly number[];
+/** The anchor pixels of the second and third subsets of each three-subset partition. */
+export declare const BC7_ANCHOR3: readonly (readonly number[])[];
+/** One BC7 block at `bytes[at]` into sixteen RGBA texels in `out`. */
+export declare function decodeBc7Block(bytes: Uint8Array, at: number, out: Uint8Array): void;

package/dist/bc7Decode.js

@@ -0,0 +1,197 @@
+/**
+ * One BC7 block into sixteen RGBA texels, exactly as the format defines it.
+ *
+ * **BC7 is the format to get bit-exact, and the one with no slack.** Eight modes, each a different
+ * split of 128 bits into partitions, endpoints, p-bits and indices; a field read one bit early
+ * shifts every field after it, and the picture that comes out is plausible noise rather than an
+ * error. Unlike BC1 to BC5, its interpolation is specified to the integer, so a decoder either
+ * agrees with the format to the byte or is wrong — `bcDecode.test.ts` holds it to that against an
+ * independent implementation, two random blocks a mode.
+ *
+ * A reserved mode — a first byte with no bit set — decodes to transparent black, which is what the
+ * format says a decoder returns for it.
+ *
+ * **Scratch lives at module scope**, because a phone without BC sampling decodes every block of
+ * every texture through here at load: a 2048² surface is 262,144 calls, and per-call arrays would
+ * be five allocations each. Not re-entrant, which nothing here needs; a worker has its own module.
+ */
+const BC7_MODES = [
+    [3, 4, 0, 0, 4, 0, 1, 0, 3, 0],
+    [2, 6, 0, 0, 6, 0, 0, 1, 3, 0],
+    [3, 6, 0, 0, 5, 0, 0, 0, 2, 0],
+    [2, 6, 0, 0, 7, 0, 1, 0, 2, 0],
+    [1, 0, 2, 1, 5, 6, 0, 0, 2, 3],
+    [1, 0, 2, 0, 7, 8, 0, 0, 2, 2],
+    [1, 0, 0, 0, 7, 7, 1, 0, 4, 0],
+    [2, 6, 0, 0, 5, 5, 1, 0, 2, 0],
+];
+/** Interpolation weights out of 64, for two-, three- and four-bit indices. */
+const BC7_WEIGHTS = [
+    [0, 21, 43, 64],
+    [0, 9, 18, 27, 37, 46, 55, 64],
+    [0, 4, 9, 13, 17, 21, 26, 30, 34, 38, 43, 47, 51, 55, 60, 64],
+];
+/**
+ * The two-subset partitions, a bit a pixel (pixel 0 lowest), 1 for the second subset.
+ *
+ * The format's own table, as published in the D3D11 BC7 specification; transcribed from
+ * `texture2ddecoder` 0.1.2 (MIT OR Apache-2.0) and held by `bcDecode.test.ts` to what the format
+ * says of it: pixel 0 in subset 0, and every anchor inside the subset it anchors.
+ */
+export const BC7_PARTITION2 = [
+    0xcccc, 0x8888, 0xeeee, 0xecc8, 0xc880, 0xfeec, 0xfec8, 0xec80, 0xc800, 0xffec, 0xfe80, 0xe800,
+    0xffe8, 0xff00, 0xfff0, 0xf000, 0xf710, 0x008e, 0x7100, 0x08ce, 0x008c, 0x7310, 0x3100, 0x8cce,
+    0x088c, 0x3110, 0x6666, 0x366c, 0x17e8, 0x0ff0, 0x718e, 0x399c, 0xaaaa, 0xf0f0, 0x5a5a, 0x33cc,
+    0x3c3c, 0x55aa, 0x9696, 0xa55a, 0x73ce, 0x13c8, 0x324c, 0x3bdc, 0x6996, 0xc33c, 0x9966, 0x0660,
+    0x0272, 0x04e4, 0x4e40, 0x2720, 0xc936, 0x936c, 0x39c6, 0x639c, 0x9336, 0x9cc6, 0x817e, 0xe718,
+    0xccf0, 0x0fcc, 0x7744, 0xee22,
+];
+/** The three-subset partitions, two bits a pixel (pixel 0 lowest). From the same source. */
+export const BC7_PARTITION3 = [
+    0xaa685050, 0x6a5a5040, 0x5a5a4200, 0x5450a0a8, 0xa5a50000, 0xa0a05050, 0x5555a0a0, 0x5a5a5050,
+    0xaa550000, 0xaa555500, 0xaaaa5500, 0x90909090, 0x94949494, 0xa4a4a4a4, 0xa9a59450, 0x2a0a4250,
+    0xa5945040, 0x0a425054, 0xa5a5a500, 0x55a0a0a0, 0xa8a85454, 0x6a6a4040, 0xa4a45000, 0x1a1a0500,
+    0x0050a4a4, 0xaaa59090, 0x14696914, 0x69691400, 0xa08585a0, 0xaa821414, 0x50a4a450, 0x6a5a0200,
+    0xa9a58000, 0x5090a0a8, 0xa8a09050, 0x24242424, 0x00aa5500, 0x24924924, 0x24499224, 0x50a50a50,
+    0x500aa550, 0xaaaa4444, 0x66660000, 0xa5a0a5a0, 0x50a050a0, 0x69286928, 0x44aaaa44, 0x66666600,
+    0xaa444444, 0x54a854a8, 0x95809580, 0x96969600, 0xa85454a8, 0x80959580, 0xaa141414, 0x96960000,
+    0xaaaa1414, 0xa05050a0, 0xa0a5a5a0, 0x96000000, 0x40804080, 0xa9a8a9a8, 0xaaaaaa44, 0x2a4a5254,
+];
+/** The anchor pixel of the second subset of each two-subset partition. From the same source. */
+export const BC7_ANCHOR2 = [
+    15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 15, 2, 8, 2, 2, 8, 8, 15, 2, 8, 2,
+    2, 8, 8, 2, 2, 15, 15, 6, 8, 2, 8, 15, 15, 2, 8, 2, 2, 2, 15, 15, 6, 6, 2, 6, 8, 15, 15, 2, 2, 15,
+    15, 15, 15, 15, 2, 2, 15,
+];
+/** The anchor pixels of the second and third subsets of each three-subset partition. */
+export const BC7_ANCHOR3 = [
+    [
+        3, 3, 15, 15, 8, 3, 15, 15, 8, 8, 6, 6, 6, 5, 3, 3, 3, 3, 8, 15, 3, 3, 6, 10, 5, 8, 8, 6, 8, 5,
+        15, 15, 8, 15, 3, 5, 6, 10, 8, 15, 15, 3, 15, 5, 15, 15, 15, 15, 3, 15, 5, 5, 5, 8, 5, 10, 5,
+        10, 8, 13, 15, 12, 3, 3,
+    ],
+    [
+        15, 8, 8, 3, 15, 15, 3, 8, 15, 15, 15, 15, 15, 15, 15, 8, 15, 8, 15, 3, 15, 8, 15, 8, 3, 15, 6,
+        10, 15, 15, 10, 8, 15, 3, 15, 10, 10, 8, 9, 10, 6, 15, 8, 15, 3, 6, 6, 8, 15, 3, 15, 15, 15, 15,
+        15, 15, 15, 15, 15, 15, 3, 15, 15, 8,
+    ],
+];
+/** `n` bits of a block from bit `pos`, least significant first, as the format orders them. */
+function bits(bytes, at, pos, n) {
+    let value = 0;
+    for (let i = 0; i < n; i++) {
+        const p = pos + i;
+        value |= ((bytes[at + (p >> 3)] >> (p & 7)) & 1) << i;
+    }
+    return value;
+}
+/** A quantised endpoint widened to eight bits by replicating its top bits into the bottom. */
+function expandEndpoint(value, width) {
+    const shifted = (value << (8 - width)) & 0xff;
+    return shifted | (shifted >> width);
+}
+/** The subset and anchor of each pixel, for a partition. */
+function subsetOf(subsets, partition, pixel) {
+    if (subsets === 2)
+        return (BC7_PARTITION2[partition] >> pixel) & 1;
+    if (subsets === 3)
+        return (BC7_PARTITION3[partition] >>> (2 * pixel)) & 3;
+    return 0;
+}
+function isAnchor(subsets, partition, pixel) {
+    if (pixel === 0)
+        return true;
+    if (subsets === 2)
+        return BC7_ANCHOR2[partition] === pixel;
+    if (subsets === 3) {
+        return BC7_ANCHOR3[0]?.[partition] === pixel || BC7_ANCHOR3[1]?.[partition] === pixel;
+    }
+    return false;
+}
+const RAW = new Uint8Array(24);
+const PBITS = new Uint8Array(6);
+const COLOURS = new Uint8Array(24);
+const PRIMARY = new Uint8Array(16);
+const SECONDARY = new Uint8Array(16);
+/** One BC7 block at `bytes[at]` into sixteen RGBA texels in `out`. */
+export function decodeBc7Block(bytes, at, out) {
+    let mode = 0;
+    while (mode < 8 && bits(bytes, at, mode, 1) === 0)
+        mode++;
+    const layout = BC7_MODES[mode];
+    if (layout === undefined) {
+        out.fill(0, 0, 64);
+        return;
+    }
+    const [subsets, partitionBits, rotationBits, selectionBits, colourBits, alphaBits, endpointP, sharedP, index1, index2,] = layout;
+    let pos = mode + 1;
+    const partition = bits(bytes, at, pos, partitionBits);
+    pos += partitionBits;
+    const rotation = bits(bytes, at, pos, rotationBits);
+    pos += rotationBits;
+    const selection = bits(bytes, at, pos, selectionBits);
+    pos += selectionBits;
+    /* Endpoints channel by channel, two per subset: red for every subset, then green, blue, alpha. */
+    const endpoints = 2 * subsets;
+    const channels = alphaBits > 0 ? 4 : 3;
+    for (let c = 0; c < channels; c++) {
+        const width = c < 3 ? colourBits : alphaBits;
+        for (let e = 0; e < endpoints; e++) {
+            RAW[e * 4 + c] = bits(bytes, at, pos, width);
+            pos += width;
+        }
+    }
+    /* P-bits: one per endpoint, or one per subset shared by its two, appended below each value. */
+    const hasP = endpointP !== 0 || sharedP !== 0;
+    for (let e = 0; e < endpoints; e++) {
+        if (endpointP !== 0)
+            PBITS[e] = bits(bytes, at, pos++, 1);
+        else if (sharedP !== 0 && e % 2 === 0)
+            PBITS[e] = PBITS[e + 1] = bits(bytes, at, pos++, 1);
+    }
+    for (let e = 0; e < endpoints; e++) {
+        for (let c = 0; c < 4; c++) {
+            if (c === 3 && alphaBits === 0) {
+                COLOURS[e * 4 + 3] = 255;
+                continue;
+            }
+            const stored = RAW[e * 4 + c];
+            const width = (c < 3 ? colourBits : alphaBits) + (hasP ? 1 : 0);
+            COLOURS[e * 4 + c] = expandEndpoint(hasP ? (stored << 1) | PBITS[e] : stored, width);
+        }
+    }
+    /* Indices: primary for all sixteen pixels, each anchor one bit short; then secondary, if any. */
+    for (let pixel = 0; pixel < 16; pixel++) {
+        const width = index1 - (isAnchor(subsets, partition, pixel) ? 1 : 0);
+        PRIMARY[pixel] = bits(bytes, at, pos, width);
+        pos += width;
+    }
+    for (let pixel = 0; index2 > 0 && pixel < 16; pixel++) {
+        const width = index2 - (pixel === 0 ? 1 : 0);
+        SECONDARY[pixel] = bits(bytes, at, pos, width);
+        pos += width;
+    }
+    const weights1 = BC7_WEIGHTS[index1 - 2];
+    const weights2 = BC7_WEIGHTS[Math.max(index2, 2) - 2];
+    for (let pixel = 0; pixel < 16; pixel++) {
+        /* One index for both unless the mode has two; mode 4's selection bit says which drives alpha. */
+        const first = weights1[PRIMARY[pixel]];
+        const second = index2 > 0 ? weights2[SECONDARY[pixel]] : first;
+        const colourWeight = selection === 0 ? first : second;
+        const alphaWeight = selection === 0 ? second : first;
+        const e0 = subsetOf(subsets, partition, pixel) * 8;
+        const texel = pixel * 4;
+        for (let c = 0; c < 4; c++) {
+            const w = c < 3 ? colourWeight : alphaWeight;
+            out[texel + c] =
+                (COLOURS[e0 + c] * (64 - w) + COLOURS[e0 + 4 + c] * w + 32) >> 6;
+        }
+        /* Rotation: the stored alpha was one of the colour channels, and that channel was alpha. */
+        if (rotation !== 0) {
+            const swap = texel + rotation - 1;
+            const alpha = out[texel + 3];
+            out[texel + 3] = out[swap];
+            out[swap] = alpha;
+        }
+    }
+}

package/dist/bcAnswer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The BC worker's whole job, as a function: one request's level 0 decoded, or the reason it could
+ * not be. Its own module so the worker imports the decoders and nothing else — not the loader, and
+ * not the engine's barrel behind it.
+ *
+ * Decoded **as a GPU samples it** for the loader's own textures, so a decode at load looks like an
+ * upload of the same blocks: BC4 red alone, BC5 red and green, the lit shader rebuilding a normal's
+ * z either way. Decoded **as an ordinary image** (`asImage`) for a consumer taking images through
+ * `onImage`, who builds textures the engine does not see. An error is answered rather than thrown,
+ * so one bad texture fails on its own and the worker lives on.
+ */
+import type { BcFormat } from '@driftengine/drft';
+/** What the loader asks the worker: one level's blocks, handed over as a buffer of their own. */
+export interface BcRequest {
+    readonly id: number;
+    readonly format: BcFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly blocks: ArrayBuffer;
+    readonly asImage: boolean;
+}
+/** The answer: RGBA, eight bits a channel, or why not. */
+export interface BcReply {
+    readonly id: number;
+    readonly rgba?: ArrayBuffer;
+    readonly error?: string;
+}
+export declare function answerBcRequest(request: BcRequest): BcReply;

package/dist/bcAnswer.js

@@ -0,0 +1,15 @@
+import { decodeBc } from './bcDecode.js';
+import { decodeBcImage } from './bcImage.js';
+export function answerBcRequest(request) {
+    try {
+        const blocks = new Uint8Array(request.blocks);
+        const { format, width, height } = request;
+        const rgba = request.asImage
+            ? decodeBcImage(format, width, height, blocks)
+            : decodeBc(format, width, height, blocks);
+        return { id: request.id, rgba: rgba.buffer };
+    }
+    catch (error) {
+        return { id: request.id, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/bcDecode.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Block-compressed texels to RGBA: BC1, BC2, BC3, BC4, BC5 and BC7.
+ *
+ * **Two callers, one decoder.** The baker turns a DDS it is told to re-encode into RGBA here, and the
+ * loader decodes a container's BC payload here on a device that cannot sample the format — most
+ * phones, which have ASTC and ETC2 instead. Both must read a block the same way, so the block
+ * routines live in one place rather than in the DDS reader that grew them first.
+ *
+ * **What a channel the format does not store reads as** is what a GPU returns for it, so a texture
+ * looks the same whether it was uploaded compressed or decoded here: BC4 is `(r, 0, 0, 255)` and BC5
+ * `(r, g, 0, 255)`. A BC5 normal map therefore arrives with blue at zero on both paths, and the lit
+ * shader rebuilds z from the two it has.
+ *
+ * **What it gives up.** BC1 to BC5 interpolants are rounded here where some decoders truncate, so a
+ * texel may differ by one from another decoder's; the format allows either, and hardware differs too.
+ * BC7 is defined exactly and decodes to the byte, in `bc7Decode.ts`.
+ *
+ * Runs off the frame, in the baker or the loader's worker, but a phone decodes every block of every
+ * texture through here at load, so the per-block scratch lives at module scope.
+ */
+import type { BcFormat } from '@driftengine/drft';
+export type { BcFormat } from '@driftengine/drft';
+/**
+ * A whole surface of blocks into RGBA, eight bits a channel, `width` by `height`. A surface that is
+ * not a whole number of blocks is decoded block by block and cropped, which is what the format does:
+ * the blocks cover a padded rectangle and the texels past the declared size are padding.
+ */
+export declare function decodeBc(format: BcFormat, width: number, height: number, blocks: Uint8Array, out?: Uint8Array): Uint8Array;

package/dist/bcDecode.js

@@ -0,0 +1,175 @@
+import { BC_BLOCK_BYTES, DrftError } from '@driftengine/drft';
+import { decodeBc7Block } from './bc7Decode.js';
+/** A colour block's four entries, and a BC4 block's eight values, rewritten for every block. */
+const PALETTE = new Uint8Array(16);
+const VALUES = new Uint8Array(8);
+const TEXELS = new Uint8Array(64);
+/** RGB565 into the palette at `at`, opaque, with the low bits replicated so white stays white. */
+function expand565(value, at) {
+    const r = (value >> 11) & 0x1f;
+    const g = (value >> 5) & 0x3f;
+    const b = value & 0x1f;
+    PALETTE[at] = (r << 3) | (r >> 2);
+    PALETTE[at + 1] = (g << 2) | (g >> 4);
+    PALETTE[at + 2] = (b << 3) | (b >> 2);
+    PALETTE[at + 3] = 255;
+}
+/**
+ * One BC1 colour block into sixteen RGBA texels.
+ *
+ * **The endpoint comparison chooses the mode and is the thing to get right.** With `c0 > c1` the
+ * block has four opaque colours; otherwise it has three and its fourth index is transparent black.
+ * A decoder that always takes the first branch produces an image that looks correct until
+ * something relies on the punch-through alpha, which for foliage and grilles is everything.
+ *
+ * `punchthrough` is false for BC2 and BC3, whatever the endpoint order: those carry alpha in their
+ * own half of the block, so there is no index left over to mean transparent and the colour half is
+ * always the four-colour opaque mode. That was a real defect once: reached unconditionally, a BC3
+ * block written with `c0 <= c1` decoded its fourth index to transparent black — invisible in most
+ * real data, because an encoder has no reason to order the endpoints the low way round.
+ */
+function decodeColourBlock(bytes, at, out, punchthrough) {
+    const c0 = bytes[at] | (bytes[at + 1] << 8);
+    const c1 = bytes[at + 2] | (bytes[at + 3] << 8);
+    expand565(c0, 0);
+    expand565(c1, 4);
+    const four = c0 > c1 || !punchthrough;
+    for (let c = 0; c < 3; c++) {
+        const e0 = PALETTE[c];
+        const e1 = PALETTE[4 + c];
+        PALETTE[8 + c] = four ? Math.round((2 * e0 + e1) / 3) : Math.round((e0 + e1) / 2);
+        PALETTE[12 + c] = four ? Math.round((e0 + 2 * e1) / 3) : 0;
+    }
+    PALETTE[11] = 255;
+    PALETTE[15] = four ? 255 : 0;
+    const indices = bytes[at + 4] |
+        (bytes[at + 5] << 8) |
+        (bytes[at + 6] << 16) |
+        (bytes[at + 7] << 24);
+    for (let texel = 0; texel < 16; texel++) {
+        const index = (indices >>> (texel * 2)) & 0x3;
+        out[texel * 4] = PALETTE[index * 4];
+        out[texel * 4 + 1] = PALETTE[index * 4 + 1];
+        out[texel * 4 + 2] = PALETTE[index * 4 + 2];
+        out[texel * 4 + 3] = PALETTE[index * 4 + 3];
+    }
+}
+/**
+ * One BC4-style eight-value block, which is what BC3's alpha and both halves of BC5 are, written
+ * into channel `offset` of each texel `stride` bytes apart.
+ *
+ * The same endpoint comparison as the colour block: with `a0 > a1` there are six interpolants, and
+ * otherwise four plus a hard 0 and 255.
+ */
+function decodeAlphaBlock(bytes, at, out, stride, offset) {
+    const a0 = bytes[at];
+    const a1 = bytes[at + 1];
+    const values = VALUES;
+    values[0] = a0;
+    values[1] = a1;
+    if (a0 > a1) {
+        for (let i = 1; i <= 6; i++)
+            values[i + 1] = Math.round(((7 - i) * a0 + i * a1) / 7);
+    }
+    else {
+        for (let i = 1; i <= 4; i++)
+            values[i + 1] = Math.round(((5 - i) * a0 + i * a1) / 5);
+        values[6] = 0;
+        values[7] = 255;
+    }
+    /* Six bytes of 3-bit indices, least significant first, as one 48-bit run. */
+    let low = bytes[at + 2] |
+        (bytes[at + 3] << 8) |
+        (bytes[at + 4] << 16);
+    let high = bytes[at + 5] |
+        (bytes[at + 6] << 8) |
+        (bytes[at + 7] << 16);
+    for (let texel = 0; texel < 8; texel++) {
+        out[texel * stride + offset] = values[low & 0x7];
+        low >>>= 3;
+    }
+    for (let texel = 8; texel < 16; texel++) {
+        out[texel * stride + offset] = values[high & 0x7];
+        high >>>= 3;
+    }
+}
+/**
+ * BC2's alpha: eight bytes of explicit four-bit values, one nibble a texel, low nibble first.
+ *
+ * Scaled by *replication* rather than by a shift: `0xF` has to come out 255 and not 240, or a texel
+ * the author wrote as fully opaque arrives at 94% and every alpha test sees a different picture.
+ */
+function decodeExplicitAlpha(bytes, at, out) {
+    for (let texel = 0; texel < 16; texel++) {
+        const byte = bytes[at + (texel >> 1)];
+        const nibble = texel % 2 === 0 ? byte & 0xf : byte >> 4;
+        out[texel * 4 + 3] = nibble * 17;
+    }
+}
+/** One block of any format into sixteen RGBA texels. */
+function decodeBlock(format, bytes, at, out) {
+    out.fill(0, 0, 64);
+    if (format === 'bc1') {
+        decodeColourBlock(bytes, at, out, true);
+    }
+    else if (format === 'bc2') {
+        decodeColourBlock(bytes, at + 8, out, false);
+        decodeExplicitAlpha(bytes, at, out);
+    }
+    else if (format === 'bc3') {
+        decodeColourBlock(bytes, at + 8, out, false);
+        decodeAlphaBlock(bytes, at, out, 4, 3);
+    }
+    else if (format === 'bc4') {
+        decodeAlphaBlock(bytes, at, out, 4, 0);
+        for (let t = 0; t < 16; t++)
+            out[t * 4 + 3] = 255;
+    }
+    else if (format === 'bc5') {
+        decodeAlphaBlock(bytes, at, out, 4, 0);
+        decodeAlphaBlock(bytes, at + 8, out, 4, 1);
+        for (let t = 0; t < 16; t++)
+            out[t * 4 + 3] = 255;
+    }
+    else {
+        decodeBc7Block(bytes, at, out);
+    }
+}
+/**
+ * A whole surface of blocks into RGBA, eight bits a channel, `width` by `height`. A surface that is
+ * not a whole number of blocks is decoded block by block and cropped, which is what the format does:
+ * the blocks cover a padded rectangle and the texels past the declared size are padding.
+ */
+export function decodeBc(format, width, height, blocks, out = new Uint8Array(width * height * 4)) {
+    const blockBytes = BC_BLOCK_BYTES[format];
+    const across = Math.max(1, Math.ceil(width / 4));
+    const down = Math.max(1, Math.ceil(height / 4));
+    const needed = across * down * blockBytes;
+    if (blocks.length < needed) {
+        throw new DrftError(`bc: a ${width}x${height} ${format.toUpperCase()} surface needs ${needed} bytes of blocks and ` +
+            `${blocks.length} were given`);
+    }
+    const texels = TEXELS;
+    for (let by = 0; by < down; by++) {
+        for (let bx = 0; bx < across; bx++) {
+            decodeBlock(format, blocks, (by * across + bx) * blockBytes, texels);
+            for (let ty = 0; ty < 4; ty++) {
+                const y = by * 4 + ty;
+                if (y >= height)
+                    break;
+                for (let tx = 0; tx < 4; tx++) {
+                    const x = bx * 4 + tx;
+                    if (x >= width)
+                        break;
+                    const from = (ty * 4 + tx) * 4;
+                    const to = (y * width + x) * 4;
+                    out[to] = texels[from];
+                    out[to + 1] = texels[from + 1];
+                    out[to + 2] = texels[from + 2];
+                    out[to + 3] = texels[from + 3];
+                }
+            }
+        }
+    }
+    return out;
+}

package/dist/bcFlip.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A BC5 normal map's green turned over in its blocks — `255 − g` at every texel — without decoding.
+ *
+ * **Why in the blocks.** A DirectX normal map points green down where glTF points it up, and the
+ * baker turns such a map over on the way in. For a PNG that is a pass over the texels; for BC5 the
+ * same pass would mean decoding and re-encoding, and this engine has no encoder — so the map would
+ * leave the bake uncompressed, and BC5 is what normal maps are stored as. Turning a BC4 half over
+ * is exact in its own terms instead: swap the two endpoints and turn each over, then renumber the
+ * indices so each texel names the value that is now its opposite.
+ *
+ * **Swapping keeps the mode**, which is the point of swapping: `a0 > a1` selects six interpolants
+ * and `a0 ≤ a1` four plus a hard 0 and 255, and `255 − a1 > 255 − a0` exactly when `a0 > a1`.
+ * Within a mode, index `i` of the interpolants counts from the first endpoint, so it becomes the
+ * one counting the same distance from the other end; the hard 0 and 255 trade places.
+ *
+ * **What it gives up**: an interpolant that falls on a half rounds the same way both before and
+ * after, so a texel at such a value lands one away from `255 − g`. That is inside the error the
+ * format already carries. Runs in the baker, so it copies.
+ */
+/** A copy of `blocks`, a level of BC5, with every block's green half turned over. */
+export declare function flipBc5Green(blocks: Uint8Array): Uint8Array;

package/dist/bcFlip.js

@@ -0,0 +1,52 @@
+/**
+ * A BC5 normal map's green turned over in its blocks — `255 − g` at every texel — without decoding.
+ *
+ * **Why in the blocks.** A DirectX normal map points green down where glTF points it up, and the
+ * baker turns such a map over on the way in. For a PNG that is a pass over the texels; for BC5 the
+ * same pass would mean decoding and re-encoding, and this engine has no encoder — so the map would
+ * leave the bake uncompressed, and BC5 is what normal maps are stored as. Turning a BC4 half over
+ * is exact in its own terms instead: swap the two endpoints and turn each over, then renumber the
+ * indices so each texel names the value that is now its opposite.
+ *
+ * **Swapping keeps the mode**, which is the point of swapping: `a0 > a1` selects six interpolants
+ * and `a0 ≤ a1` four plus a hard 0 and 255, and `255 − a1 > 255 − a0` exactly when `a0 > a1`.
+ * Within a mode, index `i` of the interpolants counts from the first endpoint, so it becomes the
+ * one counting the same distance from the other end; the hard 0 and 255 trade places.
+ *
+ * **What it gives up**: an interpolant that falls on a half rounds the same way both before and
+ * after, so a texel at such a value lands one away from `255 − g`. That is inside the error the
+ * format already carries. Runs in the baker, so it copies.
+ */
+/** Six-value mode: endpoints trade places, interpolant `i` becomes `9 − i`. */
+const SIX = [1, 0, 7, 6, 5, 4, 3, 2];
+/** Four-value mode: endpoints trade, interpolant `i` becomes `7 − i`, and 0 and 255 trade. */
+const FOUR = [1, 0, 5, 4, 3, 2, 7, 6];
+/** A copy of `blocks`, a level of BC5, with every block's green half turned over. */
+export function flipBc5Green(blocks) {
+    const out = new Uint8Array(blocks);
+    for (let at = 8; at + 8 <= out.length; at += 16)
+        flipHalf(out, at);
+    return out;
+}
+function flipHalf(bytes, at) {
+    const a0 = bytes[at];
+    const a1 = bytes[at + 1];
+    const map = a0 > a1 ? SIX : FOUR;
+    bytes[at] = 255 - a1;
+    bytes[at + 1] = 255 - a0;
+    /* Sixteen three-bit indices in two 24-bit runs, least significant first. */
+    for (let half = 0; half < 2; half++) {
+        const base = at + 2 + half * 3;
+        let run = bytes[base] |
+            (bytes[base + 1] << 8) |
+            (bytes[base + 2] << 16);
+        let flipped = 0;
+        for (let texel = 0; texel < 8; texel++) {
+            flipped |= map[run & 7] << (texel * 3);
+            run >>>= 3;
+        }
+        bytes[base] = flipped & 0xff;
+        bytes[base + 1] = (flipped >> 8) & 0xff;
+        bytes[base + 2] = (flipped >> 16) & 0xff;
+    }
+}

package/dist/bcImage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Block-compressed texels decoded into an ordinary image: what a PNG of them has to hold.
+ *
+ * **Not what a GPU samples, on purpose.** `decodeBc` returns what a device would — BC4 as red alone,
+ * BC5 as red and green with blue at zero — because the loader's fallback must look like a compressed
+ * upload. A baked image is read later as an image, by a slot that reads three channels, so the two
+ * formats that store fewer are completed here: BC4's one value fills all three, as a luminance
+ * surface does, and BC5's missing z is rebuilt from the two it has.
+ *
+ * Shared by the DDS reader and the baker's texture pass, which decode the same blocks for the same
+ * reason. Runs in the baker, so it allocates the image it returns.
+ */
+import type { BcFormat } from '@driftengine/drft';
+/** `blocks` as an RGBA image, eight bits a channel, every channel meaning what an image's does. */
+export declare function decodeBcImage(format: BcFormat, width: number, height: number, blocks: Uint8Array): Uint8Array;

package/dist/bcImage.js

@@ -0,0 +1,38 @@
+import { decodeBc } from './bcDecode.js';
+/** `blocks` as an RGBA image, eight bits a channel, every channel meaning what an image's does. */
+export function decodeBcImage(format, width, height, blocks) {
+    const rgba = decodeBc(format, width, height, blocks);
+    if (format === 'bc5')
+        rebuildNormalZ(rgba);
+    if (format === 'bc4')
+        greyFromRed(rgba);
+    return rgba;
+}
+/**
+ * BC5 is two BC4 blocks, red then green, and it is how a normal map is stored: x and y, with z
+ * implied by the normal's unit length. **A baked image has three channels and the lit shader reads
+ * three**, so z is rebuilt here as `(√(1 − x² − y²) + 1) / 2`. Until 4.8.4 the DDS reader said z
+ * belonged in the shader that consumes the map, and no shader rebuilt it: every BC5 normal map baked
+ * to PNG arrived with blue at zero, a normal lying in the surface it was meant to stand out of.
+ *
+ * Outside the unit disc — compression error at a grazing normal — z is clamped to zero rather than
+ * reflected, which would turn the normal back to face the viewer.
+ *
+ * What it gives up: a BC5 surface that is not a normal map gets a blue channel derived as though it
+ * were. Red and green are untouched, so anything reading the two channels it stored loses nothing.
+ */
+function rebuildNormalZ(rgba) {
+    for (let at = 0; at < rgba.length; at += 4) {
+        const x = (rgba[at] / 255) * 2 - 1;
+        const y = (rgba[at + 1] / 255) * 2 - 1;
+        const z = Math.sqrt(Math.max(0, 1 - x * x - y * y));
+        rgba[at + 2] = Math.round((z * 0.5 + 0.5) * 255);
+    }
+}
+/** BC4 is one channel, and a one-channel image is grey. */
+function greyFromRed(rgba) {
+    for (let at = 0; at < rgba.length; at += 4) {
+        rgba[at + 1] = rgba[at];
+        rgba[at + 2] = rgba[at];
+    }
+}

package/dist/bcLoad.d.ts

@@ -0,0 +1,26 @@
+import type { CompressedTextureFormat } from '@driftengine/core';
+import type { BcImage } from '@driftengine/drft';
+import type { BcRequest } from './bcAnswer.ts';
+export type { BcReply, BcRequest } from './bcAnswer.ts';
+export { answerBcRequest } from './bcAnswer.ts';
+/** What happens to one BC texture. */
+export type BcPlan = 'blocks' | 'decode';
+/** Blocks where this device takes the format in the colour space the slot reads, with a chain. */
+export declare function bcPlan(image: BcImage, srgb: boolean, available: readonly CompressedTextureFormat[]): BcPlan;
+/** The part of a worker the decoder uses. A browser `Worker` satisfies it. */
+export interface BcWorker {
+    postMessage(request: BcRequest, transfer?: Transferable[]): void;
+    terminate(): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror?: ((event: unknown) => void) | null;
+}
+/** Level 0 of a BC image decoded to RGBA, off the main thread where one is to be had. */
+export interface BcDecoder {
+    decode(image: BcImage, asImage: boolean): Promise<Uint8Array>;
+    /** Empty while a worker decodes; otherwise why the main thread does. */
+    readonly reason: string;
+    dispose(): void;
+}
+export declare function createBcDecoder(spawn?: (() => BcWorker) | null): BcDecoder;