@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/filter/loop_restoration.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Apply loop restoration.
+ *
+ * Reads the deringed frame and the pre-CDEF frame, and writes the restored result. The two inputs
+ * are not interchangeable: within a stripe the filter reads deringed samples, and outside it reads
+ * deblocked ones, which is what lets a hardware decoder run restoration a stripe behind CDEF
+ * without an extra line buffer.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} current the deblocked frame, upscaled if superres is in use
+ * @param {Uint16Array[]} cdef the deringed frame, upscaled if superres is in use
+ * @param {Uint16Array[]} output
+ * @param {Int32Array} stride
+ * @see AV1 spec 7.17 "Loop restoration process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_loop_restoration(ctx: Av1FrameContext, current: Uint16Array[], cdef: Uint16Array[], output: Uint16Array[], stride: Int32Array): void;
+/**
+ * `count_units_in_frame`: how many restoration units of one size a frame is divided into.
+ *
+ * @param {number} unit_size
+ * @param {number} frame_size
+ * @returns {number}
+ */
+export function count_units_in_frame(unit_size: number, frame_size: number): number;
+/**
+ * Which restoration unit a 4x4 block is filtered by.
+ *
+ * The vertical mapping is offset by eight luma samples, because restoration works in stripes that
+ * are offset by that much. Exported because the encoder has to attribute a block's error to the
+ * same unit this attributes its filtering to, and the two agreeing is the whole point.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} row 4x4 block row
+ * @param {number} col 4x4 block column
+ * @returns {number} index into the per-unit arrays
+ */
+export function restoration_unit_of(ctx: Av1FrameContext, plane: number, row: number, col: number): number;
+//# sourceMappingURL=loop_restoration.d.ts.map

package/src/avif/native/av1/filter/loop_restoration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop_restoration.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/filter/loop_restoration.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;;;;;;;GAiBG;AACH,sEATW,WAAW,EAAE,QACb,WAAW,EAAE,UACb,WAAW,EAAE,UACb,UAAU,QA+BpB;AAwDD;;;;;;GAMG;AACH,gDAJW,MAAM,cACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;GAYG;AACH,iEALW,MAAM,OACN,MAAM,OACN,MAAM,GACJ,MAAM,CAiBlB"}

package/src/avif/native/av1/filter/loop_restoration.js

