@driftengine/core 4.5.0 → 4.6.1

package/src/render/shaders/recon/resolve.wgsl.ts

@@ -34,12 +34,16 @@
  * fn reconMotion(x: i32, y: i32) -> vec4<f32>         // uv, previous view depth, flag
  * fn reconHistory(x: i32, y: i32) -> vec4<f32>        // output size, colour and gathered weight
  * fn reconHistoryBilinear(p: vec2<f32>) -> vec4<f32>
+ * fn reconFlicker(x: i32, y: i32) -> vec4<f32>        // output size, last frame's flicker record
+ * fn reconSwing(x: i32, y: i32) -> f32                // output size, last frame's held depth swing
  * ```
  *
  * and the uniform `recon: ReconParams`, whose struct this module declares.
  */
 import { wgslSceneDepthToNdc } from '../../depthConvention.ts';
 import { PLANAR_FROM, PLANAR_TO } from '../../recon/disocclusion.ts';
+import { DEPTH_SWING_WIDTH } from '../../recon/resolve.ts';
+import { FLICKER_BLEND, FLICKER_REPEAT, STILL_FROM, STILL_TO } from '../../temporalAa.ts';
 
 /**
  * The parameters one resolve reads, as `ResolveFrame` minus its images.
@@ -66,11 +70,16 @@ struct ReconParams {
   motionScale: f32,
   normalFloor: f32,
   normalCeiling: f32,
+  periodStart: u32,
+  antiFlicker: u32,
+  flickerMemory: f32,
+  flickerWidth: f32,
+  reprojection: mat4x4<f32>,
 }
 `;
 
 /** Floats in `ReconParams`, which is what a caller sizes its uniform buffer by. */
-export const RECON_PARAM_FLOATS = 72;
+export const RECON_PARAM_FLOATS = 92;
 
 /** `SAMPLE_SPREAD` and `CONFIDENT_WEIGHT`, which the reference exports and this must not restate. */
 export const RECON_SAMPLE_SPREAD = 0.47;
