@driftengine/drft 4.4.2 → 4.6.0

package/src/drftAssembly.ts

@@ -0,0 +1,322 @@
+/**
+ * `KITS` and `MSHC`: a mesh carried as painted copies of a few pieces, rather than as its vertices.
+ *
+ * **What it is for is a world built from a kit.** A city of boxes, columns and cornices is a few
+ * thousand distinct shapes placed half a million times, each at its own size and in its own paint.
+ * Merged, its vertices are most of a gigabyte even quantised; as placements of the kit they are a
+ * few tens of megabytes. So a mesh may arrive as `MSHC` — a table of surfaces and, per copy, which
+ * piece, which surface, a 3×4 matrix and how its texture stretches — and is expanded by arithmetic
+ * into exactly the `MeshData` a `MESH` would have carried (`assemble.ts`). It stands in place of a
+ * `MESH` and counts as one in every ordinal, as `MSHQ` does, so materials and regions name it
+ * like any other.
+ *
+ * **`KITS` names the pieces, and is written ahead of the geometry.** A piece is an ordinary mesh
+ * that is drawn only inside the meshes assembled from it; without the declaration a streaming
+ * reader would upload every piece as a part and draw the whole kit at the origin. Both chunks are
+ * **required**, for the `INST` reason: a reader that skipped `KITS` would draw that kit, and one
+ * that skipped `MSHC` would draw nothing where a district stands. A refusal naming them is the
+ * honest answer, and what it gives up is opening such a file in a reader before 1.23.
+ *
+ * **A piece is shape; a copy is shape placed and painted.** A piece's colours, emissive and every
+ * other per-vertex constant are ignored — the copy's surface supplies them. A piece carries
+ * positions, normals, and texture coordinates with tangents where the mesh is textured, since the
+ * tangent is what says which way a coordinate runs, and so how a copy's stretch applies to it.
+ * **Its sway is shape too**: where the assembly carries `channel`, each copy takes its piece's, as
+ * a tree's rises from its root to its leaves however it is placed.
+ *
+ * Layout, little-endian:
+ * - `KITS`: u32 count, then that many u32 mesh ordinals, ascending;
+ * - `MSHC`: u32 attribute bits (a `MESH`'s, less skinning), u32 surface count, then
+ *   `SURFACE_FLOATS` f32 a surface; u32 copy count, then per copy u32 piece ordinal, u32 surface,
+ *   12 f32 of matrix (three columns, then the translation), 3 f32 of u stretch, 3 f32 of v stretch
+ *   and 2 f32 of offset: 88 bytes a copy.
+ */
+import {
+  ATTR_EMISSIVE_COLOR,
+  ATTR_GRAIN,
+  ATTR_LAYERS,
+  ATTR_RELIEF,
+  ATTR_ROUGHNESS,
+  ATTR_SPECULAR,
+  ATTR_TANGENT,
+  ATTR_UVS,
+  ATTR_CHANNEL,
+  DrftError,
+  align,
+} from './drftFormat.ts';
+import type { MeshData } from './meshData.ts';
+
+/** Where each value sits in a surface, whichever of them the mesh carries. */
+export const SURFACE = {
+  color: 0,
+  emissive: 3,
+  specular: 4,
+  emissiveColor: 5,
+  roughness: 8,
+  grain: 9,
+  relief: 10,
+  layer: 11,
+} as const;
+export const SURFACE_FLOATS = 12;
+/** A copy's matrix: three columns of the linear part, then the translation. */
+export const COPY_MATRIX_FLOATS = 12;
+/** A copy's texture stretch: u along each piece axis, v along each, then the offset. */
+export const COPY_UV_FLOATS = 8;
+const COPY_BYTES = 8 + (COPY_MATRIX_FLOATS + COPY_UV_FLOATS) * 4;
+
+/** The optional arrays an assembled mesh may carry. Skinning is a piece of a character, not a kit. */
+export const ASSEMBLY_ATTRIBUTES =
+  ATTR_SPECULAR |
+  ATTR_UVS |
+  ATTR_EMISSIVE_COLOR |
+  ATTR_ROUGHNESS |
+  ATTR_GRAIN |
+  ATTR_RELIEF |
+  ATTR_TANGENT |
+  ATTR_LAYERS |
+  ATTR_CHANNEL;
+
+export interface DrftAssembly {
+  /** Which optional arrays the expanded mesh carries, as a `MESH`'s attribute bits. */
+  readonly attributes: number;
+  /** `SURFACE_FLOATS` a surface, laid out as `SURFACE` says. */
+  readonly surfaces: Float32Array;
+  /** One kit piece a copy, by mesh ordinal. */
+  readonly pieces: Uint32Array;
+  /** One surface a copy. */
+  readonly surfaceOf: Uint32Array;
+  /** `COPY_MATRIX_FLOATS` a copy, taking the piece to where the copy stands. */
+  readonly transforms: Float32Array;
+  /**
+   * `COPY_UV_FLOATS` a copy. A coordinate is multiplied by how far the copy stretches the piece's
+   * own direction for it — `|stretch ⊙ t|` for the unit tangent `t`, the bitangent for v — so a
+   * unit box copied at 13 × 4 m with stretches of size over tile repeats its texture in metres,
+   * face by face. `(1, 1, 1)` twice and no offset leave a piece's coordinates as they are.
+   */
+  readonly uv: Float32Array;
+}
+
+/** Whether a mesh slot holds an assembly rather than vertices. */
+export function isAssembly(mesh: object): mesh is DrftAssembly {
+  return 'pieces' in mesh && 'surfaceOf' in mesh;
+}
+
+export function buildKit(ordinals: readonly number[]): Uint8Array {
+  const out = new Uint8Array(align(4 + ordinals.length * 4));
+  const view = new DataView(out.buffer);
+  view.setUint32(0, ordinals.length, true);
+  ordinals.forEach((o, i) => view.setUint32(4 + i * 4, o, true));
+  return out;
+}
+
+/** The kit's pieces, ascending and each a mesh the file carries. */
+export function readKit(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+  meshCount: number,
+): number[] {
+  const view = new DataView(buffer, offset, byteLength);
+  if (byteLength < 4) throw new DrftError('KITS ends inside its count');
+  const count = view.getUint32(0, true);
+  if (4 + count * 4 > byteLength) throw new DrftError('KITS ends inside its pieces');
+  const out: number[] = [];
+  for (let i = 0; i < count; i++) out.push(view.getUint32(4 + i * 4, true));
+  checkKit(out, meshCount);
+  return out;
+}
+
+export function checkKit(ordinals: readonly number[], meshCount: number): void {
+  let previous = -1;
+  for (const o of ordinals) {
+    if (o >= meshCount)
+      throw new DrftError(`KITS names mesh ${o}, and the file carries ${meshCount}`);
+    if (o <= previous) throw new DrftError('KITS names its pieces out of order or twice');
+    previous = o;
+  }
+}
+
+export function buildAssembly(assembly: DrftAssembly): Uint8Array {
+  const copies = assembly.pieces.length;
+  const bytes = 12 + assembly.surfaces.length * 4 + copies * COPY_BYTES;
+  const out = new Uint8Array(align(bytes));
+  const view = new DataView(out.buffer);
+  let at = 0;
+  const u32 = (v: number): void => {
+    view.setUint32(at, v, true);
+    at += 4;
+  };
+  const f32 = (v: number): void => {
+    view.setFloat32(at, v, true);
+    at += 4;
+  };
+  u32(assembly.attributes);
+  u32(assembly.surfaces.length / SURFACE_FLOATS);
+  for (let i = 0; i < assembly.surfaces.length; i++) f32(assembly.surfaces[i] as number);
+  u32(copies);
+  for (let c = 0; c < copies; c++) {
+    u32(assembly.pieces[c] as number);
+    u32(assembly.surfaceOf[c] as number);
+    for (let i = 0; i < COPY_MATRIX_FLOATS; i++)
+      f32(assembly.transforms[c * COPY_MATRIX_FLOATS + i] as number);
+    for (let i = 0; i < COPY_UV_FLOATS; i++) f32(assembly.uv[c * COPY_UV_FLOATS + i] as number);
+  }
+  if (at !== bytes) throw new DrftError(`internal: MSHC wrote ${at} of ${bytes} bytes`);
+  return out;
+}
+
+/** One `MSHC` payload, checked on its own; its pieces are the caller's to check. */
+export function readAssembly(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+): DrftAssembly {
+  const view = new DataView(buffer, offset, byteLength);
+  let at = 0;
+  const need = (bytes: number, what: string): void => {
+    if (at + bytes > byteLength) throw new DrftError(`MSHC ends inside ${what}`);
+  };
+  need(8, 'its header');
+  const attributes = view.getUint32(0, true);
+  const surfaceCount = view.getUint32(4, true);
+  at = 8;
+  need(surfaceCount * SURFACE_FLOATS * 4 + 4, 'its surfaces');
+  const surfaces = new Float32Array(surfaceCount * SURFACE_FLOATS);
+  for (let i = 0; i < surfaces.length; i++) surfaces[i] = view.getFloat32(at + i * 4, true);
+  at += surfaces.length * 4;
+  const copies = view.getUint32(at, true);
+  at += 4;
+  need(copies * COPY_BYTES, 'its copies');
+  const pieces = new Uint32Array(copies);
+  const surfaceOf = new Uint32Array(copies);
+  const transforms = new Float32Array(copies * COPY_MATRIX_FLOATS);
+  const uv = new Float32Array(copies * COPY_UV_FLOATS);
+  for (let c = 0; c < copies; c++) {
+    pieces[c] = view.getUint32(at, true);
+    surfaceOf[c] = view.getUint32(at + 4, true);
+    at += 8;
+    for (let i = 0; i < COPY_MATRIX_FLOATS; i++, at += 4)
+      transforms[c * COPY_MATRIX_FLOATS + i] = view.getFloat32(at, true);
+    for (let i = 0; i < COPY_UV_FLOATS; i++, at += 4)
+      uv[c * COPY_UV_FLOATS + i] = view.getFloat32(at, true);
+  }
+  const assembly = { attributes, surfaces, pieces, surfaceOf, transforms, uv };
+  checkAssembly(assembly, 'MSHC');
+  return assembly;
+}
+
+/**
+ * What an assembly must be on its own: known bits, whole records, surfaces it names, finite
+ * numbers, whole layers, and no copy flattened to nothing — whose normals would be a division by
+ * zero rather than a direction.
+ */
+export function checkAssembly(assembly: DrftAssembly, name: string): void {
+  const { attributes, surfaces, pieces, surfaceOf, transforms, uv } = assembly;
+  if ((attributes & ~ASSEMBLY_ATTRIBUTES) !== 0) {
+    throw new DrftError(`${name} carries attribute bits ${attributes} an assembly cannot`);
+  }
+  if ((attributes & ATTR_LAYERS) !== 0 && (attributes & ATTR_UVS) === 0) {
+    throw new DrftError(`${name} names layers without texture coordinates for them to ride with`);
+  }
+  if ((attributes & ATTR_UVS) !== 0 && (attributes & ATTR_TANGENT) === 0) {
+    throw new DrftError(
+      `${name} is textured without tangents; a copy's stretch follows the piece's tangent`,
+    );
+  }
+  const copies = pieces.length;
+  if (
+    surfaces.length % SURFACE_FLOATS !== 0 ||
+    surfaceOf.length !== copies ||
+    transforms.length !== copies * COPY_MATRIX_FLOATS ||
+    uv.length !== copies * COPY_UV_FLOATS
+  ) {
+    throw new DrftError(`${name}'s surfaces and copies are not whole records`);
+  }
+  const surfaceCount = surfaces.length / SURFACE_FLOATS;
+  for (let s = 0; s < surfaceCount; s++) {
+    for (let i = 0; i < SURFACE_FLOATS; i++) {
+      if (!Number.isFinite(surfaces[s * SURFACE_FLOATS + i] as number)) {
+        throw new DrftError(`${name}'s surface ${s} is not finite`);
+      }
+    }
+    const layer = surfaces[s * SURFACE_FLOATS + SURFACE.layer] as number;
+    if (!(layer >= 0) || Math.floor(layer) !== layer) {
+      throw new DrftError(`${name}'s surface ${s} names layer ${layer}, not a whole number`);
+    }
+  }
+  for (let c = 0; c < copies; c++) {
+    if ((surfaceOf[c] as number) >= surfaceCount) {
+      throw new DrftError(`${name}'s copy ${c} wears surface ${surfaceOf[c]} of ${surfaceCount}`);
+    }
+    const m = c * COPY_MATRIX_FLOATS;
+    for (let i = 0; i < COPY_MATRIX_FLOATS; i++) {
+      if (!Number.isFinite(transforms[m + i] as number)) {
+        throw new DrftError(`${name}'s copy ${c} has a matrix that is not finite`);
+      }
+    }
+    for (let i = 0; i < COPY_UV_FLOATS; i++) {
+      if (!Number.isFinite(uv[c * COPY_UV_FLOATS + i] as number)) {
+        throw new DrftError(`${name}'s copy ${c} has a texture stretch that is not finite`);
+      }
+    }
+    if (Math.abs(determinant(transforms, m)) < 1e-12) {
+      throw new DrftError(`${name}'s copy ${c} is flattened to nothing by its matrix`);
+    }
+  }
+}
+
+/** The determinant of the linear part of the copy matrix at `m`. */
+export function determinant(t: ArrayLike<number>, m: number): number {
+  const a = t[m] as number;
+  const b = t[m + 1] as number;
+  const c = t[m + 2] as number;
+  const d = t[m + 3] as number;
+  const e = t[m + 4] as number;
+  const f = t[m + 5] as number;
+  const g = t[m + 6] as number;
+  const h = t[m + 7] as number;
+  const i = t[m + 8] as number;
+  return a * (e * i - f * h) - d * (b * i - c * h) + g * (b * f - c * e);
+}
+
+/**
+ * What an assembly must be to the kit around it: every copy a declared piece that comes before it
+ * in the file — so a streaming reader holds the piece when the copy lands — and every piece
+ * carrying what the assembly asks of it. Shared by the writer and both readers, so a file one
+ * refuses the others refuse too.
+ */
+export function checkCopies(
+  assembly: DrftAssembly,
+  ordinal: number,
+  kit: ReadonlySet<number>,
+  piece: (ordinal: number) => MeshData | undefined,
+): void {
+  const textured = (assembly.attributes & ATTR_UVS) !== 0;
+  const tangents = textured || (assembly.attributes & ATTR_TANGENT) !== 0;
+  const seen = new Set<number>();
+  for (let c = 0; c < assembly.pieces.length; c++) {
+    const o = assembly.pieces[c] as number;
+    if (seen.has(o)) continue;
+    seen.add(o);
+    if (!kit.has(o)) {
+      throw new DrftError(`mesh ${ordinal} copies mesh ${o}, which KITS does not name a piece`);
+    }
+    if (o >= ordinal) {
+      throw new DrftError(
+        `mesh ${ordinal} copies piece ${o}, which comes after it; a piece is written before the meshes assembled from it`,
+      );
+    }
+    const mesh = piece(o);
+    if (mesh === undefined)
+      throw new DrftError(`mesh ${ordinal} copies piece ${o}, which has not arrived`);
+    if (textured && mesh.uvs === undefined) {
+      throw new DrftError(`mesh ${ordinal} is textured and piece ${o} has no texture coordinates`);
+    }
+    if (tangents && mesh.tangents === undefined) {
+      throw new DrftError(`mesh ${ordinal} needs tangents and piece ${o} has none`);
+    }
+    if ((assembly.attributes & ATTR_CHANNEL) !== 0 && mesh.channel === undefined) {
+      throw new DrftError(`mesh ${ordinal} sways and piece ${o} carries no channel to sway by`);
+    }
+  }
+}

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 = 18;
+export const DRFT_VERSION_MINOR = 23;
 
 /** Bytes before the chunk table. */
 export const HEADER_BYTES = 32;
