@driftengine/core 4.9.0 → 4.11.0

package/src/render/skinnedClothRun.ts

@@ -11,6 +11,10 @@
  * millisecond a frame on the main thread, and 4,500 are twenty — a garment that size wants the
  * device. The device solver ran 4,500 particles in 0.65 ms a frame, most of it the dispatches
  * rather than the particles (`demo/dev/skinnedCloth.html?bench=1`).
+ *
+ * **Several garments step as one with `createSkinnedClothSet`**: one pass, one submit and one
+ * garment's dispatches a step for all of them, where a garment each was a pass, a submit and its
+ * own dispatches each. They must share a step, substeps, iterations and most steps a frame.
  */
 import { SkinnedCloth } from '@driftengine/physics';
 import type { SkinnedClothSetup } from '@driftengine/physics';
@@ -18,7 +22,7 @@ import type { SkinnedClothSetup } from '@driftengine/physics';
 import type { ClothParticlesHandle, RendererApi } from './backend/api.ts';
 import { computeHostOf } from './backend/webgpu/computeHost.ts';
 import type { ComputeHost } from './backend/webgpu/computeHost.ts';
-import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.ts';
+import { GpuClothSet } from './backend/webgpu/gpuClothSet.ts';
 
 /** A garment a renderer solves, from `createSkinnedCloth`. */
 export interface SkinnedClothSolver {
@@ -43,86 +47,182 @@ export interface SkinnedClothSolver {
   dispose(): void;
 }
 
+/** Garments a renderer solves together, from `createSkinnedClothSet`, each named by its index. */
+export interface SkinnedClothSet {
+  /** Each garment's particles, in the order its set-up was given: what `setCloth` draws it by. */
+  readonly particles: readonly ClothParticlesHandle[];
+  /** Where the set runs: on the device, or on the CPU beneath a backend without compute. */
+  readonly runsOn: 'device' | 'cpu';
+  /**
+   * Garment `g`'s rig for the next `step`: each joint's global matrix, model space, sixteen floats a
+   * joint, and the model matrix. A garment not posed in a frame steps toward its last pose.
+   */
+  setPose(g: number, globals: Float32Array, model: Float32Array): void;
+  /** The air garment `g` drags toward from its next step: the frame's sample of the one wind. */
+  setWind(g: number, x: number, y: number, z: number): void;
+  /** Garment `g` back to its skinned pose, settled, as a teleport resets it. */
+  reset(g: number): void;
+  /**
+   * `dt` seconds for every garment, run as whole fixed steps; each garment's particles at its
+   * `alpha` are then what the frame draws. **Once a frame, before the draws**, as a solver's `step`.
+   */
+  step(dt: number): void;
+  dispose(): void;
+}
+
 /** A garment for `renderer`, from a set-up checked by name. */
 export function createSkinnedCloth(
   renderer: RendererApi,
   setup: SkinnedClothSetup,
 ): SkinnedClothSolver {
   const host = computeHostOf(renderer);
-  return host === null ? new CpuCloth(renderer, setup) : new DeviceCloth(host, setup);
+  const set =
+    host === null ? new CpuClothSet(renderer, [setup]) : new DeviceClothSet(host, [setup]);
+  return new OneGarment(set);
 }
 
-class DeviceCloth implements SkinnedClothSolver {
-  readonly runsOn = 'device';
+/** A set of one, as a solver: what `createSkinnedCloth` hands back. */
+class OneGarment implements SkinnedClothSolver {
   readonly particles: ClothParticlesHandle;
-  private readonly cloth: GpuSkinnedCloth;
+  readonly runsOn: 'device' | 'cpu';
+
+  constructor(private readonly set: DeviceClothSet | CpuClothSet) {
+    this.particles = set.particles[0] as ClothParticlesHandle;
+    this.runsOn = set.runsOn;
+  }
+
+  step(globals: Float32Array, model: Float32Array, dt: number): void {
+    this.set.setPose(0, globals, model);
+    this.set.step(dt);
+  }
+
+  setWind(x: number, y: number, z: number): void {
+    this.set.setWind(0, x, y, z);
+  }
+
+  reset(): void {
+    this.set.reset(0);
+  }
+
+  dispose(): void {
+    this.set.dispose();
+  }
+
+  /** The particles where the last step left them: the parity check's door. */
+  read(): Promise<Float32Array> {
+    return this.set.read(0);
+  }
+}
+
+/**
+ * Garments for `renderer` stepped together, from set-ups checked by name: one pass, one submit and
+ * one garment's dispatches a step on the device, whatever the count. They must agree on `step`,
+ * `substeps`, `iterations` and `maxSteps`, and are refused by the first they disagree on.
+ */
+export function createSkinnedClothSet(
+  renderer: RendererApi,
+  setups: readonly SkinnedClothSetup[],
+): SkinnedClothSet {
+  const host = computeHostOf(renderer);
+  return host === null ? new CpuClothSet(renderer, setups) : new DeviceClothSet(host, setups);
+}
+
+class DeviceClothSet implements SkinnedClothSet {
+  readonly runsOn = 'device';
+  readonly particles: readonly ClothParticlesHandle[];
+  private readonly set: GpuClothSet;
 
   constructor(
     private readonly host: ComputeHost,
-    setup: SkinnedClothSetup,
+    setups: readonly SkinnedClothSetup[],
   ) {
-    this.cloth = new GpuSkinnedCloth(host.device(), setup);
-    this.particles = this.cloth.particles;
+    this.set = new GpuClothSet(host.device(), setups);
+    const particles: ClothParticlesHandle[] = [];
+    for (let g = 0; g < this.set.size; g++) particles.push(this.set.particles(g));
+    this.particles = particles;
   }
 
-  step(globals: Float32Array, model: Float32Array, dt: number): void {
+  setPose(g: number, globals: Float32Array, model: Float32Array): void {
     if (this.host.lost()) return;
-    this.cloth.advance(globals, model, dt, this.host.changeFrame());
+    this.set.setPose(g, globals, model);
   }
 
-  setWind(x: number, y: number, z: number): void {
-    this.cloth.setWind(x, y, z);
+  setWind(g: number, x: number, y: number, z: number): void {
+    this.set.setWind(g, x, y, z);
   }
 
-  reset(): void {
+  reset(g: number): void {
     if (this.host.lost()) return;
-    this.cloth.reset();
+    this.set.reset(g);
+  }
+
+  step(dt: number): void {
+    if (this.host.lost()) return;
+    this.set.step(dt, this.host.changeFrame());
   }
 
   /** Its buffers at once — its work is submitted — and its textures with the frame's. */
   dispose(): void {
-    this.cloth.dispose();
-    this.host.retire(this.cloth.particles.textures);
+    this.set.dispose();
+    for (let g = 0; g < this.set.size; g++) this.host.retire(this.set.particles(g).textures);
   }
 
-  /** The particles where the last step left them: the parity check's door, waits on the device. */
-  read(): Promise<Float32Array> {
-    return this.cloth.read();
+  /** Garment `g`'s particles where its last step left them: the parity check's, waits on the device. */
+  read(g: number): Promise<Float32Array> {
+    return this.set.read(g);
   }
 }
 
-class CpuCloth implements SkinnedClothSolver {
+class CpuClothSet implements SkinnedClothSet {
   readonly runsOn = 'cpu';
-  readonly particles: ClothParticlesHandle;
-  private readonly cloth: SkinnedCloth;
-  /** The frame's particles at `alpha`, before they go up. */
-  private readonly staging: Float32Array;
+  readonly particles: readonly ClothParticlesHandle[];
+  private readonly cloths: readonly SkinnedCloth[];
+  /** Each garment's particles at `alpha`, before they go up. */
+  private readonly staging: readonly Float32Array[];
 
   constructor(
     private readonly renderer: RendererApi,
-    setup: SkinnedClothSetup,
+    setups: readonly SkinnedClothSetup[],
   ) {
-    this.cloth = new SkinnedCloth(setup);
-    this.particles = renderer.createClothParticles(this.cloth.count);
-    this.staging = new Float32Array(this.cloth.count * 3);
+    this.cloths = setups.map((setup) => new SkinnedCloth(setup));
+    this.particles = this.cloths.map((cloth) => renderer.createClothParticles(cloth.count));
+    this.staging = this.cloths.map((cloth) => new Float32Array(cloth.count * 3));
   }
 
-  step(globals: Float32Array, model: Float32Array, dt: number): void {
-    this.cloth.setPose(globals, model);
-    this.cloth.advance(dt);
-    this.cloth.interpolate(this.cloth.alpha, this.staging);
-    this.renderer.updateClothParticles(this.particles, this.staging);
+  setPose(g: number, globals: Float32Array, model: Float32Array): void {
+    this.at(g).setPose(globals, model);
   }
 
-  setWind(x: number, y: number, z: number): void {
-    this.cloth.setWind(x, y, z);
+  setWind(g: number, x: number, y: number, z: number): void {
+    this.at(g).setWind(x, y, z);
   }
 
-  reset(): void {
-    this.cloth.reset();
+  reset(g: number): void {
+    this.at(g).reset();
+  }
+
+  step(dt: number): void {
+    for (let g = 0; g < this.cloths.length; g++) {
+      const cloth = this.cloths[g] as SkinnedCloth;
+      const staging = this.staging[g] as Float32Array;
+      cloth.advance(dt);
+      cloth.interpolate(cloth.alpha, staging);
+      this.renderer.updateClothParticles(this.particles[g] as ClothParticlesHandle, staging);
+    }
   }
 
   dispose(): void {
-    this.renderer.disposeClothParticles(this.particles);
+    for (const particles of this.particles) this.renderer.disposeClothParticles(particles);
+  }
+
+  /** Garment `g`'s particles where its last step left them, as the device set reads its own. */
+  read(g: number): Promise<Float32Array> {
+    return Promise.resolve(new Float32Array(this.at(g).positions));
+  }
+
+  private at(g: number): SkinnedCloth {
+    const cloth = this.cloths[g];
+    if (cloth === undefined) throw new Error(`skinned cloth set: no garment ${g}`);
+    return cloth;
   }
 }

package/src/render/staticDraws.ts

@@ -0,0 +1,95 @@
+/**
+ * Draws that do not change between frames, captured once from an enumeration and replayed into any
+ * colour pass: what `createStaticDraws` keeps, and the one rule both backends replay it by.
+ *
+ * **Captured, not referenced.** An enumeration is a closure over the caller's state, written to
+ * allocate nothing, so it hands a sink its scratch: the matrix it fills for every entry and the
+ * count it rewrites for the next batch. A list kept across frames copies both when it is made, so
+ * what it draws is what the enumeration said then. Meshes, batches and materials are held by
+ * reference: they are the caller's, and disposing one a list still holds is the caller's error.
+ *
+ * **Rigid meshes and instanced batches only.** A skinned mesh is posed every frame and a scatter
+ * batch bends with every frame's wind, so neither can be kept, and both are refused by name rather
+ * than captured in the pose they happened to have. A caller draws them each frame as it always has.
+ *
+ * What a backend does with the list is its own: WebGL2 replays the entries every frame through
+ * the scene-caster path, and WebGPU records them once into a render bundle per view. See
+ * `RendererApi.createStaticDraws` for what a caller is promised, which is the same on both.
+ */
+import type { InstancedHandle, MeshHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SceneCasterMaterial, ShadowCasterSink, ShadowCasters } from './shadowCasters.ts';
+
+/** A list from `createStaticDraws`. Opaque but for its size. */
+export interface StaticDrawsHandle {
+  /** How many entries it holds: meshes and batches, a batch counting once. */
+  readonly draws: number;
+}
+
+/** One captured entry. */
+export type StaticEntry =
+  | {
+      readonly kind: 'mesh';
+      readonly mesh: MeshHandle;
+      readonly model: Float32Array;
+      readonly material: SceneCasterMaterial;
+    }
+  | {
+      readonly kind: 'instanced';
+      readonly batch: InstancedHandle;
+      readonly data: MeshInstances;
+      readonly material: SceneCasterMaterial;
+    };
+
+/** What both backends hold: the entries, and whether the list has been disposed. */
+export interface StaticDrawsList extends StaticDrawsHandle {
+  readonly entries: readonly StaticEntry[];
+  disposed: boolean;
+}
+
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export function captureStaticDraws(casters: ShadowCasters): StaticDrawsList {
+  const entries: StaticEntry[] = [];
+  const sink: ShadowCasterSink = {
+    mesh: (mesh, model, material) => {
+      entries.push({
+        kind: 'mesh',
+        mesh,
+        model: new Float32Array(model as Float32Array),
+        material: material ?? null,
+      });
+    },
+    instanced: (batch, data, material) => {
+      /* The batch's placements are on the device already; the count is the caller's scratch. */
+      entries.push({ kind: 'instanced', batch, data: { ...data }, material: material ?? null });
+    },
+    skinnedMesh: () => {
+      throw new Error(
+        'createStaticDraws: a skinned mesh is posed every frame, so a list kept across frames ' +
+          'cannot hold one. Draw it each frame, with drawMesh or drawSceneCasters.',
+      );
+    },
+    scatter: () => {
+      throw new Error(
+        'createStaticDraws: a scatter batch bends with every frame’s wind, so a list kept across ' +
+          'frames cannot hold one. Draw it each frame with drawScatter.',
+      );
+    },
+  };
+  casters(sink);
+  return {
+    entries,
+    get draws() {
+      return entries.length;
+    },
+    disposed: false,
+  };
+}
+
+/** Hand every entry to `sink`, in the order it was captured. */
+export function replayStaticDraws(list: StaticDrawsList, sink: ShadowCasterSink): void {
+  for (const entry of list.entries) {
+    if (entry.kind === 'mesh') sink.mesh(entry.mesh, entry.model, entry.material);
+    else sink.instanced?.(entry.batch, entry.data, entry.material);
+  }
+}

package/src/render/surfaceLayers.ts

@@ -0,0 +1,57 @@
+/**
+ * A material blended from layers by a mask: `SurfaceMaterial.layers`, and the two vectors
+ * `shaders/flat/layered.ts` reads it from.
+ */
+
+/** The most layers a material blends: a base and one for each of the mask's four channels. */
+export const MAX_SURFACE_LAYERS = 5;
+
+/**
+ * Up to five layers, each its own colour, normal and roughness at its own repeat, blended by a mask.
+ *
+ * **Layer `i` is layer `i` of the material's arrays**: `albedo`, `normal` and `orm` each an array
+ * whose layers are the material's layers in order, read at the mesh's coordinates times
+ * `repeats[i]`, so rock can repeat forty times across a cliff while the moss on it repeats three.
+ * **The mask** is read at the mesh's own coordinates and lays each layer over those before it: red
+ * lays layer 1 over the base, green layer 2 over that, blue layer 3, alpha layer 4. Its layer 0 is
+ * read, from where a shading model's map goes, which is why a layered material carries no
+ * `modelMap`. `emissiveLayer` gives the material's emissive map to one layer, glowing where that
+ * layer shows and nowhere it is covered; absent, the map glows as on any material.
+ *
+ * **What it gives up**: every layer's maps are read wherever any shows, three reads a layer, so five
+ * layers are fifteen reads where one material is three; layers share an array's size and format; a
+ * cutout reads the base layer's alpha; and the mask is sampled linear, so it is uploaded as data
+ * (`colorSpace: 'linear'`).
+ */
+export interface SurfaceLayers<Texture> {
+  /** The weights, red to alpha laying layers 1 to 4, read at the mesh's coordinates. */
+  readonly mask: Texture;
+  /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
+  readonly repeats: readonly number[];
+  /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
+  readonly emissiveLayer?: number;
+}
+
+/** Floats `packSurfaceLayers` writes: two vectors. */
+export const LAYER_FLOATS = 8;
+
+/**
+ * `layers` into `out`: the five repeats (1 for a layer not given), then how many layers there are
+ * and which one glows (−1 for none); zeros, no layers, where there are none. A repeat that is not a
+ * positive number is 1, so a layer is never laid at a scale that collapses it to a point.
+ */
+export function packSurfaceLayers<Texture>(
+  layers: SurfaceLayers<Texture> | null | undefined,
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (layers === null || layers === undefined || layers.repeats.length === 0) return;
+  const count = Math.min(layers.repeats.length, MAX_SURFACE_LAYERS);
+  for (let i = 0; i < MAX_SURFACE_LAYERS; i++) {
+    const repeat = i < count ? (layers.repeats[i] as number) : 1;
+    out[i] = Number.isFinite(repeat) && repeat > 0 ? repeat : 1;
+  }
+  out[5] = count;
+  const glow = layers.emissiveLayer;
+  out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
+}

package/src/render/surfaceOverlay.ts

@@ -29,12 +29,24 @@ export interface OverlayRegion {
  * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
  * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
  * surface wears, not light it gives off.
+ *
+ * **Or, with `mode: 'blend'`, a colour the surface is pulled toward**, lit like the rest of it: the
+ * base colour mixed toward the rim's by the edge times `alpha`, before any light reads it, so the
+ * rim is bright where light falls and dark where none does. The colour is `colour` times
+ * `intensity`, each channel held at 1 as a base colour is, so a colour of 8 red is a red of 1 and
+ * not a glow; `alpha` is the weight, which may pass 1 to saturate the edge sooner.
  */
 export interface SurfaceRim {
   readonly colour: Vec3;
-  /** How bright, 0 for none. Multiplied with `alpha`. */
+  /**
+   * How bright, 0 for none, multiplied with `alpha`. Where the rim blends it scales `colour`
+   * instead, so 0 there is a rim of black, and `alpha` alone says how much: 0 for none.
+   */
   readonly intensity: number;
+  /** The rim's weight, 1 unless given. */
   readonly alpha?: number;
+  /** `'add'`, the default, lays the rim on as glow; `'blend'` pulls the base colour toward it, lit. */
+  readonly mode?: 'add' | 'blend';
   /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
   readonly falloff?: number;
   /**
@@ -122,10 +134,11 @@ function region(out: Float32Array, at: number, r: OverlayRegion | undefined | nu
  * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
  * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
  *
- * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim). A blending rim: the colour
+ *   times intensity, each channel held at 1, and the alpha alone
  * - 1: falloff, upward lean, contrast, mask weight
  * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
- * - 4: the pulse's low and high (1 and 1 where none)
+ * - 4: the pulse's low and high (1 and 1 where none), and the mode: 0 adds, 1 blends
  * - 5: the rim's mask region
  * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
  * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
@@ -138,10 +151,14 @@ export function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32A
   const images = overlay.maps !== undefined;
   const rim = overlay.rim;
   if (rim !== undefined) {
-    out[0] = finite(rim.colour[0], 0);
-    out[1] = finite(rim.colour[1], 0);
-    out[2] = finite(rim.colour[2], 0);
-    out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+    const blend = rim.mode === 'blend';
+    const scale = blend ? finite(rim.intensity, 0) : 1;
+    for (let c = 0; c < 3; c++) {
+      const channel = finite(rim.colour[c], 0) * scale;
+      out[c] = blend ? Math.min(Math.max(channel, 0), 1) : channel;
+    }
+    out[3] = Math.max(0, (blend ? 1 : finite(rim.intensity, 0)) * finite(rim.alpha, 1));
+    out[18] = blend ? 1 : 0;
     out[4] = Math.max(0, finite(rim.falloff, 1.5));
     out[5] = Math.max(0, finite(rim.upward, 0.4));
     out[6] = Math.max(0, finite(rim.contrast, 1));

package/src/render/surfaceProjection.ts

@@ -0,0 +1,57 @@
+/**
+ * A material's maps placed by where a point is in the world: `SurfaceMaterial.projection`, and the
+ * one vector `shaders/flat/worldUv.ts` reads it from.
+ */
+
+/**
+ * Texture coordinates from the world rather than from the mesh.
+ *
+ * **`'planar'`** lays the maps across the two horizontal axes, `x` and `z`: ground whose mesh
+ * carries flat coordinates, or none worth reading, shows its texture at `scale` repeats a metre.
+ * **`'triplanar'`** reads each map on the three planes across `x`, `y` and `z` and blends them by
+ * how squarely the surface faces each, the normal's components raised to `sharpness`, so walls and
+ * rock wear a texture without stretching. See `worldUv.ts` for the normal map's blend.
+ *
+ * **What it gives up**: the world's coordinates do not move with a mesh, so a moving mesh slides
+ * under its texture; triplanar reads every map three times; and the material's `uScale`, `vScale`
+ * and offsets, which are the mesh's coordinates', do not apply.
+ */
+export interface SurfaceProjection {
+  readonly kind: 'planar' | 'triplanar';
+  /** Repeats a metre: 2 lays a texture every half metre. */
+  readonly scale: number;
+  /** How sharply triplanar's planes meet: the exponent on the normal. 4 unless given. */
+  readonly sharpness?: number;
+}
+
+/** Floats `packSurfaceProjection` writes: one vector. */
+export const PROJECTION_FLOATS = 4;
+
+/**
+ * `projection` into `out`: its kind (0 none, 1 planar, 2 triplanar), its repeats a metre and its
+ * sharpness; zeros for none. A scale that is not finite and above zero projects nothing, so a
+ * material is never drawn at a scale that collapses its texture to a point.
+ */
+export function packSurfaceProjection(
+  projection: SurfaceProjection | null | undefined,
+  out: Float32Array,
+): void {
+  out.fill(0);
+  if (projection === null || projection === undefined) return;
+  const scale = projection.scale;
+  if (!Number.isFinite(scale) || scale <= 0) return;
+  out[0] = projection.kind === 'triplanar' ? 2 : 1;
+  out[1] = scale;
+  const sharpness = projection.sharpness ?? 4;
+  out[2] = Number.isFinite(sharpness) ? Math.min(Math.max(sharpness, 1), 64) : 4;
+}
+
+/** Whether a material projects its maps at all. */
+export function projects(projection: SurfaceProjection | null | undefined): boolean {
+  return (
+    projection !== null &&
+    projection !== undefined &&
+    Number.isFinite(projection.scale) &&
+    projection.scale > 0
+  );
+}