@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/texture/basis/etc1s/etc1s_decode_slice.d.ts

@@ -0,0 +1,57 @@
+/**
+ * One slice's blocks, as indices into the two codebooks.
+ *
+ * @typedef {object} Etc1sSlice
+ * @property {Uint16Array} endpoint_index one per block, in raster order
+ * @property {Uint16Array} selector_index one per block, in raster order
+ * @property {number} blocks_x
+ * @property {number} blocks_y
+ */
+/**
+ * Decode one ETC1S slice into per-block codebook indices.
+ *
+ * A slice is a 2D array of blocks in raster order, and each block is two codebook references: which
+ * base colour and intensity it uses, and which arrangement of the four resulting colours. Neither
+ * reference is sent outright when it can be predicted, which is what the endpoint predictor and the
+ * selector history between them exist to exploit.
+ *
+ * **This decodes references, not texels.** Turning a pair of indices into colour is the transcoder's
+ * job and depends on what it is transcoding to, so the two are kept apart — the slice decode is
+ * identical whether the destination is BC1, BC7 or a debug image.
+ *
+ * **Texture video is not decoded.** The format lets a block copy both indices from the block at the
+ * same position in the previous frame, which needs the previous frame kept and the frames decoded in
+ * order. Nothing here plays video textures, and a still image never sets the flag, so the caller
+ * refuses such a file rather than this function silently reading predictor 2 as "upper left" and
+ * producing a frame that is wrong wherever the encoder skipped a block.
+ *
+ * @param {Uint8Array} data the slice's bytes
+ * @param {number} blocks_x
+ * @param {number} blocks_y
+ * @param {Etc1sSliceTables} tables
+ * @param {number} endpoint_count entries in the endpoint codebook
+ * @param {number} selector_count entries in the selector codebook
+ * @returns {Etc1sSlice}
+ * @throws {Error} for a slice whose bitstream runs out, or which refers past either codebook
+ * @see the specification, section 10.3
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_decode_slice(data: Uint8Array, blocks_x: number, blocks_y: number, tables: Etc1sSliceTables, endpoint_count: number, selector_count: number): Etc1sSlice;
+/**
+ * One slice's blocks, as indices into the two codebooks.
+ */
+export type Etc1sSlice = {
+    /**
+     * one per block, in raster order
+     */
+    endpoint_index: Uint16Array;
+    /**
+     * one per block, in raster order
+     */
+    selector_index: Uint16Array;
+    blocks_x: number;
+    blocks_y: number;
+};
+//# sourceMappingURL=etc1s_decode_slice.d.ts.map

package/src/format/texture/basis/etc1s/etc1s_decode_slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_decode_slice.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/etc1s/etc1s_decode_slice.js"],"names":[],"mappings":"AA8DA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,yCAbW,UAAU,YACV,MAAM,YACN,MAAM,4CAEN,MAAM,kBACN,MAAM,GACJ,UAAU,CAiMtB;;;;;;;;oBA/Na,WAAW;;;;oBACX,WAAW;cACX,MAAM;cACN,MAAM"}

package/src/format/texture/basis/etc1s/etc1s_decode_slice.js

