@driftengine/assets 4.8.2 → 4.8.4

package/dist/influences.js

@@ -0,0 +1,53 @@
+/**
+ * A vertex's joint influences, sorted, cut to eight and normalised into the two sets a mesh carries.
+ *
+ * **Eight and not four, since 4.8.4.** A rig authored for eight — a face, a shoulder, a hand — loses
+ * the shape of its deformation when the four lightest are dropped, and both importers dropped them.
+ * Heaviest first is the contract the format relies on: the first set always holds the four that
+ * matter most, so a renderer or an older pipeline reading only that set keeps the best four, and
+ * the second set holds what is left. Shared by the glTF and FBX readers so both cut and order the
+ * same way.
+ *
+ * **What it gives up** is anything past eight, renormalised over what is kept, as four was before.
+ * Runs at import, off the frame, so it allocates where that is clearer.
+ */
+/** The most influences a vertex keeps: two sets of four. */
+export const MAX_INFLUENCES = 8;
+const NONE = Object.freeze({ dropped: false, rescaled: false, second: false });
+/**
+ * Write vertex `at`'s influences into `out`, heaviest first: the four heaviest into `joints` and
+ * `weights`, the next four into `joints2` and `weights2`, normalised to sum to one over all kept.
+ * A vertex with no positive weight is left all zero and reported as nothing, because inventing an
+ * influence would move geometry nobody rigged.
+ */
+export function writeInfluences(influences, out, at) {
+    if (influences === undefined || influences.length === 0)
+        return NONE;
+    /* Stable, so equal weights keep the order they arrived in: set 0 before set 1. */
+    const sorted = influences
+        .map((influence, order) => ({ ...influence, order }))
+        .filter((influence) => influence.weight > 0)
+        .sort((a, b) => b.weight - a.weight || a.order - b.order);
+    const kept = sorted.slice(0, MAX_INFLUENCES);
+    let sum = 0;
+    for (const influence of kept)
+        sum += influence.weight;
+    if (sum <= 0)
+        return NONE;
+    for (let i = 0; i < kept.length; i++) {
+        const influence = kept[i];
+        const joints = i < 4 ? out.joints : out.joints2;
+        const weights = i < 4 ? out.weights : out.weights2;
+        joints[at * 4 + (i % 4)] = influence.joint;
+        weights[at * 4 + (i % 4)] = influence.weight / sum;
+    }
+    let total = 0;
+    for (const influence of sorted)
+        total += influence.weight;
+    return {
+        dropped: sorted.length > MAX_INFLUENCES,
+        /* A tenth of a per cent, which is wider than float noise and narrower than an authoring slip. */
+        rescaled: Math.abs(total - 1) > 1e-3,
+        second: kept.length > 4,
+    };
+}

package/dist/weld.js