@@ -0,0 +1,451 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import {
+    FILTER_BITS,
+    MI_SIZE,
+    RESTORE_NONE,
+    RESTORE_SGRPROJ,
+    RESTORE_WIENER,
+    SGRPROJ_MTABLE_BITS,
+    SGRPROJ_PRJ_BITS,
+    SGRPROJ_RECIP_BITS,
+    SGRPROJ_RST_BITS,
+    SGRPROJ_SGR_BITS
+} from "../tables/av1_symbols.js";
+import { SGR_PARAMS } from "../tables/filter_tables.js";
+import { round2 } from "../util/round2.js";
+
+/**
+ * `A` and `B` from the box filter, valid over one extra sample in each direction.
+ * @type {number}
+ */
+const BOX_STRIDE = MI_SIZE + 2;
+
+/** @type {Int32Array} */
+const BOX_A = new Int32Array(BOX_STRIDE * BOX_STRIDE);
+
+/** @type {Int32Array} */
+const BOX_B = new Int32Array(BOX_STRIDE * BOX_STRIDE);
+
+/** @type {Int32Array} the two self-guided passes' outputs */
+const FLT0 = new Int32Array(MI_SIZE * MI_SIZE);
+
+/** @type {Int32Array} */
+const FLT1 = new Int32Array(MI_SIZE * MI_SIZE);
+
+/** @type {Int32Array} the Wiener filter's horizontal pass */
+const WIENER_INTERMEDIATE = new Int32Array((MI_SIZE + 6) * MI_SIZE);
+
+/** @type {Int32Array} the seven symmetric taps expanded from the three coded ones */
+const WIENER_VERTICAL = new Int32Array(7);
+
+/** @type {Int32Array} */
+const WIENER_HORIZONTAL = new Int32Array(7);
+
+/**
+ * State the source-sample fetch needs, kept here rather than threaded through every call.
+ *
+ * The fetch decides between the deringed frame and the merely deblocked one based on which stripe
+ * the sample falls in, and that boundary changes per block. Hoisting it into a small module-level
+ * record keeps the innermost loops free of parameters they would otherwise carry six deep.
+ */
+const SOURCE = {
+    ctx: null,
+    plane: 0,
+    stripe_start_y: 0,
+    stripe_end_y: 0,
+    plane_end_x: 0,
+    plane_end_y: 0,
+    stride: 0,
+    cdef: null,
+    current: null
+};
+
+/**
+ * Apply loop restoration.
+ *
+ * Reads the deringed frame and the pre-CDEF frame, and writes the restored result. The two inputs
+ * are not interchangeable: within a stripe the filter reads deringed samples, and outside it reads
+ * deblocked ones, which is what lets a hardware decoder run restoration a stripe behind CDEF
+ * without an extra line buffer.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} current the deblocked frame, upscaled if superres is in use
+ * @param {Uint16Array[]} cdef the deringed frame, upscaled if superres is in use
+ * @param {Uint16Array[]} output
+ * @param {Int32Array} stride
+ * @see AV1 spec 7.17 "Loop restoration process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_loop_restoration(ctx, current, cdef, output, stride) {
+    const frame = ctx.frame;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        // the buffers are reused across frames, so the source may be longer than this frame
+        const samples = stride[plane] * ctx.plane_rows[plane];
+
+        output[plane].set(cdef[plane].subarray(0, samples));
+    }
+
+    if (frame.uses_lr === 0) {
+        return;
+    }
+
+    for (let y = 0; y < frame.frame_height; y += MI_SIZE) {
+        for (let x = 0; x < frame.upscaled_width; x += MI_SIZE) {
+            for (let plane = 0; plane < ctx.num_planes; plane++) {
+                if (frame.frame_restoration_type[plane] === RESTORE_NONE) {
+                    continue;
+                }
+
+                restore_block(ctx, current, cdef, output, stride, plane, y >> 2, x >> 2);
+            }
+        }
+    }
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} current
+ * @param {Uint16Array[]} cdef
+ * @param {Uint16Array[]} output
+ * @param {Int32Array} stride
+ * @param {number} plane
+ * @param {number} row
+ * @param {number} col
+ * @see AV1 spec 7.17.1 "Loop restore block process"
+ */
+function restore_block(ctx, current, cdef, output, stride, plane, row, col) {
+    const frame = ctx.frame;
+
+    const luma_y = row * MI_SIZE;
+
+    // stripes are offset up by eight luma samples so a pipelined decoder can restore a stripe as
+    // soon as the superblock row above it is deblocked
+    const stripe = Math.floor((luma_y + 8) / 64);
+
+    const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+    const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+    SOURCE.ctx = ctx;
+    SOURCE.plane = plane;
+    SOURCE.stripe_start_y = (-8 + stripe * 64) >> sub_y;
+    SOURCE.stripe_end_y = SOURCE.stripe_start_y + (64 >> sub_y) - 1;
+    SOURCE.plane_end_x = round2(frame.upscaled_width, sub_x) - 1;
+    SOURCE.plane_end_y = round2(frame.frame_height, sub_y) - 1;
+    SOURCE.stride = stride[plane];
+    SOURCE.cdef = cdef[plane];
+    SOURCE.current = current[plane];
+
+    const x = (col * MI_SIZE) >> sub_x;
+    const y = (row * MI_SIZE) >> sub_y;
+
+    const w = Math.min(MI_SIZE >> sub_x, SOURCE.plane_end_x - x + 1);
+    const h = Math.min(MI_SIZE >> sub_y, SOURCE.plane_end_y - y + 1);
+
+    if (w <= 0 || h <= 0) {
+        return;
+    }
+
+    const unit_index = restoration_unit_of(ctx, plane, row, col);
+
+    const type = ctx.lr_type[unit_index];
+
+    if (type === RESTORE_WIENER) {
+        wiener_filter(ctx, output, stride, plane, unit_index, x, y, w, h);
+    } else if (type === RESTORE_SGRPROJ) {
+        self_guided_filter(ctx, output, stride, plane, unit_index, x, y, w, h);
+    }
+}
+
+/**
+ * `count_units_in_frame`: how many restoration units of one size a frame is divided into.
+ *
+ * @param {number} unit_size
+ * @param {number} frame_size
+ * @returns {number}
+ */
+export function count_units_in_frame(unit_size, frame_size) {
+    return Math.max(Math.floor((frame_size + (unit_size >> 1)) / unit_size), 1);
+}
+
+/**
+ * Which restoration unit a 4x4 block is filtered by.
+ *
+ * The vertical mapping is offset by eight luma samples, because restoration works in stripes that
+ * are offset by that much. Exported because the encoder has to attribute a block's error to the
+ * same unit this attributes its filtering to, and the two agreeing is the whole point.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {number} plane
+ * @param {number} row 4x4 block row
+ * @param {number} col 4x4 block column
+ * @returns {number} index into the per-unit arrays
+ */
+export function restoration_unit_of(ctx, plane, row, col) {
+    const frame = ctx.frame;
+
+    const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+    const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+    const unit_size = frame.loop_restoration_size[plane];
+
+    const unit_rows = count_units_in_frame(unit_size, round2(frame.frame_height, sub_y));
+    const unit_cols = count_units_in_frame(unit_size, round2(frame.upscaled_width, sub_x));
+
+    const unit_row = Math.min(unit_rows - 1, Math.floor(((row * MI_SIZE + 8) >> sub_y) / unit_size));
+    const unit_col = Math.min(unit_cols - 1, Math.floor(((col * MI_SIZE) >> sub_x) / unit_size));
+
+    return ctx.lr_unit_index(plane, unit_row, unit_col);
+}
+
+/**
+ * `get_source_sample`: deringed inside the current stripe, merely deblocked outside it.
+ *
+ * @param {number} x
+ * @param {number} y
+ * @returns {number}
+ * @see AV1 spec 7.17.6 "Get source sample process"
+ */
+function source_sample(x, y) {
+    const clamped_x = clamp(x, 0, SOURCE.plane_end_x);
+
+    let clamped_y = clamp(y, 0, SOURCE.plane_end_y);
+
+    if (clamped_y < SOURCE.stripe_start_y) {
+        clamped_y = Math.max(SOURCE.stripe_start_y - 2, clamped_y);
+
+        return SOURCE.current[clamped_y * SOURCE.stride + clamped_x];
+    }
+
+    if (clamped_y > SOURCE.stripe_end_y) {
+        clamped_y = Math.min(SOURCE.stripe_end_y + 2, clamped_y);
+
+        return SOURCE.current[clamped_y * SOURCE.stride + clamped_x];
+    }
+
+    return SOURCE.cdef[clamped_y * SOURCE.stride + clamped_x];
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} output
+ * @param {Int32Array} stride
+ * @param {number} plane
+ * @param {number} unit_index
+ * @param {number} x
+ * @param {number} y
+ * @param {number} w
+ * @param {number} h
+ * @see AV1 spec 7.17.4 "Wiener filter process"
+ */
+function wiener_filter(ctx, output, stride, plane, unit_index, x, y, w, h) {
+    const bit_depth = ctx.bit_depth;
+
+    // the rounding the specification derives for a non-compound inter prediction, reused here
+    const round0 = bit_depth === 12 ? 5 : 3;
+    const round1 = bit_depth === 12 ? 9 : 11;
+
+    expand_wiener(ctx.lr_wiener, unit_index * 6, WIENER_VERTICAL);
+    expand_wiener(ctx.lr_wiener, unit_index * 6 + 3, WIENER_HORIZONTAL);
+
+    const offset = 1 << (bit_depth + FILTER_BITS - round0 - 1);
+    const limit = (1 << (bit_depth + 1 + FILTER_BITS - round0)) - 1;
+
+    for (let r = 0; r < h + 6; r++) {
+        for (let c = 0; c < w; c++) {
+            let s = 0;
+
+            for (let t = 0; t < 7; t++) {
+                s += WIENER_HORIZONTAL[t] * source_sample(x + c + t - 3, y + r - 3);
+            }
+
+            WIENER_INTERMEDIATE[r * MI_SIZE + c] = clamp(round2(s, round0), -offset, limit - offset);
+        }
+    }
+
+    const max_value = (1 << bit_depth) - 1;
+
+    const plane_output = output[plane];
+    const plane_stride = stride[plane];
+
+    for (let r = 0; r < h; r++) {
+        for (let c = 0; c < w; c++) {
+            let s = 0;
+
+            for (let t = 0; t < 7; t++) {
+                s += WIENER_VERTICAL[t] * WIENER_INTERMEDIATE[(r + t) * MI_SIZE + c];
+            }
+
+            plane_output[(y + r) * plane_stride + x + c] = clamp(round2(s, round1), 0, max_value);
+        }
+    }
+}
+
+/**
+ * Expand three coded taps into the seven of a symmetric unit-gain filter.
+ *
+ * @param {Int8Array} coefficients
+ * @param {number} offset
+ * @param {Int32Array} filter
+ * @see AV1 spec 7.17.5 "Wiener coefficient process"
+ */
+function expand_wiener(coefficients, offset, filter) {
+    filter[3] = 128;
+
+    for (let i = 0; i < 3; i++) {
+        const c = coefficients[offset + i];
+
+        filter[i] = c;
+        filter[6 - i] = c;
+        filter[3] -= 2 * c;
+    }
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} output
+ * @param {Int32Array} stride
+ * @param {number} plane
+ * @param {number} unit_index
+ * @param {number} x
+ * @param {number} y
+ * @param {number} w
+ * @param {number} h
+ * @see AV1 spec 7.17.2 "Self guided filter process"
+ */
+function self_guided_filter(ctx, output, stride, plane, unit_index, x, y, w, h) {
+    const set = ctx.lr_sgr_set[unit_index];
+
+    box_filter(ctx, x, y, w, h, set, 0, FLT0);
+    box_filter(ctx, x, y, w, h, set, 1, FLT1);
+
+    const w0 = ctx.lr_sgr_xqd[unit_index * 2];
+    const w1 = ctx.lr_sgr_xqd[unit_index * 2 + 1];
+    const w2 = (1 << SGRPROJ_PRJ_BITS) - w0 - w1;
+
+    const r0 = SGR_PARAMS[set * 4];
+    const r1 = SGR_PARAMS[set * 4 + 2];
+
+    const max_value = (1 << ctx.bit_depth) - 1;
+
+    const plane_output = output[plane];
+    const plane_stride = stride[plane];
+
+    for (let i = 0; i < h; i++) {
+        for (let j = 0; j < w; j++) {
+            const u = SOURCE.cdef[(y + i) * SOURCE.stride + x + j] << SGRPROJ_RST_BITS;
+
+            let v = w1 * u;
+
+            v += r0 !== 0 ? w0 * FLT0[i * MI_SIZE + j] : w0 * u;
+            v += r1 !== 0 ? w2 * FLT1[i * MI_SIZE + j] : w2 * u;
+
+            plane_output[(y + i) * plane_stride + x + j] = clamp(
+                round2(v, SGRPROJ_RST_BITS + SGRPROJ_PRJ_BITS),
+                0,
+                max_value
+            );
+        }
+    }
+}
+
+/**
+ * @param {Av1FrameContext} ctx
+ * @param {number} x
+ * @param {number} y
+ * @param {number} w
+ * @param {number} h
+ * @param {number} set
+ * @param {number} pass
+ * @param {Int32Array} out
+ * @see AV1 spec 7.17.3 "Box filter process"
+ */
+function box_filter(ctx, x, y, w, h, set, pass, out) {
+    const r = SGR_PARAMS[set * 4 + pass * 2];
+
+    if (r === 0) {
+        return;
+    }
+
+    const eps = SGR_PARAMS[set * 4 + pass * 2 + 1];
+
+    const bit_depth = ctx.bit_depth;
+
+    const n = (2 * r + 1) * (2 * r + 1);
+    const n2e = n * n * eps;
+    const s = Math.floor(((1 << SGRPROJ_MTABLE_BITS) + Math.floor(n2e / 2)) / n2e);
+
+    const one_over_n = Math.floor(((1 << SGRPROJ_RECIP_BITS) + Math.floor(n / 2)) / n);
+
+    for (let i = -1; i < h + 1; i++) {
+        for (let j = -1; j < w + 1; j++) {
+            let a = 0;
+            let b = 0;
+
+            for (let dy = -r; dy <= r; dy++) {
+                for (let dx = -r; dx <= r; dx++) {
+                    const c = source_sample(x + j + dx, y + i + dy);
+
+                    a += c * c;
+                    b += c;
+                }
+            }
+
+            a = round2(a, 2 * (bit_depth - 8));
+
+            const d = round2(b, bit_depth - 8);
+
+            const p = Math.max(0, a * n - d * d);
+            const z = round2(p * s, SGRPROJ_MTABLE_BITS);
+
+            let a2;
+
+            if (z >= 255) {
+                a2 = 256;
+            } else if (z === 0) {
+                a2 = 1;
+            } else {
+                a2 = Math.floor(((z << SGRPROJ_SGR_BITS) + Math.floor(z / 2)) / (z + 1));
+            }
+
+            const b2 = ((1 << SGRPROJ_SGR_BITS) - a2) * b * one_over_n;
+
+            const index = (i + 1) * BOX_STRIDE + j + 1;
+
+            BOX_A[index] = a2;
+            BOX_B[index] = round2(b2, SGRPROJ_RECIP_BITS);
+        }
+    }
+
+    for (let i = 0; i < h; i++) {
+        const shift = pass === 0 && (i & 1) !== 0 ? 4 : 5;
+
+        for (let j = 0; j < w; j++) {
+            let a = 0;
+            let b = 0;
+
+            for (let dy = -1; dy <= 1; dy++) {
+                for (let dx = -1; dx <= 1; dx++) {
+                    let weight;
+
+                    if (pass === 0) {
+                        weight = ((i + dy) & 1) !== 0 ? (dx === 0 ? 6 : 5) : 0;
+                    } else {
+                        weight = dx === 0 || dy === 0 ? 4 : 3;
+                    }
+
+                    const index = (i + dy + 1) * BOX_STRIDE + j + dx + 1;
+
+                    a += weight * BOX_A[index];
+                    b += weight * BOX_B[index];
+                }
+            }
+
+            const v = a * SOURCE.cdef[(y + i) * SOURCE.stride + x + j] + b;
+
+            out[i * MI_SIZE + j] = round2(v, SGRPROJ_SGR_BITS + shift - SGRPROJ_RST_BITS);
+        }
+    }
+}

