@driftengine/assets 4.8.3 → 4.8.5

package/dist/bcLoad.js

@@ -0,0 +1,113 @@
+/**
+ * BC textures as the loader receives them: which go up as their blocks, and the decode of the rest
+ * off the main thread.
+ *
+ * **Blocks where the device takes them**, through `uploadsCompressed`, and only with a chain: no
+ * chain can be generated for blocks on the device, and a large texture with no mips crawls at a
+ * distance, so a single stored level is decoded and given generated mips instead. **Decoded
+ * otherwise**, which on a phone is every BC texture: in a worker, because a 2048² BC7 image is
+ * 262,144 blocks and a phone's main thread spends the better part of a second on them.
+ *
+ * **Never silently slower.** Where there is no `Worker`, or the one this module starts fails to
+ * load — a bundler that does not understand `new Worker(new URL(…))` — the decode moves to the main
+ * thread and `reason` says so, and the loader prints it once. A request in flight when the worker
+ * fails is decoded again there rather than left waiting.
+ */
+import { uploadsCompressed } from '@driftengine/core';
+import { answerBcRequest } from './bcAnswer.js';
+export { answerBcRequest } from './bcAnswer.js';
+/** Blocks where this device takes the format in the colour space the slot reads, with a chain. */
+export function bcPlan(image, srgb, available) {
+    const chained = image.levels.length > 1 || Math.max(image.width, image.height) <= 4;
+    return chained && uploadsCompressed(image.format, srgb, image.width, image.height, available)
+        ? 'blocks'
+        : 'decode';
+}
+function request(id, image, asImage) {
+    /* A copy, so the transfer detaches nothing the loader still holds: a level is a view over the
+       fetched file, and every other view over that file would read as empty afterwards. */
+    const blocks = image.levels[0].slice().buffer;
+    return { id, format: image.format, width: image.width, height: image.height, blocks, asImage };
+}
+function settle(reply, pending) {
+    if (reply.rgba !== undefined)
+        pending.resolve(new Uint8Array(reply.rgba));
+    else
+        pending.reject(new Error(reply.error ?? 'bc: the decode answered nothing'));
+}
+/**
+ * The worker this package ships, built the way a bundler understands, or null where there is no
+ * `Worker` at all. `createBcDecoder`'s `spawn` is the way past either.
+ */
+const defaultSpawn = 
+// platform: feature probe — no `Worker` means BC decodes on the main thread, with a reason
+typeof Worker === 'undefined'
+    ? null
+    : () => 
+    // platform: browser default — `createBcDecoder(spawn)` is the seam a host supplies
+    new Worker(new URL('./bcWorker.js', import.meta.url), {
+        type: 'module',
+    });
+export function createBcDecoder(spawn = defaultSpawn) {
+    let worker = null;
+    let reason = '';
+    const pending = new Map();
+    let next = 0;
+    const onMainThread = (why) => {
+        reason = `BC textures decode on the main thread: ${why}`;
+        worker?.terminate();
+        worker = null;
+        for (const [id, waiting] of pending)
+            settle(answerBcRequest(request(id, waiting.image, waiting.asImage)), waiting);
+        pending.clear();
+    };
+    if (spawn === null) {
+        reason = 'BC textures decode on the main thread: this runtime has no Worker';
+    }
+    else {
+        try {
+            worker = spawn();
+            worker.onmessage = (event) => {
+                const reply = event.data;
+                const waiting = pending.get(reply.id);
+                if (waiting === undefined)
+                    return;
+                pending.delete(reply.id);
+                settle(reply, waiting);
+            };
+            worker.onerror = (event) => {
+                const message = event?.message;
+                onMainThread(`the worker failed (${typeof message === 'string' ? message : 'no message'})`);
+            };
+        }
+        catch (error) {
+            onMainThread(`the worker would not start (${error instanceof Error ? error.message : String(error)})`);
+        }
+    }
+    return {
+        get reason() {
+            return reason;
+        },
+        decode(image, asImage) {
+            const id = next++;
+            const target = worker;
+            if (target === null) {
+                return new Promise((resolve, reject) => {
+                    settle(answerBcRequest(request(id, image, asImage)), { image, asImage, resolve, reject });
+                });
+            }
+            return new Promise((resolve, reject) => {
+                pending.set(id, { image, asImage, resolve, reject });
+                const message = request(id, image, asImage);
+                target.postMessage(message, [message.blocks]);
+            });
+        },
+        dispose() {
+            worker?.terminate();
+            worker = null;
+            for (const waiting of pending.values())
+                waiting.reject(new Error('bc: the decoder was disposed'));
+            pending.clear();
+        },
+    };
+}

