@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/heif/parse_item_property.js

@@ -0,0 +1,243 @@
+import {
+    AuxiliaryTypeProperty,
+    Av1Config,
+    CleanAperture,
+    ColourInformation,
+    ContentColourVolume,
+    ContentLightLevel,
+    ImageMirror,
+    ImageRotation,
+    ImageSpatialExtents,
+    LayerSelector,
+    LayeredImageIndexing,
+    MasteringDisplayColourVolume,
+    OperatingPointSelector,
+    PixelAspectRatio,
+    PixelInformation,
+    UnknownProperty
+} from "./ItemProperty.js";
+import { read_full_box_header } from "../isobmff/read_full_box_header.js";
+
+/**
+ * Parse one item property box into its struct.
+ *
+ * The cursor is positioned at the box payload; `payload_size` is its length. Unrecognised types
+ * are captured verbatim as {@link UnknownProperty} rather than dropped, because property indices
+ * in `ipma` are positional — silently discarding one would renumber every property after it.
+ *
+ * @param {string} type four character box type
+ * @param {ByteCursor} cursor positioned at the payload
+ * @param {number} payload_size
+ * @returns {object} one of the structs in `ItemProperty.js`
+ * @see ISO/IEC 23000-22 section 7.3 "AV1 Image Item Properties"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_item_property(type, cursor, payload_size) {
+    const payload_end = cursor.position + payload_size;
+
+    switch (type) {
+        case "ispe": {
+            const property = new ImageSpatialExtents();
+
+            read_full_box_header(cursor);
+
+            property.width = cursor.u32();
+            property.height = cursor.u32();
+
+            return property;
+        }
+
+        case "pixi": {
+            const property = new PixelInformation();
+
+            read_full_box_header(cursor);
+
+            const channel_count = cursor.u8();
+
+            property.bits_per_channel = new Uint8Array(channel_count);
+
+            for (let i = 0; i < channel_count; i++) {
+                property.bits_per_channel[i] = cursor.u8();
+            }
+
+            return property;
+        }
+
+        case "av1C": {
+            const property = new Av1Config();
+
+            const marker_and_version = cursor.u8();
+
+            if ((marker_and_version & 0x80) === 0) {
+                throw new Error("av1C is missing its marker bit");
+            }
+
+            property.version = marker_and_version & 0x7f;
+
+            const profile_and_level = cursor.u8();
+
+            property.seq_profile = (profile_and_level >> 5) & 0x7;
+            property.seq_level_idx_0 = profile_and_level & 0x1f;
+
+            const flags = cursor.u8();
+
+            property.seq_tier_0 = (flags >> 7) & 1;
+            property.high_bitdepth = (flags >> 6) & 1;
+            property.twelve_bit = (flags >> 5) & 1;
+            property.monochrome = (flags >> 4) & 1;
+            property.chroma_subsampling_x = (flags >> 3) & 1;
+            property.chroma_subsampling_y = (flags >> 2) & 1;
+            property.chroma_sample_position = flags & 0x3;
+
+            const delay = cursor.u8();
+
+            property.initial_presentation_delay_minus_one = (delay & 0x10) !== 0 ? delay & 0x0f : -1;
+
+            property.config_obus = cursor.view_bytes(payload_end - cursor.position);
+
+            return property;
+        }
+
+        case "colr": {
+            const property = new ColourInformation();
+
+            property.colour_type = cursor.fourcc();
+
+            if (property.colour_type === "nclx") {
+                property.colour_primaries = cursor.u16();
+                property.transfer_characteristics = cursor.u16();
+                property.matrix_coefficients = cursor.u16();
+                property.full_range_flag = (cursor.u8() >> 7) & 1;
+            } else {
+                property.icc_profile = cursor.view_bytes(payload_end - cursor.position);
+            }
+
+            return property;
+        }
+
+        case "pasp": {
+            const property = new PixelAspectRatio();
+
+            property.h_spacing = cursor.u32();
+            property.v_spacing = cursor.u32();
+
+            return property;
+        }
+
+        case "clap": {
+            const property = new CleanAperture();
+
+            property.width_numerator = cursor.u32();
+            property.width_denominator = cursor.u32();
+            property.height_numerator = cursor.u32();
+            property.height_denominator = cursor.u32();
+
+            // offsets are signed: the crop is expressed relative to the centre of the image, so a
+            // window left of or above centre needs a negative numerator
+            property.horizontal_offset_numerator = cursor.i32();
+            property.horizontal_offset_denominator = cursor.u32();
+            property.vertical_offset_numerator = cursor.i32();
+            property.vertical_offset_denominator = cursor.u32();
+
+            return property;
+        }
+
+        case "irot": {
+            const property = new ImageRotation();
+
+            property.angle = cursor.u8() & 0x3;
+
+            return property;
+        }
+
+        case "imir": {
+            const property = new ImageMirror();
+
+            property.axis = cursor.u8() & 0x1;
+
+            return property;
+        }
+
+        case "auxC": {
+            const property = new AuxiliaryTypeProperty();
+
+            read_full_box_header(cursor);
+
+            property.aux_type = cursor.utf8_string();
+            property.aux_subtype = cursor.view_bytes(payload_end - cursor.position);
+
+            return property;
+        }
+
+        case "clli": {
+            const property = new ContentLightLevel();
+
+            property.max_content_light_level = cursor.u16();
+            property.max_pic_average_light_level = cursor.u16();
+
+            return property;
+        }
+
+        case "mdcv": {
+            const property = new MasteringDisplayColourVolume();
+
+            for (let i = 0; i < 6; i++) {
+                property.display_primaries[i] = cursor.u16();
+            }
+
+            property.white_point_x = cursor.u16();
+            property.white_point_y = cursor.u16();
+            property.max_display_mastering_luminance = cursor.u32();
+            property.min_display_mastering_luminance = cursor.u32();
+
+            return property;
+        }
+
+        case "cclv": {
+            const property = new ContentColourVolume();
+
+            property.payload = cursor.view_bytes(payload_size);
+
+            return property;
+        }
+
+        case "a1op": {
+            const property = new OperatingPointSelector();
+
+            property.op_index = cursor.u8();
+
+            return property;
+        }
+
+        case "lsel": {
+            const property = new LayerSelector();
+
+            property.layer_id = cursor.u16();
+
+            return property;
+        }
+
+        case "a1lx": {
+            const property = new LayeredImageIndexing();
+
+            const large_size = cursor.u8() & 1;
+
+            for (let i = 0; i < 3; i++) {
+                property.layer_size[i] = large_size ? cursor.u32() : cursor.u16();
+            }
+
+            return property;
+        }
+
+        default: {
+            const property = new UnknownProperty();
+
+            property.type = type;
+            property.payload = cursor.view_bytes(payload_size);
+
+            return property;
+        }
+    }
+}

package/src/avif/native/heif/read_item_data.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Gather an item's bytes.
+ *
+ * A single-extent item stored in the file returns a view onto the file's own buffer with no copy,
+ * which is the overwhelmingly common case and the one worth keeping allocation-free. Multi-extent
+ * items are concatenated, because they have to be.
+ *
+ * Construction method 2 (offsets into another item) is resolved recursively, with a depth limit:
+ * a file can point item A at item B and item B back at item A, and without the limit that is an
+ * infinite recursion driven entirely by untrusted input.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {number} [depth] internal
+ * @returns {Uint8Array}
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_item_data(file: AvifFile, item: AvifItem, depth?: number): Uint8Array;
+//# sourceMappingURL=read_item_data.d.ts.map

package/src/avif/native/heif/read_item_data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_item_data.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/read_item_data.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAPW,MAAM,GACJ,UAAU,CAgDtB"}

package/src/avif/native/heif/read_item_data.js

@@ -0,0 +1,97 @@
+import { ConstructionMethod } from "./AvifFile.js";
+
+/**
+ * Gather an item's bytes.
+ *
+ * A single-extent item stored in the file returns a view onto the file's own buffer with no copy,
+ * which is the overwhelmingly common case and the one worth keeping allocation-free. Multi-extent
+ * items are concatenated, because they have to be.
+ *
+ * Construction method 2 (offsets into another item) is resolved recursively, with a depth limit:
+ * a file can point item A at item B and item B back at item A, and without the limit that is an
+ * infinite recursion driven entirely by untrusted input.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {number} [depth] internal
+ * @returns {Uint8Array}
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_item_data(file, item, depth = 0) {
+    if (depth > 4) {
+        throw new Error(`item ${item.id} is part of a construction method 2 reference cycle`);
+    }
+
+    const source = source_bytes_for(file, item, depth);
+
+    if (item.extents.length === 0) {
+        return source.subarray(0, 0);
+    }
+
+    let total = 0;
+
+    for (let i = 0; i < item.extents.length; i++) {
+        const extent = item.extents[i];
+
+        if (extent.offset < 0 || extent.length < 0 || extent.offset + extent.length > source.length) {
+            throw new Error(`item ${item.id} extent [${extent.offset}, ${extent.offset + extent.length}) is outside its ${source.length} byte source`);
+        }
+
+        total += extent.length;
+    }
+
+    if (item.extents.length === 1) {
+        const extent = item.extents[0];
+
+        return source.subarray(extent.offset, extent.offset + extent.length);
+    }
+
+    const gathered = new Uint8Array(total);
+
+    let written = 0;
+
+    for (let i = 0; i < item.extents.length; i++) {
+        const extent = item.extents[i];
+
+        gathered.set(source.subarray(extent.offset, extent.offset + extent.length), written);
+
+        written += extent.length;
+    }
+
+    return gathered;
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {number} depth
+ * @returns {Uint8Array}
+ */
+function source_bytes_for(file, item, depth) {
+    if (item.construction_method === ConstructionMethod.FILE_OFFSET) {
+        return file.bytes;
+    }
+
+    if (item.construction_method === ConstructionMethod.IDAT_OFFSET) {
+        if (file.item_data === null) {
+            throw new Error(`item ${item.id} refers to idat, but the file has no idat box`);
+        }
+
+        return file.item_data;
+    }
+
+    if (item.construction_method === ConstructionMethod.ITEM_OFFSET) {
+        const target = file.items.get(item.data_reference_index);
+
+        if (target === undefined) {
+            throw new Error(`item ${item.id} refers to item ${item.data_reference_index}, which does not exist`);
+        }
+
+        return read_item_data(file, target, depth + 1);
+    }
+
+    throw new Error(`item ${item.id} uses unsupported construction method ${item.construction_method}`);
+}