package/src/avif/native/av1/filter/superres.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Horizontally upscale a superres frame.
+ *
+ * Superres codes a frame narrower than it is displayed and restores the width here, with an eight
+ * tap filter whose phase advances by a fixed fractional step per output sample. Only the horizontal
+ * axis is scaled: the vertical resolution is never reduced.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} source planes at the coded width
+ * @param {Uint16Array[]} destination planes at the upscaled width
+ * @param {Int32Array} destination_stride
+ * @see AV1 spec 7.16 "Upscaling process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_superres(ctx: Av1FrameContext, source: Uint16Array[], destination: Uint16Array[], destination_stride: Int32Array): void;
+//# sourceMappingURL=superres.d.ts.map

package/src/avif/native/av1/filter/superres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"superres.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/filter/superres.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,6DARW,WAAW,EAAE,eACb,WAAW,EAAE,sBACb,UAAU,QA8DpB"}

package/src/avif/native/av1/filter/superres.js

@@ -0,0 +1,86 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import {
+    FILTER_BITS,
+    MI_SIZE,
+    SUPERRES_EXTRA_BITS,
+    SUPERRES_FILTER_OFFSET,
+    SUPERRES_FILTER_TAPS,
+    SUPERRES_SCALE_BITS,
+    SUPERRES_SCALE_MASK
+} from "../tables/av1_symbols.js";
+import { UPSCALE_FILTER } from "../tables/filter_tables.js";
+import { round2 } from "../util/round2.js";
+
+/**
+ * Horizontally upscale a superres frame.
+ *
+ * Superres codes a frame narrower than it is displayed and restores the width here, with an eight
+ * tap filter whose phase advances by a fixed fractional step per output sample. Only the horizontal
+ * axis is scaled: the vertical resolution is never reduced.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {Uint16Array[]} source planes at the coded width
+ * @param {Uint16Array[]} destination planes at the upscaled width
+ * @param {Int32Array} destination_stride
+ * @see AV1 spec 7.16 "Upscaling process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_superres(ctx, source, destination, destination_stride) {
+    const frame = ctx.frame;
+
+    const max_value = (1 << ctx.bit_depth) - 1;
+
+    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 downscaled_width = round2(frame.frame_width, sub_x);
+        const upscaled_width = round2(frame.upscaled_width, sub_x);
+        const plane_height = round2(frame.frame_height, sub_y);
+
+        const step_x = Math.trunc(((downscaled_width * (1 << SUPERRES_SCALE_BITS)) + Math.trunc(upscaled_width / 2)) / upscaled_width);
+
+        const error = upscaled_width * step_x - downscaled_width * (1 << SUPERRES_SCALE_BITS);
+
+        // both divisions truncate towards zero, and the first one's numerator is negative: the
+        // specification's integer division is truncating, not flooring
+        let initial_subpel_x = Math.trunc(
+            (-((upscaled_width - downscaled_width) * (1 << (SUPERRES_SCALE_BITS - 1))) + Math.trunc(upscaled_width / 2)) / upscaled_width
+        ) + (1 << (SUPERRES_EXTRA_BITS - 1)) - Math.trunc(error / 2);
+
+        initial_subpel_x &= SUPERRES_SCALE_MASK;
+
+        const min_x = 0;
+        const max_x = ((ctx.mi_cols >> sub_x) * MI_SIZE) - 1;
+
+        const source_stride = ctx.plane_stride[plane];
+        const out_stride = destination_stride[plane];
+
+        const in_plane = source[plane];
+        const out_plane = destination[plane];
+
+        for (let y = 0; y < plane_height; y++) {
+            const source_row = y * source_stride;
+            const destination_row = y * out_stride;
+
+            for (let x = 0; x < upscaled_width; x++) {
+                const src_x = -(1 << SUPERRES_SCALE_BITS) + initial_subpel_x + x * step_x;
+
+                const src_x_px = src_x >> SUPERRES_SCALE_BITS;
+                const src_x_subpel = (src_x & SUPERRES_SCALE_MASK) >> SUPERRES_EXTRA_BITS;
+
+                let sum = 0;
+
+                for (let k = 0; k < SUPERRES_FILTER_TAPS; k++) {
+                    const sample_x = clamp(src_x_px + (k - SUPERRES_FILTER_OFFSET), min_x, max_x);
+
+                    sum += in_plane[source_row + sample_x] * UPSCALE_FILTER[src_x_subpel * SUPERRES_FILTER_TAPS + k];
+                }
+
+                out_plane[destination_row + x] = clamp(round2(sum, FILTER_BITS), 0, max_value);
+            }
+        }
+    }
+}

package/src/avif/native/av1/grain/FilmGrainState.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Width of the grain templates, in samples. The luma template is used at full width; the chroma
+ * templates use only the leading 44 columns when the chroma planes are subsampled horizontally.
+ * @type {number}
+ */
+export const GRAIN_STRIDE: number;
+/**
+ * Height of the luma grain template, in samples.
+ * @type {number}
+ */
+export const GRAIN_ROWS: number;
+/**
+ * Height of one noise stripe, in luma samples. Stripes advance 32 rows at a time, so the last two
+ * rows of each exist only to be blended into the first two of the next.
+ * @type {number}
+ */
+export const STRIPE_ROWS: number;
+/**
+ * Working storage for film grain synthesis, allocated once and reused.
+ *
+ * The specification describes the process in terms of a noise image the size of the whole frame.
+ * Materialising that would cost three more planes, so this holds one stripe of noise and the two
+ * rows of the stripe before it that the vertical blend reads — which is all the process ever looks
+ * at, and is what the specification's own note suggests.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FilmGrainState {
+    /** @type {Int16Array} the auto-regressively filtered luma template, `GRAIN_ROWS` x `GRAIN_STRIDE` */
+    luma_grain: Int16Array;
+    /** @type {Int16Array} */
+    cb_grain: Int16Array;
+    /** @type {Int16Array} */
+    cr_grain: Int16Array;
+    /** @type {Uint8Array} three planes of 256 entries, indexed `plane * 256 + value` */
+    scaling_lut: Uint8Array;
+    /** @type {Int16Array[]} the current stripe of noise, one buffer per plane */
+    stripe: Int16Array[];
+    /** @type {Int16Array[]} the trailing rows of the previous stripe, two per plane */
+    overlap: Int16Array[];
+    /**
+     * Distance between rows of {@link stripe} and {@link overlap}, in samples.
+     *
+     * Wider than the frame: the stripe is written in 32 sample blocks of which the last may start
+     * within the frame and end past its right edge. Those samples are never read, but they are
+     * written, so there has to be somewhere to put them.
+     * @type {number}
+     */
+    stripe_stride: number;
+    /** @type {number} the 16 bit shift register the noise is drawn from */
+    random_register: number;
+    /** @type {number} */
+    grain_min: number;
+    /** @type {number} */
+    grain_max: number;
+    /**
+     * @param {number} frame_width
+     */
+    resize(frame_width: number): void;
+}
+//# sourceMappingURL=FilmGrainState.d.ts.map

package/src/avif/native/av1/grain/FilmGrainState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilmGrainState.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/grain/FilmGrainState.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,2BAFU,MAAM,CAEe;AAE/B;;;GAGG;AACH,yBAFU,MAAM,CAEa;AAE7B;;;;GAIG;AACH,0BAFU,MAAM,CAEc;AAE9B;;;;;;;;;;GAUG;AACH;IACI,qGAAqG;IACrG,YADW,UAAU,CACkC;IAEvD,yBAAyB;IACzB,UADW,UAAU,CACgC;IAErD,yBAAyB;IACzB,UADW,UAAU,CACgC;IAErD,oFAAoF;IACpF,aADW,UAAU,CACiB;IAEtC,6EAA6E;IAC7E,QADW,UAAU,EAAE,CACK;IAE5B,mFAAmF;IACnF,SADW,UAAU,EAAE,CACM;IAE7B;;;;;;;OAOG;IACH,eAFU,MAAM,CAEE;IAElB,uEAAuE;IACvE,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,WADW,MAAM,CACH;IAEd,qBAAqB;IACrB,WADW,MAAM,CACH;IAEd;;OAEG;IACH,oBAFW,MAAM,QAehB;CACJ"}