@driftengine/assets 3.61.0

package/src/loadProgress.ts

@@ -0,0 +1,131 @@
+import type { MeshHandle } from '@driftengine/core';
+
+/**
+ * The vocabulary of a load in flight: which phase it is in, how far it has got, and what a
+ * finished part is.
+ *
+ * Separate from the loader because these three are what a consumer's progress bar is written
+ * against, and reading them should not mean paging through a thousand-line class.
+ */
+
+/**
+ * Where a load has got to, in the order a file delivers it.
+ *
+ * These are the chunk kinds rather than invented steps, which is the argument docs/FORMAT.md
+ * §4.6 makes for the whole design: the format's own layout is the sequence a viewer sees.
+ */
+export type DrftLoadPhase =
+  | 'idle'
+  | 'connecting'
+  | 'manifest'
+  /** A coarse whole model has landed: the asset is on screen, at the resolution it arrived at. */
+  | 'outline'
+  | 'materials'
+  | 'geometry'
+  | 'textures'
+  | 'ready'
+  | 'absent'
+  | 'failed';
+
+/**
+ * How far a load has got, and every field here now answers about the *picture* rather than about
+ * the work.
+ *
+ * **This was not true until it was reported.** `imagesDone` counted an image when its bytes
+ * arrived, and the decode that follows is deliberately not awaited so a slow one never holds up
+ * the stream. So there was a window in which `fraction` was 1, every part was uploaded and
+ * `imagesDone` equalled `imagesTotal`, while the surfaces wearing those images still drew
+ * untextured. Measured by a consumer across a scenario switch: **one and three quarter seconds.**
+ *
+ * It cost more than a harness photographing the wrong frame, which is how it was found. The same
+ * consumer drives a loading bar off these counters, so the bar reached 100% and the model then
+ * visibly changed underneath somebody who had been told it was finished. Their argument for the
+ * trade is the one that decided it: a bar that sits still for a moment is honest about being
+ * busy, and a bar that finishes early and then lets the thing it loaded change is not, and nobody
+ * can tell the second one is happening.
+ *
+ * So an image counts when it is **on the GPU**. `fraction` reaches 1 when the picture is right,
+ * and the cost is that it pauses near the end while the last decodes finish. On a weighted bar
+ * that pause is not at 99%: parts and images carry separate shares, so it climbs to roughly two
+ * thirds on the uploads and waits there, and a bar that stops at two thirds reads as working
+ * where one that stops at 99% reads as stuck.
+ *
+ * `phase === 'ready'` remains the signal to *act* on, and is what anything judging the finished
+ * picture should gate on.
+ */
+export interface DrftLoadProgress {
+  readonly phase: DrftLoadPhase;
+  /** 0 to 1, weighted by what the manifest says the file is actually made of. */
+  readonly fraction: number;
+  readonly partsDone: number;
+  readonly partsTotal: number;
+  /**
+   * Images that are **on the GPU**, not images whose bytes have arrived.
+   *
+   * A decode that fails counts too, because the alternative to counting it is a bar that can
+   * never finish as the price of one image that was never going to draw.
+   */
+  readonly imagesDone: number;
+  readonly imagesTotal: number;
+  readonly totalBytes: number;
+  /** Present only when the phase is `failed` or `absent`. */
+  readonly message: string;
+}
+
+/** One drawable piece of a loaded model. */
+export interface DrftPart {
+  readonly mesh: MeshHandle;
+  /** Which of the asset's images this surface wears, or -1 for none. */
+  readonly albedo: number;
+  /** Which image carries its occlusion, roughness and metallic, or -1 for none. */
+  readonly orm: number;
+  /**
+   * Which image carries its surface-space normals, or -1 for none.
+   *
+   * **Carried by the container since `MATL` reached stride 72 and dropped here until 2026-08-23**,
+   * which is the whole of why a bought model looked smoother than the one its maker shipped: the
+   * baker wrote the index, the reader read it, the renderer has taken a normal map through
+   * `SurfaceMaterial.normal` since normal maps landed, and this was the one step that did not pass
+   * it on. Panel seams, stitching, tread and every other detail an exporter bakes into a normal
+   * map rather than into geometry was arriving and going nowhere.
+   */
+  readonly normal: number;
+  /**
+   * Which image carries its emission, or -1 for none.
+   *
+   * **The fourth and last index `MATL` carries, passed on from 2026-08-24.** It was written by the
+   * baker, read by the reader and dropped here for the same stretch the normal map was — but for a
+   * stated reason rather than by oversight: no renderer took an emissive map until now, so there
+   * was nowhere to pass it. `SurfaceMaterial.emissive` is that somewhere.
+   */
+  readonly emissive: number;
+  /**
+   * glTF's three factors, in the shape `SurfaceMaterial` takes them.
+   *
+   * Carried on the part rather than looked up from the material, because a caller building a
+   * `setMaterial` call has the part and not the index that produced it.
+   */
+  readonly roughnessScale: number;
+  readonly metallicScale: number;
+  readonly occlusionStrength: number;
+  readonly opacity: number;
+  readonly reflectivity: number;
+  /**
+   * Alpha below which this surface's fragments are discarded, 0 for one that discards nothing.
+   *
+   * The pair to `opacity` and not a weaker version of it: a cutout decides which texels of the
+   * surface exist, an opacity decides how much light passes through the ones that do. It is what
+   * `SurfaceMaterial.cutout` takes, and until `MATL` grew the field there was no way for a source
+   * format to say it — a masked grille arrived as a solid rectangle, and a vehicle format's alpha
+   * *test* was being spent on the opacity, which drew nine surfaces of a hundred and two as
+   * nothing at all.
+   */
+  readonly cutout: number;
+  /**
+   * 0 to 1 as this part arrives, for a caller that would rather it faded in than appeared.
+   *
+   * Advanced by `update`, so it follows the frame's own clock and holds when the frame holds.
+   * A caller that wants parts to pop in can ignore it; one that wants a build fades on it.
+   */
+  reveal: number;
+}

