@woosh/meep-engine 3.9.0 → 3.11.0

package/src/avif/native/api/AvifDecoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvifDecoder.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/AvifDecoder.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH;IACI,4BAA4B;IAC5B,QADW,WAAW,EAAE,CACI;IAE5B,yBAAyB;IACzB,QADW,UAAU,CACM;IAE3B,qBAAqB;IACrB,OADW,MAAM,CACP;IAEV,qBAAqB;IACrB,QADW,MAAM,CACN;IAEX;;;;;;OAMG;IACH,cANW,MAAM,UACN,MAAM,iBACN,MAAM,iBACN,MAAM,cACN,MAAM,QA8BhB;CACJ;AAED;;;;;;;;;GASG;AACH;IACI,8BAA8B;IAC9B,cADW,eAAe,CACW;IAErC,8BAA8B;IAC9B,aADW,eAAe,CACU;IAEpC,yBAAyB;IACzB,cADW,UAAU,CACW;IAEhC,yBAAyB;IACzB,aADW,UAAU,CACU;IAE/B,mCAAmC;IACnC,OADW,QAAQ,CACI;IAEvB,sFAAsF;IACtF,aADW,QAAQ,CACU;IAE7B,8BAA8B;IAC9B,WADW,eAAe,CACQ;IAElC,wDAAwD;IACxD,QADW,YAAY,CACT;IAEd,2BAA2B;IAC3B,QADW,YAAY,CACT;IAEd,0DAA0D;IAC1D,SADW,YAAY,CACR;IAEf,qBAAqB;IACrB,WADW,MAAM,CACH;IAEd;;OAEG;IACH,mBAFW,MAAM,QAYhB;CACJ;gCAxH+B,kCAAkC;yBAEzC,sBAAsB;gCADf,6BAA6B"}

package/src/avif/native/api/AvifDecoder.js

@@ -0,0 +1,121 @@
+import { Av1FrameContext } from "../av1/decode/Av1FrameContext.js";
+import { ColourTransform } from "../color/ColourTransform.js";
+import { YuvImage } from "../color/YuvImage.js";
+
+/**
+ * Somewhere to assemble a grid of tiles, or to hold a frame that outlives the context that decoded
+ * it.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PlaneStore {
+    /** @type {Uint16Array[]} */
+    planes = [null, null, null];
+
+    /** @type {Int32Array} */
+    stride = new Int32Array(3);
+
+    /** @type {number} */
+    width = 0;
+
+    /** @type {number} */
+    height = 0;
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     * @param {number} subsampling_x
+     * @param {number} subsampling_y
+     * @param {number} num_planes
+     */
+    resize(width, height, subsampling_x, subsampling_y, num_planes) {
+        this.width = width;
+        this.height = height;
+
+        for (let plane = 0; plane < 3; plane++) {
+            if (plane >= num_planes) {
+                this.planes[plane] = null;
+                this.stride[plane] = 0;
+
+                continue;
+            }
+
+            const sub_x = plane > 0 ? subsampling_x : 0;
+            const sub_y = plane > 0 ? subsampling_y : 0;
+
+            const stride = (width + sub_x) >> sub_x;
+            const rows = (height + sub_y) >> sub_y;
+
+            const samples = stride * rows;
+
+            this.stride[plane] = stride;
+
+            const existing = this.planes[plane];
+
+            if (existing === null || existing.length < samples) {
+                this.planes[plane] = new Uint16Array(samples);
+            }
+        }
+    }
+}
+
+/**
+ * Everything a decode needs beyond the file itself, allocated once and reused.
+ *
+ * Colour and alpha get a frame context each. They could share one, but then decoding the alpha
+ * would overwrite the picture, and every caller would have to copy the picture out first — which is
+ * exactly the allocation this is here to avoid.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class AvifDecoder {
+    /** @type {Av1FrameContext} */
+    colour_frame = new Av1FrameContext();
+
+    /** @type {Av1FrameContext} */
+    alpha_frame = new Av1FrameContext();
+
+    /** @type {PlaneStore} */
+    colour_store = new PlaneStore();
+
+    /** @type {PlaneStore} */
+    alpha_store = new PlaneStore();
+
+    /** @type {YuvImage} the picture */
+    image = new YuvImage();
+
+    /** @type {YuvImage} the alpha plane, which AVIF codes as an image in its own right */
+    alpha_image = new YuvImage();
+
+    /** @type {ColourTransform} */
+    transform = new ColourTransform();
+
+    /** @type {Float32Array} one row of Cb, at full width */
+    cb_row = null;
+
+    /** @type {Float32Array} */
+    cr_row = null;
+
+    /** @type {Float32Array} one row of interleaved R, G, B */
+    rgb_row = null;
+
+    /** @type {number} */
+    row_width = 0;
+
+    /**
+     * @param {number} width
+     */
+    resize_rows(width) {
+        if (this.row_width >= width) {
+            return;
+        }
+
+        this.row_width = width;
+
+        this.cb_row = new Float32Array(width);
+        this.cr_row = new Float32Array(width);
+        this.rgb_row = new Float32Array(width * 3);
+    }
+}

