@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/bitstream/BitWriter.js

@@ -0,0 +1,351 @@
+import { floor_log2 } from "../av1/util/floor_log2.js";
+
+/**
+ * Bytes the buffer starts at and grows by. Headers are small; the tile payload does not come
+ * through here.
+ * @type {number}
+ */
+const INITIAL_CAPACITY = 256;
+
+/**
+ * MSB-first bit sink, the inverse of {@link BitReader}.
+ *
+ * Grows its own backing array. Used for OBU headers and for synthesising streams in tests; tile
+ * payloads are produced by the symbol writer, which emits bytes directly.
+ *
+ * @see AV1 spec 4.10 "Descriptors"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BitWriter {
+    /**
+     * Bytes written so far, plus unused capacity beyond {@link byte_position}.
+     * @type {Uint8Array}
+     */
+    data = new Uint8Array(INITIAL_CAPACITY);
+
+    /**
+     * Index of the byte currently being filled.
+     * @type {number}
+     */
+    byte_position = 0;
+
+    /**
+     * Number of bits already placed in the byte at {@link byte_position}, counting from the most
+     * significant.
+     * @type {number}
+     */
+    bit_position = 0;
+
+    /**
+     * Discard everything written and start again, keeping the allocated buffer. Lets one writer
+     * serve many payloads without allocating.
+     * @returns {BitWriter} this
+     */
+    reset() {
+        this.byte_position = 0;
+        this.bit_position = 0;
+        this.data[0] = 0;
+
+        return this;
+    }
+
+    /**
+     * Bits written since the last {@link reset}.
+     * @returns {number}
+     */
+    get position_in_bits() {
+        return this.byte_position * 8 + this.bit_position;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get is_byte_aligned() {
+        return this.bit_position === 0;
+    }
+
+    /**
+     * @param {number} required_bytes
+     * @private
+     */
+    #ensure_capacity(required_bytes) {
+        if (required_bytes <= this.data.length) {
+            return;
+        }
+
+        let capacity = this.data.length * 2;
+
+        while (capacity < required_bytes) {
+            capacity *= 2;
+        }
+
+        const grown = new Uint8Array(capacity);
+
+        grown.set(this.data);
+
+        this.data = grown;
+    }
+
+    /**
+     * Write a single bit.
+     * @param {number} bit `0` or `1`
+     */
+    write_bit(bit) {
+        this.#ensure_capacity(this.byte_position + 1);
+
+        if (bit !== 0) {
+            this.data[this.byte_position] |= 1 << (7 - this.bit_position);
+        }
+
+        if (this.bit_position === 7) {
+            this.bit_position = 0;
+            this.byte_position++;
+
+            this.#ensure_capacity(this.byte_position + 1);
+
+            this.data[this.byte_position] = 0;
+        } else {
+            this.bit_position++;
+        }
+    }
+
+    /**
+     * `f(n)`: unsigned `n`-bit number, most significant bit first.
+     *
+     * Emits a byte at a time where alignment allows. `value` is decomposed with division rather
+     * than shifts so that a 32-bit value does not lose its top bit to sign extension.
+     *
+     * @param {number} n `0 .. 32`
+     * @param {number} value
+     */
+    f(n, value) {
+        if (n === 0) {
+            return;
+        }
+
+        if (n < 0 || n > 32) {
+            throw new Error(`f(n) supports 0..32 bits, got ${n}`);
+        }
+
+        if (value < 0 || value > (2 ** n) - 1) {
+            throw new Error(`value ${value} does not fit in ${n} bits`);
+        }
+
+        let remaining = n;
+
+        while (remaining > 0) {
+            const available_in_byte = 8 - this.bit_position;
+            const take = remaining < available_in_byte ? remaining : available_in_byte;
+
+            remaining -= take;
+
+            // the chunk that belongs in this byte is the `take` bits sitting just above whatever
+            // is still unwritten
+            const chunk = Math.floor(value / (2 ** remaining)) & ((1 << take) - 1);
+
+            this.#ensure_capacity(this.byte_position + 1);
+
+            this.data[this.byte_position] |= chunk << (available_in_byte - take);
+
+            this.bit_position += take;
+
+            if (this.bit_position === 8) {
+                this.bit_position = 0;
+                this.byte_position++;
+
+                this.#ensure_capacity(this.byte_position + 1);
+
+                this.data[this.byte_position] = 0;
+            }
+        }
+    }
+
+    /**
+     * `su(n)`: signed integer, bottom `n` bits written.
+     * @param {number} n `1 .. 32`
+     * @param {number} value
+     */
+    su(n, value) {
+        const sign_mask = 1 << (n - 1);
+
+        if (value < -sign_mask || value >= sign_mask) {
+            throw new Error(`value ${value} does not fit in a signed ${n} bit field`);
+        }
+
+        this.f(n, value < 0 ? value + 2 * sign_mask : value);
+    }
+
+    /**
+     * `ns(n)`: unsigned integer in `0 .. n - 1`.
+     * @param {number} n number of distinct values, `>= 1`
+     * @param {number} value
+     */
+    ns(n, value) {
+        if (value < 0 || value >= n) {
+            throw new Error(`ns(${n}) cannot encode ${value}`);
+        }
+
+        const w = floor_log2(n) + 1;
+        const m = (1 << w) - n;
+
+        if (value < m) {
+            this.f(w - 1, value);
+
+            return;
+        }
+
+        const shifted = value + m;
+
+        this.f(w - 1, shifted >> 1);
+        this.write_bit(shifted & 1);
+    }
+
+    /**
+     * `uvlc()`: variable length unsigned number.
+     * @param {number} value `0 .. 2^32 - 1`
+     */
+    uvlc(value) {
+        if (value === 4294967295) {
+            for (let i = 0; i < 32; i++) {
+                this.write_bit(0);
+            }
+
+            this.write_bit(1);
+
+            return;
+        }
+
+        const shifted = value + 1;
+        const leading_zeros = floor_log2(shifted);
+
+        for (let i = 0; i < leading_zeros; i++) {
+            this.write_bit(0);
+        }
+
+        this.write_bit(1);
+
+        this.f(leading_zeros, shifted - (2 ** leading_zeros));
+    }
+
+    /**
+     * `le(n)`: unsigned little-endian `n`-byte number. Requires byte alignment.
+     * @param {number} n `0 .. 6`
+     * @param {number} value
+     */
+    le(n, value) {
+        if (!this.is_byte_aligned) {
+            throw new Error("le(n) requires a byte aligned bitstream position");
+        }
+
+        if (n < 0 || n > 6) {
+            throw new Error(`le(n) supports 0..6 bytes, got ${n}`);
+        }
+
+        let remaining = value;
+
+        for (let i = 0; i < n; i++) {
+            this.f(8, remaining % 256);
+
+            remaining = Math.floor(remaining / 256);
+        }
+    }
+
+    /**
+     * `leb128()`: variable-length little-endian unsigned integer. Requires byte alignment.
+     *
+     * `fixed_size` pads the encoding out to a chosen byte count with redundant continuation bits.
+     * The specification explicitly allows this so a writer can reserve space for a length it does
+     * not know yet and patch it later, which is exactly how OBU sizes are emitted.
+     *
+     * @param {number} value `0 .. 2^32 - 1`
+     * @param {number} [fixed_size] number of bytes to occupy, `1 .. 8`
+     */
+    leb128(value, fixed_size = 0) {
+        if (!this.is_byte_aligned) {
+            throw new Error("leb128() requires a byte aligned bitstream position");
+        }
+
+        if (value < 0 || value > 4294967295) {
+            throw new Error(`leb128() value ${value} is outside 0..2^32 - 1`);
+        }
+
+        if (fixed_size < 0 || fixed_size > 8) {
+            throw new Error(`leb128() fixed_size must be 0..8, got ${fixed_size}`);
+        }
+
+        let remaining = value;
+        let written = 0;
+
+        do {
+            let byte = remaining % 128;
+
+            remaining = Math.floor(remaining / 128);
+
+            written++;
+
+            const more = remaining !== 0 || written < fixed_size;
+
+            if (more) {
+                byte |= 0x80;
+            }
+
+            this.f(8, byte);
+        } while (remaining !== 0 || written < fixed_size);
+    }
+
+    /**
+     * Pad to the next byte boundary with zero bits.
+     * @see AV1 spec 5.3.5 "Byte alignment syntax"
+     */
+    byte_alignment() {
+        while (!this.is_byte_aligned) {
+            this.write_bit(0);
+        }
+    }
+
+    /**
+     * Write the `trailing_one_bit` and zero padding that terminates an OBU payload.
+     * @see AV1 spec 5.3.4 "Trailing bits syntax"
+     */
+    trailing_bits() {
+        this.write_bit(1);
+
+        this.byte_alignment();
+    }
+
+    /**
+     * Copy whole bytes in. Requires byte alignment.
+     * @param {Uint8Array} bytes
+     * @param {number} [offset]
+     * @param {number} [length]
+     */
+    write_bytes(bytes, offset = 0, length = bytes.length - offset) {
+        if (!this.is_byte_aligned) {
+            throw new Error("write_bytes() requires a byte aligned bitstream position");
+        }
+
+        this.#ensure_capacity(this.byte_position + length + 1);
+
+        this.data.set(bytes.subarray(offset, offset + length), this.byte_position);
+
+        this.byte_position += length;
+        this.data[this.byte_position] = 0;
+    }
+
+    /**
+     * The bytes written so far. A partially filled trailing byte is included, with its unwritten
+     * low bits zero.
+     *
+     * Returns a view onto the writer's own buffer, so it is only valid until the next write. Copy
+     * it if it needs to outlive the writer's next use.
+     *
+     * @returns {Uint8Array}
+     */
+    to_bytes() {
+        const length = this.bit_position === 0 ? this.byte_position : this.byte_position + 1;
+
+        return this.data.subarray(0, length);
+    }
+}