@@ -0,0 +1,290 @@
+import { BasisBitReader } from "../BasisBitReader.js";
+import { Etc1sSelectorHistory } from "./Etc1sSelectorHistory.js";
+
+/**
+ * The endpoint predictor symbol that means "repeat the last one, several times over". One past the
+ * 256 real symbols, which are four two-bit predictors packed into a byte.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ENDPOINT_PRED_REPEAT_LAST_SYMBOL = 4 * 4 * 4 * 4;
+
+/**
+ * Shortest run the repeat symbol is used for, which is therefore what a decoded run length is
+ * counted from.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ENDPOINT_PRED_MIN_REPEAT_COUNT = 3;
+
+/**
+ * Chunk width of the variable-length code carrying an endpoint predictor run length.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ENDPOINT_PRED_COUNT_VLC_BITS = 4;
+
+/**
+ * Shortest selector run, counted from for the same reason as the endpoint one.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SELECTOR_HISTORY_RLE_COUNT_THRESH = 3;
+
+/**
+ * Run lengths the selector run table can name directly. The largest is reserved to mean "longer than
+ * this", and is followed by a variable-length code.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SELECTOR_HISTORY_RLE_COUNT_TOTAL = 1 << 6;
+
+/**
+ * Chunk width of the variable-length code carrying a long selector run length.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SELECTOR_HISTORY_RLE_VLC_BITS = 7;
+
+/**
+ * What each reuse predictor names, for the refusal that reports one used at an edge.
+ *
+ * @readonly
+ * @type {string[]}
+ */
+const PREDICTOR_NAMES = ["left", "upper", "upper-left"];
+
+/**
+ * One slice's blocks, as indices into the two codebooks.
+ *
+ * @typedef {object} Etc1sSlice
+ * @property {Uint16Array} endpoint_index one per block, in raster order
+ * @property {Uint16Array} selector_index one per block, in raster order
+ * @property {number} blocks_x
+ * @property {number} blocks_y
+ */
+
+/**
+ * Decode one ETC1S slice into per-block codebook indices.
+ *
+ * A slice is a 2D array of blocks in raster order, and each block is two codebook references: which
+ * base colour and intensity it uses, and which arrangement of the four resulting colours. Neither
+ * reference is sent outright when it can be predicted, which is what the endpoint predictor and the
+ * selector history between them exist to exploit.
+ *
+ * **This decodes references, not texels.** Turning a pair of indices into colour is the transcoder's
+ * job and depends on what it is transcoding to, so the two are kept apart — the slice decode is
+ * identical whether the destination is BC1, BC7 or a debug image.
+ *
+ * **Texture video is not decoded.** The format lets a block copy both indices from the block at the
+ * same position in the previous frame, which needs the previous frame kept and the frames decoded in
+ * order. Nothing here plays video textures, and a still image never sets the flag, so the caller
+ * refuses such a file rather than this function silently reading predictor 2 as "upper left" and
+ * producing a frame that is wrong wherever the encoder skipped a block.
+ *
+ * @param {Uint8Array} data the slice's bytes
+ * @param {number} blocks_x
+ * @param {number} blocks_y
+ * @param {Etc1sSliceTables} tables
+ * @param {number} endpoint_count entries in the endpoint codebook
+ * @param {number} selector_count entries in the selector codebook
+ * @returns {Etc1sSlice}
+ * @throws {Error} for a slice whose bitstream runs out, or which refers past either codebook
+ * @see the specification, section 10.3
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_decode_slice(
+    data, blocks_x, blocks_y, tables, endpoint_count, selector_count
+) {
+    const reader = new BasisBitReader().init(data);
+
+    const block_count = blocks_x * blocks_y;
+
+    const endpoint_index = new Uint16Array(block_count);
+    const selector_index = new Uint16Array(block_count);
+
+    /*
+     Two rows of per-block state, indexed by the low bit of the row: the row being decoded and the
+     one above it. A block predicting "the same endpoint as the block above" reads the second, and a
+     2x2 predictor group decoded on an even row leaves its lower half's predictor bits there for the
+     odd row beneath to pick up.
+    */
+    const pred_endpoint_index = [new Uint16Array(blocks_x), new Uint16Array(blocks_x)];
+    const pred_bits_row = [new Uint8Array(blocks_x), new Uint8Array(blocks_x)];
+
+    const selector_history = new Etc1sSelectorHistory(tables.selector_history_size);
+
+    let current_pred_bits = 0;
+    let previous_endpoint_pred_symbol = 0;
+    let endpoint_pred_repeat_count = 0;
+    let previous_endpoint_index = 0;
+    let selector_rle_count = 0;
+
+    for (let block_y = 0; block_y < blocks_y; block_y++) {
+        const current_row = block_y & 1;
+
+        for (let block_x = 0; block_x < blocks_x; block_x++) {
+            if ((block_x & 1) === 0) {
+                if ((block_y & 1) === 0) {
+                    /*
+                     One symbol carries the predictor for a whole 2x2 group of blocks — two bits
+                     each, eight bits in all. The top half is used now; the bottom half is put aside
+                     for the odd row, which is why no symbol is read there.
+                    */
+                    if (endpoint_pred_repeat_count > 0) {
+                        endpoint_pred_repeat_count--;
+                        current_pred_bits = previous_endpoint_pred_symbol;
+                    } else {
+                        current_pred_bits = tables.endpoint_pred.decode(reader);
+
+                        if (current_pred_bits === ENDPOINT_PRED_REPEAT_LAST_SYMBOL) {
+                            endpoint_pred_repeat_count = reader.vlc(ENDPOINT_PRED_COUNT_VLC_BITS)
+                                + ENDPOINT_PRED_MIN_REPEAT_COUNT - 1;
+
+                            current_pred_bits = previous_endpoint_pred_symbol;
+                        } else {
+                            previous_endpoint_pred_symbol = current_pred_bits;
+                        }
+                    }
+
+                    pred_bits_row[current_row ^ 1][block_x] = current_pred_bits >> 4;
+                } else {
+                    current_pred_bits = pred_bits_row[current_row][block_x];
+                }
+            }
+
+            const pred = current_pred_bits & 3;
+
+            current_pred_bits >>= 2;
+
+            let block_endpoint_index;
+
+            if (pred < 3) {
+                /*
+                 The three reuse predictors name a neighbour, and each has one it cannot name from
+                 the edge of the image: the left predictor at column zero, the upper at row zero, the
+                 upper-left at either. A well-formed file never does this — the encoder has the same
+                 constraint — so reaching here means the bitstream and the tables have come apart.
+
+                 Worth a refusal rather than an assertion the release build drops. Reading past the
+                 start of the previous row's array yields `undefined`, which compares false against
+                 every bound below and stores as endpoint zero: a texture quietly wrong from that
+                 block on, which is the failure this whole reader is written to avoid.
+                */
+                const needs_left = pred === 0 || pred === 2;
+                const needs_upper = pred === 1 || pred === 2;
+
+                if ((needs_left && block_x === 0) || (needs_upper && block_y === 0)) {
+                    throw new Error(
+                        `Basis: the block at ${block_x},${block_y} predicts its endpoint from the`
+                        + ` ${PREDICTOR_NAMES[pred]} block, which does not exist at the edge of a`
+                        + ` ${blocks_x}x${blocks_y} block slice`
+                    );
+                }
+            }
+
+            if (pred === 0) {
+                block_endpoint_index = previous_endpoint_index;
+            } else if (pred === 1) {
+                block_endpoint_index = pred_endpoint_index[current_row ^ 1][block_x];
+            } else if (pred === 2) {
+                block_endpoint_index = pred_endpoint_index[current_row ^ 1][block_x - 1];
+            } else {
+                const delta = tables.delta_endpoint.decode(reader);
+
+                block_endpoint_index = delta + previous_endpoint_index;
+
+                /*
+                 The delta is against a codebook that wraps rather than saturates, so an index past
+                 the end comes back around. Subtracting once is enough because the symbol alphabet is
+                 the codebook size, so the sum is below twice it.
+                */
+                if (block_endpoint_index >= endpoint_count) {
+                    block_endpoint_index -= endpoint_count;
+                }
+            }
+
+            if (block_endpoint_index >= endpoint_count) {
+                throw new Error(
+                    `Basis: a block refers to endpoint ${block_endpoint_index} of a`
+                    + ` ${endpoint_count} entry codebook`
+                );
+            }
+
+            pred_endpoint_index[current_row][block_x] = block_endpoint_index;
+            previous_endpoint_index = block_endpoint_index;
+
+            let selector_symbol;
+
+            if (selector_rle_count > 0) {
+                selector_rle_count--;
+
+                // a run repeats the *history* reference, which resolves below to its front entry
+                selector_symbol = selector_count;
+            } else {
+                selector_symbol = tables.selector.decode(reader);
+
+                const rle_symbol = selector_count + selector_history.size;
+
+                if (selector_symbol === rle_symbol) {
+                    const run = tables.selector_history_rle.decode(reader);
+
+                    selector_rle_count = run === SELECTOR_HISTORY_RLE_COUNT_TOTAL - 1
+                        ? reader.vlc(SELECTOR_HISTORY_RLE_VLC_BITS)
+                            + SELECTOR_HISTORY_RLE_COUNT_THRESH
+                        : run + SELECTOR_HISTORY_RLE_COUNT_THRESH;
+
+                    selector_symbol = selector_count;
+
+                    // this block is the run's first, so it is already accounted for
+                    selector_rle_count--;
+                }
+            }
+
+            let block_selector_index;
+
+            if (selector_symbol >= selector_count) {
+                const history_index = selector_symbol - selector_count;
+
+                if (history_index >= selector_history.size) {
+                    throw new Error(
+                        `Basis: a block refers to entry ${history_index} of a`
+                        + ` ${selector_history.size} entry selector history`
+                    );
+                }
+
+                block_selector_index = selector_history.at(history_index);
+
+                selector_history.use(history_index);
+            } else {
+                block_selector_index = selector_symbol;
+
+                if (selector_history.size > 0) {
+                    selector_history.add(block_selector_index);
+                }
+            }
+
+            if (block_selector_index >= selector_count) {
+                throw new Error(
+                    `Basis: a block refers to selector ${block_selector_index} of a`
+                    + ` ${selector_count} entry codebook`
+                );
+            }
+
+            const block = block_y * blocks_x + block_x;
+
+            endpoint_index[block] = block_endpoint_index;
+            selector_index[block] = block_selector_index;
+        }
+    }
+
+    return { endpoint_index, selector_index, blocks_x, blocks_y };
+}

