@woosh/meep-engine 3.9.0 → 3.10.0

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

@@ -0,0 +1,359 @@
+import {
+    CP_BT_709,
+    MAX_TILE_AREA,
+    MAX_TILE_WIDTH,
+    SELECT_INTEGER_MV,
+    SELECT_SCREEN_CONTENT_TOOLS,
+    CSP_UNKNOWN,
+    KEY_FRAME,
+    MC_IDENTITY,
+    ONLY_4X4,
+    PRIMARY_REF_NONE,
+    RESTORATION_TILESIZE_MAX,
+    RESTORE_NONE,
+    RESTORE_WIENER,
+    SUPERRES_NUM,
+    TC_SRGB,
+    TX_MODE_SELECT
+} from "../tables/av1_symbols.js";
+import { tile_log2 } from "../util/tile_log2.js";
+
+/**
+ * Number of bits needed to hold a value.
+ *
+ * @param {number} value
+ * @returns {number}
+ */
+function bit_length(value) {
+    let bits = 1;
+
+    while ((1 << bits) <= value) {
+        bits++;
+    }
+
+    return bits;
+}
+
+/**
+ * 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, options) {
+    const monochrome = options.monochrome;
+
+    const sub_x = monochrome === 1 ? 1 : options.subsampling_x;
+    const sub_y = monochrome === 1 ? 1 : options.subsampling_y;
+
+    sequence.seq_profile = choose_profile(options.bit_depth, monochrome, sub_x, sub_y);
+    sequence.still_picture = 1;
+    sequence.reduced_still_picture_header = 1;
+
+    sequence.timing_info_present_flag = 0;
+    sequence.decoder_model_info_present_flag = 0;
+    sequence.initial_display_delay_present_flag = 0;
+    sequence.operating_points_cnt_minus_1 = 0;
+    sequence.operating_point_idc[0] = 0;
+    sequence.seq_tier[0] = 0;
+
+    // level 6.3 imposes no constraint this encoder could violate; a decoder is required to accept a
+    // still picture at any level it supports, and nothing here reads it back
+    sequence.seq_level_idx[0] = 19;
+
+    sequence.frame_width_bits_minus_1 = bit_length(options.width - 1) - 1;
+    sequence.frame_height_bits_minus_1 = bit_length(options.height - 1) - 1;
+
+    sequence.max_frame_width_minus_1 = options.width - 1;
+    sequence.max_frame_height_minus_1 = options.height - 1;
+
+    sequence.frame_id_numbers_present_flag = 0;
+
+    sequence.use_128x128_superblock = 0;
+    sequence.enable_filter_intra = 0;
+    sequence.enable_intra_edge_filter = 1;
+
+    sequence.enable_interintra_compound = 0;
+    sequence.enable_masked_compound = 0;
+    sequence.enable_warped_motion = 0;
+    sequence.enable_dual_filter = 0;
+    sequence.enable_order_hint = 0;
+    sequence.enable_jnt_comp = 0;
+    sequence.enable_ref_frame_mvs = 0;
+    sequence.order_hint_bits = 0;
+
+    // the reduced header codes neither of these, and a decoder derives them as "choose per frame";
+    // the frame header's syntax depends on that, so the struct has to say the same
+    sequence.seq_choose_screen_content_tools = 0;
+    sequence.seq_force_screen_content_tools = SELECT_SCREEN_CONTENT_TOOLS;
+    sequence.seq_choose_integer_mv = 0;
+    sequence.seq_force_integer_mv = SELECT_INTEGER_MV;
+
+    sequence.enable_superres = 0;
+
+    // the directional filter is worth having and costs nothing in the tile: with one strength for
+    // the whole frame the per-superblock index is zero bits wide. `choose_filters` turns this back
+    // off if the strength it settles on is no strength at all
+    sequence.enable_cdef = 1;
+    sequence.enable_restoration = 1;
+
+    sequence.high_bitdepth = options.bit_depth > 8 ? 1 : 0;
+    sequence.twelve_bit = options.bit_depth === 12 ? 1 : 0;
+    sequence.bit_depth = options.bit_depth;
+    sequence.mono_chrome = monochrome;
+    sequence.num_planes = monochrome === 1 ? 1 : 3;
+
+    sequence.color_description_present_flag = 1;
+    sequence.color_primaries = options.color_primaries ?? CP_BT_709;
+    sequence.transfer_characteristics = options.transfer_characteristics ?? TC_SRGB;
+    sequence.matrix_coefficients = options.matrix_coefficients ?? MC_IDENTITY;
+    sequence.color_range = options.color_range ?? 1;
+
+    if (sequence.matrix_coefficients === MC_IDENTITY && (sub_x !== 0 || sub_y !== 0 || monochrome === 1)) {
+        throw new Error("the identity matrix means the planes are G, B and R, which cannot be subsampled");
+    }
+
+    sequence.subsampling_x = sub_x;
+    sequence.subsampling_y = sub_y;
+    sequence.chroma_sample_position = CSP_UNKNOWN;
+    sequence.separate_uv_delta_q = 0;
+
+    sequence.film_grain_params_present = 0;
+}
+
+/**
+ * The profile a colour configuration needs.
+ *
+ * @param {number} bit_depth
+ * @param {number} monochrome
+ * @param {number} subsampling_x
+ * @param {number} subsampling_y
+ * @returns {number}
+ * @see AV1 spec 6.4.1, table "Seq_Profile"
+ */
+function choose_profile(bit_depth, monochrome, subsampling_x, subsampling_y) {
+    if (bit_depth === 12) {
+        return 2;
+    }
+
+    if (monochrome === 0 && subsampling_x === 0 && subsampling_y === 0) {
+        return 1;
+    }
+
+    // 4:2:2 is the one subsampling profile 0 does not cover
+    if (monochrome === 0 && subsampling_x === 1 && subsampling_y === 0) {
+        return 2;
+    }
+
+    return 0;
+}
+
+/**
+ * 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, sequence, options) {
+    frame.show_existing_frame = 0;
+    frame.frame_type = KEY_FRAME;
+    frame.frame_is_intra = 1;
+    frame.show_frame = 1;
+    frame.showable_frame = 0;
+    frame.error_resilient_mode = 1;
+
+    frame.disable_cdf_update = 0;
+    frame.allow_screen_content_tools = 0;
+    frame.force_integer_mv = 1;
+    frame.current_frame_id = 0;
+    frame.frame_size_override_flag = 0;
+    frame.order_hint = 0;
+    frame.primary_ref_frame = PRIMARY_REF_NONE;
+    frame.refresh_frame_flags = 255;
+
+    frame.frame_width = sequence.max_frame_width_minus_1 + 1;
+    frame.frame_height = sequence.max_frame_height_minus_1 + 1;
+    frame.upscaled_width = frame.frame_width;
+    frame.use_superres = 0;
+    frame.superres_denom = SUPERRES_NUM;
+
+    frame.mi_cols = 2 * ((frame.frame_width + 7) >> 3);
+    frame.mi_rows = 2 * ((frame.frame_height + 7) >> 3);
+
+    frame.render_and_frame_size_different = 0;
+    frame.render_width = frame.upscaled_width;
+    frame.render_height = frame.frame_height;
+
+    frame.allow_intrabc = 0;
+    frame.disable_frame_end_update_cdf = 1;
+
+    build_tile_info(sequence, frame);
+
+    frame.base_q_idx = options.base_q_idx;
+    frame.delta_q_y_dc = 0;
+    frame.delta_q_u_dc = 0;
+    frame.delta_q_u_ac = 0;
+    frame.delta_q_v_dc = 0;
+    frame.delta_q_v_ac = 0;
+    frame.diff_uv_delta = 0;
+    frame.using_qmatrix = 0;
+
+    frame.segmentation_enabled = 0;
+    frame.segmentation_update_map = 0;
+    frame.segmentation_update_data = 0;
+    frame.seg_id_pre_skip = 0;
+    frame.last_active_seg_id = 0;
+    frame.feature_enabled.fill(0);
+    frame.feature_data.fill(0);
+
+    frame.delta_q_present = 0;
+    frame.delta_q_res = 0;
+    frame.delta_lf_present = 0;
+    frame.delta_lf_res = 0;
+    frame.delta_lf_multi = 0;
+
+    const lossless = frame.base_q_idx === 0;
+
+    frame.coded_lossless = lossless ? 1 : 0;
+    frame.all_lossless = frame.coded_lossless;
+    frame.lossless_array.fill(lossless ? 1 : 0);
+
+    // no deblocking: with a single quantiser over the whole picture and no inter prediction to
+    // propagate an edge, what it buys is small, and an encoder that signalled a level would have to
+    // reproduce the filter to keep its reconstruction honest
+    frame.loop_filter_level[0] = 0;
+    frame.loop_filter_level[1] = 0;
+    frame.loop_filter_level[2] = 0;
+    frame.loop_filter_level[3] = 0;
+    frame.loop_filter_sharpness = 0;
+    frame.loop_filter_delta_enabled = 0;
+
+    // the deltas a decoder starts a key frame from, which nothing here changes
+    frame.loop_filter_ref_deltas[0] = 1;
+    frame.loop_filter_ref_deltas[1] = 0;
+    frame.loop_filter_ref_deltas[2] = 0;
+    frame.loop_filter_ref_deltas[3] = 0;
+    frame.loop_filter_ref_deltas[4] = -1;
+    frame.loop_filter_ref_deltas[5] = 0;
+    frame.loop_filter_ref_deltas[6] = -1;
+    frame.loop_filter_ref_deltas[7] = -1;
+    frame.loop_filter_mode_deltas.fill(0);
+
+    // one strength for the whole frame, so the index the decoder reads per superblock is zero bits
+    // wide and the tool is free of the tile entirely. The strengths themselves are chosen by
+    // `choose_filters` once there is a reconstruction to measure
+    frame.cdef_bits = 0;
+
+    // the damping the reference encoder derives from the quantiser rather than searching: a coarse
+    // quantiser leaves larger differences across an edge, and the filter has to tolerate them
+    frame.cdef_damping = 3 + (frame.base_q_idx >> 6);
+
+    frame.cdef_y_pri_strength.fill(0);
+    frame.cdef_y_sec_strength.fill(0);
+    frame.cdef_uv_pri_strength.fill(0);
+    frame.cdef_uv_sec_strength.fill(0);
+
+    // offered up front, and withdrawn by `choose_restoration` if nothing wants it: the frame
+    // context sizes its restoration buffers from these, and they are sized before the picture is
+    // coded while the filter can only be fitted after
+    frame.uses_lr = frame.all_lossless === 1 ? 0 : 1;
+
+    frame.frame_restoration_type[0] = frame.uses_lr === 1 ? RESTORE_WIENER : RESTORE_NONE;
+    frame.frame_restoration_type[1] = frame.frame_restoration_type[0];
+    frame.frame_restoration_type[2] = frame.frame_restoration_type[0];
+
+    frame.lr_unit_shift = options.restoration_unit_shift;
+    frame.lr_uv_shift = sequence.subsampling_x === 1 && sequence.subsampling_y === 1 ? 1 : 0;
+    frame.loop_restoration_size[0] = RESTORATION_TILESIZE_MAX >> (2 - frame.lr_unit_shift);
+    frame.loop_restoration_size[1] = frame.loop_restoration_size[0] >> frame.lr_uv_shift;
+    frame.loop_restoration_size[2] = frame.loop_restoration_size[1];
+
+    // per block rather than always the largest: a transform that spans detail it cannot fit spends
+    // coefficients describing the mismatch, and the block is better off cut into four transforms
+    // that each fit. `choose_transform_depth` decides, and the depth costs one symbol
+    frame.tx_mode = lossless ? ONLY_4X4 : TX_MODE_SELECT;
+
+    frame.reduced_tx_set = 0;
+
+    frame.apply_grain = 0;
+}
+
+/**
+ * The coarsest legal tiling: one tile, unless the picture is too large for one to be legal.
+ *
+ * A tile may be at most 4096 samples wide and about nine megapixels in area, so a large enough
+ * picture *has* to be split whether the encoder wants to or not. Taking the minimum the format
+ * allows keeps the coding efficiency a tile boundary costs to what the format forces.
+ *
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} frame
+ * @see AV1 spec 5.9.15 "Tile info syntax"
+ */
+function build_tile_info(sequence, frame) {
+    const sb_shift = 4;
+    const sb_size = sb_shift + 2;
+
+    const sb_cols = (frame.mi_cols + 15) >> 4;
+    const sb_rows = (frame.mi_rows + 15) >> 4;
+
+    const max_tile_width_sb = MAX_TILE_WIDTH >> sb_size;
+    const max_tile_area_sb = MAX_TILE_AREA >> (2 * sb_size);
+
+    const min_log2_tile_cols = tile_log2(max_tile_width_sb, sb_cols);
+    const min_log2_tiles = Math.max(min_log2_tile_cols, tile_log2(max_tile_area_sb, sb_rows * sb_cols));
+
+    frame.uniform_tile_spacing_flag = 1;
+    frame.tile_cols_log2 = min_log2_tile_cols;
+
+    const tile_width_sb = (sb_cols + (1 << frame.tile_cols_log2) - 1) >> frame.tile_cols_log2;
+
+    let columns = 0;
+
+    for (let start_sb = 0; start_sb < sb_cols; start_sb += tile_width_sb) {
+        frame.mi_col_starts[columns] = start_sb << sb_shift;
+        columns++;
+    }
+
+    frame.mi_col_starts[columns] = frame.mi_cols;
+    frame.tile_cols = columns;
+
+    frame.tile_rows_log2 = Math.max(min_log2_tiles - frame.tile_cols_log2, 0);
+
+    const tile_height_sb = (sb_rows + (1 << frame.tile_rows_log2) - 1) >> frame.tile_rows_log2;
+
+    let rows = 0;
+
+    for (let start_sb = 0; start_sb < sb_rows; start_sb += tile_height_sb) {
+        frame.mi_row_starts[rows] = start_sb << sb_shift;
+        rows++;
+    }
+
+    frame.mi_row_starts[rows] = frame.mi_rows;
+    frame.tile_rows = rows;
+
+    frame.context_update_tile_id = 0;
+
+    // only coded, and only used, when there is more than one tile
+    frame.tile_size_bytes = frame.tile_cols * frame.tile_rows > 1 ? 4 : 1;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Fit the scaling that carries the reconstructed luma's shape into a chroma block.
+ *
+ * Chroma-from-luma predicts a chroma block as its own flat average plus a multiple of the luma's
+ * deviation from *its* average — which is worth having because in a photograph the two planes have
+ * their edges in the same places, and the luma's edges have already been coded.
+ *
+ * The multiple is a straight least squares fit: the chroma block already holds its flat prediction,
+ * so what is left to explain is the difference between that and the source, and the best multiple of
+ * the luma shape to explain it with is their correlation over its energy. The format carries the
+ * multiple as a sixth-of-a-bit fixed point integer between minus sixteen and sixteen, so the fit is
+ * rounded and clamped to that — and where the clamp bites, the clamped value is still the best one
+ * available, because the error is a parabola in the multiple and the format's range is an interval.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @param {number} start_x left edge of the chroma transform block
+ * @param {number} start_y
+ * @param {number} tx_size
+ * @returns {number} the scaling, zero when the luma has no shape to borrow
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function choose_chroma_alpha(ec: Av1EncodeContext, plane: number, start_x: number, start_y: number, tx_size: number): number;
+//# sourceMappingURL=choose_chroma_alpha.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"choose_chroma_alpha.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/choose_chroma_alpha.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,iEATW,MAAM,WACN,MAAM,WACN,MAAM,WACN,MAAM,GACJ,MAAM,CAuDlB"}

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

@@ -0,0 +1,90 @@
+import { TX_HEIGHT, TX_WIDTH } from "../tables/block_tables.js";
+import { chroma_from_luma_ac } from "../predict/predict_chroma_from_luma.js";
+
+/**
+ * Largest scaling the format can carry, either way.
+ * @type {number}
+ */
+const MAX_ALPHA = 16;
+
+/**
+ * What the decoder divides the scaled luma by, as a shift.
+ * @type {number}
+ */
+const ALPHA_SHIFT = 6;
+
+/**
+ * Fit the scaling that carries the reconstructed luma's shape into a chroma block.
+ *
+ * Chroma-from-luma predicts a chroma block as its own flat average plus a multiple of the luma's
+ * deviation from *its* average — which is worth having because in a photograph the two planes have
+ * their edges in the same places, and the luma's edges have already been coded.
+ *
+ * The multiple is a straight least squares fit: the chroma block already holds its flat prediction,
+ * so what is left to explain is the difference between that and the source, and the best multiple of
+ * the luma shape to explain it with is their correlation over its energy. The format carries the
+ * multiple as a sixth-of-a-bit fixed point integer between minus sixteen and sixteen, so the fit is
+ * rounded and clamped to that — and where the clamp bites, the clamped value is still the best one
+ * available, because the error is a parabola in the multiple and the format's range is an interval.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @param {number} start_x left edge of the chroma transform block
+ * @param {number} start_y
+ * @param {number} tx_size
+ * @returns {number} the scaling, zero when the luma has no shape to borrow
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function choose_chroma_alpha(ec, plane, start_x, start_y, tx_size) {
+    const ctx = ec.frame_context;
+
+    const ac = chroma_from_luma_ac(
+        ctx.planes[0],
+        ctx.plane_stride[0],
+        start_x,
+        start_y,
+        tx_size,
+        ctx.subsampling_x,
+        ctx.subsampling_y,
+        ctx.max_luma_w,
+        ctx.max_luma_h
+    );
+
+    const w = TX_WIDTH[tx_size];
+    const h = TX_HEIGHT[tx_size];
+
+    const prediction = ctx.planes[plane];
+    const prediction_stride = ctx.plane_stride[plane];
+
+    const source = ec.source[plane];
+    const source_stride = ec.source_stride[plane];
+
+    let correlation = 0;
+    let energy = 0;
+
+    for (let i = 0; i < h; i++) {
+        const a = (start_y + i) * prediction_stride + start_x;
+        const b = (start_y + i) * source_stride + start_x;
+
+        for (let j = 0; j < w; j++) {
+            const shape = ac[i * w + j];
+
+            correlation += shape * (source[b + j] - prediction[a + j]);
+            energy += shape * shape;
+        }
+    }
+
+    if (energy === 0) {
+        return 0;
+    }
+
+    const fitted = Math.round(((1 << ALPHA_SHIFT) * correlation) / energy);
+
+    if (fitted > MAX_ALPHA) {
+        return MAX_ALPHA;
+    }
+
+    return fitted < -MAX_ALPHA ? -MAX_ALPHA : fitted;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Choose the frame's in-loop filter strengths, after everything has been coded.
+ *
+ * The in-loop filters are the coding tools an AV1 encoder decides *after* it has finished coding,
+ * and that is not a shortcut — it is where they live. They run over the whole frame once decoding
+ * is done; intra prediction reads the reconstruction from before them, so nothing a block was coded
+ * against changes, and with one strength for the frame they cost a few bits in the frame header and
+ * not one symbol in the tile. So the encoder codes the picture, then asks which strengths bring the
+ * result closest to the source, and writes those.
+ *
+ * Deblocking comes first and directional enhancement second, in that order, because that is the
+ * order the decoder applies them and the second is choosing what to do about what the first left.
+ *
+ * @param {Av1EncodeContext} ec
+ * @see AV1 spec 7.14 "Loop filter process" and 7.15 "CDEF process", of which this picks the strengths
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function choose_filters(ec: Av1EncodeContext): void;
+//# sourceMappingURL=choose_filters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"choose_filters.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/choose_filters.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;;;;;;;GAkBG;AACH,2DA6CC"}