package/dist/bcWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bcWorker.js

@@ -0,0 +1,14 @@
+/**
+ * The worker `bcLoad.ts` starts: decodes BC blocks off the main thread, one request at a time, and
+ * hands each image back rather than copying it. Imports `bcAnswer.ts` alone, so its bundle is the
+ * decoders and nothing else.
+ *
+ * No top-level await, for the reason `islandWorker.ts` gives: a consumer's bundler compiles every
+ * `new Worker(new URL(…))` it finds, and an IIFE worker cannot carry one.
+ */
+import { answerBcRequest } from './bcAnswer.js';
+const scope = globalThis;
+scope.onmessage = (event) => {
+    const reply = answerBcRequest(event.data);
+    scope.postMessage(reply, reply.rgba === undefined ? [] : [reply.rgba]);
+};

package/dist/dds.d.ts

@@ -1,20 +1,16 @@
 /**
- * DDS surfaces to RGBA: BC1, BC2, BC3 and BC5 in either header spelling, and the uncompressed
- * layouts, by the masks their own header carries.
+ * DDS surfaces to RGBA: BC1 to BC5 and BC7 in either header spelling, and the uncompressed layouts,
+ * by the masks their own header carries.
  *
  * **It exists because a third of a shipped vehicle's textures are in it.** The car this was built
  * against carries 81 textures and 34 of them are DDS — 25 DXT5 and 9 DXT1 — which are its paint,
  * its interior and most of its normal maps. `imageInfo.ts` identifies PNG, JPEG and WEBP, so
  * without this the model imports correctly shaped and visibly half-painted.
  *
- * **It runs in the baker and never in a frame.** RGBA is larger than the compressed source it came
- * from, and the bake re-encodes to whatever the texture pipeline wants; nothing ships a block
- * decoder into a running game. That is what makes the cost acceptable and it is the only reason
- * decoding to RGBA rather than uploading the blocks directly is the right call here.
- *
- * **Only the mips are dropped, deliberately.** A DDS carries a full chain and the container
- * generates its own, so decoding level 0 and discarding the rest is not a loss — it is declining
- * to carry two answers to the same question.
+ * **Since 4.8.4 the baker keeps a block-compressed DDS as blocks**, through `ddsBlocks.ts`, and this
+ * is the path for what it cannot keep — an uncompressed surface, a chain it refuses — and for a bake
+ * asked to decode. It decodes level 0 only: the container generates its own chain for an image it
+ * did not receive one for.
  *
  * **Both header spellings, as of 3.30.2.** A `DX10` header names the format in a 20-byte extension
  * rather than in the four characters at byte 84, and the blocks behind it are the same blocks. This
@@ -23,19 +19,21 @@
  * as a *lighting* bug rather than as a missing texture: their baker substitutes a 1x1 white pixel,
  * and white in an ORM map is roughness 1 **and** metallic 1, which in the flat shader leaves no
  * diffuse and no sun term at all. The bodywork became a blurred mirror of the field it was parked
- * in, and the report said so in those words.
- *
- * What it refuses, by name: BC7, BC6H, BC4, signed BC5, cube maps, arrays and volumes. A format
- * identified and declined is worth more than one half-decoded, which is `recognise.ts`'s principle
- * applied one level down — and the last three of those are refused *because* a classic header has
- * no way to state them, so accepting one would answer with a picture instead of an error.
+ * in, and the report said so in those words. The header is `ddsHeader.ts`'s now, shared with the
+ * reader that keeps the blocks.
  */
-/** Whether these bytes are a DDS at all. The magic, and nothing inferred from a file name. */
-export declare function isDds(bytes: Uint8Array): boolean;
+export { isDds } from './ddsHeader.ts';
 /** What a decoded surface is: level 0, RGBA, eight bits a channel. */
 export interface DdsImage {
     readonly width: number;
     readonly height: number;
     readonly rgba: Uint8Array;
 }