package/src/avif/native/api/apply_transformations.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Apply the orientation an item's `irot` and `imir` properties declare, to interleaved RGBA.
+ *
+ * A camera writes these rather than rotating the samples, so a file that carries them is a picture
+ * that is stored one way round and meant to be seen another. libavif hands them to its caller
+ * instead of applying them, which is why this is a decode option rather than something the decoder
+ * always does — a caller that already honours orientation elsewhere would otherwise apply it twice.
+ *
+ * `clap`, the clean aperture, is deliberately left alone: it is a crop expressed as four rationals,
+ * it is rare, and cropping a picture by a misread fraction is worse than not cropping it.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}} image
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @see ISO/IEC 23008-12 section 6.5.10 "Image rotation" and 6.5.12 "Image mirroring"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_transformations(file: AvifFile, item: AvifItem, image: {
+    data: (Uint8ClampedArray | Uint16Array);
+    width: number;
+    height: number;
+}): {
+    data: (Uint8ClampedArray | Uint16Array);
+    width: number;
+    height: number;
+};
+//# sourceMappingURL=apply_transformations.d.ts.map

package/src/avif/native/api/apply_transformations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply_transformations.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/apply_transformations.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6EAPW;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GACpE;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAuBlF"}

package/src/avif/native/api/apply_transformations.js

@@ -0,0 +1,120 @@
+import { find_item_property } from "../heif/find_item_property.js";
+
+/**
+ * Apply the orientation an item's `irot` and `imir` properties declare, to interleaved RGBA.
+ *
+ * A camera writes these rather than rotating the samples, so a file that carries them is a picture
+ * that is stored one way round and meant to be seen another. libavif hands them to its caller
+ * instead of applying them, which is why this is a decode option rather than something the decoder
+ * always does — a caller that already honours orientation elsewhere would otherwise apply it twice.
+ *
+ * `clap`, the clean aperture, is deliberately left alone: it is a crop expressed as four rationals,
+ * it is rare, and cropping a picture by a misread fraction is worse than not cropping it.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}} image
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ * @see ISO/IEC 23008-12 section 6.5.10 "Image rotation" and 6.5.12 "Image mirroring"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function apply_transformations(file, item, image) {
+    const mirror = find_item_property(file, item, "imir");
+    const rotation = find_item_property(file, item, "irot");
+
+    let result = image;
+
+    // the properties apply in the order they are associated, and the association order for these
+    // two is fixed by the format: mirroring first, then rotation
+    if (mirror !== null) {
+        result = mirror_image(result, mirror.axis);
+    }
+
+    if (rotation !== null && rotation.angle !== 0) {
+        result = rotate_image(result, rotation.angle);
+    }
+
+    return result;
+}
+
+/**
+ * @param {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}} image
+ * @param {number} axis `0` about a horizontal axis, `1` about a vertical one
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ */
+function mirror_image(image, axis) {
+    const width = image.width;
+    const height = image.height;
+
+    const source = image.data;
+
+    const out = new source.constructor(source.length);
+
+    for (let y = 0; y < height; y++) {
+        const source_y = axis === 0 ? height - 1 - y : y;
+
+        for (let x = 0; x < width; x++) {
+            const source_x = axis === 0 ? x : width - 1 - x;
+
+            const from = (source_y * width + source_x) * 4;
+            const to = (y * width + x) * 4;
+
+            out[to] = source[from];
+            out[to + 1] = source[from + 1];
+            out[to + 2] = source[from + 2];
+            out[to + 3] = source[from + 3];
+        }
+    }
+
+    return { data: out, width, height };
+}
+
+/**
+ * @param {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}} image
+ * @param {number} angle in units of ninety degrees anticlockwise
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ */
+function rotate_image(image, angle) {
+    const width = image.width;
+    const height = image.height;
+
+    const source = image.data;
+
+    const turned = (angle & 1) === 1;
+
+    const out_width = turned ? height : width;
+    const out_height = turned ? width : height;
+
+    const out = new source.constructor(source.length);
+
+    for (let y = 0; y < out_height; y++) {
+        for (let x = 0; x < out_width; x++) {
+            let source_x;
+            let source_y;
+
+            if (angle === 1) {
+                // ninety degrees anticlockwise: the right hand column becomes the top row
+                source_x = out_height - 1 - y;
+                source_y = x;
+            } else if (angle === 2) {
+                source_x = width - 1 - x;
+                source_y = height - 1 - y;
+            } else {
+                source_x = y;
+                source_y = out_width - 1 - x;
+            }
+
+            const from = (source_y * width + source_x) * 4;
+            const to = (y * out_width + x) * 4;
+
+            out[to] = source[from];
+            out[to + 1] = source[from + 1];
+            out[to + 2] = source[from + 2];
+            out[to + 3] = source[from + 3];
+        }
+    }
+
+    return { data: out, width: out_width, height: out_height };
+}

