@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/obu/write_frame_header.js

@@ -0,0 +1,579 @@
+import {
+    KEY_FRAME,
+    MAX_SEGMENTS,
+    MAX_TILE_AREA,
+    MAX_TILE_COLS,
+    MAX_TILE_ROWS,
+    MAX_TILE_WIDTH,
+    RESTORE_NONE,
+    SEG_LVL_MAX,
+    SELECT_INTEGER_MV,
+    SELECT_SCREEN_CONTENT_TOOLS,
+    SUPERRES_DENOM_BITS,
+    SUPERRES_DENOM_MIN,
+    TOTAL_REFS_PER_FRAME,
+    TX_MODE_SELECT
+} from "../tables/av1_symbols.js";
+import {
+    SEGMENTATION_FEATURE_BITS,
+    SEGMENTATION_FEATURE_SIGNED
+} from "../tables/segmentation_tables.js";
+import { REMAP_LR_TYPE } from "../tables/filter_tables.js";
+import { tile_log2 } from "../util/tile_log2.js";
+
+/**
+ * Emit an uncompressed frame header for a key frame.
+ *
+ * The mirror of {@link parse_frame_header}, restricted to what that accepts. Header fields the
+ * syntax derives are recomputed by the reader and are not written.
+ *
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ * @see AV1 spec 5.9.2 "Uncompressed header syntax"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_frame_header(writer, sequence, header) {
+    if (header.frame_type !== KEY_FRAME) {
+        throw new Error("only key frames can be written");
+    }
+
+    if (sequence.reduced_still_picture_header === 0) {
+        writer.f(1, 0);
+        writer.f(2, KEY_FRAME);
+        writer.f(1, header.show_frame);
+
+        if (header.show_frame === 1 && sequence.decoder_model_info_present_flag === 1 && sequence.equal_picture_interval === 0) {
+            writer.f(sequence.frame_presentation_time_length_minus_1 + 1, 0);
+        }
+
+        if (header.show_frame === 0) {
+            writer.f(1, header.showable_frame);
+            writer.f(1, header.error_resilient_mode);
+        }
+    }
+
+    writer.f(1, header.disable_cdf_update);
+
+    if (sequence.seq_force_screen_content_tools === SELECT_SCREEN_CONTENT_TOOLS) {
+        writer.f(1, header.allow_screen_content_tools);
+    }
+
+    if (header.allow_screen_content_tools !== 0 && sequence.seq_force_integer_mv === SELECT_INTEGER_MV) {
+        // force_integer_mv: the bit is present but its value is ignored for an intra frame
+        writer.f(1, 1);
+    }
+
+    if (sequence.frame_id_numbers_present_flag === 1) {
+        const id_length = sequence.additional_frame_id_length_minus_1 + sequence.delta_frame_id_length_minus_2 + 3;
+
+        writer.f(id_length, header.current_frame_id);
+    }
+
+    if (sequence.reduced_still_picture_header === 0) {
+        writer.f(1, header.frame_size_override_flag);
+    }
+
+    writer.f(sequence.order_hint_bits, header.order_hint);
+
+    if (sequence.decoder_model_info_present_flag === 1) {
+        writer.f(1, 0);
+    }
+
+    if (header.show_frame === 0) {
+        writer.f(8, header.refresh_frame_flags);
+
+        if (header.refresh_frame_flags !== 255 && header.error_resilient_mode === 1 && sequence.enable_order_hint === 1) {
+            for (let i = 0; i < 8; i++) {
+                writer.f(sequence.order_hint_bits, 0);
+            }
+        }
+    }
+
+    write_frame_size(writer, sequence, header);
+    write_render_size(writer, header);
+
+    if (header.allow_screen_content_tools !== 0 && header.upscaled_width === header.frame_width) {
+        writer.f(1, header.allow_intrabc);
+    }
+
+    if (sequence.reduced_still_picture_header === 0 && header.disable_cdf_update === 0) {
+        writer.f(1, header.disable_frame_end_update_cdf);
+    }
+
+    write_tile_info(writer, sequence, header);
+    write_quantization_params(writer, sequence, header);
+    write_segmentation_params(writer, header);
+    write_delta_q_params(writer, header);
+    write_delta_lf_params(writer, header);
+    write_loop_filter_params(writer, sequence, header);
+    write_cdef_params(writer, sequence, header);
+    write_lr_params(writer, sequence, header);
+
+    if (header.coded_lossless === 0) {
+        writer.f(1, header.tx_mode === TX_MODE_SELECT ? 1 : 0);
+    }
+
+    writer.f(1, header.reduced_tx_set);
+
+    write_film_grain_params(writer, sequence, header);
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_frame_size(writer, sequence, header) {
+    if (header.frame_size_override_flag === 1) {
+        writer.f(sequence.frame_width_bits_minus_1 + 1, header.upscaled_width - 1);
+        writer.f(sequence.frame_height_bits_minus_1 + 1, header.frame_height - 1);
+    }
+
+    if (sequence.enable_superres === 1) {
+        writer.f(1, header.use_superres);
+    }
+
+    if (header.use_superres === 1) {
+        writer.f(SUPERRES_DENOM_BITS, header.superres_denom - SUPERRES_DENOM_MIN);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {FrameHeader} header
+ */
+function write_render_size(writer, header) {
+    writer.f(1, header.render_and_frame_size_different);
+
+    if (header.render_and_frame_size_different === 1) {
+        writer.f(16, header.render_width - 1);
+        writer.f(16, header.render_height - 1);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_tile_info(writer, sequence, header) {
+    const sb_shift = sequence.use_128x128_superblock === 1 ? 5 : 4;
+    const sb_size = sb_shift + 2;
+
+    const sb_cols = sequence.use_128x128_superblock === 1
+        ? (header.mi_cols + 31) >> 5
+        : (header.mi_cols + 15) >> 4;
+    const sb_rows = sequence.use_128x128_superblock === 1
+        ? (header.mi_rows + 31) >> 5
+        : (header.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 max_log2_tile_cols = tile_log2(1, Math.min(sb_cols, MAX_TILE_COLS));
+    const max_log2_tile_rows = tile_log2(1, Math.min(sb_rows, MAX_TILE_ROWS));
+    const min_log2_tiles = Math.max(min_log2_tile_cols, tile_log2(max_tile_area_sb, sb_rows * sb_cols));
+
+    writer.f(1, header.uniform_tile_spacing_flag);
+
+    if (header.uniform_tile_spacing_flag === 1) {
+        for (let k = min_log2_tile_cols; k < max_log2_tile_cols; k++) {
+            const increment = k < header.tile_cols_log2 ? 1 : 0;
+
+            writer.f(1, increment);
+
+            if (increment === 0) {
+                break;
+            }
+        }
+
+        const min_log2_tile_rows = Math.max(min_log2_tiles - header.tile_cols_log2, 0);
+
+        for (let k = min_log2_tile_rows; k < max_log2_tile_rows; k++) {
+            const increment = k < header.tile_rows_log2 ? 1 : 0;
+
+            writer.f(1, increment);
+
+            if (increment === 0) {
+                break;
+            }
+        }
+    } else {
+        let start_sb = 0;
+
+        for (let i = 0; i < header.tile_cols; i++) {
+            const size_sb = (header.mi_col_starts[i + 1] - header.mi_col_starts[i] + (1 << sb_shift) - 1) >> sb_shift;
+            const max_width = Math.min(sb_cols - start_sb, max_tile_width_sb);
+
+            writer.ns(max_width, size_sb - 1);
+
+            start_sb += size_sb;
+        }
+
+        let widest_tile_sb = 0;
+
+        for (let i = 0; i < header.tile_cols; i++) {
+            const size_sb = (header.mi_col_starts[i + 1] - header.mi_col_starts[i] + (1 << sb_shift) - 1) >> sb_shift;
+
+            widest_tile_sb = Math.max(widest_tile_sb, size_sb);
+        }
+
+        const area_sb = min_log2_tiles > 0
+            ? (sb_rows * sb_cols) >> (min_log2_tiles + 1)
+            : sb_rows * sb_cols;
+
+        const max_tile_height_sb = Math.max(Math.floor(area_sb / widest_tile_sb), 1);
+
+        start_sb = 0;
+
+        for (let i = 0; i < header.tile_rows; i++) {
+            const size_sb = (header.mi_row_starts[i + 1] - header.mi_row_starts[i] + (1 << sb_shift) - 1) >> sb_shift;
+            const max_height = Math.min(sb_rows - start_sb, max_tile_height_sb);
+
+            writer.ns(max_height, size_sb - 1);
+
+            start_sb += size_sb;
+        }
+    }
+
+    if (header.tile_cols_log2 > 0 || header.tile_rows_log2 > 0) {
+        writer.f(header.tile_rows_log2 + header.tile_cols_log2, header.context_update_tile_id);
+        writer.f(2, header.tile_size_bytes - 1);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {number} value
+ */
+function write_delta_q(writer, value) {
+    if (value === 0) {
+        writer.f(1, 0);
+    } else {
+        writer.f(1, 1);
+        writer.su(7, value);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_quantization_params(writer, sequence, header) {
+    writer.f(8, header.base_q_idx);
+    write_delta_q(writer, header.delta_q_y_dc);
+
+    if (sequence.num_planes > 1) {
+        if (sequence.separate_uv_delta_q === 1) {
+            writer.f(1, header.diff_uv_delta);
+        }
+
+        write_delta_q(writer, header.delta_q_u_dc);
+        write_delta_q(writer, header.delta_q_u_ac);
+
+        if (header.diff_uv_delta === 1) {
+            write_delta_q(writer, header.delta_q_v_dc);
+            write_delta_q(writer, header.delta_q_v_ac);
+        }
+    }
+
+    writer.f(1, header.using_qmatrix);
+
+    if (header.using_qmatrix === 1) {
+        writer.f(4, header.qm_y);
+        writer.f(4, header.qm_u);
+
+        if (sequence.separate_uv_delta_q === 1) {
+            writer.f(4, header.qm_v);
+        }
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {FrameHeader} header
+ */
+function write_segmentation_params(writer, header) {
+    writer.f(1, header.segmentation_enabled);
+
+    if (header.segmentation_enabled === 0) {
+        return;
+    }
+
+    for (let i = 0; i < MAX_SEGMENTS; i++) {
+        for (let j = 0; j < SEG_LVL_MAX; j++) {
+            const enabled = header.feature_enabled[i * SEG_LVL_MAX + j];
+
+            writer.f(1, enabled);
+
+            if (enabled === 0) {
+                continue;
+            }
+
+            const bits = SEGMENTATION_FEATURE_BITS[j];
+
+            if (SEGMENTATION_FEATURE_SIGNED[j] === 1) {
+                writer.su(1 + bits, header.feature_data[i * SEG_LVL_MAX + j]);
+            } else {
+                writer.f(bits, header.feature_data[i * SEG_LVL_MAX + j]);
+            }
+        }
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {FrameHeader} header
+ */
+function write_delta_q_params(writer, header) {
+    if (header.base_q_idx > 0) {
+        writer.f(1, header.delta_q_present);
+    }
+
+    if (header.delta_q_present === 1) {
+        writer.f(2, header.delta_q_res);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {FrameHeader} header
+ */
+function write_delta_lf_params(writer, header) {
+    if (header.delta_q_present !== 1) {
+        return;
+    }
+
+    if (header.allow_intrabc === 0) {
+        writer.f(1, header.delta_lf_present);
+    }
+
+    if (header.delta_lf_present === 1) {
+        writer.f(2, header.delta_lf_res);
+        writer.f(1, header.delta_lf_multi);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_loop_filter_params(writer, sequence, header) {
+    if (header.coded_lossless === 1 || header.allow_intrabc === 1) {
+        return;
+    }
+
+    writer.f(6, header.loop_filter_level[0]);
+    writer.f(6, header.loop_filter_level[1]);
+
+    if (sequence.num_planes > 1 && (header.loop_filter_level[0] !== 0 || header.loop_filter_level[1] !== 0)) {
+        writer.f(6, header.loop_filter_level[2]);
+        writer.f(6, header.loop_filter_level[3]);
+    }
+
+    writer.f(3, header.loop_filter_sharpness);
+    writer.f(1, header.loop_filter_delta_enabled);
+
+    if (header.loop_filter_delta_enabled === 1) {
+        writer.f(1, header.loop_filter_delta_update);
+
+        if (header.loop_filter_delta_update === 1) {
+            // the defaults the parser installs before reading any update, so only genuine changes
+            // are coded
+            const defaults = [1, 0, 0, 0, -1, 0, -1, -1];
+
+            for (let i = 0; i < TOTAL_REFS_PER_FRAME; i++) {
+                const changed = header.loop_filter_ref_deltas[i] !== defaults[i];
+
+                writer.f(1, changed ? 1 : 0);
+
+                if (changed) {
+                    writer.su(7, header.loop_filter_ref_deltas[i]);
+                }
+            }
+
+            for (let i = 0; i < 2; i++) {
+                const changed = header.loop_filter_mode_deltas[i] !== 0;
+
+                writer.f(1, changed ? 1 : 0);
+
+                if (changed) {
+                    writer.su(7, header.loop_filter_mode_deltas[i]);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_cdef_params(writer, sequence, header) {
+    if (header.coded_lossless === 1 || header.allow_intrabc === 1 || sequence.enable_cdef === 0) {
+        return;
+    }
+
+    writer.f(2, header.cdef_damping - 3);
+    writer.f(2, header.cdef_bits);
+
+    for (let i = 0; i < (1 << header.cdef_bits); i++) {
+        writer.f(4, header.cdef_y_pri_strength[i]);
+        writer.f(2, header.cdef_y_sec_strength[i] === 4 ? 3 : header.cdef_y_sec_strength[i]);
+
+        if (sequence.num_planes > 1) {
+            writer.f(4, header.cdef_uv_pri_strength[i]);
+            writer.f(2, header.cdef_uv_sec_strength[i] === 4 ? 3 : header.cdef_uv_sec_strength[i]);
+        }
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_lr_params(writer, sequence, header) {
+    if (header.all_lossless === 1 || header.allow_intrabc === 1 || sequence.enable_restoration === 0) {
+        return;
+    }
+
+    let uses_chroma_lr = 0;
+
+    for (let i = 0; i < sequence.num_planes; i++) {
+        let lr_type = 0;
+
+        for (let candidate = 0; candidate < 4; candidate++) {
+            if (REMAP_LR_TYPE[candidate] === header.frame_restoration_type[i]) {
+                lr_type = candidate;
+
+                break;
+            }
+        }
+
+        writer.f(2, lr_type);
+
+        if (header.frame_restoration_type[i] !== RESTORE_NONE && i > 0) {
+            uses_chroma_lr = 1;
+        }
+    }
+
+    if (header.uses_lr === 0) {
+        return;
+    }
+
+    if (sequence.use_128x128_superblock === 1) {
+        writer.f(1, header.lr_unit_shift - 1);
+    } else {
+        writer.f(1, header.lr_unit_shift > 0 ? 1 : 0);
+
+        if (header.lr_unit_shift > 0) {
+            writer.f(1, header.lr_unit_shift - 1);
+        }
+    }
+
+    if (sequence.subsampling_x === 1 && sequence.subsampling_y === 1 && uses_chroma_lr === 1) {
+        writer.f(1, header.lr_uv_shift);
+    }
+}
+
+/**
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} sequence
+ * @param {FrameHeader} header
+ */
+function write_film_grain_params(writer, sequence, header) {
+    if (sequence.film_grain_params_present === 0 || (header.show_frame === 0 && header.showable_frame === 0)) {
+        return;
+    }
+
+    writer.f(1, header.apply_grain);
+
+    if (header.apply_grain === 0) {
+        return;
+    }
+
+    writer.f(16, header.grain_seed);
+    writer.f(4, header.num_y_points);
+
+    for (let i = 0; i < header.num_y_points; i++) {
+        writer.f(8, header.point_y_value[i]);
+        writer.f(8, header.point_y_scaling[i]);
+    }
+
+    if (sequence.mono_chrome === 0) {
+        writer.f(1, header.chroma_scaling_from_luma);
+    }
+
+    const chroma_points_coded = sequence.mono_chrome === 0
+        && header.chroma_scaling_from_luma === 0
+        && !(sequence.subsampling_x === 1 && sequence.subsampling_y === 1 && header.num_y_points === 0);
+
+    if (chroma_points_coded) {
+        writer.f(4, header.num_cb_points);
+
+        for (let i = 0; i < header.num_cb_points; i++) {
+            writer.f(8, header.point_cb_value[i]);
+            writer.f(8, header.point_cb_scaling[i]);
+        }
+
+        writer.f(4, header.num_cr_points);
+
+        for (let i = 0; i < header.num_cr_points; i++) {
+            writer.f(8, header.point_cr_value[i]);
+            writer.f(8, header.point_cr_scaling[i]);
+        }
+    }
+
+    writer.f(2, header.grain_scaling_minus_8);
+    writer.f(2, header.ar_coeff_lag);
+
+    const num_pos_luma = 2 * header.ar_coeff_lag * (header.ar_coeff_lag + 1);
+
+    let num_pos_chroma = num_pos_luma;
+
+    if (header.num_y_points !== 0) {
+        num_pos_chroma = num_pos_luma + 1;
+
+        for (let i = 0; i < num_pos_luma; i++) {
+            writer.f(8, header.ar_coeffs_y_plus_128[i]);
+        }
+    }
+
+    if (header.chroma_scaling_from_luma === 1 || header.num_cb_points !== 0) {
+        for (let i = 0; i < num_pos_chroma; i++) {
+            writer.f(8, header.ar_coeffs_cb_plus_128[i]);
+        }
+    }
+
+    if (header.chroma_scaling_from_luma === 1 || header.num_cr_points !== 0) {
+        for (let i = 0; i < num_pos_chroma; i++) {
+            writer.f(8, header.ar_coeffs_cr_plus_128[i]);
+        }
+    }
+
+    writer.f(2, header.ar_coeff_shift_minus_6);
+    writer.f(2, header.grain_scale_shift);
+
+    if (header.num_cb_points !== 0) {
+        writer.f(8, header.cb_mult);
+        writer.f(8, header.cb_luma_mult);
+        writer.f(9, header.cb_offset);
+    }
+
+    if (header.num_cr_points !== 0) {
+        writer.f(8, header.cr_mult);
+        writer.f(8, header.cr_luma_mult);
+        writer.f(9, header.cr_offset);
+    }
+
+    writer.f(1, header.overlap_flag);
+    writer.f(1, header.clip_to_restricted_range);
+}

package/src/avif/native/av1/obu/write_sequence_header.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Emit a sequence header OBU payload from `header`.
+ *
+ * Exactly mirrors {@link parse_sequence_header}: a header that was parsed and is re-emitted is
+ * bit-identical, which is what makes the round-trip spec a meaningful check on both directions.
+ * Fields the syntax derives rather than codes — `bit_depth`, `num_planes`, `order_hint_bits` — are
+ * ignored here and recomputed by the reader.
+ *
+ * @param {BitWriter} writer
+ * @param {SequenceHeader} header
+ * @see AV1 spec 5.5.1 "General sequence header OBU syntax"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_sequence_header(writer: BitWriter, header: SequenceHeader): void;
+//# sourceMappingURL=write_sequence_header.d.ts.map

package/src/avif/native/av1/obu/write_sequence_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_sequence_header.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/obu/write_sequence_header.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,uFAsHC"}