@driftengine/drft 3.61.0

package/dist/drftFormat.d.ts

@@ -0,0 +1,454 @@
+/**
+ * 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 declare const DRFT_MAGIC = 1413894724;
+/**
+ * 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 declare 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 declare const DRFT_VERSION_MINOR = 12;
+/** Bytes before the chunk table. */
+export declare const HEADER_BYTES = 32;
+/** Bytes per chunk table entry. */
+export declare 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 declare const ALIGNMENT = 4;
+/** Round up to the next aligned boundary. */
+export declare function align(value: number): number;
+/** A four-character code as a u32, so chunk identity is one integer compare. */
+export declare function fourCC(code: string): number;
+/** Back to text, for error messages that name what was not understood. */
+export declare function fourCCName(code: number): string;
+export declare const CHUNK_HEAD: number;
+export declare const CHUNK_MESH: number;
+/**
+ * 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 declare const CHUNK_NODE: number;
+export declare const CHUNK_MATL: number;
+export declare const CHUNK_TEXS: number;
+/**
+ * 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 declare const CHUNK_COLL: number;
+/**
+ * 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 declare const CHUNK_LODF: number;
+export declare const CHUNK_LITE: number;
+/**
+ * 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 declare const CHUNK_LODM: number;
+/**
+ * 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 declare const CHUNK_SPLT: number;
+/**
+ * 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 declare const CHUNK_SKIN: number;
+/**
+ * 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 declare const CHUNK_ANIM: number;
+/**
+ * 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 declare const CHUNK_MORP: number;
+/**
+ * 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 declare const CHUNK_SUBS: number;
+/** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
+export declare 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 declare const KNOWN_CHUNKS: ReadonlySet<number>;
+/** Chunk flags. */
+export declare const CHUNK_REQUIRED: number;
+/** File flags. Bit 0 is set on every file this engine writes. */
+export declare const FLAG_LITTLE_ENDIAN: number;
+/**
+ * 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 declare const ATTR_SPECULAR: number;
+export declare const ATTR_UVS: number;
+export declare const ATTR_EMISSIVE_COLOR: number;
+export declare const ATTR_ROUGHNESS: number;
+/**
+ * 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 declare const ATTR_GRAIN: number;
+/**
+ * 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 declare const ATTR_RELIEF: number;
+/**
+ * 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 declare const ATTR_TANGENT: number;
+/**
+ * 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 declare const ATTR_JOINTS: number;
+/** How much each of `ATTR_JOINTS`' four influences moves the vertex. See it for the whole story. */
+export declare const ATTR_WEIGHTS: number;
+/** Everything this version defines, so a reader can spot bits from a later writer. */
+export declare const ATTR_KNOWN: number;
+/**
+ * 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 declare const CODEC_PNG = 1;
+export declare const CODEC_JPEG = 2;
+export declare const CODEC_WEBP = 3;
+export declare const CODEC_RAW = 4;
+/** What a codec is called, for a message naming what was not understood. */
+export declare function codecName(codec: number): string;
+/**
+ * A capture, as the writer is handed it.
+ *
+ * **`positions` is read and never stored**, which is the one surprising field here. The writer
+ * needs them to decide the coarse-first block layout, and the reader gets them back out of the
+ * records — so writing them a second time would be twelve bytes a splat of duplicate in the one
+ * place this format is trying hardest to be small.
+ */
+export interface DrftSplats {
+    readonly count: number;
+    /** Three per splat, in the capture's own space. Read for layout only. */
+    readonly positions: Float32Array;
+    /** `wordsPerSplat` `u32`s per splat, in `count` order. Opaque here. */
+    readonly records: Uint32Array;
+    readonly wordsPerSplat: number;
+    readonly boundsMin: Float32Array;
+    readonly boundsMax: Float32Array;
+    /** Coefficients the source carried and the packer did not read. Carried as a number. */
+    readonly sphericalHarmonics?: number;
+    /**
+     * How many blocks to split the capture into, or absent for a size this writer chooses.
+     *
+     * More blocks means a capture that opens sooner and a longer chunk table; each entry is
+     * sixteen bytes, so even thirty-two blocks is half a kilobyte against megabytes of records.
+     */
+    readonly blocks?: number;
+}
+/**
+ * One block of a capture, as the reader hands it back.
+ *
+ * Every block repeats the whole capture's count and bounds, which is twenty-eight bytes each and
+ * makes a block self-describing: a consumer that has only the first one can size its buffers and
+ * cull against the final extent, rather than waiting for a manifest it may already have passed.
+ */
+export interface DrftSplatBlock {
+    /** Splats in this block. */
+    readonly count: number;
+    /** Splats in the whole capture, so a reader allocates once from the first block it meets. */
+    readonly totalCount: number;
+    readonly wordsPerSplat: number;
+    readonly sphericalHarmonics: number;
+    /** The whole capture's extent, not this block's. */
+    readonly boundsMin: Float32Array;
+    readonly boundsMax: Float32Array;
+    /** A view over the file's own bytes: `wordsPerSplat * count` words, no copy. */
+    readonly records: Uint32Array;
+}
+/**
+ * One surface, stored once per mesh rather than once per vertex.
+ *
+ * Parallel to the `MESH` chunks by ordinal: material *n* describes mesh *n*. A parallel
+ * array rather than a field inside `MESH` because a material is small and a mesh is
+ * megabytes, and the loader wants every material before it uploads anything, so it can
+ * create each texture once and share it between the meshes that name it.
+ */
+export interface DrftMaterial {
+    /**
+     * What the source called this surface. Diagnostic, and more than diagnostic.
+     *
+     * A bought asset frequently carries **no material data worth the name** and yet names its
+     * materials perfectly well: the one this format was built against stores every surface as
+     * the same default grey with no transparency, while calling them `body`, `glass`,
+     * `chrome`, `tire_mat5` and `calipers`. The name is then the only thing in the file that
+     * says what a surface *is*, so it is carried rather than discarded, and a scene can dress
+     * an import without editing the import.
+     */
+    readonly name: string;
+    readonly color: readonly [number, number, number];
+    readonly specular: number;
+    readonly roughness: number;
+    readonly emissive: number;
+    readonly emissiveColor: readonly [number, number, number];
+    /** 1 is opaque. Below 1 the surface blends, and the loader draws it after the solid ones. */
+    readonly opacity: number;
+    /** Index into the asset's textures for the colour map, or -1 for an untextured surface. */
+    readonly albedo: number;
+    /**
+     * Index into the asset's textures for the surface-space normal map, or -1 for none.
+     *
+     * **Written by any baker that can derive it, and bound by nothing yet.** Normal maps ship in the
+     * renderer; carrying one through the container is the plan after ORM's. The field is defined
+     * here rather than appended later so that all four indices cost the format one minor version
+     * instead of three — see `MATERIAL_INDICES`.
+     */
+    readonly normalMap: number;
+    /** Occlusion in R, roughness in G, metallic in B, or -1 for none. glTF's packing. */
+    readonly ormMap: number;
+    /** Index into the asset's textures for the emissive map, or -1. Written, not yet bound. */
+    readonly emissiveMap: number;
+    /**
+     * glTF's `roughnessFactor` where an `ormMap` supplies the roughness, and 1 where it does not.
+     *
+     * **A factor that multiplies a texture is not a value**, which is the mistake this pair exists
+     * to stop repeating. `roughness` and `specular` above are the scalars a material states when it
+     * has no map; these are what the same numbers mean when it has one.
+     */
+    readonly roughnessScale: number;
+    /** glTF's `metallicFactor` where an `ormMap` supplies the metallic, and 1 where it does not. */
+    readonly metallicScale: number;
+    /**
+     * glTF's `occlusionTexture.strength`, or **0** where nothing establishes that the ORM map's R
+     * channel holds occlusion at all.
+     *
+     * glTF assigns G and B of a `metallicRoughnessTexture` and says nothing about R, so occlusion is
+     * only there when `occlusionTexture` names the same image — which is what the ORM convention is.
+     * Anywhere else this is 0, because reading R would be reading whatever the exporter left.
+     */
+    readonly occlusionStrength: number;
+    /**
+     * How much of the environment this surface mirrors, 0 to 1.
+     *
+     * Distinct from `specular`, which is the strength of a highlight from a *light*. A surface
+     * can take a sharp highlight and reflect nothing, which is most plastic, or reflect its
+     * surroundings strongly, which is what makes paint and chrome read as what they are.
+     */
+    readonly reflectivity: number;
+    /**
+     * Alpha below which a fragment is discarded, 0 for a surface that discards nothing.
+     *
+     * **A test, not an opacity, and the difference is the whole reason this field exists.** A cutout
+     * says which *texels* of a surface are there at all — the gaps in a grille, the space between
+     * leaves, the holes in a fence — and leaves everything it keeps at full strength. An opacity
+     * says how much of the light passes through the surface that is there. A format with only the
+     * second has to spend it on the first, and `SurfaceMaterial.cutout` had no way through the
+     * container until this: an alpha-tested surface arrived as a solid rectangle or as nothing.
+     *
+     * glTF states it exactly — `alphaMode: 'MASK'` with `alphaCutoff`, which defaults to 0.5 — and
+     * it is what a vehicle format's alpha-test reference is, on the materials that say they are
+     * tested.
+     */
+    readonly cutout: number;
+}
+/** Floats in a `MATL` entry, then the signed texture indices that follow them. */
+export declare 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 declare const MATERIAL_INDICES = 4;
+export declare const MATERIAL_ENTRY_BYTES: number;
+/** What `HEAD` says about the asset as a whole. */
+export interface DrftHead {
+    /** The asset's own name, for diagnostics. Never load-bearing. */
+    readonly name: string;
+    /** What wrote it — tool and version — so a bad bake can be traced to its baker. */
+    readonly generator: string;
+    /** Metres per unit in the source. 1 for an asset already authored in metres. */
+    readonly unitScale: number;
+    /** Axis-aligned bounds of everything, in this file's units: min x/y/z then max x/y/z. */
+    readonly bounds: readonly number[];
+}
+/** A chunk as the table describes it, before its payload is touched. */
+export interface DrftChunk {
+    readonly code: number;
+    readonly offset: number;
+    readonly byteLength: number;
+    readonly flags: number;
+    readonly index: number;
+}
+/**
+ * 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 declare class DrftError extends Error {
+    constructor(message: string);
+}