package/src/avif/native/api/avif_to_sampler2d.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decode an AVIF file into a sampler the renderer can use.
+ *
+ * High dynamic range images come back as half floats holding linear light, which is what the
+ * renderer's textures are; everything else comes back as eight bit samples.
+ *
+ * The linear normalisation is the renderer's: `1.0` is SDR reference white,
+ * {@link SDR_WHITE_NITS} nits per ITU-R BT.2408, which is the unit every sampler in the engine is
+ * already in. Naming it to the decoder is what makes this the exact inverse of
+ * {@link sampler2d_to_avif}, which names the same white to the encoder.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @param {object} [options]
+ * @param {boolean} [options.hdr] decode to linear half floats rather than eight bit samples
+ * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
+ * @returns {Sampler2D}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function avif_to_sampler2d(buffer: ArrayBuffer | Uint8Array, options?: {
+    hdr?: boolean;
+}, decoder?: AvifDecoder): Sampler2D;
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+//# sourceMappingURL=avif_to_sampler2d.d.ts.map

package/src/avif/native/api/avif_to_sampler2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avif_to_sampler2d.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/avif_to_sampler2d.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0CATW,WAAW,GAAC,UAAU;IAEJ,GAAG,GAArB,OAAO;2BAEL,SAAS,CAqBrB;0BAvCyB,uDAAuD"}

package/src/avif/native/api/avif_to_sampler2d.js