package/src/avif/native/color/ColourTransform.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Work out the conversion an image's colour signalling asks for.
+ *
+ * Two matrices are refused rather than approximated. Constant luminance (`MC_BT_2020_CL`,
+ * `MC_CHROMAT_CL`) codes luma through the transfer function, so undoing it is a different process
+ * rather than a different matrix; `MC_SMPTE_2085` and `MC_ICTCP` are not matrices at all. None of
+ * them appears in a real AVIF file, and silently decoding one as if it were BT.709 would produce a
+ * plausible-looking wrong picture.
+ *
+ * @param {ColourTransform} transform
+ * @param {number} matrix_coefficients an `MC_*` code
+ * @param {number} color_primaries a `CP_*` code, used only by `MC_CHROMAT_NCL`
+ * @param {number} color_range `1` for full range
+ * @param {number} bit_depth
+ * @see ITU-T H.273 section 8.3 "Matrix coefficients"
+ */
+export function colour_transform_init(transform: ColourTransform, matrix_coefficients: number, color_primaries: number, color_range: number, bit_depth: number): void;
+/**
+ * Ordinary non-constant-luminance YCbCr, which is all but two of the matrices.
+ * @type {number}
+ */
+export const CONVERSION_MATRIX: number;
+/**
+ * The planes are already G, B and R.
+ * @type {number}
+ */
+export const CONVERSION_IDENTITY: number;
+/**
+ * YCgCo, which is a lifting scheme rather than a matrix.
+ * @type {number}
+ */
+export const CONVERSION_YCGCO: number;
+/**
+ * How to turn coded samples into normalised R, G and B.
+ *
+ * Holds the arithmetic, not the policy: which matrix and which range are decided once, by
+ * {@link colour_transform_init}, and what is left is four multiplications per pixel.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ColourTransform {
+    /** @type {number} one of the `CONVERSION_*` constants */
+    kind: number;
+    /** @type {number} sample value that means black */
+    y_offset: number;
+    /** @type {number} reciprocal of the luma range, so that `(Y - y_offset) * y_scale` is `0 .. 1` */
+    y_scale: number;
+    /** @type {number} sample value that means no colour difference */
+    c_offset: number;
+    /** @type {number} reciprocal of the chroma range, giving `-0.5 .. 0.5` */
+    c_scale: number;
+    /** @type {number} */
+    cr_to_r: number;
+    /** @type {number} */
+    cb_to_g: number;
+    /** @type {number} */
+    cr_to_g: number;
+    /** @type {number} */
+    cb_to_b: number;
+}
+//# sourceMappingURL=ColourTransform.d.ts.map

