@driftengine/drft 4.3.0 → 4.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 The `.drft` container: read and write a baked scene. Declares no runtime dependency.
 
-**Cost: 8.1 KB gzipped.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 9.7 KB gzipped.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/drftFormat.d.ts

@@ -20,7 +20,7 @@ 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 = 17;
+export declare const DRFT_VERSION_MINOR = 18;
 /** Bytes before the chunk table. */
 export declare const HEADER_BYTES = 32;
 /** Bytes per chunk table entry. */
@@ -220,6 +220,17 @@ export declare const CHUNK_NAVM: number;
  * container holds text.
  */
 export declare const CHUNK_ENTS: number;
+/**
+ * Meshes drawn many times, one matrix a copy. **Required**: see `drftInstances.ts` for why a reader
+ * that skipped it would be worse than one that refused. Added in 1.18.
+ */
+export declare const CHUNK_INST: number;
+/**
+ * A mesh in the bytes its data needs: constants, 16-bit ranges and octahedral directions, decoded on
+ * read into the `MeshData` a `MESH` gives. **Required**, and counted as a mesh in every ordinal.
+ * See `drftQuantised.ts`. Added in 1.18.
+ */
+export declare const CHUNK_MSHQ: number;
 /** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
 export declare const SPLAT_BLOCK_PREFIX = 40;
 /**
@@ -460,6 +471,23 @@ export interface DrftMaterial {
      * tested.
      */
     readonly cutout: number;
+    /**
+     * Whether the surface blends: its texture's alpha is coverage, times `opacity`. 1.18.
+     *
+     * **A flag, because `opacity` could not say it.** glTF's `BLEND` makes alpha the factor times the
+     * texture, and a factor of 1 left `opacity` at 1: every loader drew the material opaque and a
+     * leaf's shape, which is all in its texture's alpha, was never read. Absent means false, which is
+     * what every file before 1.18 meant.
+     */
+    readonly blend?: boolean;
+    /**
+     * Whether both faces of the surface are seen: bit 1 of the flags word, 1.18.
+     *
+     * glTF's `doubleSided`, and what a curtain, a flag and a leaf card are. A one-sided surface is
+     * culled from behind, so a curtain seen from the other side of its arch is a hole, and half a
+     * tree's cards are not drawn. Absent means false, which is how every surface before it was drawn.
+     */
+    readonly doubleSided?: boolean;
 }
 /** Floats in a `MATL` entry, then the signed texture indices that follow them. */
 export declare const MATERIAL_FLOATS = 15;
@@ -473,6 +501,8 @@ export declare const MATERIAL_FLOATS = 15;
  * them is speculative — only unbound, and the plans that bind them need no second stride bump.
  */
 export declare const MATERIAL_INDICES = 4;
+/** A `u32` of flags after them, since 1.18: bit 0 is `blend`, bit 1 is `doubleSided`. */
+export declare const MATERIAL_FLAGS = 1;
 export declare const MATERIAL_ENTRY_BYTES: number;
 /** What `HEAD` says about the asset as a whole. */
 export interface DrftHead {

package/dist/drftFormat.js

@@ -20,7 +20,7 @@ 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 = 17;
+export const DRFT_VERSION_MINOR = 18;
 /** Bytes before the chunk table. */
 export const HEADER_BYTES = 32;
 /** Bytes per chunk table entry. */
@@ -231,6 +231,17 @@ export const CHUNK_NAVM = fourCC('NAVM');
  * container holds text.
  */
 export const CHUNK_ENTS = fourCC('ENTS');
+/**
+ * Meshes drawn many times, one matrix a copy. **Required**: see `drftInstances.ts` for why a reader
+ * that skipped it would be worse than one that refused. Added in 1.18.
+ */
+export const CHUNK_INST = fourCC('INST');
+/**
+ * A mesh in the bytes its data needs: constants, 16-bit ranges and octahedral directions, decoded on
+ * read into the `MeshData` a `MESH` gives. **Required**, and counted as a mesh in every ordinal.
+ * See `drftQuantised.ts`. Added in 1.18.
+ */
+export const CHUNK_MSHQ = fourCC('MSHQ');
 /** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
 export const SPLAT_BLOCK_PREFIX = 40;
 /**
@@ -262,6 +273,8 @@ export const KNOWN_CHUNKS = new Set([
     CHUNK_NGRF,
     CHUNK_NAVM,
     CHUNK_ENTS,
+    CHUNK_INST,
+    CHUNK_MSHQ,
 ]);
 /** Chunk flags. */
 export const CHUNK_REQUIRED = 1 << 0;
@@ -392,7 +405,9 @@ export const MATERIAL_FLOATS = 15;
  * 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;
+/** A `u32` of flags after them, since 1.18: bit 0 is `blend`, bit 1 is `doubleSided`. */
+export const MATERIAL_FLAGS = 1;
+export const MATERIAL_ENTRY_BYTES = MATERIAL_FLOATS * 4 + MATERIAL_INDICES * 4 + MATERIAL_FLAGS * 4;
 /**
  * Thrown for any malformed or unreadable file, with the offset that failed.
  *

package/dist/drftInstances.d.ts

@@ -0,0 +1,9 @@
+export interface DrftInstanceGroup {
+    /** The ordinal of the `MESH` this group draws, which holds one copy. */
+    readonly mesh: number;
+    /** Sixteen floats a copy, column-major, taking the mesh to where that copy stands. */
+    readonly transforms: Float32Array;
+}
+export declare function buildInstances(groups: readonly DrftInstanceGroup[]): Uint8Array;
+/** The groups in an `INST` payload, each checked against the file's mesh count. */
+export declare function readInstances(buffer: ArrayBufferLike, offset: number, byteLength: number, meshCount: number): DrftInstanceGroup[];