+/**
+ * Decode a DDS surface's level 0 into RGBA.
+ *
+ * A surface whose dimensions are not multiples of four is decoded block by block and cropped, which
+ * is what the format itself does: the blocks cover a padded rectangle and the texels outside the
+ * declared size are padding rather than image.
+ */
 export declare function ddsToRgba(bytes: Uint8Array): DdsImage;

package/dist/dds.js

@@ -1,20 +1,16 @@
 /**
- * DDS surfaces to RGBA: BC1, BC2, BC3 and BC5 in either header spelling, and the uncompressed
- * layouts, by the masks their own header carries.
+ * DDS surfaces to RGBA: BC1 to BC5 and BC7 in either header spelling, and the uncompressed layouts,
+ * by the masks their own header carries.
  *
  * **It exists because a third of a shipped vehicle's textures are in it.** The car this was built
  * against carries 81 textures and 34 of them are DDS — 25 DXT5 and 9 DXT1 — which are its paint,
  * its interior and most of its normal maps. `imageInfo.ts` identifies PNG, JPEG and WEBP, so
  * without this the model imports correctly shaped and visibly half-painted.
  *
- * **It runs in the baker and never in a frame.** RGBA is larger than the compressed source it came
- * from, and the bake re-encodes to whatever the texture pipeline wants; nothing ships a block
- * decoder into a running game. That is what makes the cost acceptable and it is the only reason
- * decoding to RGBA rather than uploading the blocks directly is the right call here.
- *
- * **Only the mips are dropped, deliberately.** A DDS carries a full chain and the container
- * generates its own, so decoding level 0 and discarding the rest is not a loss — it is declining
- * to carry two answers to the same question.
+ * **Since 4.8.4 the baker keeps a block-compressed DDS as blocks**, through `ddsBlocks.ts`, and this
+ * is the path for what it cannot keep — an uncompressed surface, a chain it refuses — and for a bake
+ * asked to decode. It decodes level 0 only: the container generates its own chain for an image it
+ * did not receive one for.
  *
  * **Both header spellings, as of 3.30.2.** A `DX10` header names the format in a 20-byte extension
  * rather than in the four characters at byte 84, and the blocks behind it are the same blocks. This
@@ -23,189 +19,13 @@
  * as a *lighting* bug rather than as a missing texture: their baker substitutes a 1x1 white pixel,
  * and white in an ORM map is roughness 1 **and** metallic 1, which in the flat shader leaves no
  * diffuse and no sun term at all. The bodywork became a blurred mirror of the field it was parked
- * in, and the report said so in those words.
- *
- * What it refuses, by name: BC7, BC6H, BC4, signed BC5, cube maps, arrays and volumes. A format
- * identified and declined is worth more than one half-decoded, which is `recognise.ts`'s principle
- * applied one level down — and the last three of those are refused *because* a classic header has
- * no way to state them, so accepting one would answer with a picture instead of an error.
- */
-import { DrftError } from '@driftengine/drft';
-const HEADER_BYTES = 128;
-/** `DDS_HEADER_DXT10`: the extension a `DX10` FourCC puts between the header and the surface. */
-const DX10_EXTENSION_BYTES = 20;
-/** `DDPF_FOURCC`: the pixel format names a compression rather than describing channels. */
-const DDPF_FOURCC = 0x4;
-/** Whether these bytes are a DDS at all. The magic, and nothing inferred from a file name. */
-export function isDds(bytes) {
-    return (bytes.length >= 4 &&
-        bytes[0] === 0x44 &&
-        bytes[1] === 0x44 &&
-        bytes[2] === 0x53 &&
-        bytes[3] === 0x20);
-}
-/** RGB565 to three bytes, with the low bits replicated so white stays white. */
-function expand565(value) {
-    const r = (value >> 11) & 0x1f;
-    const g = (value >> 5) & 0x3f;
-    const b = value & 0x1f;
-    return [(r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2)];
-}
-/**
- * One BC1 colour block into a 16-entry RGBA palette lookup.
- *
- * **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.
- */
-function decodeColourBlock(bytes, at, out, 
-/**
- * Whether the block may take BC1's three-colour mode.
- *
- * **False for BC2 and BC3, whatever the endpoint order, and that is the correction of a real
- * defect.** Those two 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. This function
- * was reached unconditionally, so a BC3 block written with `c0 <= c1` decoded its fourth index to
- * transparent black instead of to the interpolant — invisible in every test here and in most real
- * data, because an encoder that has no reason to order the endpoints the low way usually does not.
- * Found while adding BC2, whose specification says the same thing about the same bytes.
- */
-punchthrough) {
-    const c0 = bytes[at] | (bytes[at + 1] << 8);
-    const c1 = bytes[at + 2] | (bytes[at + 3] << 8);
-    const [r0, g0, b0] = expand565(c0);
-    const [r1, g1, b1] = expand565(c1);
-    const palette = new Uint8Array(16);
-    palette.set([r0, g0, b0, 255], 0);
-    palette.set([r1, g1, b1, 255], 4);
-    if (c0 > c1 || !punchthrough) {
-        palette.set([
-            Math.round((2 * r0 + r1) / 3),
-            Math.round((2 * g0 + g1) / 3),
-            Math.round((2 * b0 + b1) / 3),
-            255,
-            Math.round((r0 + 2 * r1) / 3),
-            Math.round((g0 + 2 * g1) / 3),
-            Math.round((b0 + 2 * b1) / 3),
-            255,
-        ], 8);
-    }
-    else {
-        palette.set([
-            Math.round((r0 + r1) / 2),
-            Math.round((g0 + g1) / 2),
-            Math.round((b0 + b1) / 2),
-            255,
-            0,
-            0,
-            0,
-            0,
-        ], 8);
-    }
-    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.
- *
- * The same endpoint comparison as the colour block, and the same consequence for getting it
- * backwards: 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 = new Uint8Array(8);
-    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, in row order.
- *
- * **No interpolation and no mode**, which is the whole difference from BC3 and the reason this is
- * four lines rather than the twenty above. Sixteen texels, low nibble of each byte first.
- *
- * The nibble is 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 in the
- * pipeline sees a different picture from the one that was exported.
- */
-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;
-    }
-}
-/**
- * The DXGI block formats, as the same blocks this reader already decodes.
- *
- * **A `DX10` header states the format in a 20-byte extension instead of in the four characters at
- * byte 84, and that is the whole of the difference.** BC3 announced as `DXGI_FORMAT_BC3_UNORM_SRGB`
- * is bit for bit the BC3 announced as `DXT5`: the same blocks, the same mip chain, and sRGB is a
- * statement about how the values are *read* rather than about how they are stored. Measured from
- * outside on one bundle's paint texture — 5,592,580 bytes against 5,592,560 for the classic
- * spelling of the same 2048² chain, which is 148 + 5,592,432 against 128 + 5,592,432.
- *
- * The typeless and sRGB spellings sit beside the plain `UNORM` ones for that reason.
- *
- * **What is deliberately absent.** BC4 (79–81), which this reader does not decode at all; and
- * `BC5_SNORM` (84), whose values are signed — mapping it would decode to wrong numbers rather than
- * to an error, which is the one failure this file is written to avoid.
- */
-const DXGI_BLOCK = {
-    70: 'bc1',
-    71: 'bc1',
-    72: 'bc1',
-    73: 'bc2',
-    74: 'bc2',
-    75: 'bc2',
-    76: 'bc3',
-    77: 'bc3',
-    78: 'bc3',
-    82: 'bc5',
-    83: 'bc5',
-};
-const FOURCC_BLOCK = {
-    DXT1: 'bc1',
-    DXT3: 'bc2',
-    DXT5: 'bc3',
-    ATI2: 'bc5',
-    BC5U: 'bc5',
-};
-/**
- * Decode a DDS surface's level 0 into RGBA.
- *
- * A surface whose dimensions are not multiples of four is decoded block by block and cropped, which
- * is what the format itself does: the blocks cover a padded rectangle and the texels outside the
- * declared size are padding rather than image.
+ * in, and the report said so in those words. The header is `ddsHeader.ts`'s now, shared with the
+ * reader that keeps the blocks.
  */
