@driftengine/core 4.13.6 → 4.14.0

package/src/render/backend/webgpu/pointSkinPass.ts

@@ -8,7 +8,7 @@
  * for every resource a later write in the frame overwrites. A skin posed twice in a frame draws its
  * last pose everywhere, as a mesh rewritten twice with `updateMesh` does.
  */
-import { reachOf, type PointSkinData, type PointSkinReach } from '../../pointSkin.ts';
+import { reachOf, widenReach, type PointSkinData, type PointSkinReach } from '../../pointSkin.ts';
 import type { GpuMesh } from './buffers.ts';
 import { POINT_SKIN_WGSL, POINT_SKIN_WORKGROUP } from './shaders/pointSkin.wgsl.ts';
 
@@ -30,12 +30,20 @@ export function createPointSkinPipeline(device: GPUDevice): GPUComputePipeline {
 
 export class GpuPointSkin {
   readonly mesh: GpuMesh;
-  readonly reach: PointSkinReach;
+  /** Widened by each rewrite, never narrowed: see `widenReach`. */
+  reach: PointSkinReach;
   private readonly count: number;
   private readonly pipeline: GPUComputePipeline;
-  private readonly joints: GPUBuffer;
+  private joints: GPUBuffer;
+  /** Params, points with their weights, joints named, normals: in that order. */
   private readonly buffers: readonly GPUBuffer[];
-  private readonly group: GPUBindGroup;
+  private group: GPUBindGroup;
+  /** A rewrite's vertices laid out as the buffers hold them, grown to the largest rewrite. */
+  private scratch = {
+    points: new Float32Array(0),
+    named: new Uint32Array(0),
+    normals: new Float32Array(0),
+  };
 
   constructor(device: GPUDevice, pipeline: GPUComputePipeline, mesh: GpuMesh, data: PointSkinData) {
     this.mesh = mesh;
@@ -44,15 +52,11 @@ export class GpuPointSkin {
     const count = data.weights.length / 4;
     this.count = count;
 
-    /* Each influence a vec4: its point, and its weight in w. */
-    const points = new Float32Array(count * 16);
-    for (let i = 0; i < count * 4; i++) {
-      points.set(data.points.subarray(i * 3, i * 3 + 3), i * 4);
-      points[i * 4 + 3] = data.weights[i] as number;
-    }
-    const named = Uint32Array.from(data.joints);
-    const normals = new Float32Array(count * 4);
-    for (let v = 0; v < count; v++) normals.set(data.normals.subarray(v * 3, v * 3 + 3), v * 4);
+    const { points, named, normals } = laidOut(data, count, {
+      points: new Float32Array(count * 16),
+      named: new Uint32Array(count * 4),
+      normals: new Float32Array(count * 4),
+    });
     const params = new Uint32Array([count, 0, 0, 0]);
 
     const made = (
@@ -68,22 +72,22 @@ export class GpuPointSkin {
       device.queue.writeBuffer(buffer, 0, contents);
       return buffer;
     };
-    this.joints = device.createBuffer({
-      label: 'pointSkin.joints',
-      size: Math.max(1, this.reach.joints) * 64,
-      usage: STORAGE | COPY_DST,
-    });
-    const buffers = [
+    this.joints = jointBuffer(device, this.reach.joints);
+    this.buffers = [
       made('pointSkin.params', params, UNIFORM),
       made('pointSkin.points', points, STORAGE),
       made('pointSkin.named', named, STORAGE),
       made('pointSkin.normals', normals, STORAGE),
     ];
-    this.buffers = buffers;
-    const [positionsOut, normalsOut] = mesh.vertexBuffers as [GPUBuffer, GPUBuffer];
-    this.group = device.createBindGroup({
+    this.group = this.bind(device);
+  }
+
+  private bind(device: GPUDevice): GPUBindGroup {
+    const buffers = this.buffers;
+    const [positionsOut, normalsOut] = this.mesh.vertexBuffers as [GPUBuffer, GPUBuffer];
+    return device.createBindGroup({
       label: 'pointSkin.pose',
-      layout: pipeline.getBindGroupLayout(0),
+      layout: this.pipeline.getBindGroupLayout(0),
       entries: [
         { binding: 0, resource: { buffer: buffers[0] as GPUBuffer } },
         { binding: 1, resource: { buffer: this.joints } },
@@ -96,6 +100,37 @@ export class GpuPointSkin {
     });
   }
 
+  /**
+   * Rewrite vertices `first` onward, as many as `data` holds, in place: three queue writes at their
+   * offsets. **A queue write reaches every dispatch submitted after it**, so the renderer submits a
+   * pose already recorded before calling this, and the rewrite reaches the next pose alone, as it
+   * does on WebGL2. A joint none of the skin named before grows the joints buffer, which is made
+   * again with its bind group; the old one goes once the work already submitted is done with it.
+   */
+  rewrite(device: GPUDevice, first: number, data: PointSkinData): void {
+    const count = data.weights.length / 4;
+    const scratch = this.scratch;
+    if (scratch.named.length < count * 4) {
+      this.scratch = {
+        points: new Float32Array(count * 16),
+        named: new Uint32Array(count * 4),
+        normals: new Float32Array(count * 4),
+      };
+    }
+    const { points, named, normals } = laidOut(data, count, this.scratch);
+    const buffers = this.buffers;
+    device.queue.writeBuffer(buffers[1] as GPUBuffer, first * 64, points, 0, count * 16);
+    device.queue.writeBuffer(buffers[2] as GPUBuffer, first * 16, named, 0, count * 4);
+    device.queue.writeBuffer(buffers[3] as GPUBuffer, first * 16, normals, 0, count * 4);
+    const joints = this.reach.joints;
+    this.reach = widenReach(this.reach, data);
+    if (Math.max(1, this.reach.joints) > Math.max(1, joints)) {
+      this.joints.destroy();
+      this.joints = jointBuffer(device, this.reach.joints);
+      this.group = this.bind(device);
+    }
+  }
+
   /** Write the pose's joints and record the dispatch that poses every vertex into `encoder`. */
   pose(device: GPUDevice, encoder: GPUCommandEncoder, matrices: Float32Array): void {
     if (this.reach.joints > 0) {
@@ -113,3 +148,35 @@ export class GpuPointSkin {
     for (const buffer of this.buffers) buffer.destroy();
   }
 }
+
+function jointBuffer(device: GPUDevice, joints: number): GPUBuffer {
+  return device.createBuffer({
+    label: 'pointSkin.joints',
+    size: Math.max(1, joints) * 64,
+    usage: STORAGE | COPY_DST,
+  });
+}
+
+/**
+ * `count` vertices of `data` as the buffers hold them, into `out`'s leading entries: each influence
+ * a vec4 of its point and its weight in w, the joints as integers, each normal a vec4.
+ */
+function laidOut(
+  data: PointSkinData,
+  count: number,
+  out: { points: Float32Array; named: Uint32Array; normals: Float32Array },
+): { points: Float32Array; named: Uint32Array; normals: Float32Array } {
+  for (let i = 0; i < count * 4; i++) {
+    out.points[i * 4] = data.points[i * 3] as number;
+    out.points[i * 4 + 1] = data.points[i * 3 + 1] as number;
+    out.points[i * 4 + 2] = data.points[i * 3 + 2] as number;
+    out.points[i * 4 + 3] = data.weights[i] as number;
+    out.named[i] = data.joints[i] as number;
+  }
+  for (let v = 0; v < count; v++) {
+    out.normals[v * 4] = data.normals[v * 3] as number;
+    out.normals[v * 4 + 1] = data.normals[v * 3 + 1] as number;
+    out.normals[v * 4 + 2] = data.normals[v * 3 + 2] as number;
+  }
+  return out;
+}

package/src/render/backend/webgpu/renderer.ts

@@ -125,7 +125,7 @@ import { ProbeSweeps } from '../../probeSweeps.ts';
 import { ggxMaxLevelFor, irradianceLevelFor, octahedralEdgeFor } from '../../prefilterEnvMap.ts';
 import { environmentTexels } from './environmentTexels.ts';
 import { packIesAtlas } from '../../iesProfile.ts';
-import { fixtureAtlasLayout, fixtureAtlasTexels } from '../../fixtureAtlas.ts';
+import { decalBandTop, fixtureAtlasLayout, fixtureAtlasTexels } from '../../fixtureAtlas.ts';
 import { resolveSurfaceScene } from '../../surfaceScene.ts';
 import { COOKIE_TILE } from '../../lightBudget.ts';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.ts';
@@ -192,6 +192,7 @@ import { GpuPointSkin, createPointSkinPipeline } from './pointSkinPass.ts';
 import {
   poseBounds,
   validatePointSkin,
+  validatePointSkinRange,
   validatePose,
   type PointSkinData,
 } from '../../pointSkin.ts';
@@ -232,6 +233,20 @@ import {
   type SurfaceDetail,
 } from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
+import { EMISSIVE_FLOW_FLOATS, packEmissiveFlow } from '../../emissiveFlow.ts';
+import {
+  BASE_DECAL_FLOATS,
+  BASE_DECAL_TILE,
+  packBaseDecals,
+  type BaseDecal,
+} from '../../baseDecals.ts';
+import { sourceSize } from '../../textureSource.ts';
+import {
+  IRIDESCENT_FLOATS,
+  iridescentRefusal,
+  packIridescentOverlay,
+  type IridescentOverlay,
+} from '../../iridescentOverlay.ts';
 import {
   frameReflectionsRefused,
   resolveFrameReflections,
@@ -439,6 +454,7 @@ import {
 } from '../../lightBudget.ts';
 import { resolveRenderQuality, type RenderQuality } from '../../renderQuality.ts';
 import {
+  mediumSkyFill,
   DEFAULT_GLOBAL_MEDIUM,
   WEAK_GPU_MEDIUM_STEPS,
   createResolvedMediumLamps,
@@ -651,6 +667,8 @@ import { fitProbeGrid } from '../../gi/probeGridFit.ts';
  * `fitProbeGrid` widens it uniformly when the budget bites, so a large scene gets a coarser grid
  * rather than a truncated one.
  */
+/** The ambient a medium is lit by in a frame bound with no environment: none. */
+const MEDIUM_NO_AMBIENT: readonly number[] = [0, 0, 0];
 const INDIRECT_PROBE_SPACING = 2;
 
 /** What the trace is given when a frame never said what was lighting it. */
@@ -3057,6 +3075,12 @@ export class WebGPURenderer implements RendererApi {
   private warnedLayersModelMap = false;
   /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
   private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** `uEmissiveFlow`, a material's glow moved and masked, packed by `packEmissiveFlow`. */
+  private readonly flowFloats = new Float32Array(EMISSIVE_FLOW_FLOATS);
+  /** `uIridescence`, a material's iridescent overlay packed by `packIridescentOverlay`. */
+  private readonly iridescentFloats = new Float32Array(IRIDESCENT_FLOATS);
+  /** The refusals of an overlay already said, each once. */
+  private readonly warnedIridescent = new Set<string>();
   /** The detail refusals already said, each once. See `detailOfMaterial`. */
   private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersTriplanar = false;
@@ -3607,6 +3631,16 @@ export class WebGPURenderer implements RendererApi {
       f[emissive] = asked?.[0] ?? 1;
       f[emissive + 1] = asked?.[1] ?? 1;
       f[emissive + 2] = asked?.[2] ?? 1;
+      /* And its glow's scroll and mask, the first time a material asks: emissiveFlow.ts. */
+      if (packEmissiveFlow(material, this.flowFloats)) this.enableLit('EMISSIVE_FLOW');
+      f.set(this.flowFloats, this.materialField('uEmissiveFlow'));
+      /* And its iridescent overlay, the first time a material lays one: iridescentOverlay.ts. */
+      const iridescent = this.iridescentOf(material);
+      packIridescentOverlay(iridescent, material ?? {}, this.iridescentFloats);
+      f.set(this.iridescentFloats, this.materialField('uIridescence'));
+      /* And whether the frame's decals mark it. See `SurfaceMaterial.receivesDecals`. */
+      f[this.materialField('uDecalReceiver')] = material?.receivesDecals === false ? 1 : 0;
+      if (iridescent !== null) this.enableLit('IRIDESCENT_OVERLAY');
       /* The model's numbers and whether its map is bound. See `packModel`. */
       packModel(
         material?.model ?? null,
@@ -6426,6 +6460,21 @@ export class WebGPURenderer implements RendererApi {
   }
 
   /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+  /** A material's iridescent overlay, or null where it is malformed, said once. */
+  private iridescentOf(
+    material: SurfaceMaterial<GpuSurfaceTexture> | null,
+  ): IridescentOverlay | null {
+    const overlay = material?.iridescentOverlay ?? null;
+    if (overlay === null) return null;
+    const refusal = iridescentRefusal(overlay);
+    if (refusal === null) return overlay;
+    if (!this.warnedIridescent.has(refusal)) {
+      this.warnedIridescent.add(refusal);
+      console.warn(`Renderer: an iridescent overlay is refused: ${refusal}. Drawn without it.`);
+    }
+    return null;
+  }
+
   private enableLit(feature: LitSwitch): void {
     if (this.pipelines.litSwitches[feature]) return;
     void this.pipelines.enable(feature);
@@ -7759,6 +7808,9 @@ export class WebGPURenderer implements RendererApi {
       { binding: TAA_TEXTURES.uFlicker },
       { binding: TAA_TEXTURES.uFlickerMotion },
       { binding: TAA_TEXTURES.uDepth, filterable: false },
+      /* WebGL2's movers' motion (`motionTarget.ts`); here the depth stands in and is never read,
+         `uMotionOn` being 0, since this backend follows movers through its reconstruction. */
+      { binding: TAA_TEXTURES.uMotion, filterable: false },
     ]);
     this.taaUniforms = device.createBuffer({
       label: 'post.taaUniforms',
@@ -8932,6 +8984,19 @@ export class WebGPURenderer implements RendererApi {
    * a destroyed buffer in a submit loses the whole command buffer. Nothing else reads them, so once
    * the rewrites are submitted, which only moves them earlier, the buffers can go at once.
    */
+  /**
+   * Rewrite part of a skin in place. **A pose already recorded is submitted first**, since a queue
+   * write reaches every dispatch submitted after it and would otherwise reach a pose the caller made
+   * before the rewrite; then the pose after it alone reads the rewrite, as on WebGL2. A rewrite with
+   * nothing pending submits nothing.
+   */
+  updatePointSkin(skin: GpuPointSkin, first: number, data: PointSkinData): void {
+    validatePointSkinRange(data, first, skin.mesh.vertexCount);
+    if (this.surface.lost) return;
+    if (this.pendingRewrites !== null) this.submit([]);
+    skin.rewrite(this.surface.device, first, data);
+  }
+
   disposePointSkin(skin: GpuPointSkin): void {
     if (this.pendingRewrites !== null && !this.surface.lost) this.submit([]);
     skin.dispose();
@@ -9094,6 +9159,13 @@ export class WebGPURenderer implements RendererApi {
     f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
     /* Nor detail. */
     f.fill(0, at('uDetail'), at('uDetail') + DETAIL_FLOATS);
+    /* Nor a glow that moves or is masked. */
+    f.fill(0, at('uEmissiveFlow'), at('uEmissiveFlow') + EMISSIVE_FLOW_FLOATS);
+    /* Nor an iridescent overlay. */
+    f.fill(0, at('uIridescence'), at('uIridescence') + IRIDESCENT_FLOATS);
+    /* The frame's decals as last laid, held across passes, and every surface receiving them. */
+    f.set(this.baseDecalFloats, at('uBaseDecals'));
+    f[at('uDecalReceiver')] = 0;
     f[at('uCutout')] = 0;
     f[at('uCutout') + 1] = 0;
     this.cutoutResolveStaged = 'hard';
@@ -13840,6 +13912,8 @@ export class WebGPURenderer implements RendererApi {
       f[depthRow + 3] = 1;
     }
     f[at('uAntiFlicker')] = 1;
+    /* The camera's motion alone: this backend follows a mover through its reconstruction. */
+    f[at('uMotionOn')] = 0;
     device.queue.writeBuffer(this.taaUniforms, 0, this.taaStaging);
 
     const pass = encoder.beginRenderPass({
@@ -14330,7 +14404,7 @@ export class WebGPURenderer implements RendererApi {
     f.set(this.frameEye, at('uCameraPos'));
     f.set(env?.directionalDir ?? [0, 1, 0], at('uSunDir'));
     f.set(env?.directionalColor ?? [0, 0, 0], at('uSunColor'));
-    f.set(env?.ambient ?? [0, 0, 0], at('uAmbient'));
+    f.set(mediumSkyFill(options, env?.ambient ?? MEDIUM_NO_AMBIENT), at('uAmbient'));
     f[at('uDensity')] = options.density;
     const height = at('uHeight');
     f[height] = options.heightFalloff;
@@ -17647,6 +17721,14 @@ export class WebGPURenderer implements RendererApi {
   /** The profiles as packed and the cookie images, kept so either can rebuild the atlas. */
   private iesAtlas = packIesAtlas([]);
   private cookieImages: readonly TexImageSource[] = [];
+  /** The images the frame's base decals lay, in the atlas's band of them. See `setBaseDecalImages`. */
+  private decalImages: readonly TexImageSource[] = [];
+  /** The decals as last laid, packed again whenever the cookies move their band. */
+  private baseDecalList: readonly BaseDecal[] = [];
+  /** `uBaseDecals`, held until the next `setBaseDecals`, across passes. */
+  private readonly baseDecalFloats = new Float32Array(BASE_DECAL_FLOATS);
+  /** The refusals of a decal or its image already said, each once. */
+  private readonly warnedBaseDecals = new Set<string>();
   /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
   private lightField: DriftLightVolumes | null = null;
   private driftIndex: GPUTexture | null = null;
@@ -18198,6 +18280,78 @@ export class WebGPURenderer implements RendererApi {
     this.cookieImages = images.slice();
     this.forgetFixtureAtlas();
     this.rebuildFlatBindGroup();
+    /* The decals' band starts below the cookies, so their rows move with them. */
+    if (this.baseDecalList.length > 0) this.setBaseDecals(this.baseDecalList);
+  }
+
+  /**
+   * The images the frame's base decals lay, each a `BASE_DECAL_TILE` square. The same count again
+   * copies the squares into the atlas and nothing else; a different count builds it again. See
+   * `renderer.ts` and `baseDecals.ts`. **Once a frame, before the draws they mark**: a copy reaches
+   * every draw of the frame it is made in, as any queue write does.
+   */
+  setBaseDecalImages(images: readonly TexImageSource[]): void {
+    if (this.surface.lost) return;
+    if (images.length === this.decalImages.length && this.fixtureTexture !== null) {
+      this.decalImages = images;
+      this.copyDecalImages(this.fixtureTexture);
+      return;
+    }
+    this.decalImages = images.slice();
+    this.forgetFixtureAtlas();
+    this.rebuildFlatBindGroup();
+    this.setBaseDecals(this.baseDecalList);
+  }
+
+  /** The decal images into their squares of the atlas. */
+  private copyDecalImages(texture: GPUTexture): void {
+    const top = decalBandTop(this.cookieImages.length);
+    for (let tile = 0; tile < this.decalImages.length; tile++) {
+      const source = this.decalImages[tile];
+      if (source === undefined || !this.decalImageFits(source)) continue;
+      this.surface.device.queue.copyExternalImageToTexture(
+        { source: source as GPUCopyExternalImageSource },
+        { texture, origin: { x: tile * BASE_DECAL_TILE, y: top } },
+        { width: BASE_DECAL_TILE, height: BASE_DECAL_TILE },
+      );
+    }
+  }
+
+  /** Whether an image is a decal's square, said once where it is not. */
+  private decalImageFits(image: TexImageSource): boolean {
+    const { width, height } = sourceSize(image);
+    if (width === BASE_DECAL_TILE && height === BASE_DECAL_TILE) return true;
+    const refusal =
+      `a base decal image of ${width} by ${height}; it is a square of ${BASE_DECAL_TILE} ` +
+      'texels, and is left clear';
+    if (!this.warnedBaseDecals.has(refusal)) {
+      this.warnedBaseDecals.add(refusal);
+      console.warn(`WebGPU: ${refusal}.`);
+    }
+    return false;
+  }
+
+  /**
+   * The decals laid into the base colours of the draws after it, until the next call, across
+   * passes. In the material block, as the overlay is, and written again where each pass starts it.
+   * See `renderer.ts` and `baseDecals.ts`.
+   */
+  setBaseDecals(decals: readonly BaseDecal[]): void {
+    if (this.surface.lost) return;
+    this.baseDecalList = decals;
+    const refusal = packBaseDecals(
+      decals,
+      this.decalImages.length,
+      decalBandTop(this.cookieImages.length),
+      this.baseDecalFloats,
+    );
+    if (refusal !== null && !this.warnedBaseDecals.has(refusal)) {
+      this.warnedBaseDecals.add(refusal);
+      console.warn(`WebGPU: ${refusal}.`);
+    }
+    if ((this.baseDecalFloats[0] as number) > 0) this.enableLit('BASE_DECALS');
+    this.perFrameFloats.set(this.baseDecalFloats, this.materialField('uBaseDecals'));
+    this.materials.dirty();
   }
 
   /** Let the atlas go, to be built again from what is in hand the next time it is bound. */
@@ -18218,7 +18372,11 @@ export class WebGPURenderer implements RendererApi {
   private fixtureAtlasView(): GPUTextureView {
     if (this.fixtureView !== null) return this.fixtureView;
     const { device } = this.surface;
-    const layout = fixtureAtlasLayout(this.iesAtlas.height, this.cookieImages.length);
+    const layout = fixtureAtlasLayout(
+      this.iesAtlas.height,
+      this.cookieImages.length,
+      this.decalImages.length,
+    );
     const texture = device.createTexture({
       label: 'fixture.atlas',
       size: [layout.width, layout.height],
@@ -18241,6 +18399,7 @@ export class WebGPURenderer implements RendererApi {
         { width: COOKIE_TILE, height: COOKIE_TILE },
       );
     }
+    this.copyDecalImages(texture);
     this.fixtureTexture = texture;
     this.fixtureView = texture.createView();
     this.iesRows = this.iesAtlas.height;
@@ -19039,6 +19198,7 @@ export class WebGPURenderer implements RendererApi {
           ...entry(TAA_TEXTURES.uFlicker, record),
           ...entry(TAA_TEXTURES.uFlickerMotion, motion),
           ...entry(TAA_TEXTURES.uDepth, this.resolvedDepthView, true),
+          ...entry(TAA_TEXTURES.uMotion, this.resolvedDepthView, true),
         ],
       });
     }

package/src/render/baseDecals.ts

@@ -0,0 +1,93 @@
+/**
+ * Decals laid into the base colour of what they land on, before it is lit: `setBaseDecals` and
+ * `setBaseDecalImages`, packed into `uBaseDecals` for the lit stage's `BASE_DECALS` switch.
+ *
+ * **What they are for, and why `DecalProjector` is not it.** A projected decal multiplies the
+ * finished pixel, so where the surface under it glows, a lettered floor or a lit panel, the mark
+ * dims the glow too. A shadow a body throws on a lit floor, a footprint, a stain is a change in what
+ * the surface *is*: it darkens the colour light falls on and leaves what the surface emits, how
+ * rough it is and its normal as they are. So each of these is a box, as a `DecalBox` is, an image
+ * read across its face, and the base colour moved toward the image's colour by its alpha.
+ *
+ * **The images ride in the fixture atlas**, a band of `BASE_DECAL_TILE` squares between the cookies
+ * and the photometric profiles (`fixtureAtlas.ts`), because the lit stage has no texture binding
+ * left (`textureUnitBudget.test.ts`). An image is that square, read as a picture: its colour is
+ * decoded from sRGB and its alpha is as it is. Rewriting them once a frame is the use they are for,
+ * and costs an upload of the squares; changing how many there are builds the atlas again.
+ *
+ * **What it gives up**: eight a frame, the uniforms they take being the limit (thirty-four vectors,
+ * so WebGL2 refuses them, in words, on a part whose lit stage has no room); the GPU-driven pipeline
+ * does not draw them; and a surface opts out by its material (`receivesDecals: false`), not by a
+ * mask of what each decal may mark.
+ */
+import { worldToDecalMatrix, type DecalBox } from './decalProjector.ts';
+
+/** Decals a frame. */
+export const MAX_BASE_DECALS = 8;
+/** Texels across an image's square in the atlas. */
+export const BASE_DECAL_TILE = 128;
+/** Floats in `uBaseDecals`: a header, then four vectors a decal. */
+export const BASE_DECAL_FLOATS = (1 + MAX_BASE_DECALS * 4) * 4;
+
+/** One decal: a box, which image it lays, and how much. */
+export interface BaseDecal extends DecalBox {
+  /** Which of `setBaseDecalImages`' images it lays, from 0. */
+  readonly image: number;
+  /** How much of the image's alpha lands, 0 to 1. Default 1. */
+  readonly opacity?: number;
+  /**
+   * How far from facing back along `forward` a surface may be turned and still be marked, as a
+   * cosine of the geometric normal against it. Default 0.2, so a floor is marked and the side of a
+   * step it stands on is not smeared. -1 marks every surface in the box.
+   */
+  readonly facingCos?: number;
+}
+
+const MATRIX = new Float32Array(16);
+
+/**
+ * Pack `decals` against `images` laid in the atlas band starting at row `bandTop` into `out`, and
+ * return why one was left out, or null where none was: past the eighth, an image there is none of,
+ * or a box with no size or no orientation. The rest are packed in order.
+ */
+export function packBaseDecals(
+  decals: readonly BaseDecal[],
+  images: number,
+  bandTop: number,
+  out: Float32Array,
+): string | null {
+  out.fill(0);
+  let refusal: string | null =
+    decals.length > MAX_BASE_DECALS
+      ? `${decals.length} base decals; a frame lays the first ${MAX_BASE_DECALS}`
+      : null;
+  let kept = 0;
+  for (let i = 0; i < decals.length && kept < MAX_BASE_DECALS; i++) {
+    const decal = decals[i] as BaseDecal;
+    if (!(Number.isInteger(decal.image) && decal.image >= 0 && decal.image < images)) {
+      refusal ??= `a base decal lays image ${decal.image} and there are ${images}`;
+      continue;
+    }
+    try {
+      worldToDecalMatrix(MATRIX, decal);
+    } catch (cause) {
+      refusal ??= cause instanceof Error ? cause.message : String(cause);
+      continue;
+    }
+    const at = 4 + kept * 16;
+    for (let row = 0; row < 3; row++) {
+      out[at + row * 4] = MATRIX[row] as number;
+      out[at + row * 4 + 1] = MATRIX[4 + row] as number;
+      out[at + row * 4 + 2] = MATRIX[8 + row] as number;
+      out[at + row * 4 + 3] = MATRIX[12 + row] as number;
+    }
+    out[at + 12] = decal.image;
+    out[at + 13] = Math.min(1, Math.max(0, decal.opacity ?? 1));
+    out[at + 14] = decal.facingCos ?? 0.2;
+    kept += 1;
+  }
+  out[0] = kept;
+  out[1] = bandTop;
+  out[2] = BASE_DECAL_TILE;
+  return refusal;
+}

package/src/render/emissiveFlow.ts

@@ -0,0 +1,66 @@
+/**
+ * A material's glow moved and masked: `SurfaceMaterial.emissiveScroll` and `emissiveMaskLayer`,
+ * packed into `uEmissiveFlow` for the lit stage's `EMISSIVE_FLOW` switch. Both backends pack it
+ * here and only upload it, so they cannot disagree about which layer a mask is.
+ *
+ * **What it is for**: lava in a rock's cracks, a sign's lettering, a glow repeated with a surface's
+ * first layer and drifting across it, held to where the surface glows by a map that spans the mesh
+ * once. Folded into each vertex's emission instead, the glow spreads across whole faces of a coarse
+ * mesh where it should follow the cracks.
+ *
+ * **The mask is the alpha of a layer of the emissive map's own array**, read at the mesh's first
+ * coordinates as they are, before the material's repeat, offset, layers or projection: alpha is
+ * never decoded as sRGB, so it is the number it was written as in either colour space, and no
+ * texture binding is spent, since the lit stage has none left (`textureUnitBudget.test.ts`). What
+ * that gives up is a mask of its own size: a layer of an array is the array's size.
+ *
+ * **The scroll moves the emissive map alone**, by `Environment.surfaceTime`, in its own repeats a
+ * second, wrapped to one so a long-running clock keeps its precision; the albedo and every other map
+ * stay where they are.
+ */
+
+/**
+ * Floats in `uEmissiveFlow`: the scroll on u and v, the mask's layer plus one (0, none) and one
+ * unused; then the scale and offset that take the material's coordinates back to the mesh's own.
+ */
+export const EMISSIVE_FLOW_FLOATS = 8;
+
+/** What a material says about its glow's flow, and the repeat and offset its coordinates carry. */
+export interface EmissiveFlowMaterial {
+  readonly emissiveScroll?: readonly [number, number] | null;
+  readonly emissiveMaskLayer?: number | null;
+  readonly uScale?: number;
+  readonly vScale?: number;
+  readonly uOffset?: number;
+  readonly vOffset?: number;
+}
+
+/**
+ * Pack a material's flow into `out` and say whether it asks for one: a scroll that moves, or a mask
+ * that is a whole layer. A scroll that is not a number is still; a layer that is not a whole number
+ * at or above zero is no mask.
+ */
+export function packEmissiveFlow(
+  material: EmissiveFlowMaterial | null,
+  out: Float32Array,
+): boolean {
+  const scroll = material?.emissiveScroll ?? null;
+  const u = scroll !== null && Number.isFinite(scroll[0]) ? scroll[0] : 0;
+  const v = scroll !== null && Number.isFinite(scroll[1]) ? scroll[1] : 0;
+  const layer = material?.emissiveMaskLayer ?? null;
+  const masked = layer !== null && Number.isInteger(layer) && layer >= 0;
+  out[0] = u;
+  out[1] = v;
+  /* Plus one, so an unwritten zero is no mask rather than a mask of layer 0. */
+  out[2] = masked ? layer + 1 : 0;
+  out[3] = 0;
+  /* The vertex stage laid `uv · scale + offset`; this undoes it. A scale of zero has no inverse,
+     and every texel of such a surface is the one coordinate, so the mesh's own is taken as 0. */
+  const uScale = material?.uScale ?? 1;
+  const vScale = material?.vScale ?? 1;
+  out[4] = uScale === 0 ? 0 : 1 / uScale;
+  out[5] = vScale === 0 ? 0 : 1 / vScale;
+  out[6] = uScale === 0 ? 0 : -(material?.uOffset ?? 0) / uScale;
+  out[7] = vScale === 0 ? 0 : -(material?.vOffset ?? 0) / vScale;
+  return u !== 0 || v !== 0 || masked;
+}

package/src/render/fixtureAtlas.ts

@@ -1,6 +1,9 @@
 /**
  * What a light fixture throws, in one texture: its spot cookies in the top band, its photometric
- * profiles in the rows below.
+ * profiles in the rows below. And between the two, since the lit stage had no binding left for them
+ * either, the images of the decals laid into base colours (`baseDecals.ts`), a band of squares a
+ * frame may rewrite; each band is found from its own end or its own row, so the others' lookups are
+ * as they were.
  *
  * **One binding for two tables, because the lit stage had one sampler left.** The cookie atlas and
  * the photometric atlas were two small float textures read with `textureLod`, and the widest lit
@@ -19,24 +22,40 @@
  */
 import { IES_ATLAS_WIDTH } from './iesProfile.ts';
 import { COOKIE_TILE } from './lightBudget.ts';
+import { BASE_DECAL_TILE } from './baseDecals.ts';
 
 export interface FixtureAtlasLayout {
   readonly width: number;
   readonly height: number;
   /** Rows of cookie tiles at the top: `COOKIE_TILE`, or 0 with none loaded. */
   readonly cookieRows: number;
-  /** The first row of the profiles, below the cookies. */
+  /** The first row of the decals' images, below the cookies, and how many rows they take. */
+  readonly decalTop: number;
+  readonly decalRows: number;
+  /** The first row of the profiles, below the cookies and the decals. */
   readonly iesTop: number;
 }
 
-/** The atlas for `iesRows` rows of profile and `cookieTiles` cookies. */
-export function fixtureAtlasLayout(iesRows: number, cookieTiles: number): FixtureAtlasLayout {
+/** The row the decals' band starts at: below the cookies, which are there or are not. */
+export function decalBandTop(cookieTiles: number): number {
+  return cookieTiles > 0 ? COOKIE_TILE : 0;
+}
+
+/** The atlas for `iesRows` rows of profile, `cookieTiles` cookies and `decalTiles` decal images. */
+export function fixtureAtlasLayout(
+  iesRows: number,
+  cookieTiles: number,
+  decalTiles = 0,
+): FixtureAtlasLayout {
   const cookieRows = cookieTiles > 0 ? COOKIE_TILE : 0;
+  const decalRows = decalTiles > 0 ? BASE_DECAL_TILE : 0;
   return {
-    width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles),
-    height: cookieRows + iesRows,
+    width: Math.max(IES_ATLAS_WIDTH, COOKIE_TILE * cookieTiles, BASE_DECAL_TILE * decalTiles),
+    height: cookieRows + decalRows + iesRows,
     cookieRows,
-    iesTop: cookieRows,
+    decalTop: cookieRows,
+    decalRows,
+    iesTop: cookieRows + decalRows,
   };
 }