@driftengine/drft 4.2.1 → 4.4.0

package/src/drftWrite.ts

@@ -35,6 +35,9 @@ import {
   CHUNK_LODF,
   CHUNK_MORP,
   CHUNK_NODE,
+  CHUNK_INST,
+  CHUNK_LITE,
+  CHUNK_MSHQ,
   CHUNK_SKIN,
   CHUNK_SPLT,
   SPLAT_BLOCK_PREFIX,
@@ -66,6 +69,11 @@ import { type EntsScene, buildEnts } from './ents.ts';
 import { type NavPolyMesh, buildNavm } from './navm.ts';
 import { type DrftGraph, buildNgrf } from './ngrf.ts';
 import { buildColliders } from './drftColliders.ts';
+import { buildInstances } from './drftInstances.ts';
+import type { DrftInstanceGroup } from './drftInstances.ts';
+import { buildLights } from './drftLights.ts';
+import type { DrftLight } from './drftLights.ts';
+import { encodeQuantisedMesh } from './drftQuantised.ts';
 
 /** An image to embed, already compressed, with what its own header said about it. */
 export interface DrftTextureSource {
@@ -155,6 +163,19 @@ export interface DrftSource {
    * the meshes exactly as it always did, which is why this is additive.
    */
   readonly nodes?: readonly DrftNode[];
+  /**
+   * Meshes drawn many times: one `INST` chunk, written ahead of the geometry and required. The mesh
+   * a group names holds one copy; see `drftInstances.ts`.
+   */
+  readonly instances?: readonly DrftInstanceGroup[];
+  /** The lights the scene was authored with: one `LITE` chunk, optional. See `drftLights.ts`. */
+  readonly lights?: readonly DrftLight[];
+  /**
+   * Write each mesh as `MSHQ` rather than `MESH`: constants, 16-bit ranges and octahedral
+   * directions, about a third of the bytes, within the bounds `drftQuantised.ts` states. Off unless
+   * asked, so a caller writing a file gets the bytes it always got; the baker asks by default.
+   */
+  readonly quantise?: boolean;
   /** Skins, one `SKIN` chunk each, or absent for an asset that deforms nothing. */
   readonly skins?: readonly DrftSkin[];
   /** Clips, one `ANIM` chunk each, or absent for an asset that animates nothing. */
@@ -292,7 +313,11 @@ function encodeString(value: string): Uint8Array {
   return bytes;
 }
 
-function buildHead(head: Partial<DrftHead> | undefined, meshes: readonly MeshData[]): PendingChunk {
+function buildHead(
+  head: Partial<DrftHead> | undefined,
+  meshes: readonly MeshData[],
+  instances: readonly DrftInstanceGroup[] = [],
+): PendingChunk {
   /*
    * 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
@@ -304,17 +329,72 @@ function buildHead(head: Partial<DrftHead> | undefined, meshes: readonly MeshDat
   let maxX = -Infinity;
   let maxY = -Infinity;
   let maxZ = -Infinity;
-  for (const mesh of meshes) {
+  const placed = new Map<number, Float32Array>();
+  for (const group of instances) placed.set(group.mesh, group.transforms);
+  for (let m = 0; m < meshes.length; m++) {
+    const mesh = meshes[m] as MeshData;
+    const transforms = placed.get(m);
+    if (transforms === undefined) {
+      for (let at = 0; at + 2 < mesh.positions.length; at += 3) {
+        const x = mesh.positions[at] as number;
+        const y = mesh.positions[at + 1] as number;
+        const z = mesh.positions[at + 2] as number;
+        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] as number;
-      const y = mesh.positions[at + 1] as number;
-      const z = mesh.positions[at + 2] as number;
-      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] as number);
+      ly = Math.min(ly, mesh.positions[at + 1] as number);
+      lz = Math.min(lz, mesh.positions[at + 2] as number);
+      hx = Math.max(hx, mesh.positions[at] as number);
+      hy = Math.max(hy, mesh.positions[at + 1] as number);
+      hz = Math.max(hz, mesh.positions[at + 2] as number);
+    }
+    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] as number) * cx +
+          (transforms[k + 4] as number) * cy +
+          (transforms[k + 8] as number) * cz +
+          (transforms[k + 12] as number);
+        const y =
+          (transforms[k + 1] as number) * cx +
+          (transforms[k + 5] as number) * cy +
+          (transforms[k + 9] as number) * cz +
+          (transforms[k + 13] as number);
+        const z =
+          (transforms[k + 2] as number) * cx +
+          (transforms[k + 6] as number) * cy +
+          (transforms[k + 10] as number) * cz +
+          (transforms[k + 14] as number);
+        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)) {
@@ -478,6 +558,11 @@ function buildMaterials(materials: readonly DrftMaterial[]): PendingChunk {
     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 };
@@ -537,7 +622,7 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
    * 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: PendingChunk[] = [buildHead(source.head, source.meshes)];
+  const chunks: PendingChunk[] = [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
@@ -568,6 +653,28 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
   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 as readonly DrftInstanceGroup[]),
+    });
+  }
+  /* 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) });
   }
@@ -613,7 +720,12 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
         }),
       });
     }
-    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));
   /* One `SUBS` for the file, and only where something was labelled — an empty chunk would cost

package/src/index.ts

@@ -17,7 +17,13 @@ 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,
@@ -59,6 +65,11 @@ export {
   buildColliders,
   readColliders,
 } from './drftColliders.ts';
+/* Meshes drawn many times, one matrix a copy, as the baker finds merged copies again. */
+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';
 /*
  * **`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 —
@@ -83,8 +94,8 @@ export type { EntsScene } from './ents.ts';
 export { readDrft } from './drftRead.ts';
 export type { DrftAsset, DrftTexture } from './drftRead.ts';
 /* Reading one while it is still arriving, for a scene that would rather show a model build. */
-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/src/meshData.ts

@@ -288,9 +288,16 @@ export function validateMeshData(data: MeshData): void {
    * 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] as number;
+  const indices = data.indices;
+  const count = indices.length;
+  for (let at = 0; at < count; at++) {
+    const index = indices[at] as number;
     if (index >= vertices) {
       throw new Error(
         `Mesh: index ${at} refers to vertex ${index}, but the mesh has ${vertices}. ` +

package/src/sdfv.ts

@@ -46,6 +46,22 @@ import { DrftError, align } from './drftFormat.ts';
 /** `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.
  *