package/dist/drftInstances.js

@@ -0,0 +1,68 @@
+/**
+ * `INST`: meshes drawn many times, each copy placed by a column-major 4×4 matrix.
+ *
+ * **Required, because a reader that skipped it would draw one copy where there are thousands.** The
+ * mesh an instance group names holds one prototype, so an old reader that did not know the chunk
+ * would open a scene of ten thousand candles as a single candle at the origin and say nothing. A
+ * refusal naming `INST` is the honest answer. What that gives up is opening such a file at all in a
+ * reader before 1.18.
+ *
+ * Layout, little-endian:
+ * - u32 group count;
+ * - per group: u32 mesh ordinal, u32 instance count, then that many 16-float matrices.
+ *
+ * A mesh appears in at most one group.
+ */
+import { DrftError, align } from './drftFormat.js';
+export function buildInstances(groups) {
+    const seen = new Set();
+    let floats = 0;
+    for (const group of groups) {
+        if (group.transforms.length === 0 || group.transforms.length % 16 !== 0) {
+            throw new DrftError(`instance group for mesh ${group.mesh} has ${group.transforms.length} floats, which is not whole matrices`);
+        }
+        if (seen.has(group.mesh))
+            throw new DrftError(`mesh ${group.mesh} is instanced twice`);
+        seen.add(group.mesh);
+        floats += group.transforms.length;
+    }
+    const bytes = new Uint8Array(align(4 + groups.length * 8 + floats * 4));
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, groups.length, true);
+    let at = 4;
+    for (const group of groups) {
+        view.setUint32(at, group.mesh, true);
+        view.setUint32(at + 4, group.transforms.length / 16, true);
+        at += 8;
+        for (let i = 0; i < group.transforms.length; i++) {
+            view.setFloat32(at, group.transforms[i], true);
+            at += 4;
+        }
+    }
+    return bytes;
+}
+/** The groups in an `INST` payload, each checked against the file's mesh count. */
+export function readInstances(buffer, offset, byteLength, meshCount) {
+    const view = new DataView(buffer, offset, byteLength);
+    const count = view.getUint32(0, true);
+    const out = [];
+    let at = 4;
+    for (let g = 0; g < count; g++) {
+        if (at + 8 > byteLength)
+            throw new DrftError('INST ends inside a group header');
+        const mesh = view.getUint32(at, true);
+        const copies = view.getUint32(at + 4, true);
+        at += 8;
+        if (mesh >= meshCount) {
+            throw new DrftError(`INST places mesh ${mesh}, and the file carries ${meshCount} meshes`);
+        }
+        if (at + copies * 64 > byteLength)
+            throw new DrftError(`INST ends inside mesh ${mesh}'s placements`);
+        const transforms = new Float32Array(copies * 16);
+        for (let i = 0; i < transforms.length; i++)
+            transforms[i] = view.getFloat32(at + i * 4, true);
+        at += copies * 64;
+        out.push({ mesh, transforms });
+    }
+    return out;
+}

package/dist/drftLights.d.ts

@@ -0,0 +1,21 @@
+export type DrftLightKind = 'point' | 'spot' | 'directional';
+export interface DrftLight {
+    readonly kind: DrftLightKind;
+    /** The node's name in the source, or empty. */
+    readonly name: string;
+    /** World space, metres. */
+    readonly position: readonly [number, number, number];
+    /** Where a spot or a directional light points, world space and unit length. glTF's local −z. */
+    readonly direction: readonly [number, number, number];
+    /** Linear, 0 to 1 a channel. */
+    readonly color: readonly [number, number, number];
+    /** Candela for a point or a spot, lux for a directional light. */
+    readonly intensity: number;
+    /** Metres at which the source's author cut the light off, or 0 for no cut. */
+    readonly range: number;
+    readonly innerConeRad: number;
+    readonly outerConeRad: number;
+}
+export declare function buildLights(lights: readonly DrftLight[]): Uint8Array;
+/** The lights in a `LITE` payload. */
+export declare function readLights(buffer: ArrayBufferLike, offset: number, byteLength: number): DrftLight[];

