@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/entropy/SymbolReader.js

@@ -0,0 +1,317 @@
+import { floor_log2 } from "../util/floor_log2.js";
+import { EC_MIN_PROB, EC_PROB_SHIFT } from "../tables/av1_symbols.js";
+
+/**
+ * AV1's multi-symbol arithmetic decoder.
+ *
+ * A cursor, like {@link BitReader}, and a class for the same reason: its whole purpose is the
+ * coupling of an arithmetic state to a byte range.
+ *
+ * This is the hottest code in the decoder — every syntax element inside a tile passes through
+ * {@link read_symbol} — so it reads bytes directly rather than through `BitReader`, and keeps its
+ * bit cursor as a byte index plus a bit offset.
+ *
+ * CDFs are in specification form: for `N` symbols, `N - 1` cumulative probabilities, then
+ * `1 << 15`, then an adaptation counter. They are passed as `(array, offset, N)` rather than as
+ * their own arrays so the whole CDF set can live in a handful of typed arrays and a read costs no
+ * indirection.
+ *
+ * @see AV1 spec 8.2 "Parsing process for symbol decoder"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SymbolReader {
+    /** @type {Uint8Array} */
+    data = null;
+
+    /** @type {number} index of the byte holding the next bit */
+    byte_position = 0;
+
+    /** @type {number} index of the next bit within that byte, `0` being the most significant */
+    bit_position = 0;
+
+    /** @type {number} index one past the last readable byte */
+    end = 0;
+
+    /** @type {number} `SymbolValue` */
+    symbol_value = 0;
+
+    /** @type {number} `SymbolRange` */
+    symbol_range = 0;
+
+    /** @type {number} `SymbolMaxBits`; goes negative once the payload is exhausted */
+    symbol_max_bits = 0;
+
+    /**
+     * `0` to adapt CDFs after every symbol, `1` to leave them alone. Mirrors the frame header's
+     * `disable_cdf_update`.
+     * @type {number}
+     */
+    disable_cdf_update = 0;
+
+    /**
+     * `init_symbol( sz )`.
+     *
+     * @param {Uint8Array} data
+     * @param {number} byte_offset
+     * @param {number} size number of bytes the symbol decoder may read
+     * @param {number} [disable_cdf_update]
+     * @returns {SymbolReader} this
+     * @see AV1 spec 8.2.2 "Initialization process for symbol decoder"
+     */
+    init(data, byte_offset, size, disable_cdf_update = 0) {
+        if (byte_offset < 0 || size < 0 || byte_offset + size > data.length) {
+            throw new Error(`symbol decoder range [${byte_offset}, ${byte_offset + size}) is outside the ${data.length} byte buffer`);
+        }
+
+        this.data = data;
+        this.byte_position = byte_offset;
+        this.bit_position = 0;
+        this.end = byte_offset + size;
+        this.disable_cdf_update = disable_cdf_update;
+
+        const num_bits = Math.min(size * 8, 15);
+        const buf = this.#read_bits(num_bits);
+        const padded = buf << (15 - num_bits);
+
+        this.symbol_value = ((1 << 15) - 1) ^ padded;
+        this.symbol_range = 1 << 15;
+        this.symbol_max_bits = 8 * size - 15;
+
+        return this;
+    }
+
+    /**
+     * Read `n` bits, most significant first. `n` is at most 15 here, and the caller has already
+     * bounded it by `SymbolMaxBits`, so this never runs off the end.
+     *
+     * @param {number} n
+     * @returns {number}
+     * @private
+     */
+    #read_bits(n) {
+        let result = 0;
+        let remaining = n;
+
+        const data = this.data;
+
+        let byte_position = this.byte_position;
+        let bit_position = this.bit_position;
+
+        while (remaining > 0) {
+            const available = 8 - bit_position;
+            const take = remaining < available ? remaining : available;
+
+            const chunk = (data[byte_position] >> (available - take)) & ((1 << take) - 1);
+
+            result = (result << take) | chunk;
+
+            bit_position += take;
+
+            if (bit_position === 8) {
+                bit_position = 0;
+                byte_position++;
+            }
+
+            remaining -= take;
+        }
+
+        this.byte_position = byte_position;
+        this.bit_position = bit_position;
+
+        return result;
+    }
+
+    /**
+     * `read_symbol( cdf )`.
+     *
+     * @param {Uint16Array} cdf
+     * @param {number} offset index of the CDF's first entry within `cdf`
+     * @param {number} n number of symbols
+     * @returns {number} the decoded symbol, `0 .. n - 1`
+     * @see AV1 spec 8.2.6 "Symbol decoding process"
+     */
+    read_symbol(cdf, offset, n) {
+        const range = this.symbol_range;
+        const range_high = range >> 8;
+
+        let value = this.symbol_value;
+
+        let cur = range;
+        let prev = range;
+        let symbol = -1;
+
+        do {
+            symbol++;
+            prev = cur;
+
+            const f = (1 << 15) - cdf[offset + symbol];
+
+            cur = (((range_high * (f >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB * (n - symbol - 1)) | 0;
+        } while (value < cur);
+
+        let new_range = prev - cur;
+
+        value -= cur;
+
+        // renormalise: bring the range back above 2^14 and pull in the bits that exposes
+        const bits = 15 - floor_log2(new_range);
+
+        if (bits > 0) {
+            new_range <<= bits;
+
+            const max_bits = this.symbol_max_bits;
+            const available = max_bits > 0 ? max_bits : 0;
+            const num_bits = bits < available ? bits : available;
+
+            const new_data = this.#read_bits(num_bits);
+            const padded = new_data << (bits - num_bits);
+
+            value = padded ^ (((value + 1) << bits) - 1);
+
+            this.symbol_max_bits = max_bits - bits;
+        }
+
+        this.symbol_range = new_range;
+        this.symbol_value = value;
+
+        if (this.disable_cdf_update === 0) {
+            const count = cdf[offset + n];
+
+            const rate = 3 + (count > 15 ? 1 : 0) + (count > 31 ? 1 : 0) + Math.min(floor_log2(n), 2);
+
+            let tmp = 0;
+
+            for (let i = 0; i < n - 1; i++) {
+                if (i === symbol) {
+                    tmp = 1 << 15;
+                }
+
+                const c = cdf[offset + i];
+
+                if (tmp < c) {
+                    cdf[offset + i] = c - ((c - tmp) >> rate);
+                } else {
+                    cdf[offset + i] = c + ((tmp - c) >> rate);
+                }
+            }
+
+            if (count < 32) {
+                cdf[offset + n] = count + 1;
+            }
+        }
+
+        return symbol;
+    }
+
+    /**
+     * `read_bool( )`: one symbol at even odds.
+     *
+     * The specification builds a throwaway CDF of `{ 1 << 14, 1 << 15, 0 }` for this and notes that
+     * the adaptation it performs is discarded. That is inlined here rather than allocated, which
+     * also skips the update entirely.
+     *
+     * @returns {number} `0` or `1`
+     * @see AV1 spec 8.2.3 "Boolean decoding process"
+     */
+    read_bool() {
+        const range = this.symbol_range;
+
+        let value = this.symbol_value;
+
+        // cdf[0] = 1 << 14, so f = 1 << 14 and the offset term is EC_MIN_PROB * 1
+        const cur = (((range >> 8) * ((1 << 14) >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB;
+
+        let symbol;
+        let new_range;
+
+        if (value < cur) {
+            // the loop would advance to symbol 1, whose f is 0 and whose cur is therefore 0
+            symbol = 1;
+            new_range = cur;
+        } else {
+            symbol = 0;
+            new_range = range - cur;
+            value -= cur;
+        }
+
+        const bits = 15 - floor_log2(new_range);
+
+        if (bits > 0) {
+            new_range <<= bits;
+
+            const max_bits = this.symbol_max_bits;
+            const available = max_bits > 0 ? max_bits : 0;
+            const num_bits = bits < available ? bits : available;
+
+            const new_data = this.#read_bits(num_bits);
+            const padded = new_data << (bits - num_bits);
+
+            value = padded ^ (((value + 1) << bits) - 1);
+
+            this.symbol_max_bits = max_bits - bits;
+        }
+
+        this.symbol_range = new_range;
+        this.symbol_value = value;
+
+        return symbol;
+    }
+
+    /**
+     * `L(n)`: an `n` bit literal, most significant bit first.
+     *
+     * @param {number} n
+     * @returns {number}
+     * @see AV1 spec 8.2.5 "Parsing process for read_literal"
+     */
+    read_literal(n) {
+        let x = 0;
+
+        for (let i = 0; i < n; i++) {
+            x = 2 * x + this.read_bool();
+        }
+
+        return x;
+    }
+
+    /**
+     * `NS(n)`: the arithmetic-coded form of `ns(n)`.
+     *
+     * @param {number} n number of distinct values
+     * @returns {number} `0 .. n - 1`
+     * @see AV1 spec 4.10.10 "NS(n)"
+     */
+    read_ns(n) {
+        const w = floor_log2(n) + 1;
+        const m = (1 << w) - n;
+
+        const v = this.read_literal(w - 1);
+
+        if (v < m) {
+            return v;
+        }
+
+        return (v << 1) - m + this.read_bool();
+    }
+
+    /**
+     * `exit_symbol( )`, reduced to what a decoder needs: skip the trailing bits so the caller knows
+     * where the payload ended.
+     *
+     * The specification also copies the tile's final CDFs into the frame's saved set here. That
+     * only matters to a later frame that loads them, and a still image has no later frame, so the
+     * copy is omitted rather than performed and discarded.
+     *
+     * @see AV1 spec 8.2.4 "Exit process for symbol decoder"
+     */
+    exit() {
+        const skip = this.symbol_max_bits > 0 ? this.symbol_max_bits : 0;
+
+        const total = this.bit_position + skip;
+
+        this.byte_position += total >> 3;
+        this.bit_position = total & 7;
+    }
+}

package/src/avif/native/av1/entropy/SymbolWriter.d.ts

@@ -0,0 +1,107 @@
+/**
+ * AV1's multi-symbol arithmetic encoder — the inverse of {@link SymbolReader}.
+ *
+ * The specification defines only the decoder; the encoder is whatever produces a stream the
+ * decoder reads back. This is the standard construction: the same interval arithmetic run forwards,
+ * with the low end of the interval accumulated and flushed a byte at a time.
+ *
+ * ### Why the accumulator is a double and not a 32-bit integer
+ *
+ * The low end of the interval carries up to 24 bits of pending output and is then shifted left by
+ * as much as 15 more during renormalisation, which overflows a 32-bit register. Reference encoders
+ * solve this with a 64-bit window. JavaScript has no 64-bit integer that is cheap, but a double
+ * represents every integer below 2^53 exactly, so shifts become multiplications by a power of two
+ * and masks become a modulus. That is what {@link POW2} is for, and it is why nothing in this file
+ * uses `<<` on the accumulator.
+ *
+ * ### Carry propagation
+ *
+ * Bytes are emitted into a 16-bit pre-carry buffer rather than an 8-bit one, so a byte that
+ * overflows can record its carry and have it resolved in a single backwards pass at the end. This
+ * is exactly the trick the reference encoder uses, and it is why the output is assembled only in
+ * {@link finish}.
+ *
+ * ### Pricing rather than writing
+ *
+ * {@link reset_costing} puts a writer into a mode where it emits nothing and adds up what emitting
+ * would have cost, in {@link COST_ONE_BIT} units, leaving the CDFs alone. That is how the encoder
+ * gets a rate to weigh a distortion against, and it is a *mode of this class* rather than a class
+ * of its own on purpose: `write_coefficients` is handed one or the other and is the hottest
+ * function in the encoder, and two classes at that call site is a shape V8 will not inline through.
+ * One class, one shape, one branch.
+ *
+ * @see AV1 spec 8.2 "Parsing process for symbol decoder", inverted
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class SymbolWriter {
+    /** @type {Uint16Array} pending bytes, each with room for a carry above bit 7 */
+    precarry: Uint16Array;
+    /** @type {number} number of words used in {@link precarry} */
+    precarry_length: number;
+    /** @type {number} low end of the current interval, with pending output above bit 16 */
+    low: number;
+    /** @type {number} width of the current interval, always in `(1 << 15) .. (1 << 16) - 1` */
+    range: number;
+    /** @type {number} bits of {@link low} that are ready to flush, less 16 */
+    count: number;
+    /**
+     * @type {number} mirrors the frame header's `disable_cdf_update`; must match the reader's
+     */
+    disable_cdf_update: number;
+    /** @type {number} `1` to price symbols instead of emitting them */
+    costing: number;
+    /** @type {number} what the symbols priced so far would have cost, in {@link COST_ONE_BIT} units */
+    cost: number;
+    /**
+     * Start a fresh payload, keeping the allocated buffer.
+     * @param {number} [disable_cdf_update]
+     * @returns {SymbolWriter} this
+     */
+    reset(disable_cdf_update?: number): SymbolWriter;
+    /**
+     * Start pricing rather than writing. Nothing is emitted and no CDF is touched — a trial that
+     * adapted would leave the tile's probabilities carrying the trace of a decision not taken.
+     *
+     * @returns {SymbolWriter} this
+     */
+    reset_costing(): SymbolWriter;
+    /**
+     * Encode one symbol against `cdf`, adapting it exactly as {@link SymbolReader.read_symbol}
+     * would.
+     *
+     * @param {number} symbol `0 .. n - 1`
+     * @param {Uint16Array} cdf in specification form
+     * @param {number} offset
+     * @param {number} n number of symbols
+     */
+    write_symbol(symbol: number, cdf: Uint16Array, offset: number, n: number): void;
+    /**
+     * Encode one even-odds symbol, matching {@link SymbolReader.read_bool}.
+     * @param {number} value `0` or `1`
+     */
+    write_bool(value: number): void;
+    /**
+     * @param {number} value
+     * @param {number} n number of bits, most significant first
+     */
+    write_literal(value: number, n: number): void;
+    /**
+     * `NS(n)`.
+     * @param {number} value `0 .. n - 1`
+     * @param {number} n
+     */
+    write_ns(value: number, n: number): void;
+    /**
+     * Flush the interval and resolve carries, producing the payload.
+     *
+     * Enough bits are emitted that any continuation decodes the symbols written so far correctly,
+     * which is what lets the trailing byte be padded rather than exact.
+     *
+     * @returns {Uint8Array} a view onto an internal buffer, valid until the next {@link reset}
+     */
+    finish(): Uint8Array;
+    #private;
+}
+//# sourceMappingURL=SymbolWriter.d.ts.map

package/src/avif/native/av1/entropy/SymbolWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SymbolWriter.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/entropy/SymbolWriter.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH;IACI,gFAAgF;IAChF,UADW,WAAW,CACuB;IAE7C,8DAA8D;IAC9D,iBADW,MAAM,CACG;IAEpB,uFAAuF;IACvF,KADW,MAAM,CACT;IAER,2FAA2F;IAC3F,OADW,MAAM,CACH;IAEd,0EAA0E;IAC1E,OADW,MAAM,CACN;IAEX;;OAEG;IACH,oBAFU,MAAM,CAEO;IAEvB,mEAAmE;IACnE,SADW,MAAM,CACL;IAEZ,mGAAmG;IACnG,MADW,MAAM,CACR;IAET;;;;OAIG;IACH,2BAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;OAKG;IACH,iBAFa,YAAY,CAQxB;IAiED;;;;;;;;OAQG;IACH,qBALW,MAAM,OACN,WAAW,UACX,MAAM,KACN,MAAM,QAuDhB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAoBhB;IAED;;;OAGG;IACH,qBAHW,MAAM,KACN,MAAM,QAMhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,KACN,MAAM,QAgBhB;IAED;;;;;;;OAOG;IACH,UAFa,UAAU,CA8CtB;;CACJ"}