@woosh/meep-engine 3.14.1 → 3.14.3

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

@@ -0,0 +1,164 @@
+/**
+ * Bytes in one ASTC 4x4 block.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const ASTC_BLOCK_BYTES = 16;
+
+/**
+ * Colour endpoint mode 8: LDR RGB, direct. Six endpoint values, `R0 R1 G0 G1 B0 B1`.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const CEM_LDR_RGB_DIRECT = 8;
+
+/**
+ * Where the endpoint values begin: eleven bits of block mode, two of partition count, four of CEM.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ENDPOINT_BIT = 17;
+
+/**
+ * The two single-plane 4x4 block modes this tree writes, by how many bits a weight takes.
+ *
+ * **Read out of the specification's block-mode layout, and confirmed against the reference.** The
+ * low-precision row packs `D` at bit 10, `H` at 9, the height term `B` at 8:7, the width term `A` at
+ * 6:5, `R0` at 4, two zero bits, then `R2` and `R1` at 1:0 — with the grid `A+2` wide by `B+4` high
+ * and the weight range read from `R = R2·4 + R1·2 + R0`. So `A = 2`, `B = 0`, `D = H = 0` is a 4x4
+ * grid on one plane, and `R` picks the range: 4 gives four levels and 7 gives eight.
+ *
+ * Both appear in `basisu`'s own output for these files, which is what turns a derivation into a
+ * check.
+ *
+ * @readonly
+ * @type {Object<number, number>}
+ */
+export const ASTC_BLOCK_MODE = {
+    2: 0x42,
+    3: 0x53,
+};
+
+/**
+ * What a weight unquantizes to, out of 64, for each weight-bit count this writes.
+ *
+ * **Not evenly spaced, and not a rounding of `v / levels`.** A pure-bit weight is replicated up to
+ * six bits and then nudged: `if (T > 32) T += 1`, which is what turns the top of the range into
+ * exactly 64 rather than 63. Two bits gives `0, 21, 43, 64` and three gives `0, 9, 18, 27, 37, 46,
+ * 55, 64` — note 36 becoming 37, which a thirds-and-sevenths formula does not produce.
+ *
+ * @readonly
+ * @type {Object<number, number[]>}
+ */
+export const ASTC_WEIGHT_UNQUANTIZED = {
+    2: [0, 21, 43, 64],
+    3: [0, 9, 18, 27, 37, 46, 55, 64],
+};
+
+/**
+ * Decode one channel the way the format does.
+ *
+ * **This is not `c0 + (c1 - c0) * w / 64`.** ASTC widens each 8-bit endpoint to sixteen bits by bit
+ * replication first, interpolates there with a rounding `+32`, and takes the top eight bits of the
+ * result — which disagrees with the direct form on about one texel in twenty, always by a level.
+ * Fitting endpoints against the direct form and letting hardware decode with this one puts that
+ * disagreement into the output for nothing, so every encoder here scores against this.
+ *
+ * @param {number} c0 eight bits
+ * @param {number} c1 eight bits
+ * @param {number} weight unquantized, `0..64`
+ * @returns {number} eight bits
+ */
+export function astc_interpolate(c0, c1, weight) {
+    const wide0 = (c0 << 8) | c0;
+    const wide1 = (c1 << 8) | c1;
+
+    return Math.floor((wide0 * (64 - weight) + wide1 * weight + 32) / 64) >> 8;
+}
+
+/**
+ * Put the endpoints the way round colour endpoint mode 8 requires, inverting the weights to match.
+ *
+ * **The rule that makes a wrong-way-round block decode as the wrong colours rather than as a
+ * mirror.** Mode 8 compares the endpoints by the sum of their channels: with `s1 >= s0` they are
+ * taken as written, and otherwise the decoder *swaps* them and applies blue contraction —
+ * `r = (r + b) >> 1`, `g = (g + b) >> 1` — to both. That second path is a different picture, not an
+ * inverted one, and no bit in the block records that it happened.
+ *
+ * A least-squares fit puts the first endpoint at the darker end, so this is nearly always already
+ * satisfied; nearly is not a guarantee once rounding and clamping have run, and a block that trips
+ * it is not one any test would think to construct. Swapping the pair and inverting the weights
+ * leaves the decoded block identical, so it costs nothing where it does nothing.
+ *
+ * @param {Int32Array} endpoints six values, `R0 R1 G0 G1 B0 B1`, modified in place
+ * @param {Uint8Array} weights sixteen weight *levels* (not unquantized), modified in place
+ * @param {number} top the highest weight level, so the inversion knows its own range
+ */
+export function astc_order_endpoints(endpoints, weights, top) {
+    const first = endpoints[0] + endpoints[2] + endpoints[4];
+    const second = endpoints[1] + endpoints[3] + endpoints[5];
+
+    if (second >= first) {
+        return;
+    }
+
+    for (let channel = 0; channel < 3; channel++) {
+        const swap = endpoints[channel * 2];
+
+        endpoints[channel * 2] = endpoints[channel * 2 + 1];
+        endpoints[channel * 2 + 1] = swap;
+    }
+
+    for (let texel = 0; texel < 16; texel++) {
+        weights[texel] = top - weights[texel];
+    }
+}
+
+/**
+ * Write one single-partition, mode-8 ASTC block: header and endpoints from the bottom, weights from
+ * the top.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {Int32Array} endpoints six values, `R0 R1 G0 G1 B0 B1`
+ * @param {Uint8Array} weights sixteen weight levels, in raster order
+ * @param {number} weight_bits 2 or 3
+ */
+export function astc_write_block(out, offset, endpoints, weights, weight_bits) {
+    let block = BigInt(ASTC_BLOCK_MODE[weight_bits]);
+
+    // partition count - 1, at bits 11..12, is zero: one partition
+
+    block |= BigInt(CEM_LDR_RGB_DIRECT) << 13n;
+
+    for (let i = 0; i < 6; i++) {
+        block |= BigInt(endpoints[i]) << BigInt(ENDPOINT_BIT + i * 8);
+    }
+
+    /*
+     The weights fill the top of the block with the whole field's bit order reversed — the first
+     texel's weight ends up in the block's most significant bits. Building the field the natural way
+     round and mirroring it once is easier to read than writing each weight to a computed bit, and is
+     the same thing.
+    */
+    let field = 0n;
+
+    for (let texel = 0; texel < 16; texel++) {
+        field |= BigInt(weights[texel]) << BigInt(texel * weight_bits);
+    }
+
+    const width = 16 * weight_bits;
+
+    for (let i = 0; i < width; i++) {
+        if ((field >> BigInt(i)) & 1n) {
+            block |= 1n << BigInt(127 - i);
+        }
+    }
+
+    for (let i = 0; i < ASTC_BLOCK_BYTES; i++) {
+        out[offset + i] = Number((block >> BigInt(i * 8)) & 0xFFn);
+    }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * The five trits packed into one eight-bit group, as the specification's decode produces them.
+ *
+ * **Written as the decoder and inverted, rather than as an encoder.** The specification gives this
+ * direction only — it says outright that encoding is left to the implementation and that a table
+ * works well — so the honest way to get the table is to run the normative procedure over all 256
+ * inputs and read it backwards. A hand-written encoder would be a second reading of the same rules
+ * with nothing to check it against; this one cannot disagree with the decoder because it *is* the
+ * decoder.
+ *
+ * @param {number} packed eight bits
+ * @returns {number[]} five trits
+ */
+export function astc_unpack_trits(packed: number): number[];
+/**
+ * The three quints packed into one seven-bit group.
+ *
+ * @param {number} packed seven bits
+ * @returns {number[]} three quints
+ * @see astc_unpack_trits for why this is the decode rather than an encode
+ */
+export function astc_unpack_quints(packed: number): number[];
+/**
+ * Write a sequence of quantized values into an ASTC block as an integer sequence.
+ *
+ * **The interleaving is the whole of it.** A trit-based sequence goes five values at a time: the
+ * eight bits that carry their trits are cut into pieces and threaded *between* the values' plain
+ * bits, so the group occupies `5 * bits + 8` bits with nothing contiguous. Quints do the same three
+ * at a time over seven bits. A pure-bit range is the easy case and just runs.
+ *
+ * The piece boundaries below — two bits, then two, then one, then two, then one — are the
+ * specification's, and they are what a reader expects to find where. Getting them wrong produces a
+ * block whose every endpoint is somebody else's.
+ *
+ * @param {(value: number, width: number) => void} write appends `width` bits, least significant first
+ * @param {number[]|Uint8Array} values quantized, each below the range's level count
+ * @param {number} range_index into {@link ASTC_RANGE}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function astc_write_integer_sequence(write: (value: number, width: number) => void, values: number[] | Uint8Array, range_index: number): void;
+/**
+ * ASTC's quantization ranges, by the index a block mode or endpoint field names.
+ *
+ * Each is some number of plain bits, optionally multiplied by a trit (three values) or a quint
+ * (five) — which is how the format reaches level counts that are not powers of two without wasting
+ * the fraction of a bit a naive packing would.
+ *
+ * @readonly
+ * @type {{levels: number, bits: number, trits: number, quints: number}[]}
+ */
+export const ASTC_RANGE: {
+    levels: number;
+    bits: number;
+    trits: number;
+    quints: number;
+}[];
+//# sourceMappingURL=astc_integer_sequence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"astc_integer_sequence.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/basis/astc_integer_sequence.js"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;GAYG;AACH,0CAHW,MAAM,GACJ,MAAM,EAAE,CAgDpB;AAED;;;;;;GAMG;AACH,2CAJW,MAAM,GACJ,MAAM,EAAE,CAiCpB;AA0CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,2DAPmB,MAAM,SAAS,MAAM,KAAK,IAAI,UACtC,MAAM,EAAE,GAAC,UAAU,eACnB,MAAM,QAiDhB;AA7OD;;;;;;;;;GASG;AACH,yBAFU;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,EAAE,CAwBvE"}

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

@@ -0,0 +1,251 @@
+/**
+ * ASTC's quantization ranges, by the index a block mode or endpoint field names.
+ *
+ * Each is some number of plain bits, optionally multiplied by a trit (three values) or a quint
+ * (five) — which is how the format reaches level counts that are not powers of two without wasting
+ * the fraction of a bit a naive packing would.
+ *
+ * @readonly
+ * @type {{levels: number, bits: number, trits: number, quints: number}[]}
+ */
+export const ASTC_RANGE = [
+    { levels: 2, bits: 1, trits: 0, quints: 0 },
+    { levels: 3, bits: 0, trits: 1, quints: 0 },
+    { levels: 4, bits: 2, trits: 0, quints: 0 },
+    { levels: 5, bits: 0, trits: 0, quints: 1 },
+    { levels: 6, bits: 1, trits: 1, quints: 0 },
+    { levels: 8, bits: 3, trits: 0, quints: 0 },
+    { levels: 10, bits: 1, trits: 0, quints: 1 },
+    { levels: 12, bits: 2, trits: 1, quints: 0 },
+    { levels: 16, bits: 4, trits: 0, quints: 0 },
+    { levels: 20, bits: 2, trits: 0, quints: 1 },
+    { levels: 24, bits: 3, trits: 1, quints: 0 },
+    { levels: 32, bits: 5, trits: 0, quints: 0 },
+    { levels: 40, bits: 3, trits: 0, quints: 1 },
+    { levels: 48, bits: 4, trits: 1, quints: 0 },
+    { levels: 64, bits: 6, trits: 0, quints: 0 },
+    { levels: 80, bits: 4, trits: 0, quints: 1 },
+    { levels: 96, bits: 5, trits: 1, quints: 0 },
+    { levels: 128, bits: 7, trits: 0, quints: 0 },
+    { levels: 160, bits: 5, trits: 0, quints: 1 },
+    { levels: 192, bits: 6, trits: 1, quints: 0 },
+    { levels: 256, bits: 8, trits: 0, quints: 0 },
+];
+
+/**
+ * The five trits packed into one eight-bit group, as the specification's decode produces them.
+ *
+ * **Written as the decoder and inverted, rather than as an encoder.** The specification gives this
+ * direction only — it says outright that encoding is left to the implementation and that a table
+ * works well — so the honest way to get the table is to run the normative procedure over all 256
+ * inputs and read it backwards. A hand-written encoder would be a second reading of the same rules
+ * with nothing to check it against; this one cannot disagree with the decoder because it *is* the
+ * decoder.
+ *
+ * @param {number} packed eight bits
+ * @returns {number[]} five trits
+ */
+export function astc_unpack_trits(packed) {
+    const bit = index => (packed >> index) & 1;
+    const field = (high, low) => (packed >> low) & ((1 << (high - low + 1)) - 1);
+
+    let c;
+    let t3;
+    let t4;
+
+    if (field(4, 2) === 0b111) {
+        c = (field(7, 5) << 2) | field(1, 0);
+        t4 = 2;
+        t3 = 2;
+    } else {
+        c = field(4, 0);
+
+        if (field(6, 5) === 0b11) {
+            t4 = 2;
+            t3 = bit(7);
+        } else {
+            t4 = bit(7);
+            t3 = field(6, 5);
+        }
+    }
+
+    const c_bit = index => (c >> index) & 1;
+    const c_field = (high, low) => (c >> low) & ((1 << (high - low + 1)) - 1);
+
+    let t0;
+    let t1;
+    let t2;
+
+    if (c_field(1, 0) === 0b11) {
+        t2 = 2;
+        t1 = c_bit(4);
+        t0 = (c_bit(3) << 1) | (c_bit(2) & ~c_bit(3) & 1);
+    } else if (c_field(3, 2) === 0b11) {
+        t2 = 2;
+        t1 = 2;
+        t0 = c_field(1, 0);
+    } else {
+        t2 = c_bit(4);
+        t1 = c_field(3, 2);
+        t0 = (c_bit(1) << 1) | (c_bit(0) & ~c_bit(1) & 1);
+    }
+
+    return [t0, t1, t2, t3, t4];
+}
+
+/**
+ * The three quints packed into one seven-bit group.
+ *
+ * @param {number} packed seven bits
+ * @returns {number[]} three quints
+ * @see astc_unpack_trits for why this is the decode rather than an encode
+ */
+export function astc_unpack_quints(packed) {
+    const bit = index => (packed >> index) & 1;
+    const field = (high, low) => (packed >> low) & ((1 << (high - low + 1)) - 1);
+
+    if (field(2, 1) === 0b11 && field(6, 5) === 0b00) {
+        const q2 = (bit(0) << 2)
+            | ((bit(4) & ~bit(0) & 1) << 1)
+            | (bit(3) & ~bit(0) & 1);
+
+        return [4, 4, q2];
+    }
+
+    let q2;
+    let c;
+
+    if (field(2, 1) === 0b11) {
+        q2 = 4;
+        c = (field(4, 3) << 3) | ((~field(6, 5) & 0b11) << 1) | bit(0);
+    } else {
+        q2 = field(6, 5);
+        c = field(4, 0);
+    }
+
+    const c_field = (high, low) => (c >> low) & ((1 << (high - low + 1)) - 1);
+
+    if (c_field(2, 0) === 0b101) {
+        return [c_field(4, 3), 4, q2];
+    }
+
+    return [c_field(2, 0), c_field(4, 3), q2];
+}
+
+/**
+ * Build the inverse of an unpacker: digit tuple to the group that decodes to it.
+ *
+ * @param {(packed: number) => number[]} unpack
+ * @param {number} group_values how many digits a group holds
+ * @param {number} radix 3 or 5
+ * @returns {Int32Array} indexed by the digits read as a base-`radix` number, least significant first
+ */
+function invert(unpack, group_values, radix) {
+    const table = new Int32Array(radix ** group_values).fill(-1);
+
+    for (let packed = 0; packed < (1 << (group_values === 5 ? 8 : 7)); packed++) {
+        const digits = unpack(packed);
+
+        let key = 0;
+
+        for (let i = group_values - 1; i >= 0; i--) {
+            key = key * radix + digits[i];
+        }
+
+        if (table[key] === -1) {
+            table[key] = packed;
+        }
+    }
+
+    return table;
+}
+
+/**
+ * Digits to packed group, for trits and for quints.
+ *
+ * Every combination is reachable — 243 of the 256 trit groups and 125 of the 128 quint groups are
+ * distinct, and the spare encodings are duplicates rather than gaps. `astc_integer_sequence.spec.js`
+ * asserts that, which is what makes the inversion safe to rely on.
+ *
+ * @readonly
+ */
+const TRIT_GROUP = invert(astc_unpack_trits, 5, 3);
+const QUINT_GROUP = invert(astc_unpack_quints, 3, 5);
+
+/**
+ * Write a sequence of quantized values into an ASTC block as an integer sequence.
+ *
+ * **The interleaving is the whole of it.** A trit-based sequence goes five values at a time: the
+ * eight bits that carry their trits are cut into pieces and threaded *between* the values' plain
+ * bits, so the group occupies `5 * bits + 8` bits with nothing contiguous. Quints do the same three
+ * at a time over seven bits. A pure-bit range is the easy case and just runs.
+ *
+ * The piece boundaries below — two bits, then two, then one, then two, then one — are the
+ * specification's, and they are what a reader expects to find where. Getting them wrong produces a
+ * block whose every endpoint is somebody else's.
+ *
+ * @param {(value: number, width: number) => void} write appends `width` bits, least significant first
+ * @param {number[]|Uint8Array} values quantized, each below the range's level count
+ * @param {number} range_index into {@link ASTC_RANGE}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function astc_write_integer_sequence(write, values, range_index) {
+    const range = ASTC_RANGE[range_index];
+
+    const { bits } = range;
+
+    if (range.trits === 0 && range.quints === 0) {
+        for (const value of values) {
+            write(value, bits);
+        }
+
+        return;
+    }
+
+    const group_values = range.trits === 1 ? 5 : 3;
+    const radix = range.trits === 1 ? 3 : 5;
+
+    // how the packed group's bits are split up and threaded between the values
+    const cuts = range.trits === 1 ? [2, 2, 1, 2, 1] : [3, 2, 2];
+
+    for (let start = 0; start < values.length; start += group_values) {
+        let key = 0;
+
+        for (let i = group_values - 1; i >= 0; i--) {
+            const value = start + i < values.length ? values[start + i] : 0;
+
+            key = key * radix + (value >> bits);
+        }
+
+        const packed = range.trits === 1 ? TRIT_GROUP[key] : QUINT_GROUP[key];
+
+        let consumed = 0;
+
+        for (let i = 0; i < group_values; i++) {
+            if (start + i < values.length) {
+                write(values[start + i] & ((1 << bits) - 1), bits);
+            } else if (bits > 0) {
+                write(0, bits);
+            }
+
+            write((packed >> consumed) & ((1 << cuts[i]) - 1), cuts[i]);
+
+            consumed += cuts[i];
+        }
+    }
+}
+
+/*
+ There is deliberately no "how many bits does this sequence take" helper here.
+
+ One was written and removed: it charged a partial trailing group a whole packed field, which
+ over-reports — ASTC's own size rule gives a partial group only the bits it needs. Nothing used it,
+ and a size function that disagrees with the writer beside it is a trap rather than a convenience.
+
+ What the writer relies on instead is that padding a partial group with zeros keeps its high bits
+ zero, so the run never reaches the weight field even where the cursor formally passes it. That is
+ asserted over every mode and every trailing-group value in `uastc_to_astc.spec.js` rather than
+ assumed here.
+*/

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

@@ -0,0 +1,56 @@
+/**
+ * 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: number, x: number, y: number, partition_count: number): number;
+/**
+ * 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: number, partition_count: number): Uint8Array;
+/**
+ * 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: Uint8Array, partition_count: number): {
+    seed: number;
+    permutation: number[];
+} | undefined;
+//# sourceMappingURL=astc_partition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"astc_partition.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/basis/astc_partition.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CAVW,MAAM,KACN,MAAM,KACN,MAAM,mBACN,MAAM,GACJ,MAAM,CAiFlB;AAED;;;;;;GAMG;AACH,6CAJW,MAAM,mBACN,MAAM,GACJ,UAAU,CAYtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iDALW,UAAU,mBACV,MAAM,GACJ;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAC,GAAC,SAAS,CAmC3D"}