@@ -272,6 +272,37 @@ export const CHUNK_INST = fourCC('INST');
  */
 export const CHUNK_MSHQ = fourCC('MSHQ');
 
+/**
+ * One region of a streamed world: its levels of detail as mesh ordinals, its prop groups, its
+ * occluders and its collision. **Required**, one chunk per region, written just ahead of the meshes
+ * it introduces; see `drftRegions.ts`. Added in 1.21.
+ */
+export const CHUNK_REGN = fourCC('REGN');
+
+/**
+ * A world's fixed lights summed offline into one dense volume. Optional: a reader that skips it
+ * loses the glow of every light past the ones it shades exactly. See `drftLightVolume.ts`. Added in
+ * 1.22.
+ */
+export const CHUNK_LVOL = fourCC('LVOL');
+
+/**
+ * The meshes that are pieces of a kit, drawn only as copies inside assembled meshes. **Required**,
+ * and written ahead of the geometry; see `drftAssembly.ts`. Added in 1.23.
+ */
+export const CHUNK_KITS = fourCC('KITS');
+
+/**
+ * A mesh carried as painted copies of kit pieces, expanded on read into the `MeshData` a `MESH`
+ * gives. **Required**, and counted as a mesh in every ordinal. See `drftAssembly.ts`. Added in 1.23.
+ */
+export const CHUNK_MSHC = fourCC('MSHC');
+
+/** Whether a chunk is a mesh in the ordinal sequence: plain, quantised or assembled. */
+export function isMeshChunk(code: number): boolean {
+  return code === CHUNK_MESH || code === CHUNK_MSHQ || code === CHUNK_MSHC;
+}
+
 /** Bytes before the records in a `SPLT` payload. See `DrftSplatBlock` for the fields. */
 export const SPLAT_BLOCK_PREFIX = 40;
 
