@driftengine/core 4.4.2 → 4.6.0

package/src/render/shadowMap.ts

@@ -1,49 +1,106 @@
 /**
- * Single-cascade directional shadow map: one depth texture, one extra draw of
- * the static world per update.
+ * The sun's shadow: one depth array whose layers are the static world, its movers, and the static
+ * world's second occluder (the peel), drawn one at a time and sampled together.
  *
- * Filtering belongs to the receiving material shader, so the depth target can
- * stay a single-sample texture shared by every mesh pass.
+ * **One array rather than three maps since 4.5.0**, for the reason the lamps' twelve cubemaps
+ * became one: a texture unit. The lit pass binds all three through one `sampler2DArray`, which is
+ * what paid for the two tints glass casts with. The layers share one size and one format, so
+ * nothing about how each is drawn or read moved — only where it lives.
  *
- * Note this is a depth *render target*, not an art texture: AGENTS.md's
- * "zero textures" rule is about the art direction (no image assets in the
- * payload), and nothing here adds a byte to it.
+ * Filtering belongs to the receiving material shader, so the depth target can stay a
+ * single-sample texture shared by every mesh pass. This is a depth *render target*, not an art
+ * texture: AGENTS.md's "zero textures" rule is about the payload, and nothing here adds to it.
  */
 import { SHADOW_DEPTH_CLEAR } from './depthConvention.ts';
 import { DEFAULT_RENDER_QUALITY } from './renderQuality.ts';
 
