@woosh/meep-engine 3.14.2 → 3.14.4

package/src/basis/BasisBitReader.js

@@ -1,231 +0,0 @@
-/**
- * Bits are consumed into a 32-bit accumulator; this is how many it may hold.
- *
- * @readonly
- * @type {number}
- */
-const ACCUMULATOR_CAPACITY = 32;
-
-/**
- * LSB-first bit cursor over a byte range, with the speculative peek a Huffman decoder needs.
- *
- * **Why this is not {@link BitReader}.** `avif/native/bitstream/BitReader.js` is the other bit
- * reader in this tree and it does not fit, for two reasons that are about the format rather than
- * about convenience:
- *
- * 1. **It is MSB-first, and Basis is LSB-first.** The specification is explicit — "Huffman codes are
- *    stored in each output byte in LSB to MSB order. (This is opposite of the JPEG format)". Bit
- *    order is not a parameter that could be added the way {@link ByteCursor} took a byte order:
- *    a byte order is a property of a *field*, applied once per read, while a bit order changes what
- *    the single-bit primitive means and so changes every accessor beneath it.
- * 2. **Huffman decoding needs peek-then-consume, which a descriptor reader has no reason to offer.**
- *    A canonical code's length is not known until it has been looked up, so the decoder reads bits
- *    it may not consume. `BitReader`'s `f(n)` is sequential by construction.
- *
- * One class doing both would be a flag on every method. So this is a second bit reader,
- * deliberately, and it stays in `basis/` rather than moving to `core/binary/` until something other
- * than Basis wants it — the same rule `ByteCursor` moved under, applied in the direction that says
- * "not yet".
- *
- * **Peeking past the end reads zeros; consuming past it throws.** The two have to differ. A Huffman
- * peek is speculative and legitimately runs off the end of a section — the last code in a stream is
- * rarely flush with a byte boundary — so refusing there would refuse well-formed files. Consuming is
- * a different claim, and a stream that runs out mid-symbol is corrupt.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class BasisBitReader {
-    /**
-     * Bytes being read. Not owned.
-     * @type {Uint8Array}
-     */
-    #data = null;
-
-    /**
-     * Index into {@link #data} of the next byte to pull into {@link #accumulator}.
-     * @type {number}
-     */
-    #byte_position = 0;
-
-    /**
-     * Index into {@link #data} one past the last readable byte.
-     * @type {number}
-     */
-    #end = 0;
-
-    /**
-     * Buffered bits, least significant first. Only the low {@link #bit_count} are meaningful.
-     * @type {number}
-     */
-    #accumulator = 0;
-
-    /**
-     * How many of {@link #accumulator}'s bits are meaningful.
-     * @type {number}
-     */
-    #bit_count = 0;
-
-    /**
-     * Bits of {@link #accumulator} that were manufactured past {@link #end} rather than read.
-     *
-     * They sit at the most significant end, since that is where a refill puts them. Consuming far
-     * enough to reach them is the overrun that throws.
-     *
-     * @type {number}
-     */
-    #phantom_bits = 0;
-
-    /**
-     * Point the reader at a byte range.
-     *
-     * @param {Uint8Array} data
-     * @param {number} [byte_offset]
-     * @param {number} [byte_length]
-     * @returns {BasisBitReader} this
-     * @throws {Error} for a range outside `data`
-     */
-    init(data, byte_offset = 0, byte_length = data.length - byte_offset) {
-        if (byte_offset < 0 || byte_length < 0 || byte_offset + byte_length > data.length) {
-            throw new Error(
-                `Basis: a bit reader range of [${byte_offset}, ${byte_offset + byte_length}) is`
-                + ` outside the ${data.length} byte buffer it was given`
-            );
-        }
-
-        this.#data = data;
-        this.#byte_position = byte_offset;
-        this.#end = byte_offset + byte_length;
-        this.#accumulator = 0;
-        this.#bit_count = 0;
-        this.#phantom_bits = 0;
-
-        return this;
-    }
-
-    /**
-     * Fill {@link #accumulator} to at least `count` meaningful bits, manufacturing zeros past the
-     * end of the range.
-     *
-     * @param {number} count
-     */
-    #fill(count) {
-        while (this.#bit_count < count) {
-            const past_end = this.#byte_position >= this.#end;
-
-            const byte = past_end ? 0 : this.#data[this.#byte_position];
-
-            if (past_end) {
-                this.#phantom_bits += 8;
-            }
-
-            this.#byte_position++;
-
-            /*
-             `<<` is a signed 32-bit shift, so a byte landing on bits 24..31 would make the
-             accumulator negative; `>>> 0` puts it back in the unsigned range the masks assume.
-            */
-            this.#accumulator = (this.#accumulator | (byte << this.#bit_count)) >>> 0;
-            this.#bit_count += 8;
-        }
-    }
-
-    /**
-     * Look at the next `count` bits without consuming them. Bits past the end of the range read as
-     * zero — see the note on the class.
-     *
-     * @param {number} count `0` to 24; the Huffman decoder's longest peek is 16
-     * @returns {number}
-     */
-    peek(count) {
-        if (count === 0) {
-            return 0;
-        }
-
-        this.#fill(count);
-
-        return this.#accumulator & ((1 << count) - 1);
-    }
-
-    /**
-     * Drop the next `count` bits.
-     *
-     * @param {number} count
-     * @throws {Error} when the bits dropped were never in the range
-     */
-    consume(count) {
-        if (count === 0) {
-            return;
-        }
-
-        this.#fill(count);
-
-        /*
-         The phantom bits sit at the top of the accumulator, so the bits being consumed are real
-         exactly when the meaningful ones below them outnumber the request.
-        */
-        if (this.#bit_count - this.#phantom_bits < count) {
-            throw new Error(
-                `Basis: the bitstream ended mid-symbol — ${count} bits were asked for and only`
-                + ` ${Math.max(this.#bit_count - this.#phantom_bits, 0)} remain in the section`
-            );
-        }
-
-        this.#accumulator = count === ACCUMULATOR_CAPACITY ? 0 : this.#accumulator >>> count;
-
-        this.#bit_count -= count;
-    }
-
-    /**
-     * Read `count` bits, least significant first.
-     *
-     * @param {number} count `0` to 24
-     * @returns {number}
-     * @throws {Error} when the range does not hold them
-     */
-    bits(count) {
-        const value = this.peek(count);
-
-        this.consume(count);
-
-        return value;
-    }
-
-    /**
-     * The specification's variable-length code: `chunk_bits` of payload plus a continuation bit,
-     * repeated until the continuation bit is clear.
-     *
-     * @param {number} chunk_bits
-     * @returns {number}
-     * @throws {Error} for a code that would not fit in 32 bits, which is a corrupt stream rather
-     * than a large number
-     * @see the specification's `decode_vlc`, section 10.2
-     */
-    vlc(chunk_bits) {
-        const chunk_size = 1 << chunk_bits;
-        const chunk_mask = chunk_size - 1;
-
-        let value = 0;
-        let offset = 0;
-
-        for (; ;) {
-            const chunk = this.bits(chunk_bits + 1);
-
-            value |= (chunk & chunk_mask) << offset;
-            offset += chunk_bits;
-
-            if ((chunk & chunk_size) === 0) {
-                break;
-            }
-
-            if (offset >= ACCUMULATOR_CAPACITY) {
-                throw new Error(
-                    `Basis: a variable-length code ran past ${ACCUMULATOR_CAPACITY} bits without`
-                    + ` terminating, which no valid stream does`
-                );
-            }
-        }
-
-        return value >>> 0;
-    }
-}

