@driftengine/core 4.8.6 → 4.9.0

package/dist/render/ssrPass.js

@@ -3,7 +3,7 @@ import { decalScissor } from './decalProjector.js';
 import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
-import { SSR_RESOLVE_FRAG } from './shaders/ssrResolve.js';
+import { SSR_MATERIAL_RESOLVE_FRAG, SSR_RESOLVE_FRAG } from './shaders/ssrResolve.js';
 import { SSR_TRACE_FRAG } from './shaders/ssrTrace.js';
 import { blendKeeping } from './sceneCoverage.js';
 /**
@@ -32,6 +32,9 @@ export class SsrPass {
     width = 0;
     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. */
+    materialResolve = null;
+    materialUniforms = {};
     depthToWorld = new Float32Array(16);
     scissor = new Int32Array(4);
     constructor(gl, 
@@ -118,6 +121,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`. */
@@ -133,6 +141,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);
@@ -152,6 +161,100 @@ export class SsrPass {
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     }
     /** 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, depth, probe, tint, viewProjection, eye, width, height, edgeFade, reflections) {
+        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);
+        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, tint, width, height, reflections) {
+        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() {
         const { gl } = this;
         if (this.reflection === null)
@@ -188,6 +291,9 @@ export class SsrPass {
             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/dist/render/surfaceModel.d.ts

@@ -50,7 +50,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;
@@ -104,7 +109,21 @@ export declare function hairModel(options?: {
     scatter?: number;
     backlit?: number;
 }): 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 declare const SKIN_MEAN_EXIT = 2.5;
+/** Burley's distance `d` for one channel of a skin, in metres: see `SKIN_MEAN_EXIT`. */
+export declare function skinProfileDistance(model: SkinModel, channel: 0 | 1 | 2): number;
+/** Skin. The defaults are a fair skin's: red light leaving a little over a centimetre away. */
 export declare function skinModel(options?: {
     scatterColor?: Vec3;
     radius?: number;
@@ -130,16 +149,18 @@ export declare function lightmapModel(options?: {
 }): LightmapModel;
 /**
  * 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 declare function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void;
+export declare function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array, physical?: boolean): void;
 /**
  * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
  * turned by its joint's palette entry, where it names one and a palette is set, and then by the

package/dist/render/surfaceModel.js

@@ -46,7 +46,23 @@ export function hairModel(options = {}) {
         backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
     });
 }
-/** 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, channel) {
+    return (model.scatterColor[channel] * 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 = {}) {
     const color = options.scatterColor ?? [0.85, 0.35, 0.22];
     for (let c = 0; c < 3; c++)
@@ -92,25 +108,31 @@ export function lightmapModel(options = {}) {
 }
 /**
  * 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, mapped, out) {
+export function packModel(model, mapped, out, physical = false) {
     out.fill(0);
-    if (model === null)
+    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;
@@ -121,7 +143,8 @@ export function packModel(model, mapped, out) {
             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;
@@ -139,6 +162,7 @@ export function packModel(model, mapped, out) {
             out[1] = model.region[1];
             out[2] = model.region[2];
             out[3] = model.region[3];
+            out[6] = highlight;
             return;
     }
 }

package/dist/render/surfaceOverlay.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 declare const OVERLAY_VECTORS = 15;
+/** Floats `packSurfaceOverlay` fills. */
+export declare const OVERLAY_FLOATS: number;
+/**
+ * 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 declare function packSurfaceOverlay(overlay: SurfaceOverlay | null, out: Float32Array): void;
+/** Whether an overlay lays anything at all, so a renderer can leave the lit switch off. */
+export declare function overlayLays(overlay: SurfaceOverlay | null): boolean;

package/dist/render/surfaceOverlay.js

@@ -0,0 +1,85 @@
+/** 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, fallback) => value !== undefined && Number.isFinite(value) ? value : fallback;
+function region(out, at, r) {
+    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, out) {
+    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) {
+    return (overlay !== null &&
+        (overlay.rim !== undefined || overlay.dissolve !== undefined || overlay.wrinkle !== undefined));
+}

package/dist/render/surfaceTexture.d.ts

@@ -13,6 +13,7 @@ import type { CompressedTextureFormat, SurfaceSource } from './compressedSource.
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 import type { CutoutMode } from './cutoutDither.ts';
 import type { LightmapTexels } from './lightmap.ts';
+import type { SceneCaptureTexels } from './sceneCapture.ts';
 /**
  * How a texture behaves past its edges and between its texels.
  *
@@ -161,6 +162,24 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * that is not a colour.
      */
     modelMap?: Texture | null;
+    /**
+     * Whether a lamp's and the sun's highlight on this surface is GGX's own, `π · D · Vis · F · N·L`,
+     * as Unreal and this engine's skin and eye shade it, rather than the engine's lobe scaled to a
+     * peak of one. **False by default**, every surface as it was.
+     *
+     * The peak-normalised lobe is a look control: the specular attribute says how strong a highlight
+     * is and roughness how wide, apart. Physical, they are entangled as they are in a real surface —
+     * the peak is `1 / (4 α²)` of the light head-on, so a polished surface's highlight is many times
+     * the look's and a rough one's lower and broader — and the specular attribute is read as the
+     * reflectance at normal incidence, F0: Unreal's `0.08 × Specular`, 0.04 at its default. Fresnel
+     * then brightens every surface toward grazing, not only a metal. A rectangle's highlight is the
+     * lobe integrated over it with the attribute as F0 already, so it is unchanged either way.
+     *
+     * On the standard, lightmap and anisotropic models. Skin and the eye are physical already; hair
+     * keeps its own three lobes. **What it gives up**: the look's independence of strength and width,
+     * and an 8-bit frame clips the brighter peak without `hdrScene`.
+     */
+    physicalSpecular?: boolean;
 }
 export interface SurfaceTextureOptions {
     /**
@@ -257,12 +276,19 @@ export declare class SurfaceTexture {
     private effectsTable;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     private readonly blockFormat;
+    /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
+    private width;
+    private height;
+    /** The texture's storage format, which `flatLayer`'s copy matches so the copy converts nothing. */
+    private readonly storage;
+    /** Layer 0 as a plain 2D texture, made by `flatLayer` and dropped when the pixels change. */
+    private flat;
     /**
      * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
      * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
      * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
-    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
+    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
     get hasEffects(): boolean;
     bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;
@@ -278,7 +304,24 @@ export declare class SurfaceTexture {
      * doing this every frame at any size wants to know that it costs what it costs.
      */
     update(gl: WebGL2RenderingContext, source: TexImageSource): void;
+    /**
+     * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
+     * by `captureScene`. Engine-internal, as `bind` is.
+     */
+    attachColor(gl: WebGL2RenderingContext): void;
     /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
     bind(gl: WebGL2RenderingContext, unit: number): void;
+    /**
+     * Layer 0 as a plain 2D texture: what a `sampler2D` can be handed, which an array cannot. Copied
+     * the first time it is asked for, by a framebuffer blit into storage of the same format, and kept
+     * until `update` or `dispose`. Engine-internal: a surface overlay's atlas is bound where the
+     * lit stage's one 2D image slot is (`surfaceOverlay.ts`).
+     *
+     * **Null for blocks**, which no framebuffer can read; the caller says so. What it costs is a copy
+     * of level 0 in memory beside the array, and the bindings of both framebuffer targets, which are
+     * read back before the blit and put back after it — a sync query, paid once per image.
+     */
+    flatLayer(gl: WebGL2RenderingContext): WebGLTexture | null;
+    private dropFlat;
     dispose(gl: WebGL2RenderingContext): void;
 }