-export class ShadowMap {
+/** Where each of the sun's maps lives in the array. The shaders read these same numbers. */
+export const SUN_STATIC_LAYER = 0;
+export const SUN_DYNAMIC_LAYER = 1;
+/** Present only when more than one static depth layer is asked for. */
+export const SUN_PEELED_LAYER = 2;
+/**
+ * Where the nearest pane's depth lives once glass has cast: after the three maps, at fixed places,
+ * because a shader cannot ask an array how many layers it has here — naga refuses the third
+ * component of an arrayed size query. A profile with no peel grows past an unused third layer to
+ * reach them, which is one map's memory in a profile that already declined one.
+ */
+export const SUN_GLASS_STATIC_LAYER = 3;
+export const SUN_GLASS_MOVING_LAYER = 4;
+
+/** The three passes a scene opens, by the names `beginShadowPass` takes. */
+export type SunShadowLayer = 'static' | 'static-peel' | 'dynamic';
+
+/** The array layer a pass draws into. */
+export function sunLayerIndex(layer: SunShadowLayer): number {
+  return layer === 'static'
+    ? SUN_STATIC_LAYER
+    : layer === 'dynamic'
+      ? SUN_DYNAMIC_LAYER
+      : SUN_PEELED_LAYER;
+}
+
+export class SunShadowArray {
   readonly size: number;
-  readonly texture: WebGLTexture;
+  /** Replaced once, when glass first casts: see `growForGlass`. */
+  private current: WebGLTexture;
+  private layerCount: number;
+  private glass = false;
 
   private readonly framebuffer: WebGLFramebuffer;
+  /**
+   * **The peel is drawn here and copied into its layer when the pass ends.** It reads the static
+   * layer while it is drawn, and WebGL2 calls a texture both sampled and attached a feedback loop
+   * whatever layer each names — so drawing the peel into the array would draw nothing at all.
+   * What it costs is one more map's memory where a peel is asked for, and one blit per peel.
+   */
+  private readonly peelTexture: WebGLTexture | null;
+  private readonly peelFramebuffer: WebGLFramebuffer | null;
+  private peeling = false;
 
-  constructor(gl: WebGL2RenderingContext, size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize) {
+  constructor(
+    gl: WebGL2RenderingContext,
+    size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize,
+    peeled = false,
+  ) {
     this.size = size;
+    this.layerCount = peeled ? 3 : 2;
 
-    const texture = gl.createTexture();
-    if (texture === null) throw new Error('ShadowMap: createTexture failed');
-    this.texture = texture;
-
-    gl.bindTexture(gl.TEXTURE_2D, texture);
-    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
-    // Clamp so anything outside the light frustum samples the border and is
-    // treated as lit, rather than wrapping into a spurious shadow.
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    const texture = createSunTexture(gl, size, this.layerCount);
+    this.current = texture;
 
     const framebuffer = gl.createFramebuffer();
-    if (framebuffer === null) throw new Error('ShadowMap: createFramebuffer failed');
+    if (framebuffer === null) throw new Error('SunShadowArray: createFramebuffer failed');
     this.framebuffer = framebuffer;
-
     gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
-    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, SUN_STATIC_LAYER);
     // Depth-only: without this WebGL expects a colour attachment.
     gl.drawBuffers([gl.NONE]);
     gl.readBuffer(gl.NONE);
 
+    if (peeled) {
+      const peelTexture = gl.createTexture();
+      const peelFramebuffer = gl.createFramebuffer();
+      if (peelTexture === null || peelFramebuffer === null) {
+        throw new Error('SunShadowArray: the peel target could not be created');
+      }
+      gl.bindTexture(gl.TEXTURE_2D, peelTexture);
+      gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+      gl.bindFramebuffer(gl.FRAMEBUFFER, peelFramebuffer);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, peelTexture, 0);
+      gl.drawBuffers([gl.NONE]);
+      gl.readBuffer(gl.NONE);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+      this.peelTexture = peelTexture;
+      this.peelFramebuffer = peelFramebuffer;
+    } else {
+      this.peelTexture = null;
+      this.peelFramebuffer = null;
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
     const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
     if (status !== gl.FRAMEBUFFER_COMPLETE) {
       /*
@@ -52,29 +109,121 @@ export class ShadowMap {
        * because the context cannot be lost before it exists.
        */
       if (gl.isContextLost()) return;
-      throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
+      throw new Error(`SunShadowArray: framebuffer incomplete (0x${status.toString(16)})`);
     }
 
     /*
-     * **Cleared once, here, to the far plane, because nothing else says what the texture holds.**
-     * WebGL zeroes it, and a zero compared with `LEQUAL` is an occluder at the light itself, so
-     * a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan hands the same
-     * texture back reading 1, which is lit, and that is what every capture here ran on: a scene
-     * with a second depth layer it never peeled lost its sun only under ANGLE's GL backend, the
-     * one Chrome on Linux runs by default. The frame's clear value is borrowed and put back.
+     * **Every layer cleared once, here, to the far plane, because nothing else says what it
+     * holds.** WebGL zeroes the texture, and a zero compared with `LEQUAL` is an occluder at the
+     * light itself, so a layer no pass has drawn put the whole world in shade. ANGLE on Vulkan
+     * hands the same texture back reading 1, which is lit, and that is what every capture here
+     * ran on: a scene with a second depth layer it never peeled lost its sun only under ANGLE's
+     * GL backend, the one Chrome on Linux runs by default. The frame's clear value is put back.
      */
     const frameClear = gl.getParameter(gl.DEPTH_CLEAR_VALUE) as number;
     gl.clearDepth(SHADOW_DEPTH_CLEAR);
-    gl.clear(gl.DEPTH_BUFFER_BIT);
+    gl.viewport(0, 0, size, size);
+    for (let layer = 0; layer < this.layers; layer++) {
+      gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+      gl.clear(gl.DEPTH_BUFFER_BIT);
+    }
     gl.clearDepth(frameClear);
 
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
-    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+  }
+
+  get texture(): WebGLTexture {
+    return this.current;
+  }
+
+  get layers(): number {
+    return this.layerCount;
+  }
+
+  /** Whether the two glass layers exist: from the first glass a sun pass is offered, for good. */
+  get hasGlass(): boolean {
+    return this.glass;
   }
 
-  /** Bind as the render target and clear. Caller then draws the casters. */
-  begin(gl: WebGL2RenderingContext): void {
+  /** The glass depth layer beside a map: fixed places after the three maps. */
+  glassLayer(which: 'static' | 'dynamic'): number {
+    return which === 'static' ? SUN_GLASS_STATIC_LAYER : SUN_GLASS_MOVING_LAYER;
+  }
+
+  /**
+   * Add the two glass layers, once, carrying every layer already held across.
+   *
+   * **Carried rather than re-baked**, because the sun's static map is the consumer's to bake and
+   * it may bake it once: the glass that grows the array arrives in the very pass that drew that
+   * map, so a copy is what keeps it. A depth blit per layer, same size and format, and the glass
+   * layers cleared to the far plane — nothing nearer than the sun until a pane is drawn there.
+   * Returns whether it grew, so the caller knows every bind of the old texture is stale.
+   */
+  growForGlass(gl: WebGL2RenderingContext): boolean {
+    if (this.glass) return false;
+    const old = this.current;
+    const oldLayers = this.layerCount;
+    const layers = SUN_GLASS_MOVING_LAYER + 1;
+    const texture = createSunTexture(gl, this.size, layers);
+    const read = gl.createFramebuffer();
+    if (read === null) throw new Error('SunShadowArray: createFramebuffer failed');
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+    for (let layer = 0; layer < oldLayers; layer++) {
+      gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, old, 0, layer);
+      gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+      gl.blitFramebuffer(
+        0,
+        0,
+        this.size,
+        this.size,
+        0,
+        0,
+        this.size,
+        this.size,
+        gl.DEPTH_BUFFER_BIT,
+        gl.NEAREST,
+      );
+    }
+    for (let layer = oldLayers; layer < layers; layer++) {
+      gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, layer);
+      gl.clearBufferfv(gl.DEPTH, 0, FAR_PLANE);
+    }
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.deleteFramebuffer(read);
+    gl.deleteTexture(old);
+    this.current = texture;
+    this.layerCount = layers;
+    this.glass = true;
+    return true;
+  }
+
+  /** Bind `layer` as the render target and clear it. Caller then draws the casters. */
+  begin(gl: WebGL2RenderingContext, layer: SunShadowLayer): void {
+    this.peeling = layer === 'static-peel' && this.peelFramebuffer !== null;
+    if (this.peeling) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, this.peelFramebuffer);
+    } else {
+      this.attach(gl, sunLayerIndex(layer));
+    }
+    this.clearAndRaster(gl);
+  }
+
+  /** Bind a glass depth layer as the render target and clear it: where the nearest pane is. */
+  beginGlass(gl: WebGL2RenderingContext, which: 'static' | 'dynamic'): void {
+    this.peeling = false;
+    this.attach(gl, this.glassLayer(which));
+    this.clearAndRaster(gl);
+  }
+
+  private attach(gl: WebGL2RenderingContext, layer: number): void {
     gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.current, 0, layer);