package/src/format/texture/basis/etc1s/etc1s_read_endpoint_codebook.d.ts

@@ -0,0 +1,48 @@
+/**
+ * One decoded endpoint codebook.
+ *
+ * Stored as two flat arrays rather than an array of objects: there may be up to sixteen thousand
+ * entries and every block decode indexes one, so the shape that avoids an object per entry is worth
+ * the slightly noisier access.
+ *
+ * @typedef {object} Etc1sEndpointCodebook
+ * @property {Uint8Array} color5 three five-bit channels per entry, `[r, g, b]` interleaved
+ * @property {Uint8Array} intensity one three-bit table index per entry
+ * @property {number} count
+ */
+/**
+ * Read the ETC1S colour endpoint codebook.
+ *
+ * Each entry is an ETC1S block's base colour — five bits per channel — and its intensity table
+ * index. Both are sent as deltas against the previous entry, so the codebook has to be read in one
+ * pass from the start and an entry cannot be decoded on its own.
+ *
+ * @param {Uint8Array} data the endpoints section of the global data
+ * @param {number} count how many entries the section holds, from the global data header
+ * @returns {Etc1sEndpointCodebook}
+ * @throws {Error} for a section whose bitstream runs out before the entries do
+ * @see the specification, section 7.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_endpoint_codebook(data: Uint8Array, count: number): Etc1sEndpointCodebook;
+/**
+ * One decoded endpoint codebook.
+ *
+ * Stored as two flat arrays rather than an array of objects: there may be up to sixteen thousand
+ * entries and every block decode indexes one, so the shape that avoids an object per entry is worth
+ * the slightly noisier access.
+ */
+export type Etc1sEndpointCodebook = {
+    /**
+     * three five-bit channels per entry, `[r, g, b]` interleaved
+     */
+    color5: Uint8Array;
+    /**
+     * one three-bit table index per entry
+     */
+    intensity: Uint8Array;
+    count: number;
+};
+//# sourceMappingURL=etc1s_read_endpoint_codebook.d.ts.map

