@driftengine/core 4.5.0 → 4.6.0

package/src/geometry/solidRound.ts

@@ -0,0 +1,443 @@
+/**
+ * The round solids: cylinder, cone, frustum, tube, sphere, hemisphere, icosphere, capsule, torus
+ * and lathe — all but the icosphere one revolve of a profile around +Y.
+ *
+ * A profile is `(r, y)` points. Revolving it, the vertex at angle θ sits at (r·cos θ, y, r·sin θ),
+ * and a quad is wound so that the profile's direction crossed with the direction of increasing θ
+ * points outward: a profile climbing on its outer side, or running outward along a bottom cap,
+ * faces out. Where the profile touches the axis a quad collapses to a triangle and only the
+ * triangle is written, so no edge is counted twice.
+ *
+ * `smooth` shares vertices around the axis with normals that vary around it; the default,
+ * faceted, gives every quad its own four vertices and its own normal. Texture u runs around (0..1,
+ * the seam duplicated) and v along the profile (0..1 by length).
+ */
+import type { Solid } from './solid.ts';
+import { SolidWriter } from './solidWriter.ts';
+
+/** A profile point with the in-plane normal it wants when smooth: (nr, ny) across the profile. */
+interface ProfilePoint {
+  readonly r: number;
+  readonly y: number;
+  readonly nr: number;
+  readonly ny: number;
+}
+
+/**
+ * Revolve one or more strips — runs of profile points whose normals are continuous — around +Y.
+ * A strip's normals are used when smooth; faceted quads take the normal their corners imply.
+ */
+function revolve(
+  strips: readonly (readonly ProfilePoint[])[],
+  segments: number,
+  smooth: boolean,
+): Solid {
+  const n = Math.max(3, Math.floor(segments));
+  const out = new SolidWriter();
+  let total = 0;
+  for (const strip of strips) {
+    for (let i = 0; i + 1 < strip.length; i++) total += span(strip[i], strip[i + 1]);
+  }
+  let walked = 0;
+  for (const strip of strips) {
+    const v: number[] = [];
+    for (let i = 0; i < strip.length; i++) {
+      if (i > 0) walked += span(strip[i - 1], strip[i]);
+      v.push(total > 0 ? walked / total : 0);
+    }
+    if (smooth) revolveSmooth(out, strip, v, n);
+    else revolveFaceted(out, strip, v, n);
+  }
+  return out.finish();
+}
+
+function span(a: ProfilePoint | undefined, b: ProfilePoint | undefined): number {
+  return a && b ? Math.hypot(b.r - a.r, b.y - a.y) : 0;
+}
+
+function revolveSmooth(
+  out: SolidWriter,
+  strip: readonly ProfilePoint[],
+  v: number[],
+  n: number,
+): void {
+  const base = out.vertexCount;
+  const row = n + 1;
+  for (let i = 0; i < strip.length; i++) {
+    const p = strip[i];
+    if (!p) continue;
+    for (let j = 0; j <= n; j++) {
+      const t = (2 * Math.PI * (j % n)) / n;
+      const c = Math.cos(t);
+      const s = Math.sin(t);
+      out.vertex(p.r * c, p.y, p.r * s, p.nr * c, p.ny, p.nr * s, j / n, v[i] ?? 0);
+    }
+  }
+  for (let i = 0; i + 1 < strip.length; i++) {
+    const r0 = strip[i]?.r ?? 0;
+    const r1 = strip[i + 1]?.r ?? 0;
+    for (let j = 0; j < n; j++) {
+      const a = base + i * row + j;
+      const b = a + row;
+      const c = b + 1;
+      const d = a + 1;
+      emit(out, a, b, c, d, r0, r1);
+    }
+  }
+}
+
+function revolveFaceted(
+  out: SolidWriter,
+  strip: readonly ProfilePoint[],
+  v: number[],
+  n: number,
+): void {
+  for (let i = 0; i + 1 < strip.length; i++) {
+    const p = strip[i];
+    const q = strip[i + 1];
+    if (!p || !q) continue;
+    for (let j = 0; j < n; j++) {
+      const t0 = (2 * Math.PI * j) / n;
+      const t1 = (2 * Math.PI * ((j + 1) % n)) / n;
+      const c0 = Math.cos(t0);
+      const s0 = Math.sin(t0);
+      const c1 = Math.cos(t1);
+      const s1 = Math.sin(t1);
+      const ax = p.r * c0;
+      const az = p.r * s0;
+      const bx = q.r * c0;
+      const bz = q.r * s0;
+      const cx = q.r * c1;
+      const cz = q.r * s1;
+      const dx = p.r * c1;
+      const dz = p.r * s1;
+      /* The normal from the diagonals, (c − a) × (d − b): right for a quad and for the triangle a
+         quad collapses to at the axis, where the edge-based cross product is zero. */
+      const ex = cx - ax;
+      const ey = q.y - p.y;
+      const ez = cz - az;
+      const fx = dx - bx;
+      const fy = p.y - q.y;
+      const fz = dz - bz;
+      let nx = ey * fz - ez * fy;
+      let ny = ez * fx - ex * fz;
+      let nz = ex * fy - ey * fx;
+      const len = Math.hypot(nx, ny, nz) || 1;
+      nx /= len;
+      ny /= len;
+      nz /= len;
+      const u0 = j / n;
+      const u1 = (j + 1) / n;
+      const a = out.vertex(ax, p.y, az, nx, ny, nz, u0, v[i] ?? 0);
+      const b = out.vertex(bx, q.y, bz, nx, ny, nz, u0, v[i + 1] ?? 0);
+      const c = out.vertex(cx, q.y, cz, nx, ny, nz, u1, v[i + 1] ?? 0);
+      const d = out.vertex(dx, p.y, dz, nx, ny, nz, u1, v[i] ?? 0);
+      emit(out, a, b, c, d, p.r, q.r);
+    }
+  }
+}
+
+/** Quad `a b c d`, or the one triangle left of it where either end of the profile step is on the axis. */
+function emit(
+  out: SolidWriter,
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+  r0: number,
+  r1: number,
+): void {
+  if (r0 <= 1e-12 && r1 <= 1e-12) return;
+  if (r0 <= 1e-12) out.triangle(a, b, c);
+  else if (r1 <= 1e-12) out.triangle(a, b, d);
+  else out.quad(a, b, c, d);
+}
+
+/** Points along a polyline profile, each segment its own strip so every corner creases. */
+function creasedStrips(points: readonly (readonly [number, number])[]): ProfilePoint[][] {
+  const strips: ProfilePoint[][] = [];
+  for (let i = 0; i + 1 < points.length; i++) {
+    const [r0, y0] = points[i] ?? [0, 0];
+    const [r1, y1] = points[i + 1] ?? [0, 0];
+    const len = Math.hypot(r1 - r0, y1 - y0) || 1;
+    const nr = (y1 - y0) / len;
+    const ny = -(r1 - r0) / len;
+    strips.push([
+      { r: r0, y: y0, nr, ny },
+      { r: r1, y: y1, nr, ny },
+    ]);
+  }
+  return strips;
+}
+
+/** An arc of the circle centred (cr, cy), radius `radius`, from angle `a0` to `a1` in `steps`. */
+function arc(
+  cr: number,
+  cy: number,
+  radius: number,
+  a0: number,
+  a1: number,
+  steps: number,
+): ProfilePoint[] {
+  const points: ProfilePoint[] = [];
+  for (let s = 0; s <= steps; s++) {
+    const a = a0 + ((a1 - a0) * s) / steps;
+    const c = Math.cos(a);
+    const sn = Math.sin(a);
+    points.push({ r: Math.max(0, cr + radius * c), y: cy + radius * sn, nr: c, ny: sn });
+  }
+  return points;
+}
+
+/** A cylinder of `radius` and `length` along Y, centred, capped. */
+export function solidCylinder(
+  radius: number,
+  length: number,
+  segments: number,
+  smooth = false,
+): Solid {
+  return solidFrustum(radius, radius, length, segments, smooth);
+}
+
+/** A cone: base `radius` at −length/2, apex at +length/2. */
+export function solidCone(radius: number, length: number, segments: number, smooth = false): Solid {
+  return solidFrustum(radius, 0, length, segments, smooth);
+}
+
+/** A frustum with explicit radii at its bottom (−length/2) and top (+length/2), capped. */
+export function solidFrustum(
+  radiusBottom: number,
+  radiusTop: number,
+  length: number,
+  segments: number,
+  smooth = false,
+): Solid {
+  const h = length / 2;
+  return revolve(
+    creasedStrips([
+      [0, -h],
+      [radiusBottom, -h],
+      [radiusTop, h],
+      [0, h],
+    ]),
+    segments,
+    smooth,
+  );
+}
+
+/** A hollow cylinder: outer `radius`, wall `thickness`, `length` along Y, centred. Four segments make a square frame. */
+export function solidTube(
+  radius: number,
+  thickness: number,
+  length: number,
+  segments: number,
+  smooth = false,
+): Solid {
+  const h = length / 2;
+  const inner = Math.max(0, radius - thickness);
+  return revolve(
+    creasedStrips([
+      [inner, -h],
+      [radius, -h],
+      [radius, h],
+      [inner, h],
+      [inner, -h],
+    ]),
+    segments,
+    smooth,
+  );
+}
+
+/** A sphere of `radius`: `segments` around, half as many from pole to pole. */
+export function solidSphere(radius: number, segments: number, smooth = false): Solid {
+  const rings = Math.max(2, Math.floor(segments / 2));
+  return revolve([arc(0, 0, radius, -Math.PI / 2, Math.PI / 2, rings)], segments, smooth);
+}
+
+/** A dome toward +Y on a flat base at the origin. */
+export function solidHemisphere(radius: number, segments: number, smooth = false): Solid {
+  const rings = Math.max(1, Math.floor(segments / 4));
+  const base: ProfilePoint[] = [
+    { r: 0, y: 0, nr: 0, ny: -1 },
+    { r: radius, y: 0, nr: 0, ny: -1 },
+  ];
+  return revolve([base, arc(0, 0, radius, 0, Math.PI / 2, rings)], segments, smooth);
+}
+
+/** A capsule: a cylinder of `length` (excluding the caps) with hemispherical ends, along Y. */
+export function solidCapsule(
+  radius: number,
+  length: number,
+  segments: number,
+  smooth = false,
+): Solid {
+  const rings = Math.max(1, Math.floor(segments / 4));
+  const h = length / 2;
+  return revolve(
+    [
+      arc(0, -h, radius, -Math.PI / 2, 0, rings),
+      [
+        { r: radius, y: -h, nr: 1, ny: 0 },
+        { r: radius, y: h, nr: 1, ny: 0 },
+      ],
+      arc(0, h, radius, 0, Math.PI / 2, rings),
+    ],
+    segments,
+    smooth,
+  );
+}
+
+/** A torus around +Y: ring radius `major`, tube radius `minor`, `segments` around and `sides` across. */
+export function solidTorus(
+  major: number,
+  minor: number,
+  segments: number,
+  sides: number,
+  smooth = false,
+): Solid {
+  return revolve(
+    [arc(major, 0, minor, 0, 2 * Math.PI, Math.max(3, Math.floor(sides)))],
+    segments,
+    smooth,
+  );
+}
+
+/**
+ * A profile (`r, y` pairs, bottom to top) revolved around +Y. An end off the axis is closed with a
+ * flat cap, so any profile makes a solid. Every profile corner creases, faceted or smooth.
+ */
+export function solidLathe(profile: ArrayLike<number>, segments: number, smooth = false): Solid {
+  const points: [number, number][] = [];
+  for (let i = 0; i + 1 < profile.length; i += 2)
+    points.push([profile[i] ?? 0, profile[i + 1] ?? 0]);
+  const first = points[0];
+  const last = points[points.length - 1];
+  if (first && first[0] > 1e-12) points.unshift([0, first[1]]);
+  if (last && last[0] > 1e-12) points.push([0, last[1]]);
+  return revolve(creasedStrips(points), segments, smooth);
+}
+
+/**
+ * An icosahedron subdivided `level` times onto a sphere of `radius`. Faceted by default — every
+ * triangle its own vertices and face normal — or smooth, sharing vertices with radial normals.
+ */
+export function solidIcosphere(radius: number, level: number, smooth = false): Solid {
+  const t = (1 + Math.sqrt(5)) / 2;
+  const verts: number[][] = [
+    [-1, t, 0],
+    [1, t, 0],
+    [-1, -t, 0],
+    [1, -t, 0],
+    [0, -1, t],
+    [0, 1, t],
+    [0, -1, -t],
+    [0, 1, -t],
+    [t, 0, -1],
+    [t, 0, 1],
+    [-t, 0, -1],
+    [-t, 0, 1],
+  ].map(unit);
+  let faces: number[][] = [
+    [0, 11, 5],
+    [0, 5, 1],
+    [0, 1, 7],
+    [0, 7, 10],
+    [0, 10, 11],
+    [1, 5, 9],
+    [5, 11, 4],
+    [11, 10, 2],
+    [10, 7, 6],
+    [7, 1, 8],
+    [3, 9, 4],
+    [3, 4, 2],
+    [3, 2, 6],
+    [3, 6, 8],
+    [3, 8, 9],
+    [4, 9, 5],
+    [2, 4, 11],
+    [6, 2, 10],
+    [8, 6, 7],
+    [9, 8, 1],
+  ];
+  for (let l = 0; l < Math.floor(level); l++) {
+    const cache = new Map<string, number>();
+    const mid = (a: number, b: number): number => {
+      const key = a < b ? `${a},${b}` : `${b},${a}`;
+      const hit = cache.get(key);
+      if (hit !== undefined) return hit;
+      const va = verts[a] ?? [0, 0, 0];
+      const vb = verts[b] ?? [0, 0, 0];
+      verts.push(
+        unit([
+          (va[0] ?? 0) + (vb[0] ?? 0),
+          (va[1] ?? 0) + (vb[1] ?? 0),
+          (va[2] ?? 0) + (vb[2] ?? 0),
+        ]),
+      );
+      cache.set(key, verts.length - 1);
+      return verts.length - 1;
+    };
+    const next: number[][] = [];
+    for (const [a = 0, b = 0, c = 0] of faces) {
+      const ab = mid(a, b);
+      const bc = mid(b, c);
+      const ca = mid(c, a);
+      next.push([a, ab, ca], [b, bc, ab], [c, ca, bc], [ab, bc, ca]);
+    }
+    faces = next;
+  }
+  const out = new SolidWriter();
+  const uv = (p: number[]): [number, number] => [
+    0.5 + Math.atan2(p[2] ?? 0, p[0] ?? 0) / (2 * Math.PI),
+    0.5 + Math.asin(Math.max(-1, Math.min(1, p[1] ?? 0))) / Math.PI,
+  ];
+  if (smooth) {
+    for (const p of verts) {
+      const [u, v] = uv(p);
+      out.vertex(
+        (p[0] ?? 0) * radius,
+        (p[1] ?? 0) * radius,
+        (p[2] ?? 0) * radius,
+        p[0] ?? 0,
+        p[1] ?? 0,
+        p[2] ?? 0,
+        u,
+        v,
+      );
+    }
+    /* The table's faces run counter-clockwise seen from outside, as every face here does. */
+    for (const [a = 0, b = 0, c = 0] of faces) out.triangle(a, b, c);
+    return out.finish();
+  }
+  for (const [a = 0, b = 0, c = 0] of faces) {
+    const pa = verts[a] ?? [0, 0, 0];
+    const pb = verts[b] ?? [0, 0, 0];
+    const pc = verts[c] ?? [0, 0, 0];
+    const n = unit([
+      ((pa[0] ?? 0) + (pb[0] ?? 0) + (pc[0] ?? 0)) / 3,
+      ((pa[1] ?? 0) + (pb[1] ?? 0) + (pc[1] ?? 0)) / 3,
+      ((pa[2] ?? 0) + (pb[2] ?? 0) + (pc[2] ?? 0)) / 3,
+    ]);
+    const base = out.vertexCount;
+    for (const p of [pa, pb, pc]) {
+      const [u, v] = uv(p);
+      out.vertex(
+        (p[0] ?? 0) * radius,
+        (p[1] ?? 0) * radius,
+        (p[2] ?? 0) * radius,
+        n[0] ?? 0,
+        n[1] ?? 0,
+        n[2] ?? 0,
+        u,
+        v,
+      );
+    }
+    out.triangle(base, base + 1, base + 2);
+  }
+  return out.finish();
+}
+
+function unit(p: number[]): number[] {
+  const len = Math.hypot(p[0] ?? 0, p[1] ?? 0, p[2] ?? 0) || 1;
+  return [(p[0] ?? 0) / len, (p[1] ?? 0) / len, (p[2] ?? 0) / len];
+}