+  }
+
+  private clearAndRaster(gl: WebGL2RenderingContext): void {
     gl.viewport(0, 0, this.size, this.size);
     gl.clear(gl.DEPTH_BUFFER_BIT);
     /*
@@ -93,11 +242,56 @@ export class ShadowMap {
   end(gl: WebGL2RenderingContext): void {
     gl.disable(gl.POLYGON_OFFSET_FILL);
     gl.cullFace(gl.BACK);
+    if (this.peeling) {
+      /* The peel into its layer: same size, same format, so a nearest depth blit is a copy. */
+      gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.peelFramebuffer);
+      gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+      gl.framebufferTextureLayer(
+        gl.DRAW_FRAMEBUFFER,
+        gl.DEPTH_ATTACHMENT,
+        this.current,
+        0,
+        SUN_PEELED_LAYER,
+      );
+      gl.blitFramebuffer(
+        0,
+        0,
+        this.size,
+        this.size,
+        0,
+        0,
+        this.size,
+        this.size,
+        gl.DEPTH_BUFFER_BIT,
+        gl.NEAREST,
+      );
+      gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+      this.peeling = false;
+    }
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
   }
 
   dispose(gl: WebGL2RenderingContext): void {
     gl.deleteFramebuffer(this.framebuffer);
-    gl.deleteTexture(this.texture);
+    gl.deleteTexture(this.current);
+    if (this.peelFramebuffer !== null) gl.deleteFramebuffer(this.peelFramebuffer);
+    if (this.peelTexture !== null) gl.deleteTexture(this.peelTexture);
   }
 }