@@ -52,6 +52,9 @@ const ATTRIBUTES = {
     tangents: 4,
     joints: 4,
     weights: 4,
+    /* The fifth to eighth influences, which are per vertex like the first four. */
+    joints2: 4,
+    weights2: 4,
     /*
      * The four-lane per-vertex channel. It joins the key above as well as the copy below, which is
      * the behaviour that matters: two vertices at one position whose sway or sky exposure differ

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/assets",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "Model readers and the streaming loader for the .drft container",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,11 +27,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.8.2",
-    "@driftengine/texture": "4.8.2"
+    "@driftengine/drft": "4.8.4",
+    "@driftengine/texture": "4.8.4"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.8.2"
+    "@driftengine/core": "4.8.4"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/bc7Decode.ts

@@ -0,0 +1,237 @@
+/**
+ * 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.
+ */
+
+/**
+ * Each mode's layout: subsets, then the bit widths of its partition, rotation, index selection,
+ * colour and alpha fields, whether it has a p-bit per endpoint or one shared per subset, and the
+ * widths of its primary and secondary indices.
+ */
+type Bc7Mode = readonly [
+  subsets: number,
+  partitionBits: number,
+  rotationBits: number,
+  selectionBits: number,
+  colourBits: number,
+  alphaBits: number,
+  endpointP: number,
+  sharedP: number,
+  index1: number,
+  index2: number,
+];
+
+const BC7_MODES: readonly Bc7Mode[] = [
+  [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: readonly (readonly number[])[] = [
+  [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: readonly number[] = [
+  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: readonly number[] = [
+  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: readonly number[] = [
+  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: readonly (readonly number[])[] = [
+  [
+    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: Uint8Array, at: number, pos: number, n: number): number {
+  let value = 0;
+  for (let i = 0; i < n; i++) {
+    const p = pos + i;
+    value |= (((bytes[at + (p >> 3)] as number) >> (p & 7)) & 1) << i;
+  }
+  return value;
+}
+
+/** A quantised endpoint widened to eight bits by replicating its top bits into the bottom. */
+function expandEndpoint(value: number, width: number): number {
+  const shifted = (value << (8 - width)) & 0xff;
+  return shifted | (shifted >> width);
+}
+
+/** The subset and anchor of each pixel, for a partition. */
+function subsetOf(subsets: number, partition: number, pixel: number): number {
+  if (subsets === 2) return ((BC7_PARTITION2[partition] as number) >> pixel) & 1;
+  if (subsets === 3) return ((BC7_PARTITION3[partition] as number) >>> (2 * pixel)) & 3;
+  return 0;
+}
+
+function isAnchor(subsets: number, partition: number, pixel: number): boolean {
+  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: Uint8Array, at: number, out: Uint8Array): void {
+  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] as number;
+      const width = (c < 3 ? colourBits : alphaBits) + (hasP ? 1 : 0);
+      COLOURS[e * 4 + c] = expandEndpoint(
+        hasP ? (stored << 1) | (PBITS[e] as number) : 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] as readonly number[];
+  const weights2 = BC7_WEIGHTS[Math.max(index2, 2) - 2] as readonly number[];
+  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] as number] as number;
+    const second = index2 > 0 ? (weights2[SECONDARY[pixel] as number] as number) : 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] as number) * (64 - w) + (COLOURS[e0 + 4 + c] as number) * 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] as number;
+      out[texel + 3] = out[swap] as number;
+      out[swap] = alpha;
+    }
+  }
+}

package/src/bcAnswer.ts

@@ -0,0 +1,45 @@
+/**
+ * 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';
+
+import { decodeBc } from './bcDecode.ts';
+import { decodeBcImage } from './bcImage.ts';
+
+/** 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 function answerBcRequest(request: BcRequest): BcReply {
+  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 as ArrayBuffer };
+  } catch (error) {
+    return { id: request.id, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/bcDecode.ts

@@ -0,0 +1,218 @@
+/**
+ * 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';
+import { BC_BLOCK_BYTES, DrftError } from '@driftengine/drft';
+
+import { decodeBc7Block } from './bc7Decode.ts';
+
+export type { BcFormat } from '@driftengine/drft';
+
+/** 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: number, at: number): void {
+  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: Uint8Array,
+  at: number,
+  out: Uint8Array,
+  punchthrough: boolean,
+): void {
+  const c0 = (bytes[at] as number) | ((bytes[at + 1] as number) << 8);
+  const c1 = (bytes[at + 2] as number) | ((bytes[at + 3] as number) << 8);
+  expand565(c0, 0);
+  expand565(c1, 4);
+  const four = c0 > c1 || !punchthrough;
+  for (let c = 0; c < 3; c++) {
+    const e0 = PALETTE[c] as number;
+    const e1 = PALETTE[4 + c] as number;
+    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] as number) |
+    ((bytes[at + 5] as number) << 8) |
+    ((bytes[at + 6] as number) << 16) |
+    ((bytes[at + 7] as number) << 24);
+  for (let texel = 0; texel < 16; texel++) {
+    const index = (indices >>> (texel * 2)) & 0x3;
+    out[texel * 4] = PALETTE[index * 4] as number;
+    out[texel * 4 + 1] = PALETTE[index * 4 + 1] as number;
+    out[texel * 4 + 2] = PALETTE[index * 4 + 2] as number;
+    out[texel * 4 + 3] = PALETTE[index * 4 + 3] as number;
+  }
+}
+
+/**
+ * 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: Uint8Array,
+  at: number,
+  out: Uint8Array,
+  stride: number,
+  offset: number,
+): void {
+  const a0 = bytes[at] as number;
+  const a1 = bytes[at + 1] as number;
+  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] as number) |
+    ((bytes[at + 3] as number) << 8) |
+    ((bytes[at + 4] as number) << 16);
+  let high =
+    (bytes[at + 5] as number) |
+    ((bytes[at + 6] as number) << 8) |
+    ((bytes[at + 7] as number) << 16);
+  for (let texel = 0; texel < 8; texel++) {
+    out[texel * stride + offset] = values[low & 0x7] as number;
+    low >>>= 3;
+  }
+  for (let texel = 8; texel < 16; texel++) {
+    out[texel * stride + offset] = values[high & 0x7] as number;
+    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: Uint8Array, at: number, out: Uint8Array): void {
+  for (let texel = 0; texel < 16; texel++) {
+    const byte = bytes[at + (texel >> 1)] as number;
+    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: BcFormat, bytes: Uint8Array, at: number, out: Uint8Array): void {
+  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: BcFormat,
+  width: number,
+  height: number,
+  blocks: Uint8Array,
+  out: Uint8Array = new Uint8Array(width * height * 4),
+): Uint8Array {
+  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] as number;
+          out[to + 1] = texels[from + 1] as number;
+          out[to + 2] = texels[from + 2] as number;
+          out[to + 3] = texels[from + 3] as number;
+        }
+      }
+    }
+  }
+  return out;
+}

package/src/bcFlip.ts

@@ -0,0 +1,55 @@
+/**
+ * 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: Uint8Array): Uint8Array {
+  const out = new Uint8Array(blocks);
+  for (let at = 8; at + 8 <= out.length; at += 16) flipHalf(out, at);
+  return out;
+}
+
+function flipHalf(bytes: Uint8Array, at: number): void {
+  const a0 = bytes[at] as number;
+  const a1 = bytes[at + 1] as number;
+  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] as number) |
+      ((bytes[base + 1] as number) << 8) |
+      ((bytes[base + 2] as number) << 16);
+    let flipped = 0;
+    for (let texel = 0; texel < 8; texel++) {
+      flipped |= (map[run & 7] as number) << (texel * 3);
+      run >>>= 3;
+    }
+    bytes[base] = flipped & 0xff;
+    bytes[base + 1] = (flipped >> 8) & 0xff;
+    bytes[base + 2] = (flipped >> 16) & 0xff;
+  }
+}