@woosh/meep-engine 3.14.2 → 3.14.4

package/src/format/scene/gltf/gltf_read_accessor.js

@@ -0,0 +1,294 @@
+import { assert } from "../../../core/assert.js";
+import {
+    GLTF_COMPONENT_TYPE,
+    gltf_array_type_for_component_type,
+    gltf_column_count_for_type,
+    gltf_column_stride_for_type,
+    gltf_component_count_for_type,
+    gltf_component_type_is_signed,
+    gltf_element_size_for_type,
+    gltf_normalized_divisor,
+    gltf_read_component,
+    gltf_size_for_component_type,
+} from "./gltf_component_type.js";
+
+/**
+ * Reading one accessor — the whole of how a glTF says where its numbers are.
+ *
+ * An accessor is a typed window onto a bufferView, and the format lets that window be laid out three
+ * ways at once: it may skip bytes between elements (an interleaved vertex buffer), it may name no
+ * view at all (an all-zero accessor), and it may carry a sparse overlay that substitutes individual
+ * elements. All three are the same read, and doing them in one place is what keeps a caller from
+ * implementing two of them and throwing on the third. A fourth layout hides *inside* an element: a
+ * matrix pads its columns out to 4-byte boundaries, so a `MAT3` of bytes is 12 bytes carrying 9
+ * components, and reading one as a flat run hands back three pad bytes as numbers.
+ *
+ * What comes back is always a **fresh, tightly packed** array. A view onto the container's own bytes
+ * would be cheaper by one copy, and would keep the entire file resident for as long as any geometry
+ * built from it lives; it would also inherit whatever alignment the container happened to have, and
+ * a `Uint16Array` cannot be laid over an odd byte offset at all — which a buffer read off a
+ * filesystem regularly is.
+ *
+ * A **resolved glTF** — what every function here takes — is the container's JSON with `buffers`
+ * replaced by the bytes they resolved to. That is the shape {@link TinyGltf} hands out and the shape
+ * the virtual-geometry builder's reader hands out, so anything that reads geometry works with either.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * One accessor's values, decoded out of whatever layout held them.
+ */
+export class GltfAccessorData {
+    /**
+     * `count * components` numbers of the accessor's own component type, tightly packed — a matrix's
+     * column padding is not among them.
+     * @type {TypedArray}
+     */
+    values = new Float32Array(0);
+
+    /**
+     * @type {number}
+     */
+    components = 0;
+
+    /**
+     * @type {GLTF_COMPONENT_TYPE}
+     */
+    component_type = GLTF_COMPONENT_TYPE.FLOAT;
+
+    /**
+     * Elements, as distinct from numbers.
+     * @type {number}
+     */
+    count = 0;
+
+    /**
+     * Whether the integers above are a fixed-point encoding of `[0, 1]` or `[-1, 1]`.
+     * @type {boolean}
+     */
+    normalized = false;
+}
+
+/**
+ * Copy `count` elements out of a bufferView into a fresh packed array.
+ *
+ * Column by column rather than component by component, because a column is the granularity the
+ * format places things at: a matrix element is column-major with every column starting on a 4-byte
+ * boundary, and the bytes that buys it belong to no component. A scalar or a vector is one column,
+ * and walks the same two loops.
+ *
+ * Only components are ever read, never the padding behind one, which is also what lets an element
+ * whose trailing pad the file left off — permitted at the end of a buffer — read like any other.
+ *
+ * @param {object} gltf resolved
+ * @param {number} view_index into `gltf.bufferViews`
+ * @param {number} byte_offset of the first element, from the start of the view
+ * @param {string} type the accessor type name whose layout is being read
+ * @param {GLTF_COMPONENT_TYPE} component_type
+ * @param {number} count elements
+ * @param {number} stride bytes from one element to the next
+ * @returns {TypedArray} `count * components` values, tightly packed
+ */
+function read_elements(gltf, view_index, byte_offset, type, component_type, count, stride) {
+    const view = gltf.bufferViews[view_index];
+
+    const buffer = gltf.buffers[view.buffer];
+
+    const source = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+
+    const component_size = gltf_size_for_component_type(component_type);
+
+    const base = (view.byteOffset ?? 0) + byte_offset;
+
+    const ArrayType = gltf_array_type_for_component_type(component_type);
+
+    const components = gltf_component_count_for_type(type);
+
+    const columns = gltf_column_count_for_type(type);
+
+    const rows = components / columns;
+
+    const column_stride = gltf_column_stride_for_type(type, component_type);
+
+    const result = new ArrayType(count * components);
+
+    for (let element = 0; element < count; element++) {
+        const element_base = base + element * stride;
+
+        for (let column = 0; column < columns; column++) {
+            const column_base = element_base + column * column_stride;
+
+            const target = element * components + column * rows;
+
+            for (let row = 0; row < rows; row++) {
+                result[target + row] = gltf_read_component(
+                    source,
+                    column_base + row * component_size,
+                    component_type
+                );
+            }
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Overlay a sparse accessor's substituted values, per glTF 2.0 §3.6.2.3.
+ *
+ * `sparse.indices` names the elements to replace — scalars, strictly increasing — and `sparse.values`
+ * carries their replacements in the accessor's own type. Neither sub-view may declare a stride, so
+ * both are read packed — as tightly as the *type* packs, which for a matrix still leaves its columns
+ * on 4-byte boundaries: a replacement element is laid out the way the elements it replaces are.
+ *
+ * @param {object} gltf resolved
+ * @param {object} sparse the accessor's `sparse` object
+ * @param {TypedArray} target the accessor's values, mutated in place
+ * @param {string} type of the accessor
+ * @param {GLTF_COMPONENT_TYPE} component_type of the accessor
+ */
+function apply_sparse(gltf, sparse, target, type, component_type) {
+    const count = sparse.count;
+
+    assert.isNonNegativeInteger(count, 'sparse.count');
+
+    const components = gltf_component_count_for_type(type);
+
+    const index_component_type = sparse.indices.componentType;
+
+    const indices = read_elements(
+        gltf,
+        sparse.indices.bufferView,
+        sparse.indices.byteOffset ?? 0,
+        'SCALAR',
+        index_component_type,
+        count,
+        gltf_size_for_component_type(index_component_type)
+    );
+
+    const values = read_elements(
+        gltf,
+        sparse.values.bufferView,
+        sparse.values.byteOffset ?? 0,
+        type,
+        component_type,
+        count,
+        gltf_element_size_for_type(type, component_type)
+    );
+
+    const element_count = target.length / components;
+
+    for (let i = 0; i < count; i++) {
+        const element = indices[i];
+
+        assert.lessThan(element, element_count, 'sparse element index');
+
+        const target_address = element * components;
+        const source_address = i * components;
+
+        for (let component = 0; component < components; component++) {
+            target[target_address + component] = values[source_address + component];
+        }
+    }
+}
+
+/**
+ * Read one accessor.
+ *
+ * @param {object} gltf resolved
+ * @param {number} accessor_index into `gltf.accessors`
+ * @returns {GltfAccessorData}
+ */
+export function gltf_read_accessor(gltf, accessor_index) {
+    assert.isNonNegativeInteger(accessor_index, 'accessor_index');
+
+    const accessor = gltf.accessors[accessor_index];
+
+    const components = gltf_component_count_for_type(accessor.type);
+
+    assert.greaterThan(components, 0, `accessor ${accessor_index} has unknown type '${accessor.type}'`);
+
+    const component_type = accessor.componentType;
+    const count = accessor.count;
+
+    assert.isNonNegativeInteger(count, `accessor ${accessor_index} count`);
+
+    const result = new GltfAccessorData();
+
+    result.components = components;
+    result.component_type = component_type;
+    result.count = count;
+    result.normalized = accessor.normalized === true;
+
+    if (accessor.bufferView === undefined) {
+        /*
+         An accessor naming no view reads as zeroes, which is what a fresh typed array already holds.
+         Only meaningful together with `sparse`, which substitutes into it below.
+        */
+        const ArrayType = gltf_array_type_for_component_type(component_type);
+
+        result.values = new ArrayType(count * components);
+    } else {
+        const element_size = gltf_element_size_for_type(accessor.type, component_type);
+
+        const stride = gltf.bufferViews[accessor.bufferView].byteStride ?? element_size;
+
+        result.values = read_elements(
+            gltf,
+            accessor.bufferView,
+            accessor.byteOffset ?? 0,
+            accessor.type,
+            component_type,
+            count,
+            stride
+        );
+    }
+
+    if (accessor.sparse !== undefined) {
+        apply_sparse(gltf, accessor.sparse, result.values, accessor.type, component_type);
+    }
+
+    return result;
+}
+
+/**
+ * The same values as float32, decoding glTF's fixed-point rule for a normalized integer accessor.
+ *
+ * @param {GltfAccessorData} accessor
+ * @returns {Float32Array}
+ * @throws {Error} for a normalized accessor whose component type carries no such encoding
+ */
+export function gltf_accessor_to_float32(accessor) {
+    const values = accessor.values;
+
+    const result = new Float32Array(values.length);
+
+    if (!accessor.normalized) {
+        result.set(values);
+
+        return result;
+    }
+
+    const divisor = gltf_normalized_divisor(accessor.component_type);
+
+    if (divisor === 0) {
+        throw new Error(`component type ${accessor.component_type} cannot be normalized`);
+    }
+
+    if (!gltf_component_type_is_signed(accessor.component_type)) {
+        for (let i = 0; i < values.length; i++) {
+            result[i] = values[i] / divisor;
+        }
+
+        return result;
+    }
+
+    // The most negative storage value divides to just under -1, which the format clamps away.
+    for (let i = 0; i < values.length; i++) {
+        result[i] = Math.max(-1, values[i] / divisor);
+    }
+
+    return result;
+}

package/src/format/scene/gltf/gltf_used_image_indices.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Which images are KTX2 containers, because a texture reaches them through `KHR_texture_basisu`.
+ *
+ * **The extension is the authority, not the MIME type.** `KHR_texture_basisu` *permits* an image
+ * referenced by URI to declare `image/ktx2` and only *requires* it inside a GLB, where the image
+ * comes from a bufferView. So a perfectly ordinary `.gltf` may say no more than
+ * `{"uri": "wood.ktx2"}` — and a loader that went by MIME type alone would hand that to
+ * `createImageBitmap`, which is the exact failure the note at the top of this file is about.
+ *
+ * Every image the extension names is a KTX2 container by definition of the extension, whatever else
+ * the file does or does not say about it.
+ *
+ * @param {object} json parsed glTF
+ * @returns {Set<number>} image indices, empty when no texture uses the extension
+ */
+export function gltf_basisu_image_indices(json: object): Set<number>;
+/**
+ * Which image a texture will be sampled from.
+ *
+ * @param {object} texture a `textures` entry
+ * @returns {number|undefined} an index into `images`, or `undefined` for a texture naming none
+ */
+export function gltf_texture_image_index(texture: object): number | undefined;
+/**
+ * Which of a glTF's images will actually be sampled.
+ *
+ * A texture may name several images for one slot — `source` plus an extension offering the same
+ * picture in another container — and a loader uses exactly one of them. Decoding the others is not
+ * merely wasted work: a container the browser cannot decode makes `createImageBitmap` reject, and an
+ * image nothing was ever going to sample takes the whole model down with it.
+ *
+ * Which is not hypothetical. The game's level models are authored with an `MSFT_texture_dds`
+ * extension beside every PNG, so each `textures` entry reads
+ *
+ *     { "source": 0, "extensions": { "MSFT_texture_dds": { "source": 1 } } }
+ *
+ * and image 1 is a DDS. DDS was dropped from the engine in this migration; nothing selects it, and
+ * decoding it anyway meant **not one model in the level loaded**.
+ *
+ * **This must agree with how `load_gltf` resolves a texture's source.** The two are the same decision
+ * asked twice — once to know what to fetch, once to know what to use — and a loader that decodes one
+ * set and samples another is back where it started. So both ask
+ * {@link gltf_texture_image_index}, and neither writes the rule out for itself: that is what the
+ * incident above cost, and one shared function is the only arrangement in which the two cannot drift
+ * apart again.
+ *
+ * @param {object} json parsed glTF
+ * @returns {Set<number>} image indices, empty when the file has no textures
+ */
+export function gltf_used_image_indices(json: object): Set<number>;
+//# sourceMappingURL=gltf_used_image_indices.d.ts.map

package/src/format/scene/gltf/gltf_used_image_indices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gltf_used_image_indices.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/gltf/gltf_used_image_indices.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;GAcG;AACH,gDAHW,MAAM,GACJ,IAAI,MAAM,CAAC,CAcvB;AAED;;;;;GAKG;AACH,kDAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAgB5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,8CAHW,MAAM,GACJ,IAAI,MAAM,CAAC,CAuBvB"}

package/src/format/scene/gltf/gltf_used_image_indices.js

@@ -0,0 +1,122 @@
+/**
+ * The order this loader prefers a texture's images in, best first.
+ *
+ * **`KHR_texture_basisu` before `EXT_texture_webp` before `source`.** A KTX2/Basis payload is the one
+ * the GPU can hold compressed — it is transcoded to a block format and stays that way, at a quarter
+ * of the memory of the decoded WebP or PNG beside it — so where a file offers it, it is the one to
+ * take even though it costs transcode time on load. The other two both decode to an `ImageBitmap`
+ * and differ only in how well they compressed on the wire, which is already spent by the time the
+ * bytes are here.
+ *
+ * @readonly
+ * @type {string[]}
+ */
+const EXTENSION_PREFERENCE = ["KHR_texture_basisu", "EXT_texture_webp"];
+
+/**
+ * The extension whose images are KTX2 containers.
+ *
+ * @readonly
+ * @type {string}
+ */
+const BASISU_EXTENSION = "KHR_texture_basisu";
+
+/**
+ * Which images are KTX2 containers, because a texture reaches them through `KHR_texture_basisu`.
+ *
+ * **The extension is the authority, not the MIME type.** `KHR_texture_basisu` *permits* an image
+ * referenced by URI to declare `image/ktx2` and only *requires* it inside a GLB, where the image
+ * comes from a bufferView. So a perfectly ordinary `.gltf` may say no more than
+ * `{"uri": "wood.ktx2"}` — and a loader that went by MIME type alone would hand that to
+ * `createImageBitmap`, which is the exact failure the note at the top of this file is about.
+ *
+ * Every image the extension names is a KTX2 container by definition of the extension, whatever else
+ * the file does or does not say about it.
+ *
+ * @param {object} json parsed glTF
+ * @returns {Set<number>} image indices, empty when no texture uses the extension
+ */
+export function gltf_basisu_image_indices(json) {
+    const result = new Set();
+
+    for (const texture of json.textures ?? []) {
+        const source = texture.extensions?.[BASISU_EXTENSION]?.source;
+
+        if (source !== undefined) {
+            result.add(source);
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Which image a texture will be sampled from.
+ *
+ * @param {object} texture a `textures` entry
+ * @returns {number|undefined} an index into `images`, or `undefined` for a texture naming none
+ */
+export function gltf_texture_image_index(texture) {
+    const extensions = texture.extensions;
+
+    if (extensions !== undefined) {
+        for (const name of EXTENSION_PREFERENCE) {
+            const source = extensions[name]?.source;
+
+            if (source !== undefined) {
+                return source;
+            }
+        }
+    }
+
+    return texture.source;
+}
+
+/**
+ * Which of a glTF's images will actually be sampled.
+ *
+ * A texture may name several images for one slot — `source` plus an extension offering the same
+ * picture in another container — and a loader uses exactly one of them. Decoding the others is not
+ * merely wasted work: a container the browser cannot decode makes `createImageBitmap` reject, and an
+ * image nothing was ever going to sample takes the whole model down with it.
+ *
+ * Which is not hypothetical. The game's level models are authored with an `MSFT_texture_dds`
+ * extension beside every PNG, so each `textures` entry reads
+ *
+ *     { "source": 0, "extensions": { "MSFT_texture_dds": { "source": 1 } } }
+ *
+ * and image 1 is a DDS. DDS was dropped from the engine in this migration; nothing selects it, and
+ * decoding it anyway meant **not one model in the level loaded**.
+ *
+ * **This must agree with how `load_gltf` resolves a texture's source.** The two are the same decision
+ * asked twice — once to know what to fetch, once to know what to use — and a loader that decodes one
+ * set and samples another is back where it started. So both ask
+ * {@link gltf_texture_image_index}, and neither writes the rule out for itself: that is what the
+ * incident above cost, and one shared function is the only arrangement in which the two cannot drift
+ * apart again.
+ *
+ * @param {object} json parsed glTF
+ * @returns {Set<number>} image indices, empty when the file has no textures
+ */
+export function gltf_used_image_indices(json) {
+    const result = new Set();
+
+    const textures = json.textures;
+
+    if (textures === undefined) {
+        return result;
+    }
+
+    for (let i = 0; i < textures.length; i++) {
+        const source = gltf_texture_image_index(textures[i]);
+
+        if (source === undefined) {
+            // a texture naming no image at all; nothing to fetch for it
+            continue;
+        }
+
+        result.add(source);
+    }
+
+    return result;
+}

package/src/format/scene/usd/UsdError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UsdError.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/UsdError.js"],"names":[],"mappings":"AAAA;;GAEG;AACH;IAEI;;;;;OAKG;IACH,qBALW,MAAM;QAEW,OAAO,GAAxB,MAAM;QACW,MAAM,GAAvB,MAAM;OAMhB;IADG;kBANO,MAAM;iBACN,MAAM;MAKe;CAEnC;AAGD;;GAEG;AACH;IAEI;;OAEG;IACH,qBAFW,MAAM,EAMhB;IADG,gBAAsB;CAE7B"}

package/src/format/scene/usd/parse_usda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_usda.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/parse_usda.js"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,iCAJW,MAAM,GACJ;IAAE,WAAW;YAAU,MAAM,GAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,MAAQ;SAAE;MAAC;CAAE,CAsBlF"}

package/src/format/scene/usd/unpack_usdz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unpack_usdz.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/unpack_usdz.js"],"names":[],"mappings":"AA4BA;;;;;;;;GAQG;AACH,0CANW,WAAW;WACA,IAAI,MAAM,EAAE,UAAU,CAAC;kBAAgB,MAAM;EAyElE"}

package/src/format/scene/usd/unpack_usdz.js

@@ -0,0 +1,106 @@
+/**
+ * USDZ (zip container) unpacker.
+ *
+ * USDZ is a zero-compression ZIP archive containing one or more USD files
+ * plus optional ancillary assets (textures, audio).
+ *
+ * @see https://openusd.org/release/spec_usdz.html — USDZ File Format Specification
+ *
+ * Key constraints from the spec:
+ * - All files are stored with compression method 0 (uncompressed / "stored")
+ * - Files must be aligned to 64-byte boundaries within the archive
+ * - The first file must be a USD layer (.usda, .usdc, or .usd)
+ *
+ * @module unpack_usdz
+ */
+
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { UsdParseError } from "./UsdError.js";
+
+
+/**
+ * ZIP local file header signature.
+ * @see https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT — Section 4.3.7
+ * @type {number}
+ */
+const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+
+
+/**
+ * Unpack a USDZ archive into a map of filename → Uint8Array.
+ *
+ * @param {ArrayBuffer} array_buffer - Raw USDZ file bytes
+ * @returns {{ files: Map<string, Uint8Array>, rootFileName: string }}
+ *   - `files`: Map of all archive entries
+ *   - `rootFileName`: Name of the first USD file (the root layer)
+ * @throws {UsdParseError} If the archive is malformed or uses compression
+ */
+export function unpack_usdz(array_buffer) {
+
+    const buffer = new BinaryBuffer();
+    buffer.fromArrayBuffer(array_buffer);
+
+    const raw_bytes = buffer.raw_bytes;
+    const files = new Map();
+
+    let root_file_name = "";
+
+    while (buffer.position < buffer.capacity) {
+
+        // Read local file header signature
+        if (buffer.position + 4 > buffer.capacity) break;
+
+        const signature = buffer.readUint32();
+
+        if (signature !== ZIP_LOCAL_FILE_HEADER_SIGNATURE) {
+            // We've reached the central directory or end-of-archive marker
+            break;
+        }
+
+        // @see APPNOTE.TXT Section 4.3.7 — Local file header layout
+        // Skip: version(2) + flags(2)
+        buffer.skip(4);
+
+        const compression_method = buffer.readUint16();
+
+        // Skip: modTime(2) + modDate(2) + crc32(4)
+        buffer.skip(8);
+
+        const compressed_size = buffer.readUint32();
+        const uncompressed_size = buffer.readUint32();
+        const filename_length = buffer.readUint16();
+        const extra_length = buffer.readUint16();
+
+        const filename = buffer.readASCIICharacters(filename_length);
+
+        // Skip extra field
+        buffer.skip(extra_length);
+
+        if (compression_method !== 0) {
+            throw new UsdParseError(
+                `USDZ requires uncompressed entries, but "${filename}" uses method ${compression_method}`,
+                { section: "unpack_usdz", offset: buffer.position }
+            );
+        }
+
+        // Extract file data as a view into the original buffer
+        const data_start = buffer.position;
+        const file_data = new Uint8Array(array_buffer, data_start, uncompressed_size);
+
+        files.set(filename, file_data);
+
+        // First file is the root layer per the USDZ spec
+        if (root_file_name === "") {
+            root_file_name = filename;
+        }
+
+        // Advance past the file data
+        buffer.position = data_start + compressed_size;
+    }
+
+    if (root_file_name === "") {
+        throw new UsdParseError("Empty USDZ archive — no files found", { section: "unpack_usdz" });
+    }
+
+    return { files, rootFileName: root_file_name };
+}

package/src/format/scene/usd/usd_compose_transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usd_compose_transform.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/usd_compose_transform.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;GAYG;AACH,kFAHW,MAAM,GACJ,YAAY,CA0BxB"}