package/src/avif/native/heif/write_avif_file.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Assemble an AVIF file from a description of its items.
+ *
+ * ### The offset problem, and how this writer sidesteps it
+ *
+ * `iloc` holds absolute file offsets into `mdat`, and `mdat`'s position depends on the size of the
+ * metadata that precedes it — `iloc` included. Writing the offsets naively makes them wrong by the
+ * size of the difference, and iterating to a fixed point is fiddly because a changed offset can
+ * change the width of the field holding it.
+ *
+ * Fixing the offset fields at 32 bits makes the metadata size independent of the values in them,
+ * so one measure-then-patch pass converges immediately: offsets are written as zeroes, their
+ * positions recorded, the payloads laid out, and the recorded positions patched. The cost is a few
+ * bytes on small files and a 4 GiB ceiling, which the writer checks rather than silently wrapping.
+ *
+ * @param {object} description
+ * @param {string} [description.major_brand]
+ * @param {number} [description.minor_version]
+ * @param {string[]} [description.compatible_brands]
+ * @param {number} description.primary_item_id
+ * @param {Array<{id: number, item_type: string, item_name?: string, content_type?: string, hidden?: boolean, properties?: object[], essential?: boolean[], data: Uint8Array}>} description.items
+ * @param {Array<{from_item_id: number, reference_type: string, to_item_ids: number[]}>} [description.references]
+ * @returns {ArrayBuffer}
+ * @see ISO/IEC 23000-22 section 8 "AVIF file format"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_avif_file(description: {
+    major_brand?: string;
+    minor_version?: number;
+    compatible_brands?: string[];
+    primary_item_id: number;
+    items: {
+        id: number;
+        item_type: string;
+        item_name?: string;
+        content_type?: string;
+        hidden?: boolean;
+        properties?: object[];
+        essential?: boolean[];
+        data: Uint8Array;
+    }[];
+    references?: Array<{
+        from_item_id: number;
+        reference_type: string;
+        to_item_ids: number[];
+    }>;
+}): ArrayBuffer;
+//# sourceMappingURL=write_avif_file.d.ts.map

package/src/avif/native/heif/write_avif_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_avif_file.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/write_avif_file.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;kBAZW,MAAM;oBACN,MAAM;wBACN,MAAM,EAAE;qBACR,MAAM;;YACK,MAAM;mBAAa,MAAM;oBAAc,MAAM;uBAAiB,MAAM;iBAAW,OAAO;qBAAe,MAAM,EAAE;oBAAc,OAAO,EAAE;cAAQ,UAAU;;iBACjK,MAAM;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC;IAC1E,WAAW,CA0CvB"}