package/src/format/texture/basis/etc1s/etc1s_read_endpoint_codebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_read_endpoint_codebook.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/etc1s/etc1s_read_endpoint_codebook.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,mDATW,UAAU,SACV,MAAM,GACJ,qBAAqB,CAkEjC;;;;;;;;;;;;YAhFa,UAAU;;;;eACV,UAAU;WACV,MAAM"}

package/src/format/texture/basis/etc1s/etc1s_read_endpoint_codebook.js

@@ -0,0 +1,111 @@
+import { BasisBitReader } from "../BasisBitReader.js";
+import { basis_read_huffman_table } from "../basis_read_huffman_table.js";
+
+/**
+ * Upper bound on the previous channel value that selects the first of the three delta models, and
+ * likewise for the second. Past both, the third is used.
+ *
+ * Three models rather than one because the delta's *range* depends on where the previous value sat:
+ * a channel already near zero can only go up, one near thirty-one can only go down, and giving each
+ * case its own statistics is most of what makes the codebook small.
+ *
+ * @readonly
+ * @type {number}
+ */
+const COLOR5_PAL0_PREV_HI = 9;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+const COLOR5_PAL1_PREV_HI = 21;
+
+/**
+ * One decoded endpoint codebook.
+ *
+ * Stored as two flat arrays rather than an array of objects: there may be up to sixteen thousand
+ * entries and every block decode indexes one, so the shape that avoids an object per entry is worth
+ * the slightly noisier access.
+ *
+ * @typedef {object} Etc1sEndpointCodebook
+ * @property {Uint8Array} color5 three five-bit channels per entry, `[r, g, b]` interleaved
+ * @property {Uint8Array} intensity one three-bit table index per entry
+ * @property {number} count
+ */
+
+/**
+ * Read the ETC1S colour endpoint codebook.
+ *
+ * Each entry is an ETC1S block's base colour — five bits per channel — and its intensity table
+ * index. Both are sent as deltas against the previous entry, so the codebook has to be read in one
+ * pass from the start and an entry cannot be decoded on its own.
+ *
+ * @param {Uint8Array} data the endpoints section of the global data
+ * @param {number} count how many entries the section holds, from the global data header
+ * @returns {Etc1sEndpointCodebook}
+ * @throws {Error} for a section whose bitstream runs out before the entries do
+ * @see the specification, section 7.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_endpoint_codebook(data, count) {
+    const reader = new BasisBitReader().init(data);
+
+    const color5_delta_model = [
+        basis_read_huffman_table(reader),
+        basis_read_huffman_table(reader),
+        basis_read_huffman_table(reader),
+    ];
+
+    const intensity_delta_model = basis_read_huffman_table(reader);
+
+    const grayscale = reader.bits(1) !== 0;
+
+    const color5 = new Uint8Array(count * 3);
+    const intensity = new Uint8Array(count);
+
+    /*
+     The specification's starting state, and it is a state rather than a convention: the first
+     entry's delta is against these, so a decoder that started from zero would produce a codebook
+     that is wrong everywhere rather than wrong in its first entry.
+    */
+    const previous_color5 = [16, 16, 16];
+
+    let previous_intensity = 0;
+
+    for (let i = 0; i < count; i++) {
+        previous_intensity = (intensity_delta_model.decode(reader) + previous_intensity) & 7;
+
+        intensity[i] = previous_intensity;
+
+        const channels = grayscale ? 1 : 3;
+
+        for (let c = 0; c < channels; c++) {
+            const previous = previous_color5[c];
+
+            const model = previous <= COLOR5_PAL0_PREV_HI
+                ? color5_delta_model[0]
+                : previous <= COLOR5_PAL1_PREV_HI
+                    ? color5_delta_model[1]
+                    : color5_delta_model[2];
+
+            const value = (previous + model.decode(reader)) & 31;
+
+            color5[i * 3 + c] = value;
+            previous_color5[c] = value;
+        }
+
+        if (grayscale) {
+            /*
+             A grayscale codebook sends one channel and means three. The previous-value state stays
+             one channel wide — the next entry's delta is against R alone — so the copy is into the
+             output only.
+            */
+            color5[i * 3 + 1] = color5[i * 3];
+            color5[i * 3 + 2] = color5[i * 3];
+        }
+    }
+
+    return { color5, intensity, count };
+}

