@woosh/meep-engine 3.14.0 → 3.14.2

package/src/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;
+    }
+}

package/src/basis/etc1s/etc1s_read_slice_tables.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The Huffman tables every slice in a file is decoded with, plus the size of the selector history.
+ *
+ * They are global rather than per-slice — one set covers every mip level, face and frame — which is
+ * what makes a mip chain cost little more than its base level.
+ *
+ * @typedef {object} Etc1sSliceTables
+ * @property {BasisHuffmanTable} endpoint_pred how each block in a 2x2 group takes its endpoint
+ * @property {BasisHuffmanTable} delta_endpoint an endpoint index, relative to the previous block's
+ * @property {BasisHuffmanTable} selector a selector index, a history reference, or a run
+ * @property {BasisHuffmanTable} selector_history_rle the length of such a run
+ * @property {number} selector_history_size entries in the move-to-front list
+ */
+/**
+ * Read the four slice-decoding Huffman tables and the selector history size.
+ *
+ * @param {Uint8Array} data the tables section of the global data
+ * @returns {Etc1sSliceTables}
+ * @throws {Error} for a section that runs out before the four tables do
+ * @see the specification, section 9.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_slice_tables(data: Uint8Array): Etc1sSliceTables;
+/**
+ * The Huffman tables every slice in a file is decoded with, plus the size of the selector history.
+ *
+ * They are global rather than per-slice — one set covers every mip level, face and frame — which is
+ * what makes a mip chain cost little more than its base level.
+ */
+export type Etc1sSliceTables = {
+    /**
+     * how each block in a 2x2 group takes its endpoint
+     */
+    endpoint_pred: BasisHuffmanTable;
+    /**
+     * an endpoint index, relative to the previous block's
+     */
+    delta_endpoint: BasisHuffmanTable;
+    /**
+     * a selector index, a history reference, or a run
+     */
+    selector: BasisHuffmanTable;
+    /**
+     * the length of such a run
+     */
+    selector_history_rle: BasisHuffmanTable;
+    /**
+     * entries in the move-to-front list
+     */
+    selector_history_size: number;
+};
+//# sourceMappingURL=etc1s_read_slice_tables.d.ts.map

package/src/basis/etc1s/etc1s_read_slice_tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_read_slice_tables.d.ts","sourceRoot":"","sources":["../../../../src/basis/etc1s/etc1s_read_slice_tables.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;GAUG;AACH,8CARW,UAAU,GACR,gBAAgB,CAyB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAhCa,MAAM"}

package/src/basis/etc1s/etc1s_read_slice_tables.js

