@driftengine/core 4.8.6 → 4.9.0

package/src/render/shaders/ssrTrace.ts

@@ -21,6 +21,7 @@
  */
 
 import { glslIsFarDepth } from '../depthConvention.ts';
+import { ENV_BRDF_GLSL } from './flat/lobes.ts';
 
 /**
  * The most samples the march may take. `uSsrSteps` breaks out early.
@@ -64,15 +65,34 @@ uniform vec3 uSsrEye;
 uniform vec3 uSsrAxis;
 uniform vec3 uSsrTint;
 uniform float uSsrStrength;
+/**
+ * Whether \`uSsrStrength\` is the surface's reflectance head-on, carried per pixel through the
+ * split-sum BRDF (x, 1 or 0), and the roughness it is carried at (y). \`ReflectiveSurface.fresnel\`.
+ */
+uniform vec2 uSsrFresnel;
 uniform float uSsrFacingCos;
 uniform float uSsrReach;
 uniform float uSsrThickness;
 uniform float uSsrSteps;
 /** How much of the frame each side is fade, as a fraction. */
 uniform float uSsrEdgeFade;
+/**
+ * **1 where the trace is the frame's materials rather than a box's**: every pixel the lit stage
+ * left a reflection for reflects, by its own material, and the box, its axis and its strength are
+ * not read. See \`flat/reflectionSurface.ts\` for the two maps it is handed.
+ */
+uniform float uSsrMaterial;
+/** The roughness past which a pixel's reflection is the probes' alone, faded over the last quarter. */
+uniform float uSsrMaxRoughness;
+/** The environment as the frame shows it, and the surface's roughness in its alpha. */
+uniform sampler2D uSsrProbeMap;
+/** What a found reflection is multiplied by to land where the environment did. */
+uniform sampler2D uSsrTintMap;
 
 out vec4 fragColor;
 