package/src/format/texture/basis/etc1s/etc1s_read_selector_codebook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * One decoded selector codebook.
+ *
+ * @typedef {object} Etc1sSelectorCodebook
+ * @property {Uint8Array} selectors sixteen two-bit selectors per entry, one byte each, in
+ * raster order within the block
+ * @property {number} count
+ */
+/**
+ * Read the ETC1S selector codebook.
+ *
+ * Each entry is a block's sixteen two-bit selectors — which of the four colours the block's endpoint
+ * defines each texel takes. The entries are stored as four bytes, one per row of the block, and are
+ * either raw or coded as a byte-wise exclusive-or against the previous entry.
+ *
+ * **Selectors are stored one per byte rather than packed.** Four times the memory of the packed form
+ * and worth it: every block transcode reads all sixteen, and unpacking them here once is unpacking
+ * them once per codebook entry rather than once per block that references it.
+ *
+ * @param {Uint8Array} data the selectors section of the global data
+ * @param {number} count how many entries the section holds, from the global data header
+ * @returns {Etc1sSelectorCodebook}
+ * @throws {Error} for the global and hybrid codebook forms, which the format defines and no encoder
+ * produces
+ * @see the specification, section 8.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_selector_codebook(data: Uint8Array, count: number): Etc1sSelectorCodebook;
+/**
+ * One decoded selector codebook.
+ */
+export type Etc1sSelectorCodebook = {
+    /**
+     * sixteen two-bit selectors per entry, one byte each, in
+     * raster order within the block
+     */
+    selectors: Uint8Array;
+    count: number;
+};
+//# sourceMappingURL=etc1s_read_selector_codebook.d.ts.map

package/src/format/texture/basis/etc1s/etc1s_read_selector_codebook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_read_selector_codebook.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/etc1s/etc1s_read_selector_codebook.js"],"names":[],"mappings":"AAmBA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,mDAVW,UAAU,SACV,MAAM,GACJ,qBAAqB,CAqEjC;;;;;;;;;eAvFa,UAAU;WAEV,MAAM"}