@@ -0,0 +1,47 @@
+import { BasisBitReader } from "../BasisBitReader.js";
+import { basis_read_huffman_table } from "../basis_read_huffman_table.js";
+
+/**
+ * The Huffman tables every slice in a file is decoded with, plus the size of the selector history.
+ *
+ * They are global rather than per-slice — one set covers every mip level, face and frame — which is
+ * what makes a mip chain cost little more than its base level.
+ *
+ * @typedef {object} Etc1sSliceTables
+ * @property {BasisHuffmanTable} endpoint_pred how each block in a 2x2 group takes its endpoint
+ * @property {BasisHuffmanTable} delta_endpoint an endpoint index, relative to the previous block's
+ * @property {BasisHuffmanTable} selector a selector index, a history reference, or a run
+ * @property {BasisHuffmanTable} selector_history_rle the length of such a run
+ * @property {number} selector_history_size entries in the move-to-front list
+ */
+
+/**
+ * Read the four slice-decoding Huffman tables and the selector history size.
+ *
+ * @param {Uint8Array} data the tables section of the global data
+ * @returns {Etc1sSliceTables}
+ * @throws {Error} for a section that runs out before the four tables do
+ * @see the specification, section 9.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_read_slice_tables(data) {
+    const reader = new BasisBitReader().init(data);
+
+    const endpoint_pred = basis_read_huffman_table(reader);
+    const delta_endpoint = basis_read_huffman_table(reader);
+    const selector = basis_read_huffman_table(reader);
+    const selector_history_rle = basis_read_huffman_table(reader);
+
+    const selector_history_size = reader.bits(13);
+
+    // "Any remaining bits may be safely ignored" — the section is padded to a byte boundary
+    return {
+        endpoint_pred,
+        delta_endpoint,
+        selector,
+        selector_history_rle,
+        selector_history_size,
+    };
+}

package/src/basis/transcode/build_range_plan.js

@@ -0,0 +1,54 @@
+import { SELECTOR_RANGES, selector_codebook_ranges } from "./fit_endpoints.js";
+
+/**
+ * Which selector spans a file's codebook actually contains, and where each entry's span sits.
+ *
+ * Endpoints are fitted per (endpoint entry, selector span) pairing, and there are ten possible
+ * spans — but a real file uses only a few of them, and building a fit for spans no block has would
+ * be most of the work for none of the benefit. So the spans present are collected first and the
+ * templates are allocated against those alone.
+ *
+ * @typedef {object} Etc1sRangePlan
+ * @property {number} slot_count how many distinct spans the codebook contains
+ * @property {Uint8Array} range_of_slot the {@link SELECTOR_RANGES} index each slot stands for
+ * @property {Uint8Array} slot_of_entry one slot per selector codebook entry
+ */
+
+/**
+ * Work out the {@link Etc1sRangePlan} for a selector codebook.
+ *
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Etc1sRangePlan}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function build_range_plan(selectors) {
+    const range_of_entry = selector_codebook_ranges(selectors);
+
+    const slot_of_range = new Int32Array(SELECTOR_RANGES.length).fill(-1);
+
+    const range_of_slot_list = [];
+
+    for (let entry = 0; entry < range_of_entry.length; entry++) {
+        const range = range_of_entry[entry];
+
+        if (slot_of_range[range] < 0) {
+            slot_of_range[range] = range_of_slot_list.length;
+
+            range_of_slot_list.push(range);
+        }
+    }
+
+    const slot_of_entry = new Uint8Array(range_of_entry.length);
+
+    for (let entry = 0; entry < range_of_entry.length; entry++) {
+        slot_of_entry[entry] = slot_of_range[range_of_entry[entry]];
+    }
+
+    return {
+        slot_count: range_of_slot_list.length,
+        range_of_slot: Uint8Array.from(range_of_slot_list),
+        slot_of_entry,
+    };
+}

package/src/basis/transcode/etc1s_to_bc1.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Transcode a decoded ETC1S slice to BC1.
+ *
+ * **Both formats put four colours on a line, which is what makes this cheap and good.** An ETC1S
+ * block is a base colour plus an intensity modifier applied equally to all three channels, so its
+ * four colours are collinear; BC1's are two endpoints plus two interpolants, which is the same
+ * shape. The transcode is therefore a re-parameterisation rather than a re-quantisation, and what it
+ * loses is only what 5:6:5 endpoints lose over ETC1S's 5:5:5-plus-modifier.
+ *
+ * **The work is per endpoint codebook entry, not per block.** A block's four colours depend only on
+ * which endpoint entry it names, so the endpoint pair and the selector-to-index mapping are computed
+ * once per entry — of which there are at most a few thousand — and every block that names it just
+ * writes them out. A texture is typically tens of thousands of blocks over a few hundred entries.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed BC1 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_bc1(slice: Etc1sSlice, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook): Uint8Array;
+//# sourceMappingURL=etc1s_to_bc1.d.ts.map

package/src/basis/transcode/etc1s_to_bc1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_bc1.d.ts","sourceRoot":"","sources":["../../../../src/basis/transcode/etc1s_to_bc1.js"],"names":[],"mappings":"AA0EA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qHALa,UAAU,CAuCtB"}

package/src/basis/transcode/etc1s_to_bc1.js

@@ -0,0 +1,205 @@
+import { etc1s_block_colors } from "../etc1s/etc1s_block_colors.js";
+
+/**
+ * Bytes one BC1 block occupies: two 16-bit endpoints and sixteen 2-bit indices.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BC1_BLOCK_BYTES = 8;
+
+/**
+ * Pack an eight-bit-per-channel colour into BC1's 5:6:5 endpoint.
+ *
+ * Rounding rather than truncating: truncation biases every endpoint darker, and over a whole texture
+ * that reads as a gamma shift rather than as noise.
+ *
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {number} sixteen bits
+ */
+function pack565(r, g, b) {
+    const r5 = Math.min(31, (r * 31 + 127) / 255 | 0);
+    const g6 = Math.min(63, (g * 63 + 127) / 255 | 0);
+    const b5 = Math.min(31, (b * 31 + 127) / 255 | 0);
+
+    return (r5 << 11) | (g6 << 5) | b5;
+}
+
+/**
+ * The eight-bit colour a 5:6:5 endpoint decodes to, by the same bit replication hardware uses.
+ *
+ * @param {Uint8Array} out
+ * @param {number} offset
+ * @param {number} packed
+ */
+function unpack565(out, offset, packed) {
+    const r5 = (packed >> 11) & 31;
+    const g6 = (packed >> 5) & 63;
+    const b5 = packed & 31;
+
+    out[offset] = (r5 << 3) | (r5 >> 2);
+    out[offset + 1] = (g6 << 2) | (g6 >> 4);
+    out[offset + 2] = (b5 << 3) | (b5 >> 2);
+}
+
+/**
+ * Which of BC1's four colours best matches a target, given the block's decoded palette.
+ *
+ * @param {Uint8Array} palette twelve bytes, four `[r, g, b]` triples in BC1 index order
+ * @param {Uint8Array} target three bytes
+ * @param {number} target_offset
+ * @returns {number} `0` to `3`
+ */
+function closest_index(palette, target, target_offset) {
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < 4; i++) {
+        const dr = palette[i * 3] - target[target_offset];
+        const dg = palette[i * 3 + 1] - target[target_offset + 1];
+        const db = palette[i * 3 + 2] - target[target_offset + 2];
+
+        const error = dr * dr + dg * dg + db * db;
+
+        if (error < best_error) {
+            best_error = error;
+            best = i;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Transcode a decoded ETC1S slice to BC1.
+ *
+ * **Both formats put four colours on a line, which is what makes this cheap and good.** An ETC1S
+ * block is a base colour plus an intensity modifier applied equally to all three channels, so its
+ * four colours are collinear; BC1's are two endpoints plus two interpolants, which is the same
+ * shape. The transcode is therefore a re-parameterisation rather than a re-quantisation, and what it
+ * loses is only what 5:6:5 endpoints lose over ETC1S's 5:5:5-plus-modifier.
+ *
+ * **The work is per endpoint codebook entry, not per block.** A block's four colours depend only on
+ * which endpoint entry it names, so the endpoint pair and the selector-to-index mapping are computed
+ * once per entry — of which there are at most a few thousand — and every block that names it just
+ * writes them out. A texture is typically tens of thousands of blocks over a few hundred entries.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed BC1 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_bc1(slice, endpoints, selectors) {
+    const plan = build_range_plan(selectors);
+
+    const templates = build_templates(endpoints, plan);
+
+    const block_count = slice.blocks_x * slice.blocks_y;
+
+    const out = new Uint8Array(block_count * BC1_BLOCK_BYTES);
+
+    for (let block = 0; block < block_count; block++) {
+        const selector_entry = slice.selector_index[block];
+        const selector_base = selector_entry * 16;
+
+        const pairing = slice.endpoint_index[block] * plan.slot_count
+            + plan.slot_of_entry[selector_entry];
+
+        const low = templates.low[pairing];
+        const high = templates.high[pairing];
+        const map = pairing * 4;
+
+        const o = block * BC1_BLOCK_BYTES;
+
+        out[o] = low & 255;
+        out[o + 1] = low >> 8;
+        out[o + 2] = high & 255;
+        out[o + 3] = high >> 8;
+
+        for (let row = 0; row < 4; row++) {
+            const base = selector_base + row * 4;
+
+            out[o + 4 + row] =
+                templates.selector_to_index[map + selectors.selectors[base]]
+                | (templates.selector_to_index[map + selectors.selectors[base + 1]] << 2)
+                | (templates.selector_to_index[map + selectors.selectors[base + 2]] << 4)
+                | (templates.selector_to_index[map + selectors.selectors[base + 3]] << 6);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * The BC1 endpoint pair and selector mapping for every entry of the endpoint codebook.
+ *
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @returns {{low: Uint16Array, high: Uint16Array, selector_to_index: Uint8Array}} `low` is written
+ * first, and is the larger of the pair so the block decodes in four-colour mode
+ */
+function build_templates(endpoints) {
+    const count = endpoints.count;
+
+    const low = new Uint16Array(count);
+    const high = new Uint16Array(count);
+    const selector_to_index = new Uint8Array(count * 4);
+
+    const colors = new Uint8Array(12);
+    const palette = new Uint8Array(12);
+
+    for (let entry = 0; entry < count; entry++) {
+        etc1s_block_colors(colors, 0, endpoints.color5, endpoints.intensity, entry);
+
+        /*
+         The darkest and brightest of the four span the line; the middle two are recovered by BC1's
+         own interpolants, which sit at one and two thirds. ETC1S's middle colours are not exactly
+         there — the modifier table is not evenly spaced — so they are matched rather than assumed.
+        */
+        let first = pack565(colors[9], colors[10], colors[11]);
+        let second = pack565(colors[0], colors[1], colors[2]);
+
+        /*
+         Four-colour mode needs the first endpoint to compare greater. Equal endpoints would select
+         three-colour mode, whose fourth index is transparent black — so they are nudged apart, which
+         is invisible because the block is a single colour either way.
+        */
+        if (first < second) {
+            const swap = first;
+
+            first = second;
+            second = swap;
+        }
+
+        if (first === second) {
+            second = first === 0 ? 0 : first - 1;
+        }
+
+        low[entry] = first;
+        high[entry] = second;
+
+        unpack565(palette, 0, first);
+        unpack565(palette, 3, second);
+
+        /*
+         The specification's interpolants, truncating rather than rounding. It matters only that the
+         same arithmetic is used here and by whatever decodes the result: these colours exist to pick
+         indices, and picking them against a palette a decoder will not produce is how a transcoder
+         ends up half a level off everywhere.
+        */
+        for (let c = 0; c < 3; c++) {
+            palette[6 + c] = (2 * palette[c] + palette[3 + c]) / 3 | 0;
+            palette[9 + c] = (palette[c] + 2 * palette[3 + c]) / 3 | 0;
+        }
+
+        for (let selector = 0; selector < 4; selector++) {
+            selector_to_index[entry * 4 + selector] = closest_index(palette, colors, selector * 3);
+        }
+    }
+
+    return { low, high, selector_to_index };
+}

package/src/basis/transcode/etc1s_to_bc7.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transcode a decoded ETC1S slice to BC7.
+ *
+ * **Two modes, chosen by whether the payload carries alpha, because BC7 cannot do both at once.**
+ * Mode 6 gives one index per texel, shared by all four channels, with four bits of it; mode 5 gives
+ * colour and alpha their own indices but only two bits each. An opaque payload wants the finer
+ * index; an alpha payload needs the independent one, because an ETC1S file's alpha slice has its own
+ * selectors, unrelated to the colour slice's, and a shared index could not express both.
+ *
+ * Neither mode loses much to ETC1S, for the reason {@link etc1s_to_bc1} spells out: an ETC1S block's
+ * four colours lie on a line, which is the shape both modes store natively. Mode 5's two-bit index
+ * is in fact an exact structural match — four colours, four index values — and gives up only the
+ * freedom to place the middle two, which ETC1S's modifier table has already fixed.
+ *
+ * **The work is per codebook entry, not per block.** A block's colours depend only on which endpoint
+ * entry it names, so endpoints and the selector-to-index mapping are computed once per entry and
+ * every block that names it just writes them out. Colour and alpha are tabulated separately, which
+ * is what lets mode 5 pair any colour entry with any alpha entry without a table of their product.
+ *
+ * @param {Etc1sSlice} slice the colour slice
+ * @param {Etc1sSlice|undefined} alpha_slice the alpha slice, when the payload has one
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed BC7 blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_bc7(slice: Etc1sSlice, alpha_slice: Etc1sSlice | undefined, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook): Uint8Array;
+//# sourceMappingURL=etc1s_to_bc7.d.ts.map

package/src/basis/transcode/etc1s_to_bc7.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_bc7.d.ts","sourceRoot":"","sources":["../../../../src/basis/transcode/etc1s_to_bc7.js"],"names":[],"mappings":"AA4FA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,6DARW,aAAW,SAAS,uEAGlB,UAAU,CAStB"}