@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/texture/basis/astc_partition.js

@@ -0,0 +1,199 @@
+/**
+ * ASTC's partition hash.
+ *
+ * A fixed sequence of shifts, adds and xors over a 32-bit word — the specification gives it as
+ * `hash52` and it is reproduced here in the arithmetic JavaScript actually has. Every step is forced
+ * back into unsigned 32 bits, because `<<` in JavaScript yields a *signed* result and `p += p << 16`
+ * on a value with the top bit set would otherwise go negative and take every later step with it.
+ *
+ * @param {number} p
+ * @returns {number} unsigned 32-bit
+ */
+function hash52(p) {
+    p = p >>> 0;
+
+    p = (p ^ (p >>> 15)) >>> 0;
+    p = (p - ((p << 17) >>> 0)) >>> 0;
+    p = (p + ((p << 7) >>> 0)) >>> 0;
+    p = (p + ((p << 4) >>> 0)) >>> 0;
+    p = (p ^ (p >>> 5)) >>> 0;
+    p = (p + ((p << 16) >>> 0)) >>> 0;
+    p = (p ^ (p >>> 7)) >>> 0;
+    p = (p ^ (p >>> 3)) >>> 0;
+    p = (p ^ ((p << 6) >>> 0)) >>> 0;
+    p = (p ^ (p >>> 17)) >>> 0;
+
+    return p >>> 0;
+}
+
+/**
+ * Which subset a texel belongs to, for a given partition seed.
+ *
+ * **ASTC does not store its partition patterns; it computes them.** A block names a ten-bit seed and
+ * every decoder runs this to recover the same assignment, which is why there are 1024 patterns per
+ * subset count at no cost in the bitstream. That also means a pattern cannot be chosen directly: an
+ * encoder that wants a particular shape has to find a seed that produces it, which is what
+ * {@link astc_find_partition_seed} does.
+ *
+ * `small_block` doubles the coordinates for blocks under 31 texels, and a 4x4 block is one — so this
+ * is hard-coded to that rather than taking a parameter it would only ever be handed one value for.
+ *
+ * @param {number} seed ten bits
+ * @param {number} x
+ * @param {number} y
+ * @param {number} partition_count 2, 3 or 4
+ * @returns {number} the subset index, `0` to `partition_count - 1`
+ *
+ * @see the ASTC specification, "Partition Pattern Generation"
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function astc_select_partition(seed, x, y, partition_count) {
+    // a 4x4 block is a small block, so its coordinates are doubled before they enter the hash
+    x <<= 1;
+    y <<= 1;
+
+    const combined = seed + (partition_count - 1) * 1024;
+
+    const rnum = hash52(combined);
+
+    const nibble = shift => (rnum >>> shift) & 0xF;
+
+    let seed1 = nibble(0);
+    let seed2 = nibble(4);
+    let seed3 = nibble(8);
+    let seed4 = nibble(12);
+    let seed5 = nibble(16);
+    let seed6 = nibble(20);
+    let seed7 = nibble(24);
+    let seed8 = nibble(28);
+    let seed9 = nibble(18);
+    let seed10 = nibble(22);
+    let seed11 = nibble(26);
+    let seed12 = (((rnum >>> 30) | ((rnum << 2) >>> 0)) & 0xF) >>> 0;
+
+    seed1 *= seed1; seed2 *= seed2;
+    seed3 *= seed3; seed4 *= seed4;
+    seed5 *= seed5; seed6 *= seed6;
+    seed7 *= seed7; seed8 *= seed8;
+    seed9 *= seed9; seed10 *= seed10;
+    seed11 *= seed11; seed12 *= seed12;
+
+    let sh1;
+    let sh2;
+
+    if (combined & 1) {
+        sh1 = (combined & 2) ? 4 : 5;
+        sh2 = partition_count === 3 ? 6 : 5;
+    } else {
+        sh1 = partition_count === 3 ? 6 : 5;
+        sh2 = (combined & 2) ? 4 : 5;
+    }
+
+    const sh3 = (combined & 0x10) ? sh1 : sh2;
+
+    seed1 >>= sh1; seed2 >>= sh2; seed3 >>= sh1; seed4 >>= sh2;
+    seed5 >>= sh1; seed6 >>= sh2; seed7 >>= sh1; seed8 >>= sh2;
+    seed9 >>= sh3; seed10 >>= sh3; seed11 >>= sh3; seed12 >>= sh3;
+
+    // the z terms drop out: a 2D block's third coordinate is zero
+    let a = (seed1 * x + seed2 * y + (rnum >>> 14)) & 0x3F;
+    let b = (seed3 * x + seed4 * y + (rnum >>> 10)) & 0x3F;
+    let c = (seed5 * x + seed6 * y + (rnum >>> 6)) & 0x3F;
+    let d = (seed7 * x + seed8 * y + (rnum >>> 2)) & 0x3F;
+
+    if (partition_count < 4) {
+        d = 0;
+    }
+
+    if (partition_count < 3) {
+        c = 0;
+    }
+
+    if (a >= b && a >= c && a >= d) {
+        return 0;
+    }
+
+    if (b >= c && b >= d) {
+        return 1;
+    }
+
+    if (c >= d) {
+        return 2;
+    }
+
+    return 3;
+}
+
+/**
+ * The sixteen subset indices a seed produces, in raster order.
+ *
+ * @param {number} seed
+ * @param {number} partition_count
+ * @returns {Uint8Array} sixteen
+ */
+export function astc_partition_pattern(seed, partition_count) {
+    const out = new Uint8Array(16);
+
+    for (let y = 0; y < 4; y++) {
+        for (let x = 0; x < 4; x++) {
+            out[y * 4 + x] = astc_select_partition(seed, x, y, partition_count);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Find a seed whose pattern matches `wanted`, allowing the subsets to be numbered differently.
+ *
+ * **Searched rather than tabulated, and that is the point.** UASTC names its patterns by index into
+ * its own list and ASTC names them by a seed into a hash; the mapping between them is a table of
+ * thirty-odd numbers that exists in the reference transcoder and could be copied. Deriving it here
+ * instead means the numbers are *checked* — a wrong entry is not a typo that survives review, it is a
+ * search that fails and says so.
+ *
+ * **Relabelling is allowed because subsets are named by position, not identity.** ASTC's hash decides
+ * which texels share endpoints, and which of them it calls subset 0 is arbitrary; what matters is
+ * that the grouping agrees. So a match returns the permutation alongside the seed, and the caller
+ * reorders its endpoint pairs to suit rather than demanding the hash produce a numbering it cannot be
+ * asked for.
+ *
+ * @param {Uint8Array} wanted sixteen subset indices, in raster order
+ * @param {number} partition_count
+ * @returns {{seed: number, permutation: number[]}|undefined} `permutation[u]` is the ASTC subset
+ * that UASTC's subset `u` became, or undefined if no seed produces this grouping
+ */
+export function astc_find_partition_seed(wanted, partition_count) {
+    for (let seed = 0; seed < 1024; seed++) {
+        const pattern = astc_partition_pattern(seed, partition_count);
+
+        /*
+         Built from the first texel of each UASTC subset and then verified over all sixteen, rather
+         than tried as every possible permutation: the mapping a match would need is forced by any
+         one texel of each subset, so there is nothing to search over.
+        */
+        const permutation = new Int32Array(partition_count).fill(-1);
+        const taken = new Int32Array(partition_count).fill(-1);
+
+        let ok = true;
+
+        for (let texel = 0; texel < 16 && ok; texel++) {
+            const from = wanted[texel];
+            const to = pattern[texel];
+
+            if (permutation[from] === -1 && taken[to] === -1) {
+                permutation[from] = to;
+                taken[to] = from;
+            } else if (permutation[from] !== to) {
+                ok = false;
+            }
+        }
+
+        if (ok && permutation.every(entry => entry !== -1)) {
+            return { seed, permutation: [...permutation] };
+        }
+    }
+
+    return undefined;
+}

package/src/format/texture/basis/basis_read_huffman_table.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Read one of the format's compressed Huffman tables.
+ *
+ * The table is described by its symbols' code lengths, and those lengths are themselves run-length
+ * and Huffman coded — the same two-level arrangement Deflate uses, which the specification says it
+ * is deliberately compatible with. So this reads a small table first, then uses it to read the
+ * lengths of the one that was asked for.
+ *
+ * @param {BasisBitReader} reader positioned at the start of the table
+ * @returns {BasisHuffmanTable}
+ * @throws {Error} naming the field, for a table whose header or code lengths are not self-consistent
+ * @see the specification, section 6.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function basis_read_huffman_table(reader: BasisBitReader): BasisHuffmanTable;
+import { BasisBitReader } from "./BasisBitReader.js";
+import { BasisHuffmanTable } from "./BasisHuffmanTable.js";
+//# sourceMappingURL=basis_read_huffman_table.d.ts.map

package/src/format/texture/basis/basis_read_huffman_table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis_read_huffman_table.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/basis/basis_read_huffman_table.js"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;;;GAeG;AACH,iDARW,cAAc,GACZ,iBAAiB,CAqG7B;+BA1L8B,qBAAqB;kCAK7C,wBAAwB"}

package/src/format/texture/basis/basis_read_huffman_table.js

@@ -0,0 +1,187 @@
+import { BasisBitReader } from "./BasisBitReader.js";
+import {
+    BasisHuffmanTable,
+    HUFFMAN_MAX_CODE_SIZE,
+    HUFFMAN_MAX_SYMBOLS
+} from "./BasisHuffmanTable.js";
+
+/**
+ * Symbols in the little table that codes the big table's code lengths: the seventeen lengths
+ * `[0, 16]` plus four run codes. The specification's `cHuffmanTotalCodelengthCodes`.
+ *
+ * @readonly
+ * @type {number}
+ */
+const CODELENGTH_CODE_COUNT = 21;
+
+/**
+ * A run of symbols with no code, three to ten long. The specification's `cHuffmanSmallZeroRunCode`.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SMALL_ZERO_RUN_CODE = 17;
+
+/**
+ * A run of symbols with no code, eleven to a hundred and thirty-eight long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BIG_ZERO_RUN_CODE = 18;
+
+/**
+ * A run repeating the previous symbol's code length, three to six long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SMALL_REPEAT_CODE = 19;
+
+/**
+ * A run repeating the previous symbol's code length, seven to a hundred and thirty-four long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BIG_REPEAT_CODE = 20;
+
+/**
+ * Extra bits, and the minimum the run may be, for each of the four run codes — indexed by the code
+ * itself so the decode loop reads them rather than branching four ways.
+ *
+ * @readonly
+ * @type {Object<number, {extra_bits: number, minimum: number}>}
+ */
+const RUNS = {
+    [SMALL_ZERO_RUN_CODE]: { extra_bits: 3, minimum: 3 },
+    [BIG_ZERO_RUN_CODE]: { extra_bits: 7, minimum: 11 },
+    [SMALL_REPEAT_CODE]: { extra_bits: 2, minimum: 3 },
+    [BIG_REPEAT_CODE]: { extra_bits: 7, minimum: 7 },
+};
+
+/**
+ * The order the code lengths of the little table arrive in.
+ *
+ * Not sorted, and not arbitrary: the run codes come first and the ordinary lengths radiate outward
+ * from eight, so the lengths a typical table never uses cluster at the end and can be left unsent.
+ *
+ * @readonly
+ * @type {number[]}
+ */
+const CODELENGTH_CODE_ORDER = [
+    SMALL_ZERO_RUN_CODE, BIG_ZERO_RUN_CODE, SMALL_REPEAT_CODE, BIG_REPEAT_CODE,
+    0, 8, 7, 9, 6, 0xA, 5, 0xB, 4, 0xC, 3, 0xD, 2, 0xE, 1, 0xF, 0x10,
+];
+
+/**
+ * Read one of the format's compressed Huffman tables.
+ *
+ * The table is described by its symbols' code lengths, and those lengths are themselves run-length
+ * and Huffman coded — the same two-level arrangement Deflate uses, which the specification says it
+ * is deliberately compatible with. So this reads a small table first, then uses it to read the
+ * lengths of the one that was asked for.
+ *
+ * @param {BasisBitReader} reader positioned at the start of the table
+ * @returns {BasisHuffmanTable}
+ * @throws {Error} naming the field, for a table whose header or code lengths are not self-consistent
+ * @see the specification, section 6.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function basis_read_huffman_table(reader) {
+    const total_used_syms = reader.bits(14);
+
+    if (total_used_syms === 0 || total_used_syms > HUFFMAN_MAX_SYMBOLS) {
+        throw new Error(
+            `Basis: a Huffman table declares ${total_used_syms} symbols, and the format allows`
+            + ` 1 to ${HUFFMAN_MAX_SYMBOLS}`
+        );
+    }
+
+    const codelength_code_count = reader.bits(5);
+
+    if (codelength_code_count === 0 || codelength_code_count > CODELENGTH_CODE_COUNT) {
+        throw new Error(
+            `Basis: a Huffman table declares ${codelength_code_count} code length codes, and the`
+            + ` format allows 1 to ${CODELENGTH_CODE_COUNT}`
+        );
+    }
+
+    const codelength_code_lengths = new Uint8Array(CODELENGTH_CODE_COUNT);
+
+    for (let i = 0; i < codelength_code_count; i++) {
+        codelength_code_lengths[CODELENGTH_CODE_ORDER[i]] = reader.bits(3);
+    }
+
+    const codelength_table = new BasisHuffmanTable().init(codelength_code_lengths);
+
+    const code_lengths = new Uint8Array(total_used_syms);
+
+    let symbol = 0;
+
+    while (symbol < total_used_syms) {
+        const code = codelength_table.decode(reader);
+
+        if (code <= HUFFMAN_MAX_CODE_SIZE) {
+            code_lengths[symbol++] = code;
+
+            continue;
+        }
+
+        const run = RUNS[code];
+
+        if (run === undefined) {
+            throw new Error(
+                `Basis: a Huffman table's code length stream used symbol ${code}, and only`
+                + ` 0 to ${BIG_REPEAT_CODE} are defined`
+            );
+        }
+
+        const count = reader.bits(run.extra_bits) + run.minimum;
+
+        if (symbol + count > total_used_syms) {
+            throw new Error(
+                `Basis: a run of ${count} code lengths starting at symbol ${symbol} overruns the`
+                + ` ${total_used_syms} symbols the Huffman table declared`
+            );
+        }
+
+        const repeats = code === SMALL_REPEAT_CODE || code === BIG_REPEAT_CODE;
+
+        if (!repeats) {
+            // a zero run; the array is already zero, so the run only has to advance past it
+            symbol += count;
+
+            continue;
+        }
+
+        /*
+         The specification forbids a repeat as the first symbol, and forbids repeating a length of
+         zero — the run says "the same as the last one" and there has to be a last one for it to
+         name. Both would otherwise read as a run of unused symbols, which is what a zero run is for.
+        */
+        if (symbol === 0) {
+            throw new Error(
+                "Basis: a Huffman table's code length stream opens with a repeat run, which has no"
+                + " previous length to repeat"
+            );
+        }
+
+        const previous = code_lengths[symbol - 1];
+
+        if (previous === 0) {
+            throw new Error(
+                `Basis: a Huffman table's code length stream repeats symbol ${symbol - 1}, which has`
+                + ` no code — a zero run is how unused symbols are spelled`
+            );
+        }
+
+        code_lengths.fill(previous, symbol, symbol + count);
+
+        symbol += count;
+    }
+
+    return new BasisHuffmanTable().init(code_lengths);
+}

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

