@woosh/meep-engine 3.8.0 → 3.10.0

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

@@ -0,0 +1,59 @@
+/**
+ * How much work the file asks of whoever reads it.
+ *
+ * The other axis to {@link EFFORT_FAST} and its neighbours, and an unrelated one. Encode effort
+ * spends *this* machine's time to make a smaller file; decode effort spends the *reader's* time to
+ * the same end, by signalling in-loop filters the decoder then has to run over the whole frame.
+ * A file is smaller with them and slower to read; the trade lands on different people.
+ *
+ * Measured over eight pictures — five of them photographs — against libavif at speed 6, at
+ * {@link EFFORT_BALANCED}, with the decode times on one megapixel of the same picture:
+ *
+ *     DECODE_FAST       +13.1% rate      115 ms/MP
+ *     DECODE_BALANCED    +8.6%           294 ms/MP
+ *     DECODE_THOROUGH    +7.9%           350 ms/MP
+ *
+ * The directional filter is the whole of that first step: four and a half points of rate for a
+ * hundred and seventy milliseconds a megapixel, because its direction search runs over every 8x8
+ * block of the frame. Restoration is the second: another seven tenths of a point for fifty-odd
+ * milliseconds. Deblocking is in all three because it is nearly free — fifteen milliseconds — and
+ * worth two and a half points.
+ *
+ * ### Why fast is the default
+ *
+ * A texture is decoded on the machine that will draw with it, once per load, competing with
+ * everything else that machine is doing. A megapixel texture five per cent larger costs a few
+ * kilobytes of download — tens of milliseconds on a slow connection, and cached after that — where
+ * the filters cost two hundred and forty milliseconds of CPU every single time it is read. For
+ * pictures that are decoded far more often than they are transferred, the fast setting is the right
+ * one by two orders of magnitude, and that is what this codec is for.
+ *
+ * Reverse it for anything whose bytes are the scarce thing: an image served to many readers over a
+ * network it is paid for by the gigabyte, where a fifth of a second on each of their machines is
+ * someone else's problem and five per cent of every transfer is yours.
+ *
+ * None of this changes fidelity at a given quality setting. What the filters buy is *rate* at
+ * matched fidelity — the same picture in fewer bytes, not a better one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Deblocking only. Three times faster to read, five per cent larger.
+ * @type {number}
+ */
+export const DECODE_FAST = 0;
+
+/**
+ * And the directional filter, which is most of what the other two settings cost and most of what
+ * they save.
+ * @type {number}
+ */
+export const DECODE_BALANCED = 1;
+
+/**
+ * And loop restoration: the smallest file this encoder makes, and the slowest to read.
+ * @type {number}
+ */
+export const DECODE_THOROUGH = 2;

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

