@driftengine/drft 3.63.0 → 4.0.0

package/src/drftMeshlets.ts

@@ -0,0 +1,185 @@
+import { DrftError, align } from './drftFormat.ts';
+
+/**
+ * `MSHL`: the clusters a mesh draws as, and the level-of-detail graph over them.
+ *
+ * **One chunk per level, not one for the whole graph.** A level is a complete alternative mesh —
+ * its own positions, its own indices, its own clusters — so folding every level into one chunk
+ * would mean one payload whose parts are only meaningful together. Separate chunks let a loader
+ * stream the coarsest level first and refine, which is the same argument `coarseFirst.ts` already
+ * makes for splats.
+ *
+ * ```
+ * u32  clusterCount
+ * u32  indexTotal
+ * u32  triangleOffsets[clusterCount]   first triangle of each cluster
+ * u32  triangleCounts[clusterCount]
+ * f32  boundsCentre[clusterCount * 3]
+ * f32  boundsRadius[clusterCount]
+ * f32  coneAxis[clusterCount * 3]      average face normal, normalised
+ * f32  coneCutoff[clusterCount]        minimum dot of any face against the axis
+ * f32  ownError[clusterCount]          this cluster's geometric error
+ * f32  parentError[clusterCount]       the error of what replaces it one level up
+ * u32  indices[indexTotal]
+ * ```
+ *
+ * **No per-chunk version field**, matching `COLL` and every other chunk here: the file's own
+ * version covers the format and a second one would be a second thing to keep in step.
+ *
+ * **`parentError` may be infinite**, which is how the coarsest level says it has no parent. A
+ * float32 carries that exactly, so a reader needs no sentinel and a comparison against it needs
+ * no special case.
+ */
+
+/** How many clusters one level may carry. Well past what a streaming budget permits. */
+export const MAX_CLUSTERS = 1 << 20;
+
+export interface MeshletLevel {
+  triangleOffsets: Uint32Array;
+  triangleCounts: Uint32Array;
+  boundsCentre: Float32Array;
+  boundsRadius: Float32Array;
+  coneAxis: Float32Array;
+  coneCutoff: Float32Array;
+  ownError: Float32Array;
+  parentError: Float32Array;
+  indices: Uint32Array;
+  count: number;
+}
+
+const HEADER = 8;
+
+function layoutOf(clusterCount: number, indexTotal: number) {
+  const triangleOffsets = HEADER;
+  const triangleCounts = triangleOffsets + clusterCount * 4;
+  const boundsCentre = triangleCounts + clusterCount * 4;
+  const boundsRadius = boundsCentre + clusterCount * 12;
+  const coneAxis = boundsRadius + clusterCount * 4;
+  const coneCutoff = coneAxis + clusterCount * 12;
+  const ownError = coneCutoff + clusterCount * 4;
+  const parentError = ownError + clusterCount * 4;
+  const indices = parentError + clusterCount * 4;
+  return {
+    triangleOffsets,
+    triangleCounts,
+    boundsCentre,
+    boundsRadius,
+    coneAxis,
+    coneCutoff,
+    ownError,
+    parentError,
+    indices,
+    size: indices + indexTotal * 4,
+  };
+}
+
+export function buildMeshlets(level: MeshletLevel): Uint8Array {
+  const { count } = level;
+  if (count > MAX_CLUSTERS) {
+    throw new DrftError(`${count} clusters exceeds the ${MAX_CLUSTERS} cap`);
+  }
+  if (level.triangleOffsets.length < count || level.triangleCounts.length < count) {
+    throw new DrftError('MSHL was given fewer cluster offsets or counts than clusters');
+  }
+  if (level.indices.length % 3 !== 0) {
+    throw new DrftError(
+      `MSHL was given ${level.indices.length} indices, which is not whole triangles`,
+    );
+  }
+
+  /*
+   * Every cluster's triangles are checked to lie inside the index array before anything is
+   * written. A cluster running past the end would otherwise be a subarray of arbitrary geometry on
+   * the way back in, which is the same failure `COLL` checks its starts table for.
+   */
+  const triangles = level.indices.length / 3;
+  for (let c = 0; c < count; c += 1) {
+    const at = level.triangleOffsets[c] as number;
+    const n = level.triangleCounts[c] as number;
+    if (at + n > triangles) {
+      throw new DrftError(`MSHL cluster ${c} runs past the ${triangles} triangles it was given`);
+    }
+  }
+
+  const layout = layoutOf(count, level.indices.length);
+  const bytes = new Uint8Array(align(layout.size));
+  const view = new DataView(bytes.buffer);
+  view.setUint32(0, count, true);
+  view.setUint32(4, level.indices.length, true);
+
+  new Uint32Array(bytes.buffer, layout.triangleOffsets, count).set(
+    level.triangleOffsets.subarray(0, count),
+  );
+  new Uint32Array(bytes.buffer, layout.triangleCounts, count).set(
+    level.triangleCounts.subarray(0, count),
+  );
+  new Float32Array(bytes.buffer, layout.boundsCentre, count * 3).set(
+    level.boundsCentre.subarray(0, count * 3),
+  );
+  new Float32Array(bytes.buffer, layout.boundsRadius, count).set(
+    level.boundsRadius.subarray(0, count),
+  );
+  new Float32Array(bytes.buffer, layout.coneAxis, count * 3).set(
+    level.coneAxis.subarray(0, count * 3),
+  );
+  new Float32Array(bytes.buffer, layout.coneCutoff, count).set(level.coneCutoff.subarray(0, count));
+  new Float32Array(bytes.buffer, layout.ownError, count).set(level.ownError.subarray(0, count));
+  new Float32Array(bytes.buffer, layout.parentError, count).set(
+    level.parentError.subarray(0, count),
+  );
+  new Uint32Array(bytes.buffer, layout.indices, level.indices.length).set(level.indices);
+  return bytes;
+}
+
+/**
+ * The level an `MSHL` chunk carries, as views over the fetched buffer.
+ *
+ * Views rather than copies, like every other chunk here, so a load allocates nothing beyond the
+ * object holding them.
+ */
+export function readMeshlets(
+  buffer: ArrayBuffer,
+  offset: number,
+  byteLength: number,
+): MeshletLevel {
+  if (byteLength < HEADER) throw new DrftError('MSHL is too short to hold its counts');
+  const view = new DataView(buffer, offset, byteLength);
+  const count = view.getUint32(0, true);
+  const indexTotal = view.getUint32(4, true);
+
+  if (count > MAX_CLUSTERS) {
+    throw new DrftError(`MSHL claims ${count} clusters, over the ${MAX_CLUSTERS} cap`);
+  }
+  if (indexTotal % 3 !== 0) {
+    throw new DrftError(`MSHL claims ${indexTotal} indices, which is not whole triangles`);
+  }
+
+  const layout = layoutOf(count, indexTotal);
+  if (byteLength < layout.size) {
+    throw new DrftError(
+      `MSHL claims ${count} clusters and ${indexTotal} indices, which runs past the chunk`,
+    );
+  }
+
+  const triangleOffsets = new Uint32Array(buffer, offset + layout.triangleOffsets, count);
+  const triangleCounts = new Uint32Array(buffer, offset + layout.triangleCounts, count);
+  const triangles = indexTotal / 3;
+  for (let c = 0; c < count; c += 1) {
+    if ((triangleOffsets[c] as number) + (triangleCounts[c] as number) > triangles) {
+      throw new DrftError(`MSHL cluster ${c} runs past the ${triangles} triangles the chunk holds`);
+    }
+  }
+
+  return {
+    triangleOffsets,
+    triangleCounts,
+    boundsCentre: new Float32Array(buffer, offset + layout.boundsCentre, count * 3),
+    boundsRadius: new Float32Array(buffer, offset + layout.boundsRadius, count),
+    coneAxis: new Float32Array(buffer, offset + layout.coneAxis, count * 3),
+    coneCutoff: new Float32Array(buffer, offset + layout.coneCutoff, count),
+    ownError: new Float32Array(buffer, offset + layout.ownError, count),
+    parentError: new Float32Array(buffer, offset + layout.parentError, count),
+    indices: new Uint32Array(buffer, offset + layout.indices, indexTotal),
+    count,
+  };
+}