+${ENV_BRDF_GLSL}
+
 /** What the frame drew at a screen position, as a world point. */
 vec3 worldAt(vec2 uv, float stored) {
   vec4 world = uSsrDepthToWorld * vec4(uv * 2.0 - 1.0, stored, 1.0);
@@ -133,7 +153,32 @@ void main() {
   mask *= smoothstep(uSsrFacingCos, min(1.0, uSsrFacingCos + 0.25), facing);
   /* Nothing was drawn here, so there is no surface to reflect in. */
   mask *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
-  mask *= uSsrStrength;
+  /*
+   * **How much the surface returns**: one number over the box, or, where the caller asks, its
+   * reflectance head-on carried through the split-sum BRDF at this pixel's own view and the
+   * surface's roughness — the lit stage's fit, so the two agree on what a surface reflects. A floor
+   * then returns more toward the horizon than underfoot, and the share follows the camera.
+   */
+  float returned = uSsrStrength;
+  if (uSsrFresnel.x > 0.5) {
+    vec2 dfg = envBrdfApprox(clamp(dot(normal, normalize(toEye)), 0.0, 1.0), uSsrFresnel.y);
+    returned = clamp(uSsrStrength * dfg.x + dfg.y, 0.0, 1.0);
+  }
+  mask *= returned;
+  /*
+   * **Or the pixel's own material**, where the trace is the frame's: reflective wherever the lit
+   * stage left a reflection to swap (any tint above zero), and the probes' alone past the
+   * roughness ceiling. How much it returns is the tint, which the resolve multiplies by, so the
+   * mask here is only whether to march and how much to trust a hit.
+   */
+  if (uSsrMaterial > 0.5) {
+    vec3 tint = textureLod(uSsrTintMap, vUv, 0.0).rgb;
+    float roughness = textureLod(uSsrProbeMap, vUv, 0.0).a;
+    float reflective = max(max(tint.r, tint.g), tint.b) > 0.0 ? 1.0 : 0.0;
+    float ceiling = max(uSsrMaxRoughness, 1.0e-4);
+    mask = reflective * (1.0 - smoothstep(ceiling * 0.75, ceiling, roughness));
+    mask *= ${glslIsFarDepth('stored')} ? 0.0 : 1.0;
+  }
 
   vec3 found = vec3(0.0);
   float weight = 0.0;

package/src/render/shaders/water.ts

@@ -177,8 +177,11 @@ uniform vec3 uAmbient;
  * is the single strongest cue that a surface *is* water switched off because no
  * directional source existed to make it. A lantern on a jetty threw nothing.
  *
- * Same slots, same weights and the same two falloff shapes as the surface shader, so a
- * lamp behaves the same way over water as it does over the ground beside it.
+ * Same slots, same weights and the surface shader's falloffs, a light's own exponent among
+ * them, so a lamp reaches as far over water as over the ground beside it. **What it gives up**:
+ * a spot's cone, which water does not read, so a spot lights the water around it as a lamp
+ * would; and the smooth falloff's square, which the surface applies and this has never, so under
+ * that falloff a lamp's pool on water is the wider of the two.
  */
 #define MAX_LIGHTS ${MAX_POINT_LIGHTS}
 uniform int uLightCount;
@@ -187,6 +190,8 @@ uniform vec3 uLightColor[MAX_LIGHTS];
 uniform float uLightRadius[MAX_LIGHTS];
 uniform float uLightWeight[MAX_LIGHTS];
 uniform int uLightFalloff;
+/* The surface shader's cone record, of which water reads z alone: a light's own falloff exponent. */
+uniform vec4 uLightCone[MAX_LIGHTS];
 ${FOG_GLSL}
 uniform vec3 uCameraPos;
 uniform sampler2D uReflectionMap;
@@ -243,7 +248,11 @@ void main() {
     vec3 toLight = uLightPos[i] - vWorldPos;
     float lightDist = length(toLight);
     float falloff;
-    if (uLightFalloff == 1) {
+    float exponent = uLightCone[i].z;
+    if (exponent > 0.0) {
+      float reach = lightDist / max(uLightRadius[i], 1e-4);
+      falloff = pow(clamp(1.0 - reach * reach, 0.0, 1.0), exponent);
+    } else if (uLightFalloff == 1) {
       float window = clamp(1.0 - pow(lightDist / max(uLightRadius[i], 1e-4), 4.0), 0.0, 1.0);
       falloff = window * window / max(lightDist * lightDist, 0.01);
     } else {

package/src/render/skinScatter.ts

@@ -7,7 +7,9 @@
  * neighbours' `N·L` as well as its own: the clamped cosine averaged around a ring of the surface's
  * curvature, weighted by the diffusion profile at each neighbour's distance. The profile is Burley's
  * normalised diffusion, one per channel, at a scatter distance `d` — the model's `radius` times its
- * scatter colour — projected onto the ring's plane, as a cylinder's cross-section sees it. The
+ * scatter colour, over `SKIN_MEAN_EXIT`, since `radius` is how far light travels and the profile
+ * carries it two and a half `d` — projected onto the ring's plane, as a cylinder's cross-section
+ * sees it. The
  * result depends on `N·L` and on one number per channel, `k = d × curvature`, and at `k = 0` it is
  * Lambert's.
  *

package/src/render/ssrPass.ts

@@ -6,7 +6,8 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.ts';
 import type { ReflectionQueue } from './screenSpaceReflection.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
-import { SSR_RESOLVE_FRAG } from './shaders/ssrResolve.ts';
+import { SSR_MATERIAL_RESOLVE_FRAG, SSR_RESOLVE_FRAG } from './shaders/ssrResolve.ts';
+import type { ResolvedFrameReflections } from './frameReflections.ts';
 import { SSR_TRACE_FRAG } from './shaders/ssrTrace.ts';
 import { blendKeeping } from './sceneCoverage.ts';
 
@@ -36,6 +37,10 @@ export class SsrPass {
   private height = 0;
 
   /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per surface. */
+  /** The frame's materials' resolve, compiled the first time a frame traces them. */
+  private materialResolve: WebGLProgram | null = null;
+  private materialUniforms: Record<string, WebGLUniformLocation | null> = {};
+
   private readonly depthToWorld = new Float32Array(16);
   private readonly scissor = new Int32Array(4);
 
@@ -150,6 +155,11 @@ export class SsrPass {
     gl.activeTexture(gl.TEXTURE1);
     gl.bindTexture(gl.TEXTURE_2D, scene);
     gl.uniform1i(u['uSsrScene'] ?? null, 1);
+    /* The materials' maps unread in this mode, and pointed at a bound texture all the same: a
+       driver may fetch a sampler's descriptor before the branch that skips it. */
+    gl.uniform1i(u['uSsrProbeMap'] ?? null, 0);
+    gl.uniform1i(u['uSsrTintMap'] ?? null, 0);
+    gl.uniform1f(u['uSsrMaterial'] ?? null, 0);
     gl.uniformMatrix4fv(u['uSsrDepthToWorld'] ?? null, false, this.depthToWorld);
     /* No Y flip on this backend: `gl.scissor` and the framebuffer both count rows from the bottom,
        which is the space the raw matrix already emits. See `CLIP_Y_FLIP`. */
@@ -173,6 +183,7 @@ export class SsrPass {
       gl.uniform3fv(u['uSsrAxis'] ?? null, surface.axis);
       gl.uniform3fv(u['uSsrTint'] ?? null, surface.tint);
       gl.uniform1f(u['uSsrStrength'] ?? null, surface.strength);
+      gl.uniform2f(u['uSsrFresnel'] ?? null, surface.fresnel ? 1 : 0, surface.roughness);
       gl.uniform1f(u['uSsrFacingCos'] ?? null, surface.facingCos);
       gl.uniform1f(u['uSsrReach'] ?? null, surface.reachM);
       gl.uniform1f(u['uSsrThickness'] ?? null, surface.thicknessM);
@@ -194,6 +205,131 @@ export class SsrPass {
   }
 
   /** Composite what the trace found over whatever framebuffer is bound. */
+  /**
+   * Every pixel the lit stage left a reflection for, marched against the frame's depth by the
+   * trace's material mode, into this pass's own target; `resolveMaterials` then swaps the probe's
+   * share for it. See `frameReflections.ts`. Ends on the default framebuffer, as the surfaces' does.
+   */
+  traceMaterials(
+    scene: WebGLTexture,
+    depth: WebGLTexture,
+    probe: WebGLTexture,
+    tint: WebGLTexture,
+    viewProjection: ReadonlyMat4,
+    eye: ArrayLike<number>,
+    width: number,
+    height: number,
+    edgeFade: number,
+    reflections: ResolvedFrameReflections,
+  ): void {
+    const { gl } = this;
+    const u = this.traceUniforms;
+    this.ensureSize(width, height);
+    mat4.invert(this.depthToWorld, viewProjection);
+    mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, width, height);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.disable(gl.SCISSOR_TEST);
+    gl.disable(gl.BLEND);
+    gl.clearBufferfv(gl.COLOR, 0, [0, 0, 0, 0]);
+
+    gl.useProgram(this.trace);
+    gl.bindVertexArray(this.vao);
+    const textures = [depth, scene, probe, tint];
+    const names = ['uSsrDepth', 'uSsrScene', 'uSsrProbeMap', 'uSsrTintMap'];
+    for (let unit = 0; unit < 4; unit++) {
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, textures[unit] ?? null);
+      gl.uniform1i(u[names[unit] ?? ''] ?? null, unit);
+    }
+    gl.uniformMatrix4fv(u['uSsrDepthToWorld'] ?? null, false, this.depthToWorld);
+    gl.uniformMatrix4fv(u['uSsrViewProj'] ?? null, false, viewProjection as Float32Array);
+    gl.uniform3f(u['uSsrEye'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+    gl.uniform1f(u['uSsrEdgeFade'] ?? null, edgeFade);
+    gl.uniform3f(u['uSsrAxis'] ?? null, 0, 0, 0);
+    gl.uniform3f(u['uSsrTint'] ?? null, 1, 1, 1);
+    gl.uniform1f(u['uSsrStrength'] ?? null, 1);
+    gl.uniform2f(u['uSsrFresnel'] ?? null, 0, 0);
+    gl.uniform1f(u['uSsrFacingCos'] ?? null, -1);
+    gl.uniform1f(u['uSsrReach'] ?? null, reflections.reachM);
+    gl.uniform1f(u['uSsrThickness'] ?? null, reflections.thicknessM);
+    gl.uniform1f(u['uSsrSteps'] ?? null, reflections.steps);
+    gl.uniform1f(u['uSsrMaterial'] ?? null, 1);
+    gl.uniform1f(u['uSsrMaxRoughness'] ?? null, reflections.maxRoughness);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    /* Back to the surfaces' mode, which every other trace in the frame is. */
+    gl.uniform1f(u['uSsrMaterial'] ?? null, 0);
+
+    gl.bindVertexArray(null);
+    for (let unit = 3; unit >= 0; unit--) {
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    gl.depthMask(true);
+    gl.enable(gl.DEPTH_TEST);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  /**
+   * The probe's share of each pixel swapped for what `traceMaterials` found, blurred by the
+   * surface's roughness, added onto whatever framebuffer is bound — the scene's, with the two maps
+   * already detached from it. See `SSR_MATERIAL_RESOLVE_FRAG`.
+   */
+  resolveMaterials(
+    probe: WebGLTexture,
+    tint: WebGLTexture,
+    width: number,
+    height: number,
+    reflections: ResolvedFrameReflections,
+  ): void {
+    const { gl } = this;
+    if (this.reflection === null) return;
+    if (this.materialResolve === null) {
+      this.materialResolve = compileProgram(
+        gl,
+        FULLSCREEN_VERT,
+        SSR_MATERIAL_RESOLVE_FRAG,
+        'ssrMaterialResolve',
+      );
+      this.materialUniforms = uniformLocations(gl, this.materialResolve, 'ssrMaterialResolve');
+    }
+    const u = this.materialUniforms;
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.disable(gl.CULL_FACE);
+    gl.enable(gl.BLEND);
+    /* Added, a negative addend subtracting, and the scene's alpha kept. */
+    blendKeeping(gl, gl.ONE, gl.ONE);
+    gl.useProgram(this.materialResolve);
+    const textures = [this.reflection, probe, tint];
+    const names = ['uSsrReflection', 'uSsrProbeMap', 'uSsrTintMap'];
+    for (let unit = 0; unit < 3; unit++) {
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, textures[unit] ?? null);
+      gl.uniform1i(u[names[unit] ?? ''] ?? null, unit);
+    }
+    gl.uniform3f(
+      u['uSsrBlur'] ?? null,
+      1 / Math.max(width, 1),
+      1 / Math.max(height, 1),
+      reflections.blur * height,
+    );
+    gl.bindVertexArray(this.vao);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+    gl.bindVertexArray(null);
+    for (let unit = 2; unit >= 0; unit--) {
+      gl.activeTexture(gl.TEXTURE0 + unit);
+      gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    gl.disable(gl.BLEND);
+    gl.depthMask(true);
+    gl.enable(gl.DEPTH_TEST);
+  }
+
   resolveReflections(): void {
     const { gl } = this;
     if (this.reflection === null) return;
@@ -233,6 +369,8 @@ export class SsrPass {
     if (this.framebuffer !== null) gl.deleteFramebuffer(this.framebuffer);
     gl.deleteProgram(this.trace);
     gl.deleteProgram(this.resolve);
+    if (this.materialResolve !== null) gl.deleteProgram(this.materialResolve);
+    this.materialResolve = null;
     gl.deleteVertexArray(this.vao);
     this.reflection = null;
     this.framebuffer = null;

package/src/render/surfaceModel.ts

@@ -54,7 +54,12 @@ export interface SkinModel {
   readonly kind: 'skin';
   /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
   readonly scatterColor: Vec3;
-  /** Metres: how far light travels beneath it before it leaves. */
+  /**
+   * Metres: how far light travels beneath it, on average, before it leaves — from where it entered
+   * to where it leaves, for a channel whose share of `scatterColor` is 1. Burley's profile, which
+   * the lit stage and the screen-space blur both scatter by, does that at a distance `d` two fifths
+   * of it, and carries a tail of light out to about three and a half times it.
+   */
   readonly radius: number;
   /** 0 to 1: how much a light behind a thin part shows through it. */
   readonly transmission: number;
@@ -159,7 +164,25 @@ export function hairModel(
   });
 }
 
-/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+/**
+ * How far Burley's normalised diffusion carries light on average, in units of its own distance
+ * `d`: its radial density `(e^(−r/d) + e^(−r/3d)) / 4d` has the mean `(d² + 9d²) / 4d = 2.5 d`. So a
+ * skin whose light travels `radius` scatters by a profile at `d = radius / 2.5`.
+ *
+ * **Until 4.8.7 `radius` was `d` itself**, so light travelled two and a half times as far as the
+ * model said, and the screen-space blur — whose taps reach nine `d` — spread a face at arm's length
+ * over sixty pixels: a nose, lips and brows washed into one blur where a centimetre covers a few.
+ * The lit stage's pre-integrated fit, transmission and penumbra take the same `d`, so the two paths
+ * still agree with each other.
+ */
+export const SKIN_MEAN_EXIT = 2.5;
+
+/** Burley's distance `d` for one channel of a skin, in metres: see `SKIN_MEAN_EXIT`. */
+export function skinProfileDistance(model: SkinModel, channel: 0 | 1 | 2): number {
+  return ((model.scatterColor[channel] as number) * model.radius) / SKIN_MEAN_EXIT;
+}
+
+/** Skin. The defaults are a fair skin's: red light leaving a little over a centimetre away. */
 export function skinModel(
   options: { scatterColor?: Vec3; radius?: number; transmission?: number; profile?: number } = {},
 ): SkinModel {
@@ -218,24 +241,36 @@ export function lightmapModel(options: { region?: LightmapRegion } = {}): Lightm
 
 /**
  * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
- * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
- * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ * map is bound into the last. An eye's axis goes in with the descriptor's own until the draw turns
+ * it: see `eyeAxisInWorld`. `physical` is `SurfaceMaterial.physicalSpecular`, in the lane the
+ * models that read it leave free; skin, hair and the eye shade their own highlights and never do.
  *
- * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - standard (null): − · −, −, physical, −
+ * - anisotropic: strength, cos and sin of the rotation · −, −, physical, map
  * - hair: shift, scatter, backlit, − · −, −, −, map
- * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - skin: the scatter colour, radius / `SKIN_MEAN_EXIT` · transmission, profile, −, map
  * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
- * - lightmap: the region's scale and bias · −, −, −, map
+ * - lightmap: the region's scale and bias · −, −, physical, map
  */
-export function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void {
+export function packModel(
+  model: SurfaceModel | null,
+  mapped: boolean,
+  out: Float32Array,
+  physical = false,
+): void {
   out.fill(0);
-  if (model === null) return;
+  const highlight = physical ? 1 : 0;
+  if (model === null) {
+    out[6] = highlight;
+    return;
+  }
   out[7] = mapped ? 1 : 0;
   switch (model.kind) {
     case 'anisotropic':
       out[0] = model.strength;
       out[1] = Math.cos(model.rotation);
       out[2] = Math.sin(model.rotation);
+      out[6] = highlight;
       return;
     case 'hair':
       out[0] = model.shift;
@@ -246,7 +281,8 @@ export function packModel(model: SurfaceModel | null, mapped: boolean, out: Floa
       out[0] = model.scatterColor[0];
       out[1] = model.scatterColor[1];
       out[2] = model.scatterColor[2];
-      out[3] = model.radius;
+      /* Burley's distance for a channel of share 1, which the shader scales by each share. */
+      out[3] = model.radius / SKIN_MEAN_EXIT;
       out[4] = model.transmission;
       out[5] = model.profile;
       return;
@@ -264,6 +300,7 @@ export function packModel(model: SurfaceModel | null, mapped: boolean, out: Floa
       out[1] = model.region[1];
       out[2] = model.region[2];
       out[3] = model.region[3];
+      out[6] = highlight;
       return;
   }
 }

package/src/render/surfaceOverlay.ts

@@ -0,0 +1,195 @@
+/**
+ * What a draw lays over its surface beyond its material: a rim of light, an emissive overlay that
+ * dissolves the surface away, and a second normal map blended in by region. Set per draw with
+ * `RendererApi.setSurfaceOverlay`, so one character's whole set of materials changes together
+ * while another's does not.
+ *
+ * **Per draw and held, like `setEnvironmentGain`**: set before a character's draws, cleared after,
+ * and every draw between them wears it. **Images come from one atlas** (`maps`), each named by the
+ * rectangle it occupies — a scale and an offset in the atlas's uv — because the lit stage binds every
+ * sampler a device is guaranteed and has none left for a texture of its own: the atlas is bound in
+ * the slot the frame's refraction copy takes, which an opaque surface never reads. A draw that both
+ * refracts and wears an overlay's images keeps its refraction and loses the images, said once.
+ *
+ * **Fifteen vectors of numbers**, in the material's uniform block. WebGPU has the room; WebGL2 has
+ * room where its device reports more than the lit stage's 254 vectors, and refuses the overlay in
+ * words where it does not. See `packSurfaceOverlay` for the layout.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { SurfaceTextureHandle } from './backend/api.ts';
+
+/** Where an image sits in the atlas: its size and its corner, each in the atlas's uv. */
+export interface OverlayRegion {
+  readonly scale: readonly [number, number];
+  readonly offset: readonly [number, number];
+}
+
+/**
+ * Light along the silhouette: the edge `(1 - N·V)^falloff`, leaning toward normals that face up,
+ * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
+ * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
+ * surface wears, not light it gives off.
+ */
+export interface SurfaceRim {
+  readonly colour: Vec3;
+  /** How bright, 0 for none. Multiplied with `alpha`. */
+  readonly intensity: number;
+  readonly alpha?: number;
+  /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
+  readonly falloff?: number;
+  /**
+   * How far the rim leans toward normals that face up: the weight is `(N·up · ½ + ½)^upward`, so
+   * 0 is no lean. 0.4 unless given.
+   */
+  readonly upward?: number;
+  /** The exponent the whole edge is raised to. 1 unless given. */
+  readonly contrast?: number;
+  /** A noise image laid in screen space and scrolled, the rim taken times it, clamped to 1. */
+  readonly noise?: {
+    readonly region: OverlayRegion;
+    /** Screens a second, along x and y. */
+    readonly scroll?: readonly [number, number];
+    /** Repeats across the screen's height. 1 unless given. */
+    readonly tiling?: number;
+  };
+  /** A pulse `½ + ½ sin(rate · t)`, held between `low` and `high`, on `Environment.surfaceTime`. */
+  readonly pulse?: { readonly rate: number; readonly low: number; readonly high: number };
+  /** A mask in the mesh's uv where the rim is erased: the rim times `1 - weight · mask`. */
+  readonly mask?: { readonly region: OverlayRegion; readonly weight: number };
+}
+
+/**
+ * The surface cut away where a noise in its uv falls under `threshold`, with a glowing band just
+ * above it, and a colour laid over the surface through the same noise.
+ */
+export interface SurfaceDissolve {
+  readonly noise: { readonly region: OverlayRegion; readonly tiling?: readonly [number, number] };
+  /** 0 keeps everything; 1 cuts everything. */
+  readonly threshold: number;
+  /** The band's width, in the noise's own units. 0.05 unless given. */
+  readonly edge?: number;
+  /** The band's light. */
+  readonly edgeColour?: Vec3;
+  readonly edgeIntensity?: number;
+  /** A colour laid over the surface through the noise, as light, and how much of it. */
+  readonly overlay?: { readonly colour: Vec3; readonly amount: number };
+}
+
+/**
+ * A second normal map blended into the surface's by six region weights, read through two masks:
+ * the first mask's red, green and blue carry regions 1 to 3, the second's regions 4 to 6. A face's
+ * expressions, or veins brought up all over.
+ */
+export interface SurfaceWrinkle {
+  readonly normal: OverlayRegion;
+  readonly masks: readonly [OverlayRegion, OverlayRegion];
+  readonly weights: readonly [number, number, number, number, number, number];
+}
+
+/**
+ * What a draw lays over its surface beyond its material, for `setSurfaceOverlay`: a rim, a dissolve
+ * and wrinkles, each optional, and the atlas their images are regions of.
+ */
+export interface SurfaceOverlay {
+  /**
+   * The atlas every image above is a region of. Absent: no image is read whatever regions are
+   * named — rims are smooth, nothing dissolves and nothing wrinkles — because the slot then holds a
+   * stand-in whose colour would read as a noise and a mask.
+   */
+  readonly maps?: SurfaceTextureHandle;
+  readonly rim?: SurfaceRim;
+  readonly dissolve?: SurfaceDissolve;
+  readonly wrinkle?: SurfaceWrinkle;
+}
+
+/** Vectors the overlay takes in the material's block: `uOverlay[OVERLAY_VECTORS]`. */
+export const OVERLAY_VECTORS = 15;
+/** Floats `packSurfaceOverlay` fills. */
+export const OVERLAY_FLOATS = OVERLAY_VECTORS * 4;
+
+const finite = (value: number | undefined, fallback: number): number =>
+  value !== undefined && Number.isFinite(value) ? value : fallback;
+
+function region(out: Float32Array, at: number, r: OverlayRegion | undefined | null): void {
+  out[at] = finite(r?.scale[0], 0);
+  out[at + 1] = finite(r?.scale[1], 0);
+  out[at + 2] = finite(r?.offset[0], 0);
+  out[at + 3] = finite(r?.offset[1], 0);
+}
+
+/**
+ * An overlay as the shader reads it, into `out` (`OVERLAY_FLOATS`); all zeros for `null`, which is
+ * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
+ * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
+ *
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 1: falloff, upward lean, contrast, mask weight
+ * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
+ * - 4: the pulse's low and high (1 and 1 where none)
+ * - 5: the rim's mask region
+ * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
+ * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
+ * - 10: the wrinkle normal's region; 11 and 12: the two masks'; 13 and 14: the six weights
+ */
+export function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32Array): void {
+  out.fill(0);
+  if (overlay === null) return;
+  /* No atlas, no region: see `SurfaceOverlay.maps`. */
+  const images = overlay.maps !== undefined;
+  const rim = overlay.rim;
+  if (rim !== undefined) {
+    out[0] = finite(rim.colour[0], 0);
+    out[1] = finite(rim.colour[1], 0);
+    out[2] = finite(rim.colour[2], 0);
+    out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+    out[4] = Math.max(0, finite(rim.falloff, 1.5));
+    out[5] = Math.max(0, finite(rim.upward, 0.4));
+    out[6] = Math.max(0, finite(rim.contrast, 1));
+    out[7] = rim.mask === undefined ? 0 : Math.min(Math.max(finite(rim.mask.weight, 0), 0), 1);
+    region(out, 8, images ? rim.noise?.region : null);
+    out[12] = finite(rim.noise?.scroll?.[0], 0);
+    out[13] = finite(rim.noise?.scroll?.[1], 0);
+    out[14] = Math.max(0, finite(rim.noise?.tiling, 1));
+    out[15] = finite(rim.pulse?.rate, 0);
+    out[16] = rim.pulse === undefined ? 1 : finite(rim.pulse.low, 1);
+    out[17] = rim.pulse === undefined ? 1 : finite(rim.pulse.high, 1);
+    region(out, 20, images ? rim.mask?.region : null);
+  }
+  const dissolve = overlay.dissolve;
+  if (dissolve !== undefined) {
+    region(out, 24, images ? dissolve.noise.region : null);
+    out[28] = finite(dissolve.noise.tiling?.[0], 1);
+    out[29] = finite(dissolve.noise.tiling?.[1], 1);
+    out[30] = Math.min(Math.max(finite(dissolve.threshold, 0), 0), 1);
+    out[31] = Math.max(1e-4, finite(dissolve.edge, 0.05));
+    const edge = dissolve.edgeColour ?? [0, 0, 0];
+    out[32] = finite(edge[0], 0);
+    out[33] = finite(edge[1], 0);
+    out[34] = finite(edge[2], 0);
+    out[35] = Math.max(0, finite(dissolve.edgeIntensity, 1));
+    const laid = dissolve.overlay;
+    if (laid !== undefined) {
+      out[36] = finite(laid.colour[0], 0);
+      out[37] = finite(laid.colour[1], 0);
+      out[38] = finite(laid.colour[2], 0);
+      out[39] = Math.max(0, finite(laid.amount, 0));
+    }
+  }
+  const wrinkle = overlay.wrinkle;
+  if (wrinkle !== undefined) {
+    region(out, 40, images ? wrinkle.normal : null);
+    region(out, 44, images ? wrinkle.masks[0] : null);
+    region(out, 48, images ? wrinkle.masks[1] : null);
+    for (let i = 0; i < 6; i++) {
+      out[52 + i] = Math.min(Math.max(finite(wrinkle.weights[i], 0), 0), 1);
+    }
+  }
+}
+
+/** Whether an overlay lays anything at all, so a renderer can leave the lit switch off. */
+export function overlayLays(overlay: SurfaceOverlay | null): boolean {
+  return (
+    overlay !== null &&
+    (overlay.rim !== undefined || overlay.dissolve !== undefined || overlay.wrinkle !== undefined)
+  );
+}