+import { DrftError, BC_BLOCK_BYTES } from '@driftengine/drft';
+import { decodeBcImage } from './bcImage.js';
+import { DDPF_FOURCC, HEADER_BYTES, isDds, readDdsSurface } from './ddsHeader.js';
+export { isDds } from './ddsHeader.js';
 /** `DDPF_ALPHAPIXELS`, `DDPF_RGB`, `DDPF_LUMINANCE`: what the pixel format says it describes. */
 const DDPF_ALPHAPIXELS = 0x1;
 const DDPF_RGB = 0x40;
@@ -295,53 +115,12 @@ function uncompressedToRgba(bytes, view, width, height, flags) {
     return { width, height, rgba };
 }
 /**
- * Which blocks the file holds, and where they start.
- *
- * **Two spellings of one thing.** A classic header names the format in the four characters at byte
- * 84 and the surface follows at 128; a `DX10` header puts `DX10` there instead and states the real
- * format in a 20-byte extension, so the surface starts at 148. Nothing else differs — the blocks
- * are the same blocks — which is why this resolves both to one name and one offset rather than
- * growing a second decoder.
+ * Decode a DDS surface's level 0 into RGBA.
  *
- * **What a `DX10` header can say that a reader must refuse.** `resourceDimension` other than 3
- * (`TEXTURE2D`), `miscFlag` bit 2 (a cube map) or an `arraySize` above 1. The classic header has no
- * way to state any of them, so taking one would hand the caller six faces or twenty slices claiming
- * to be a single surface — a picture rather than an error.
+ * A surface whose dimensions are not multiples of four is decoded block by block and cropped, which
+ * is what the format itself does: the blocks cover a padded rectangle and the texels outside the
+ * declared size are padding rather than image.
  */