package/src/geometry/solidWriter.ts

@@ -0,0 +1,58 @@
+/**
+ * The accumulator every solid primitive writes through: a vertex at a time, a triangle or a quad at
+ * a time, finished into a `Solid`.
+ *
+ * Internal to the geometry modules and not in the barrel — a caller building geometry of its own
+ * wants `MeshBuilder` or typed arrays, and this exists so the primitives share one place that
+ * decides how a vertex is laid out.
+ */
+import { GrowableF32, GrowableU32 } from './growable.ts';
+import type { Solid } from './solid.ts';
+
+export class SolidWriter {
+  private readonly positions = new GrowableF32();
+  private readonly normals = new GrowableF32();
+  private readonly uvs = new GrowableF32();
+  private readonly indices = new GrowableU32();
+  private count = 0;
+
+  /** Add one vertex and return its index. The normal is taken as given; pass it unit length. */
+  vertex(
+    px: number,
+    py: number,
+    pz: number,
+    nx: number,
+    ny: number,
+    nz: number,
+    u: number,
+    v: number,
+  ): number {
+    this.positions.push(px, py, pz);
+    this.normals.push(nx, ny, nz);
+    this.uvs.push(u, v);
+    return this.count++;
+  }
+
+  triangle(a: number, b: number, c: number): void {
+    this.indices.push(a, b, c);
+  }
+
+  /** Two triangles over a counter-clockwise quad `a b c d`. */
+  quad(a: number, b: number, c: number, d: number): void {
+    this.indices.push(a, b, c, a, c, d);
+  }
+
+  /** How many vertices so far, which is the index the next `vertex` returns. */
+  get vertexCount(): number {
+    return this.count;
+  }
+
+  finish(): Solid {
+    return {
+      positions: this.positions.toTyped(),
+      normals: this.normals.toTyped(),
+      uvs: this.uvs.toTyped(),
+      indices: this.indices.toTyped(),
+    };
+  }
+}

