@driftengine/core 3.61.0

package/src/geometry/filmPatch.ts

@@ -0,0 +1,158 @@
+/**
+ * A rounded, feathered patch lying on a swept surface.
+ *
+ * The shape a spill has. Not a rectangle, not a decal, not a box: an irregular
+ * lens that follows the surface's curvature and bank and dissolves at its rim.
+ *
+ * The rim is the whole reason this exists. A patch drawn with a hard edge reads as
+ * a sticker on the world no matter what material it is made of, because a real
+ * puddle is thinnest where it ends — so this emits a *coverage* value per vertex,
+ * 1 through the middle and 0 around the outside, and the film shader turns that
+ * into alpha. Geometry supplies the silhouette; the shader supplies the wetness.
+ *
+ * Textureless and engine-generic: it takes a curve, a window along it, a width and
+ * a seed, and knows nothing about oil, water or what a slick is for.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import type { Spline } from './spline.ts';
+import { createSplineSample } from './spline.ts';
+import type { Vec3 } from '../math/color.ts';
+
+export interface FilmPatchOptions {
+  /** Arc-length window on the curve. */
+  fromM: number;
+  toM: number;
+  /** Lateral centre and half-width, metres from the centreline. */
+  centreM: number;
+  halfWidthM: number;
+  /** Height above the surface. Small: this is a film, not a kerb. */
+  liftM: number;
+  color: Vec3;
+  /**
+   * Shape seed. Two patches with the same window and the same seed are the same
+   * patch, which is what keeps a day's world identical on every device.
+   */
+  seed: number;
+}
+
+/**
+ * Stations along the patch, and vertices across it.
+ *
+ * Nine across is what a soft rim costs: the outer pair carry zero coverage, so
+ * they contribute silhouette rather than colour, and the falloff needs a couple of
+ * rings inside them or the shoulder becomes a visible band.
+ */
+const MIN_STATIONS = 7;
+const STATION_SPACING_M = 0.7;
+const ACROSS = 9;
+/**
+ * How much the outline wanders, as a fraction of the half-width.
+ *
+ * Enough that no two slicks are the same lens and none of them looks drawn with a
+ * compass; not so much that the patch stops reading as one connected spill.
+ */
+const WOBBLE = 0.28;
+
+export function buildFilmPatch(spline: Spline, options: FilmPatchOptions): MeshData {
+  const spanM = Math.max(options.toM - options.fromM, 0.1);
+  const stations = Math.max(MIN_STATIONS, Math.ceil(spanM / STATION_SPACING_M) | 1);
+  const vertexCount = stations * ACROSS;
+
+  const positions = new Float32Array(vertexCount * 3);
+  const normals = new Float32Array(vertexCount * 3);
+  const colors = new Float32Array(vertexCount * 3);
+  const coverage = new Float32Array(vertexCount);
+  const indices = new Uint32Array((stations - 1) * (ACROSS - 1) * 6);
+
+  const sample = createSplineSample();
+  // Two incommensurable frequencies per axis, so the outline does not repeat
+  // across a long patch, and phases from the seed so each one is its own shape.
+  const phaseA = (options.seed % 1000) * 0.0063;
+  const phaseB = (options.seed % 997) * 0.0157;
+
+  let v = 0;
+  let i = 0;
+  for (let s = 0; s < stations; s++) {
+    // -1 at the near end, +1 at the far end.
+    const along = (s / (stations - 1)) * 2 - 1;
+    const d = options.fromM + ((along + 1) / 2) * spanM;
+    spline.sampleAt(d, sample);
+
+    /*
+     * An ellipse, roughened.
+     *
+     * The circular profile is what rounds the ends — a patch whose width is
+     * constant to its last station has square ends however soft its sides are.
+     */
+    const profile = Math.sqrt(Math.max(1 - along * along, 0));
+    /*
+     * The wobble only ever eats *inward*.
+     *
+     * Written first as `1 ± wobble`, which is the obvious form and is wrong: the
+     * half-width then reaches 1.28× what the caller asked for, and a caller like an
+     * oil slick has a physics window that is exactly this band. Ground that looks
+     * wet and grips normally is a lie, and ground that grips nowhere near what is
+     * drawn is worse. Subtracting keeps the silhouette inside the contract by
+     * construction rather than by a tolerance.
+     */
+    const dent =
+      0.6 * (0.5 + 0.5 * Math.sin(along * 3.7 + phaseA)) +
+      0.4 * (0.5 + 0.5 * Math.sin(along * 8.3 + phaseB));
+    const half = options.halfWidthM * profile * (1 - WOBBLE * dent);
+
+    for (let a = 0; a < ACROSS; a++) {
+      // -1 at one edge, +1 at the other.
+      const across = (a / (ACROSS - 1)) * 2 - 1;
+      const lateral = options.centreM + across * half;
+
+      const o = v * 3;
+      positions[o] = sample.x + sample.rightX * lateral + sample.normalX * options.liftM;
+      positions[o + 1] = sample.y + sample.rightY * lateral + sample.normalY * options.liftM;
+      positions[o + 2] = sample.z + sample.rightZ * lateral + sample.normalZ * options.liftM;
+      normals[o] = sample.normalX;
+      normals[o + 1] = sample.normalY;
+      normals[o + 2] = sample.normalZ;
+      colors[o] = options.color[0];
+      colors[o + 1] = options.color[1];
+      colors[o + 2] = options.color[2];
+
+      /*
+       * Coverage falls off in both directions at once, and multiplying the two is
+       * what keeps the corners honest — a patch feathered only across its width
+       * still ends in two hard lines at the ends.
+       */
+      const acrossFade = 1 - across * across;
+      const alongFade = 1 - along * along;
+      coverage[v] = Math.max(acrossFade, 0) * Math.max(alongFade, 0);
+      v++;
+    }
+
+    if (s === 0) continue;
+    for (let a = 0; a < ACROSS - 1; a++) {
+      const here = s * ACROSS + a;
+      const back = here - ACROSS;
+      /*
+       * Wound so the patch faces *up*.
+       *
+       * The first version had every triangle facing down — measured, 224 of 224 — which under
+       * back-face culling means the slick was never drawn at all. That cost a whole session
+       * hunting the shader while looking straight at the patch: the shader was fine and the
+       * geometry was inside out.
+       *
+       * The lesson is the same one the ribbon taught, and it is why the test below measures the
+       * cross product of the triangle rather than reading `normals`: the stored normals are the
+       * *surface's*, written by hand and pointing up whatever the winding does, so asking them
+       * whether the winding is right is asking the wrong array.
+       */
+      indices[i] = back;
+      indices[i + 1] = back + 1;
+      indices[i + 2] = here;
+      indices[i + 3] = back + 1;
+      indices[i + 4] = here + 1;
+      indices[i + 5] = here;
+      i += 6;
+    }
+  }
+
+  return { positions, normals, colors, emissive: coverage, indices };
+}

