@woosh/meep-engine 3.14.0 → 3.14.2

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

@@ -1,383 +1,384 @@
-import { for_each_box } from "../isobmff/for_each_box.js";
-import { ByteCursor } from "../isobmff/ByteCursor.js";
-import { full_box_flags, full_box_version, read_full_box_header } from "../isobmff/read_full_box_header.js";
-import { AvifFile, AvifItem, ItemExtent, ItemReference } from "./AvifFile.js";
-import { parse_item_property } from "./parse_item_property.js";
-
-/**
- * Ceiling on counts read from the file before they are used to size anything. A real AVIF has a
- * handful of items and properties; a count in the millions is corruption, and without a ceiling it
- * becomes a multi-gigabyte allocation or a loop that never ends.
- * @type {number}
- */
-const MAX_ENTRIES = 65536;
-
-/**
- * Parse an AVIF file into its item model.
- *
- * Only structure is read: item payloads are located, not decoded, and their bytes are left in
- * place. Nothing is copied out of `buffer`.
- *
- * @param {ArrayBuffer|Uint8Array} buffer
- * @returns {AvifFile}
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function parse_avif_file(buffer) {
-    const file = new AvifFile();
-
-    const cursor = new ByteCursor().init(buffer);
-
-    file.bytes = cursor.bytes.subarray(0, cursor.end);
-
-    let saw_ftyp = false;
-    let saw_meta = false;
-
-    for_each_box(cursor, (header, box_cursor) => {
-        if (header.type === "ftyp") {
-            read_ftyp(file, box_cursor, header.end);
-
-            saw_ftyp = true;
-        } else if (header.type === "meta") {
-            read_meta(file, box_cursor, header.end);
-
-            saw_meta = true;
-        } else if (header.type === "moov") {
-            file.has_image_sequence = true;
-        }
-    });
-
-    if (!saw_ftyp) {
-        throw new Error("not an ISOBMFF file: no ftyp box");
-    }
-
-    if (!saw_meta) {
-        throw new Error("not an AVIF file: no meta box");
-    }
-
-    resolve_item_offsets(file);
-
-    return file;
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- */
-function read_ftyp(file, cursor, end) {
-    file.major_brand = cursor.fourcc();
-    file.minor_version = cursor.u32();
-
-    while (cursor.position + 4 <= end) {
-        file.compatible_brands.push(cursor.fourcc());
-    }
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- */
-function read_meta(file, cursor, end) {
-    read_full_box_header(cursor);
-
-    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
-
-    for_each_box(children, (header, box_cursor) => {
-        switch (header.type) {
-            case "pitm":
-                read_pitm(file, box_cursor);
-                break;
-            case "iloc":
-                read_iloc(file, box_cursor);
-                break;
-            case "iinf":
-                read_iinf(file, box_cursor, header.end);
-                break;
-            case "iref":
-                read_iref(file, box_cursor, header.end);
-                break;
-            case "iprp":
-                read_iprp(file, box_cursor, header.end);
-                break;
-            case "idat":
-                file.item_data = box_cursor.view_bytes(header.payload_size);
-                break;
-            default:
-                break;
-        }
-    });
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- */
-function read_pitm(file, cursor) {
-    const version = full_box_version(read_full_box_header(cursor));
-
-    file.primary_item_id = version === 0 ? cursor.u16() : cursor.u32();
-}
-
-/**
- * @param {AvifFile} file
- * @param {number} id
- * @returns {AvifItem}
- */
-function item_for_id(file, id) {
-    let item = file.items.get(id);
-
-    if (item === undefined) {
-        item = new AvifItem();
-        item.id = id;
-
-        file.items.set(id, item);
-    }
-
-    return item;
-}
-
-/**
- * @param {number} count
- * @param {string} what
- */
-function check_count(count, what) {
-    if (count > MAX_ENTRIES) {
-        throw new Error(`${what} declares ${count} entries, beyond the ${MAX_ENTRIES} supported`);
-    }
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
- */
-function read_iloc(file, cursor) {
-    const version = full_box_version(read_full_box_header(cursor));
-
-    const sizes = cursor.u8();
-    const offset_size = (sizes >> 4) & 0xf;
-    const length_size = sizes & 0xf;
-
-    const base_and_index = cursor.u8();
-    const base_offset_size = (base_and_index >> 4) & 0xf;
-    const index_size = version === 1 || version === 2 ? base_and_index & 0xf : 0;
-
-    const item_count = version < 2 ? cursor.u16() : cursor.u32();
-
-    check_count(item_count, "iloc");
-
-    for (let i = 0; i < item_count; i++) {
-        const id = version < 2 ? cursor.u16() : cursor.u32();
-
-        const item = item_for_id(file, id);
-
-        if (version === 1 || version === 2) {
-            item.construction_method = cursor.u16() & 0xf;
-        }
-
-        item.data_reference_index = cursor.u16();
-        item.base_offset = cursor.uint_of_size(base_offset_size);
-
-        const extent_count = cursor.u16();
-
-        check_count(extent_count, "iloc extents");
-
-        for (let j = 0; j < extent_count; j++) {
-            if (index_size > 0) {
-                cursor.uint_of_size(index_size);
-            }
-
-            const extent = new ItemExtent();
-
-            extent.offset = cursor.uint_of_size(offset_size);
-            extent.length = cursor.uint_of_size(length_size);
-
-            item.extents.push(extent);
-        }
-    }
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- * @see ISO/IEC 14496-12 section 8.11.6 "Item information box"
- */
-function read_iinf(file, cursor, end) {
-    const version = full_box_version(read_full_box_header(cursor));
-
-    const entry_count = version === 0 ? cursor.u16() : cursor.u32();
-
-    check_count(entry_count, "iinf");
-
-    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
-
-    for_each_box(children, (header, box_cursor) => {
-        if (header.type !== "infe") {
-            return;
-        }
-
-        read_infe(file, box_cursor, header.end);
-    });
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- */
-function read_infe(file, cursor, end) {
-    const version_and_flags = read_full_box_header(cursor);
-    const version = full_box_version(version_and_flags);
-    const flags = full_box_flags(version_and_flags);
-
-    if (version < 2) {
-        // versions 0 and 1 have no item_type field at all, so an item's nature can only be guessed
-        // from its name. No AVIF writer emits them; refusing is better than guessing.
-        throw new Error(`infe version ${version} is not supported by AVIF`);
-    }
-
-    const id = version === 2 ? cursor.u16() : cursor.u32();
-
-    const item = item_for_id(file, id);
-
-    cursor.u16();
-
-    item.item_type = cursor.fourcc();
-    item.item_name = cursor.utf8_string();
-    item.hidden = (flags & 1) !== 0;
-
-    if (item.item_type === "mime" && cursor.position < end) {
-        item.content_type = cursor.utf8_string();
-    } else if (item.item_type === "uri " && cursor.position < end) {
-        item.content_type = cursor.utf8_string();
-    }
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- * @see ISO/IEC 14496-12 section 8.11.12 "Item reference box"
- */
-function read_iref(file, cursor, end) {
-    const version = full_box_version(read_full_box_header(cursor));
-
-    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
-
-    for_each_box(children, (header, box_cursor) => {
-        const reference = new ItemReference();
-
-        reference.reference_type = header.type;
-        reference.from_item_id = version === 0 ? box_cursor.u16() : box_cursor.u32();
-
-        const count = box_cursor.u16();
-
-        check_count(count, "iref");
-
-        for (let i = 0; i < count; i++) {
-            reference.to_item_ids.push(version === 0 ? box_cursor.u16() : box_cursor.u32());
-        }
-
-        file.references.push(reference);
-    });
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- * @see ISO/IEC 23008-12 section 9.3 "Item properties"
- */
-function read_iprp(file, cursor, end) {
-    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
-
-    for_each_box(children, (header, box_cursor) => {
-        if (header.type === "ipco") {
-            read_ipco(file, box_cursor, header.end);
-        } else if (header.type === "ipma") {
-            read_ipma(file, box_cursor);
-        }
-    });
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- * @param {number} end
- */
-function read_ipco(file, cursor, end) {
-    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
-
-    for_each_box(children, (header, box_cursor) => {
-        file.properties.push(parse_item_property(header.type, box_cursor, header.payload_size));
-    });
-}
-
-/**
- * @param {AvifFile} file
- * @param {ByteCursor} cursor
- */
-function read_ipma(file, cursor) {
-    const version_and_flags = read_full_box_header(cursor);
-    const version = full_box_version(version_and_flags);
-    const wide_indices = (full_box_flags(version_and_flags) & 1) !== 0;
-
-    const entry_count = cursor.u32();
-
-    check_count(entry_count, "ipma");
-
-    for (let i = 0; i < entry_count; i++) {
-        const id = version < 1 ? cursor.u16() : cursor.u32();
-
-        const item = item_for_id(file, id);
-
-        const association_count = cursor.u8();
-
-        for (let j = 0; j < association_count; j++) {
-            let essential;
-            let index;
-
-            if (wide_indices) {
-                const packed = cursor.u16();
-
-                essential = (packed & 0x8000) !== 0;
-                index = packed & 0x7fff;
-            } else {
-                const packed = cursor.u8();
-
-                essential = (packed & 0x80) !== 0;
-                index = packed & 0x7f;
-            }
-
-            // index 0 means "no property"; the specification allows it and it must not be treated
-            // as a reference to the first property
-            if (index === 0) {
-                continue;
-            }
-
-            item.property_indices.push(index);
-            item.property_essential.push(essential);
-        }
-    }
-}
-
-/**
- * Fold `base_offset` into each extent, so consumers see absolute offsets and never have to know
- * which of the three construction methods produced them.
- *
- * Method 1 offsets are relative to `idat` and method 2 to another item; both are left in their own
- * space and resolved by {@link read_item_data}, which is the only place that can see the target.
- *
- * @param {AvifFile} file
- */
-function resolve_item_offsets(file) {
-    for (const item of file.items.values()) {
-        for (let i = 0; i < item.extents.length; i++) {
-            item.extents[i].offset += item.base_offset;
-        }
-    }
-}
+import { for_each_box } from "../isobmff/for_each_box.js";
+import { ByteCursor } from "../../../core/binary/ByteCursor.js";
+import { EndianType } from "../../../core/binary/EndianType.js";
+import { full_box_flags, full_box_version, read_full_box_header } from "../isobmff/read_full_box_header.js";
+import { AvifFile, AvifItem, ItemExtent, ItemReference } from "./AvifFile.js";
+import { parse_item_property } from "./parse_item_property.js";
+
+/**
+ * Ceiling on counts read from the file before they are used to size anything. A real AVIF has a
+ * handful of items and properties; a count in the millions is corruption, and without a ceiling it
+ * becomes a multi-gigabyte allocation or a loop that never ends.
+ * @type {number}
+ */
+const MAX_ENTRIES = 65536;
+
+/**
+ * Parse an AVIF file into its item model.
+ *
+ * Only structure is read: item payloads are located, not decoded, and their bytes are left in
+ * place. Nothing is copied out of `buffer`.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @returns {AvifFile}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_avif_file(buffer) {
+    const file = new AvifFile();
+
+    const cursor = new ByteCursor().init(buffer, EndianType.BigEndian);
+
+    file.bytes = cursor.bytes.subarray(0, cursor.end);
+
+    let saw_ftyp = false;
+    let saw_meta = false;
+
+    for_each_box(cursor, (header, box_cursor) => {
+        if (header.type === "ftyp") {
+            read_ftyp(file, box_cursor, header.end);
+
+            saw_ftyp = true;
+        } else if (header.type === "meta") {
+            read_meta(file, box_cursor, header.end);
+
+            saw_meta = true;
+        } else if (header.type === "moov") {
+            file.has_image_sequence = true;
+        }
+    });
+
+    if (!saw_ftyp) {
+        throw new Error("not an ISOBMFF file: no ftyp box");
+    }
+
+    if (!saw_meta) {
+        throw new Error("not an AVIF file: no meta box");
+    }
+
+    resolve_item_offsets(file);
+
+    return file;
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ftyp(file, cursor, end) {
+    file.major_brand = cursor.fourcc();
+    file.minor_version = cursor.u32();
+
+    while (cursor.position + 4 <= end) {
+        file.compatible_brands.push(cursor.fourcc());
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_meta(file, cursor, end) {
+    read_full_box_header(cursor);
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        switch (header.type) {
+            case "pitm":
+                read_pitm(file, box_cursor);
+                break;
+            case "iloc":
+                read_iloc(file, box_cursor);
+                break;
+            case "iinf":
+                read_iinf(file, box_cursor, header.end);
+                break;
+            case "iref":
+                read_iref(file, box_cursor, header.end);
+                break;
+            case "iprp":
+                read_iprp(file, box_cursor, header.end);
+                break;
+            case "idat":
+                file.item_data = box_cursor.view_bytes(header.payload_size);
+                break;
+            default:
+                break;
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_pitm(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    file.primary_item_id = version === 0 ? cursor.u16() : cursor.u32();
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {number} id
+ * @returns {AvifItem}
+ */
+function item_for_id(file, id) {
+    let item = file.items.get(id);
+
+    if (item === undefined) {
+        item = new AvifItem();
+        item.id = id;
+
+        file.items.set(id, item);
+    }
+
+    return item;
+}
+
+/**
+ * @param {number} count
+ * @param {string} what
+ */
+function check_count(count, what) {
+    if (count > MAX_ENTRIES) {
+        throw new Error(`${what} declares ${count} entries, beyond the ${MAX_ENTRIES} supported`);
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ */
+function read_iloc(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const sizes = cursor.u8();
+    const offset_size = (sizes >> 4) & 0xf;
+    const length_size = sizes & 0xf;
+
+    const base_and_index = cursor.u8();
+    const base_offset_size = (base_and_index >> 4) & 0xf;
+    const index_size = version === 1 || version === 2 ? base_and_index & 0xf : 0;
+
+    const item_count = version < 2 ? cursor.u16() : cursor.u32();
+
+    check_count(item_count, "iloc");
+
+    for (let i = 0; i < item_count; i++) {
+        const id = version < 2 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        if (version === 1 || version === 2) {
+            item.construction_method = cursor.u16() & 0xf;
+        }
+
+        item.data_reference_index = cursor.u16();
+        item.base_offset = cursor.uint_of_size(base_offset_size);
+
+        const extent_count = cursor.u16();
+
+        check_count(extent_count, "iloc extents");
+
+        for (let j = 0; j < extent_count; j++) {
+            if (index_size > 0) {
+                cursor.uint_of_size(index_size);
+            }
+
+            const extent = new ItemExtent();
+
+            extent.offset = cursor.uint_of_size(offset_size);
+            extent.length = cursor.uint_of_size(length_size);
+
+            item.extents.push(extent);
+        }
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.6 "Item information box"
+ */
+function read_iinf(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const entry_count = version === 0 ? cursor.u16() : cursor.u32();
+
+    check_count(entry_count, "iinf");
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type !== "infe") {
+            return;
+        }
+
+        read_infe(file, box_cursor, header.end);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_infe(file, cursor, end) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const flags = full_box_flags(version_and_flags);
+
+    if (version < 2) {
+        // versions 0 and 1 have no item_type field at all, so an item's nature can only be guessed
+        // from its name. No AVIF writer emits them; refusing is better than guessing.
+        throw new Error(`infe version ${version} is not supported by AVIF`);
+    }
+
+    const id = version === 2 ? cursor.u16() : cursor.u32();
+
+    const item = item_for_id(file, id);
+
+    cursor.u16();
+
+    item.item_type = cursor.fourcc();
+    item.item_name = cursor.utf8_string();
+    item.hidden = (flags & 1) !== 0;
+
+    if (item.item_type === "mime" && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    } else if (item.item_type === "uri " && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.12 "Item reference box"
+ */
+function read_iref(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        const reference = new ItemReference();
+
+        reference.reference_type = header.type;
+        reference.from_item_id = version === 0 ? box_cursor.u16() : box_cursor.u32();
+
+        const count = box_cursor.u16();
+
+        check_count(count, "iref");
+
+        for (let i = 0; i < count; i++) {
+            reference.to_item_ids.push(version === 0 ? box_cursor.u16() : box_cursor.u32());
+        }
+
+        file.references.push(reference);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 23008-12 section 9.3 "Item properties"
+ */
+function read_iprp(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type === "ipco") {
+            read_ipco(file, box_cursor, header.end);
+        } else if (header.type === "ipma") {
+            read_ipma(file, box_cursor);
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ipco(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        file.properties.push(parse_item_property(header.type, box_cursor, header.payload_size));
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_ipma(file, cursor) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const wide_indices = (full_box_flags(version_and_flags) & 1) !== 0;
+
+    const entry_count = cursor.u32();
+
+    check_count(entry_count, "ipma");
+
+    for (let i = 0; i < entry_count; i++) {
+        const id = version < 1 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        const association_count = cursor.u8();
+
+        for (let j = 0; j < association_count; j++) {
+            let essential;
+            let index;
+
+            if (wide_indices) {
+                const packed = cursor.u16();
+
+                essential = (packed & 0x8000) !== 0;
+                index = packed & 0x7fff;
+            } else {
+                const packed = cursor.u8();
+
+                essential = (packed & 0x80) !== 0;
+                index = packed & 0x7f;
+            }
+
+            // index 0 means "no property"; the specification allows it and it must not be treated
+            // as a reference to the first property
+            if (index === 0) {
+                continue;
+            }
+
+            item.property_indices.push(index);
+            item.property_essential.push(essential);
+        }
+    }
+}
+
+/**
+ * Fold `base_offset` into each extent, so consumers see absolute offsets and never have to know
+ * which of the three construction methods produced them.
+ *
+ * Method 1 offsets are relative to `idat` and method 2 to another item; both are left in their own
+ * space and resolved by {@link read_item_data}, which is the only place that can see the target.
+ *
+ * @param {AvifFile} file
+ */
+function resolve_item_offsets(file) {
+    for (const item of file.items.values()) {
+        for (let i = 0; i < item.extents.length; i++) {
+            item.extents[i].offset += item.base_offset;
+        }
+    }
+}