@driftengine/drft 3.61.0

package/dist/drftFormat.js

@@ -0,0 +1,350 @@
+/**
+ * The `.drft` container: constants, layout and the compatibility rules.
+ *
+ * Shared by the reader and the writer so the two cannot disagree about a byte. Everything
+ * here is a fact about the format rather than about either side of it — if a number lives
+ * in this file, changing it changes the format.
+ *
+ * See docs/FORMAT.md for the specification this implements and the reasoning behind it.
+ */
+/** `DRFT`, little-endian, as a u32. The first four bytes of every file. */
+export const DRFT_MAGIC = 0x54465244;
+/**
+ * The generation of the layout. Bumped only when a byte changes meaning.
+ *
+ * A file whose major exceeds the reader's is refused — that is the one direction
+ * compatibility is allowed to fail, and it fails loudly rather than by misreading.
+ */
+export const DRFT_VERSION_MAJOR = 1;
+/**
+ * Additive revisions within a generation: new optional chunks, new attribute bits, new
+ * enum values with a defined fallback. Never a changed meaning.
+ */
+export const DRFT_VERSION_MINOR = 12;
+/** Bytes before the chunk table. */
+export const HEADER_BYTES = 32;
+/** Bytes per chunk table entry. */
+export const CHUNK_ENTRY_BYTES = 16;
+/**
+ * Everything is 4-byte aligned so a reader can build a `Float32Array` view straight over
+ * the fetched buffer. A typed array cannot start at an arbitrary offset, so alignment is
+ * not tidiness here — it is the entire reason this format exists rather than glTF.
+ */
+export const ALIGNMENT = 4;
+/** Round up to the next aligned boundary. */
+export function align(value) {
+    return (value + (ALIGNMENT - 1)) & ~(ALIGNMENT - 1);
+}
+/** A four-character code as a u32, so chunk identity is one integer compare. */
+export function fourCC(code) {
+    if (code.length !== 4)
+        throw new Error(`drft: a FourCC is four characters, got "${code}"`);
+    return ((code.charCodeAt(0) & 0xff) |
+        ((code.charCodeAt(1) & 0xff) << 8) |
+        ((code.charCodeAt(2) & 0xff) << 16) |
+        ((code.charCodeAt(3) & 0xff) << 24));
+}
+/** Back to text, for error messages that name what was not understood. */
+export function fourCCName(code) {
+    return String.fromCharCode(code & 0xff, (code >> 8) & 0xff, (code >> 16) & 0xff, (code >> 24) & 0xff);
+}
+export const CHUNK_HEAD = fourCC('HEAD');
+export const CHUNK_MESH = fourCC('MESH');
+/**
+ * The asset's own hierarchy: parent index, TRS, mesh index and name. Optional.
+ *
+ * **Specified in v1 and implemented in 1.6**, which is worth stating rather than quietly fixing.
+ * This constant and its `KNOWN_CHUNKS` entry have existed since the format did, and docs/FORMAT.md
+ * §4.3 described the payload — while no writer emitted one and no reader consumed one, for the
+ * whole of v1. Rigid TRS animation is the first thing that needs a hierarchy, so the chunk is
+ * finally built, and to the layout §4.3 already promised rather than to a new one.
+ */
+export const CHUNK_NODE = fourCC('NODE');
+export const CHUNK_MATL = fourCC('MATL');
+export const CHUNK_TEXS = fourCC('TEXS');
+/**
+ * Baked colliders: a set of convex hulls, as the points whose hulls they are.
+ *
+ * **Claimed in v1 and defined in 1.12.** The code and the `KNOWN_CHUNKS` entry existed from the
+ * start while no writer emitted one and no reader consumed one — the same history `CHUNK_NODE` and
+ * `CHUNK_ANIM` had. `drftColliders.ts` carries the payload and the reason it is points rather than
+ * shapes.
+ */
+export const CHUNK_COLL = fourCC('COLL');
+/**
+ * A discrete level of detail, as a **complete nested `.drft`**. Added at 1.9.
+ *
+ * **Not `LODM`, and the difference is what the chunk exists for.** `LODM` is one merged,
+ * material-less outline standing in for a whole asset while it loads. A discrete level is a whole
+ * model in its own right — its own meshes, its own materials, its own hierarchy — which is what a
+ * source that ships four hand-authored levels actually has, and folding one into `LODM` would
+ * merge its parts into a single mesh and discard every material it carries.
+ *
+ * **A nested file rather than appended arrays, and that is what keeps it additive.** `MATL` is
+ * parallel to `MESH` by ordinal and `NODE.mesh` indexes `MESH`, so appending another level's
+ * meshes to the same arrays would leave an older reader drawing every level at once, on top of
+ * itself. Nesting means an older reader skips one unknown chunk under §4.4 rule 2 and opens the
+ * file as the full-detail model it also is, which is the degradation that rule promises.
+ *
+ * Read as bytes rather than parsed, so a consumer pays only for a level it decides to use.
+ */
+export const CHUNK_LODF = fourCC('LODF');
+export const CHUNK_LITE = fourCC('LITE');
+/**
+ * A coarse whole-asset level of detail, added in 1.2. Its payload is a `MESH` payload.
+ *
+ * **A chunk of its own rather than a level field inside `MESH`**, which is what §4.6 of
+ * docs/FORMAT.md proposed and is the one part of that design that could not stand. Three
+ * things break if a coarse level arrives as a `MESH`, and every one of them is silent:
+ *
+ * - `MESH` is a *required* chunk kind, so rule 2's protection does not apply. A 1.1 reader
+ *   would draw the coarse level as a real part, on top of the model it stands for.
+ * - `MATL` pairs with `MESH` **by ordinal** and both sides refuse a count mismatch, so a
+ *   file with one extra `MESH` either fails to open or shifts every material by one.
+ * - The manifest counts `MESH` chunks, so "142 of 187 parts" would gain a part that is not
+ *   one.
+ *
+ * Optional and skipped in silence, which is rule 2 doing exactly its job: a 1.1 reader opens
+ * a 1.2 file as the model without its outline, and the outline is not something a reader that
+ * has never heard of it should draw. The table's `index` is the **level ordinal, coarsest
+ * first**, which is the same "ordinal within a FourCC" every other chunk kind uses.
+ */
+export const CHUNK_LODM = fourCC('LODM');
+/**
+ * One block of a Gaussian splat capture, added in 1.5. Optional, and there are usually several.
+ *
+ * **Several chunks rather than one, and that is the whole point of putting splats in this
+ * container at all.** A chunk is reported when its last byte lands, so a single chunk holding a
+ * million splats arrives all at once and streaming buys nothing. Split into blocks whose contents
+ * are interleaved across the *whole* capture — see `coarseFirst.ts` — the first block that lands
+ * is a complete sparse capture rather than a finished corner of one, and the load opens on a
+ * recognisable place that densifies. The table's `index` is the block ordinal.
+ *
+ * Optional, so rule 2 of docs/FORMAT.md §4.4 applies exactly as it does to `LODM`: a 1.4 reader
+ * skips every block in silence and opens the file as whatever else it holds. That is the right
+ * degradation — a reader that has never heard of a splat cannot draw one, and a capture is not a
+ * mesh it could approximate.
+ *
+ * **The payload is opaque to this format.** Its per-splat record is `wordsPerSplat` `u32`s whose
+ * meaning belongs to whoever packed them, which is `@driftengine/splats`. That keeps the container
+ * free of the shader's texel layout and lets a later minor version widen the record — for
+ * spherical harmonics, say — without this file learning anything new.
+ */
+export const CHUNK_SPLT = fourCC('SPLT');
+/**
+ * A skin: joints, their parents and their inverse bind matrices. Optional, added in 1.6.
+ *
+ * Written **parents-first**, and the reader refuses any other order. A palette is resolved in
+ * index order and reads each joint's parent as it goes, so a nearly-sorted rig is wrong in one
+ * limb — which reads as a bad animation rather than as a bad file. The importer is the layer that
+ * sorts, because it is also the one that can remap every index naming a joint.
+ */
+export const CHUNK_SKIN = fourCC('SKIN');
+/**
+ * One animation clip. Optional, one chunk per clip, added in 1.6.
+ *
+ * **This FourCC was claimed and undefined for the whole of v1** — docs/FORMAT.md §4.3 listed it as
+ * "Reserved. Not in v1", and §4.4's own example of a free additive change was "a v1.4 file carrying
+ * `ANIM` opens in a v1.0 reader as a v1.0 file would". That example stops being hypothetical here,
+ * and it holds: the chunk is optional, so rule 2 skips it in silence.
+ *
+ * The table's `index` is the clip ordinal, which is the same "ordinal within a FourCC" every other
+ * repeated chunk kind uses.
+ */
+export const CHUNK_ANIM = fourCC('ANIM');
+/**
+ * One mesh's morph target deltas. Optional, one chunk per mesh that has any, added in 1.7.
+ *
+ * **A chunk of its own rather than more attribute bits in `MESH`**, and the reason is the one
+ * `CHUNK_LODM` gives about not being a `MESH`: an attribute covers every vertex once, and morph
+ * deltas cover every vertex once *per target*. There is no attribute bit that can express a length
+ * that scales with a count stored elsewhere, and a reader that guessed would read the wrong number
+ * of floats and hand back geometry rather than fail.
+ *
+ * The table's `index` is the **mesh ordinal** it belongs to, which is how a reader pairs them — the
+ * same "ordinal within a FourCC" `MATL` uses, except that `MATL` pairs by position and this pairs
+ * by an index a mesh may not have. A mesh with no targets simply has no chunk.
+ */
+export const CHUNK_MORP = fourCC('MORP');
+/**
+ * Which substance each material is made of. Optional, one chunk per file, added in 1.8.
+ *
+ * **`§16` of the chemistry design, and it exists so there is no code between an artist and a fire**:
+ * the baker reads `extras.substance` off a glTF material and writes it here, and a consumer hands
+ * the ids to `installChemistry().match`. Labelling the oak in Blender is the whole of what a
+ * consumer does to make a log burn like oak.
+ *
+ * **One chunk for the file, pairing by an ordinal in the payload.** `CHUNK_MORP`'s note records why:
+ * the table's `index` is the ordinal within a FourCC, so a file where only the fourth material is
+ * labelled would carry a chunk at index 0 and a reader pairing by it would set the wrong material on
+ * fire. See `drftSubs.ts` for the layout.
+ */
+export const CHUNK_SUBS = fourCC('SUBS');
+/** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
+export const SPLAT_BLOCK_PREFIX = 40;
+/**
+ * Chunks this reader understands.
+ *
+ * The set matters because of rule 3 in docs/FORMAT.md §4.4: a *required* chunk that is not in
+ * here is a refusal. An optional one is skipped in silence, which is what makes adding a
+ * chunk in a minor version free.
+ */
+export const KNOWN_CHUNKS = new Set([
+    CHUNK_HEAD,
+    CHUNK_MESH,
+    CHUNK_NODE,
+    CHUNK_MATL,
+    CHUNK_TEXS,
+    CHUNK_COLL,
+    CHUNK_LITE,
+    CHUNK_LODM,
+    CHUNK_LODF,
+    CHUNK_SPLT,
+    CHUNK_SKIN,
+    CHUNK_ANIM,
+    CHUNK_MORP,
+    CHUNK_SUBS,
+]);
+/** Chunk flags. */
+export const CHUNK_REQUIRED = 1 << 0;
+/** File flags. Bit 0 is set on every file this engine writes. */
+export const FLAG_LITTLE_ENDIAN = 1 << 0;
+/**
+ * Which optional attributes a `MESH` chunk carries.
+ *
+ * Positions, normals, colours and emissive are mandatory — every `MeshData` has them —
+ * so they take no bit. The four optional arrays do, in the order they appear in the
+ * payload, and the order is frozen: a new attribute takes the next free bit and appends
+ * to the payload, which is why an older reader can stop at the bits it knows.
+ */
+export const ATTR_SPECULAR = 1 << 0;
+export const ATTR_UVS = 1 << 1;
+export const ATTR_EMISSIVE_COLOR = 1 << 2;
+export const ATTR_ROUGHNESS = 1 << 3;
+/**
+ * Added in 1.1, and the worked example of why the order is frozen rather than tidy.
+ *
+ * It takes the next free bit and appends to the end of the payload, so a 1.0 reader meets
+ * exactly the arrays it knows in exactly the places it expects them and stops before this
+ * one. The asset then draws without grain, which is what a reader that has never heard of
+ * grain should produce. Inserting it beside `roughness`, where it belongs conceptually,
+ * would have shifted every array after it and repainted the model with no error raised.
+ */
+export const ATTR_GRAIN = 1 << 4;
+/**
+ * Added in 1.3, and it is the same story as `grain` one bit along.
+ *
+ * `MeshData.relief` and `MeshBuilder.setRelief` shipped in engine 0.23.0 and the container was
+ * never taught the bit, so a mesh carrying microscopic relief went through `writeDrft` and came
+ * back without it. Everything else survived, which is what made it invisible: a round trip gave
+ * the right shape with its surface texture gone, and that reads as a lighting problem rather
+ * than as a format dropping an array. Found from outside by a test that writes every optional
+ * attribute and reports *all* the losses rather than the first.
+ *
+ * Next free bit and appended last, for the reason spelled out above: a 1.2 reader meets the
+ * arrays it knows where it expects them, stops before this one, and draws the asset smooth,
+ * which is what a reader that has never heard of relief should produce.
+ */
+export const ATTR_RELIEF = 1 << 5;
+/**
+ * Added in 1.4, and the first optional attribute wider than three floats a vertex.
+ *
+ * A tangent frame: `xyz` running with u, and the bitangent's handedness in `w`. Four floats
+ * rather than three because a UV layout can mirror, and a bitangent computed without the sign
+ * lights one side of a model inside out. See `generateTangents` for the derivation.
+ *
+ * Next free bit, appended last, exactly as `grain` and `relief` each explain at length: a 1.3
+ * reader meets the six arrays it knows in the six places it expects them, stops before this one,
+ * and draws the asset with no tangent frame — which is what a reader that has never heard of
+ * tangents should produce, and which is precisely what today's shaders do with one.
+ */
+export const ATTR_TANGENT = 1 << 6;
+/**
+ * Added in 1.11, and it is `relief` again with more at stake.
+ *
+ * **Which joints move a vertex, four of them, as indices into a skinning palette.** `MeshData`
+ * declared `joints` and `weights` from the day skinning shipped and `validateMeshData` checked
+ * both — four floats a vertex, and neither present without the other — and this format wrote
+ * neither, because `buildMesh` listed the six optional arrays it knew and there was no bit to
+ * list. The `SKIN` chunk beside it was correct the whole time, so a file carried a skeleton, its
+ * bind pose and its clips, pointing at vertices that recorded no influence on any of them.
+ *
+ * **The failure was silent, which is what makes it the worse kind.** A baker handed the writer a
+ * correctly-validated skinned mesh, got no error, and produced a file nothing could skin — and
+ * `Mesh.isSkinned` reads `data.joints`, so what came back drew in bind pose for ever. Confine
+ * wrote its own binary for one human body rather than use this, about seventy lines across a
+ * baker and a loader, and that is the cost this closes.
+ *
+ * Two bits rather than one, because they are two arrays in the payload and the frozen order is a
+ * property of arrays. They are still both-or-neither: `validateMeshData` refuses one without the
+ * other on the way out and again on the way in, so the pair cannot half-arrive.
+ *
+ * Next free bits, appended last, for the reason `grain`, `relief` and `tangents` each spell out:
+ * a 1.10 reader meets the seven arrays it knows in the seven places it expects them, stops before
+ * these, and draws the asset in bind pose — which is what a reader that has never heard of
+ * skinning should produce.
+ */
+export const ATTR_JOINTS = 1 << 7;
+/** How much each of `ATTR_JOINTS`' four influences moves the vertex. See it for the whole story. */
+export const ATTR_WEIGHTS = 1 << 8;
+/** Everything this version defines, so a reader can spot bits from a later writer. */
+export const ATTR_KNOWN = ATTR_SPECULAR |
+    ATTR_UVS |
+    ATTR_EMISSIVE_COLOR |
+    ATTR_ROUGHNESS |
+    ATTR_GRAIN |
+    ATTR_RELIEF |
+    ATTR_TANGENT |
+    ATTR_JOINTS |
+    ATTR_WEIGHTS;
+/**
+ * How a `TEXS` payload is encoded.
+ *
+ * The compressed three are decoded by `createImageBitmap`, which every target browser has,
+ * so carrying them costs no dependency and no decoder of ours. `RAW` is uncompressed RGBA8
+ * for generated data and tests. `KTX2` is reserved rather than defined: it is the right
+ * long-term answer and it needs a transcoder of some 200 KB, so it becomes an additive
+ * minor version once a game needs it rather than a cost every asset pays now.
+ */
+export const CODEC_PNG = 1;
+export const CODEC_JPEG = 2;
+export const CODEC_WEBP = 3;
+export const CODEC_RAW = 4;
+/** What a codec is called, for a message naming what was not understood. */
+export function codecName(codec) {
+    return codec === CODEC_PNG
+        ? 'PNG'
+        : codec === CODEC_JPEG
+            ? 'JPEG'
+            : codec === CODEC_WEBP
+                ? 'WEBP'
+                : codec === CODEC_RAW
+                    ? 'RAW'
+                    : `codec ${codec}`;
+}
+/** Floats in a `MATL` entry, then the signed texture indices that follow them. */
+export const MATERIAL_FLOATS = 15;
+/**
+ * Albedo, normal, ORM and emissive.
+ *
+ * **Four at once rather than one per feature, and the arithmetic is the argument.** Each appended
+ * field is a writer change, a reader change, a `FORMAT.md` table edit and a forged-old-file test,
+ * so taking them one at a time would spend three minor versions arriving where this arrives in
+ * one. A glTF material names all four of its maps as plainly as it names the first, so none of
+ * them is speculative — only unbound, and the plans that bind them need no second stride bump.
+ */
+export const MATERIAL_INDICES = 4;
+export const MATERIAL_ENTRY_BYTES = MATERIAL_FLOATS * 4 + MATERIAL_INDICES * 4;
+/**
+ * Thrown for any malformed or unreadable file, with the offset that failed.
+ *
+ * One error type rather than several, because every caller does the same thing with it:
+ * a `.drft` that cannot be read is an asset that cannot be shown, and the useful part is
+ * the message. Loading fails loudly at init; nothing partial is ever returned.
+ */
+export class DrftError extends Error {
+    constructor(message) {
+        super(`drft: ${message}`);
+        this.name = 'DrftError';
+    }
+}