@@ -0,0 +1,42 @@
+import { COLOUR_SPACE_LINEAR, COLOUR_SPACE_SIGNAL, CHROMA_UPSAMPLING_BEST } from "./convert_to_rgba.js";
+import { SDR_WHITE_NITS } from "../../../core/color/PQ/PQ_constants.js";
+import { Sampler2D } from "../../../engine/graphics/texture/sampler/Sampler2D.js";
+import { decode_avif } from "./decode_avif.js";
+
+/**
+ * Decode an AVIF file into a sampler the renderer can use.
+ *
+ * High dynamic range images come back as half floats holding linear light, which is what the
+ * renderer's textures are; everything else comes back as eight bit samples.
+ *
+ * The linear normalisation is the renderer's: `1.0` is SDR reference white,
+ * {@link SDR_WHITE_NITS} nits per ITU-R BT.2408, which is the unit every sampler in the engine is
+ * already in. Naming it to the decoder is what makes this the exact inverse of
+ * {@link sampler2d_to_avif}, which names the same white to the encoder.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @param {object} [options]
+ * @param {boolean} [options.hdr] decode to linear half floats rather than eight bit samples
+ * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
+ * @returns {Sampler2D}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function avif_to_sampler2d(buffer, options = {}, decoder = undefined) {
+    const hdr = options.hdr === true;
+
+    const decoded = decode_avif(
+        buffer,
+        {
+            bit_depth: hdr ? 12 : 8,
+            output_float16: hdr,
+            output_colour_space: hdr ? COLOUR_SPACE_LINEAR : COLOUR_SPACE_SIGNAL,
+            linear_reference_nits: SDR_WHITE_NITS,
+            chroma_upsampling: CHROMA_UPSAMPLING_BEST
+        },
+        decoder
+    );
+
+    return new Sampler2D(decoded.data, 4, decoded.width, decoded.height);
+}

package/src/avif/native/api/convert_to_rgba.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Convert a decoded image to interleaved RGBA.
+ *
+ * Works a row at a time through buffers on the decoder, so the only allocation is the output
+ * itself — which the caller owns and this cannot reuse.
+ *
+ * @param {AvifDecoder} decoder
+ * @param {YuvImage} image
+ * @param {object} [options]
+ * @param {number} [options.bit_depth] `8`, `10` or `12`; ignored when the output is float
+ * @param {boolean} [options.output_float16] half floats rather than integers
+ * @param {number} [options.output_colour_space] one of the `COLOUR_SPACE_*` constants
+ * @param {number} [options.linear_reference_nits] luminance a linear `1.0` in the *output* stands
+ *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read for `COLOUR_SPACE_LINEAR`,
+ *   and the exact counterpart of {@link encode_avif}'s option of the same name
+ * @param {number} [options.chroma_upsampling] one of the `CHROMA_UPSAMPLING_*` constants
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function convert_to_rgba(decoder: AvifDecoder, image: YuvImage, options?: {
+    bit_depth?: number;
+    output_float16?: boolean;
+    output_colour_space?: number;
+    linear_reference_nits?: number;
+    chroma_upsampling?: number;
+}): {
+    data: (Uint8ClampedArray | Uint16Array);
+    width: number;
+    height: number;
+};
+/**
+ * Hand back the samples as they were coded, gamma and all.
+ * @type {number}
+ */
+export const COLOUR_SPACE_SIGNAL: number;
+/**
+ * Undo the transfer function, so that the output is linear light with `1.0` at
+ * {@link LINEAR_REFERENCE_NITS}, or at whatever `linear_reference_nits` names instead. Only useful
+ * with a float output: HDR content goes well above one.
+ * @type {number}
+ */
+export const COLOUR_SPACE_LINEAR: number;
+/**
+ * Let the decoder pick, which means interpolating whenever chroma is subsampled.
+ * @type {number}
+ */
+export const CHROMA_UPSAMPLING_AUTOMATIC: number;
+/** @type {number} nearest neighbour */
+export const CHROMA_UPSAMPLING_FASTEST: number;
+/** @type {number} bilinear */
+export const CHROMA_UPSAMPLING_BEST: number;
+//# sourceMappingURL=convert_to_rgba.d.ts.map

package/src/avif/native/api/convert_to_rgba.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert_to_rgba.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/convert_to_rgba.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAZ4B,SAAS,GAA1B,MAAM;IACY,cAAc,GAAhC,OAAO;IACU,mBAAmB,GAApC,MAAM;IACW,qBAAqB,GAAtC,MAAM;IAGW,iBAAiB,GAAlC,MAAM;;UACG,CAAC,iBAAiB,GAAC,WAAW,CAAC;WAAS,MAAM;YAAU,MAAM;EAiHjF;AA3JD;;;GAGG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;;;GAKG;AACH,kCAFU,MAAM,CAEqB;AAErC;;;GAGG;AACH,0CAFU,MAAM,CAE6B;AAE7C,uCAAuC;AACvC,wCADW,MAAM,CAC0B;AAE3C,8BAA8B;AAC9B,qCADW,MAAM,CACuB"}

package/src/avif/native/api/convert_to_rgba.js