package/src/basis/BasisHuffmanTable.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"BasisHuffmanTable.d.ts","sourceRoot":"","sources":["../../../src/basis/BasisHuffmanTable.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,kCAFU,MAAM,CAE2B;AAsB3C;;;;;;;;;;;;;;;;GAgBG;AACH;IAqCI;;;;;;;OAOG;IACH,mBALW,UAAU,GACR,iBAAiB,CAyE7B;IAiDD;;;;;;OAMG;IACH,eAJW,cAAc,GACZ,MAAM,CAuClB;;CACJ;+BAtQ8B,qBAAqB"}

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

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"Etc1sSelectorHistory.d.ts","sourceRoot":"","sources":["../../../../src/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/basis/etc1s/etc1s_block_colors.d.ts.map

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

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

@@ -1 +0,0 @@
-{"version":3,"file":"etc1s_decode_slice.d.ts","sourceRoot":"","sources":["../../../../src/basis/etc1s/etc1s_decode_slice.js"],"names":[],"mappings":"AAsDA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,yCAbW,UAAU,YACV,MAAM,YACN,MAAM,4CAEN,MAAM,kBACN,MAAM,GACJ,UAAU,CAyKtB;;;;;;;;oBAvMa,WAAW;;;;oBACX,WAAW;cACX,MAAM;cACN,MAAM"}

package/src/basis/etc1s/etc1s_decode_slice.js

@@ -1,258 +0,0 @@
-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;
-
-/**
- * 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 === 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/basis/etc1s/etc1s_read_endpoint_codebook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"etc1s_read_endpoint_codebook.d.ts","sourceRoot":"","sources":["../../../../src/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/basis/etc1s/etc1s_read_selector_codebook.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"etc1s_read_selector_codebook.d.ts","sourceRoot":"","sources":["../../../../src/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/basis/etc1s/etc1s_read_slice_tables.d.ts.map

@@ -1 +0,0 @@
-{"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/transcode/etc1s_to_bc1.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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"}