@woosh/meep-engine 3.14.2 → 3.14.4

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"}

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.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/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/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_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"}