@woosh/meep-engine 3.9.0 → 3.10.0

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

@@ -0,0 +1,352 @@
+import { floor_log2 } from "../util/floor_log2.js";
+import { BOOL_COST, COST_ONE_BIT, symbol_cost } from "./symbol_cost.js";
+import { EC_MIN_PROB, EC_PROB_SHIFT } from "../tables/av1_symbols.js";
+
+/**
+ * Initial capacity of the pre-carry buffer, in 16-bit words. Grows as needed.
+ * @type {number}
+ */
+const INITIAL_CAPACITY = 4096;
+
+/**
+ * Powers of two, so the accumulator can be shifted with multiplication and masked with a modulus
+ * instead of with `<<` and `&`.
+ * @type {Float64Array}
+ */
+const POW2 = new Float64Array(64);
+
+for (let i = 0; i < 64; i++) {
+    POW2[i] = 2 ** i;
+}
+
+/**
+ * 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 = new Uint16Array(INITIAL_CAPACITY);
+
+    /** @type {number} number of words used in {@link precarry} */
+    precarry_length = 0;
+
+    /** @type {number} low end of the current interval, with pending output above bit 16 */
+    low = 0;
+
+    /** @type {number} width of the current interval, always in `(1 << 15) .. (1 << 16) - 1` */
+    range = 32768;
+
+    /** @type {number} bits of {@link low} that are ready to flush, less 16 */
+    count = -9;
+
+    /**
+     * @type {number} mirrors the frame header's `disable_cdf_update`; must match the reader's
+     */
+    disable_cdf_update = 0;
+
+    /** @type {number} `1` to price symbols instead of emitting them */
+    costing = 0;
+
+    /** @type {number} what the symbols priced so far would have cost, in {@link COST_ONE_BIT} units */
+    cost = 0;
+
+    /**
+     * Start a fresh payload, keeping the allocated buffer.
+     * @param {number} [disable_cdf_update]
+     * @returns {SymbolWriter} this
+     */
+    reset(disable_cdf_update = 0) {
+        this.precarry_length = 0;
+        this.low = 0;
+        this.range = 32768;
+        this.count = -9;
+        this.disable_cdf_update = disable_cdf_update;
+        this.costing = 0;
+        this.cost = 0;
+
+        return this;
+    }
+
+    /**
+     * 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() {
+        this.costing = 1;
+        this.cost = 0;
+        this.disable_cdf_update = 1;
+
+        return this;
+    }
+
+    /**
+     * @param {number} required
+     * @private
+     */
+    #ensure_capacity(required) {
+        if (required <= this.precarry.length) {
+            return;
+        }
+
+        let capacity = this.precarry.length * 2;
+
+        while (capacity < required) {
+            capacity *= 2;
+        }
+
+        const grown = new Uint16Array(capacity);
+
+        grown.set(this.precarry);
+
+        this.precarry = grown;
+    }
+
+    /**
+     * Renormalise after narrowing the interval, flushing whatever bytes that exposes.
+     *
+     * @param {number} low
+     * @param {number} range
+     * @private
+     */
+    #normalize(low, range) {
+        let count = this.count;
+
+        const d = 16 - (32 - Math.clz32(range));
+
+        let s = count + d;
+
+        if (s >= 0) {
+            this.#ensure_capacity(this.precarry_length + 2);
+
+            count += 16;
+
+            let m = POW2[count] - 1;
+
+            if (s >= 8) {
+                this.precarry[this.precarry_length++] = Math.floor(low / POW2[count]);
+
+                low = low % POW2[count];
+                count -= 8;
+                m = POW2[count] - 1;
+            }
+
+            this.precarry[this.precarry_length++] = Math.floor(low / POW2[count]);
+
+            s = count + d - 24;
+
+            low = low % POW2[count];
+        }
+
+        this.low = low * POW2[d];
+        this.range = range * POW2[d];
+        this.count = s;
+    }
+
+    /**
+     * 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, cdf, offset, n) {
+        if (this.costing === 1) {
+            this.cost += symbol_cost(cdf, offset, symbol, n);
+
+            return;
+        }
+
+        const range = this.range;
+        const range_high = Math.floor(range / 256);
+
+        // the decoder's `cur` for this symbol and for the one before it: the interval the symbol
+        // owns is [cur(symbol), cur(symbol - 1)), with cur(-1) being the whole range
+        const high = (((range_high * (((1 << 15) - cdf[offset + symbol]) >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB * (n - symbol - 1)) | 0;
+
+        let low = this.low;
+        let new_range;
+
+        if (symbol > 0) {
+            const previous = (((range_high * (((1 << 15) - cdf[offset + symbol - 1]) >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB * (n - symbol)) | 0;
+
+            low += range - previous;
+            new_range = previous - high;
+        } else {
+            new_range = range - high;
+        }
+
+        this.#normalize(low, new_range);
+
+        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;
+            }
+        }
+    }
+
+    /**
+     * Encode one even-odds symbol, matching {@link SymbolReader.read_bool}.
+     * @param {number} value `0` or `1`
+     */
+    write_bool(value) {
+        if (this.costing === 1) {
+            this.cost += BOOL_COST;
+
+            return;
+        }
+
+        const range = this.range;
+
+        const cur = ((Math.floor(range / 256) * ((1 << 14) >> EC_PROB_SHIFT)) >> (7 - EC_PROB_SHIFT)) + EC_MIN_PROB;
+
+        if (value !== 0) {
+            // symbol 1 owns [0, cur): the interval below the split, which in the decoder's
+            // complemented value space is the one the low end has to be advanced past
+            this.#normalize(this.low + range - cur, cur);
+        } else {
+            this.#normalize(this.low, range - cur);
+        }
+    }
+
+    /**
+     * @param {number} value
+     * @param {number} n number of bits, most significant first
+     */
+    write_literal(value, n) {
+        for (let i = n - 1; i >= 0; i--) {
+            this.write_bool((value >> i) & 1);
+        }
+    }
+
+    /**
+     * `NS(n)`.
+     * @param {number} value `0 .. n - 1`
+     * @param {number} n
+     */
+    write_ns(value, n) {
+        const w = floor_log2(n) + 1;
+        const m = (1 << w) - n;
+
+        if (value < m) {
+            this.write_literal(value, w - 1);
+
+            return;
+        }
+
+        const shifted = value + m;
+
+        this.write_literal(shifted >> 1, w - 1);
+        this.write_bool(shifted & 1);
+    }
+
+    /**
+     * 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() {
+        let low = this.low;
+        let count = this.count;
+
+        let s = 10 + count;
+
+        // round the low end up to the coarsest value still inside the interval, so the fewest bits
+        // pin it down
+        const m = 0x3fff;
+
+        let e = (Math.floor((low + m) / POW2[14]) * POW2[14]) + (m + 1);
+
+        this.#ensure_capacity(this.precarry_length + Math.max(0, (s + 7) >> 3) + 8);
+
+        if (s > 0) {
+            let n = POW2[count + 16] - 1;
+
+            do {
+                this.precarry[this.precarry_length++] = Math.floor(e / POW2[count + 16]);
+
+                e = e % POW2[count + 16];
+
+                s -= 8;
+                count -= 8;
+                n = POW2[count + 16] - 1;
+            } while (s > 0);
+        }
+
+        const extra = s > 0 ? (s + 7) >> 3 : 0;
+        const length = this.precarry_length + extra;
+
+        const out = new Uint8Array(length);
+
+        let carry = 0;
+
+        for (let i = this.precarry_length - 1; i >= 0; i--) {
+            carry = this.precarry[i] + carry;
+
+            out[i] = carry & 0xff;
+
+            carry >>= 8;
+        }
+
+        return out;
+    }
+}

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

@@ -0,0 +1,71 @@
+/**
+ * The contexts coefficient coding conditions its probabilities on.
+ *
+ * Shared rather than duplicated: an encoder has to derive every one of these identically to the
+ * decoder, and a context that drifted by one would desynchronise the arithmetic coder several
+ * blocks later, somewhere that looks nothing like the mistake.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} x4
+ * @param {number} y4
+ * @param {number} w4
+ * @param {number} h4
+ * @param {number} tx_size
+ * @returns {number}
+ * @see AV1 spec 8.3.2, `all_zero`
+ */
+export function get_all_zero_ctx(ctx: Av1FrameContext, plane: number, x4: number, y4: number, w4: number, h4: number, tx_size: number): number;
+/**
+ * @param {Int32Array} quant
+ * @param {number} tx_class
+ * @param {number} bwl
+ * @param {number} width
+ * @param {number} height
+ * @param {number} pos
+ * @param {number} c
+ * @param {number} is_eob
+ * @param {number} tx_size
+ * @returns {number}
+ * @see AV1 spec 8.3.2, `get_coeff_base_ctx`
+ */
+export function get_coeff_base_ctx(quant: Int32Array, tx_class: number, bwl: number, width: number, height: number, pos: number, c: number, is_eob: number, tx_size: number): number;
+/**
+ * @param {Int32Array} quant
+ * @param {number} tx_class
+ * @param {number} bwl
+ * @param {number} width
+ * @param {number} height
+ * @param {number} pos
+ * @returns {number}
+ * @see AV1 spec 8.3.2, `coeff_br`
+ */
+export function get_coeff_br_ctx(quant: Int32Array, tx_class: number, bwl: number, width: number, height: number, pos: number): number;
+/**
+ * Clear the coefficient contexts a block covers, which is what a skipped block leaves behind.
+ *
+ * A block coded with `skip` writes no coefficients at all, so both sides have to agree that it
+ * contributed nothing — not that it contributed whatever the block before it did.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} bw4 block width in 4x4 units
+ * @param {number} bh4
+ * @see AV1 spec 5.11.6, `reset_block_context`
+ */
+export function reset_block_context(ctx: Av1FrameContext, bw4: number, bh4: number): void;
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} x4
+ * @param {number} y4
+ * @param {number} w4
+ * @param {number} h4
+ * @returns {number}
+ * @see AV1 spec 8.3.2, `dc_sign`
+ */
+export function get_dc_sign_ctx(ctx: Av1FrameContext, plane: number, x4: number, y4: number, w4: number, h4: number): number;
+//# sourceMappingURL=coefficient_context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coefficient_context.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/entropy/coefficient_context.js"],"names":[],"mappings":"AAiBA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,8DATW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,GACJ,MAAM,CAwFlB;AAED;;;;;;;;;;;;GAYG;AACH,0CAZW,UAAU,YACV,MAAM,OACN,MAAM,SACN,MAAM,UACN,MAAM,OACN,MAAM,KACN,MAAM,UACN,MAAM,WACN,MAAM,GACJ,MAAM,CAiDlB;AAED;;;;;;;;;GASG;AACH,wCATW,UAAU,YACV,MAAM,OACN,MAAM,SACN,MAAM,UACN,MAAM,OACN,MAAM,GACJ,MAAM,CAsClB;AAED;;;;;;;;;;GAUG;AACH,+DAJW,MAAM,OACN,MAAM,QAyBhB;AAED;;;;;;;;;GASG;AACH,6DARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,MAAM,CAgDlB"}