@woosh/meep-engine 3.9.0 → 3.11.0

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

@@ -0,0 +1,590 @@
+import { Av1BlockSnapshot } from "./Av1BlockSnapshot.js";
+import { DECODE_FAST } from "./decode_effort.js";
+import { Av1FrameContext } from "../decode/Av1FrameContext.js";
+import { ColourTransform } from "../../color/ColourTransform.js";
+import { SymbolWriter } from "../entropy/SymbolWriter.js";
+import { FrameHeader } from "../obu/FrameHeader.js";
+import { INTRA_MODES } from "../tables/av1_symbols.js";
+import { SequenceHeader } from "../obu/SequenceHeader.js";
+
+/**
+ * Largest transform this encoder emits, in samples along one side.
+ * @type {number}
+ */
+const MAX_TRANSFORM = 32;
+
+/**
+ * Three views of the same length over one allocation, laid end to end.
+ *
+ * Per-plane scratch is asked for one plane at a time and in order, so putting the three next to
+ * each other in memory is worth doing on purpose: three separately allocated typed arrays are three
+ * objects the heap may put anywhere, and the encoder walks all three of them for every block.
+ *
+ * @param {Function} kind the typed array constructor
+ * @param {number} length entries per plane
+ * @returns {Array} three views
+ */
+function plane_views(kind, length) {
+    const buffer = new ArrayBuffer(length * kind.BYTES_PER_ELEMENT * 3);
+
+    return [
+        new kind(buffer, 0, length),
+        new kind(buffer, length * kind.BYTES_PER_ELEMENT, length),
+        new kind(buffer, length * kind.BYTES_PER_ELEMENT * 2, length)
+    ];
+}
+
+/**
+ * Fields of {@link Av1EncodeContext#decisions}, in the order they are laid out.
+ * @type {number}
+ */
+export const DECISION_Y_MODE = 0;
+
+/** @type {number} */
+export const DECISION_UV_MODE = 1;
+
+/** @type {number} */
+export const DECISION_SKIP = 2;
+
+/** @type {number} */
+export const DECISION_TX_TYPE = 3;
+
+/** @type {number} */
+export const DECISION_TX_SIZE = 4;
+
+/** @type {number} */
+const DECISION_FIELDS = 5;
+
+/**
+ * Depths a partition is recorded at: a superblock is 64x64 and the smallest block is 4x4, so a node
+ * sits at one of 64, 32, 16, 8 or 4.
+ * @type {number}
+ */
+const PARTITION_DEPTHS = 5;
+
+/**
+ * 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 = new Av1FrameContext();
+
+    /** @type {SequenceHeader} */
+    sequence = new SequenceHeader();
+
+    /** @type {FrameHeader} */
+    frame = new FrameHeader();
+
+    /** @type {Uint16Array[]} the picture being encoded, padded out to the mode info grid */
+    source = [null, null, null];
+
+    /** @type {Int32Array} */
+    source_stride = new Int32Array(3);
+
+    /** @type {Int32Array} residual, then coefficients */
+    residual = new Int32Array(MAX_TRANSFORM * MAX_TRANSFORM);
+
+    /**
+     * 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 = plane_views(Int32Array, MAX_TRANSFORM * MAX_TRANSFORM);
+
+    /** @type {Int32Array} whether each plane's chosen levels are all zero */
+    chosen_empty = new Int32Array(3);
+
+    /**
+     * @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 = 0;
+
+    /**
+     * @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 = 0;
+
+    /**
+     * @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 = 0;
+
+    /** @type {number} the transform type the block's luma residual is coded with */
+    luma_tx_type = 0;
+
+    /** @type {number} what the winning luma mode's plane cost, which the transform search starts from */
+    chosen_plane_cost = 0;
+
+    /** @type {number} whether the plane the last trial priced quantised to nothing */
+    trial_empty = 1;
+
+    /** @type {number} the same, for the U plane, which the chroma decision prices before the V */
+    trial_empty_u = 1;
+
+    /** @type {Int32Array} candidate prediction modes, best-predicting first */
+    mode_order = new Int32Array(INTRA_MODES);
+
+    /** @type {Float64Array} the squared prediction error each entry of {@link mode_order} scored */
+    mode_error = new Float64Array(INTRA_MODES);
+
+    /**
+     * 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 = new SymbolWriter();
+
+    /** @type {SymbolWriter} prices a whole block, which nests around {@link cost_writer} */
+    block_cost_writer = new SymbolWriter();
+
+    /** @type {SymbolWriter} prices a partition symbol, which nests around both */
+    partition_cost_writer = new SymbolWriter();
+
+    /** @type {number} the dequantiser the last quantised block's DC will be multiplied back up by */
+    step_dc = 1;
+
+    /** @type {number} and its AC */
+    step_ac = 1;
+
+    /** @type {number} and what the dequantiser divides by afterwards */
+    step_denominator = 1;
+
+    /** @type {number} squared error the block being priced would leave behind */
+    block_distortion = 0;
+
+    /**
+     * 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 = [
+        new Av1BlockSnapshot(),
+        new Av1BlockSnapshot(),
+        new Av1BlockSnapshot(),
+        new Av1BlockSnapshot(),
+        new Av1BlockSnapshot(),
+        new Av1BlockSnapshot(),
+        new 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 = new Uint8Array(0);
+
+    /**
+     * How far apart the fields of {@link decisions} are, which is one frame of 4x4 positions.
+     * @type {number}
+     */
+    decision_stride = 0;
+
+    /**
+     * 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 = new Uint8Array(0);
+
+    /**
+     * 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 = 2;
+
+    /** @type {Int32Array} scratch for the Walsh-Hadamard pair */
+    scratch = new Int32Array(4);
+
+    /** @type {number} the quantiser step the frame's decisions are measured against */
+    quantiser_step = 1;
+
+    /**
+     * 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 = 1;
+
+    /**
+     * @type {Uint16Array[]} the reconstruction before any in-loop filter, so that a filter strength
+     * can be tried, measured and taken back
+     */
+    unfiltered = [null, null, null];
+
+    /**
+     * 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 = 7;
+
+    /**
+     * 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 = 3;
+
+    /**
+     * Size the filter scratch for a frame, allocating only what has grown.
+     *
+     * @param {Av1FrameContext} ctx
+     */
+    resize_filters(ctx) {
+        for (let plane = 0; plane < ctx.num_planes; plane++) {
+            const samples = ctx.plane_stride[plane] * ctx.plane_rows[plane];
+
+            const existing = this.unfiltered[plane];
+
+            if (existing === null || existing.length < samples) {
+                this.unfiltered[plane] = new Uint16Array(samples);
+            }
+        }
+    }
+
+    /**
+     * 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) {
+        let samples = 0;
+
+        for (let plane = 0; plane < ctx.num_planes; plane++) {
+            samples = Math.max(samples, ctx.plane_stride[plane] * ctx.plane_rows[plane]);
+        }
+
+        if (this.restoration_middle.length < samples) {
+            this.restoration_middle = new Float32Array(samples);
+        }
+
+        const blocks = ((ctx.plane_stride[0] >> 2) + 1) * ((ctx.plane_rows[0] >> 2) + 1);
+
+        if (this.restoration_map.length < blocks) {
+            this.restoration_map = new Int32Array(blocks);
+        }
+
+        const units = 3 * ctx.lr_unit_rows * ctx.lr_unit_stride;
+
+        if (this.restoration_stats.length < units * 12) {
+            this.restoration_stats = new Float64Array(units * 12);
+        }
+
+        if (this.restoration_errors.length < units * 2) {
+            this.restoration_errors = new Float64Array(units * 2);
+        }
+    }
+
+    /** @type {Float32Array} one plane, with one direction's taps run over it */
+    restoration_middle = new Float32Array(0);
+
+    /** @type {Int32Array} which restoration unit each 4x4 block of a plane belongs to */
+    restoration_map = new Int32Array(0);
+
+    /** @type {Float64Array} the normal equations of every unit: nine of a matrix, then three of a
+     * right hand side */
+    restoration_stats = new Float64Array(0);
+
+    /** @type {Float64Array} squared error per unit, with the filter and without it */
+    restoration_errors = new Float64Array(0);
+
+    /** @type {Int32Array} three coded taps expanded into the seven of a symmetric filter */
+    restoration_taps = new Int32Array(7);
+
+    /** @type {Float64Array} the three sums one sample contributes to a fit */
+    restoration_basis = new Float64Array(3);
+
+    /** @type {Float64Array} the augmented matrix a unit's fit is eliminated in */
+    restoration_system = new Float64Array(12);
+
+    /** @type {Float64Array} the taps it comes out with, before they are rounded and clamped */
+    restoration_solution = new Float64Array(3);
+
+    /** @type {Int8Array} one plane's reference taps, put back after a unit is priced */
+    restoration_reference = new Int8Array(6);
+
+    /** @type {SymbolWriter} prices a restoration unit by writing its real syntax */
+    restoration_writer = new SymbolWriter();
+
+    /** @type {number} restoration units down the frame, for the plane being fitted */
+    restoration_rows = 0;
+
+    /** @type {number} and across it */
+    restoration_columns = 0;
+
+    /**
+     * 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 = 2;
+
+    /**
+     * 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 = 2;
+
+    /** @type {number} how many planes are offered a restoration filter */
+    restoration_planes = 3;
+
+    /**
+     * 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 = DECODE_FAST;
+
+    /** @type {ColourTransform} how the caller's RGB becomes the planes this codes */
+    transform = new ColourTransform();
+
+    /** @type {Float32Array} one row of interleaved RGB, at the padded width */
+    rgb_row = null;
+
+    /** @type {Float32Array} */
+    cb_row = null;
+
+    /** @type {Float32Array} */
+    cr_row = null;
+
+    /** @type {Float32Array} one chroma row being averaged into */
+    chroma_blue = null;
+
+    /** @type {Float32Array} */
+    chroma_red = null;
+
+    /** @type {Float32Array} */
+    chroma_weight = null;
+
+    /** @type {number} */
+    row_width = 0;
+
+    /**
+     * @param {number} width the padded width, in luma samples
+     */
+    resize_rows(width) {
+        if (this.row_width >= width) {
+            return;
+        }
+
+        this.row_width = width;
+
+        this.rgb_row = new Float32Array(width * 3);
+        this.cb_row = new Float32Array(width);
+        this.cr_row = new Float32Array(width);
+
+        this.chroma_blue = new Float32Array(width);
+        this.chroma_red = new Float32Array(width);
+        this.chroma_weight = new Float32Array(width);
+    }
+
+    /**
+     * 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 = 0.45;
+
+    /**
+     * 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 = 12;
+
+    /**
+     * 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 = 1.2;
+
+    /**
+     * {@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 = 0.0016;
+
+    /**
+     * 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 = 3;
+
+    /**
+     * 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 = 3;
+
+    /**
+     * 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 = 3;
+
+
+    /**
+     * 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) {
+        if (this.decisions.length < mi_count * DECISION_FIELDS) {
+            this.decisions = new Uint8Array(mi_count * DECISION_FIELDS);
+        }
+
+        this.decision_stride = mi_count;
+
+        if (this.partitions.length < mi_count * PARTITION_DEPTHS) {
+            this.partitions = new Uint8Array(mi_count * PARTITION_DEPTHS);
+        }
+    }
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     * @param {number} subsampling_x
+     * @param {number} subsampling_y
+     * @param {number} num_planes
+     */
+    resize_source(width, height, subsampling_x, subsampling_y, num_planes) {
+        for (let plane = 0; plane < 3; plane++) {
+            if (plane >= num_planes) {
+                this.source[plane] = null;
+                this.source_stride[plane] = 0;
+
+                continue;
+            }
+
+            const sub_x = plane > 0 ? subsampling_x : 0;
+            const sub_y = plane > 0 ? subsampling_y : 0;
+
+            const stride = (width + sub_x) >> sub_x;
+            const rows = (height + sub_y) >> sub_y;
+
+            this.source_stride[plane] = stride;
+
+            const existing = this.source[plane];
+
+            if (existing === null || existing.length < stride * rows) {
+                this.source[plane] = new Uint16Array(stride * rows);
+            }
+        }
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Fill in a sequence header for a still picture.
+ *
+ * `reduced_still_picture_header` is set, which is what it exists for: it drops every field about
+ * timing, operating points and reference frames, none of which a single coded picture has.
+ *
+ * @param {SequenceHeader} sequence
+ * @param {object} options
+ * @param {number} options.width
+ * @param {number} options.height
+ * @param {number} options.bit_depth
+ * @param {number} options.monochrome
+ * @param {number} options.subsampling_x
+ * @param {number} options.subsampling_y
+ * @param {number} [options.color_primaries]
+ * @param {number} [options.transfer_characteristics]
+ * @param {number} [options.matrix_coefficients]
+ * @param {number} [options.color_range]
+ * @see AV1 spec 5.5.1 "General sequence header OBU syntax"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function build_sequence_header(sequence: SequenceHeader, options: {
+    width: number;
+    height: number;
+    bit_depth: number;
+    monochrome: number;
+    subsampling_x: number;
+    subsampling_y: number;
+    color_primaries?: number;
+    transfer_characteristics?: number;
+    matrix_coefficients?: number;
+    color_range?: number;
+}): void;
+/**
+ * Fill in a frame header for a still picture.
+ *
+ * @param {FrameHeader} frame
+ * @param {SequenceHeader} sequence
+ * @param {object} options
+ * @param {number} options.base_q_idx
+ * @param {number} options.restoration_unit_shift how large a loop restoration unit is
+ * @see AV1 spec 5.9.2 "Uncompressed header syntax"
+ */
+export function build_frame_header(frame: FrameHeader, sequence: SequenceHeader, options: {
+    base_q_idx: number;
+    restoration_unit_shift: number;
+}): void;
+//# sourceMappingURL=build_headers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build_headers.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/build_headers.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAf2B,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,SAAS,EAAzB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,aAAa,EAA7B,MAAM;IACU,aAAa,EAA7B,MAAM;IACW,eAAe,GAAhC,MAAM;IACW,wBAAwB,GAAzC,MAAM;IACW,mBAAmB,GAApC,MAAM;IACW,WAAW,GAA5B,MAAM;SAqFhB;AA6BD;;;;;;;;;GASG;AACH;IAJ2B,UAAU,EAA1B,MAAM;IACU,sBAAsB,EAAtC,MAAM;SA6HhB"}