@@ -306,6 +337,10 @@ export const KNOWN_CHUNKS: ReadonlySet<number> = new Set([
   CHUNK_ENTS,
   CHUNK_INST,
   CHUNK_MSHQ,
+  CHUNK_REGN,
+  CHUNK_LVOL,
+  CHUNK_KITS,
+  CHUNK_MSHC,
 ]);
 
 /** Chunk flags. */
@@ -393,6 +428,26 @@ 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;
 
+/**
+ * Added in 1.20: which image of a texture array each vertex's face wears. See `MeshData.layers`.
+ *
+ * Next free bit, appended last, for the reason `grain` gives at length: a 1.19 reader meets the
+ * arrays it knows where it expects them, stops before this one, and draws every face at layer 0 —
+ * the first image of the array, which is what a reader that has never heard of layers should
+ * produce.
+ */
+export const ATTR_LAYERS = 1 << 9;
+
+/**
+ * Added in 1.23: `MeshData.channel`, four floats a vertex — sway, sky, opacity, and a spare lane.
+ *
+ * **The writer dropped it without a word until then**, which is the silent kind of missing: a tree
+ * baked with its sway came back still, and nothing said the lane had not been written. Next free
+ * bit, appended last, so a 1.22 reader meets every array it knows where it expects them, stops
+ * before this one, and draws the mesh planted, sunlit and opaque — the absent lane's own meaning.
+ */
+export const ATTR_CHANNEL = 1 << 10;
+
 /** Everything this version defines, so a reader can spot bits from a later writer. */
 export const ATTR_KNOWN =
   ATTR_SPECULAR |
