@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/decode/reconstruct.js

@@ -0,0 +1,241 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import {
+    ADST_FLIPADST,
+    DCT_FLIPADST,
+    FLIPADST_ADST,
+    FLIPADST_DCT,
+    FLIPADST_FLIPADST,
+    H_FLIPADST,
+    IDTX,
+    MAX_SEGMENTS,
+    SEG_LVL_ALT_Q,
+    SEG_LVL_MAX,
+    TX_16X32,
+    TX_16X64,
+    TX_32X16,
+    TX_32X32,
+    TX_32X64,
+    TX_64X16,
+    TX_64X32,
+    TX_64X64,
+    V_FLIPADST
+} from "../tables/av1_symbols.js";
+import { QM_OFFSET, QUANTIZER_MATRIX } from "../tables/quantizer_matrix_tables.js";
+import { AC_QLOOKUP, DC_QLOOKUP } from "../tables/quantizer_tables.js";
+import { TX_HEIGHT, TX_WIDTH } from "../tables/block_tables.js";
+import { inverse_transform_2d } from "../transform/inverse_transform_2d.js";
+import { round2 } from "../util/round2.js";
+
+/**
+ * `Quantizer_Matrix` covers one level and plane type in this many entries.
+ * @type {number}
+ */
+const QM_TOTAL_SIZE = 3344;
+
+/**
+ * `dc_q( b )`. Exported because an encoder has to quantise with exactly what this dequantises with.
+ * @param {number} bit_depth
+ * @param {number} b
+ * @returns {number}
+ */
+export function dc_quant(bit_depth, b) {
+    return DC_QLOOKUP[((bit_depth - 8) >> 1) * 256 + clamp(b, 0, 255)];
+}
+
+/**
+ * `ac_q( b )`.
+ * @param {number} bit_depth
+ * @param {number} b
+ * @returns {number}
+ */
+export function ac_quant(bit_depth, b) {
+    return AC_QLOOKUP[((bit_depth - 8) >> 1) * 256 + clamp(b, 0, 255)];
+}
+
+/**
+ * `get_qindex( 0, segment_id )`: the block's quantizer index, honouring any per-block delta.
+ * @param {Av1FrameContext} ctx
+ * @returns {number}
+ * @see AV1 spec 7.12.2 "Dequantization functions"
+ */
+export function get_qindex(ctx) {
+    const frame = ctx.frame;
+    const segment = ctx.segment_id;
+
+    if (frame.segmentation_enabled === 1 && frame.feature_enabled[segment * SEG_LVL_MAX + SEG_LVL_ALT_Q] !== 0) {
+        const data = frame.feature_data[segment * SEG_LVL_MAX + SEG_LVL_ALT_Q];
+
+        const qindex = frame.delta_q_present === 1
+            ? ctx.current_q_index + data
+            : frame.base_q_idx + data;
+
+        return clamp(qindex, 0, 255);
+    }
+
+    if (frame.delta_q_present === 1) {
+        return ctx.current_q_index;
+    }
+
+    return frame.base_q_idx;
+}
+
+/**
+ * Whether the transform type flips its output vertically.
+ * @param {number} tx_type
+ * @returns {boolean}
+ */
+function flips_vertically(tx_type) {
+    return tx_type === FLIPADST_DCT
+        || tx_type === FLIPADST_ADST
+        || tx_type === V_FLIPADST
+        || tx_type === FLIPADST_FLIPADST;
+}
+
+/**
+ * Whether the transform type flips its output horizontally.
+ * @param {number} tx_type
+ * @returns {boolean}
+ */
+function flips_horizontally(tx_type) {
+    return tx_type === DCT_FLIPADST
+        || tx_type === ADST_FLIPADST
+        || tx_type === H_FLIPADST
+        || tx_type === FLIPADST_FLIPADST;
+}
+
+/**
+ * Dequantise, inverse transform and add the residual into the plane.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} x left edge of the transform block in plane samples
+ * @param {number} y top edge of the transform block in plane samples
+ * @param {number} tx_size
+ * @see AV1 spec 7.12.3 "Reconstruct process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function reconstruct(ctx, plane, x, y, tx_size) {
+    const frame = ctx.frame;
+    const bit_depth = ctx.bit_depth;
+
+    let dq_denom = 1;
+
+    if (tx_size === TX_32X32 || tx_size === TX_16X32 || tx_size === TX_32X16 || tx_size === TX_16X64 || tx_size === TX_64X16) {
+        dq_denom = 2;
+    } else if (tx_size === TX_64X64 || tx_size === TX_32X64 || tx_size === TX_64X32) {
+        dq_denom = 4;
+    }
+
+    const w = TX_WIDTH[tx_size];
+    const h = TX_HEIGHT[tx_size];
+
+    const tw = Math.min(32, w);
+    const th = Math.min(32, h);
+
+    const tx_type = ctx.plane_tx_type;
+
+    const flip_up_down = flips_vertically(tx_type);
+    const flip_left_right = flips_horizontally(tx_type);
+
+    const qindex = get_qindex(ctx);
+
+    const dc_q = dc_quant(bit_depth, qindex + dc_delta(frame, plane));
+    const ac_q = ac_quant(bit_depth, qindex + ac_delta(frame, plane));
+
+    const residual = ctx.residual;
+    const quant = ctx.quant;
+
+    residual.fill(0, 0, w * h);
+
+    const qm_level = frame.using_qmatrix === 1 ? frame.seg_qm_level[plane * MAX_SEGMENTS + ctx.segment_id] : 15;
+    const use_qm = frame.using_qmatrix === 1 && tx_type < IDTX && qm_level < 15;
+
+    const qm_base = use_qm
+        ? (qm_level * 2 + (plane > 0 ? 1 : 0)) * QM_TOTAL_SIZE + QM_OFFSET[tx_size]
+        : 0;
+
+    const limit = 1 << (7 + bit_depth);
+
+    for (let i = 0; i < th; i++) {
+        for (let j = 0; j < tw; j++) {
+            const level = quant[i * tw + j];
+
+            // a coefficient the quantiser zeroed dequantises to zero, and the residual is already
+            // zero there. Most of a block is this
+            if (level === 0) {
+                continue;
+            }
+
+            const q = i === 0 && j === 0 ? dc_q : ac_q;
+
+            const q2 = use_qm ? round2(q * QUANTIZER_MATRIX[qm_base + i * tw + j], 5) : q;
+
+            const dq = level * q2;
+
+            const sign = dq < 0 ? -1 : 1;
+
+            // the mask is not a clamp: the specification truncates the magnitude to 24 bits and
+            // only then divides, so a value above it wraps rather than saturating
+            const dq2 = sign * Math.floor((Math.abs(dq) & 0xffffff) / dq_denom);
+
+            residual[i * w + j] = clamp(dq2, -limit, limit - 1);
+        }
+    }
+
+    inverse_transform_2d(residual, tx_size, tx_type, ctx.lossless, bit_depth, ctx.transform_scratch);
+
+    const plane_data = ctx.planes[plane];
+    const stride = ctx.plane_stride[plane];
+    const plane_width = ctx.plane_width[plane];
+    const plane_height = ctx.plane_height[plane];
+
+    const max_value = (1 << bit_depth) - 1;
+
+    for (let i = 0; i < h; i++) {
+        const yy = flip_up_down ? h - i - 1 : i;
+
+        if (y + yy >= plane_height) {
+            continue;
+        }
+
+        const row = (y + yy) * stride;
+
+        for (let j = 0; j < w; j++) {
+            const xx = flip_left_right ? w - j - 1 : j;
+
+            if (x + xx >= plane_width) {
+                continue;
+            }
+
+            plane_data[row + x + xx] = clamp(plane_data[row + x + xx] + residual[i * w + j], 0, max_value);
+        }
+    }
+}
+
+/**
+ * @param {FrameHeader} frame
+ * @param {number} plane
+ * @returns {number}
+ */
+function dc_delta(frame, plane) {
+    if (plane === 0) {
+        return frame.delta_q_y_dc;
+    }
+
+    return plane === 1 ? frame.delta_q_u_dc : frame.delta_q_v_dc;
+}
+
+/**
+ * @param {FrameHeader} frame
+ * @param {number} plane
+ * @returns {number}
+ */
+function ac_delta(frame, plane) {
+    if (plane === 0) {
+        return 0;
+    }
+
+    return plane === 1 ? frame.delta_q_u_ac : frame.delta_q_v_ac;
+}