package/src/geometry/growable.ts

@@ -0,0 +1,165 @@
+/**
+ * A number list that is already a typed array, so handing it to the GPU is a copy and not a
+ * conversion.
+ *
+ * **Because `build()` was the frame.** `MeshBuilder` accumulated into ten plain `number[]` and
+ * turned each into a `Float32Array` in one uninterruptible call at the end. Measured on this
+ * machine at **41.9 ms for 110,628 triangles** — two and a half frames — which is what made a
+ * consumer streaming a world cap its batches at a triangle count tuned to one laptop, and overshoot
+ * that cap by whatever the last object happened to be.
+ *
+ * The work is the same total work; it moves to where the caller already is. A `number[]` holds
+ * boxed doubles that `new Float32Array(list)` must walk and narrow one at a time, while writing
+ * into a `Float32Array` as geometry arrives makes the end a `slice` — one memcpy the allocator and
+ * the CPU are both good at.
+ *
+ * **`push` takes six optional numbers rather than a rest parameter**, and that is not a style
+ * choice: a rest parameter allocates an array on every call, and this is called sixty-seven times
+ * per box across the builder. Six covers every arity the builder uses (one, two, three and six),
+ * and the shape means not one of those call sites had to change.
+ *
+ * **What would make it wrong** is a caller wanting more than six at once, which would silently drop
+ * the rest — so `push` is deliberately not variadic-looking, and a seventh argument is a type
+ * error rather than a lost vertex.
+ */
+export class GrowableF32 {
+  private buffer: Float32Array;
+  /** How many numbers have been written. Not the buffer's capacity. */
+  length = 0;
+  /**
+   * Whether anything other than the default was ever written.
+   *
+   * **Because `build` used to ask five times, over every vertex.** Specular, emissive colour,
+   * roughness, grain and relief are each accumulated always and emitted only when something asked
+   * for one, and the asking was a `some()` over the whole list — about 1.5 million predicate calls
+   * for a mesh this size, on a path whose entire job is to be cheap. A write knows whether it
+   * matters; a scan afterwards is rediscovering it.
+   */
+  hasOther = false;
+  private readonly fallback: number;
+
+  constructor(capacity = 256, fallback = Number.NaN) {
+    this.buffer = new Float32Array(capacity);
+    this.fallback = fallback;
+  }
+
+  push(a: number, b?: number, c?: number, d?: number, e?: number, f?: number): void {
+    const count =
+      f !== undefined
+        ? 6
+        : e !== undefined
+          ? 5
+          : d !== undefined
+            ? 4
+            : c !== undefined
+              ? 3
+              : b !== undefined
+                ? 2
+                : 1;
+    if (this.length + count > this.buffer.length) this.grow(this.length + count);
+    const at = this.length;
+    const buffer = this.buffer;
+    buffer[at] = a;
+    if (b !== undefined) buffer[at + 1] = b;
+    if (c !== undefined) buffer[at + 2] = c;
+    if (d !== undefined) buffer[at + 3] = d;
+    if (e !== undefined) buffer[at + 4] = e;
+    if (f !== undefined) buffer[at + 5] = f;
+    this.length = at + count;
+    /* A list with no default never answers this, and pays one comparison it can predict. */
+    if (!this.hasOther && !Number.isNaN(this.fallback)) {
+      for (let i = at; i < this.length; i++) {
+        if (buffer[i] !== this.fallback) {
+          this.hasOther = true;
+          break;
+        }
+      }
+    }
+  }
+
+  /** One value, for the few places that read back what they wrote. */
+  at(index: number): number {
+    return index < this.length ? (this.buffer[index] as number) : 0;
+  }
+
+  /** Whether any written value satisfies the predicate. A typed-array walk, not a boxed one. */
+  some(predicate: (value: number) => boolean): boolean {
+    for (let i = 0; i < this.length; i++) if (predicate(this.buffer[i] as number)) return true;
+    return false;
+  }
+
+  /**
+   * The written range as its own array, which is what a mesh is handed.
+   *
+   * A copy rather than a `subarray`, deliberately: a view would keep the whole grown buffer alive
+   * and would change under anything that kept writing, and a mesh outlives its builder.
+   */
+  toTyped(): Float32Array {
+    return this.buffer.slice(0, this.length);
+  }
+
+  /**
+   * Doubling, and never to less than what was asked for.
+   *
+   * A geometry verb can write six numbers at once into an empty list, so growing by a factor alone
+   * can still be short — which is a silent one-vertex truncation rather than a throw.
+   */
+  private grow(needed: number): void {
+    let size = this.buffer.length || 1;
+    while (size < needed) size *= 2;
+    const grown = new Float32Array(size);
+    grown.set(this.buffer);
+    this.buffer = grown;
+  }
+}
+
+/** The same, for indices, which are integers and are handed over as a `Uint32Array`. */
+export class GrowableU32 {
+  private buffer: Uint32Array;
+  length = 0;
+
+  constructor(capacity = 256) {
+    this.buffer = new Uint32Array(capacity);
+  }
+
+  push(a: number, b?: number, c?: number, d?: number, e?: number, f?: number): void {
+    const count =
+      f !== undefined
+        ? 6
+        : e !== undefined
+          ? 5
+          : d !== undefined
+            ? 4
+            : c !== undefined
+              ? 3
+              : b !== undefined
+                ? 2
+                : 1;
+    if (this.length + count > this.buffer.length) this.grow(this.length + count);
+    const at = this.length;
+    const buffer = this.buffer;
+    buffer[at] = a;
+    if (b !== undefined) buffer[at + 1] = b;
+    if (c !== undefined) buffer[at + 2] = c;
+    if (d !== undefined) buffer[at + 3] = d;
+    if (e !== undefined) buffer[at + 4] = e;
+    if (f !== undefined) buffer[at + 5] = f;
+    this.length = at + count;
+  }
+
+  at(index: number): number {
+    return index < this.length ? (this.buffer[index] as number) : 0;
+  }
+
+  toTyped(): Uint32Array {
+    return this.buffer.slice(0, this.length);
+  }
+
+  private grow(needed: number): void {
+    let size = this.buffer.length || 1;
+    while (size < needed) size *= 2;
+    const grown = new Uint32Array(size);
+    grown.set(this.buffer);
+    this.buffer = grown;
+  }
+}

