@woosh/meep-engine 3.9.0 → 3.11.0

package/src/avif/native/av1/encode/Av1BlockSnapshot.js

@@ -0,0 +1,299 @@
+import { BLOCK_DECODED_ORIGIN, BLOCK_DECODED_STRIDE } from "../decode/Av1FrameContext.js";
+import { NUM_4X4_BLOCKS_HIGH, NUM_4X4_BLOCKS_WIDE } from "../tables/block_tables.js";
+
+/**
+ * Widest block a snapshot has to hold, in samples.
+ * @type {number}
+ */
+const MAX_SIDE = 64;
+
+/**
+ * The same in 4x4 units, and the stride of every mode-info plane a snapshot holds.
+ * @type {number}
+ */
+export const SNAPSHOT_STRIDE = MAX_SIDE / 4;
+
+/**
+ * @type {number}
+ */
+const MAX_SIDE4 = SNAPSHOT_STRIDE;
+
+/**
+ * Samples one plane of the largest block holds.
+ * @type {number}
+ */
+const PLANE_SAMPLES = MAX_SIDE * MAX_SIDE;
+
+/**
+ * Entries one mode-info plane holds, which is also how many 4x4 positions a superblock has.
+ * @type {number}
+ */
+const MODE_INFO_ENTRIES = MAX_SIDE4 * MAX_SIDE4;
+
+/**
+ * @type {number}
+ */
+export const SUPERBLOCK_POSITIONS = MODE_INFO_ENTRIES;
+
+/**
+ * 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 {
+    constructor() {
+        const samples = PLANE_SAMPLES * 3;
+        const runs = MAX_SIDE4 * 3 * 4;
+        const flags = MODE_INFO_ENTRIES * 3;
+        const info = MODE_INFO_ENTRIES * 6;
+
+        const buffer = new ArrayBuffer(samples * 2 + runs + flags + info);
+
+        let at = 0;
+
+        /** @type {Uint16Array[]} the reconstruction under the block, one plane at a time */
+        this.planes = [];
+
+        for (let plane = 0; plane < 3; plane++) {
+            this.planes.push(new Uint16Array(buffer, at, PLANE_SAMPLES));
+
+            at += PLANE_SAMPLES * 2;
+        }
+
+        /** @type {Uint8Array[]} */
+        this.above_level = [];
+
+        /** @type {Uint8Array[]} */
+        this.above_dc = [];
+
+        /** @type {Uint8Array[]} */
+        this.left_level = [];
+
+        /** @type {Uint8Array[]} */
+        this.left_dc = [];
+
+        for (const run of [this.above_level, this.above_dc, this.left_level, this.left_dc]) {
+            for (let plane = 0; plane < 3; plane++) {
+                run.push(new Uint8Array(buffer, at, MAX_SIDE4));
+
+                at += MAX_SIDE4;
+            }
+        }
+
+        /** @type {Uint8Array[]} which of the block's own transform blocks have been coded */
+        this.block_decoded = [];
+
+        for (let plane = 0; plane < 3; plane++) {
+            this.block_decoded.push(new Uint8Array(buffer, at, MODE_INFO_ENTRIES));
+
+            at += MODE_INFO_ENTRIES;
+        }
+
+        /** @type {Uint8Array} */
+        this.y_modes = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+
+        at += MODE_INFO_ENTRIES;
+
+        /** @type {Uint8Array} */
+        this.uv_modes = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+
+        at += MODE_INFO_ENTRIES;
+
+        /** @type {Uint8Array} */
+        this.mi_sizes = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+
+        at += MODE_INFO_ENTRIES;
+
+        /** @type {Uint8Array} */
+        this.skips = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+
+        at += MODE_INFO_ENTRIES;
+
+        /** @type {Uint8Array} */
+        this.tx_types = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+
+        at += MODE_INFO_ENTRIES;
+
+        /** @type {Uint8Array} */
+        this.tx_sizes = new Uint8Array(buffer, at, MODE_INFO_ENTRIES);
+    }
+}
+
+/**
+ * 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, snapshot, r, c, b_size) {
+    move_block(ctx, snapshot, r, c, b_size, 1);
+}
+
+/**
+ * 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, snapshot, r, c, b_size) {
+    move_block(ctx, snapshot, r, c, b_size, 0);
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {Av1BlockSnapshot} snapshot
+ * @param {number} r
+ * @param {number} c
+ * @param {number} b_size
+ * @param {number} capture `1` context to snapshot, `0` snapshot to context
+ */
+function move_block(ctx, snapshot, r, c, b_size, capture) {
+    const bw4 = NUM_4X4_BLOCKS_WIDE[b_size];
+    const bh4 = NUM_4X4_BLOCKS_HIGH[b_size];
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+        const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+        const x0 = (c * 4) >> sub_x;
+        const y0 = (r * 4) >> sub_y;
+        const width = (bw4 * 4) >> sub_x;
+        const height = (bh4 * 4) >> sub_y;
+
+        const live = ctx.planes[plane];
+        const stride = ctx.plane_stride[plane];
+        const saved = snapshot.planes[plane];
+
+        for (let i = 0; i < height; i++) {
+            const a = (y0 + i) * stride + x0;
+            const b = i * width;
+
+            if (capture === 1) {
+                for (let j = 0; j < width; j++) {
+                    saved[b + j] = live[a + j];
+                }
+            } else {
+                for (let j = 0; j < width; j++) {
+                    live[a + j] = saved[b + j];
+                }
+            }
+        }
+
+        move_run(ctx.above_level_context[plane], c >> sub_x, snapshot.above_level[plane], bw4 >> sub_x, capture);
+        move_run(ctx.above_dc_context[plane], c >> sub_x, snapshot.above_dc[plane], bw4 >> sub_x, capture);
+        move_run(ctx.left_level_context[plane], r >> sub_y, snapshot.left_level[plane], bh4 >> sub_y, capture);
+        move_run(ctx.left_dc_context[plane], r >> sub_y, snapshot.left_dc[plane], bh4 >> sub_y, capture);
+
+        // only the block's own square: a transform block sets the flag for the samples it covers
+        // and no others, so nothing outside can have changed
+        const flag_row = ((r & 15) >> sub_y) + BLOCK_DECODED_ORIGIN;
+        const flag_column = ((c & 15) >> sub_x) + BLOCK_DECODED_ORIGIN;
+
+        const flag_rows = bh4 >> sub_y;
+        const flag_columns = bw4 >> sub_x;
+
+        const live_flags = ctx.block_decoded[plane];
+        const saved_flags = snapshot.block_decoded[plane];
+
+        for (let i = 0; i < flag_rows; i++) {
+            const a = (flag_row + i) * BLOCK_DECODED_STRIDE + flag_column;
+            const b = i * MAX_SIDE4;
+
+            if (capture === 1) {
+                for (let j = 0; j < flag_columns; j++) {
+                    saved_flags[b + j] = live_flags[a + j];
+                }
+            } else {
+                for (let j = 0; j < flag_columns; j++) {
+                    live_flags[a + j] = saved_flags[b + j];
+                }
+            }
+        }
+    }
+
+    move_mode_info(ctx.y_modes, snapshot.y_modes, ctx, r, c, bw4, bh4, capture);
+    move_mode_info(ctx.uv_modes, snapshot.uv_modes, ctx, r, c, bw4, bh4, capture);
+    move_mode_info(ctx.mi_sizes, snapshot.mi_sizes, ctx, r, c, bw4, bh4, capture);
+    move_mode_info(ctx.skips, snapshot.skips, ctx, r, c, bw4, bh4, capture);
+    move_mode_info(ctx.tx_types, snapshot.tx_types, ctx, r, c, bw4, bh4, capture);
+    move_mode_info(ctx.inter_tx_sizes, snapshot.tx_sizes, ctx, r, c, bw4, bh4, capture);
+}
+
+/**
+ * @param {Uint8Array} live
+ * @param {number} start
+ * @param {Uint8Array} saved
+ * @param {number} count
+ * @param {number} capture
+ */
+function move_run(live, start, saved, count, capture) {
+    if (capture === 1) {
+        for (let i = 0; i < count; i++) {
+            saved[i] = live[start + i];
+        }
+
+        return;
+    }
+
+    for (let i = 0; i < count; i++) {
+        live[start + i] = saved[i];
+    }
+}
+
+/**
+ * @param {Uint8Array} live
+ * @param {Uint8Array} saved
+ * @param {Av1FrameContext} ctx
+ * @param {number} r
+ * @param {number} c
+ * @param {number} bw4
+ * @param {number} bh4
+ * @param {number} capture
+ */
+function move_mode_info(live, saved, ctx, r, c, bw4, bh4, capture) {
+    const stride = ctx.mi_stride;
+
+    const rows = Math.min(bh4, ctx.mi_rows - r);
+    const columns = Math.min(bw4, ctx.mi_cols - c);
+
+    for (let i = 0; i < rows; i++) {
+        const a = (r + i) * stride + c;
+        const b = i * MAX_SIDE4;
+
+        if (capture === 1) {
+            for (let j = 0; j < columns; j++) {
+                saved[b + j] = live[a + j];
+            }
+        } else {
+            for (let j = 0; j < columns; j++) {
+                live[a + j] = saved[b + j];
+            }
+        }
+    }
+}

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

