@driftengine/drft 4.3.0 → 4.4.1

package/dist/drftWrite.js

@@ -10,7 +10,7 @@
  */
 import { buildClip, buildMorph, buildNodes, buildSkin } from './drftSkin.js';
 import { validateMeshData } from './meshData.js';
-import { ALIGNMENT, ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_JOINTS, ATTR_RELIEF, ATTR_TANGENT, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_UVS, ATTR_WEIGHTS, CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_ANIM, CHUNK_DTEX, CHUNK_ENTS, CHUNK_NAVM, CHUNK_LODM, CHUNK_LODF, CHUNK_MORP, CHUNK_NODE, CHUNK_SKIN, CHUNK_SPLT, SPLAT_BLOCK_PREFIX, CHUNK_MATL, CHUNK_MESH, CHUNK_REQUIRED, CHUNK_COLL, CHUNK_NNET, CHUNK_NGRF, CHUNK_SDFV, CHUNK_SUBS, CHUNK_TEXS, MATERIAL_ENTRY_BYTES, DRFT_MAGIC, DRFT_VERSION_MAJOR, DRFT_VERSION_MINOR, DrftError, FLAG_LITTLE_ENDIAN, HEADER_BYTES, align, } from './drftFormat.js';
+import { ALIGNMENT, ATTR_EMISSIVE_COLOR, ATTR_GRAIN, ATTR_JOINTS, ATTR_RELIEF, ATTR_TANGENT, ATTR_ROUGHNESS, ATTR_SPECULAR, ATTR_UVS, ATTR_WEIGHTS, CHUNK_ENTRY_BYTES, CHUNK_HEAD, CHUNK_ANIM, CHUNK_DTEX, CHUNK_ENTS, CHUNK_NAVM, CHUNK_LODM, CHUNK_LODF, CHUNK_MORP, CHUNK_NODE, CHUNK_INST, CHUNK_LITE, CHUNK_MSHQ, CHUNK_SKIN, CHUNK_SPLT, SPLAT_BLOCK_PREFIX, CHUNK_MATL, CHUNK_MESH, CHUNK_REQUIRED, CHUNK_COLL, CHUNK_NNET, CHUNK_NGRF, CHUNK_SDFV, CHUNK_SUBS, CHUNK_TEXS, MATERIAL_ENTRY_BYTES, DRFT_MAGIC, DRFT_VERSION_MAJOR, DRFT_VERSION_MINOR, DrftError, FLAG_LITTLE_ENDIAN, HEADER_BYTES, align, } from './drftFormat.js';
 import { coarseFirstOrder } from './coarseFirst.js';
 import { buildSubs } from './drftSubs.js';
 import { buildSdfv } from './sdfv.js';
@@ -20,6 +20,9 @@ import { buildEnts } from './ents.js';
 import { buildNavm } from './navm.js';
 import { buildNgrf } from './ngrf.js';
 import { buildColliders } from './drftColliders.js';
