@woosh/meep-engine 3.14.2 → 3.14.3

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.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_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_slice_tables.d.ts.map

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

package/src/format/texture/basis/transcode/build_range_plan.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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: Etc1sSelectorCodebook): Etc1sRangePlan;
+/**
+ * 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.
+ */
+export type Etc1sRangePlan = {
+    /**
+     * how many distinct spans the codebook contains
+     */
+    slot_count: number;
+    /**
+     * the {@link SELECTOR_RANGES } index each slot stands for
+     */
+    range_of_slot: Uint8Array;
+    /**
+     * one slot per selector codebook entry
+     */
+    slot_of_entry: Uint8Array;
+};
+//# sourceMappingURL=build_range_plan.d.ts.map

package/src/format/texture/basis/transcode/build_range_plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build_range_plan.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/build_range_plan.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,oEALa,cAAc,CAiC1B;;;;;;;;;;;;;gBA1Ca,MAAM;;;;mBACN,UAAU;;;;mBACV,UAAU"}

package/src/format/texture/basis/transcode/etc1s_to_astc.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Transcode ETC1S to ASTC 4x4.
+ *
+ * **The mobile counterpart to {@link etc1s_to_etc2}**, and the one compressed format that appears in
+ * every role's preference list — every recent phone samples it, where ETC2 is the older floor. Both
+ * are eight bits a texel.
+ *
+ * **A close fit, because an ETC1S block is already a line.** Its four colours are one base colour
+ * plus the same offset in each channel, so they lie on a line parallel to the grey axis, which is
+ * exactly what a single-partition ASTC block with two endpoints and an interpolant represents. What
+ * is left is choosing where on that line the four weight levels sit, which {@link fit_block} searches.
+ *
+ * **Opaque only.** ASTC can carry alpha, but not with a shared weight plane: an ETC1S payload's
+ * colour and alpha come from two independent slices with their own selectors, and forcing them onto
+ * one set of weights would wreck both. The dual-plane block mode that would separate them cannot also
+ * hold eight endpoints and thirty-two weight bits in 128 bits. So this declares no alpha and a
+ * payload carrying some falls through to a target that has room — the mechanism BC1 has used since
+ * step 9, and which `ktx2_read` now applies before a format is committed to rather than after.
+ *
+ * @param {Etc1sSlice} slice
+ * @param {Etc1sSlice|undefined} _alpha_slice refused before this is called; see above
+ * @param {Etc1sEndpointCodebook} endpoints
+ * @param {Etc1sSelectorCodebook} selectors
+ * @returns {Uint8Array} tightly packed ASTC blocks, in raster order
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_to_astc(slice: Etc1sSlice, _alpha_slice: Etc1sSlice | undefined, endpoints: Etc1sEndpointCodebook, selectors: Etc1sSelectorCodebook): Uint8Array;
+//# sourceMappingURL=etc1s_to_astc.d.ts.map

package/src/format/texture/basis/transcode/etc1s_to_astc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_to_astc.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/etc1s_to_astc.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+DARW,aAAW,SAAS,uEAGlB,UAAU,CA6BtB"}