@driftengine/drft 3.61.0

package/dist/drftSkin.js

@@ -0,0 +1,270 @@
+import { align, DrftError } from './drftFormat.js';
+/** i32 parent, 3 floats, 4 floats, 3 floats, i32 mesh. */
+const NODE_ENTRY_BYTES = 4 + 12 + 16 + 12 + 4;
+/** u32 joint, u32 path, u32 keyCount. */
+const TRACK_ENTRY_BYTES = 12;
+const PATHS = ['translation', 'rotation', 'scale'];
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** Length-prefixed and padded to four, so the block that follows a name stays aligned. */
+function encodeString(value) {
+    const text = encoder.encode(value);
+    const bytes = new Uint8Array(align(4 + text.length));
+    new DataView(bytes.buffer).setUint32(0, text.length, true);
+    bytes.set(text, 4);
+    return bytes;
+}
+/** Reads one, and answers where the next begins. */
+function decodeString(view, at) {
+    const length = view.getUint32(at, true);
+    const start = view.byteOffset + at + 4;
+    if (start + length > view.byteOffset + view.byteLength) {
+        throw new DrftError('a name runs past the end of its chunk');
+    }
+    return {
+        value: decoder.decode(new Uint8Array(view.buffer, start, length)),
+        next: at + align(4 + length),
+    };
+}
+/* --- NODE --- */
+export function buildNodes(nodes) {
+    const names = nodes.map((node) => encodeString(node.name));
+    let nameBytes = 0;
+    for (const name of names)
+        nameBytes += name.length;
+    const bytes = new Uint8Array(align(8 + nodes.length * NODE_ENTRY_BYTES + nameBytes));
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, nodes.length, true);
+    view.setUint32(4, NODE_ENTRY_BYTES, true);
+    let at = 8;
+    for (const node of nodes) {
+        view.setInt32(at, node.parent, true);
+        for (let c = 0; c < 3; c++)
+            view.setFloat32(at + 4 + c * 4, node.translation[c], true);
+        for (let c = 0; c < 4; c++)
+            view.setFloat32(at + 16 + c * 4, node.rotation[c], true);
+        for (let c = 0; c < 3; c++)
+            view.setFloat32(at + 32 + c * 4, node.scale[c], true);
+        view.setInt32(at + 44, node.mesh, true);
+        at += NODE_ENTRY_BYTES;
+    }
+    for (const name of names) {
+        bytes.set(name, at);
+        at += name.length;
+    }
+    return bytes;
+}
+export function readNodes(buffer, offset, byteLength) {
+    if (byteLength < 8)
+        throw new DrftError('NODE is too short to hold its header');
+    const view = new DataView(buffer, offset, byteLength);
+    const count = view.getUint32(0, true);
+    /*
+     * The stride is read rather than assumed, exactly as `MATL` reads its own: a later minor version
+     * may widen an entry, and a reader that assumed the old width would walk into the middle of the
+     * next one and produce a hierarchy of noise rather than a refusal.
+     */
+    const stride = view.getUint32(4, true);
+    if (stride < NODE_ENTRY_BYTES) {
+        throw new DrftError(`NODE entry stride ${stride} is shorter than this reader's ${NODE_ENTRY_BYTES}`);
+    }
+    if (8 + count * stride > byteLength)
+        throw new DrftError('NODE names more nodes than it holds');
+    const nodes = [];
+    let namesAt = 8 + count * stride;
+    for (let i = 0; i < count; i++) {
+        const at = 8 + i * stride;
+        const name = decodeString(view, namesAt);
+        namesAt = name.next;
+        nodes.push({
+            parent: view.getInt32(at, true),
+            translation: [
+                view.getFloat32(at + 4, true),
+                view.getFloat32(at + 8, true),
+                view.getFloat32(at + 12, true),
+            ],
+            rotation: [
+                view.getFloat32(at + 16, true),
+                view.getFloat32(at + 20, true),
+                view.getFloat32(at + 24, true),
+                view.getFloat32(at + 28, true),
+            ],
+            scale: [
+                view.getFloat32(at + 32, true),
+                view.getFloat32(at + 36, true),
+                view.getFloat32(at + 40, true),
+            ],
+            mesh: view.getInt32(at + 44, true),
+            name: name.value,
+        });
+    }
+    return nodes;
+}
+/* --- SKIN --- */
+export function buildSkin(skin) {
+    const count = skin.joints.length;
+    if (skin.inverseBind.length !== count * 16) {
+        throw new DrftError(`SKIN: ${count} joints but ${skin.inverseBind.length} inverse-bind floats; expected ${count * 16}`);
+    }
+    const names = skin.joints.map((joint) => encodeString(joint.name));
+    let nameBytes = 0;
+    for (const name of names)
+        nameBytes += name.length;
+    const parentsAt = 8;
+    const matricesAt = parentsAt + count * 4;
+    const namesStart = matricesAt + count * 64;
+    const bytes = new Uint8Array(align(namesStart + nameBytes));
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, count, true);
+    /* Reserved, and it must be ignored on read — rule 6 of §4.4, so it can become a field later. */
+    view.setUint32(4, 0, true);
+    skin.joints.forEach((joint, i) => view.setInt32(parentsAt + i * 4, joint.parent, true));
+    for (let f = 0; f < count * 16; f++) {
+        view.setFloat32(matricesAt + f * 4, skin.inverseBind[f], true);
+    }
+    let at = namesStart;
+    for (const name of names) {
+        bytes.set(name, at);
+        at += name.length;
+    }
+    return bytes;
+}
+export function readSkin(buffer, offset, byteLength) {
+    if (byteLength < 8)
+        throw new DrftError('SKIN is too short to hold its header');
+    const view = new DataView(buffer, offset, byteLength);
+    const count = view.getUint32(0, true);
+    const parentsAt = 8;
+    const matricesAt = parentsAt + count * 4;
+    const namesStart = matricesAt + count * 64;
+    if (namesStart > byteLength)
+        throw new DrftError('SKIN names more joints than it holds');
+    const inverseBind = new Float32Array(count * 16);
+    for (let f = 0; f < count * 16; f++)
+        inverseBind[f] = view.getFloat32(matricesAt + f * 4, true);
+    const joints = [];
+    let namesAt = namesStart;
+    for (let i = 0; i < count; i++) {
+        const name = decodeString(view, namesAt);
+        namesAt = name.next;
+        const parent = view.getInt32(parentsAt + i * 4, true);
+        /*
+         * Checked on the way in rather than trusted. A palette is resolved in index order, so a joint
+         * whose parent is not already resolved produces a rig wrong in one limb — which reads as a bad
+         * animation rather than as a bad file, and is exactly the failure a reader can turn loud.
+         */
+        if (parent >= i) {
+            throw new DrftError(`SKIN: joint ${i} ("${name.value}") names parent ${parent}, which is not before it. ` +
+                `Joints are written parents-first.`);
+        }
+        joints.push({ parent, name: name.value });
+    }
+    return { joints, inverseBind };
+}
+/* --- ANIM --- */
+export function buildClip(clip) {
+    const name = encodeString(clip.name);
+    const tracks = clip.tracks;
+    let floats = 0;
+    for (const track of tracks)
+        floats += track.times.length + track.values.length;
+    const headerAt = 16 + name.length;
+    const dataAt = headerAt + tracks.length * TRACK_ENTRY_BYTES;
+    const bytes = new Uint8Array(align(dataAt + floats * 4));
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, tracks.length, true);
+    view.setFloat32(4, clip.durationSec, true);
+    view.setUint32(8, name.length, true);
+    view.setUint32(12, 0, true);
+    bytes.set(name, 16);
+    let at = headerAt;
+    let data = dataAt;
+    for (const track of tracks) {
+        const path = PATHS.indexOf(track.path);
+        if (path < 0)
+            throw new DrftError(`ANIM: unknown track path "${track.path}"`);
+        view.setUint32(at, track.joint, true);
+        view.setUint32(at + 4, path, true);
+        view.setUint32(at + 8, track.times.length, true);
+        at += TRACK_ENTRY_BYTES;
+        for (const value of track.times) {
+            view.setFloat32(data, value, true);
+            data += 4;
+        }
+        for (const value of track.values) {
+            view.setFloat32(data, value, true);
+            data += 4;
+        }
+    }
+    return bytes;
+}
+export function readClip(buffer, offset, byteLength) {
+    if (byteLength < 16)
+        throw new DrftError('ANIM is too short to hold its header');
+    const view = new DataView(buffer, offset, byteLength);
+    const count = view.getUint32(0, true);
+    const durationSec = view.getFloat32(4, true);
+    const nameBytes = view.getUint32(8, true);
+    const name = decodeString(view, 16).value;
+    const headerAt = 16 + nameBytes;
+    let at = headerAt;
+    let data = headerAt + count * TRACK_ENTRY_BYTES;
+    const tracks = [];
+    for (let i = 0; i < count; i++) {
+        const joint = view.getUint32(at, true);
+        const pathIndex = view.getUint32(at + 4, true);
+        const keys = view.getUint32(at + 8, true);
+        at += TRACK_ENTRY_BYTES;
+        const path = PATHS[pathIndex];
+        if (path === undefined)
+            throw new DrftError(`ANIM: track ${i} names path ${pathIndex}`);
+        const components = path === 'rotation' ? 4 : 3;
+        if (data + keys * 4 + keys * components * 4 > byteLength) {
+            throw new DrftError(`ANIM: track ${i} reads past the end of its chunk`);
+        }
+        const times = new Float32Array(keys);
+        for (let k = 0; k < keys; k++) {
+            times[k] = view.getFloat32(data, true);
+            data += 4;
+        }
+        const values = new Float32Array(keys * components);
+        for (let v = 0; v < keys * components; v++) {
+            values[v] = view.getFloat32(data, true);
+            data += 4;
+        }
+        tracks.push({ joint, path, times, values });
+    }
+    return { name, durationSec, tracks };
+}
+export function buildMorph(morph) {
+    const bytes = new Uint8Array(align(8 + morph.deltas.length * 4));
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, morph.targetCount, true);
+    /*
+     * The mesh this deforms, **in the payload rather than in the chunk table's `index`**.
+     *
+     * That field is the ordinal *within a FourCC* — the writer derives it and a caller cannot set
+     * it — so for a file where only the second and fifth meshes have targets, the two `MORP` chunks
+     * would carry 0 and 1 and a reader pairing by it would deform the wrong geometry. The table's
+     * own convention is right and this is the field that has to move.
+     */
+    view.setUint32(4, morph.mesh, true);
+    for (let f = 0; f < morph.deltas.length; f++) {
+        view.setFloat32(8 + f * 4, morph.deltas[f], true);
+    }
+    return bytes;
+}
+export function readMorph(buffer, offset, byteLength) {
+    if (byteLength < 8)
+        throw new DrftError('MORP is too short to hold its header');
+    const view = new DataView(buffer, offset, byteLength);
+    const targetCount = view.getUint32(0, true);
+    const mesh = view.getUint32(4, true);
+    if (targetCount < 1)
+        throw new DrftError(`MORP for mesh ${mesh} declares ${targetCount} targets`);
+    const floats = Math.floor((byteLength - 8) / 4);
+    const deltas = new Float32Array(floats);
+    for (let f = 0; f < floats; f++)
+        deltas[f] = view.getFloat32(8 + f * 4, true);
+    return { mesh, targetCount, deltas };
+}

