@woosh/meep-engine 3.8.0 → 3.10.0

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

@@ -0,0 +1,433 @@
+import {
+    DEFAULT_ANGLE_DELTA_CDF,
+    DEFAULT_CFL_ALPHA_CDF,
+    DEFAULT_CFL_SIGN_CDF,
+    DEFAULT_COEFF_BASE_CDF,
+    DEFAULT_COEFF_BASE_EOB_CDF,
+    DEFAULT_COEFF_BR_CDF,
+    DEFAULT_DC_SIGN_CDF,
+    DEFAULT_DELTA_LF_CDF,
+    DEFAULT_DELTA_Q_CDF,
+    DEFAULT_EOB_EXTRA_CDF,
+    DEFAULT_EOB_PT_1024_CDF,
+    DEFAULT_EOB_PT_128_CDF,
+    DEFAULT_EOB_PT_16_CDF,
+    DEFAULT_EOB_PT_256_CDF,
+    DEFAULT_EOB_PT_32_CDF,
+    DEFAULT_EOB_PT_512_CDF,
+    DEFAULT_EOB_PT_64_CDF,
+    DEFAULT_FILTER_INTRA_CDF,
+    DEFAULT_FILTER_INTRA_MODE_CDF,
+    DEFAULT_INTRABC_CDF,
+    DEFAULT_INTRA_FRAME_Y_MODE_CDF,
+    DEFAULT_INTRA_TX_TYPE_SET1_CDF,
+    DEFAULT_INTRA_TX_TYPE_SET2_CDF,
+    DEFAULT_MV_BIT_CDF,
+    DEFAULT_MV_CLASS0_BIT_CDF,
+    DEFAULT_MV_CLASS0_FR_CDF,
+    DEFAULT_MV_CLASS0_HP_CDF,
+    DEFAULT_MV_CLASS_CDF,
+    DEFAULT_MV_FR_CDF,
+    DEFAULT_MV_HP_CDF,
+    DEFAULT_MV_JOINT_CDF,
+    DEFAULT_MV_SIGN_CDF,
+    DEFAULT_PALETTE_SIZE_2_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_2_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_3_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_3_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_4_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_4_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_5_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_5_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_6_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_6_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_7_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_7_Y_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_8_UV_COLOR_CDF,
+    DEFAULT_PALETTE_SIZE_8_Y_COLOR_CDF,
+    DEFAULT_PALETTE_UV_MODE_CDF,
+    DEFAULT_PALETTE_UV_SIZE_CDF,
+    DEFAULT_PALETTE_Y_MODE_CDF,
+    DEFAULT_PALETTE_Y_SIZE_CDF,
+    DEFAULT_PARTITION_W128_CDF,
+    DEFAULT_PARTITION_W16_CDF,
+    DEFAULT_PARTITION_W32_CDF,
+    DEFAULT_PARTITION_W64_CDF,
+    DEFAULT_PARTITION_W8_CDF,
+    DEFAULT_RESTORATION_TYPE_CDF,
+    DEFAULT_SEGMENT_ID_CDF,
+    DEFAULT_SKIP_CDF,
+    DEFAULT_TXB_SKIP_CDF,
+    DEFAULT_TX_16X16_CDF,
+    DEFAULT_TX_32X32_CDF,
+    DEFAULT_TX_64X64_CDF,
+    DEFAULT_TX_8X8_CDF,
+    DEFAULT_USE_SGRPROJ_CDF,
+    DEFAULT_USE_WIENER_CDF,
+    DEFAULT_UV_MODE_CFL_ALLOWED_CDF,
+    DEFAULT_UV_MODE_CFL_NOT_ALLOWED_CDF
+} from "../tables/cdf_tables.js";
+
+/**
+ * The adaptive CDF state a tile decodes against.
+ *
+ * ### What is here and what is not
+ *
+ * Only the CDFs an intra key frame can reach. The inter-only families — reference frame selection,
+ * compound modes, motion mode, interpolation filter, wedge masks — are unreachable from a still
+ * image, so carrying them would be memory and copying for state nothing reads.
+ *
+ * The motion vector CDFs *are* here: intra block copy codes a displacement with the same syntax,
+ * with `MV_INTRABC_CONTEXT` selecting the second of the two contexts.
+ *
+ * ### Why the coefficient CDFs are one slice, not four
+ *
+ * The specification's coefficient tables carry four sets indexed by a quantizer band, and
+ * `init_coeff_cdfs` selects one from `base_q_idx`. Storing only the selected slice makes the
+ * working set a quarter of the size and removes the band from every index computation downstream.
+ *
+ * ### Lifetime
+ *
+ * One context is allocated per decode and reused. {@link cdf_context_init} re-seeds it from the
+ * defaults, which is what every tile does at its start: a still image never carries CDFs forward
+ * to another frame, so the tile-end save the specification describes has no consumer and is not
+ * performed.
+ *
+ * @see AV1 spec 8.4 "Cdf selection process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class CdfContext {
+    /** @type {Uint16Array} `[5][5][14]` */
+    intra_frame_y_mode = new Uint16Array(DEFAULT_INTRA_FRAME_Y_MODE_CDF.length);
+
+    /** @type {Uint16Array} `[13][14]` */
+    uv_mode_cfl_not_allowed = new Uint16Array(DEFAULT_UV_MODE_CFL_NOT_ALLOWED_CDF.length);
+
+    /** @type {Uint16Array} `[13][15]` */
+    uv_mode_cfl_allowed = new Uint16Array(DEFAULT_UV_MODE_CFL_ALLOWED_CDF.length);
+
+    /** @type {Uint16Array} `[8][8]` */
+    angle_delta = new Uint16Array(DEFAULT_ANGLE_DELTA_CDF.length);
+
+    /** @type {Uint16Array} `[3]` */
+    intrabc = new Uint16Array(DEFAULT_INTRABC_CDF.length);
+
+    /** @type {Uint16Array} `[4][5]` */
+    partition_w8 = new Uint16Array(DEFAULT_PARTITION_W8_CDF.length);
+
+    /** @type {Uint16Array} `[4][11]` */
+    partition_w16 = new Uint16Array(DEFAULT_PARTITION_W16_CDF.length);
+
+    /** @type {Uint16Array} `[4][11]` */
+    partition_w32 = new Uint16Array(DEFAULT_PARTITION_W32_CDF.length);
+
+    /** @type {Uint16Array} `[4][11]` */
+    partition_w64 = new Uint16Array(DEFAULT_PARTITION_W64_CDF.length);
+
+    /** @type {Uint16Array} `[4][9]` */
+    partition_w128 = new Uint16Array(DEFAULT_PARTITION_W128_CDF.length);
+
+    /** @type {Uint16Array} `[3][3]` */
+    tx_8x8 = new Uint16Array(DEFAULT_TX_8X8_CDF.length);
+
+    /** @type {Uint16Array} `[3][4]` */
+    tx_16x16 = new Uint16Array(DEFAULT_TX_16X16_CDF.length);
+
+    /** @type {Uint16Array} `[3][4]` */
+    tx_32x32 = new Uint16Array(DEFAULT_TX_32X32_CDF.length);
+
+    /** @type {Uint16Array} `[3][4]` */
+    tx_64x64 = new Uint16Array(DEFAULT_TX_64X64_CDF.length);
+
+    /** @type {Uint16Array} `[6]` */
+    filter_intra_mode = new Uint16Array(DEFAULT_FILTER_INTRA_MODE_CDF.length);
+
+    /** @type {Uint16Array} `[22][3]` */
+    filter_intra = new Uint16Array(DEFAULT_FILTER_INTRA_CDF.length);
+
+    /** @type {Uint16Array} `[3][9]` */
+    segment_id = new Uint16Array(DEFAULT_SEGMENT_ID_CDF.length);
+
+    /** @type {Uint16Array} `[3][3]` */
+    skip = new Uint16Array(DEFAULT_SKIP_CDF.length);
+
+    /** @type {Uint16Array} `[5]` */
+    delta_q = new Uint16Array(DEFAULT_DELTA_Q_CDF.length);
+
+    /** @type {Uint16Array} `[5]` */
+    delta_lf = new Uint16Array(DEFAULT_DELTA_LF_CDF.length);
+
+    /** @type {Uint16Array} `[4][5]`, one per plane-and-more flavour of delta_lf_multi */
+    delta_lf_multi = new Uint16Array(DEFAULT_DELTA_LF_CDF.length * 4);
+
+    /** @type {Uint16Array} `[2][13][8]` */
+    intra_tx_type_set1 = new Uint16Array(DEFAULT_INTRA_TX_TYPE_SET1_CDF.length);
+
+    /** @type {Uint16Array} `[3][13][6]` */
+    intra_tx_type_set2 = new Uint16Array(DEFAULT_INTRA_TX_TYPE_SET2_CDF.length);
+
+    /** @type {Uint16Array} `[9]` */
+    cfl_sign = new Uint16Array(DEFAULT_CFL_SIGN_CDF.length);
+
+    /** @type {Uint16Array} `[6][17]` */
+    cfl_alpha = new Uint16Array(DEFAULT_CFL_ALPHA_CDF.length);
+
+    /** @type {Uint16Array} `[3]` */
+    use_wiener = new Uint16Array(DEFAULT_USE_WIENER_CDF.length);
+
+    /** @type {Uint16Array} `[3]` */
+    use_sgrproj = new Uint16Array(DEFAULT_USE_SGRPROJ_CDF.length);
+
+    /** @type {Uint16Array} `[4]` */
+    restoration_type = new Uint16Array(DEFAULT_RESTORATION_TYPE_CDF.length);
+
+    // ---- palette -------------------------------------------------------------------------------
+
+    /** @type {Uint16Array} `[7][8]` */
+    palette_y_size = new Uint16Array(DEFAULT_PALETTE_Y_SIZE_CDF.length);
+
+    /** @type {Uint16Array} `[7][8]` */
+    palette_uv_size = new Uint16Array(DEFAULT_PALETTE_UV_SIZE_CDF.length);
+
+    /** @type {Uint16Array} `[7][3][3]` */
+    palette_y_mode = new Uint16Array(DEFAULT_PALETTE_Y_MODE_CDF.length);
+
+    /** @type {Uint16Array} `[2][3]` */
+    palette_uv_mode = new Uint16Array(DEFAULT_PALETTE_UV_MODE_CDF.length);
+
+    /**
+     * Palette colour CDFs for sizes two through eight, luma then chroma.
+     *
+     * Kept as an array of arrays because the alphabets differ in size — three through nine — so a
+     * single flat buffer would need a stride table to index it and would be no faster.
+     * @type {Uint16Array[]}
+     */
+    palette_y_color = [
+        new Uint16Array(DEFAULT_PALETTE_SIZE_2_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_3_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_4_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_5_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_6_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_7_Y_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_8_Y_COLOR_CDF.length)
+    ];
+
+    /** @type {Uint16Array[]} */
+    palette_uv_color = [
+        new Uint16Array(DEFAULT_PALETTE_SIZE_2_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_3_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_4_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_5_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_6_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_7_UV_COLOR_CDF.length),
+        new Uint16Array(DEFAULT_PALETTE_SIZE_8_UV_COLOR_CDF.length)
+    ];
+
+    // ---- motion vectors, reached only through intra block copy ----------------------------------
+
+    /** @type {Uint16Array} `[5]` */
+    mv_joint = new Uint16Array(DEFAULT_MV_JOINT_CDF.length);
+
+    /** @type {Uint16Array} `[2][3]` — one per component */
+    mv_sign = new Uint16Array(DEFAULT_MV_SIGN_CDF.length * 2);
+
+    /** @type {Uint16Array} `[2][12]` */
+    mv_class = new Uint16Array(DEFAULT_MV_CLASS_CDF.length);
+
+    /** @type {Uint16Array} `[2][3]` */
+    mv_class0_bit = new Uint16Array(DEFAULT_MV_CLASS0_BIT_CDF.length * 2);
+
+    /** @type {Uint16Array} `[2][10][3]` */
+    mv_bit = new Uint16Array(DEFAULT_MV_BIT_CDF.length * 2);
+
+    /** @type {Uint16Array} `[2][2][5]` */
+    mv_class0_fr = new Uint16Array(DEFAULT_MV_CLASS0_FR_CDF.length);
+
+    /** @type {Uint16Array} `[2][5]` */
+    mv_fr = new Uint16Array(DEFAULT_MV_FR_CDF.length);
+
+    /** @type {Uint16Array} `[2][3]` */
+    mv_class0_hp = new Uint16Array(DEFAULT_MV_CLASS0_HP_CDF.length * 2);
+
+    /** @type {Uint16Array} `[2][3]` */
+    mv_hp = new Uint16Array(DEFAULT_MV_HP_CDF.length * 2);
+
+    // ---- coefficients, one quantizer band's slice ------------------------------------------------
+
+    /** @type {Uint16Array} `[5][13][3]` */
+    txb_skip = new Uint16Array(DEFAULT_TXB_SKIP_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][2][6]` */
+    eob_pt_16 = new Uint16Array(DEFAULT_EOB_PT_16_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][2][7]` */
+    eob_pt_32 = new Uint16Array(DEFAULT_EOB_PT_32_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][2][8]` */
+    eob_pt_64 = new Uint16Array(DEFAULT_EOB_PT_64_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][2][9]` */
+    eob_pt_128 = new Uint16Array(DEFAULT_EOB_PT_128_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][2][10]` */
+    eob_pt_256 = new Uint16Array(DEFAULT_EOB_PT_256_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][11]` */
+    eob_pt_512 = new Uint16Array(DEFAULT_EOB_PT_512_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][12]` */
+    eob_pt_1024 = new Uint16Array(DEFAULT_EOB_PT_1024_CDF.length / 4);
+
+    /** @type {Uint16Array} `[5][2][9][3]` */
+    eob_extra = new Uint16Array(DEFAULT_EOB_EXTRA_CDF.length / 4);
+
+    /** @type {Uint16Array} `[2][3][3]` */
+    dc_sign = new Uint16Array(DEFAULT_DC_SIGN_CDF.length / 4);
+
+    /** @type {Uint16Array} `[5][2][4][4]` */
+    coeff_base_eob = new Uint16Array(DEFAULT_COEFF_BASE_EOB_CDF.length / 4);
+
+    /** @type {Uint16Array} `[5][2][42][5]` */
+    coeff_base = new Uint16Array(DEFAULT_COEFF_BASE_CDF.length / 4);
+
+    /** @type {Uint16Array} `[5][2][21][5]` */
+    coeff_br = new Uint16Array(DEFAULT_COEFF_BR_CDF.length / 4);
+}
+
+/**
+ * The quantizer band whose coefficient CDFs a frame uses.
+ *
+ * @param {number} base_q_idx
+ * @returns {number} `0 .. 3`
+ * @see AV1 spec 6.8.2, `init_coeff_cdfs`
+ */
+export function coefficient_cdf_band(base_q_idx) {
+    if (base_q_idx <= 20) {
+        return 0;
+    }
+
+    if (base_q_idx <= 60) {
+        return 1;
+    }
+
+    if (base_q_idx <= 120) {
+        return 2;
+    }
+
+    return 3;
+}
+
+/**
+ * Copy one band's slice out of a four-band coefficient table.
+ *
+ * @param {Uint16Array} destination
+ * @param {Uint16Array} source
+ * @param {number} band `0 .. 3`
+ */
+function copy_band(destination, source, band) {
+    const stride = source.length / 4;
+
+    destination.set(source.subarray(band * stride, (band + 1) * stride));
+}
+
+/**
+ * Re-seed a context from the default CDFs, as `init_non_coeff_cdfs` and `init_coeff_cdfs` do.
+ *
+ * @param {CdfContext} cdf
+ * @param {number} base_q_idx selects the coefficient CDF band
+ * @see AV1 spec 6.8.2 "Uncompressed header semantics"
+ */
+export function cdf_context_init(cdf, base_q_idx) {
+    cdf.intra_frame_y_mode.set(DEFAULT_INTRA_FRAME_Y_MODE_CDF);
+    cdf.uv_mode_cfl_not_allowed.set(DEFAULT_UV_MODE_CFL_NOT_ALLOWED_CDF);
+    cdf.uv_mode_cfl_allowed.set(DEFAULT_UV_MODE_CFL_ALLOWED_CDF);
+    cdf.angle_delta.set(DEFAULT_ANGLE_DELTA_CDF);
+    cdf.intrabc.set(DEFAULT_INTRABC_CDF);
+
+    cdf.partition_w8.set(DEFAULT_PARTITION_W8_CDF);
+    cdf.partition_w16.set(DEFAULT_PARTITION_W16_CDF);
+    cdf.partition_w32.set(DEFAULT_PARTITION_W32_CDF);
+    cdf.partition_w64.set(DEFAULT_PARTITION_W64_CDF);
+    cdf.partition_w128.set(DEFAULT_PARTITION_W128_CDF);
+
+    cdf.tx_8x8.set(DEFAULT_TX_8X8_CDF);
+    cdf.tx_16x16.set(DEFAULT_TX_16X16_CDF);
+    cdf.tx_32x32.set(DEFAULT_TX_32X32_CDF);
+    cdf.tx_64x64.set(DEFAULT_TX_64X64_CDF);
+
+    cdf.filter_intra_mode.set(DEFAULT_FILTER_INTRA_MODE_CDF);
+    cdf.filter_intra.set(DEFAULT_FILTER_INTRA_CDF);
+
+    cdf.segment_id.set(DEFAULT_SEGMENT_ID_CDF);
+    cdf.skip.set(DEFAULT_SKIP_CDF);
+
+    cdf.delta_q.set(DEFAULT_DELTA_Q_CDF);
+    cdf.delta_lf.set(DEFAULT_DELTA_LF_CDF);
+
+    for (let i = 0; i < 4; i++) {
+        cdf.delta_lf_multi.set(DEFAULT_DELTA_LF_CDF, i * DEFAULT_DELTA_LF_CDF.length);
+    }
+
+    cdf.intra_tx_type_set1.set(DEFAULT_INTRA_TX_TYPE_SET1_CDF);
+    cdf.intra_tx_type_set2.set(DEFAULT_INTRA_TX_TYPE_SET2_CDF);
+
+    cdf.cfl_sign.set(DEFAULT_CFL_SIGN_CDF);
+    cdf.cfl_alpha.set(DEFAULT_CFL_ALPHA_CDF);
+
+    cdf.use_wiener.set(DEFAULT_USE_WIENER_CDF);
+    cdf.use_sgrproj.set(DEFAULT_USE_SGRPROJ_CDF);
+    cdf.restoration_type.set(DEFAULT_RESTORATION_TYPE_CDF);
+
+    cdf.palette_y_size.set(DEFAULT_PALETTE_Y_SIZE_CDF);
+    cdf.palette_uv_size.set(DEFAULT_PALETTE_UV_SIZE_CDF);
+    cdf.palette_y_mode.set(DEFAULT_PALETTE_Y_MODE_CDF);
+    cdf.palette_uv_mode.set(DEFAULT_PALETTE_UV_MODE_CDF);
+
+    cdf.palette_y_color[0].set(DEFAULT_PALETTE_SIZE_2_Y_COLOR_CDF);
+    cdf.palette_y_color[1].set(DEFAULT_PALETTE_SIZE_3_Y_COLOR_CDF);
+    cdf.palette_y_color[2].set(DEFAULT_PALETTE_SIZE_4_Y_COLOR_CDF);
+    cdf.palette_y_color[3].set(DEFAULT_PALETTE_SIZE_5_Y_COLOR_CDF);
+    cdf.palette_y_color[4].set(DEFAULT_PALETTE_SIZE_6_Y_COLOR_CDF);
+    cdf.palette_y_color[5].set(DEFAULT_PALETTE_SIZE_7_Y_COLOR_CDF);
+    cdf.palette_y_color[6].set(DEFAULT_PALETTE_SIZE_8_Y_COLOR_CDF);
+
+    cdf.palette_uv_color[0].set(DEFAULT_PALETTE_SIZE_2_UV_COLOR_CDF);
+    cdf.palette_uv_color[1].set(DEFAULT_PALETTE_SIZE_3_UV_COLOR_CDF);
+    cdf.palette_uv_color[2].set(DEFAULT_PALETTE_SIZE_4_UV_COLOR_CDF);
+    cdf.palette_uv_color[3].set(DEFAULT_PALETTE_SIZE_5_UV_COLOR_CDF);
+    cdf.palette_uv_color[4].set(DEFAULT_PALETTE_SIZE_6_UV_COLOR_CDF);
+    cdf.palette_uv_color[5].set(DEFAULT_PALETTE_SIZE_7_UV_COLOR_CDF);
+    cdf.palette_uv_color[6].set(DEFAULT_PALETTE_SIZE_8_UV_COLOR_CDF);
+
+    cdf.mv_joint.set(DEFAULT_MV_JOINT_CDF);
+    cdf.mv_class.set(DEFAULT_MV_CLASS_CDF);
+    cdf.mv_class0_fr.set(DEFAULT_MV_CLASS0_FR_CDF);
+    cdf.mv_fr.set(DEFAULT_MV_FR_CDF);
+
+    // the per-component CDFs are one table in the specification and two contexts in use
+    for (let component = 0; component < 2; component++) {
+        cdf.mv_sign.set(DEFAULT_MV_SIGN_CDF, component * DEFAULT_MV_SIGN_CDF.length);
+        cdf.mv_class0_bit.set(DEFAULT_MV_CLASS0_BIT_CDF, component * DEFAULT_MV_CLASS0_BIT_CDF.length);
+        cdf.mv_bit.set(DEFAULT_MV_BIT_CDF, component * DEFAULT_MV_BIT_CDF.length);
+        cdf.mv_class0_hp.set(DEFAULT_MV_CLASS0_HP_CDF, component * DEFAULT_MV_CLASS0_HP_CDF.length);
+        cdf.mv_hp.set(DEFAULT_MV_HP_CDF, component * DEFAULT_MV_HP_CDF.length);
+    }
+
+    const band = coefficient_cdf_band(base_q_idx);
+
+    copy_band(cdf.txb_skip, DEFAULT_TXB_SKIP_CDF, band);
+    copy_band(cdf.eob_pt_16, DEFAULT_EOB_PT_16_CDF, band);
+    copy_band(cdf.eob_pt_32, DEFAULT_EOB_PT_32_CDF, band);
+    copy_band(cdf.eob_pt_64, DEFAULT_EOB_PT_64_CDF, band);
+    copy_band(cdf.eob_pt_128, DEFAULT_EOB_PT_128_CDF, band);
+    copy_band(cdf.eob_pt_256, DEFAULT_EOB_PT_256_CDF, band);
+    copy_band(cdf.eob_pt_512, DEFAULT_EOB_PT_512_CDF, band);
+    copy_band(cdf.eob_pt_1024, DEFAULT_EOB_PT_1024_CDF, band);
+    copy_band(cdf.eob_extra, DEFAULT_EOB_EXTRA_CDF, band);
+    copy_band(cdf.dc_sign, DEFAULT_DC_SIGN_CDF, band);
+    copy_band(cdf.coeff_base_eob, DEFAULT_COEFF_BASE_EOB_CDF, band);
+    copy_band(cdf.coeff_base, DEFAULT_COEFF_BASE_CDF, band);
+    copy_band(cdf.coeff_br, DEFAULT_COEFF_BR_CDF, band);
+}

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

@@ -0,0 +1,103 @@
+/**
+ * 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: Uint8Array;
+    /** @type {number} index of the byte holding the next bit */
+    byte_position: number;
+    /** @type {number} index of the next bit within that byte, `0` being the most significant */
+    bit_position: number;
+    /** @type {number} index one past the last readable byte */
+    end: number;
+    /** @type {number} `SymbolValue` */
+    symbol_value: number;
+    /** @type {number} `SymbolRange` */
+    symbol_range: number;
+    /** @type {number} `SymbolMaxBits`; goes negative once the payload is exhausted */
+    symbol_max_bits: number;
+    /**
+     * `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: number;
+    /**
+     * `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: Uint8Array, byte_offset: number, size: number, disable_cdf_update?: number): SymbolReader;
+    /**
+     * `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: Uint16Array, offset: number, n: number): number;
+    /**
+     * `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(): number;
+    /**
+     * `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: number): number;
+    /**
+     * `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: number): number;
+    /**
+     * `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(): void;
+    #private;
+}
+//# sourceMappingURL=SymbolReader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SymbolReader.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/entropy/SymbolReader.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IACI,yBAAyB;IACzB,MADW,UAAU,CACT;IAEZ,4DAA4D;IAC5D,eADW,MAAM,CACC;IAElB,4FAA4F;IAC5F,cADW,MAAM,CACA;IAEjB,2DAA2D;IAC3D,KADW,MAAM,CACT;IAER,mCAAmC;IACnC,cADW,MAAM,CACA;IAEjB,mCAAmC;IACnC,cADW,MAAM,CACA;IAEjB,kFAAkF;IAClF,iBADW,MAAM,CACG;IAEpB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;;;;;;OASG;IACH,WAPW,UAAU,eACV,MAAM,QACN,MAAM,uBACN,MAAM,GACJ,YAAY,CAuBxB;IA2CD;;;;;;;;OAQG;IACH,iBANW,WAAW,UACX,MAAM,KACN,MAAM,GACJ,MAAM,CA0ElB;IAED;;;;;;;;;OASG;IACH,aAHa,MAAM,CA6ClB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;OAMG;IACH,WAJW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;OASG;IACH,aAOC;;CACJ"}