+import { buildInstances } from './drftInstances.js';
+import { buildLights } from './drftLights.js';
+import { encodeQuantisedMesh } from './drftQuantised.js';
 /**
  * The most blocks a capture is split into, and the fewest splats worth having in one.
  *
@@ -101,7 +104,7 @@ function encodeString(value) {
     bytes.set(text, 4);
     return bytes;
 }
-function buildHead(head, meshes) {
+function buildHead(head, meshes, instances = []) {
     /*
      * Bounds are computed rather than taken on trust. A caller that gets them wrong would
      * produce an asset that culls itself out of frame, which looks like a rendering bug and
@@ -113,23 +116,83 @@ function buildHead(head, meshes) {
     let maxX = -Infinity;
     let maxY = -Infinity;
     let maxZ = -Infinity;
-    for (const mesh of meshes) {
+    const placed = new Map();
+    for (const group of instances)
+        placed.set(group.mesh, group.transforms);
+    for (let m = 0; m < meshes.length; m++) {
+        const mesh = meshes[m];
+        const transforms = placed.get(m);
+        if (transforms === undefined) {
+            for (let at = 0; at + 2 < mesh.positions.length; at += 3) {
+                const x = mesh.positions[at];
+                const y = mesh.positions[at + 1];
+                const z = mesh.positions[at + 2];
+                if (x < minX)
+                    minX = x;
+                if (y < minY)
+                    minY = y;
+                if (z < minZ)
+                    minZ = z;
+                if (x > maxX)
+                    maxX = x;
+                if (y > maxY)
+                    maxY = y;
+                if (z > maxZ)
+                    maxZ = z;
+            }
+            continue;
+        }
+        /*
+         * **An instanced mesh's bounds are every copy's**, or a file of ten thousand candles reports one
+         * candle's box and a consumer fits and culls it as one candle. Each copy's box is the prototype's
+         * eight corners through its matrix: conservative for a copy that turns, exact for one that moves.
+         */
+        let lx = Infinity;
+        let ly = Infinity;
+        let lz = Infinity;
+        let hx = -Infinity;
+        let hy = -Infinity;
+        let hz = -Infinity;
         for (let at = 0; at + 2 < mesh.positions.length; at += 3) {
-            const x = mesh.positions[at];
-            const y = mesh.positions[at + 1];
-            const z = mesh.positions[at + 2];
-            if (x < minX)
-                minX = x;
-            if (y < minY)
-                minY = y;
-            if (z < minZ)
-                minZ = z;
-            if (x > maxX)
-                maxX = x;
-            if (y > maxY)
-                maxY = y;
-            if (z > maxZ)
-                maxZ = z;
+            lx = Math.min(lx, mesh.positions[at]);
+            ly = Math.min(ly, mesh.positions[at + 1]);
+            lz = Math.min(lz, mesh.positions[at + 2]);
+            hx = Math.max(hx, mesh.positions[at]);
+            hy = Math.max(hy, mesh.positions[at + 1]);
+            hz = Math.max(hz, mesh.positions[at + 2]);
+        }
+        if (!Number.isFinite(lx))
+            continue;
+        for (let k = 0; k + 15 < transforms.length; k += 16) {
+            for (let corner = 0; corner < 8; corner++) {
+                const cx = corner & 1 ? hx : lx;
+                const cy = corner & 2 ? hy : ly;
+                const cz = corner & 4 ? hz : lz;
+                const x = transforms[k] * cx +
+                    transforms[k + 4] * cy +
+                    transforms[k + 8] * cz +
+                    transforms[k + 12];
+                const y = transforms[k + 1] * cx +
+                    transforms[k + 5] * cy +
+                    transforms[k + 9] * cz +
+                    transforms[k + 13];
+                const z = transforms[k + 2] * cx +
+                    transforms[k + 6] * cy +
+                    transforms[k + 10] * cz +
+                    transforms[k + 14];
+                if (x < minX)
+                    minX = x;
+                if (y < minY)
+                    minY = y;
+                if (z < minZ)
+                    minZ = z;
+                if (x > maxX)
+                    maxX = x;
+                if (y > maxY)
+                    maxY = y;
+                if (z > maxZ)
+                    maxZ = z;
+            }
         }
     }
     if (!Number.isFinite(minX)) {
@@ -302,6 +365,7 @@ function buildMaterials(materials) {
         view.setFloat32(at + 64, material.metallicScale, true);
         view.setFloat32(at + 68, material.occlusionStrength, true);
         view.setFloat32(at + 72, material.cutout, true);
+        view.setUint32(at + 76, (material.blend === true ? 1 : 0) | (material.doubleSided === true ? 2 : 0), true);
         at += MATERIAL_ENTRY_BYTES;
     }
     return { code: CHUNK_MATL, flags: 0, bytes };
@@ -352,7 +416,7 @@ export function writeDrft(source) {
      * same asset less its textures rather than a refusal. Moving it earlier in the file changes
      * nothing about that, because a chunk is found through the table rather than by position.
      */
-    const chunks = [buildHead(source.head, source.meshes)];
+    const chunks = [buildHead(source.head, source.meshes, source.instances)];
     /*
      * The outline first, ahead of even the paint. It is the one thing that puts a recognisable
      * whole object on screen, it is a few hundred kilobytes against tens of megabytes, and the
@@ -386,6 +450,26 @@ export function writeDrft(source) {
     for (const node of source.nodes === undefined ? [] : [source.nodes]) {
         chunks.push({ code: CHUNK_NODE, flags: 0, bytes: buildNodes(node) });
     }
+    /*
+     * The placements ahead of the meshes they place, for the rig's reason: a streaming consumer must
+     * know a mesh is drawn ten thousand times before it lands, or it has already made it one part.
+     */
+    if ((source.instances?.length ?? 0) > 0) {
+        for (const group of source.instances ?? []) {
+            if (group.mesh >= source.meshes.length) {
+                throw new DrftError(`an instance group places mesh ${group.mesh}, and the asset has ${source.meshes.length}`);
+            }
+        }
+        chunks.push({
+            code: CHUNK_INST,
+            flags: CHUNK_REQUIRED,
+            bytes: buildInstances(source.instances),
+        });
+    }
+    /* Small, and ahead of the geometry, so a streaming consumer can place its lamps early. */
+    if ((source.lights?.length ?? 0) > 0) {
+        chunks.push({ code: CHUNK_LITE, flags: 0, bytes: buildLights(source.lights ?? []) });
+    }
     for (const skin of source.skins ?? []) {
         chunks.push({ code: CHUNK_SKIN, flags: 0, bytes: buildSkin(skin) });
     }
@@ -429,7 +513,13 @@ export function writeDrft(source) {
                 }),
             });
         }