@@ -403,7 +458,9 @@ export const ATTR_KNOWN =
   ATTR_RELIEF |
   ATTR_TANGENT |
   ATTR_JOINTS |
-  ATTR_WEIGHTS;
+  ATTR_WEIGHTS |
+  ATTR_LAYERS |
+  ATTR_CHANNEL;
 
 /**
  * How a `TEXS` payload is encoded.
@@ -582,10 +639,19 @@ export interface DrftMaterial {
    * tree's cards are not drawn. Absent means false, which is how every surface before it was drawn.
    */
   readonly doubleSided?: boolean;
+  /**
+   * Glass, 1.19: the share of light that passes, 0 opaque to 1 clear. Absent or 0 is not glass,
+   * which is what every surface before it was. See the engine's `glass.ts`.
+   */
+  readonly transmission?: number;
+  /** How milky the glass is, 0 see-through to 1 fully diffusing. 1.19. */
+  readonly frost?: number;
+  /** The colour light takes through the glass; white is clear. 1.19. */
+  readonly tint?: readonly [number, number, number];
 }
 
 /** Floats in a `MATL` entry, then the signed texture indices that follow them. */
-export const MATERIAL_FLOATS = 15;
+export const MATERIAL_FLOATS = 20;
 /**
  * Albedo, normal, ORM and emissive.
  *
@@ -596,7 +662,11 @@ 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;
-/** A `u32` of flags after them, since 1.18: bit 0 is `blend`, bit 1 is `doubleSided`. */
+/**
+ * A `u32` of flags after them, since 1.18: bit 0 is `blend`, bit 1 is `doubleSided`. Glass's five
+ * floats — transmission, frost, tint — follow the flags word, since 1.19, which is why the float
+ * count is twenty while the entry is still laid out floats, indices, flags, floats.
+ */
 export const MATERIAL_FLAGS = 1;
 export const MATERIAL_ENTRY_BYTES = MATERIAL_FLOATS * 4 + MATERIAL_INDICES * 4 + MATERIAL_FLAGS * 4;
 