package/src/localise.ts

@@ -0,0 +1,275 @@
+/**
+ * World-space meshes plus their graph, as parts each expressed about its own node.
+ *
+ * **Why this exists at all.** `MESH` holds world-space positions, deliberately: `docs/FORMAT.md`
+ * §4.4 rule 4 forbids a minor version from changing what an existing byte means, so geometry
+ * could not move into node-local space without breaking every reader that predates the
+ * hierarchy. The consequence is that a consumer holding a vehicle and its graph still cannot
+ * turn a wheel, because the wheel's vertices are expressed around the model's origin and not
+ * around the hub's. Turning one into the other is exact and mechanical, so the engine does it
+ * once here instead of every consumer deriving it slightly differently.
+ *
+ * **`DrftLoader` deliberately does not call this.** Its own note says placing parts under a graph
+ * is a scene decision, and that is still true — this is the arithmetic that decision needs,
+ * offered to whoever makes it.
+ *
+ * **What it costs.** One 4x4 inversion per node and one transform per vertex: 221k vertices for
+ * the largest asset this was measured against, once, at load. Not per frame. A caller loading a
+ * large model should run it behind a frame budget instead of in one block.
+ */
+
+import type { DrftNode, MeshData } from '@driftengine/drft';
+
+/** Column-major 4x4 from a node's TRS, matching what a caller hands a renderer. */
+function compose(node: DrftNode): Float32Array {
+  const [x, y, z, w] = node.rotation;
+  const [sx, sy, sz] = node.scale;
+  const out = new Float32Array(16);
+  out[0] = (1 - 2 * (y * y + z * z)) * sx;
+  out[1] = 2 * (x * y + z * w) * sx;
+  out[2] = 2 * (x * z - y * w) * sx;
+  out[4] = 2 * (x * y - z * w) * sy;
+  out[5] = (1 - 2 * (x * x + z * z)) * sy;
+  out[6] = 2 * (y * z + x * w) * sy;
+  out[8] = 2 * (x * z + y * w) * sz;
+  out[9] = 2 * (y * z - x * w) * sz;
+  out[10] = (1 - 2 * (x * x + y * y)) * sz;
+  out[12] = node.translation[0];
+  out[13] = node.translation[1];
+  out[14] = node.translation[2];
+  out[15] = 1;
+  return out;
+}
+
+/** `out = a * b`, column-major. */
+function multiply(a: Float32Array, b: Float32Array): Float32Array {
+  const out = new Float32Array(16);
+  for (let column = 0; column < 4; column++) {
+    for (let row = 0; row < 4; row++) {
+      let sum = 0;
+      for (let k = 0; k < 4; k++) sum += (a[k * 4 + row] as number) * (b[column * 4 + k] as number);
+      out[column * 4 + row] = sum;
+    }
+  }
+  return out;
+}
+
+/** A full 4x4 inverse, or null where the matrix is singular. */
+function invert(m: Float32Array): Float32Array | null {
+  const a = (i: number): number => m[i] as number;
+  const inv = new Float32Array(16);
+  inv[0] =
+    a(5) * a(10) * a(15) -
+    a(5) * a(11) * a(14) -
+    a(9) * a(6) * a(15) +
+    a(9) * a(7) * a(14) +
+    a(13) * a(6) * a(11) -
+    a(13) * a(7) * a(10);
+  inv[4] =
+    -a(4) * a(10) * a(15) +
+    a(4) * a(11) * a(14) +
+    a(8) * a(6) * a(15) -
+    a(8) * a(7) * a(14) -
+    a(12) * a(6) * a(11) +
+    a(12) * a(7) * a(10);
+  inv[8] =
+    a(4) * a(9) * a(15) -
+    a(4) * a(11) * a(13) -
+    a(8) * a(5) * a(15) +
+    a(8) * a(7) * a(13) +
+    a(12) * a(5) * a(11) -
+    a(12) * a(7) * a(9);
+  inv[12] =
+    -a(4) * a(9) * a(14) +
+    a(4) * a(10) * a(13) +
+    a(8) * a(5) * a(14) -
+    a(8) * a(6) * a(13) -
+    a(12) * a(5) * a(10) +
+    a(12) * a(6) * a(9);
+  inv[1] =
+    -a(1) * a(10) * a(15) +
+    a(1) * a(11) * a(14) +
+    a(9) * a(2) * a(15) -
+    a(9) * a(3) * a(14) -
+    a(13) * a(2) * a(11) +
+    a(13) * a(3) * a(10);
+  inv[5] =
+    a(0) * a(10) * a(15) -
+    a(0) * a(11) * a(14) -
+    a(8) * a(2) * a(15) +
+    a(8) * a(3) * a(14) +
+    a(12) * a(2) * a(11) -
+    a(12) * a(3) * a(10);
+  inv[9] =
+    -a(0) * a(9) * a(15) +
+    a(0) * a(11) * a(13) +
+    a(8) * a(1) * a(15) -
+    a(8) * a(3) * a(13) -
+    a(12) * a(1) * a(11) +
+    a(12) * a(3) * a(9);
+  inv[13] =
+    a(0) * a(9) * a(14) -
+    a(0) * a(10) * a(13) -
+    a(8) * a(1) * a(14) +
+    a(8) * a(2) * a(13) +
+    a(12) * a(1) * a(10) -
+    a(12) * a(2) * a(9);
+  inv[2] =
+    a(1) * a(6) * a(15) -
+    a(1) * a(7) * a(14) -
+    a(5) * a(2) * a(15) +
+    a(5) * a(3) * a(14) +
+    a(13) * a(2) * a(7) -
+    a(13) * a(3) * a(6);
+  inv[6] =
+    -a(0) * a(6) * a(15) +
+    a(0) * a(7) * a(14) +
+    a(4) * a(2) * a(15) -
+    a(4) * a(3) * a(14) -
+    a(12) * a(2) * a(7) +
+    a(12) * a(3) * a(6);
+  inv[10] =
+    a(0) * a(5) * a(15) -
+    a(0) * a(7) * a(13) -
+    a(4) * a(1) * a(15) +
+    a(4) * a(3) * a(13) +
+    a(12) * a(1) * a(7) -
+    a(12) * a(3) * a(5);
+  inv[14] =
+    -a(0) * a(5) * a(14) +
+    a(0) * a(6) * a(13) +
+    a(4) * a(1) * a(14) -
+    a(4) * a(2) * a(13) -
+    a(12) * a(1) * a(6) +
+    a(12) * a(2) * a(5);
+  inv[3] =
+    -a(1) * a(6) * a(11) +
+    a(1) * a(7) * a(10) +
+    a(5) * a(2) * a(11) -
+    a(5) * a(3) * a(10) -
+    a(9) * a(2) * a(7) +
+    a(9) * a(3) * a(6);
+  inv[7] =
+    a(0) * a(6) * a(11) -
+    a(0) * a(7) * a(10) -
+    a(4) * a(2) * a(11) +
+    a(4) * a(3) * a(10) +
+    a(8) * a(2) * a(7) -
+    a(8) * a(3) * a(6);
+  inv[11] =
+    -a(0) * a(5) * a(11) +
+    a(0) * a(7) * a(9) +
+    a(4) * a(1) * a(11) -
+    a(4) * a(3) * a(9) -
+    a(8) * a(1) * a(7) +
+    a(8) * a(3) * a(5);
+  inv[15] =
+    a(0) * a(5) * a(10) -
+    a(0) * a(6) * a(9) -
+    a(4) * a(1) * a(10) +
+    a(4) * a(2) * a(9) +
+    a(8) * a(1) * a(6) -
+    a(8) * a(2) * a(5);
+
+  const determinant =
+    a(0) * (inv[0] as number) +
+    a(1) * (inv[4] as number) +
+    a(2) * (inv[8] as number) +
+    a(3) * (inv[12] as number);
+  if (determinant === 0 || !Number.isFinite(determinant)) return null;
+  for (let i = 0; i < 16; i++) inv[i] = (inv[i] as number) / determinant;
+  return inv;
+}
+
+export interface Localised {
+  /** Parallel to the meshes given, each about the origin of the node that placed it. */
+  parts: MeshData[];
+  /** Parallel to the nodes given: the accumulated world matrix, column-major. */
+  world: Float32Array[];
+  /** Nodes whose geometry could not be localised, named so a person can look at them. */
+  warnings: string[];
+}
+
+/**
+ * Move each mesh into the frame of the node that placed it, and report every node's world matrix.
+ *
+ * A mesh no node claims is passed through untouched, which is what a format carrying no hierarchy
+ * yields and is the correct no-op.
+ */
+export function localiseNodes(meshes: readonly MeshData[], nodes: readonly DrftNode[]): Localised {
+  const world: Float32Array[] = [];
+  for (const node of nodes) {
+    const local = compose(node);
+    world.push(node.parent < 0 ? local : multiply(world[node.parent] as Float32Array, local));
+  }
+
+  const warnings: string[] = [];
+  const parts: MeshData[] = meshes.map((mesh) => mesh);
+  for (let index = 0; index < nodes.length; index++) {
+    const node = nodes[index] as DrftNode;
+    if (node.mesh < 0) continue;
+    const mesh = meshes[node.mesh];
+    if (mesh === undefined) continue;
+    const inverse = invert(world[index] as Float32Array);
+    if (inverse === null) {
+      /*
+       * A singular basis has no inverse and no rotation worth recovering, so the mesh stays where
+       * it is. Named, because a part that cannot be animated is something a person needs told
+       * rather than left to discover when it will not turn.
+       */
+      warnings.push(
+        `node "${node.name}" has a singular transform, so its mesh is left in world space and ` +
+          'cannot be animated about its own origin.',
+      );
+      continue;
+    }
+
+    const positions = new Float32Array(mesh.positions.length);
+    for (let at = 0; at < 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;
+      positions[at] =
+        x * (inverse[0] as number) +
+        y * (inverse[4] as number) +
+        z * (inverse[8] as number) +
+        (inverse[12] as number);
+      positions[at + 1] =
+        x * (inverse[1] as number) +
+        y * (inverse[5] as number) +
+        z * (inverse[9] as number) +
+        (inverse[13] as number);
+      positions[at + 2] =
+        x * (inverse[2] as number) +
+        y * (inverse[6] as number) +
+        z * (inverse[10] as number) +
+        (inverse[14] as number);
+    }
+
+    /*
+     * Normals take the inverse transpose, which for the inverse already in hand is the transpose
+     * of that inverse — the same correction `gltf.ts` applies when it flattens, in the opposite
+     * direction. Renormalised, because a node carrying a scale would otherwise leave them short.
+     */
+    const normals = new Float32Array(mesh.normals.length);
+    for (let at = 0; at < mesh.normals.length; at += 3) {
+      const x = mesh.normals[at] as number;
+      const y = mesh.normals[at + 1] as number;
+      const z = mesh.normals[at + 2] as number;
+      const nx =
+        x * (inverse[0] as number) + y * (inverse[1] as number) + z * (inverse[2] as number);
+      const ny =
+        x * (inverse[4] as number) + y * (inverse[5] as number) + z * (inverse[6] as number);
+      const nz =
+        x * (inverse[8] as number) + y * (inverse[9] as number) + z * (inverse[10] as number);
+      const length = Math.hypot(nx, ny, nz) || 1;
+      normals[at] = nx / length;
+      normals[at + 1] = ny / length;
+      normals[at + 2] = nz / length;
+    }
+
+    parts[node.mesh] = { ...mesh, positions, normals };
+  }
+
+  return { parts, world, warnings };
+}