@@ -0,0 +1,204 @@
+import { clamp01 } from "../../../core/math/clamp01.js";
+import { clamp_sample } from "../color/clamp_sample.js";
+import { colour_transform_init } from "../color/ColourTransform.js";
+import { LINEAR_REFERENCE_NITS } from "../color/transfer_to_linear.js";
+import { MC_BT_601 } from "../av1/tables/av1_symbols.js";
+import { to_half_float_uint16 } from "../../../core/binary/to_half_float_uint16.js";
+import { transfer_row_to_linear } from "../color/transfer_to_linear.js";
+import { UPSAMPLE_BILINEAR, UPSAMPLE_NEAREST, upsample_chroma_row } from "../color/upsample_chroma_row.js";
+import { ycbcr_row_to_rgb } from "../color/ycbcr_row_to_rgb.js";
+
+/**
+ * Hand back the samples as they were coded, gamma and all.
+ * @type {number}
+ */
+export const COLOUR_SPACE_SIGNAL = 0;
+
+/**
+ * Undo the transfer function, so that the output is linear light with `1.0` at
+ * {@link LINEAR_REFERENCE_NITS}, or at whatever `linear_reference_nits` names instead. Only useful
+ * with a float output: HDR content goes well above one.
+ * @type {number}
+ */
+export const COLOUR_SPACE_LINEAR = 1;
+
+/**
+ * Let the decoder pick, which means interpolating whenever chroma is subsampled.
+ * @type {number}
+ */
+export const CHROMA_UPSAMPLING_AUTOMATIC = 0;
+
+/** @type {number} nearest neighbour */
+export const CHROMA_UPSAMPLING_FASTEST = 1;
+
+/** @type {number} bilinear */
+export const CHROMA_UPSAMPLING_BEST = 2;
+
+/**
+ * Convert a decoded image to interleaved RGBA.
+ *
+ * Works a row at a time through buffers on the decoder, so the only allocation is the output
+ * itself — which the caller owns and this cannot reuse.
+ *
+ * @param {AvifDecoder} decoder
+ * @param {YuvImage} image
+ * @param {object} [options]
+ * @param {number} [options.bit_depth] `8`, `10` or `12`; ignored when the output is float
+ * @param {boolean} [options.output_float16] half floats rather than integers
+ * @param {number} [options.output_colour_space] one of the `COLOUR_SPACE_*` constants
+ * @param {number} [options.linear_reference_nits] luminance a linear `1.0` in the *output* stands
+ *   for, in nits; defaults to {@link LINEAR_REFERENCE_NITS}. Only read for `COLOUR_SPACE_LINEAR`,
+ *   and the exact counterpart of {@link encode_avif}'s option of the same name
+ * @param {number} [options.chroma_upsampling] one of the `CHROMA_UPSAMPLING_*` constants
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function convert_to_rgba(decoder, image, options = {}) {
+    const width = image.width;
+    const height = image.height;
+
+    const output_bit_depth = options.bit_depth ?? 8;
+    const output_float16 = options.output_float16 === true;
+    const colour_space = options.output_colour_space ?? COLOUR_SPACE_SIGNAL;
+
+    // the colour module decodes to LINEAR_REFERENCE_NITS to the unit; a caller that counts in some
+    // other white asks for it here, and pays one multiply a sample for it
+    const linear_scale = LINEAR_REFERENCE_NITS / (options.linear_reference_nits ?? LINEAR_REFERENCE_NITS);
+
+    if (output_bit_depth !== 8 && output_bit_depth !== 10 && output_bit_depth !== 12) {
+        throw new Error(`unsupported output bit depth ${output_bit_depth}`);
+    }
+
+    const upsampling = choose_upsampling(options.chroma_upsampling ?? CHROMA_UPSAMPLING_AUTOMATIC);
+
+    decoder.resize_rows(width);
+
+    const transform = decoder.transform;
+
+    // a monochrome image has no matrix to speak of: neutral chroma through any of them is grey,
+    // and going through one keeps the range handling in a single place
+    colour_transform_init(
+        transform,
+        image.num_planes === 1 ? MC_BT_601 : image.matrix_coefficients,
+        image.color_primaries,
+        image.color_range,
+        image.bit_depth
+    );
+
+    const cb_row = decoder.cb_row;
+    const cr_row = decoder.cr_row;
+    const rgb_row = decoder.rgb_row;
+
+    if (image.num_planes === 1) {
+        cb_row.fill(transform.c_offset, 0, width);
+        cr_row.fill(transform.c_offset, 0, width);
+    }
+
+    const samples = width * height * 4;
+
+    const data = output_float16 || output_bit_depth > 8
+        ? new Uint16Array(samples)
+        : new Uint8ClampedArray(samples);
+
+    const maximum = (1 << output_bit_depth) - 1;
+
+    const alpha_scale = alpha_normalisation(image);
+    const alpha_offset = image.alpha_range === 1 ? 0 : 16 << (image.alpha_bit_depth - 8);
+
+    const chroma_width = (image.width + image.subsampling_x) >> image.subsampling_x;
+    const chroma_height = (image.height + image.subsampling_y) >> image.subsampling_y;
+
+    for (let y = 0; y < height; y++) {
+        if (image.num_planes > 1) {
+            upsample_chroma_row(
+                image.planes[1], image.stride[1], chroma_width, chroma_height,
+                image.subsampling_x, image.subsampling_y, y, width, upsampling, cb_row
+            );
+
+            upsample_chroma_row(
+                image.planes[2], image.stride[2], chroma_width, chroma_height,
+                image.subsampling_x, image.subsampling_y, y, width, upsampling, cr_row
+            );
+        }
+
+        ycbcr_row_to_rgb(transform, image.planes[0], y * image.stride[0], cb_row, cr_row, width, rgb_row);
+
+        if (colour_space === COLOUR_SPACE_LINEAR) {
+            transfer_row_to_linear(image.transfer_characteristics, rgb_row, width);
+
+            if (linear_scale !== 1) {
+                for (let i = 0, count = width * 3; i < count; i++) {
+                    rgb_row[i] *= linear_scale;
+                }
+            }
+        }
+
+        const alpha_row = image.alpha === null ? 0 : y * image.alpha_stride;
+
+        let out = y * width * 4;
+
+        for (let x = 0; x < width; x++) {
+            const i = x * 3;
+
+            const alpha = image.alpha === null
+                ? 1
+                : clamp01((image.alpha[alpha_row + x] - alpha_offset) * alpha_scale);
+
+            if (output_float16) {
+                data[out] = to_half_float_uint16(rgb_row[i]);
+                data[out + 1] = to_half_float_uint16(rgb_row[i + 1]);
+                data[out + 2] = to_half_float_uint16(rgb_row[i + 2]);
+                data[out + 3] = to_half_float_uint16(alpha);
+            } else {
+                data[out] = quantise(rgb_row[i], maximum);
+                data[out + 1] = quantise(rgb_row[i + 1], maximum);
+                data[out + 2] = quantise(rgb_row[i + 2], maximum);
+                data[out + 3] = quantise(alpha, maximum);
+            }
+
+            out += 4;
+        }
+    }
+
+    return { data, width, height };
+}
+
+/**
+ * @param {number} requested
+ * @returns {number} one of the `UPSAMPLE_*` constants
+ */
+function choose_upsampling(requested) {
+    if (requested === CHROMA_UPSAMPLING_FASTEST) {
+        return UPSAMPLE_NEAREST;
+    }
+
+    return UPSAMPLE_BILINEAR;
+}
+
+/**
+ * @param {YuvImage} image
+ * @returns {number}
+ */
+function alpha_normalisation(image) {
+    if (image.alpha === null) {
+        return 1;
+    }
+
+    if (image.alpha_range === 1) {
+        return 1 / ((1 << image.alpha_bit_depth) - 1);
+    }
+
+    return 1 / (219 << (image.alpha_bit_depth - 8));
+}
+
+/**
+ * A normalised `0 .. 1` value as a coded sample of the output depth.
+ * @param {number} value
+ * @param {number} maximum
+ * @returns {number}
+ */
+function quantise(value, maximum) {
+    return clamp_sample(value * maximum, maximum);
+}