@@ -0,0 +1,17 @@
+/**
+ * Encode the picture in an encode context as an AV1 still.
+ *
+ * Returns the sequence header on its own, for the container's `av1C` property, and the item payload
+ * — which carries a copy of that header followed by the coded frame.
+ *
+ * @param {Av1EncodeContext} ec with its source planes filled and its headers built
+ * @returns {{configuration_obus: Uint8Array, payload: Uint8Array}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function encode_av1_still(ec: Av1EncodeContext): {
+    configuration_obus: Uint8Array;
+    payload: Uint8Array;
+};
+//# sourceMappingURL=encode_av1_still.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encode_av1_still.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/encode_av1_still.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;GAWG;AACH;wBALkC,UAAU;aAAW,UAAU;EAwEhE"}

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

@@ -0,0 +1,194 @@
+import { BitWriter } from "../../bitstream/BitWriter.js";
+import { OBU_FRAME, OBU_SEQUENCE_HEADER } from "../tables/av1_symbols.js";
+import { COST_ONE_BIT } from "../entropy/symbol_cost.js";
+import { ac_quant } from "../decode/reconstruct.js";
+import { cdf_context_init } from "../entropy/CdfContext.js";
+import { choose_filters } from "./choose_filters.js";
+import { choose_restoration } from "./choose_restoration.js";
+import { encode_tile } from "./encode_tile.js";
+import { write_frame_header } from "../obu/write_frame_header.js";
+import { write_sequence_header } from "../obu/write_sequence_header.js";
+
+/**
+ * Encode the picture in an encode context as an AV1 still.
+ *
+ * Returns the sequence header on its own, for the container's `av1C` property, and the item payload
+ * — which carries a copy of that header followed by the coded frame.
+ *
+ * @param {Av1EncodeContext} ec with its source planes filled and its headers built
+ * @returns {{configuration_obus: Uint8Array, payload: Uint8Array}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function encode_av1_still(ec) {
+    const ctx = ec.frame_context;
+
+    const sequence = ec.sequence;
+    const frame = ec.frame;
+
+    ctx.resize(sequence, frame);
+
+    ec.resize_decisions(ctx.mi_stride * ctx.mi_rows);
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        ctx.planes[plane].fill(0);
+    }
+
+    ctx.lossless = frame.lossless_array[0];
+
+    ec.quantiser_step = quantiser_step(ctx, frame);
+
+    // the slope of the rate-distortion curve at this quantiser, in squared error per unit of the
+    // cost writer's rate, so that every decision downstream is one comparison rather than two
+    ec.lambda = (ec.lambda_scale * ec.quantiser_step * ec.quantiser_step) / COST_ONE_BIT;
+
+    const writer = new BitWriter();
+
+    const tiles = [];
+
+    code_tiles(ec, tiles, 0);
+
+    // after the tiles, because that is where the answer lives: the in-loop filters run over the
+    // whole frame once decoding is done, so nothing any block was coded against depends on them
+    choose_filters(ec);
+
+    choose_restoration(ec);
+
+    // and restoration, alone among them, is coded inside the tile — so a frame that keeps any of it
+    // writes the tile a second time, from the decisions the first pass recorded. The picture that
+    // comes out is the same one; what differs is the parameters carried alongside it
+    if (frame.uses_lr === 1) {
+        code_tiles(ec, tiles, 1);
+    }
+
+    // written here rather than before the tiles because `choose_filters` may yet decide the frame
+    // wants no directional filter, and that is a sequence header field
+    write_sequence_header(writer, sequence);
+    writer.trailing_bits();
+
+    const configuration_obus = emit_obu(OBU_SEQUENCE_HEADER, writer.to_bytes());
+
+    writer.reset();
+
+    write_frame_header(writer, sequence, frame);
+
+    writer.byte_alignment();
+
+    write_tile_group(writer, frame, tiles);
+
+    const frame_obu = emit_obu(OBU_FRAME, writer.to_bytes());
+
+    // the sequence header goes in both places. The container property is where the format says a
+    // decoder may look for it before it has any data; repeating it in the payload is what libavif
+    // does, and a decoder that only reads the payload — which is most of them — needs it there.
+    const payload = new Uint8Array(configuration_obus.length + frame_obu.length);
+
+    payload.set(configuration_obus, 0);
+    payload.set(frame_obu, configuration_obus.length);
+
+    return { configuration_obus, payload };
+}
+
+/**
+ * Code every tile of the frame, from an empty reconstruction.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {Uint8Array[]} tiles filled with the coded tiles, replacing whatever was there
+ * @param {number} replay `0` to search and write, `1` to write again from what the search recorded
+ */
+function code_tiles(ec, tiles, replay) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    tiles.length = 0;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        ctx.planes[plane].fill(0);
+    }
+
+    for (let tile_row = 0; tile_row < frame.tile_rows; tile_row++) {
+        for (let tile_col = 0; tile_col < frame.tile_cols; tile_col++) {
+            ctx.mi_row_start = frame.mi_row_starts[tile_row];
+            ctx.mi_row_end = frame.mi_row_starts[tile_row + 1];
+            ctx.mi_col_start = frame.mi_col_starts[tile_col];
+            ctx.mi_col_end = frame.mi_col_starts[tile_col + 1];
+
+            ctx.current_q_index = frame.base_q_idx;
+
+            cdf_context_init(ctx.cdf, frame.base_q_idx);
+
+            ctx.writer.reset(frame.disable_cdf_update);
+
+            encode_tile(ec, replay);
+
+            tiles.push(Uint8Array.from(ctx.writer.finish()));
+        }
+    }
+}
+
+/**
+ * The quantiser step the mode decisions measure detail against: the AC step at the frame's
+ * quantizer index, which is what every coefficient but one per block is divided by.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FrameHeader} frame
+ * @returns {number}
+ */
+function quantiser_step(ctx, frame) {
+    return ac_quant(ctx.bit_depth, frame.base_q_idx);
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {FrameHeader} frame
+ * @param {Uint8Array[]} tiles
+ * @see AV1 spec 5.11.1 "General tile group OBU syntax"
+ */
+function write_tile_group(writer, frame, tiles) {
+    if (tiles.length > 1) {
+        // the whole frame in one group, so the range is implied and no start or end is coded
+        writer.f(1, 0);
+    }
+
+    writer.byte_alignment();
+
+    for (let i = 0; i < tiles.length; i++) {
+        const tile = tiles[i];
+
+        if (i !== tiles.length - 1) {
+            writer.le(frame.tile_size_bytes, tile.length - 1);
+        }
+
+        writer.write_bytes(tile);
+    }
+}
+
+/**
+ * Wrap a payload in an OBU header with a size field.
+ *
+ * @param {number} type
+ * @param {Uint8Array} payload
+ * @returns {Uint8Array}
+ * @see AV1 spec 5.3.1 "OBU syntax"
+ */
+function emit_obu(type, payload) {
+    const writer = new BitWriter();
+
+    writer.f(1, 0);
+    writer.f(4, type);
+    writer.f(1, 0);
+    writer.f(1, 1);
+    writer.f(1, 0);
+
+    writer.leb128(payload.length);
+
+    const head = writer.to_bytes();
+
+    const out = new Uint8Array(head.length + payload.length);
+
+    out.set(head, 0);
+    out.set(payload, head.length);
+
+    return out;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} effort one of the `EFFORT_*` constants
+ */
+export function apply_effort(ec: Av1EncodeContext, effort: number): void;
+/**
+ * How hard the encoder looks before it decides.
+ *
+ * Every decision this encoder makes is a search, and every search is a trade: the same picture at
+ * the same quantiser comes out smaller the longer it is given. These are the three points on that
+ * curve worth naming, measured against libavif at speed 6 over eight pictures — five of them
+ * photographs — with `tools/measure_encoder.mjs`:
+ *
+ *     EFFORT_FAST         +21.6% rate for the same fidelity
+ *     EFFORT_BALANCED     +13.1%                              about two and a half times as long
+ *     EFFORT_THOROUGH      +7.5%                              about ten times as long
+ *
+ * Behind them are eight knobs: how many of the thirteen intra modes get priced properly rather than
+ * merely ranked, how many transform sizes and how many transform types the winner is tried against,
+ * how many in-loop filter strengths are measured and how many rounds a restoration filter is fitted
+ * for, how readily and in how many ways a block is cut unevenly as well as evenly, and how cheap a
+ * block has to be before it is left whole unasked.
+ * Anything finer is set on the context directly; this is what a caller who does not want to know
+ * about mode trials asks for.
+ *
+ * The cheapest of the three is not the one that does the least of everything. Pricing only the mode
+ * that predicted closest saves a sixth of the time and costs seventeen points of rate — a trade
+ * nothing else on this ladder comes near — so the fast setting prices three modes like the others
+ * and buys its speed by not cutting blocks unevenly and by giving up on them sooner.
+ *
+ * What none of these decide is which in-loop filters the file makes the *reader* run. That is the
+ * other axis, and an unrelated one: see `decode_effort.js`. The rates above are at the default
+ * {@link DECODE_FAST}; the balanced setting measures +8.6% at {@link DECODE_BALANCED} and +7.9% at
+ * {@link DECODE_THOROUGH}, for a file three times slower to read.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Price three modes, code the winner with a plain DCT, cut blocks only in four, and give up on a
+ * block sooner.
+ * @type {number}
+ */
+export const EFFORT_FAST: number;
+/**
+ * Price three modes, try every transform type and size against the winner, and cut a block in half
+ * as well as in four when the two are close.
+ * @type {number}
+ */
+export const EFFORT_BALANCED: number;
+/**
+ * Price all thirteen, and rank nothing.
+ * @type {number}
+ */
+export const EFFORT_THOROUGH: number;
+//# sourceMappingURL=encode_effort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encode_effort.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/encode_effort.js"],"names":[],"mappings":"AAsDA;;;GAGG;AACH,2DAFW,MAAM,QAwChB;AAhGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;GAIG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;;GAIG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,8BAFU,MAAM,CAEiB"}

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

@@ -0,0 +1,97 @@
+/**
+ * How hard the encoder looks before it decides.
+ *
+ * Every decision this encoder makes is a search, and every search is a trade: the same picture at
+ * the same quantiser comes out smaller the longer it is given. These are the three points on that
+ * curve worth naming, measured against libavif at speed 6 over eight pictures — five of them
+ * photographs — with `tools/measure_encoder.mjs`:
+ *
+ *     EFFORT_FAST         +21.6% rate for the same fidelity
+ *     EFFORT_BALANCED     +13.1%                              about two and a half times as long
+ *     EFFORT_THOROUGH      +7.5%                              about ten times as long
+ *
+ * Behind them are eight knobs: how many of the thirteen intra modes get priced properly rather than
+ * merely ranked, how many transform sizes and how many transform types the winner is tried against,
+ * how many in-loop filter strengths are measured and how many rounds a restoration filter is fitted
+ * for, how readily and in how many ways a block is cut unevenly as well as evenly, and how cheap a
+ * block has to be before it is left whole unasked.
+ * Anything finer is set on the context directly; this is what a caller who does not want to know
+ * about mode trials asks for.
+ *
+ * The cheapest of the three is not the one that does the least of everything. Pricing only the mode
+ * that predicted closest saves a sixth of the time and costs seventeen points of rate — a trade
+ * nothing else on this ladder comes near — so the fast setting prices three modes like the others
+ * and buys its speed by not cutting blocks unevenly and by giving up on them sooner.
+ *
+ * What none of these decide is which in-loop filters the file makes the *reader* run. That is the
+ * other axis, and an unrelated one: see `decode_effort.js`. The rates above are at the default
+ * {@link DECODE_FAST}; the balanced setting measures +8.6% at {@link DECODE_BALANCED} and +7.9% at
+ * {@link DECODE_THOROUGH}, for a file three times slower to read.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Price three modes, code the winner with a plain DCT, cut blocks only in four, and give up on a
+ * block sooner.
+ * @type {number}
+ */
+export const EFFORT_FAST = 0;
+
+/**
+ * Price three modes, try every transform type and size against the winner, and cut a block in half
+ * as well as in four when the two are close.
+ * @type {number}
+ */
+export const EFFORT_BALANCED = 1;
+
+/**
+ * Price all thirteen, and rank nothing.
+ * @type {number}
+ */
+export const EFFORT_THOROUGH = 2;
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} effort one of the `EFFORT_*` constants
+ */
+export function apply_effort(ec, effort) {
+    if (effort === EFFORT_FAST) {
+        ec.mode_trials = 3;
+        ec.transform_trials = 0;
+        ec.transform_depths = 2;
+        ec.filter_trials = 4;
+        ec.cdef_trials = 3;
+        ec.rectangle_margin = 1;
+        ec.uneven_partitions = 0;
+        ec.split_floor = 90;
+        ec.restoration_trials = 1;
+
+        return;
+    }
+
+    if (effort === EFFORT_THOROUGH) {
+        ec.mode_trials = 13;
+        ec.transform_trials = 3;
+        ec.transform_depths = 4;
+        ec.filter_trials = 7;
+        ec.cdef_trials = 12;
+        ec.rectangle_margin = 4;
+        ec.uneven_partitions = 8;
+        ec.split_floor = 12;
+        ec.restoration_trials = 2;
+
+        return;
+    }
+
+    ec.mode_trials = 3;
+    ec.transform_trials = 3;
+    ec.transform_depths = 3;
+    ec.filter_trials = 7;
+    ec.cdef_trials = 3;
+    ec.rectangle_margin = 1.2;
+    ec.uneven_partitions = 2;
+    ec.split_floor = 12;
+    ec.restoration_trials = 2;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Encode one tile — which, for a still image, is the whole picture.
+ *
+ * Each superblock is coded twice. The first pass searches: it prices both answers to every
+ * partition decision by *making* each of them — predicting, quantising, reconstructing, advancing
+ * the contexts — against a writer that emits nothing, and puts the state back between them. The
+ * second pass writes the tree the first settled on.
+ *
+ * It has to be that way round. A partition symbol comes before everything under it in the stream,
+ * and choosing which one to write means knowing what the whole subtree would cost. What makes the
+ * two passes agree is that the second starts from exactly the state the first did, and replays the
+ * decisions the first recorded, so it reproduces the winning path sample for sample.
+ *
+ * Searching a superblock at a time rather than the whole tile keeps the probabilities honest: the
+ * CDFs a search prices against are the ones the previous superblock left behind, which is within a
+ * superblock of the ones its own symbols will meet.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} replay `0` to search and write, `1` to write again from what the search recorded
+ * @see AV1 spec 5.11.2 "Decode tile syntax", of which this is the mirror
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function encode_tile(ec: Av1EncodeContext, replay: number): void;
+//# sourceMappingURL=encode_tile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encode_tile.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/encode_tile.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,0DANW,MAAM,QA2ChB"}