-        chunks.push(buildMesh(mesh));
+        if (source.quantise === true) {
+            validateMeshData(mesh);
+            chunks.push({ code: CHUNK_MSHQ, flags: CHUNK_REQUIRED, bytes: encodeQuantisedMesh(mesh) });
+        }
+        else {
+            chunks.push(buildMesh(mesh));
+        }
     });
     for (const texture of source.textures ?? [])
         chunks.push(buildTexture(texture));

package/dist/index.d.ts

@@ -13,13 +13,17 @@ export type { DrftMorph, DrftNode } from './drftSkin.ts';
 export type { DrftSubs, DrftSubstanceEntry } from './drftSubs.ts';
 export { buildSubs, readSubs } from './drftSubs.ts';
 export type { DrftSdfv, DrftSdfvEntry } from './sdfv.ts';
-export { buildSdfv, readSdfv, SDFV_ENTRY_BYTES, SDFV_MAX_SAMPLES } from './sdfv.ts';
+export { buildSdfv, readSdfv, SDFV_ENTRY_BYTES, SDFV_MAX_SAMPLES, SDFV_WHOLE_FILE, } from './sdfv.ts';
 export { NNET_ENTRY_BYTES, NNET_MAX_HIDDEN, NNET_MAX_WIDTH, buildNnet, nnetWeightCount, readNnet, } from './nnet.ts';
 export type { DrftNetwork, DrftNnet } from './nnet.ts';
 export { buildNgrf, readNgrf } from './ngrf.ts';
 export type { DrftAttribute, DrftGraph, DrftGraphNode, DrftGraphTensor, DrftGraphValue, } from './ngrf.ts';
 export { buildClip, buildMorph, buildNodes, buildSkin, readClip, readMorph, readNodes, readSkin, } from './drftSkin.ts';
 export { MAX_COLLIDER_HULLS, MAX_COLLIDER_POINTS, buildColliders, readColliders, } from './drftColliders.ts';
+export { buildInstances, readInstances } from './drftInstances.ts';
+export { buildLights, readLights } from './drftLights.ts';
+export type { DrftLight, DrftLightKind } from './drftLights.ts';
+export type { DrftInstanceGroup } from './drftInstances.ts';
 export { buildDtex, readDtex, DTEX_ADDRESS_MODES, DTEX_MAX_TILES, DTEX_REGISTERS } from './dtex.ts';
 export type { DtexEntry, DtexMaterial } from './dtex.ts';
 export { buildNavm, readNavm } from './navm.ts';
@@ -28,8 +32,8 @@ export { buildEnts, readEnts } from './ents.ts';
 export type { EntsScene } from './ents.ts';
 export { readDrft } from './drftRead.ts';
 export type { DrftAsset, DrftTexture } from './drftRead.ts';
-export { DrftStream, streamDrft } from './drftStream.ts';
-export type { DrftManifest, DrftStreamHandlers } from './drftStream.ts';
+export { DEFAULT_STREAM_SLICE_MS, DrftStream, streamDrft } from './drftStream.ts';
+export type { DrftManifest, DrftStreamHandlers, DrftStreamPacing } from './drftStream.ts';
 export { writeDrft } from './drftWrite.ts';
 export type { DrftSource, DrftTextureSource } from './drftWrite.ts';
 export { DrftError, DRFT_VERSION_MAJOR, DRFT_VERSION_MINOR } from './drftFormat.ts';