package/src/avif/native/api/decode_avif.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Decode an AVIF file to interleaved RGBA.
+ *
+ * Synchronous by design: there is no worker, no WebAssembly and nothing to wait for, so a promise
+ * would only be ceremony. A caller that does not want to block should call this from a worker it
+ * controls, which is the arrangement meep already has for encoding.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @param {object} [options] see {@link convert_to_rgba}, plus `apply_transformations` to honour the
+ *   file's declared orientation — off by default, because the decoder this replaces left it to its
+ *   caller and a caller that already handles orientation would otherwise apply it twice
+ * @param {AvifDecoder} [decoder] pass one back in to decode many images without reallocating
+ * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function decode_avif(buffer: ArrayBuffer | Uint8Array, options?: object, decoder?: AvifDecoder): {
+    data: (Uint8ClampedArray | Uint16Array);
+    width: number;
+    height: number;
+};
+import { AvifDecoder } from "./AvifDecoder.js";
+//# sourceMappingURL=decode_avif.d.ts.map

package/src/avif/native/api/decode_avif.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode_avif.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/api/decode_avif.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;GAgBG;AACH,oCAVW,WAAW,GAAC,UAAU,YACtB,MAAM,YAGN,WAAW,GACT;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAmClF;4BA/D2B,kBAAkB"}