@@ -0,0 +1,50 @@
+/**
+ * The recently used selector indices, as an approximate move-to-front list.
+ *
+ * A slice refers to a selector either by its codebook index or by its position in this list, and the
+ * second is cheaper whenever a block reuses something a nearby block used — which most blocks do.
+ * What makes it *approximate* is the two shortcuts it takes over a real move-to-front transform, and
+ * both matter to a decoder because they define the state exactly:
+ *
+ * - **A used entry swaps with the one at half its index** rather than moving to the front and
+ *   shifting everything after it along. So a repeatedly used entry walks toward the front
+ *   geometrically instead of arriving in one step, and the list is never actually re-ordered.
+ * - **A new entry overwrites at a rover** that sweeps the back half of the list and wraps, rather
+ *   than pushing the oldest entry off the end.
+ *
+ * Both make the encoder's and decoder's work constant per block instead of linear in the list, which
+ * for a list of up to several thousand entries is the whole reason it is affordable at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Etc1sSelectorHistory {
+    /**
+     * @param {number} size from the slice tables section; may be zero, for a file whose blocks never
+     * refer to the history
+     */
+    constructor(size: number);
+    /**
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * @param {number} index
+     * @returns {number} the selector codebook index remembered there
+     */
+    at(index: number): number;
+    /**
+     * Remember a selector index that was referred to by its codebook index.
+     *
+     * @param {number} value
+     */
+    add(value: number): void;
+    /**
+     * Promote the entry at `index`, having just referred to it.
+     *
+     * @param {number} index
+     */
+    use(index: number): void;
+    #private;
+}
+//# sourceMappingURL=Etc1sSelectorHistory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Etc1sSelectorHistory.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/etc1s/Etc1sSelectorHistory.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAaI;;;OAGG;IACH,kBAHW,MAAM,EAMhB;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFW,MAAM,QAQhB;IAED;;;;OAIG;IACH,WAFW,MAAM,QAchB;;CACJ"}

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