package/src/format/texture/basis/etc1s/etc1s_read_selector_codebook.js

@@ -0,0 +1,127 @@
+import { BasisBitReader } from "../BasisBitReader.js";
+import { basis_read_huffman_table } from "../basis_read_huffman_table.js";
+
+/**
+ * Texels in an ETC1S block, and so selectors in a codebook entry.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SELECTORS_PER_ENTRY = 16;
+
+/**
+ * Bytes one entry occupies in the raw form: four selectors of two bits in each.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BYTES_PER_ENTRY = 4;
+
+/**
+ * One decoded selector codebook.
+ *
+ * @typedef {object} Etc1sSelectorCodebook
+ * @property {Uint8Array} selectors sixteen two-bit selectors per entry, one byte each, in
+ * raster order within the block
+ * @property {number} count
+ */
+
+/**
+ * Read the ETC1S selector codebook.
+ *
+ * Each entry is a block's sixteen two-bit selectors — which of the four colours the block's endpoint
+ * defines each texel takes. The entries are stored as four bytes, one per row of the block, and are
+ * either raw or coded as a byte-wise exclusive-or against the previous entry.
+ *
+ * **Selectors are stored one per byte rather than packed.** Four times the memory of the packed form
+ * and worth it: every block transcode reads all sixteen, and unpacking them here once is unpacking
+ * them once per codebook entry rather than once per block that references it.
+ *
+ * @param {Uint8Array} data the selectors section of the global data
+ * @param {number} count how many entries the section holds, from the global data header
+ * @returns {Etc1sSelectorCodebook}
+ * @throws {Error} for the global and hybrid codebook forms, which the format defines and no encoder
+ * produces
+ * @see the specification, section 8.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_selector_codebook(data, count) {
+    const reader = new BasisBitReader().init(data);
+
+    const global_codebook = reader.bits(1) !== 0;
+    const hybrid_codebook = reader.bits(1) !== 0;
+    const raw = reader.bits(1) !== 0;
+
+    /*
+     Both are reserved in the format and neither has ever been written: the specification says each
+     bit "should always be 0", because the encoder has no option that sets it. Refusing names the
+     feature rather than reading the codebook that follows as though the flag were clear, which would
+     produce a texture full of the wrong selectors.
+    */
+    if (global_codebook) {
+        throw new Error(
+            "Basis: the selector codebook declares a global codebook, which the format reserves and"
+            + " no encoder emits. There is no global codebook here to resolve it against."
+        );
+    }
+
+    if (hybrid_codebook) {
+        throw new Error(
+            "Basis: the selector codebook declares a hybrid global/local codebook, which the format"
+            + " reserves and no encoder emits."
+        );
+    }
+
+    const selectors = new Uint8Array(count * SELECTORS_PER_ENTRY);
+
+    if (raw) {
+        for (let i = 0; i < count; i++) {
+            for (let row = 0; row < BYTES_PER_ENTRY; row++) {
+                unpack_row(selectors, i, row, reader.bits(8));
+            }
+        }
+
+        return { selectors, count };
+    }
+
+    const delta_model = basis_read_huffman_table(reader);
+
+    const previous = new Uint8Array(BYTES_PER_ENTRY);
+
+    for (let i = 0; i < count; i++) {
+        for (let row = 0; row < BYTES_PER_ENTRY; row++) {
+            /*
+             The first entry is sent raw, and the rest as a delta against the entry before. The
+             exclusive-or is its own inverse, so one expression covers both: the first entry's
+             "previous" is zero, against which the delta is the value.
+            */
+            const byte = i === 0
+                ? reader.bits(8)
+                : delta_model.decode(reader) ^ previous[row];
+
+            previous[row] = byte;
+
+            unpack_row(selectors, i, row, byte);
+        }
+    }
+
+    return { selectors, count };
+}
+
+/**
+ * Spread one packed byte across the four selectors of a block row.
+ *
+ * @param {Uint8Array} selectors
+ * @param {number} entry
+ * @param {number} row
+ * @param {number} byte four two-bit selectors, the leftmost texel in the least significant pair
+ */
+function unpack_row(selectors, entry, row, byte) {
+    const base = entry * SELECTORS_PER_ENTRY + row * 4;
+
+    for (let column = 0; column < 4; column++) {
+        selectors[base + column] = (byte >> (column * 2)) & 3;
+    }
+}