@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/grain/film_grain.js

@@ -0,0 +1,623 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import { GAUSSIAN_SEQUENCE } from "../tables/grain_tables.js";
+import { GRAIN_ROWS, GRAIN_STRIDE, STRIPE_ROWS } from "./FilmGrainState.js";
+import { MC_IDENTITY } from "../tables/av1_symbols.js";
+import { round2 } from "../util/round2.js";
+
+/**
+ * Seed the Cb template is drawn with, so that it decorrelates from luma.
+ * @type {number}
+ */
+const CB_SEED_XOR = 0xb524;
+
+/** @type {number} */
+const CR_SEED_XOR = 0x49d8;
+
+/**
+ * Add synthesised film grain to a decoded frame, in place.
+ *
+ * Grain is not a filter over the image: it is noise generated from a seed in the bitstream, so an
+ * encoder can discard the grain in its source and have the decoder put an equivalent amount back.
+ * Two 82x73 templates of shaped noise are built once, then tiled over the frame from pseudo-random
+ * offsets and scaled by how bright each sample already is.
+ *
+ * @param {Av1FrameContext} ctx
+ * @see AV1 spec 7.18.3 "Film grain synthesis process"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_film_grain(ctx) {
+    const frame = ctx.frame;
+
+    if (frame.apply_grain === 0) {
+        return;
+    }
+
+    const state = ctx.grain;
+
+    const grain_center = 128 << (ctx.bit_depth - 8);
+
+    state.grain_min = -grain_center;
+    state.grain_max = (256 << (ctx.bit_depth - 8)) - 1 - grain_center;
+    state.random_register = frame.grain_seed;
+
+    state.resize(ctx.output_width);
+
+    generate_grain(ctx, state);
+    initialise_scaling_lut(ctx, state);
+    add_noise(ctx, state);
+}
+
+/**
+ * Draw the next pseudo-random number.
+ *
+ * A sixteen bit linear feedback shift register, so that an encoder and a decoder agreeing only on a
+ * seed produce the same noise.
+ *
+ * @param {FilmGrainState} state
+ * @param {number} bits how many bits of the register to return
+ * @returns {number}
+ * @see AV1 spec 7.18.3.2 "Random number process"
+ */
+function get_random_number(state, bits) {
+    const r = state.random_register;
+
+    const bit = ((r >> 0) ^ (r >> 1) ^ (r >> 3) ^ (r >> 12)) & 1;
+
+    const next = (r >> 1) | (bit << 15);
+
+    state.random_register = next;
+
+    return (next >> (16 - bits)) & ((1 << bits) - 1);
+}
+
+/**
+ * Build the grain templates: white noise, shaped by an auto-regressive filter whose coefficients the
+ * bitstream carries.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @see AV1 spec 7.18.3.3 "Generate grain process"
+ */
+function generate_grain(ctx, state) {
+    const frame = ctx.frame;
+
+    const luma = state.luma_grain;
+
+    const noise_shift = 12 - ctx.bit_depth + frame.grain_scale_shift;
+    const ar_shift = frame.ar_coeff_shift_minus_6 + 6;
+
+    const lag = frame.ar_coeff_lag;
+
+    const minimum = state.grain_min;
+    const maximum = state.grain_max;
+
+    for (let y = 0; y < GRAIN_ROWS; y++) {
+        for (let x = 0; x < GRAIN_STRIDE; x++) {
+            const g = frame.num_y_points > 0 ? GAUSSIAN_SEQUENCE[get_random_number(state, 11)] : 0;
+
+            luma[y * GRAIN_STRIDE + x] = round2(g, noise_shift);
+        }
+    }
+
+    for (let y = 3; y < GRAIN_ROWS; y++) {
+        for (let x = 3; x < GRAIN_STRIDE - 3; x++) {
+            let s = 0;
+            let pos = 0;
+
+            for (let delta_row = -lag; delta_row <= 0; delta_row++) {
+                for (let delta_col = -lag; delta_col <= lag; delta_col++) {
+                    if (delta_row === 0 && delta_col === 0) {
+                        break;
+                    }
+
+                    const c = frame.ar_coeffs_y_plus_128[pos] - 128;
+
+                    s += luma[(y + delta_row) * GRAIN_STRIDE + x + delta_col] * c;
+
+                    pos++;
+                }
+            }
+
+            const index = y * GRAIN_STRIDE + x;
+
+            luma[index] = clamp(luma[index] + round2(s, ar_shift), minimum, maximum);
+        }
+    }
+
+    if (ctx.num_planes === 1) {
+        return;
+    }
+
+    const cb = state.cb_grain;
+    const cr = state.cr_grain;
+
+    const sub_x = ctx.subsampling_x;
+    const sub_y = ctx.subsampling_y;
+
+    const chroma_width = sub_x !== 0 ? 44 : 82;
+    const chroma_height = sub_y !== 0 ? 38 : 73;
+
+    const draws_cb = frame.num_cb_points > 0 || frame.chroma_scaling_from_luma === 1;
+    const draws_cr = frame.num_cr_points > 0 || frame.chroma_scaling_from_luma === 1;
+
+    state.random_register = frame.grain_seed ^ CB_SEED_XOR;
+
+    for (let y = 0; y < chroma_height; y++) {
+        for (let x = 0; x < chroma_width; x++) {
+            const g = draws_cb ? GAUSSIAN_SEQUENCE[get_random_number(state, 11)] : 0;
+
+            cb[y * GRAIN_STRIDE + x] = round2(g, noise_shift);
+        }
+    }
+
+    state.random_register = frame.grain_seed ^ CR_SEED_XOR;
+
+    for (let y = 0; y < chroma_height; y++) {
+        for (let x = 0; x < chroma_width; x++) {
+            const g = draws_cr ? GAUSSIAN_SEQUENCE[get_random_number(state, 11)] : 0;
+
+            cr[y * GRAIN_STRIDE + x] = round2(g, noise_shift);
+        }
+    }
+
+    for (let y = 3; y < chroma_height; y++) {
+        for (let x = 3; x < chroma_width - 3; x++) {
+            let s0 = 0;
+            let s1 = 0;
+            let pos = 0;
+
+            for (let delta_row = -lag; delta_row <= 0; delta_row++) {
+                for (let delta_col = -lag; delta_col <= lag; delta_col++) {
+                    const c0 = frame.ar_coeffs_cb_plus_128[pos] - 128;
+                    const c1 = frame.ar_coeffs_cr_plus_128[pos] - 128;
+
+                    if (delta_row === 0 && delta_col === 0) {
+                        // the centre tap is a correlation with the luma template rather than with
+                        // the chroma one, which is what ties the two together
+                        if (frame.num_y_points > 0) {
+                            let sum = 0;
+
+                            const luma_x = ((x - 3) << sub_x) + 3;
+                            const luma_y = ((y - 3) << sub_y) + 3;
+
+                            for (let i = 0; i <= sub_y; i++) {
+                                for (let j = 0; j <= sub_x; j++) {
+                                    sum += luma[(luma_y + i) * GRAIN_STRIDE + luma_x + j];
+                                }
+                            }
+
+                            sum = round2(sum, sub_x + sub_y);
+
+                            s0 += sum * c0;
+                            s1 += sum * c1;
+                        }
+
+                        break;
+                    }
+
+                    s0 += cb[(y + delta_row) * GRAIN_STRIDE + x + delta_col] * c0;
+                    s1 += cr[(y + delta_row) * GRAIN_STRIDE + x + delta_col] * c1;
+
+                    pos++;
+                }
+            }
+
+            const index = y * GRAIN_STRIDE + x;
+
+            cb[index] = clamp(cb[index] + round2(s0, ar_shift), minimum, maximum);
+            cr[index] = clamp(cr[index] + round2(s1, ar_shift), minimum, maximum);
+        }
+    }
+}
+
+/**
+ * Expand the handful of signalled points into a scaling curve, one entry per eight bit sample value.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @see AV1 spec 7.18.3.4 "Scaling lookup initialization process"
+ */
+function initialise_scaling_lut(ctx, state) {
+    const frame = ctx.frame;
+
+    const lut = state.scaling_lut;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const from_luma = plane === 0 || frame.chroma_scaling_from_luma === 1;
+
+        let values;
+        let scalings;
+        let count;
+
+        if (from_luma) {
+            values = frame.point_y_value;
+            scalings = frame.point_y_scaling;
+            count = frame.num_y_points;
+        } else if (plane === 1) {
+            values = frame.point_cb_value;
+            scalings = frame.point_cb_scaling;
+            count = frame.num_cb_points;
+        } else {
+            values = frame.point_cr_value;
+            scalings = frame.point_cr_scaling;
+            count = frame.num_cr_points;
+        }
+
+        const base = plane * 256;
+
+        if (count === 0) {
+            lut.fill(0, base, base + 256);
+
+            continue;
+        }
+
+        lut.fill(scalings[0], base, base + values[0]);
+
+        for (let i = 0; i < count - 1; i++) {
+            const delta_y = scalings[i + 1] - scalings[i];
+            const delta_x = values[i + 1] - values[i];
+
+            const delta = delta_y * Math.floor((65536 + (delta_x >> 1)) / delta_x);
+
+            for (let x = 0; x < delta_x; x++) {
+                lut[base + values[i] + x] = scalings[i] + ((x * delta + 32768) >> 16);
+            }
+        }
+
+        lut.fill(scalings[count - 1], base + values[count - 1], base + 256);
+    }
+}
+
+/**
+ * Interpolate the scaling curve at a sample value, which above eight bits falls between entries.
+ *
+ * @param {FilmGrainState} state
+ * @param {number} plane
+ * @param {number} index the sample value to scale for
+ * @param {number} bit_depth
+ * @returns {number}
+ * @see AV1 spec 7.18.3.5, `scale_lut`
+ */
+function scale_lut(state, plane, index, bit_depth) {
+    const shift = bit_depth - 8;
+
+    const x = index >> shift;
+
+    const base = plane * 256;
+
+    if (shift === 0 || x === 255) {
+        return state.scaling_lut[base + x];
+    }
+
+    const rem = index - (x << shift);
+
+    const start = state.scaling_lut[base + x];
+    const end = state.scaling_lut[base + x + 1];
+
+    return start + round2((end - start) * rem, shift);
+}
+
+/**
+ * Tile the templates over the frame and blend the result into the image.
+ *
+ * The specification writes this as a noise image the size of the frame, then blends it. Noise for
+ * one stripe only ever depends on the stripe before it, so this walks the two together and keeps
+ * just the rows the next stripe will read.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @see AV1 spec 7.18.3.5 "Add noise synthesis process"
+ */
+function add_noise(ctx, state) {
+    const w = ctx.output_width;
+    const h = ctx.output_height;
+
+    const sub_x = ctx.num_planes > 1 ? ctx.subsampling_x : 0;
+    const sub_y = ctx.num_planes > 1 ? ctx.subsampling_y : 0;
+
+    const stripes = Math.ceil(((h + 1) >> 1) / 16);
+
+    for (let luma_num = 0; luma_num < stripes; luma_num++) {
+        build_stripe(ctx, state, luma_num, w, sub_x, sub_y);
+
+        blend_stripe(ctx, state, luma_num, w, h, sub_x, sub_y);
+
+        save_overlap(ctx, state, sub_y);
+    }
+}
+
+/**
+ * Fill one stripe of noise by tiling the templates from pseudo-random offsets.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @param {number} luma_num which stripe
+ * @param {number} w frame width in luma samples
+ * @param {number} sub_x
+ * @param {number} sub_y
+ */
+function build_stripe(ctx, state, luma_num, w, sub_x, sub_y) {
+    const frame = ctx.frame;
+
+    const stride = state.stripe_stride;
+
+    const minimum = state.grain_min;
+    const maximum = state.grain_max;
+
+    const overlaps = frame.overlap_flag === 1;
+
+    state.random_register = frame.grain_seed
+        ^ (((luma_num * 37 + 178) & 255) << 8)
+        ^ ((luma_num * 173 + 105) & 255);
+
+    const half_width = (w + 1) >> 1;
+
+    for (let x = 0; x < half_width; x += 16) {
+        const random = get_random_number(state, 8);
+
+        const offset_x = random >> 4;
+        const offset_y = random & 15;
+
+        for (let plane = 0; plane < ctx.num_planes; plane++) {
+            const plane_sub_x = plane > 0 ? sub_x : 0;
+            const plane_sub_y = plane > 0 ? sub_y : 0;
+
+            const plane_offset_x = plane_sub_x !== 0 ? 6 + offset_x : 9 + offset_x * 2;
+            const plane_offset_y = plane_sub_y !== 0 ? 6 + offset_y : 9 + offset_y * 2;
+
+            const grain = plane === 0
+                ? state.luma_grain
+                : (plane === 1 ? state.cb_grain : state.cr_grain);
+
+            const noise = state.stripe[plane];
+
+            const rows = STRIPE_ROWS >> plane_sub_y;
+            const columns = STRIPE_ROWS >> plane_sub_x;
+
+            const first_column = plane_sub_x !== 0 ? x : x * 2;
+
+            for (let i = 0; i < rows; i++) {
+                const source_row = (plane_offset_y + i) * GRAIN_STRIDE + plane_offset_x;
+                const destination_row = i * stride + first_column;
+
+                for (let j = 0; j < columns; j++) {
+                    let g = grain[source_row + j];
+
+                    // where two tiles meet, the samples either side of the seam are a weighted mix
+                    // of both, or the tiling would show as a grid of edges
+                    if (plane_sub_x === 0) {
+                        if (j < 2 && overlaps && x > 0) {
+                            const old = noise[destination_row + j];
+
+                            g = j === 0 ? old * 27 + g * 17 : old * 17 + g * 27;
+                            g = clamp(round2(g, 5), minimum, maximum);
+                        }
+                    } else if (j === 0 && overlaps && x > 0) {
+                        const old = noise[destination_row + j];
+
+                        g = clamp(round2(old * 23 + g * 22, 5), minimum, maximum);
+                    }
+
+                    noise[destination_row + j] = g;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Blend one stripe of noise into the image.
+ *
+ * The chroma planes are done first: their noise is scaled by how bright the luma underneath is, and
+ * the specification means the luma before noise was added to it.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @param {number} luma_num
+ * @param {number} w
+ * @param {number} h
+ * @param {number} sub_x
+ * @param {number} sub_y
+ */
+function blend_stripe(ctx, state, luma_num, w, h, sub_x, sub_y) {
+    const frame = ctx.frame;
+
+    const bit_depth = ctx.bit_depth;
+
+    const scaling_shift = frame.grain_scaling_minus_8 + 8;
+
+    const maximum_sample = (1 << bit_depth) - 1;
+
+    let minimum_value;
+    let maximum_luma;
+    let maximum_chroma;
+
+    if (frame.clip_to_restricted_range === 1) {
+        minimum_value = 16 << (bit_depth - 8);
+        maximum_luma = 235 << (bit_depth - 8);
+        maximum_chroma = ctx.sequence.matrix_coefficients === MC_IDENTITY
+            ? maximum_luma
+            : 240 << (bit_depth - 8);
+    } else {
+        minimum_value = 0;
+        maximum_luma = maximum_sample;
+        maximum_chroma = maximum_sample;
+    }
+
+    const luma_plane = ctx.output_planes[0];
+    const luma_stride = ctx.output_stride[0];
+
+    const scales_cb = frame.num_cb_points > 0 || frame.chroma_scaling_from_luma === 1;
+    const scales_cr = frame.num_cr_points > 0 || frame.chroma_scaling_from_luma === 1;
+
+    if (ctx.num_planes > 1 && (scales_cb || scales_cr)) {
+        const chroma_rows = (h + sub_y) >> sub_y;
+        const chroma_columns = (w + sub_x) >> sub_x;
+
+        const first_row = luma_num * (32 >> sub_y);
+        const last_row = Math.min(chroma_rows, first_row + (32 >> sub_y));
+
+        for (let y = first_row; y < last_row; y++) {
+            const luma_y = y << sub_y;
+
+            for (let x = 0; x < chroma_columns; x++) {
+                const luma_x = x << sub_x;
+
+                let average_luma;
+
+                if (sub_x !== 0) {
+                    const next_x = Math.min(luma_x + 1, w - 1);
+
+                    average_luma = round2(
+                        luma_plane[luma_y * luma_stride + luma_x]
+                        + luma_plane[luma_y * luma_stride + next_x],
+                        1
+                    );
+                } else {
+                    average_luma = luma_plane[luma_y * luma_stride + luma_x];
+                }
+
+                if (scales_cb) {
+                    blend_chroma_sample(
+                        ctx, state, 1, x, y, y - first_row, luma_num, average_luma,
+                        frame.cb_mult, frame.cb_luma_mult, frame.cb_offset,
+                        scaling_shift, minimum_value, maximum_chroma, maximum_sample, sub_y
+                    );
+                }
+
+                if (scales_cr) {
+                    blend_chroma_sample(
+                        ctx, state, 2, x, y, y - first_row, luma_num, average_luma,
+                        frame.cr_mult, frame.cr_luma_mult, frame.cr_offset,
+                        scaling_shift, minimum_value, maximum_chroma, maximum_sample, sub_y
+                    );
+                }
+            }
+        }
+    }
+
+    if (frame.num_y_points === 0) {
+        return;
+    }
+
+    const stride = state.stripe_stride;
+
+    const noise_plane = state.stripe[0];
+    const overlap_plane = state.overlap[0];
+
+    const overlaps = frame.overlap_flag === 1 && luma_num > 0;
+
+    const first_row = luma_num * 32;
+    const last_row = Math.min(h, first_row + 32);
+
+    for (let y = first_row; y < last_row; y++) {
+        const i = y - first_row;
+
+        const noise_row = i * stride;
+        const image_row = y * luma_stride;
+
+        for (let x = 0; x < w; x++) {
+            let g = noise_plane[noise_row + x];
+
+            if (i < 2 && overlaps) {
+                const old = overlap_plane[noise_row + x];
+
+                g = i === 0 ? old * 27 + g * 17 : old * 17 + g * 27;
+                g = clamp(round2(g, 5), state.grain_min, state.grain_max);
+            }
+
+            const original = luma_plane[image_row + x];
+
+            const noise = round2(scale_lut(state, 0, original, bit_depth) * g, scaling_shift);
+
+            luma_plane[image_row + x] = clamp(original + noise, minimum_value, maximum_luma);
+        }
+    }
+}
+
+/**
+ * Blend one chroma sample.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @param {number} plane 1 for Cb, 2 for Cr
+ * @param {number} x
+ * @param {number} y row within the plane
+ * @param {number} i row within the stripe
+ * @param {number} luma_num
+ * @param {number} average_luma
+ * @param {number} mult
+ * @param {number} luma_mult
+ * @param {number} offset
+ * @param {number} scaling_shift
+ * @param {number} minimum_value
+ * @param {number} maximum_chroma
+ * @param {number} maximum_sample
+ * @param {number} sub_y
+ */
+function blend_chroma_sample(
+    ctx, state, plane, x, y, i, luma_num, average_luma,
+    mult, luma_mult, offset, scaling_shift, minimum_value, maximum_chroma, maximum_sample, sub_y
+) {
+    const frame = ctx.frame;
+
+    const stride = state.stripe_stride;
+
+    let g = state.stripe[plane][i * stride + x];
+
+    if (frame.overlap_flag === 1 && luma_num > 0 && i < (sub_y !== 0 ? 1 : 2)) {
+        const old = state.overlap[plane][i * stride + x];
+
+        if (sub_y !== 0) {
+            g = clamp(round2(old * 23 + g * 22, 5), state.grain_min, state.grain_max);
+        } else {
+            g = i === 0 ? old * 27 + g * 17 : old * 17 + g * 27;
+            g = clamp(round2(g, 5), state.grain_min, state.grain_max);
+        }
+    }
+
+    const image = ctx.output_planes[plane];
+    const image_stride = ctx.output_stride[plane];
+
+    const original = image[y * image_stride + x];
+
+    let merged;
+
+    if (frame.chroma_scaling_from_luma === 1) {
+        merged = average_luma;
+    } else {
+        const combined = average_luma * (luma_mult - 128) + original * (mult - 128);
+
+        merged = clamp((combined >> 6) + ((offset - 256) << (ctx.bit_depth - 8)), 0, maximum_sample);
+    }
+
+    const noise = round2(scale_lut(state, plane, merged, ctx.bit_depth) * g, scaling_shift);
+
+    image[y * image_stride + x] = clamp(original + noise, minimum_value, maximum_chroma);
+}
+
+/**
+ * Keep the rows of this stripe that the next one blends with.
+ *
+ * @param {Av1FrameContext} ctx
+ * @param {FilmGrainState} state
+ * @param {number} sub_y
+ */
+function save_overlap(ctx, state, sub_y) {
+    const stride = state.stripe_stride;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const plane_sub_y = plane > 0 ? sub_y : 0;
+
+        const noise = state.stripe[plane];
+        const overlap = state.overlap[plane];
+
+        if (plane_sub_y !== 0) {
+            overlap.set(noise.subarray(16 * stride, 17 * stride), 0);
+        } else {
+            overlap.set(noise.subarray(32 * stride, 34 * stride), 0);
+        }
+    }
+}