-function resolveSurface(bytes, view, fourcc) {
-    if (fourcc !== 'DX10') {
-        const format = FOURCC_BLOCK[fourcc];
-        if (format === undefined) {
-            throw new DrftError(`dds: "${fourcc}" is not a format this reader decodes. It reads BC1 (DXT1), BC2 (DXT3), ` +
-                'BC3 (DXT5) and BC5 (ATI2). Convert the texture to PNG, or re-export it as one of those.');
-        }
-        return { format, dataAt: HEADER_BYTES };
-    }
-    const dataAt = HEADER_BYTES + DX10_EXTENSION_BYTES;
-    if (bytes.length < dataAt) {
-        throw new DrftError('dds: a DX10 header is declared and the twenty-byte extension is not there');
-    }
-    const dxgi = view.getUint32(HEADER_BYTES, true);
-    const dimension = view.getUint32(HEADER_BYTES + 4, true);
-    const miscFlag = view.getUint32(HEADER_BYTES + 8, true);
-    const arraySize = view.getUint32(HEADER_BYTES + 12, true);
-    if (dimension !== 3) {
-        throw new DrftError(`dds: this DX10 surface declares resourceDimension ${dimension}, and only 3 (a plain 2D ` +
-            'texture) is read here. A 1D or volume texture is a different thing wearing the same header.');
-    }
-    if ((miscFlag & 0x4) !== 0) {
-        throw new DrftError('dds: this is a cube map, and only a plain 2D texture is read here.');
-    }
-    if (arraySize > 1) {
-        throw new DrftError(`dds: this is a texture array of ${arraySize}, and only a plain 2D texture is read here.`);
-    }
-    const format = DXGI_BLOCK[dxgi];
-    if (format === undefined) {
-        throw new DrftError(`dds: DXGI format ${dxgi} is not one this reader decodes. It reads BC1, BC2, BC3 and BC5 ` +
-            '(unsigned). Convert the texture to PNG, or re-export it as one of those.');
-    }
-    return { format, dataAt };
-}
 export function ddsToRgba(bytes) {
     if (!isDds(bytes))
         throw new DrftError('dds: these bytes do not begin "DDS "');
@@ -351,7 +130,6 @@ export function ddsToRgba(bytes) {
     const height = view.getUint32(12, true);
     const width = view.getUint32(16, true);
     const pixelFlags = view.getUint32(80, true);
-    const fourcc = String.fromCharCode(bytes[84], bytes[85], bytes[86], bytes[87]);
     /*
      * A pixel format that describes channels rather than naming a compression. There is no block to
      * decode, so it is a bit count, four masks and a copy — and it is 289 of one consumer's 766
@@ -364,62 +142,11 @@ export function ddsToRgba(bytes) {
         }
         return uncompressedToRgba(bytes, view, width, height, pixelFlags);
     }
-    const { format, dataAt } = resolveSurface(bytes, view, fourcc);
-    const blockBytes = format === 'bc1' ? 8 : 16;
-    const blocksX = Math.max(1, Math.ceil(width / 4));
-    const blocksY = Math.max(1, Math.ceil(height / 4));
-    const needed = blocksX * blocksY * blockBytes;
+    const { format, dataAt, named } = readDdsSurface(bytes, view);
+    const needed = Math.max(1, Math.ceil(width / 4)) * Math.max(1, Math.ceil(height / 4)) * BC_BLOCK_BYTES[format];
     if (bytes.length - dataAt < needed) {
-        throw new DrftError(`dds: the surface is short — ${width}x${height} of ${fourcc} needs ${needed} bytes and ` +
+        throw new DrftError(`dds: the surface is short — ${width}x${height} of ${named} needs ${needed} bytes and ` +
             `${bytes.length - dataAt} follow the header.`);
     }
-    const rgba = new Uint8Array(width * height * 4);
-    const block = new Uint8Array(16 * 4);
-    for (let by = 0; by < blocksY; by++) {
-        for (let bx = 0; bx < blocksX; bx++) {
-            const at = dataAt + (by * blocksX + bx) * blockBytes;
-            block.fill(0);
-            if (format === 'bc1') {
-                decodeColourBlock(bytes, at, block, true);
-            }
-            else if (format === 'bc2') {
-                /* Eight bytes of explicit alpha, then a colour block that is always four-colour. */
-                decodeColourBlock(bytes, at + 8, block, false);
-                decodeExplicitAlpha(bytes, at, block);
-            }
-            else if (format === 'bc3') {
-                decodeColourBlock(bytes, at + 8, block, false);
-                decodeAlphaBlock(bytes, at, block, 4, 3);
-            }
-            else {
-                /*
-                 * BC5 is two BC4 blocks, red then green, and it is how a normal map is stored. Blue is
-                 * left at zero rather than reconstructed: `z = sqrt(1 - x² - y²)` belongs in the shader
-                 * that consumes the map, where the reconstruction can use the same convention the
-                 * renderer's own tangent basis does.
-                 */
-                decodeAlphaBlock(bytes, at, block, 4, 0);
-                decodeAlphaBlock(bytes, at + 8, block, 4, 1);
-                for (let texel = 0; texel < 16; texel++)
-                    block[texel * 4 + 3] = 255;
-            }
-            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;
-                    rgba[to] = block[from];
-                    rgba[to + 1] = block[from + 1];
-                    rgba[to + 2] = block[from + 2];
-                    rgba[to + 3] = block[from + 3];
-                }
-            }
-        }
-    }
-    return { width, height, rgba };
+    return { width, height, rgba: decodeBcImage(format, width, height, bytes.subarray(dataAt)) };
 }