package/src/geometry/lightVolume.ts

@@ -0,0 +1,161 @@
+/**
+ * The hull a volume of light is drawn on: a beam, a shaft through a window, the cone under
+ * a lamp.
+ *
+ * **It exists because the geometry and the draw call have to agree, and nothing enforced
+ * it.** `Renderer.drawLightVolume` fades the light to nothing at a length and an aperture
+ * it is *told*, and those two numbers are read in the geometry's own space. A caller who
+ * builds the shape by hand therefore states each of them twice, in two files, and the
+ * failure when the copies disagree is silent both ways: a length longer than the geometry
+ * draws a beam that stops at a bright polygon edge, and an aperture wider than the
+ * geometry's own flare draws a hard-edged wedge. Two demo scenes here wrote the same loop,
+ * and a consumer outside this repository shipped stubs in two worlds — no beam at all
+ * through two captures, then hard white wedges through a third — because the numbers a beam
+ * needs are three and the ones that are obviously wrong when mistaken are zero.
+ *
+ * **What this builds changed in 0.35.0, and a mesh built before it must be rebuilt.** It
+ * used to emit a few flat panes crossing the axis, which is what the pass rasterised and
+ * weighted. The pass now walks the view ray instead, so what it needs from geometry is only
+ * a closed hull deciding which pixels run: a cone frustum with its two caps. Panes handed to
+ * the new pass light only the sliver of screen the panes themselves cover. Anything that
+ * calls this function is already correct; anything that hand-rolled its own is not.
+ *
+ * Textureless and engine-generic: a length, an aperture and a colour. It does not know
+ * whether it is a lighthouse or a window.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import { MeshBuilder } from './meshBuilder.ts';
+import type { Vec3 } from '../math/color.ts';
+
+export interface LightVolumeOptions {
+  /**
+   * How far the light reaches along the volume's own +Z, in the units the panes are
+   * built in — which are the units of whatever `model` matrix places them.
+   *
+   * **Pass this same number to `drawLightVolume` as its `length`.** The panes end exactly
+   * here, so the light reaches zero at the last row of vertices and no edge is ever in the
+   * picture.
+   */
+  lengthM: number;
+  /**
+   * Half-width over distance: the tangent of the cone's half-angle.
+   *
+   * **Pass this same number to `drawLightVolume` as its `spread`.** The panes are built a
+   * shade wider than it, so the fade lands inside the polygon rather than at its rim.
+   */
+  spread: number;
+  color: Vec3;
+  /**
+   * Where the volume starts, along the same +Z. Zero for a beam that begins at its source.
+   *
+   * A shaft of daylight through an opening is a slice taken far down a very wide cone —
+   * the apex sits above the roof, and only the part below the opening is drawn. That is
+   * what this is for, and it is why the near end is a parameter rather than the origin.
+   */
+  nearM?: number;
+  /**
+   * How many sides the hull has. Rounded up to an even number, because the caps are quads.
+   *
+   * It decides the silhouette and nothing else: the light inside is the ray march's, so a
+   * coarse hull is a polygonal *outline* around a volume that is still round. Twelve is
+   * indistinguishable from a circle at the size a beam usually occupies; drop it for a
+   * volume that is always distant, raise it for one that fills the frame.
+   */
+  sides?: number;
+}
+
+/**
+ * How far past the aperture the hull reaches.
+ *
+ * The march's own falloff is what should end the beam, so the hull has to outlast it or the
+ * silhouette becomes a cut rather than a fade. Fifteen percent is enough that no edge is
+ * visible at any angle and little enough that the hull is not mostly empty margin.
+ */
+const EDGE_MARGIN = 1.15;
+
+/** Sides when a caller does not say. Round enough for a beam at any distance it is legible at. */
+const DEFAULT_SIDES = 12;
+
+/**
+ * The hull's radius at its near end when the volume starts at its own apex.
+ *
+ * A beam that begins at its source begins at a point, and `addQuad` refuses a degenerate
+ * corner pair rather than emit a normal it cannot compute. A thousandth of the far radius
+ * reads as an apex and lies where the march's across-axis falloff is 1 anyway.
+ */
+const APEX_WIDTH_FRACTION = 1e-3;
+
+/**
+ * Build the hull for a volume of light, in the volume's own space, opening along +Z.
+ *
+ * A closed cone frustum, wound outward so the renderer can cull whichever half it needs: it
+ * draws the front faces from outside and the back faces from inside, which is what lets a
+ * camera walk into a beam without the beam vanishing. The caps matter more than they look —
+ * without the near one, a viewer looking straight up a vertical shaft finds a hole through
+ * the middle of it exactly where the volume should be at its most solid.
+ *
+ * Nothing here shapes the light. The hull says which pixels to run on and the pass decides
+ * what they are worth, so a coarser hull is a coarser outline and never a coarser beam.
+ */
+export function buildLightVolume(options: LightVolumeOptions): MeshData {
+  const near = options.nearM ?? 0;
+  const far = options.lengthM;
+  if (!(far > near)) {
+    throw new Error(`buildLightVolume: lengthM (${far}) must be beyond nearM (${near})`);
+  }
+
+  /* Even, because each cap is built from quads spanning two segments at a time. */
+  const sides = Math.max(4, Math.round((options.sides ?? DEFAULT_SIDES) / 2) * 2);
+  const farRadius = far * options.spread * EDGE_MARGIN;
+  const nearRadius =
+    near > 0 ? near * options.spread * EDGE_MARGIN : farRadius * APEX_WIDTH_FRACTION;
+
+  const builder = new MeshBuilder();
+  builder.setEmissiveColor(options.color);
+  builder.setRoughness(null);
+  builder.setGrain(0);
+
+  const ring = (i: number, radius: number, z: number): Vec3 => {
+    const turn = ((i % sides) / sides) * Math.PI * 2;
+    return [Math.cos(turn) * radius, Math.sin(turn) * radius, z];
+  };
+
+  /* The lateral surface. Wound so the face normal points away from the axis. */
+  for (let i = 0; i < sides; i++) {
+    builder.addQuad(
+      ring(i, nearRadius, near),
+      ring(i + 1, nearRadius, near),
+      ring(i + 1, farRadius, far),
+      ring(i, farRadius, far),
+      options.color,
+      1,
+    );
+  }
+
+  /*
+   * The caps, as a fan of quads from the centre rather than triangles, because `MeshBuilder`
+   * has no triangle and a quad with a repeated corner has no normal to compute. Two segments
+   * per quad is why the side count is forced even.
+   */
+  for (let i = 0; i < sides; i += 2) {
+    builder.addQuad(
+      [0, 0, far],
+      ring(i, farRadius, far),
+      ring(i + 1, farRadius, far),
+      ring(i + 2, farRadius, far),
+      options.color,
+      1,
+    );
+    builder.addQuad(
+      [0, 0, near],
+      ring(i + 2, nearRadius, near),
+      ring(i + 1, nearRadius, near),
+      ring(i, nearRadius, near),
+      options.color,
+      1,
+    );
+  }
+
+  builder.setEmissiveColor(null);
+  return builder.build();
+}