@@ -0,0 +1,89 @@
+/**
+ * The recently used selector indices, as an approximate move-to-front list.
+ *
+ * A slice refers to a selector either by its codebook index or by its position in this list, and the
+ * second is cheaper whenever a block reuses something a nearby block used — which most blocks do.
+ * What makes it *approximate* is the two shortcuts it takes over a real move-to-front transform, and
+ * both matter to a decoder because they define the state exactly:
+ *
+ * - **A used entry swaps with the one at half its index** rather than moving to the front and
+ *   shifting everything after it along. So a repeatedly used entry walks toward the front
+ *   geometrically instead of arriving in one step, and the list is never actually re-ordered.
+ * - **A new entry overwrites at a rover** that sweeps the back half of the list and wraps, rather
+ *   than pushing the oldest entry off the end.
+ *
+ * Both make the encoder's and decoder's work constant per block instead of linear in the list, which
+ * for a list of up to several thousand entries is the whole reason it is affordable at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Etc1sSelectorHistory {
+    /**
+     * @type {Int32Array}
+     */
+    #values = null;
+
+    /**
+     * Where {@link add} writes next. Sweeps the back half of {@link #values} and wraps to its
+     * middle, so the front half is only ever reached by {@link use} promoting something into it.
+     * @type {number}
+     */
+    #rover = 0;
+
+    /**
+     * @param {number} size from the slice tables section; may be zero, for a file whose blocks never
+     * refer to the history
+     */
+    constructor(size) {
+        this.#values = new Int32Array(size);
+        this.#rover = size >> 1;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get size() {
+        return this.#values.length;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number} the selector codebook index remembered there
+     */
+    at(index) {
+        return this.#values[index];
+    }
+
+    /**
+     * Remember a selector index that was referred to by its codebook index.
+     *
+     * @param {number} value
+     */
+    add(value) {
+        this.#values[this.#rover++] = value;
+
+        if (this.#rover === this.#values.length) {
+            this.#rover = this.#values.length >> 1;
+        }
+    }
+
+    /**
+     * Promote the entry at `index`, having just referred to it.
+     *
+     * @param {number} index
+     */
+    use(index) {
+        if (index === 0) {
+            // already as far forward as the list goes, and halving would swap it with itself
+            return;
+        }
+
+        const half = index >> 1;
+
+        const promoted = this.#values[index];
+
+        this.#values[index] = this.#values[half];
+        this.#values[half] = promoted;
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The four colours a block's endpoint entry defines, which its selectors choose between.
+ *
+ * @param {Uint8Array} out receives twelve bytes, four `[r, g, b]` triples darkest first
+ * @param {number} out_offset
+ * @param {Uint8Array} color5 the endpoint codebook's channel array
+ * @param {Uint8Array} intensity the endpoint codebook's intensity array
+ * @param {number} endpoint_index
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_block_colors(out: Uint8Array, out_offset: number, color5: Uint8Array, intensity: Uint8Array, endpoint_index: number): void;
+//# sourceMappingURL=etc1s_block_colors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_block_colors.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/etc1s/etc1s_block_colors.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;GAWG;AACH,wCATW,UAAU,cACV,MAAM,UACN,UAAU,aACV,UAAU,kBACV,MAAM,QAmBhB"}

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

@@ -0,0 +1,75 @@
+/**
+ * ETC1's intensity modifier table: what is added to every channel of the block's base colour, for
+ * each of the four selector values.
+ *
+ * This is ETC1's own table, not something Basis invented — ETC1S is a subset of ETC1 and its blocks
+ * decode identically on any ETC1 hardware. The four entries of a row are ordered darkest to
+ * brightest, which is the order a selector indexes them in.
+ *
+ * The same offset goes to all three channels, so a block's four colours lie on a line parallel to
+ * the grey axis. That is the fact the transcoders below rely on: a format with two endpoints and an
+ * interpolant can hold such a block almost exactly.
+ *
+ * @readonly
+ * @type {Int32Array}
+ * @see the ETC1 specification, and section 2.0 of the Basis specification
+ */
+const INTENSITY_MODIFIER = new Int32Array([
+    -8, -2, 2, 8,
+    -17, -5, 5, 17,
+    -29, -9, 9, 29,
+    -42, -13, 13, 42,
+    -60, -18, 18, 60,
+    -80, -24, 24, 80,
+    -106, -33, 33, 106,
+    -183, -47, 47, 183,
+]);
+
+/**
+ * Widen a five-bit channel to eight bits.
+ *
+ * Replicating the top three bits into the bottom rather than shifting alone is what makes 31 map to
+ * 255 instead of 248 — an endpoint of full white has to decode as white.
+ *
+ * @param {number} value five bits
+ * @returns {number} eight bits
+ */
+function expand5(value) {
+    return (value << 3) | (value >> 2);
+}
+
+/**
+ * @param {number} value
+ * @returns {number} `value` brought into `[0, 255]`
+ */
+function clamp255(value) {
+    return value < 0 ? 0 : value > 255 ? 255 : value;
+}
+
+/**
+ * The four colours a block's endpoint entry defines, which its selectors choose between.
+ *
+ * @param {Uint8Array} out receives twelve bytes, four `[r, g, b]` triples darkest first
+ * @param {number} out_offset
+ * @param {Uint8Array} color5 the endpoint codebook's channel array
+ * @param {Uint8Array} intensity the endpoint codebook's intensity array
+ * @param {number} endpoint_index
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_block_colors(out, out_offset, color5, intensity, endpoint_index) {
+    const r = expand5(color5[endpoint_index * 3]);
+    const g = expand5(color5[endpoint_index * 3 + 1]);
+    const b = expand5(color5[endpoint_index * 3 + 2]);
+
+    const row = intensity[endpoint_index] * 4;
+
+    for (let selector = 0; selector < 4; selector++) {
+        const modifier = INTENSITY_MODIFIER[row + selector];
+
+        out[out_offset + selector * 3] = clamp255(r + modifier);
+        out[out_offset + selector * 3 + 1] = clamp255(g + modifier);
+        out[out_offset + selector * 3 + 2] = clamp255(b + modifier);
+    }
+}