package/src/drftLightVolume.ts

@@ -0,0 +1,179 @@
+/**
+ * `LVOL`: a world's fixed lights summed into one dense volume offline, as the renderer reads it.
+ *
+ * **Optional, because the file is whole without it.** A reader that skips it draws the world lit by
+ * the lights it shades exactly and loses the glow of every light past them — less, not wrong.
+ *
+ * **Runs, because most of a city's volume is dark.** Lamps reach thirty metres and the volume stands
+ * a hundred and more, so the samples above the light are nothing, and a sample inside a building is
+ * nothing of another kind: it is not a sample at all, which the shader's filtering must be told.
+ * So samples are written in order as runs of three kinds — dark air, solid, and literal — and only a
+ * literal run carries values, eight half floats a sample: the colour and whether it is a sample,
+ * then the direction light arrives from.
+ *
+ * Layout, little-endian:
+ * - f32 × 3 origin, f32 spacing, u32 × 3 samples on each axis;
+ * - runs until every sample is covered, each a u32 whose top two bits are the kind (0 dark air,
+ *   1 solid, 2 literal) and whose low thirty are the count, a literal followed by its halves.
+ */
+import { DrftError, align } from './drftFormat.ts';
+
+/** The same shape as core's `DenseLightVolume`, so a read volume goes straight to the renderer. */
+export interface DrftLightVolume {
+  readonly origin: readonly [number, number, number];
+  readonly spacing: number;
+  readonly dims: readonly [number, number, number];
+  /** Four floats a sample, x fastest: the colour, then 1 for a sample and 0 inside solid. */
+  readonly light: Float32Array;
+  /** Four floats a sample: the direction light arrives from, then 0. */
+  readonly direction: Float32Array;
+}
+
+const DARK = 0;
+const SOLID = 1;
+const LITERAL = 2;
+const COUNT_MASK = 0x3fffffff;
+
+function kindOf(volume: DrftLightVolume, sample: number): number {
+  const at = sample * 4;
+  const light = volume.light;
+  const lit =
+    light[at] !== 0 ||
+    light[at + 1] !== 0 ||
+    light[at + 2] !== 0 ||
+    volume.direction[at] !== 0 ||
+    volume.direction[at + 1] !== 0 ||
+    volume.direction[at + 2] !== 0;
+  if (lit) return LITERAL;
+  if (light[at + 3] === 1) return DARK;
+  if (light[at + 3] === 0) return SOLID;
+  return LITERAL;
+}
+
+export function buildLightVolume(volume: DrftLightVolume): Uint8Array {
+  const count = volume.dims[0] * volume.dims[1] * volume.dims[2];
+  if (volume.light.length !== count * 4 || volume.direction.length !== count * 4) {
+    throw new DrftError(`a light volume of ${count} samples needs ${count * 4} floats a channel`);
+  }
+  if (!(volume.spacing > 0)) throw new DrftError(`a light volume's spacing is ${volume.spacing}`);
+  /* Measured first, so the payload is allocated once. */
+  let bytes = 28;
+  for (let sample = 0; sample < count;) {
+    const kind = kindOf(volume, sample);
+    let end = sample + 1;
+    while (end < count && end - sample < COUNT_MASK && kindOf(volume, end) === kind) end++;
+    bytes += 4 + (kind === LITERAL ? (end - sample) * 16 : 0);
+    sample = end;
+  }
+  const out = new Uint8Array(align(bytes));
+  const view = new DataView(out.buffer);
+  for (let i = 0; i < 3; i++) view.setFloat32(i * 4, volume.origin[i] as number, true);
+  view.setFloat32(12, volume.spacing, true);
+  for (let i = 0; i < 3; i++) view.setUint32(16 + i * 4, volume.dims[i] as number, true);
+  let at = 28;
+  for (let sample = 0; sample < count;) {
+    const kind = kindOf(volume, sample);
+    let end = sample + 1;
+    while (end < count && end - sample < COUNT_MASK && kindOf(volume, end) === kind) end++;
+    view.setUint32(at, ((kind << 30) | (end - sample)) >>> 0, true);
+    at += 4;
+    if (kind === LITERAL) {
+      for (let s = sample; s < end; s++) {
+        for (let c = 0; c < 4; c++) {
+          view.setUint16(at, halfOf(volume.light[s * 4 + c] as number), true);
+          view.setUint16(at + 8, halfOf(volume.direction[s * 4 + c] as number), true);
+          at += 2;
+        }
+        at += 8;
+      }
+    }
+    sample = end;
+  }
+  return out;
+}
+
+export function readLightVolume(
+  buffer: ArrayBufferLike,
+  offset: number,
+  byteLength: number,
+): DrftLightVolume {
+  if (byteLength < 28) throw new DrftError('LVOL ends inside its header');
+  const view = new DataView(buffer, offset, byteLength);
+  const origin: [number, number, number] = [
+    view.getFloat32(0, true),
+    view.getFloat32(4, true),
+    view.getFloat32(8, true),
+  ];
+  const spacing = view.getFloat32(12, true);
+  const dims: [number, number, number] = [
+    view.getUint32(16, true),
+    view.getUint32(20, true),
+    view.getUint32(24, true),
+  ];
+  const count = dims[0] * dims[1] * dims[2];
+  if (!(spacing > 0) || count === 0) {
+    throw new DrftError(`LVOL has spacing ${spacing} and ${dims.join(' x ')} samples`);
+  }
+  const light = new Float32Array(count * 4);
+  const direction = new Float32Array(count * 4);
+  let at = 28;
+  let sample = 0;
+  while (sample < count) {
+    if (at + 4 > byteLength) throw new DrftError(`LVOL ends at sample ${sample} of ${count}`);
+    const word = view.getUint32(at, true);
+    at += 4;
+    const kind = word >>> 30;
+    const run = word & COUNT_MASK;
+    if (run === 0 || sample + run > count || kind > LITERAL) {
+      throw new DrftError(`LVOL has a run of ${run} of kind ${kind} at sample ${sample}`);
+    }
+    if (kind === DARK) {
+      for (let s = sample; s < sample + run; s++) light[s * 4 + 3] = 1;
+    } else if (kind === LITERAL) {
+      if (at + run * 16 > byteLength) throw new DrftError(`LVOL ends inside sample ${sample}`);
+      for (let s = sample; s < sample + run; s++) {
+        for (let c = 0; c < 4; c++) {
+          light[s * 4 + c] = floatOf(view.getUint16(at, true));
+          direction[s * 4 + c] = floatOf(view.getUint16(at + 8, true));
+          at += 2;
+        }
+        at += 8;
+      }
+    }
+    sample += run;
+  }
+  return { origin, spacing, dims, light, direction };
+}
+
+const scratchFloat = new Float32Array(1);
+const scratchWord = new Uint32Array(scratchFloat.buffer);
+
+/** A float as IEEE half-precision bits, rounded to nearest, overflow to infinity. */
+function halfOf(value: number): number {
+  scratchFloat[0] = value;
+  const word = scratchWord[0] as number;
+  const sign = (word >>> 16) & 0x8000;
+  const exponent = ((word >>> 23) & 0xff) - 127 + 15;
+  const mantissa = word & 0x7fffff;
+  if (exponent >= 31)
+    return sign | 0x7c00 | (((word >>> 23) & 0xff) === 0xff && mantissa ? 0x200 : 0);
+  if (exponent <= 0) {
+    if (exponent < -10) return sign;
+    const full = mantissa | 0x800000;
+    const shift = 14 - exponent;
+    const rounded = (full + (1 << (shift - 1))) >> shift;
+    return sign | rounded;
+  }
+  const rounded = (exponent << 10) + ((mantissa + 0x1000) >> 13);
+  return sign | Math.min(rounded, 0x7c00);
+}
+
+/** IEEE half-precision bits as a float. */
+function floatOf(bits: number): number {
+  const sign = bits & 0x8000 ? -1 : 1;
+  const exponent = (bits >> 10) & 0x1f;
+  const mantissa = bits & 0x3ff;
+  if (exponent === 0) return sign * mantissa * 2 ** -24;
+  if (exponent === 31) return mantissa ? Number.NaN : sign * Number.POSITIVE_INFINITY;
+  return sign * (1 + mantissa / 1024) * 2 ** (exponent - 15);
+}