package/src/avif/native/color/ColourTransform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColourTransform.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/color/ColourTransform.js"],"names":[],"mappings":"AAiFA;;;;;;;;;;;;;;;GAeG;AACH,iDAPW,eAAe,uBACf,MAAM,mBACN,MAAM,eACN,MAAM,aACN,MAAM,QA8FhB;AA1KD;;;GAGG;AACH,gCAFU,MAAM,CAEmB;AAEnC;;;GAGG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,+BAFU,MAAM,CAEkB;AASlC;;;;;;;;GAQG;AACH;IACI,yDAAyD;IACzD,MADW,MAAM,CACQ;IAEzB,mDAAmD;IACnD,UADW,MAAM,CACJ;IAEb,kGAAkG;IAClG,SADW,MAAM,CACL;IAEZ,kEAAkE;IAClE,UADW,MAAM,CACJ;IAEb,0EAA0E;IAC1E,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,SADW,MAAM,CACL;CACf"}

package/src/avif/native/color/ColourTransform.js

@@ -0,0 +1,189 @@
+import {
+    MC_BT_2020_CL,
+    MC_BT_2020_NCL,
+    MC_BT_470_B_G,
+    MC_BT_601,
+    MC_BT_709,
+    MC_CHROMAT_CL,
+    MC_CHROMAT_NCL,
+    MC_FCC,
+    MC_ICTCP,
+    MC_IDENTITY,
+    MC_SMPTE_2085,
+    MC_SMPTE_240,
+    MC_SMPTE_YCGCO,
+    MC_UNSPECIFIED
+} from "../av1/tables/av1_symbols.js";
+import { derive_luma_coefficients } from "./primaries.js";
+
+/**
+ * Ordinary non-constant-luminance YCbCr, which is all but two of the matrices.
+ * @type {number}
+ */
+export const CONVERSION_MATRIX = 0;
+
+/**
+ * The planes are already G, B and R.
+ * @type {number}
+ */
+export const CONVERSION_IDENTITY = 1;
+
+/**
+ * YCgCo, which is a lifting scheme rather than a matrix.
+ * @type {number}
+ */
+export const CONVERSION_YCGCO = 2;
+
+/**
+ * Scratch for {@link colour_transform_init}. Module level because initialisation happens once per
+ * image and the coefficients are wanted only for the moment it takes to derive the matrix from them.
+ * @type {Float64Array}
+ */
+const COEFFICIENTS = new Float64Array(3);
+
+/**
+ * How to turn coded samples into normalised R, G and B.
+ *
+ * Holds the arithmetic, not the policy: which matrix and which range are decided once, by
+ * {@link colour_transform_init}, and what is left is four multiplications per pixel.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ColourTransform {
+    /** @type {number} one of the `CONVERSION_*` constants */
+    kind = CONVERSION_MATRIX;
+
+    /** @type {number} sample value that means black */
+    y_offset = 0;
+
+    /** @type {number} reciprocal of the luma range, so that `(Y - y_offset) * y_scale` is `0 .. 1` */
+    y_scale = 1;
+
+    /** @type {number} sample value that means no colour difference */
+    c_offset = 0;
+
+    /** @type {number} reciprocal of the chroma range, giving `-0.5 .. 0.5` */
+    c_scale = 1;
+
+    /** @type {number} */
+    cr_to_r = 0;
+
+    /** @type {number} */
+    cb_to_g = 0;
+
+    /** @type {number} */
+    cr_to_g = 0;
+
+    /** @type {number} */
+    cb_to_b = 0;
+}
+
+/**
+ * Work out the conversion an image's colour signalling asks for.
+ *
+ * Two matrices are refused rather than approximated. Constant luminance (`MC_BT_2020_CL`,
+ * `MC_CHROMAT_CL`) codes luma through the transfer function, so undoing it is a different process
+ * rather than a different matrix; `MC_SMPTE_2085` and `MC_ICTCP` are not matrices at all. None of
+ * them appears in a real AVIF file, and silently decoding one as if it were BT.709 would produce a
+ * plausible-looking wrong picture.
+ *
+ * @param {ColourTransform} transform
+ * @param {number} matrix_coefficients an `MC_*` code
+ * @param {number} color_primaries a `CP_*` code, used only by `MC_CHROMAT_NCL`
+ * @param {number} color_range `1` for full range
+ * @param {number} bit_depth
+ * @see ITU-T H.273 section 8.3 "Matrix coefficients"
+ */
+export function colour_transform_init(transform, matrix_coefficients, color_primaries, color_range, bit_depth) {
+    const shift = bit_depth - 8;
+
+    if (color_range === 1) {
+        const maximum = (1 << bit_depth) - 1;
+
+        transform.y_offset = 0;
+        transform.y_scale = 1 / maximum;
+        transform.c_offset = 1 << (bit_depth - 1);
+        transform.c_scale = 1 / maximum;
+    } else {
+        transform.y_offset = 16 << shift;
+        transform.y_scale = 1 / (219 << shift);
+        transform.c_offset = 128 << shift;
+        transform.c_scale = 1 / (224 << shift);
+    }
+
+    if (matrix_coefficients === MC_IDENTITY) {
+        transform.kind = CONVERSION_IDENTITY;
+
+        return;
+    }
+
+    if (matrix_coefficients === MC_SMPTE_YCGCO) {
+        transform.kind = CONVERSION_YCGCO;
+
+        return;
+    }
+
+    transform.kind = CONVERSION_MATRIX;
+
+    let kr;
+    let kb;
+
+    switch (matrix_coefficients) {
+        case MC_BT_709:
+            kr = 0.2126;
+            kb = 0.0722;
+            break;
+
+        case MC_FCC:
+            kr = 0.30;
+            kb = 0.11;
+            break;
+
+        case MC_BT_470_B_G:
+        case MC_BT_601:
+        // an unspecified matrix is not a licence to invent one: every encoder that leaves it
+        // unspecified means BT.601, and that is what every decoder assumes
+        case MC_UNSPECIFIED:
+            kr = 0.299;
+            kb = 0.114;
+            break;
+
+        case MC_SMPTE_240:
+            kr = 0.212;
+            kb = 0.087;
+            break;
+
+        case MC_BT_2020_NCL:
+            kr = 0.2627;
+            kb = 0.0593;
+            break;
+
+        case MC_CHROMAT_NCL:
+            derive_luma_coefficients(color_primaries, COEFFICIENTS);
+
+            kr = COEFFICIENTS[0];
+            kb = COEFFICIENTS[2];
+            break;
+
+        case MC_BT_2020_CL:
+        case MC_CHROMAT_CL:
+            throw new Error("constant luminance matrix coefficients are not supported");
+
+        case MC_SMPTE_2085:
+            throw new Error("SMPTE 2085 (Y'D'zD'x) matrix coefficients are not supported");
+
+        case MC_ICTCP:
+            throw new Error("ICtCp matrix coefficients are not supported");
+
+        default:
+            throw new Error(`unknown matrix coefficients ${matrix_coefficients}`);
+    }
+
+    const kg = 1 - kr - kb;
+
+    transform.cr_to_r = 2 * (1 - kr);
+    transform.cb_to_b = 2 * (1 - kb);
+    transform.cb_to_g = -2 * kb * (1 - kb) / kg;
+    transform.cr_to_g = -2 * kr * (1 - kr) / kg;
+}