package/src/index.ts

@@ -391,6 +391,17 @@ export type {
 } from './render/gi/globalField.ts';
 export { FIELD_FADE_SEC, LightField } from './render/driftLight/lightField.ts';
 export type { LightFieldOptions, LightFieldSource } from './render/driftLight/lightField.ts';
+export {
+  DENSE_MAX_AXIS,
+  DENSE_MAX_HEIGHT,
+  bakeDenseField,
+} from './render/driftLight/denseField.ts';
+export type { DenseLightVolume } from './render/driftLight/denseField.ts';
+export { WorldLightField } from './render/driftLight/worldLightField.ts';
+export type { WorldLightFieldOptions } from './render/driftLight/worldLightField.ts';
+export { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './render/surfaceEffects.ts';
+export type { SurfaceLayerEffect } from './render/surfaceEffects.ts';
+export type { FieldLight } from './render/driftLight/bake.ts';
 export {
   GI_SCREEN_MARCH,
   SCREEN_TRACE_BIAS_M,
@@ -603,8 +614,11 @@ export type { GpuIdentity, DescribeGpuOptions } from './render/gpuCapability.ts'
 export {
   DEFAULT_POINT_LIGHT_VIEW_RANGE,
   createPointLightBuffer,
+  selectGridLights,
   selectPointLights,
 } from './render/pointLightSelection.ts';
+export { LIGHT_GRID_MAX_CELLS, createLightGrid, gatherLights } from './render/lightGrid.ts';
+export type { LightGrid } from './render/lightGrid.ts';
 export type { PointLightBuffer, PointLightSource } from './render/pointLightSelection.ts';
 export { createFlame, flameFrequencyHz, updateFlame } from './render/flameLight.ts';
 export type { Flame, FlameOptions } from './render/flameLight.ts';
@@ -658,6 +672,38 @@ export { WaterRenderer } from './render/waterRenderer.ts';
 export type { WaterBody, WaterBounds, WaterSettings } from './render/waterRenderer.ts';
 export { MeshBuilder } from './geometry/meshBuilder.ts';
 export { concatMeshes, placeMesh } from './geometry/meshConcat.ts';
+export {
+  emptySolid,
+  mergeSolids,
+  solidToMesh,
+  solidVolume,
+  transformSolid,
+} from './geometry/solid.ts';
+export type { Solid } from './geometry/solid.ts';
+export {
+  solidBox,
+  solidExtrude,
+  solidPrism,
+  solidQuad,
+  solidRoundedBox,
+  solidSweep,
+} from './geometry/solidFlat.ts';
+export {
+  solidCapsule,
+  solidCone,
+  solidCylinder,
+  solidFrustum,
+  solidHemisphere,
+  solidIcosphere,
+  solidLathe,
+  solidSphere,
+  solidTorus,
+  solidTube,
+} from './geometry/solidRound.ts';
+export { solidIntersect, solidSubtract, solidUnion } from './geometry/csg.ts';
+export { boxBooleanCells, solidBoxBoolean } from './geometry/boxCsg.ts';
+export type { BoxOperation } from './geometry/boxCsg.ts';
+export { smoothSolidNormals } from './geometry/solidNormals.ts';
 /* A tangent frame, which every map in the material track reads. */
 export { generateTangents } from './geometry/tangents.ts';
 export type { MeshBuildOptions } from './geometry/meshBuilder.ts';
@@ -1017,7 +1063,9 @@ export type { FlockParams } from './render/flockRenderer.ts';
 export { buildTree } from './geometry/treeBuilder.ts';
 export type { TreeParams, TreeGeometry } from './geometry/treeBuilder.ts';
 export type { InstanceData } from './render/instancedMesh.ts';
-export type { MeshInstances } from './render/instances.ts';
+export type { InstancedOptions, MeshInstances } from './render/instances.ts';
+export { batchBoxVisible, cullInstances, instancesBox } from './render/instanceCull.ts';
+export type { BoxOccluder } from './render/instanceCull.ts';
 export type { WindProfile, WindState } from './render/wind.ts';
 
 /*
@@ -1055,3 +1103,5 @@ export {
   thawCell,
 } from './world/freeze.ts';
 export type { FreezableWorld, FrozenCell, FrozenCells } from './world/freeze.ts';
+export { HLOD_NONE, HlodSet, createHlodDraws, projectionScaleOf } from './world/hlod.ts';
+export type { HlodDraws, HlodOptions } from './world/hlod.ts';

package/src/render/backend/api.ts

@@ -4,7 +4,7 @@ import type { ReadonlyMat4 } from 'gl-matrix';
 import type { MeshData } from '../mesh.ts';
 import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
-import type { MeshInstances } from '../instances.ts';
+import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -282,6 +282,7 @@ export type RendererApi = Omit<
   | 'drawSdfText'
   | 'disposeSdfText'
   | 'createSurfaceTexture'
+  | 'createSurfaceTextureArray'
   | 'updateSurfaceTexture'
   | 'disposeSurfaceTexture'
   | 'setSurfaceTexture'
@@ -293,6 +294,24 @@ export type RendererApi = Omit<
     options?: Parameters<Renderer['createSurfaceTexture']>[1],
   ): SurfaceTextureHandle;
 
+  /**
+   * Upload several images of one size as the layers of one array texture.
+   *
+   * The same handle a single image returns — every surface texture is an array, and a plain image
+   * is an array of one — so it goes wherever a texture goes: any map of `setMaterial`. A mesh picks
+   * its image per vertex with `MeshData.layers`, and every map of the material is read at that
+   * layer, so an albedo array and an emissive array built in one order pair image with glow by
+   * index. **A merged mesh wearing many images is then one draw and one material change.**
+   *
+   * Every image must be the same size: the device allocates one size for every layer, and the
+   * refusal names the first image that differs. A layer past the end reads the last one.
+   * `updateSurfaceTexture` refuses an array.
+   */
+  createSurfaceTextureArray(
+    sources: readonly TexImageSource[],
+    options?: Parameters<Renderer['createSurfaceTexture']>[1],
+  ): SurfaceTextureHandle;
+
   /**
    * Replace a texture's pixels, keeping the GPU object and its sampler state.
    *
@@ -548,7 +567,7 @@ export type RendererApi = Omit<
    * would wear one expression. Both are refused where the variant is built rather than dropped
    * quietly.
    */
-  createInstanced(mesh: MeshHandle, capacity: number): InstancedHandle;
+  createInstanced(mesh: MeshHandle, capacity: number, options?: InstancedOptions): InstancedHandle;
 
   /**
    * Push placement and colour to the device. Only `data.count` instances are written.

package/src/render/backend/drawFog.ts

@@ -0,0 +1,31 @@
+/**
+ * How a draw meets the medium between it and the eye: the value of the mesh shader's
+ * `uFogEnabled`, which both backends write from this one rule.
+ *
+ * **A surface recedes into the medium; light added to the frame fades in it.** A surface that
+ * covers what is behind it is mixed toward the medium's colour with distance, which is the haze
+ * standing in front of it. An additive draw covers nothing: what is behind it has already been
+ * fogged, and mixing the draw toward the medium's colour and then *adding* it puts that haze into
+ * the frame a second time. So a glow by day added the sky's grey in the shape of the glow, and
+ * added more of it the thicker the air — reported as solid grey cones under every street lamp on
+ * a hazy morning. Faded instead, added light loses what the medium scatters out of it and adds
+ * nothing of its own, which is how the same shader already treats the glow behind frosted glass.
+ *
+ * What fading gives up is the one thing mixing did for a glow: at great distance it disappears
+ * into the air instead of greying into it. That is what light in fog does. What would make it
+ * wrong is an additive draw standing for *lit air* rather than light — and that is what
+ * `drawLightVolume` is for, which is fogged by neither rule.
+ */
+
+/** Out of the medium entirely: `TranslucentMeshOptions.fog` set to false. */
+export const FOG_OFF = 0;
+/** Mixed toward the medium's colour with distance: every surface, and the pass's default. */
+export const FOG_RECEDE = 1;
+/** Scaled down by what the medium scatters and given none of its colour: added light. */
+export const FOG_FADE = 2;
+
+/** The medium rule for a draw that asked for fog or not, and adds its light or covers. */
+export function fogModeOf(fog: boolean, additive: boolean): number {
+  if (!fog) return FOG_OFF;
+  return additive ? FOG_FADE : FOG_RECEDE;
+}

package/src/render/backend/materialChanges.ts

@@ -18,11 +18,14 @@
  * slot on the backend that keeps slots, and comparing every field would cost more than the slot.
  */
 
+import { FOG_RECEDE } from './drawFog.ts';
+
 /** What of a draw's own options its material carries. */
 export interface DrawMaterialOptions {
   readonly opacity: number;
   readonly lit: boolean;
-  readonly fog: boolean;
+  /** How it meets the medium, as `fogModeOf` says; the pass's own is `FOG_RECEDE`. */
+  readonly fog: number;
   readonly toneMapped: boolean;
   /** Whether the draw refracts this time, which a backend decides by whether it has a snapshot. */
   readonly refracting: boolean;
@@ -31,7 +34,11 @@ export interface DrawMaterialOptions {
 /** Whether a draw's options differ from the pass's, so it takes a material and leaves one to restore. */
 export function ownsMaterial(options: DrawMaterialOptions): boolean {
   return (
-    options.opacity < 1 || !options.lit || !options.fog || !options.toneMapped || options.refracting
+    options.opacity < 1 ||
+    !options.lit ||
+    options.fog !== FOG_RECEDE ||
+    !options.toneMapped ||
+    options.refracting
   );
 }