package/dist/drftRead.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Reading a `.drft`.
+ *
+ * Two rules govern everything here, and they pull in opposite directions on purpose:
+ *
+ * 1. **Never misread.** Every offset and length is checked against the buffer before it
+ *    is used. A file that is wrong is refused with the byte that failed, never
+ *    approximated and never half-returned. A partial asset shows up later as a rendering
+ *    artefact with no route back to its cause, which is the failure mode this whole
+ *    format was designed after.
+ * 2. **Never copy.** Vertex data is viewed in place — `new Float32Array(buffer, offset,
+ *    count)` — so loading a mesh costs the bounds checks and nothing else.
+ *
+ * Compatibility lives here too. See docs/FORMAT.md §4.4: old files open forever, unknown
+ * optional chunks are skipped in silence, unknown *required* chunks are a refusal.
+ */
+import type { AnimationClip, DrftSkin } from './animationData.ts';
+import type { DrftNode } from './drftSkin.ts';
+import type { MeshData } from './meshData.ts';
+import type { DrftChunk, DrftHead, DrftMaterial, DrftSplatBlock } from './drftFormat.ts';
+/** An embedded image, still compressed. Decoding is the consumer's, through `createImageBitmap`. */
+export interface DrftTexture {
+    /** What the source called this image. Empty for a file written before names existed. */
+    readonly name: string;
+    readonly codec: number;
+    readonly width: number;
+    readonly height: number;
+    /**
+     * A view over the fetched buffer, not a copy, exactly like the vertex arrays.
+     *
+     * It therefore keeps the whole file alive for as long as it is held. That is the intended
+     * trade for a load that allocates nothing, and it is why a consumer decoding these should
+     * drop its reference to the asset afterwards rather than keep it beside the GPU textures.
+     */
+    readonly bytes: Uint8Array;
+}
+/** A decoded asset. See docs/FORMAT.md for what each chunk carries. */
+export interface DrftAsset {
+    readonly head: DrftHead;
+    readonly meshes: readonly MeshData[];
+    /**
+     * Coarse whole-asset levels of detail, coarsest first, or empty for a file carrying none.
+     *
+     * Separate from `meshes` because they are not parts of the model: each one *is* the model,
+     * at a resolution that arrives sooner. A consumer reading a whole file at once has no use
+     * for them and ignores them; the streaming loader draws the best one it has until the real
+     * geometry is complete. See `DrftLoader` and docs/FORMAT.md §4.6.
+     */
+    readonly lods: readonly MeshData[];
+    /**
+     * Discrete levels of detail, finest first, each a complete `.drft` still in its bytes.
+     *
+     * **Handed over unparsed on purpose.** A level is a whole model, and a consumer that picks one
+     * by distance wants exactly one of them — parsing all four to hand back three that will not be
+     * drawn is work nobody asked for. Pass the one you want to `readDrft` again.
+     */
+    readonly levels: readonly Uint8Array[];
+    /**
+     * The whole capture, assembled from every `SPLT` block in ordinal order, or null for a file
+     * carrying none.
+     *
+     * **Assembled rather than handed over as blocks**, because a caller reading a whole file at
+     * once has no use for the split: it exists so a *stream* can put a sparse capture on screen
+     * early, and `DrftStream.onSplats` is where that matters. The records still arrive in the
+     * file's coarse-first order, so a consumer that draws a prefix of them draws a sparse whole.
+     */
+    readonly splats: DrftSplatBlock | null;
+    /**
+     * The asset's own hierarchy, or empty for a file carrying no `NODE`.
+     *
+     * Empty means what it always meant — one mesh at the origin — so a caller written before 1.6
+     * behaves identically against a file with a hierarchy it ignores.
+     */
+    readonly nodes: readonly DrftNode[];
+    /** Skins, in the order their chunks appear. Empty for a file that deforms nothing. */
+    readonly skins: readonly DrftSkin[];
+    /** Clips, in the order their chunks appear. Empty for a file that animates nothing. */
+    readonly clips: readonly AnimationClip[];
+    /** One per mesh by ordinal, or empty when the file names no materials. */
+    readonly materials: readonly DrftMaterial[];
+    readonly textures: readonly DrftTexture[];
+    /**
+     * Which substance each material is made of, or empty where the file labels none.
+     *
+     * The `SUBS` chunk, added at 1.8. Hand these to `installChemistry().match` — which matches
+     * **exactly** and reports what it could not, rather than guessing.
+     */
+    readonly substances: readonly {
+        readonly material: number;
+        readonly substance: string;
+    }[];
+    /**
+     * The convex hulls this asset collides as, or empty for a file carrying no `COLL`.
+     *
+     * Views over the fetched buffer, xyz-packed, in the asset's own space. Turning them into shapes is
+     * one line and belongs to whoever has a physics package:
+     *
+     * ```ts
+     * const shapes = asset.colliders.map((points) => hullShape(points));
+     * ```
+     */
+    readonly colliders: readonly Float32Array[];
+    /** Optional chunks this reader did not understand, in file order. Diagnostics only. */
+    readonly skipped: readonly string[];
+    readonly versionMajor: number;
+    readonly versionMinor: number;
+}
+export declare function readHead(buffer: ArrayBuffer, chunk: DrftChunk): DrftHead;
+export declare function readMesh(buffer: ArrayBuffer, chunk: DrftChunk): MeshData;
+/** Decode a `.drft` from a buffer. Throws `DrftError` on anything it cannot read. */
+export declare function readDrft(buffer: ArrayBuffer): DrftAsset;
+/**
+ * One `SPLT` block, viewed in place.
+ *
+ * **Zero-copy, like every other payload here.** The records are a `Uint32Array` over the file's
+ * own bytes, which is what the format's four-byte alignment exists for and what lets a capture of
+ * tens of megabytes reach the GPU without being duplicated on the way.
+ */
+export declare function readSplatBlock(buffer: ArrayBuffer, chunk: DrftChunk): DrftSplatBlock;
+export declare function readTexture(buffer: ArrayBuffer, chunk: DrftChunk): DrftTexture;
+export declare function readMaterials(buffer: ArrayBuffer, chunk: DrftChunk): DrftMaterial[];