package/src/avif/native/color/YuvImage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A decoded image, as the AV1 layer produces it and the colour layer consumes it.
+ *
+ * Deliberately a description rather than an owner: the plane arrays belong to whoever allocated
+ * them, usually a frame context that reuses them across decodes. Nothing here copies samples, which
+ * is what lets a grid of tiles, an alpha channel and the colour conversion all talk about the same
+ * memory.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class YuvImage {
+    /** @type {Uint16Array[]} Y, Cb, Cr — or G, B, R when the matrix is the identity */
+    planes: Uint16Array[];
+    /** @type {Int32Array} distance between rows of each plane, in samples */
+    stride: Int32Array;
+    /** @type {number} */
+    width: number;
+    /** @type {number} */
+    height: number;
+    /** @type {number} `8`, `10` or `12` */
+    bit_depth: number;
+    /** @type {number} */
+    subsampling_x: number;
+    /** @type {number} */
+    subsampling_y: number;
+    /** @type {number} `1` for monochrome */
+    num_planes: number;
+    /** @type {number} a `CP_*` code */
+    color_primaries: number;
+    /** @type {number} a `TC_*` code */
+    transfer_characteristics: number;
+    /** @type {number} an `MC_*` code */
+    matrix_coefficients: number;
+    /** @type {number} `1` when the samples use the full range of the bit depth */
+    color_range: number;
+    /** @type {Uint16Array|null} the alpha plane, which AVIF codes as a separate monochrome image */
+    alpha: Uint16Array | null;
+    /** @type {number} */
+    alpha_stride: number;
+    /** @type {number} */
+    alpha_bit_depth: number;
+    /** @type {number} */
+    alpha_range: number;
+    /**
+     * @type {number} `1` when the colour channels have already been multiplied by alpha
+     * @see ISO/IEC 23000-22 `prem` item reference
+     */
+    alpha_premultiplied: number;
+}
+//# sourceMappingURL=YuvImage.d.ts.map

package/src/avif/native/color/YuvImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"YuvImage.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/color/YuvImage.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI,mFAAmF;IACnF,QADW,WAAW,EAAE,CACI;IAE5B,yEAAyE;IACzE,QADW,UAAU,CACM;IAE3B,qBAAqB;IACrB,OADW,MAAM,CACP;IAEV,qBAAqB;IACrB,QADW,MAAM,CACN;IAEX,uCAAuC;IACvC,WADW,MAAM,CACH;IAEd,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,wCAAwC;IACxC,YADW,MAAM,CACF;IAEf,mCAAmC;IACnC,iBADW,MAAM,CACG;IAEpB,mCAAmC;IACnC,0BADW,MAAM,CACY;IAE7B,oCAAoC;IACpC,qBADW,MAAM,CACO;IAExB,8EAA8E;IAC9E,aADW,MAAM,CACD;IAEhB,gGAAgG;IAChG,OADW,WAAW,GAAC,IAAI,CACd;IAEb,qBAAqB;IACrB,cADW,MAAM,CACA;IAEjB,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,aADW,MAAM,CACD;IAEhB;;;OAGG;IACH,qBAHU,MAAM,CAGQ;CAC3B"}