package/src/avif/native/av1/decode/transform_type.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Which set of transform types a transform size may choose from.
+ *
+ * The inter branches are kept even though this decoder never takes them: `get_tx_set` is also
+ * consulted when deciding whether a *chroma* transform type inherited from luma is legal, and
+ * keeping the function whole means that test reads the same way it does in the specification.
+ *
+ * @param {number} tx_size
+ * @param {number} is_inter
+ * @param {number} reduced_tx_set
+ * @returns {number} one of the `TX_SET_*` constants
+ * @see AV1 spec 5.11.48 "Get transform set function"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function get_tx_set(tx_size: number, is_inter: number, reduced_tx_set: number): number;
+/**
+ * @param {number} tx_set
+ * @param {number} tx_type
+ * @param {number} is_inter
+ * @returns {boolean}
+ */
+export function is_tx_type_in_set(tx_set: number, tx_type: number, is_inter: number): boolean;
+/**
+ * The transform type in force for a plane's transform block.
+ *
+ * Luma reads the type the bitstream recorded for that position. Chroma derives it from the chroma
+ * prediction mode, and falls back to a plain DCT when the derived type is not in the set this
+ * transform size allows.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} tx_size
+ * @param {number} block_x luma 4x4 column of the transform block
+ * @param {number} block_y luma 4x4 row of the transform block
+ * @returns {number}
+ * @see AV1 spec 5.11.40 "Compute transform type function"
+ */
+export function compute_tx_type(ctx: Av1FrameContext, plane: number, tx_size: number, block_x: number, block_y: number): number;
+/**
+ * The directional class of a transform type, which decides how coefficient contexts are gathered.
+ *
+ * @param {number} tx_type
+ * @returns {number} one of `TX_CLASS_2D`, `TX_CLASS_VERT`, `TX_CLASS_HORIZ`
+ * @see AV1 spec 8.3.2, `get_tx_class`
+ */
+export function get_tx_class(tx_type: number): number;
+//# sourceMappingURL=transform_type.d.ts.map