+
+/** The far plane, as `clearBufferfv` takes it: a layer no pane has reached is clear of glass. */
+const FAR_PLANE = new Float32Array([SHADOW_DEPTH_CLEAR]);
+
+function createSunTexture(gl: WebGL2RenderingContext, size: number, layers: number): WebGLTexture {
+  const texture = gl.createTexture();
+  if (texture === null) throw new Error('SunShadowArray: createTexture failed');
+  gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+  gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.DEPTH_COMPONENT24, size, size, layers);
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+  // Clamp so anything outside the light frustum samples the border and is
+  // treated as lit, rather than wrapping into a spurious shadow.
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return texture;
+}

package/src/render/sunGlassTint.ts

@@ -0,0 +1,86 @@
+/**
+ * What the sun's light keeps of itself through glass: an RGBA8 array of two layers, static and
+ * moving, beside the sun's depth array. RGB is the product of every pane's
+ * `transmission × (1 − F) × tint`, A the product of their clarities (`glassShadow.ts`).
+ *
+ * **Cleared to white and drawn with a multiplying blend and no depth test**, so every pane on a ray
+ * contributes and the order they come in cannot matter. **Mipmapped and filtered**, unlike the
+ * depths beside it: a frosted pane's colour is read at the level its spread asks for, so a wide
+ * spread is smooth rather than a scatter of taps — the chain is rebuilt after every draw of a layer.
+ * `'half'` makes it half the depth map's size and nothing else changes: the light matrix is the
+ * same, so a texel is a texel of the same place, only larger.
+ */
+export class SunGlassTint {
+  readonly size: number;
+  readonly texture: WebGLTexture;
+  private readonly framebuffer: WebGLFramebuffer;
+
+  constructor(gl: WebGL2RenderingContext, size: number) {
+    this.size = size;
+    const texture = gl.createTexture();
+    const framebuffer = gl.createFramebuffer();
+    if (texture === null || framebuffer === null) {
+      throw new Error('SunGlassTint: the tint target could not be created');
+    }
+    this.texture = texture;
+    this.framebuffer = framebuffer;
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    gl.texStorage3D(gl.TEXTURE_2D_ARRAY, mipLevels(size), gl.RGBA8, size, size, 2);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+    /* Both layers born clear: a layer no pane has reached lets everything through. */
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    for (let layer = 0; layer < 2; layer++) {
+      gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, texture, 0, layer);
+      gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    this.fillMips(gl);
+  }
+
+  /** Bind `layer` (0 static, 1 moving), clear it to white, and set the multiplying state. */
+  begin(gl: WebGL2RenderingContext, layer: number): void {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, layer);
+    gl.viewport(0, 0, this.size, this.size);
+    gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+    gl.enable(gl.BLEND);
+    gl.blendEquation(gl.FUNC_ADD);
+    gl.blendFuncSeparate(gl.DST_COLOR, gl.ZERO, gl.DST_ALPHA, gl.ZERO);
+  }
+
+  /** Put back what `begin` changed, and rebuild the mip chain the frost reads. */
+  end(gl: WebGL2RenderingContext): void {
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.enable(gl.DEPTH_TEST);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    this.fillMips(gl);
+  }
+
+  /** Every level from level 0, both layers: bound on the active unit and handed back. */
+  private fillMips(gl: WebGL2RenderingContext): void {
+    const previous = gl.getParameter(gl.TEXTURE_BINDING_2D_ARRAY) as WebGLTexture | null;
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
+    gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, previous);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteTexture(this.texture);
+  }
+}
+
+const CLEAR = new Float32Array([1, 1, 1, 1]);
+
+/** A full chain down to one texel. */
+function mipLevels(size: number): number {
+  return Math.floor(Math.log2(Math.max(1, size))) + 1;
+}

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);
+}