package/dist/drftStream.d.ts

@@ -0,0 +1,170 @@
+/** Reading a `.drft` while it is still arriving, chunk by chunk. */
+import type { MeshData } from './meshData.ts';
+import type { DrftHead, DrftMaterial, DrftSplatBlock } from './drftFormat.ts';
+import type { DrftTexture } from './drftRead.ts';
+import type { AnimationClip, DrftSkin } from './animationData.ts';
+import type { DrftNode } from './drftSkin.ts';
+import type { DrftMorph } from './drftSkin.ts';
+/**
+ * What the file says is coming, known from the first few kilobytes.
+ *
+ * **The chunk table is a manifest and always was**: a fixed 32-byte header, then
+ * `chunkCount x 16` bytes naming every chunk's kind, offset and length. For a 187-mesh car
+ * that is about 3 KB, so a reader holding the first three kilobytes of a 74 MB file knows
+ * exactly what the rest of it contains and how big each piece is. That is what lets a loading
+ * bar say "142 of 187 parts" rather than counting bytes and hoping.
+ */
+export interface DrftManifest {
+    readonly totalBytes: number;
+    readonly meshCount: number;
+    readonly textureCount: number;
+    /** Bytes of geometry, of images, and of everything else, from the table alone. */
+    readonly meshBytes: number;
+    readonly textureBytes: number;
+    /**
+     * How many coarse levels of detail this file carries, which is normally one or none.
+     *
+     * Worth reporting rather than leaving to be discovered, because it is the difference between
+     * a load that opens on an outline and one that opens on an empty room, and a caller composing
+     * words for a progress readout wants to know that before the first stage rather than after it.
+     */
+    readonly lodCount: number;
+    /**
+     * How many `SPLT` blocks this file carries, and how many bytes they are between them.
+     *
+     * **Blocks, not splats**, because the number a progress readout wants is how many refinements
+     * are still coming — the splat count is in every block's own header and a caller has it from
+     * the first one. Zero for a file with no capture, which is most of them.
+     */
+    readonly splatBlockCount: number;
+    readonly splatBytes: number;
+}
+/**
+ * Called as each kind of thing finishes arriving. Every one is optional.
+ *
+ * A consumer that wants the whole asset at once should use `readDrft`; these exist so a scene
+ * can put a coarse thing on screen and improve it, which is the point of streaming at all.
+ */
+export interface DrftStreamHandlers {
+    /** The table has arrived, so what is coming is now known. Fires once, before anything else. */
+    readonly onManifest?: (manifest: DrftManifest) => void;
+    readonly onHead?: (head: DrftHead) => void;
+    /**
+     * A coarse whole-model level, with its level ordinal: 0 is the coarsest.
+     *
+     * Fires before any part on a file the baker laid out, which is the whole point of it — a
+     * complete object on screen while the parts are still arriving. A caller that draws it must
+     * stop drawing it in the same frame it starts drawing the model, or the two are both there.
+     */
+    readonly onLod?: (mesh: MeshData, level: number) => void;
+    /** One mesh, in the order the file lays them out, with its ordinal in that order. */
+    readonly onMesh?: (mesh: MeshData, ordinal: number) => void;
+    /**
+     * One block of a Gaussian splat capture, with its ordinal.
+     *
+     * **Every block is a sparse version of the whole capture, so the first one is already worth
+     * drawing** — that is what the writer's coarse-first ordering buys and it is the reason splats
+     * are in this container rather than in a file of their own. A consumer allocates from
+     * `block.totalCount` on the first call and appends after that; the drawn count rises and
+     * nothing is re-allocated or re-sorted.
+     */
+    readonly onSplats?: (block: DrftSplatBlock, ordinal: number) => void;
+    /**
+     * The asset's hierarchy, once, when its `NODE` chunk lands.
+     *
+     * Handed over whole rather than a node at a time: a hierarchy is one chunk and a partial one is
+     * not useful — a child whose parent has not arrived cannot be placed.
+     */
+    readonly onNodes?: (nodes: readonly DrftNode[]) => void;
+    /** One mesh's morph deltas, naming the mesh ordinal they belong to. */
+    readonly onMorph?: (morph: DrftMorph) => void;
+    /** One skin, as its `SKIN` chunk lands. Several arrive for an asset with several. */
+    readonly onSkin?: (skin: DrftSkin, ordinal: number) => void;
+    /**
+     * One clip, as its `ANIM` chunk lands.
+     *
+     * Per chunk rather than collected, for the reason `onSplats` is: a consumer that can start a
+     * character on the first clip should not wait for the last. The writer puts all three ahead of
+     * the geometry so this is usually possible.
+     */
+    readonly onClip?: (clip: AnimationClip, ordinal: number) => void;
+    readonly onMaterials?: (materials: readonly DrftMaterial[]) => void;
+    readonly onTexture?: (texture: DrftTexture, ordinal: number) => void;
+}
+/**
+ * An incremental `.drft` reader: feed it bytes, it reports each chunk as that chunk completes.
+ *
+ * **Its own entry point rather than a flag on `readDrft`**, which is what docs/FORMAT.md §4.6
+ * asks for and the reason is the strictness. `readDrft` requires a `HEAD` and at least one
+ * `MESH` and refuses anything partial, which is right for a file on disk and wrong for a
+ * stream. The rules do not relax here, they *move*: a chunk is validated when its last byte
+ * lands, the table's own rules apply the moment the table is readable, and the whole-asset
+ * rules apply at `end`. A malformed file still throws, naming the chunk.
+ *
+ * **Zero-copy survives, and that is not obvious.** The header carries `totalBytes`, so this
+ * allocates one buffer of the final size the moment it knows that number and writes arriving
+ * bytes into it. Every completed chunk is then viewed in place, exactly as a whole-file read
+ * views it. Accumulating chunks into their own buffers instead would cost a copy per chunk and
+ * give up the one property this format exists for.
+ *
+ * Sequential, because that is the property worth designing for: with the payloads laid out in
+ * priority order by the baker, a *plain* fetch refines the model as bytes arrive, with no range
+ * requests and no server support beyond serving a file. Range requests would be an
+ * optimisation on top, and would need an offset per push rather than a different reader.
+ */
+export declare class DrftStream {
+    private readonly handlers;
+    /** The final buffer, once `totalBytes` is known. Written into at the arrival offset. */
+    private buffer;
+    private bytes;
+    /** The header and table, before the real buffer exists. At most a few arrivals. */
+    private prelude;
+    private preludeBytes;
+    private received;
+    private chunks;
+    /** How many table entries have been reported complete, in table order. */
+    private settled;
+    private meshOrdinal;
+    private textureOrdinal;
+    private head;
+    private meshCount;
+    private materialCount;
+    private textureCount;
+    private splatBlockCount;
+    private manifestSent;
+    private versionMajor;
+    private versionMinor;
+    private ended;
+    constructor(handlers?: DrftStreamHandlers);
+    /** Bytes arrived so far, and how many the file says there are. Zero until the header lands. */
+    get progress(): {
+        readonly received: number;
+        readonly total: number;
+    };
+    /**
+     * Hand over the next bytes of the file, in order.
+     *
+     * Reports whatever those bytes completed before returning, so a caller that draws between
+     * pushes sees every intermediate state.
+     */
+    push(part: Uint8Array): void;
+    /**
+     * No more bytes. Applies the rules that are about the asset as a whole rather than about one
+     * chunk, which is where `readDrft`'s refusals live.
+     */
+    end(): void;
+    /** Everything the header and the table say, once they have arrived. */
+    private openBuffer;
+    /** Parse the table once all of it has arrived, and announce what is coming. */
+    private readTable;
+    /** Report every chunk whose last byte has now landed, in file order. */
+    private settleChunks;
+}
+/**
+ * Read a `.drft` from a fetch response as it arrives.
+ *
+ * The whole point of the sequential design in one function: a plain `fetch` of a plain file,
+ * and the model improves as the bytes land. A response with no body — an error page, a
+ * cache miss served as a redirect — throws rather than resolving to an empty asset.
+ */
+export declare function streamDrft(response: Response, handlers?: DrftStreamHandlers): Promise<void>;