package/src/avif/native/av1/decode/transform_type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform_type.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/decode/transform_type.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,oCATW,MAAM,YACN,MAAM,kBACN,MAAM,GACJ,MAAM,CAmClB;AAED;;;;;GAKG;AACH,0CALW,MAAM,WACN,MAAM,YACN,MAAM,GACJ,OAAO,CAMnB;AAED;;;;;;;;;;;;;;GAcG;AACH,6DAPW,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,GACJ,MAAM,CAqBlB;AAED;;;;;;GAMG;AACH,sCAJW,MAAM,GACJ,MAAM,CAalB"}

package/src/avif/native/av1/decode/transform_type.js

@@ -0,0 +1,137 @@
+import {
+    DCT_DCT,
+    TX_16X16,
+    TX_32X32,
+    TX_SET_DCTONLY,
+    TX_SET_INTER_1,
+    TX_SET_INTER_2,
+    TX_SET_INTER_3,
+    TX_SET_INTRA_1,
+    TX_SET_INTRA_2,
+    TX_CLASS_2D,
+    TX_CLASS_HORIZ,
+    TX_CLASS_VERT,
+    H_ADST,
+    H_DCT,
+    H_FLIPADST,
+    V_ADST,
+    V_DCT,
+    V_FLIPADST
+} from "../tables/av1_symbols.js";
+import { TX_SIZE_SQR, TX_SIZE_SQR_UP } from "../tables/block_tables.js";
+import { TX_TYPE_IN_SET_INTRA, TX_TYPE_IN_SET_INTER } from "../tables/transform_tables.js";
+import { MODE_TO_TXFM } from "../tables/prediction_tables.js";
+import { TX_TYPES } from "../tables/av1_symbols.js";
+
+/**
+ * Which set of transform types a transform size may choose from.
+ *
+ * The inter branches are kept even though this decoder never takes them: `get_tx_set` is also
+ * consulted when deciding whether a *chroma* transform type inherited from luma is legal, and
+ * keeping the function whole means that test reads the same way it does in the specification.
+ *
+ * @param {number} tx_size
+ * @param {number} is_inter
+ * @param {number} reduced_tx_set
+ * @returns {number} one of the `TX_SET_*` constants
+ * @see AV1 spec 5.11.48 "Get transform set function"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function get_tx_set(tx_size, is_inter, reduced_tx_set) {
+    const square = TX_SIZE_SQR[tx_size];
+    const square_up = TX_SIZE_SQR_UP[tx_size];
+
+    if (square_up > TX_32X32) {
+        return TX_SET_DCTONLY;
+    }
+
+    if (is_inter === 1) {
+        if (reduced_tx_set === 1 || square_up === TX_32X32) {
+            return TX_SET_INTER_3;
+        }
+
+        if (square === TX_16X16) {
+            return TX_SET_INTER_2;
+        }
+
+        return TX_SET_INTER_1;
+    }
+
+    if (square_up === TX_32X32) {
+        return TX_SET_DCTONLY;
+    }
+
+    if (reduced_tx_set === 1 || square === TX_16X16) {
+        return TX_SET_INTRA_2;
+    }
+
+    return TX_SET_INTRA_1;
+}
+
+/**
+ * @param {number} tx_set
+ * @param {number} tx_type
+ * @param {number} is_inter
+ * @returns {boolean}
+ */
+export function is_tx_type_in_set(tx_set, tx_type, is_inter) {
+    const table = is_inter === 1 ? TX_TYPE_IN_SET_INTER : TX_TYPE_IN_SET_INTRA;
+
+    return table[tx_set * TX_TYPES + tx_type] !== 0;
+}
+
+/**
+ * The transform type in force for a plane's transform block.
+ *
+ * Luma reads the type the bitstream recorded for that position. Chroma derives it from the chroma
+ * prediction mode, and falls back to a plain DCT when the derived type is not in the set this
+ * transform size allows.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} tx_size
+ * @param {number} block_x luma 4x4 column of the transform block
+ * @param {number} block_y luma 4x4 row of the transform block
+ * @returns {number}
+ * @see AV1 spec 5.11.40 "Compute transform type function"
+ */
+export function compute_tx_type(ctx, plane, tx_size, block_x, block_y) {
+    if (ctx.lossless === 1 || TX_SIZE_SQR_UP[tx_size] > TX_32X32) {
+        return DCT_DCT;
+    }
+
+    const tx_set = get_tx_set(tx_size, 0, ctx.frame.reduced_tx_set);
+
+    if (plane === 0) {
+        return ctx.tx_types[block_y * ctx.mi_stride + block_x];
+    }
+
+    const tx_type = MODE_TO_TXFM[ctx.uv_mode];
+
+    if (!is_tx_type_in_set(tx_set, tx_type, 0)) {
+        return DCT_DCT;
+    }
+
+    return tx_type;
+}
+
+/**
+ * The directional class of a transform type, which decides how coefficient contexts are gathered.
+ *
+ * @param {number} tx_type
+ * @returns {number} one of `TX_CLASS_2D`, `TX_CLASS_VERT`, `TX_CLASS_HORIZ`
+ * @see AV1 spec 8.3.2, `get_tx_class`
+ */
+export function get_tx_class(tx_type) {
+    if (tx_type === V_DCT || tx_type === V_ADST || tx_type === V_FLIPADST) {
+        return TX_CLASS_VERT;
+    }
+
+    if (tx_type === H_DCT || tx_type === H_ADST || tx_type === H_FLIPADST) {
+        return TX_CLASS_HORIZ;
+    }
+
+    return TX_CLASS_2D;
+}