package/src/drftRead.ts

@@ -35,6 +35,9 @@ import {
   CHUNK_HEAD,
   CHUNK_LODM,
   CHUNK_LODF,
+  CHUNK_DTEX,
+  CHUNK_ENTS,
+  CHUNK_NAVM,
   CHUNK_SPLT,
   SPLAT_BLOCK_PREFIX,
   CHUNK_MESH,
@@ -53,11 +56,20 @@ import {
   CHUNK_NODE,
   CHUNK_SKIN,
   CHUNK_MORP,
+  CHUNK_NNET,
+  CHUNK_NGRF,
+  CHUNK_SDFV,
   CHUNK_SUBS,
   CHUNK_COLL,
 } from './drftFormat.ts';
 import type { DrftChunk, DrftHead, DrftMaterial, DrftSplatBlock } from './drftFormat.ts';
 import { type DrftSubs, readSubs } from './drftSubs.ts';
+import { type DrftSdfv, type DrftSdfvEntry, readSdfv } from './sdfv.ts';
+import { type DtexEntry, readDtex } from './dtex.ts';
+import { type EntsScene, readEnts } from './ents.ts';
+import { type NavPolyMesh, readNavm } from './navm.ts';
+import { type DrftNetwork, type DrftNnet, readNnet } from './nnet.ts';
+import { type DrftGraph, readNgrf } from './ngrf.ts';
 import { readColliders } from './drftColliders.ts';
 
 /** An embedded image, still compressed. Decoding is the consumer's, through `createImageBitmap`. */
@@ -108,6 +120,24 @@ export interface DrftAsset {
    * file's coarse-first order, so a consumer that draws a prefix of them draws a sparse whole.
    */
   readonly splats: DrftSplatBlock | null;
+  /**
+   * A decode program per material, or empty for a file that carries none.
+   *
+   * Each says which `MATL` entry it belongs to. **A reader that does not know this chunk skips it
+   * by its length** and loses only the material it could not have decoded, which is what keeps the
+   * format's freeze intact.
+   */
+  readonly dtex: readonly DtexEntry[];
+  /**
+   * A way across the scene, or `null` for a file that carries none.
+   *
+   * **`null` rather than an empty mesh**, because *nobody built one* and *there is nowhere to walk*
+   * are different facts, and a consumer that cannot tell them apart cannot decide whether to build
+   * one itself.
+   */
+  readonly navigation: NavPolyMesh | null;
+  /** The things in the scene, or `null` for a file that is an asset rather than a scene. */
+  readonly entities: EntsScene | null;
   /**
    * The asset's own hierarchy, or empty for a file carrying no `NODE`.
    *
@@ -129,6 +159,29 @@ export interface DrftAsset {
    * **exactly** and reports what it could not, rather than guessing.
    */
   readonly substances: readonly { readonly material: number; readonly substance: string }[];
+  /**
+   * The signed distance field of each mesh that carries one, or empty for a file with none.
+   *
+   * The `SDFV` chunk, added at 1.13. Views over the fetched buffer, so a file that carries fields
+   * for geometry a consumer never traces through costs one view apiece and no copy. Hand them to
+   * `composeGlobalField`, which is what turns per-object fields into a world around the camera.
+   */
+  readonly fields: readonly DrftSdfvEntry[];
+  /**
+   * The networks the file carries, each with the role a consumer asks for it by, or empty.
+   *
+   * The `NNET` chunk, added at 1.14. Weights are views over the fetched buffer, in the precision
+   * they were written in — half-precision bits stay bits, because the device uploads them as such.
+   */
+  readonly networks: readonly DrftNetwork[];
+  /**
+   * The graphs the file carries — networks built from operators — each with its role, or empty.
+   *
+   * The `NGRF` chunk, added at 1.15. Tensors are views over the fetched buffer where its alignment
+   * allows, in the precision they were written in. `@driftengine/texture` validates one before it
+   * runs, naming any operator it lacks.
+   */
+  readonly graphs: readonly DrftGraph[];
   /**
    * The convex hulls this asset collides as, or empty for a file carrying no `COLL`.
    *
@@ -300,11 +353,17 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
   const textures: DrftTexture[] = [];
   let materials: DrftMaterial[] = [];
   const splatBlocks: { block: DrftSplatBlock; at: number }[] = [];
+  const dtex: DtexEntry[] = [];
+  let navigation: NavPolyMesh | null = null;
+  let entities: EntsScene | null = null;
   let nodes: DrftNode[] = [];
   const skins: DrftSkin[] = [];
   const clips: AnimationClip[] = [];
   const morphs: DrftMorph[] = [];
   let subs: DrftSubs | null = null;
+  let fields: DrftSdfv | null = null;
+  let nnet: DrftNnet | null = null;
+  let graphs: DrftGraph[] = [];
   let colliders: readonly Float32Array[] = [];
   const skipped: string[] = [];
   let head: DrftHead | null = null;
@@ -357,6 +416,10 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
     else if (chunk.code === CHUNK_MATL) materials = readMaterials(buffer, chunk);
     else if (chunk.code === CHUNK_SPLT)
       splatBlocks.push({ block: readSplatBlock(buffer, chunk), at: chunk.index });
+    else if (chunk.code === CHUNK_DTEX) dtex.push(readDtex(buffer, chunk.offset, chunk.byteLength));
+    else if (chunk.code === CHUNK_NAVM)
+      navigation = readNavm(buffer, chunk.offset, chunk.byteLength);
+    else if (chunk.code === CHUNK_ENTS) entities = readEnts(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_NODE) nodes = readNodes(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_SKIN)
       skins.push(readSkin(buffer, chunk.offset, chunk.byteLength));
@@ -365,6 +428,9 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
     else if (chunk.code === CHUNK_MORP)
       morphs.push(readMorph(buffer, chunk.offset, chunk.byteLength));
     else if (chunk.code === CHUNK_SUBS) subs = readSubs(buffer, chunk.offset, chunk.byteLength);
+    else if (chunk.code === CHUNK_SDFV) fields = readSdfv(buffer, chunk.offset, chunk.byteLength);
+    else if (chunk.code === CHUNK_NNET) nnet = readNnet(buffer, chunk.offset, chunk.byteLength);
+    else if (chunk.code === CHUNK_NGRF) graphs = readNgrf(buffer, chunk.offset, chunk.byteLength);
     else if (chunk.code === CHUNK_COLL)
       colliders = readColliders(buffer, chunk.offset, chunk.byteLength);
     /* Every other known chunk is defined but not yet carried; see docs/FORMAT.md phase table. */
@@ -377,8 +443,16 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
    * for the absence of a chunk kind it never needed would be the format telling a consumer what
    * its scene may be made of.
    */
-  if (meshes.length === 0 && splatBlocks.length === 0) {
-    throw new DrftError('no MESH and no SPLT chunk — an asset with neither geometry nor a capture');
+  /* And networks, since 1.15: a converted model is weights and nothing else. */
+  if (
+    meshes.length === 0 &&
+    splatBlocks.length === 0 &&
+    (nnet?.networks.length ?? 0) === 0 &&
+    graphs.length === 0
+  ) {
+    throw new DrftError(
+      'no MESH, SPLT, NNET or NGRF chunk — an asset with no geometry, capture or network',
+    );
   }
 
   /*
@@ -448,7 +522,13 @@ export function readDrft(buffer: ArrayBuffer): DrftAsset {
     materials,
     textures,
     substances: subs?.entries ?? [],
+    fields: fields?.entries ?? [],
+    networks: nnet?.networks ?? [],
+    graphs,
     colliders,
+    dtex,
+    navigation,
+    entities,
     splats: joinSplatBlocks(splatBlocks),
     skipped,
     versionMajor,

package/src/drftWrite.ts

@@ -28,6 +28,9 @@ import {
   CHUNK_ENTRY_BYTES,
   CHUNK_HEAD,
   CHUNK_ANIM,
+  CHUNK_DTEX,
+  CHUNK_ENTS,
+  CHUNK_NAVM,
   CHUNK_LODM,
   CHUNK_LODF,
   CHUNK_MORP,
@@ -39,6 +42,9 @@ import {
   CHUNK_MESH,
   CHUNK_REQUIRED,
   CHUNK_COLL,
+  CHUNK_NNET,
+  CHUNK_NGRF,
+  CHUNK_SDFV,
   CHUNK_SUBS,
   CHUNK_TEXS,
   MATERIAL_ENTRY_BYTES,
@@ -53,6 +59,12 @@ import {
 import type { DrftHead, DrftMaterial, DrftSplats } from './drftFormat.ts';
 import { coarseFirstOrder } from './coarseFirst.ts';
 import { type DrftSubstanceEntry, buildSubs } from './drftSubs.ts';
+import { type DrftSdfvEntry, buildSdfv } from './sdfv.ts';
+import { type DrftNetwork, buildNnet } from './nnet.ts';
+import { type DtexEntry, buildDtex } from './dtex.ts';
+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';
 
 /** An image to embed, already compressed, with what its own header said about it. */
@@ -91,6 +103,25 @@ export interface DrftSource {
    * than by position, so a file labelling only its fourth material says so.
    */
   readonly substances?: readonly DrftSubstanceEntry[];
+  /**
+   * The signed distance field of each mesh that has one, or absent for a file carrying none.
+   *
+   * Written as one `SDFV` chunk at 1.13. It pairs by the mesh ordinal carried per entry rather
+   * than by position, so a file with a field for only its fourth mesh says so — `SUBS`'s rule,
+   * and `MORP` is the chunk that found out why it is a rule.
+   */
+  readonly fields?: readonly DrftSdfvEntry[];
+  /**
+   * The networks this file carries, or absent for a file carrying none.
+   *
+   * Written as one `NNET` chunk at 1.14, each network found by its role rather than by position.
+   */
+  readonly networks?: readonly DrftNetwork[];
+  /**
+   * The graphs this file carries — networks built from operators rather than dense layers — or
+   * absent for a file carrying none. Written as one `NGRF` chunk at 1.15, each found by its role.
+   */
+  readonly graphs?: readonly DrftGraph[];
   /**
    * The convex hulls this asset collides as, or absent for a file that carries none.
    *
@@ -136,6 +167,29 @@ export interface DrftSource {
    * `CHUNK_SPLT` for why it is several chunks rather than one.
    */
   readonly splats?: DrftSplats;
+  /**
+   * A decode program per material, or absent for a file whose materials are ordinary.
+   *
+   * One `DTEX` chunk each, **paired to a `MATL` entry by the index inside the chunk** rather than
+   * by the order they appear. A file may carry one for some of its materials and not others — a
+   * scene where one surface came from a capture and the rest were authored — and a reader pairing
+   * by position would hand the wrong material the wrong texture with nothing to fail on.
+   */
+  readonly dtex?: readonly DtexEntry[];
+  /**
+   * A way across the scene, or absent for a file nobody navigates.
+   *
+   * The mesh carries the origin and cell size it was built at, because the numbers in it are cell
+   * indices and a reader without those has a mesh in the wrong units at the wrong place.
+   */
+  readonly navigation?: NavPolyMesh;
+  /**
+   * The things in the scene, as `serializeWorld` wrote them.
+   *
+   * A *scene*, not an asset: this is what a capture proposes or an editor saves, and a file may
+   * carry geometry with no scene at all — which is every baked model this format has ever held.
+   */
+  readonly entities?: EntsScene;
 }
 
 /**
@@ -442,8 +496,20 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
    * ordinary asset and the reader accepts it, so refusing to write one would be the two halves of
    * the format disagreeing about what a file may contain.
    */
-  if (source.meshes.length === 0 && (source.splats === undefined || source.splats.count === 0)) {
-    throw new DrftError('an asset must contain at least one mesh or a capture with splats in it');
+  /*
+   * **And networks, since 1.15**, on the same argument: a converted model is weights and nothing
+   * else, and refusing it for the absence of geometry would be the format telling a consumer what
+   * an asset may be made of.
+   */
+  if (
+    source.meshes.length === 0 &&
+    (source.splats === undefined || source.splats.count === 0) &&
+    (source.networks?.length ?? 0) === 0 &&
+    (source.graphs?.length ?? 0) === 0
+  ) {
+    throw new DrftError(
+      'an asset must contain at least one mesh, a capture with splats in it, or a network',
+    );
   }
 
   const materials = source.materials;
@@ -508,6 +574,26 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
   for (const clip of source.clips ?? []) {
     chunks.push({ code: CHUNK_ANIM, flags: 0, bytes: buildClip(clip) });
   }
+  for (const entry of source.dtex ?? []) {
+    /*
+     * **Refused here rather than at the reader**, because a decode program for a material the file
+     * does not carry is a bake that went wrong, and the writer is where the author can still be
+     * told. A reader meeting one has nothing useful to do with it.
+     */
+    if (entry.material >= (source.materials?.length ?? 0)) {
+      throw new DrftError(
+        `drft: DTEX names material ${entry.material} and the file carries ` +
+          `${source.materials?.length ?? 0}`,
+      );
+    }
+    chunks.push({ code: CHUNK_DTEX, flags: 0, bytes: buildDtex(entry) });
+  }
+  if (source.navigation !== undefined) {
+    chunks.push({ code: CHUNK_NAVM, flags: 0, bytes: buildNavm(source.navigation) });
+  }
+  if (source.entities !== undefined) {
+    chunks.push({ code: CHUNK_ENTS, flags: 0, bytes: buildEnts(source.entities) });
+  }
   source.meshes.forEach((mesh, ordinal) => {
     /*
      * **Its deltas immediately before it, not after.** A streaming consumer uploads a mesh the
@@ -539,6 +625,30 @@ export function writeDrft(source: DrftSource): ArrayBuffer {
       bytes: buildSubs({ entries: source.substances as readonly DrftSubstanceEntry[] }),
     });
   }
+  /* And one `SDFV`, on exactly the same terms. */
+  if ((source.fields?.length ?? 0) > 0) {
+    chunks.push({
+      code: CHUNK_SDFV,
+      flags: 0,
+      bytes: buildSdfv({ entries: source.fields as readonly DrftSdfvEntry[] }),
+    });
+  }
+  /* And one `NNET`, on the same terms again. */
+  if ((source.networks?.length ?? 0) > 0) {
+    chunks.push({
+      code: CHUNK_NNET,
+      flags: 0,
+      bytes: buildNnet({ networks: source.networks as readonly DrftNetwork[] }),
+    });
+  }
+  /* And one `NGRF`, for the networks a perceptron's table cannot describe. */
+  if ((source.graphs?.length ?? 0) > 0) {
+    chunks.push({
+      code: CHUNK_NGRF,
+      flags: 0,
+      bytes: buildNgrf(source.graphs as readonly DrftGraph[]),
+    });
+  }
 
   /*
    * `COLL` last among the small chunks, because collision is the one thing a viewer never needs and