package/src/drftQuantised.ts

@@ -33,6 +33,8 @@ import {
   ATTR_TANGENT,
   ATTR_UVS,
   ATTR_WEIGHTS,
+  ATTR_LAYERS,
+  ATTR_CHANNEL,
   DrftError,
   align,
 } from './drftFormat.ts';
@@ -60,7 +62,9 @@ type Name =
   | 'relief'
   | 'tangents'
   | 'joints'
-  | 'weights';
+  | 'weights'
+  | 'layers'
+  | 'channel';
 
 /** The frozen order `MESH` uses, with each optional array's bit: `FORMAT.md` §4.3. */
 const ORDER: readonly {
@@ -82,6 +86,9 @@ const ORDER: readonly {
   { name: 'tangents', width: 4, bit: ATTR_TANGENT, kind: 'direction' },
   { name: 'joints', width: 4, bit: ATTR_JOINTS, kind: 'exact' },
   { name: 'weights', width: 4, bit: ATTR_WEIGHTS, kind: 'value' },
+  /* Whole numbers naming an image, so exact: a layer quantised onto its neighbour is another picture. */
+  { name: 'layers', width: 1, bit: ATTR_LAYERS, kind: 'exact' },
+  { name: 'channel', width: 4, bit: ATTR_CHANNEL, kind: 'value' },
 ];
 
 /** A growing little-endian byte list, for the writer: offline, so it may allocate. */