package/src/avif/native/av1/encode/Av1BlockSnapshot.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Copy the state a block covers into a snapshot.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Av1BlockSnapshot} snapshot
+ * @param {number} r
+ * @param {number} c
+ * @param {number} b_size
+ */
+export function capture_block(ctx: Av1FrameContext, snapshot: Av1BlockSnapshot, r: number, c: number, b_size: number): void;
+/**
+ * Put a snapshot back, undoing everything coding the block changed.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Av1BlockSnapshot} snapshot
+ * @param {number} r
+ * @param {number} c
+ * @param {number} b_size
+ */
+export function restore_block(ctx: Av1FrameContext, snapshot: Av1BlockSnapshot, r: number, c: number, b_size: number): void;
+/**
+ * The same in 4x4 units, and the stride of every mode-info plane a snapshot holds.
+ * @type {number}
+ */
+export const SNAPSHOT_STRIDE: number;
+/**
+ * @type {number}
+ */
+export const SUPERBLOCK_POSITIONS: number;
+/**
+ * Everything one block's coding changes that a later decision can see.
+ *
+ * A partition decision has to price both answers, and pricing one means *making* it: predicting,
+ * quantising, reconstructing, and advancing the contexts, because the block after this one predicts
+ * from the reconstruction and codes against those contexts. So the encoder does make it, measures
+ * it, and puts the state back.
+ *
+ * What is here is what a later decision reads: the reconstruction, the coefficient contexts either
+ * side, the flags saying which transform blocks have been coded, and the six mode-info planes that
+ * feed a neighbour's context — the modes, the block sizes, the skip flags, the transform types and
+ * the transform sizes. The rest of the mode-info planes are written by every block and read by
+ * nothing before the frame is whole.
+ *
+ * ### One allocation, not twenty
+ *
+ * All of it lives in a single `ArrayBuffer` with the typed arrays as views laid end to end. Twenty
+ * separately allocated arrays are twenty objects the heap may put anywhere, and a snapshot is taken
+ * and put back several times per block — so what is being copied wants to be one run of memory
+ * rather than twenty walks to find out where the next piece is. The sample planes come first
+ * because they are two-byte and want their alignment.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Av1BlockSnapshot {
+    /** @type {Uint16Array[]} the reconstruction under the block, one plane at a time */
+    planes: Uint16Array[];
+    /** @type {Uint8Array[]} */
+    above_level: Uint8Array[];
+    /** @type {Uint8Array[]} */
+    above_dc: Uint8Array[];
+    /** @type {Uint8Array[]} */
+    left_level: Uint8Array[];
+    /** @type {Uint8Array[]} */
+    left_dc: Uint8Array[];
+    /** @type {Uint8Array[]} which of the block's own transform blocks have been coded */
+    block_decoded: Uint8Array[];
+    /** @type {Uint8Array} */
+    y_modes: Uint8Array;
+    /** @type {Uint8Array} */
+    uv_modes: Uint8Array;
+    /** @type {Uint8Array} */
+    mi_sizes: Uint8Array;
+    /** @type {Uint8Array} */
+    skips: Uint8Array;
+    /** @type {Uint8Array} */
+    tx_types: Uint8Array;
+    /** @type {Uint8Array} */
+    tx_sizes: Uint8Array;
+}
+//# sourceMappingURL=Av1BlockSnapshot.d.ts.map