package/dist/ddsBlocks.d.ts

@@ -0,0 +1,3 @@
+import type { BcImage } from '@driftengine/drft';
+/** The surface's blocks and stored levels, as views over `bytes`. */
+export declare function ddsBlocks(bytes: Uint8Array): BcImage;

package/dist/ddsBlocks.js

@@ -0,0 +1,54 @@
+/**
+ * A block-compressed DDS kept as it was authored: its blocks, untouched, and every mip level its
+ * author stored, ready for a `CODEC_BC` payload.
+ *
+ * **Why keep them rather than decode them.** A BC7 texture is a byte a texel on the GPU where RGBA
+ * is four, and its chain is the one its author built — often filtered with care a box filter does
+ * not take, and for a normal map renormalised at every level. Decoding to RGBA and letting the
+ * engine generate mips throws both away, and costs a phone's memory and a desktop's bandwidth for
+ * the privilege. Where a device cannot sample a format, the loader decodes the same blocks there.
+ *
+ * **What it refuses, so the baker can fall back to decoding level 0:** a chain longer than the
+ * image has levels for, a chain whose bytes stop before its last level, a volume texture (each of
+ * whose levels holds several slices, so its layout is not a chain of images), and an uncompressed
+ * surface, which has no blocks to keep. Bytes after the last level are left where they are; a
+ * classic cube map's other five faces are such bytes, so its first face is what is kept.
+ */
+import { bcChainLength, bcLevelBytes, DrftError } from '@driftengine/drft';
+import { DDPF_FOURCC, HEADER_BYTES, isDds, readDdsSurface } from './ddsHeader.js';
+/** `DDSCAPS2_VOLUME`: each level is a stack of slices rather than one image. */
+const DDSCAPS2_VOLUME = 0x200000;
+/** The surface's blocks and stored levels, as views over `bytes`. */
+export function ddsBlocks(bytes) {
+    if (!isDds(bytes))
+        throw new DrftError('dds: these bytes do not begin "DDS "');
+    if (bytes.length < HEADER_BYTES) {
+        throw new DrftError('dds: the file is shorter than its own header');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if ((view.getUint32(80, true) & DDPF_FOURCC) === 0) {
+        throw new DrftError('dds: this surface is uncompressed, so it has no blocks to keep');
+    }
+    if ((view.getUint32(112, true) & DDSCAPS2_VOLUME) !== 0) {
+        throw new DrftError('dds: this is a volume texture, whose levels are stacks of slices rather than a chain');
+    }
+    const surface = readDdsSurface(bytes, view);
+    const { format, width, height, mipCount } = surface;
+    const most = bcChainLength(width, height);
+    if (mipCount > most) {
+        throw new DrftError(`dds: ${surface.named} declares ${mipCount} levels for a ${width}x${height} image, which ` +
+            `has at most ${most}`);
+    }
+    const levels = [];
+    let at = surface.dataAt;
+    for (let i = 0; i < mipCount; i++) {
+        const size = bcLevelBytes(format, width, height, i);
+        if (at + size > bytes.length) {
+            throw new DrftError(`dds: level ${i} of ${mipCount} needs ${size} bytes and ${Math.max(0, bytes.length - at)} ` +
+                'are left');
+        }
+        levels.push(bytes.subarray(at, at + size));
+        at += size;
+    }
+    return { format, srgb: surface.srgb, width, height, levels };
+}

package/dist/ddsHeader.d.ts

@@ -0,0 +1,32 @@
+import type { BcFormat } from '@driftengine/drft';
+export declare const HEADER_BYTES = 128;
+/** `DDPF_FOURCC`: the pixel format names a compression rather than describing channels. */
+export declare const DDPF_FOURCC = 4;
+/** Whether these bytes are a DDS at all. The magic, and nothing inferred from a file name. */
+export declare function isDds(bytes: Uint8Array): boolean;
+/** What a block-compressed DDS holds, read from its header alone. */
+export interface DdsSurface {
+    readonly format: BcFormat;
+    readonly srgb: boolean;
+    readonly width: number;
+    readonly height: number;
+    /**
+     * The levels the header says follow. Zero is read as one, which is what Microsoft's own loader
+     * does: many writers leave the count zero, and its flag unset, on a surface with no chain.
+     */
+    readonly mipCount: number;
+    /** Where level 0's first block starts. */
+    readonly dataAt: number;
+    /** How the header named the format, for a message: a FourCC, or `DXGI <n>`. */
+    readonly named: string;
+}
+/**
+ * The surface a block-compressed DDS declares. The caller has checked the magic, the length of the
+ * classic header and that the pixel format names a compression.
+ *
+ * **What a `DX10` header can say that a reader must refuse.** `resourceDimension` other than 3
+ * (`TEXTURE2D`), `miscFlag` bit 2 (a cube map) or an `arraySize` above 1. Taking one would hand the
+ * caller six faces or twenty slices claiming to be a single surface — a picture rather than an
+ * error.
+ */
+export declare function readDdsSurface(bytes: Uint8Array, view: DataView): DdsSurface;