package/dist/drftLights.js

@@ -0,0 +1,108 @@
+/**
+ * `LITE`: the lights a scene was authored with, in glTF's own terms.
+ *
+ * **The source's numbers, unconverted.** Intensity is candela for a point or a spot and lux for a
+ * directional light, as `KHR_lights_punctual` states it, because what a candela is in a consumer's
+ * units is that consumer's exposure decision and no two agree. The chunk says where the lamps are and
+ * what their author said about them. Deciding how bright they draw is the consumer's job.
+ *
+ * **Optional.** A reader that skips it loses the lights and nothing else; they were only ever the
+ * consumer's to place. What that gives up is a file whose lights are essential saying so, which
+ * none is: a scene without its lamps is darker, not wrong.
+ *
+ * Layout, little-endian:
+ * - u32 light count, u32 name count;
+ * - the names, each a u32 byte length and UTF-8, padded to four bytes. **Each distinct name is
+ *   written once**: a pack of ten thousand candles names every one "Instance";
+ * - per light, 64 bytes: u32 kind (0 point, 1 spot, 2 directional), u32 name index, position,
+ *   direction, colour (three f32 each), intensity, range (0 is unbounded), inner and outer cone
+ *   in radians, and one reserved f32.
+ */
+import { DrftError, align } from './drftFormat.js';
+const KINDS = ['point', 'spot', 'directional'];
+const LIGHT_BYTES = 64;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function buildLights(lights) {
+    const names = [];
+    const nameIndex = new Map();
+    for (const light of lights) {
+        if (!nameIndex.has(light.name)) {
+            nameIndex.set(light.name, names.length);
+            names.push(light.name);
+        }
+    }
+    const encoded = names.map((name) => encoder.encode(name));
+    let nameBytes = 0;
+    for (const text of encoded)
+        nameBytes += align(4 + text.length);
+    const bytes = new Uint8Array(8 + nameBytes + lights.length * LIGHT_BYTES);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, lights.length, true);
+    view.setUint32(4, names.length, true);
+    let at = 8;
+    for (const text of encoded) {
+        view.setUint32(at, text.length, true);
+        bytes.set(text, at + 4);
+        at += align(4 + text.length);
+    }
+    for (const light of lights) {
+        view.setUint32(at, KINDS.indexOf(light.kind), true);
+        view.setUint32(at + 4, nameIndex.get(light.name) ?? 0, true);
+        const floats = [
+            ...light.position,
+            ...light.direction,
+            ...light.color,
+            light.intensity,
+            light.range,
+            light.innerConeRad,
+            light.outerConeRad,
+        ];
+        for (let i = 0; i < floats.length; i++)
+            view.setFloat32(at + 8 + i * 4, floats[i], true);
+        at += LIGHT_BYTES;
+    }
+    return bytes;
+}
+/** The lights in a `LITE` payload. */
+export function readLights(buffer, offset, byteLength) {
+    const view = new DataView(buffer, offset, byteLength);
+    if (byteLength < 8)
+        throw new DrftError('LITE is shorter than its own header');
+    const count = view.getUint32(0, true);
+    const nameCount = view.getUint32(4, true);
+    const names = [];
+    let at = 8;
+    for (let n = 0; n < nameCount; n++) {
+        if (at + 4 > byteLength)
+            throw new DrftError('LITE ends inside its names');
+        const length = view.getUint32(at, true);
+        if (at + 4 + length > byteLength)
+            throw new DrftError('a LITE name runs past the chunk');
+        names.push(decoder.decode(new Uint8Array(buffer, offset + at + 4, length)));
+        at += align(4 + length);
+    }
+    if (at + count * LIGHT_BYTES > byteLength) {
+        throw new DrftError(`LITE says ${count} lights and ends inside them`);
+    }
+    const f = (o) => view.getFloat32(o, true);
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        const kind = KINDS[view.getUint32(at, true)];
+        if (kind === undefined)
+            throw new DrftError(`LITE light ${i} is of a kind this reader does not know`);
+        out.push({
+            kind,
+            name: names[view.getUint32(at + 4, true)] ?? '',
+            position: [f(at + 8), f(at + 12), f(at + 16)],
+            direction: [f(at + 20), f(at + 24), f(at + 28)],
+            color: [f(at + 32), f(at + 36), f(at + 40)],
+            intensity: f(at + 44),
+            range: f(at + 48),
+            innerConeRad: f(at + 52),
+            outerConeRad: f(at + 56),
+        });
+        at += LIGHT_BYTES;
+    }
+    return out;
+}

package/dist/drftQuantised.d.ts

@@ -0,0 +1,3 @@
+import type { MeshData } from './meshData.ts';
+export declare function encodeQuantisedMesh(mesh: MeshData): Uint8Array;
+export declare function decodeQuantisedMesh(buffer: ArrayBufferLike, offset: number, byteLength: number): MeshData;