package/src/avif/native/av1/encode/Av1BlockSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Av1BlockSnapshot.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/Av1BlockSnapshot.js"],"names":[],"mappings":"AA6IA;;;;;;;;GAQG;AACH,8DALW,gBAAgB,KAChB,MAAM,KACN,MAAM,UACN,MAAM,QAIhB;AAED;;;;;;;;GAQG;AACH,8DALW,gBAAgB,KAChB,MAAM,KACN,MAAM,UACN,MAAM,QAIhB;AA5JD;;;GAGG;AACH,8BAFU,MAAM,CAE4B;AAmB5C;;GAEG;AACH,mCAFU,MAAM,CAEsC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAWQ,oFAAoF;IACpF,QADW,WAAW,EAAE,CACR;IAQhB,2BAA2B;IAC3B,aADW,UAAU,EAAE,CACF;IAErB,2BAA2B;IAC3B,UADW,UAAU,EAAE,CACL;IAElB,2BAA2B;IAC3B,YADW,UAAU,EAAE,CACH;IAEpB,2BAA2B;IAC3B,SADW,UAAU,EAAE,CACN;IAUjB,qFAAqF;IACrF,eADW,UAAU,EAAE,CACA;IAQvB,yBAAyB;IACzB,SADW,UAAU,CACuC;IAI5D,yBAAyB;IACzB,UADW,UAAU,CACwC;IAI7D,yBAAyB;IACzB,UADW,UAAU,CACwC;IAI7D,yBAAyB;IACzB,OADW,UAAU,CACqC;IAI1D,yBAAyB;IACzB,UADW,UAAU,CACwC;IAI7D,yBAAyB;IACzB,UADW,UAAU,CACwC;CAEpE"}