@@ -91,8 +100,8 @@ export const RECON_WORKGROUP = 8;
 export const RECON_HISTORY_FORMAT: GPUTextureFormat = 'rgba16float';
 
 /**
- * The arithmetic, as text. Defines `reconResolvePixel(ox, oy) -> vec4<f32>` — the next history's
- * colour and the weight it has gathered — and `reconSharpenAt(ox, oy) -> vec3<f32>`, the picture
+ * The arithmetic, as text. Defines `reconResolvePixel(ox, oy) -> ReconResolved` — the next
+ * history's colour and the weight it has gathered, and the pixel's next flicker record — and `reconSharpenAt(ox, oy) -> vec3<f32>`, the picture
  * shown, which reads the history the first has already written.
  */
 export const RECON_RESOLVE_CORE_WGSL = /* wgsl */ `
@@ -100,6 +109,11 @@ const RECON_SAMPLE_SPREAD: f32 = ${RECON_SAMPLE_SPREAD};
 const RECON_CONFIDENT_WEIGHT: f32 = ${RECON_CONFIDENT_WEIGHT}.0;
 const RECON_PLANAR_FROM: f32 = ${PLANAR_FROM};
 const RECON_PLANAR_TO: f32 = ${PLANAR_TO};
+const RECON_FLICKER_BLEND: f32 = ${FLICKER_BLEND};
+const RECON_FLICKER_REPEAT: f32 = ${FLICKER_REPEAT};
+const RECON_STILL_FROM: f32 = ${STILL_FROM};
+const RECON_STILL_TO: f32 = ${STILL_TO};
+const RECON_DEPTH_SWING_WIDTH: f32 = ${DEPTH_SWING_WIDTH}.0;
 
 fn reconClampTexel(value: i32, size: i32) -> i32 {
   return clamp(value, 0, size - 1);
@@ -467,6 +481,10 @@ fn reconSurfaceAt(previous: bool, x: i32, y: i32, centre: f32) -> ReconSurface {
 struct ReconHistory {
   weight: f32,
   colour: vec4<f32>,
+  /* How far the surface moved, in output pixels; read only where the weight is not zero. */
+  moved: f32,
+  /* How far, relative, last frame's depth missed the one expected there; -1 where none was held. */
+  missed: f32,
 }
 
 /*
@@ -474,10 +492,12 @@ struct ReconHistory {
  * behind last frame's eye or off its picture, and otherwise what it gathered, scaled by whether it
  * is the same surface.
  */
-fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
+fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32, swing: f32) -> ReconHistory {
   var out: ReconHistory;
   out.weight = 0.0;
   out.colour = vec4<f32>(0.0);
+  out.moved = 0.0;
+  out.missed = -1.0;
   if (recon.hasHistory == 0u) { return out; }
   let rw = f32(recon.renderSize.x);
   let rh = f32(recon.renderSize.y);
@@ -490,20 +510,24 @@ fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
     mv = motion.y;
     expected = motion.z;
   } else {
-    let here = reconWorldAt(false, dx, dy);
-    if (!(here.depth > 0.0)) { return out; }
-    let clip = recon.previousViewProj * vec4<f32>(here.position, 1.0);
+    /* Through the one reprojection matrix the renderer multiplied: see resolve.ts. */
+    let du = (f32(dx) + 0.5 - recon.jitter.x) / rw;
+    let dv = (f32(dy) + 0.5 - recon.jitter.y) / rh;
+    let ndc = vec4<f32>(du * 2.0 - 1.0, dv * 2.0 - 1.0, reconDepth(dx, dy), 1.0);
+    let m = recon.inverseViewProj;
+    let hw = m[0][3] * ndc.x + m[1][3] * ndc.y + m[2][3] * ndc.z + m[3][3];
+    if (!(hw > 1e-12)) { return out; }
+    let clip = recon.reprojection * ndc;
     /*
      * A surface behind last frame's eye has a w that is not positive: the disocclusion trusts no
      * such depth, so it needs no refusal of its own here.
      */
-    expected = clip.w;
-    let du = (f32(dx) + 0.5 - recon.jitter.x) / rw;
-    let dv = (f32(dy) + 0.5 - recon.jitter.y) / rh;
-    mu = (clip.x / expected) * 0.5 + 0.5 - du;
-    mv = (clip.y / expected) * 0.5 + 0.5 - dv;
+    expected = clip.w / hw;
+    mu = (clip.x / clip.w) * 0.5 + 0.5 - du;
+    mv = (clip.y / clip.w) * 0.5 + 0.5 - dv;
   }
 
+  out.moved = length(vec2<f32>(mu * f32(recon.outputSize.x), mv * f32(recon.outputSize.y)));
   let pu = u + mu;
   let pv = v + mv;
   if (!(pu >= 0.0 && pu <= 1.0 && pv >= 0.0 && pv <= 1.0)) { return out; }
@@ -550,13 +574,41 @@ fn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {
       normalDot = 1.0 - planar * (1.0 - dot(hereNormal.normal, thereNormal.normal));
     }
   }
-  let trust = reconDisocclusion(expected, held, length(vec2<f32>(mu, mv)), normalDot, here.slope);
+  if (held > 0.0 && expected > 0.0) { out.missed = abs(held - expected) / expected; }
+  /* A still pixel's own held depth swing: see resolve.ts. */
+  var swung = 0.0;
+  if (swing > 0.0) {
+    swung = RECON_DEPTH_SWING_WIDTH * swing *
+      (1.0 - reconSmoothstep(RECON_STILL_FROM, RECON_STILL_TO, out.moved));
+  }
+  let trust = reconDisocclusion(
+    expected,
+    held,
+    length(vec2<f32>(mu, mv)),
+    normalDot,
+    here.slope + swung,
+  );
   out.weight = out.colour.w * trust;
   return out;
 }
 
-/* One output pixel: the history's next colour, before sharpening, and the weight it has gathered. */
-fn reconResolvePixel(ox: i32, oy: i32) -> vec4<f32> {
+/* temporalAa.ts's repeats: whether two periods' means are the same, one to zero. */
+fn reconRepeats(mean: f32, previous: f32) -> f32 {
+  let apart = abs(mean - previous) / max(max(mean, previous), 1.0 / 255.0);
+  return 1.0 - reconSmoothstep(RECON_FLICKER_REPEAT, 2.0 * RECON_FLICKER_REPEAT, apart);
+}
+
+struct ReconResolved {
+  /* The history's next colour, before sharpening, and the weight it has gathered. */
+  colour: vec4<f32>,
+  /* The pixel's next flicker record: spread, this period's sum, last period's mean, repeats. */
+  record: vec4<f32>,
+  /* And its next held depth swing. */
+  swing: f32,
+}
+
+/* One output pixel: the history's next colour and weight, and its next flicker record. */
+fn reconResolvePixel(ox: i32, oy: i32) -> ReconResolved {
   let rw = i32(recon.renderSize.x);
   let rh = i32(recon.renderSize.y);
   let ow = i32(recon.outputSize.x);
@@ -604,18 +656,68 @@ fn reconResolvePixel(ox: i32, oy: i32) -> vec4<f32> {
   accum = accum / gathered;
 
   /* The history, and the weight it still deserves; a tenth of each frame is always new. */
-  let cap = (1.0 - recon.alpha) / recon.alpha;
-  let history = reconHistoryWeight(u, v, dx, dy);
+  var swing = 0.0;
+  if (recon.antiFlicker != 0u) { swing = reconSwing(ox, oy); }
+  let history = reconHistoryWeight(u, v, dx, dy, swing);
+  var cap = (1.0 - recon.alpha) / recon.alpha;
+  var low = box.low;
+  var high = box.high;
+  var out: ReconResolved;
+  out.record = vec4<f32>(0.0);
+  out.swing = 0.0;
+  /* The anti-flicker, operation for operation resolve.ts's: see temporalAa.ts. */
+  if (recon.antiFlicker != 0u) {
+    let seen = dot(accum, vec3<f32>(0.2126, 0.7152, 0.0722));
+    let memory = recon.flickerMemory;
+    let width = recon.flickerWidth;
+    var held = vec4<f32>(0.0, seen * memory, seen, 0.0);
+    if (history.weight > 0.0) { held = reconFlicker(ox, oy); }
+    var still = 0.0;
+    if (history.weight > 0.0) {
+      still = 1.0 - reconSmoothstep(RECON_STILL_FROM, RECON_STILL_TO, history.moved);
+    }
+    let apart = abs(seen - held.z);
+    let within = apart <= width * held.x + 1.0 / 255.0;
+    let proven = held.w > 0.75 && within;
+    var widen = 0.0;
+    let base = 1.0 - recon.alpha;
+    var keep = base;
+    if (proven) {
+      widen = width * held.x * still;
+      keep = base + (RECON_FLICKER_BLEND - base) * still;
+    }
+    low = low - vec3<f32>(widen);
+    high = high + vec3<f32>(widen);
+    cap = keep / (1.0 - keep);
+    var sum = held.y;
+    var mean = held.z;
+    var repeated = 0.0;
+    if (within) { repeated = held.w; }
+    if (recon.periodStart != 0u) {
+      if (reconRepeats(sum, mean) > 0.5) { repeated = min(1.0, repeated + 0.5); } else { repeated = 0.0; }
+      mean = sum;
+      sum = 0.0;
+    }
+    out.record = vec4<f32>(
+      held.x + (apart - held.x) * memory,
+      sum + seen * memory,
+      mean,
+      repeated * still,
+    );
+    /* The peak carried on, halving over a period, whatever the test said. */
+    if (history.missed >= 0.0) { out.swing = max(history.missed, swing * pow(0.5, memory)); }
+  }
   let kept = min(cap, history.weight);
 
   let total = kept + gathered;
   var mixed = accum;
   if (kept > 0.0) {
-    let clipped = reconClipToBox(reconToYCoCg(history.colour.xyz), box.low, box.high);
+    let clipped = reconClipToBox(reconToYCoCg(history.colour.xyz), low, high);
     mixed = reconAccumulate(accum, reconFromYCoCg(clipped), 1.0, gathered / total);
   }
   let known = min(1.0, total / RECON_CONFIDENT_WEIGHT);
-  return vec4<f32>(sample * (1.0 - known) + mixed * known, total);
+  out.colour = vec4<f32>(sample * (1.0 - known) + mixed * known, total);
+  return out;
 }
 
 /*
@@ -655,8 +757,9 @@ fn reconSharpenAt(ox: i32, oy: i32) -> vec3<f32> {
  * doing its own bilinear so the comparison is arithmetic rather than a tolerance on the device's
  * sampler.
  *
- * Two entry points over one set of bindings. `resolveMain` writes four floats a pixel — the next
- * history — and `sharpenMain` reads that history back at binding 4 and writes three.
+ * Two entry points over one set of bindings. `resolveMain` writes nine floats a pixel — the next
+ * history, the next flicker record and the next depth swing — and `sharpenMain` reads that history back at binding 4
+ * and writes three.
  */
 export function reconResolveParityWgsl(): string {
   return /* wgsl */ `