package/dist/index.js

@@ -8,7 +8,7 @@
  */
 export { validateMeshData } from './meshData.js';
 export { buildSubs, readSubs } from './drftSubs.js';
-export { buildSdfv, readSdfv, SDFV_ENTRY_BYTES, SDFV_MAX_SAMPLES } from './sdfv.js';
+export { buildSdfv, readSdfv, SDFV_ENTRY_BYTES, SDFV_MAX_SAMPLES, SDFV_WHOLE_FILE, } from './sdfv.js';
 export { NNET_ENTRY_BYTES, NNET_MAX_HIDDEN, NNET_MAX_WIDTH, buildNnet, nnetWeightCount, readNnet, } from './nnet.js';
 export { buildNgrf, readNgrf } from './ngrf.js';
 export { buildClip, buildMorph, buildNodes, buildSkin, readClip, readMorph, readNodes, readSkin, } from './drftSkin.js';
@@ -20,6 +20,9 @@ export { buildClip, buildMorph, buildNodes, buildSkin, readClip, readMorph, read
  * of the format unable to disagree about a byte.
  */
 export { MAX_COLLIDER_HULLS, MAX_COLLIDER_POINTS, buildColliders, readColliders, } from './drftColliders.js';
+/* Meshes drawn many times, one matrix a copy, as the baker finds merged copies again. */
+export { buildInstances, readInstances } from './drftInstances.js';
+export { buildLights, readLights } from './drftLights.js';
 /*
  * **`DTEX`: a material as a decode program over a latent, rather than as pictures.** The chunk
  * carries no semantics — this package is the container and does not know what a channel means —
@@ -40,7 +43,7 @@ export { buildNavm, readNavm } from './navm.js';
 export { buildEnts, readEnts } from './ents.js';
 export { readDrft } from './drftRead.js';
 /* Reading one while it is still arriving, for a scene that would rather show a model build. */
-export { DrftStream, streamDrft } from './drftStream.js';
+export { DEFAULT_STREAM_SLICE_MS, DrftStream, streamDrft } from './drftStream.js';
 export { writeDrft } from './drftWrite.js';
 export { DrftError, DRFT_VERSION_MAJOR, DRFT_VERSION_MINOR } from './drftFormat.js';
 /* A consumer decoding an embedded texture has to know which codec it is holding. */

package/dist/meshData.js

@@ -94,9 +94,16 @@ export function validateMeshData(data) {
      * An index past the end is the same hazard from the other side, and the same latitude
      * applies: a driver may clamp it or refuse the draw. Scanned once at construction, which
      * is a cost paid when a mesh is built rather than when it is drawn.
+     *
+     * **The array is read once, outside the loop.** A mesh arrives in as many object shapes as there
+     * are combinations of optional fields, so `data.indices` is a megamorphic load, and one inside the
+     * loop is a lookup per index the compiler cannot hoist: 0.8 s of a five-pack load, five times what
+     * the same scan costs over a local.
      */
-    for (let at = 0; at < data.indices.length; at++) {
-        const index = data.indices[at];
+    const indices = data.indices;
+    const count = indices.length;
+    for (let at = 0; at < count; at++) {
+        const index = indices[at];
         if (index >= vertices) {
             throw new Error(`Mesh: index ${at} refers to vertex ${index}, but the mesh has ${vertices}. ` +
                 `Out-of-range indices may be clamped on one driver and reject the draw on another.`);

package/dist/sdfv.d.ts

@@ -42,6 +42,21 @@
  */
 /** `u32` mesh, three `u32` dimensions and six `f32` bounds. A field's samples are elsewhere. */
 export declare const SDFV_ENTRY_BYTES = 40;
+/**
+ * The mesh ordinal that means **the file's static geometry as a whole**, in the file's own space.
+ *
+ * **One field for a scene rather than one per mesh, because a scene is where per-mesh fields
+ * fail.** A bought courtyard exports its walls as a few meshes spanning the whole of it, so a field
+ * of thirty-two samples along each mesh's longest side is 1.2 m voxels on the walls that matter and
+ * 12.6 MB across four hundred meshes; one field over all of them at 25 cm is 3 MB and resolves a
+ * column. A reader places it with the file's own transform and nothing per mesh.
+ *
+ * **Additive, and it had to be checked rather than assumed**: no reader has ever compared an
+ * entry's ordinal with the mesh count, so a reader that predates this value reads the entry and
+ * pairs it with no mesh, which loses only the traced light it could not have used. What would make
+ * it wrong is a file whose static geometry moves, which is a file with more than one field.
+ */
+export declare const SDFV_WHOLE_FILE = 4294967295;
 /**
  * The most samples one field may declare.
  *

package/dist/sdfv.js

@@ -43,6 +43,21 @@
 import { DrftError, align } from './drftFormat.js';
 /** `u32` mesh, three `u32` dimensions and six `f32` bounds. A field's samples are elsewhere. */
 export const SDFV_ENTRY_BYTES = 40;
+/**
+ * The mesh ordinal that means **the file's static geometry as a whole**, in the file's own space.
+ *
+ * **One field for a scene rather than one per mesh, because a scene is where per-mesh fields
+ * fail.** A bought courtyard exports its walls as a few meshes spanning the whole of it, so a field
+ * of thirty-two samples along each mesh's longest side is 1.2 m voxels on the walls that matter and
+ * 12.6 MB across four hundred meshes; one field over all of them at 25 cm is 3 MB and resolves a
+ * column. A reader places it with the file's own transform and nothing per mesh.
+ *
+ * **Additive, and it had to be checked rather than assumed**: no reader has ever compared an
+ * entry's ordinal with the mesh count, so a reader that predates this value reads the entry and
+ * pairs it with no mesh, which loses only the traced light it could not have used. What would make
+ * it wrong is a file whose static geometry moves, which is a file with more than one field.
+ */
+export const SDFV_WHOLE_FILE = 0xffffffff;
 /**
  * The most samples one field may declare.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/drft",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "description": "The .drft container: a streaming format for baked 3D scenes",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,9 +27,9 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@driftengine/core": "4.3.0",
-    "@driftengine/entities": "4.3.0",
-    "@driftengine/texture": "4.3.0"
+    "@driftengine/core": "4.4.1",
+    "@driftengine/entities": "4.4.1",
+    "@driftengine/texture": "4.4.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/drftFormat.ts

@@ -23,7 +23,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;
@@ -259,6 +259,19 @@ export const CHUNK_NAVM = fourCC('NAVM');
  */
 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;
 
@@ -291,6 +304,8 @@ export const KNOWN_CHUNKS: ReadonlySet<number> = new Set([
   CHUNK_NGRF,
   CHUNK_NAVM,
   CHUNK_ENTS,
+  CHUNK_INST,
+  CHUNK_MSHQ,
 ]);
 
 /** Chunk flags. */
@@ -550,6 +565,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. */
@@ -564,7 +596,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;
 
 /** What `HEAD` says about the asset as a whole. */
 export interface DrftHead {

package/src/drftInstances.ts

@@ -0,0 +1,81 @@
+/**
+ * `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.ts';
+
+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 function buildInstances(groups: readonly DrftInstanceGroup[]): Uint8Array {
+  const seen = new Set<number>();
+  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] as number, true);
+      at += 4;
+    }
+  }
+  return bytes;
+}
+
+/** The groups in an `INST` payload, each checked against the file's mesh count. */
+export function readInstances(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+  meshCount: number,
+): DrftInstanceGroup[] {
+  const view = new DataView(buffer, offset, byteLength);
+  const count = view.getUint32(0, true);
+  const out: DrftInstanceGroup[] = [];
+  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/src/drftLights.ts

@@ -0,0 +1,131 @@
+/**
+ * `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.ts';
+
+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;
+}
+
+const KINDS: readonly DrftLightKind[] = ['point', 'spot', 'directional'];
+const LIGHT_BYTES = 64;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+export function buildLights(lights: readonly DrftLight[]): Uint8Array {
+  const names: string[] = [];
+  const nameIndex = new Map<string, number>();
+  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] as number, true);
+    at += LIGHT_BYTES;
+  }
+  return bytes;
+}
+
+/** The lights in a `LITE` payload. */
+export function readLights(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+): DrftLight[] {
+  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: string[] = [];
+  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: number): number => view.getFloat32(o, true);
+  const out: DrftLight[] = [];
+  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;
+}