@@ -0,0 +1,384 @@
+/**
+ * Fields of {@link Av1EncodeContext#decisions}, in the order they are laid out.
+ * @type {number}
+ */
+export const DECISION_Y_MODE: number;
+/** @type {number} */
+export const DECISION_UV_MODE: number;
+/** @type {number} */
+export const DECISION_SKIP: number;
+/** @type {number} */
+export const DECISION_TX_TYPE: number;
+/** @type {number} */
+export const DECISION_TX_SIZE: number;
+/**
+ * Everything an encode needs on top of what a decode does.
+ *
+ * The frame context is the decoder's, unchanged: an encoder has to hold the *reconstruction* — what
+ * the decoder will end up with — because that is what the next block predicts from. Keeping the same
+ * struct means the two cannot drift apart in what they think a plane or a context is.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Av1EncodeContext {
+    /** @type {Av1FrameContext} holds the reconstruction, the contexts and the symbol writer */
+    frame_context: Av1FrameContext;
+    /** @type {SequenceHeader} */
+    sequence: SequenceHeader;
+    /** @type {FrameHeader} */
+    frame: FrameHeader;
+    /** @type {Uint16Array[]} the picture being encoded, padded out to the mode info grid */
+    source: Uint16Array[];
+    /** @type {Int32Array} */
+    source_stride: Int32Array;
+    /** @type {Int32Array} residual, then coefficients */
+    residual: Int32Array;
+    /**
+     * Quantised levels of the transform block being coded, one view per plane.
+     *
+     * A plane of one block holds as many levels as it has samples however it is cut into transform
+     * blocks — sixty-four four by fours or one thirty-two by thirty-two come to the same thousand
+     * and twenty-four — so one buffer per plane covers every transform size the encoder can pick,
+     * with each transform block's levels laid end to end.
+     *
+     * The three are views into one allocation, laid out in the order they are used. Three separate
+     * typed arrays would be three separate objects on the heap with nothing keeping them near each
+     * other; one buffer keeps a block's whole working set inside a page.
+     * @type {Int32Array[]}
+     */
+    levels: Int32Array[];
+    /** @type {Int32Array} whether each plane's chosen levels are all zero */
+    chosen_empty: Int32Array;
+    /**
+     * @type {number} squared error in the coefficient domain that the last quantised transform
+     * block cost, which is what a trial reads instead of reconstructing to find out
+     */
+    quantised_error: number;
+    /**
+     * @type {number} `1` to measure a trial's loss by reconstructing it and subtracting the source,
+     * rather than by reading it off the quantiser. Slower by the price of an inverse transform per
+     * candidate, and here to keep the cheap answer honest
+     */
+    exact_trial_distortion: number;
+    /**
+     * @type {number} `1` while a plane is being coded only so that what comes after it can see the
+     * reconstruction, which is the one time a trial has to build one
+     */
+    materialising: number;
+    /** @type {number} the transform type the block's luma residual is coded with */
+    luma_tx_type: number;
+    /** @type {number} what the winning luma mode's plane cost, which the transform search starts from */
+    chosen_plane_cost: number;
+    /** @type {number} whether the plane the last trial priced quantised to nothing */
+    trial_empty: number;
+    /** @type {number} the same, for the U plane, which the chroma decision prices before the V */
+    trial_empty_u: number;
+    /** @type {Int32Array} candidate prediction modes, best-predicting first */
+    mode_order: Int32Array;
+    /** @type {Float64Array} the squared prediction error each entry of {@link mode_order} scored */
+    mode_error: Float64Array;
+    /**
+     * Writers that price rather than emit, one per level of the search that nests inside another.
+     *
+     * The same class as the one that writes the bitstream, in its costing mode: the coefficient
+     * writer is handed one or the other, and it is the hottest function in the encoder, so what it
+     * sees at that call site has to be one shape rather than two.
+     * @type {SymbolWriter}
+     */
+    cost_writer: SymbolWriter;
+    /** @type {SymbolWriter} prices a whole block, which nests around {@link cost_writer} */
+    block_cost_writer: SymbolWriter;
+    /** @type {SymbolWriter} prices a partition symbol, which nests around both */
+    partition_cost_writer: SymbolWriter;
+    /** @type {number} the dequantiser the last quantised block's DC will be multiplied back up by */
+    step_dc: number;
+    /** @type {number} and its AC */
+    step_ac: number;
+    /** @type {number} and what the dequantiser divides by afterwards */
+    step_denominator: number;
+    /** @type {number} squared error the block being priced would leave behind */
+    block_distortion: number;
+    /**
+     * Saved state a partition decision can be put back to.
+     *
+     * One for the superblock, whose search has to be undone in full before the winning tree is
+     * written, and then two for each depth that decides anything — the state before any answer was
+     * tried, and the state the best answer so far left, so that answer does not have to be made
+     * again when it turns out to have won. Blocks run 32x32 down to 8x8 and each of those three
+     * decides, so seven is the whole of it.
+     * @type {Av1BlockSnapshot[]}
+     */
+    snapshots: Av1BlockSnapshot[];
+    /**
+     * What the search settled on, for the whole frame: one entry per 4x4 position per field.
+     *
+     * Frame-wide rather than a superblock at a time because the writing pass may have to run twice.
+     * Loop restoration is chosen from the finished, filtered picture and coded per superblock
+     * *inside* the tile, so the only way to write it is to code the tile once, look at what came
+     * out, and then code it again from the same decisions.
+     * @type {Uint8Array}
+     */
+    decisions: Uint8Array;
+    /**
+     * How far apart the fields of {@link decisions} are, which is one frame of 4x4 positions.
+     * @type {number}
+     */
+    decision_stride: number;
+    /**
+     * Which partition the search chose at each node, by depth and corner, for the whole frame.
+     *
+     * Not in the snapshot, because a node writes only its own entry and a losing branch's children
+     * are never read: the writing pass descends only where the parent says it split.
+     * @type {Uint8Array}
+     */
+    partitions: Uint8Array;
+    /**
+     * How many of the eight uneven partitions are searched, in the order they are worth asking
+     * about: the two halves, then the four T-shapes, then the two quarterings.
+     *
+     * Each is another whole subtree to price and they are gated on the whole and the quartered
+     * answers being close, so this is a knob rather than a fact.
+     * @type {number}
+     */
+    uneven_partitions: number;
+    /** @type {Int32Array} scratch for the Walsh-Hadamard pair */
+    scratch: Int32Array;
+    /** @type {number} the quantiser step the frame's decisions are measured against */
+    quantiser_step: number;
+    /**
+     * Squared error the encoder will give up to save one bit.
+     *
+     * The slope of the rate-distortion curve at this quantiser: a decision is taken when
+     * `distortion + lambda * rate` falls, which is the Lagrangian that makes "smaller" and "better"
+     * one number rather than two. Set per frame by {@link encode_av1_still} from the quantiser step,
+     * because the trade is worth more where the quantiser is coarse.
+     *
+     * In squared error per {@link COST_ONE_BIT} of rate, so that the rate the cost writer reports
+     * can be used without scaling it first.
+     * @type {number}
+     */
+    lambda: number;
+    /**
+     * @type {Uint16Array[]} the reconstruction before any in-loop filter, so that a filter strength
+     * can be tried, measured and taken back
+     */
+    unfiltered: Uint16Array[];
+    /**
+     * How many deblocking levels are measured before refining around the best of them.
+     *
+     * Zero signals no deblocking at all, which is what this encoder did before it could measure.
+     * @type {number}
+     */
+    filter_trials: number;
+    /**
+     * How many directional filter strengths are measured.
+     *
+     * One pass over the frame measures one candidate for luma and one for chroma at once, because
+     * the two are independent — a strength touches only its own planes. Zero signals no directional
+     * filter at all.
+     *
+     * Three rather than the whole ladder: each is a pass over the frame, and because the ladder is
+     * ordered to spread rather than to crowd the weak end, three of them come within a percent of
+     * all twelve and cost a third of what they do.
+     * @type {number}
+     */
+    cdef_trials: number;
+    /**
+     * Size the filter scratch for a frame, allocating only what has grown.
+     *
+     * @param {Av1FrameContext} ctx
+     */
+    resize_filters(ctx: Av1FrameContext): void;
+    /**
+     * Make room for the restoration fit: one plane of intermediates, one unit index per 4x4 block,
+     * and the normal equations of every unit at once.
+     *
+     * @param {Av1FrameContext} ctx
+     */
+    resize_restoration(ctx: Av1FrameContext): void;
+    /** @type {Float32Array} one plane, with one direction's taps run over it */
+    restoration_middle: Float32Array;
+    /** @type {Int32Array} which restoration unit each 4x4 block of a plane belongs to */
+    restoration_map: Int32Array;
+    /** @type {Float64Array} the normal equations of every unit: nine of a matrix, then three of a
+     * right hand side */
+    restoration_stats: Float64Array;
+    /** @type {Float64Array} squared error per unit, with the filter and without it */
+    restoration_errors: Float64Array;
+    /** @type {Int32Array} three coded taps expanded into the seven of a symmetric filter */
+    restoration_taps: Int32Array;
+    /** @type {Float64Array} the three sums one sample contributes to a fit */
+    restoration_basis: Float64Array;
+    /** @type {Float64Array} the augmented matrix a unit's fit is eliminated in */
+    restoration_system: Float64Array;
+    /** @type {Float64Array} the taps it comes out with, before they are rounded and clamped */
+    restoration_solution: Float64Array;
+    /** @type {Int8Array} one plane's reference taps, put back after a unit is priced */
+    restoration_reference: Int8Array;
+    /** @type {SymbolWriter} prices a restoration unit by writing its real syntax */
+    restoration_writer: SymbolWriter;
+    /** @type {number} restoration units down the frame, for the plane being fitted */
+    restoration_rows: number;
+    /** @type {number} and across it */
+    restoration_columns: number;
+    /**
+     * How many times the restoration fit alternates between the two directions.
+     *
+     * The first round fits the horizontal taps against the picture as it is and the vertical ones
+     * against what those left; a second round refits both against each other and is where the fit
+     * settles. Zero asks for no restoration at all, which is what a frame gets when the filter
+     * would cost more than it saves everywhere.
+     * @type {number}
+     */
+    restoration_trials: number;
+    /**
+     * How large a restoration unit is: zero for sixty-four samples, one for a hundred and
+     * twenty-eight, two for two hundred and fifty-six.
+     *
+     * A unit's taps cost thirty or forty bits whatever it covers, so the smallest units are the
+     * most adapted and the least affordable — on a small picture sixty-four sample units would
+     * spend a tenth of the file describing filters. Two hundred and fifty-six is where the cost
+     * disappears and most of the gain is still there.
+     * @type {number}
+     */
+    restoration_unit_shift: number;
+    /** @type {number} how many planes are offered a restoration filter */
+    restoration_planes: number;
+    /**
+     * Which in-loop filters the file asks the reader to run: one of the `DECODE_*` constants.
+     *
+     * The other axis to effort, and an unrelated one — this one spends the *reader's* time rather
+     * than this machine's. See {@link decode_effort.js} for what each setting costs and buys, and
+     * for why a codec that exists to load textures defaults to the fast one.
+     * @type {number}
+     */
+    decode_effort: number;
+    /** @type {ColourTransform} how the caller's RGB becomes the planes this codes */
+    transform: ColourTransform;
+    /** @type {Float32Array} one row of interleaved RGB, at the padded width */
+    rgb_row: Float32Array;
+    /** @type {Float32Array} */
+    cb_row: Float32Array;
+    /** @type {Float32Array} */
+    cr_row: Float32Array;
+    /** @type {Float32Array} one chroma row being averaged into */
+    chroma_blue: Float32Array;
+    /** @type {Float32Array} */
+    chroma_red: Float32Array;
+    /** @type {Float32Array} */
+    chroma_weight: Float32Array;
+    /** @type {number} */
+    row_width: number;
+    /**
+     * @param {number} width the padded width, in luma samples
+     */
+    resize_rows(width: number): void;
+    /**
+     * How far a coefficient must be past a quantiser step before it is coded at all, as a fraction
+     * of the step.
+     *
+     * Below one half this is a dead zone: it costs a little accuracy on coefficients that were
+     * nearly zero anyway, and saves a great many bits, because a coefficient that quantises to zero
+     * costs almost nothing to code.
+     *
+     * Nine twentieths of a step, which is where it measures best. It is also, now, the *only* thing
+     * deciding: an encoder that also priced the last few coefficients against what coding them cost,
+     * and dropped the ones that did not pay, measured half a per cent *worse* than this and took
+     * five times as long over the coefficient syntax. See D35.
+     * @type {number}
+     */
+    rounding: number;
+    /**
+     * What a split costs at the very least, in bits, below which one is not looked for.
+     *
+     * Splitting a block into four writes a partition symbol and then, per quarter, a skip flag and
+     * a luma and a chroma mode — a dozen bits before a single coefficient. So a block already
+     * costing less than a dozen bits' worth of squared error cannot be improved by splitting it,
+     * whatever the four quarters would do, and the whole subtree under it can go unsearched.
+     *
+     * That is nearly a proof rather than a heuristic; the "nearly" is that the dozen is a count of
+     * symbols rather than a floor on what those symbols cost in this block's contexts. Raising it
+     * trades compression for speed, and it is the first knob to reach for.
+     * @type {number}
+     */
+    split_floor: number;
+    /**
+     * How close the whole and the quartered answers must be before the halves are searched too.
+     *
+     * A half is the answer between a whole and a quarter, so it is worth asking about exactly when
+     * those two are close. When one wins outright the picture has already said whether the detail
+     * here is worth another partition symbol, and two more subtrees will not change its mind —
+     * while each costs as much again as the unsplit answer did. One turns the rectangles off; a
+     * large number searches them always.
+     * @type {number}
+     */
+    rectangle_margin: number;
+    /**
+     * {@link lambda} as a multiple of the squared quantiser step.
+     *
+     * The constant in the usual relation between a quantiser and the slope of the rate-distortion
+     * curve, and it has to be measured rather than derived: the step it multiplies is the
+     * *transform-domain* dequantiser, the distortion it converts to is in samples, and the ratio
+     * between those depends on the transform's gain.
+     *
+     * Measured as the encoder's own slope — encode at two quantisers, divide the change in squared
+     * error over the coded planes by the change in coded bits — which comes out at this value to
+     * within a sixth across photographic and synthetic pictures and across three decades of
+     * quantiser. That is a property of the format's quantiser tables, not of the pictures.
+     * @type {number}
+     */
+    lambda_scale: number;
+    /**
+     * How many prediction modes are priced properly, out of the thirteen.
+     *
+     * Every candidate is predicted and ranked by how close its prediction lands; only this many are
+     * then transformed, quantised and costed. The ranking is nearly free and the pricing is not, and
+     * the mode that wins on rate and distortion is almost always among the two or three that
+     * predicted best. Raising this is the quality-for-time knob; two is a sensible floor and
+     * thirteen is an exhaustive search.
+     * @type {number}
+     */
+    mode_trials: number;
+    /**
+     * How many transforms beyond the plain DCT the block's luma residual is tried against.
+     *
+     * Zero codes every block with a DCT, which is what the format's larger transform sizes allow
+     * anyway. Three is the whole of what {@link forward_transform_2d} can build a matrix for.
+     * @type {number}
+     */
+    transform_trials: number;
+    /**
+     * How many transform sizes the block's luma is tried at, largest first.
+     *
+     * One takes the largest the block allows, which is what the format calls largest-transform mode
+     * and is what this encoder did before it could ask. Each step after that halves again, and the
+     * returns fall away quickly: the first is worth 1.7% and the second 0.6%.
+     * @type {number}
+     */
+    transform_depths: number;
+    /**
+     * Make room for a frame's worth of decisions.
+     *
+     * The five fields live end to end in one array rather than in five of their own, because they
+     * are read together, one position at a time, by the writing pass.
+     *
+     * @param {number} mi_count 4x4 positions in the frame
+     */
+    resize_decisions(mi_count: number): void;
+    /**
+     * @param {number} width
+     * @param {number} height
+     * @param {number} subsampling_x
+     * @param {number} subsampling_y
+     * @param {number} num_planes
+     */
+    resize_source(width: number, height: number, subsampling_x: number, subsampling_y: number, num_planes: number): void;
+}
+import { Av1FrameContext } from "../decode/Av1FrameContext.js";
+import { SequenceHeader } from "../obu/SequenceHeader.js";
+import { FrameHeader } from "../obu/FrameHeader.js";
+import { SymbolWriter } from "../entropy/SymbolWriter.js";
+import { Av1BlockSnapshot } from "./Av1BlockSnapshot.js";
+import { ColourTransform } from "../../color/ColourTransform.js";
+//# sourceMappingURL=Av1EncodeContext.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Av1EncodeContext.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/Av1EncodeContext.js"],"names":[],"mappings":"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"}