@@ -668,6 +771,16 @@ export function reconResolveParityWgsl(): string {
 ${RECON_PARAMS_WGSL}
 @group(0) @binding(5) var<uniform> recon: ReconParams;
 @group(0) @binding(6) var<storage, read_write> output: array<f32>;
+@group(0) @binding(7) var flickerTexture: texture_2d<f32>;
+@group(0) @binding(8) var swingTexture: texture_2d<f32>;
+
+fn reconFlicker(x: i32, y: i32) -> vec4<f32> {
+  return textureLoad(flickerTexture, vec2<i32>(x, y), 0);
+}
+
+fn reconSwing(x: i32, y: i32) -> f32 {
+  return textureLoad(swingTexture, vec2<i32>(x, y), 0).x;
+}
 
 fn reconScene(x: i32, y: i32) -> vec3<f32> {
   return textureLoad(sceneTexture, vec2<i32>(x, y), 0).xyz;
@@ -725,11 +838,16 @@ ${RECON_RESOLVE_CORE_WGSL}
 fn resolveMain(@builtin(global_invocation_id) id: vec3<u32>) {
   if (id.x >= recon.outputSize.x || id.y >= recon.outputSize.y) { return; }
   let value = reconResolvePixel(i32(id.x), i32(id.y));
-  let at = (id.y * recon.outputSize.x + id.x) * 4u;
-  output[at] = value.x;
-  output[at + 1u] = value.y;
-  output[at + 2u] = value.z;
-  output[at + 3u] = value.w;
+  let at = (id.y * recon.outputSize.x + id.x) * 9u;
+  output[at] = value.colour.x;
+  output[at + 1u] = value.colour.y;
+  output[at + 2u] = value.colour.z;
+  output[at + 3u] = value.colour.w;
+  output[at + 4u] = value.record.x;
+  output[at + 5u] = value.record.y;
+  output[at + 6u] = value.record.z;
+  output[at + 7u] = value.record.w;
+  output[at + 8u] = value.swing;
 }
 
 @compute @workgroup_size(${RECON_WORKGROUP}, ${RECON_WORKGROUP})
@@ -780,6 +898,12 @@ ${RECON_PARAMS_WGSL}
 @group(0) @binding(6) var<uniform> recon: ReconParams;
 @group(0) @binding(7) var resolved: texture_storage_2d<rgba16float, write>;
 /* Not "target": it is a reserved keyword in WGSL, as "meta" was in the cluster cull. */
+/* Last frame's flicker records, and where this frame's go: a pair beside the histories. */
+@group(0) @binding(8) var flickerTexture: texture_2d<f32>;
+@group(0) @binding(9) var flickerOut: texture_storage_2d<rgba16float, write>;
+/* And each pixel's held depth swing, a pair of its own. */
+@group(0) @binding(10) var swingTexture: texture_2d<f32>;
+@group(0) @binding(11) var swingOut: texture_storage_2d<r32float, write>;
 
 /* Rows flip here: the reference's row 0 is the bottom one and a texture's is the top. */
 fn reconRenderRow(y: i32) -> i32 {
@@ -812,6 +936,14 @@ fn reconHistory(x: i32, y: i32) -> vec4<f32> {
   return textureLoad(historyTexture, vec2<i32>(x, reconOutputRow(y)), 0);
 }
 
+fn reconFlicker(x: i32, y: i32) -> vec4<f32> {
+  return textureLoad(flickerTexture, vec2<i32>(x, reconOutputRow(y)), 0);
+}
+
+fn reconSwing(x: i32, y: i32) -> f32 {
+  return textureLoad(swingTexture, vec2<i32>(x, reconOutputRow(y)), 0).x;
+}
+
 /* A texel coordinate becomes the uv of its centre, with the row taken from the other end. */
 fn reconSceneBilinear(p: vec2<f32>) -> vec3<f32> {
   let size = vec2<f32>(f32(recon.renderSize.x), f32(recon.renderSize.y));
@@ -831,7 +963,9 @@ fn resolveMain(@builtin(global_invocation_id) id: vec3<u32>) {
   if (id.x >= recon.outputSize.x || id.y >= recon.outputSize.y) { return; }
   let y = i32(recon.outputSize.y) - 1 - i32(id.y);
   let value = reconResolvePixel(i32(id.x), y);
-  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), value);
+  textureStore(resolved, vec2<i32>(i32(id.x), i32(id.y)), value.colour);
+  textureStore(flickerOut, vec2<i32>(i32(id.x), i32(id.y)), value.record);
+  textureStore(swingOut, vec2<i32>(i32(id.x), i32(id.y)), vec4<f32>(value.swing, 0.0, 0.0, 0.0));
 }
 
 @compute @workgroup_size(${RECON_WORKGROUP}, ${RECON_WORKGROUP})

package/src/render/shaders/rush.ts

@@ -104,6 +104,16 @@ uniform float uMotionMax;
  */
 uniform sampler2D uAo;
 uniform float uAoStrength;
+/**
+ * Where this frame's jitter put the picture the occlusion was measured from, in this pass's uv.
+ *
+ * The occlusion is measured from the frame's own depth, which a temporal resolve or a
+ * reconstruction jittered, and it is applied here to a picture those have already taken the jitter
+ * out of — so read at the pixel's own uv it moved by the jitter every frame, and every crevice
+ * shimmered by up to half a render texel. Read where the jitter put it, it holds still. Zero for an
+ * unjittered frame.
+ */
+uniform vec2 uAoOffset;
 
 /**
  * The bloom chain's top level, already thresholded, blurred and summed by its own pass.
@@ -341,7 +351,7 @@ void main() {
    * strength, so the parameter reads as "how much of this occlusion", and 0 is exactly the
    * frame that existed before the effect did.
    */
-  float ao = mix(1.0, textureLod(uAo, vUv, 0.0).r, uAoStrength);
+  float ao = mix(1.0, textureLod(uAo, vUv + uAoOffset, 0.0).r, uAoStrength);
 
   /*
    * Distance from the centre, corrected so the falloff is a circle on screen rather than

package/src/render/shaders/sdfText.ts

@@ -30,7 +30,8 @@ precision highp float;
 
 in vec2 vUv;
 
-uniform sampler2D uAtlas;
+/* An array of one: every surface texture is an array, and an atlas is read at layer 0. */
+uniform mediump sampler2DArray uAtlas;
 uniform vec3 uColor;
 uniform float uOpacity;
 /* Texels the field spans, from the atlas metrics. Scales the antialiasing band. */
@@ -52,7 +53,7 @@ float median(vec3 rgb) {
 }
 
 void main() {
-  vec3 sampled = textureLod(uAtlas, vUv, 0.0).rgb;
+  vec3 sampled = textureLod(uAtlas, vec3(vUv, 0.0), 0.0).rgb;
   float distance = median(sampled) - 0.5;
 
   /*

package/src/render/shaders/text.ts

@@ -27,7 +27,7 @@ uniform vec2 uViewport;
 /** Where the string's baseline-left sits, in pixels from the top left. */
 uniform vec2 uOrigin;
 uniform float uCellSize;
-/** Distance from the virtual camera; larger flattens the perspective. */
+/** How far each cell is seen from, head-on; larger flattens the perspective. */
 uniform float uDepth;
 
 /** 0 before a character has arrived, 1 once it has settled. */
@@ -105,14 +105,23 @@ void main() {
   vec2 cell = aCell * uCellSize;
   float bob = sin(uTime * 3.1 + aCharIndex * 0.7) * uBob;
 
-  // Pixels, y down from the top-left corner of the viewport.
-  vec2 screen = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);
-  vec3 view = vec3(screen + local3.xy, -uDepth + local3.z);
-
-  // A hand-built perspective divide. The near plane is the viewport itself, so
-  // a cell at depth uDepth is exactly its pixel size on screen.
-  float invDepth = uDepth / max(0.001, -view.z);
-  vec2 ndc = ((view.xy * invDepth) / uViewport) * 2.0 - 1.0;
+  // The cell's centre in pixels, y down from the top-left corner of the viewport.
+  vec2 centre = uOrigin + vec2(cell.x, -cell.y) + vec2(0.0, rise - bob);
+
+  // A hand-built perspective divide about the cell's own centre, so every cube
+  // is seen head-on: its front face at depth zero is exactly its cell, and at
+  // rest its sides are behind it wherever on the screen it is drawn.
+  //
+  // It divided about the viewport's top-left corner until 2026-09-30, which
+  // shifted a front face by its distance from that corner times z / uDepth and
+  // showed the side it uncovered. Near the corner that was nothing; across the
+  // screen it widened every stroke by up to a pixel either side and closed the
+  // one-cell gaps a 5x7 face reads by. What this gives up is the extruded look
+  // text far from the corner had at rest; what would make it wrong is a caller
+  // wanting that look, which is then one offset for every cell, not a position.
+  float invDepth = uDepth / max(0.001, uDepth - local3.z);
+  vec2 screen = centre + local3.xy * invDepth;
+  vec2 ndc = (screen / uViewport) * 2.0 - 1.0;
   // Depth from the cube's own extrusion, mapped into a narrow slice of the
   // range so a message sorts against itself without ever reaching the scene.
   float depth = clamp(-local3.z / max(1.0, uCellSize * 2.0), -1.0, 1.0) * 0.4;

package/src/render/surfaceEffects.ts

@@ -0,0 +1,132 @@
+/**
+ * What each layer of a surface array does beyond its picture: rooms behind its windows, windows that
+ * light by night, wear, animation, and whether rain wets it.
+ *
+ * **Per layer, because a city region is one mesh.** Its facades are told apart by the layer each
+ * vertex carries (`MeshData.layers`), so an effect's parameters cannot be a per-draw uniform — two facades of one
+ * draw would share them. They are a table beside the array, six texels a layer, read at the vertex's
+ * layer with `texelFetch`, and they bind whenever the array does.
+ *
+ * **Everything off is all zeros**, so a layer a scene names no effect for — and every layer of an
+ * array given no table — costs the shader one size query and nothing else.
+ *
+ * Layout, six RGBA texels a layer, half floats on the GPU (every whole number here is under 2,048,
+ * which a half holds exactly):
+ * - 0: window cells across and up, glass mask (1: glass where the albedo's alpha is 0), seed;
+ * - 1: room layer (0: none; the layer plus one), room depth (0 to 1 of a cell), share of rooms lit,
+ *      window glow;
+ * - 2: window colour, then 1 where rain leaves the surface dry;
+ * - 3: dust, grime, streaks, the metres over which wear fades out with distance (0: never);
+ * - 4: scroll along u and v in repeats a second, pulse rate in hertz, pulse depth;
+ * - 5: flicker, flipbook frames, flipbook frames a second, the metres past which emission fades
+ *      (0: never).
+ */
+
+/** Texels a layer takes in the table. */
+export const SURFACE_EFFECT_TEXELS = 6;
+
+export interface SurfaceLayerEffect {
+  /**
+   * Windows across and up one repeat of the layer, for everything that works window by window:
+   * rooms, lit windows. With `glass`, a window is a hole in the albedo — glass where its alpha is 0,
+   * wall where it is 1 — which is how a facade is drawn, and the other way round would lose the
+   * wall's colour, which does not survive an upload at alpha 0.
+   */
+  readonly windows?: {
+    readonly cells: readonly [number, number];
+    readonly glass?: boolean;
+    /** Varies which windows light and which rooms show, between facades wearing one layer. */
+    readonly seed?: number;
+    /** How bright a lit window glows, 0 for none. */
+    readonly glow?: number;
+    /**
+     * The light a window shows where there is no room behind it. **A vertex that names an emissive
+     * colour overrides it** — the window's colour, or a tint on the room where there is one — which
+     * is how buildings sharing a layer each keep their own light: a window layer's vertex emissive
+     * is otherwise unused, so the colour there, strength folded in, is free to say it.
+     */
+    readonly colour?: readonly [number, number, number];
+  };
+  /** A room seen in parallax behind each window, drawn from another layer of the same array. */
+  readonly interior?: {
+    readonly roomLayer: number;
+    /** How deep a room is, as a share of a window's width. 0.5 unless stated. */
+    readonly depth?: number;
+    /** The share of rooms lit, 0 to 1. 1 unless stated. */
+    readonly lit?: number;
+  };
+  /** Procedural wear, each 0 to 1, fading out past `fade` metres (never, unless stated). */
+  readonly wear?: {
+    readonly dust?: number;
+    readonly grime?: number;
+    readonly streaks?: number;
+    readonly fade?: number;
+  };
+  /** Motion on the caller's clock (`Environment.surfaceTime`), so a held clock holds it. */
+  readonly animation?: {
+    /** Repeats a second along u and v. */
+    readonly scroll?: readonly [number, number];
+    /** Emission rising and falling: hertz, and how far it falls, 0 to 1. */
+    readonly pulse?: readonly [number, number];
+    /** Emission stuttering, 0 to 1. */
+    readonly flicker?: number;
+    /** Successive layers as frames: how many from this one, and how fast. */
+    readonly flipbook?: readonly [number, number];
+    /** Metres past which emission fades out, 0 for never. */
+    readonly fade?: number;
+  };
+  /** Rain leaves it dry: a covered walkway, an interior floor. */
+  readonly dry?: boolean;
+}
+
+/**
+ * The table for `effects`, one entry a layer (`undefined` for a layer with none), as floats: six
+ * RGBA texels a layer, a row a layer.
+ */
+export function packSurfaceEffects(
+  effects: readonly (SurfaceLayerEffect | undefined)[],
+): Float32Array {
+  const out = new Float32Array(effects.length * SURFACE_EFFECT_TEXELS * 4);
+  effects.forEach((effect, layer) => {
+    if (effect === undefined) return;
+    const at = layer * SURFACE_EFFECT_TEXELS * 4;
+    const windows = effect.windows;
+    if (windows !== undefined) {
+      out[at] = windows.cells[0];
+      out[at + 1] = windows.cells[1];
+      out[at + 2] = windows.glass === true ? 1 : 0;
+      out[at + 3] = windows.seed ?? 0;
+      out[at + 7] = windows.glow ?? 0;
+      const colour = windows.colour ?? [1, 0.82, 0.55];
+      out[at + 8] = colour[0];
+      out[at + 9] = colour[1];
+      out[at + 10] = colour[2];
+    }
+    const interior = effect.interior;
+    if (interior !== undefined) {
+      out[at + 4] = interior.roomLayer + 1;
+      out[at + 5] = interior.depth ?? 0.5;
+      out[at + 6] = interior.lit ?? 1;
+    }
+    out[at + 11] = effect.dry === true ? 1 : 0;
+    const wear = effect.wear;
+    if (wear !== undefined) {
+      out[at + 12] = wear.dust ?? 0;
+      out[at + 13] = wear.grime ?? 0;
+      out[at + 14] = wear.streaks ?? 0;
+      out[at + 15] = wear.fade ?? 0;
+    }
+    const animation = effect.animation;
+    if (animation !== undefined) {
+      out[at + 16] = animation.scroll?.[0] ?? 0;
+      out[at + 17] = animation.scroll?.[1] ?? 0;
+      out[at + 18] = animation.pulse?.[0] ?? 0;
+      out[at + 19] = animation.pulse?.[1] ?? 0;
+      out[at + 20] = animation.flicker ?? 0;
+      out[at + 21] = animation.flipbook?.[0] ?? 0;
+      out[at + 22] = animation.flipbook?.[1] ?? 0;
+      out[at + 23] = animation.fade ?? 0;
+    }
+  });
+  return out;
+}

package/src/render/surfaceScene.ts

@@ -0,0 +1,16 @@
+/**
+ * The scene's surface clock and weather, decided once for both backends: the four numbers the lit
+ * stage reads as `uSurfaceScene`. Each backend only uploads them, so the two cannot disagree about
+ * what a wetness of 1.4 means — it means 1, as a share of lit windows past one means all of them.
+ */
+import type { Environment } from './backend/webgl2/renderer.ts';
+
+const unit = (value: number | undefined): number => Math.min(1, Math.max(0, value ?? 0));
+
+/** Fill `out`: seconds on the caller's clock, wetness, the lit share, the late share. */
+export function resolveSurfaceScene(env: Environment, out: Float32Array): void {
+  out[0] = env.surfaceTime ?? 0;
+  out[1] = unit(env.wetness);
+  out[2] = unit(env.litWindows);
+  out[3] = unit(env.lateWindows);
+}