@driftengine/core 4.8.7 → 4.9.0

package/dist/render/ssrPass.d.ts

@@ -1,5 +1,6 @@
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { ReflectionQueue } from './screenSpaceReflection.ts';
+import type { ResolvedFrameReflections } from './frameReflections.ts';
 /**
  * Screen-space reflection on WebGL2: a scissored trace per surface, then one composite.
  *
@@ -33,6 +34,9 @@ export declare class SsrPass {
     private width;
     private height;
     /** `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;
+    private materialUniforms;
     private readonly depthToWorld;
     private readonly scissor;
     constructor(gl: WebGL2RenderingContext, 
@@ -54,6 +58,18 @@ export declare class SsrPass {
      */
     traceReflections(queue: ReflectionQueue, scene: WebGLTexture, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number, edgeFade: number): void;
     /** 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;
+    /**
+     * 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;
     resolveReflections(): void;
     dispose(): void;
 }

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`. */
@@ -153,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)
@@ -189,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/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

@@ -276,6 +276,13 @@ 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
@@ -304,5 +311,17 @@ export declare class SurfaceTexture {
     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;
 }

package/dist/render/surfaceTexture.js

@@ -25,6 +25,13 @@ export class SurfaceTexture {
     effectsTable = null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     blockFormat;
+    /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
+    width = 0;
+    height = 0;
+    /** The texture's storage format, which `flatLayer`'s copy matches so the copy converts nothing. */
+    storage;
+    /** Layer 0 as a plain 2D texture, made by `flatLayer` and dropped when the pixels change. */
+    flat = null;
     /**
      * 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
@@ -51,6 +58,9 @@ export class SurfaceTexture {
             this.layers = 1;
             this.blockFormat = null;
             this.mipmapped = false;
+            this.width = capture.width;
+            this.height = capture.height;
+            this.storage = capture.float ? gl.RGBA16F : gl.RGBA8;
             gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, capture.float ? gl.RGBA16F : gl.RGBA8, capture.width, capture.height, 1);
         }
         else if (baked !== null) {
@@ -58,6 +68,9 @@ export class SurfaceTexture {
             this.layers = baked.layers.length;
             this.blockFormat = null;
             this.mipmapped = false;
+            this.width = baked.width;
+            this.height = baked.height;
+            this.storage = gl.RGBA8;
             /* A typed array refuses either flag set, so both are put down here rather than assumed. */
             gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
             gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
@@ -73,6 +86,7 @@ export class SurfaceTexture {
                `generateMipmap` cannot write a compressed format. */
             this.layers = blocks.length;
             this.blockFormat = blocks[0].format;
+            this.storage = gl.NONE;
             this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
             uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
         }
@@ -81,6 +95,10 @@ export class SurfaceTexture {
             this.layers = sources.length;
             this.blockFormat = null;
             this.mipmapped = options.mipmap ?? true;
+            const { width, height } = layerSize(sources);
+            this.width = width;
+            this.height = height;
+            this.storage = this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8;
             uploadImages(gl, sources, this.srgb);
         }
         gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
@@ -143,6 +161,9 @@ export class SurfaceTexture {
         refuseArrayUpdate(this.layers);
         refuseBlockUpdate(this.blockFormat);
         const { width, height } = sourceSize(source);
+        this.width = width;
+        this.height = height;
+        this.dropFlat(gl);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
         /* Unflipped, matching the constructor. See it for why, and for what it cost. */
         gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, source);
@@ -162,9 +183,57 @@ export class SurfaceTexture {
         gl.activeTexture(gl.TEXTURE0 + unit);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     }
+    /**
+     * 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) {
+        if (this.texture === null || this.blockFormat !== null)
+            return null;
+        if (this.flat !== null)
+            return this.flat;
+        const flat = gl.createTexture();
+        const read = gl.createFramebuffer();
+        const draw = gl.createFramebuffer();
+        if (flat === null || read === null || draw === null)
+            return null;
+        gl.bindTexture(gl.TEXTURE_2D, flat);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, this.storage, this.width, this.height);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        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);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        const heldRead = gl.getParameter(gl.READ_FRAMEBUFFER_BINDING);
+        const heldDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+        gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, 0);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, draw);
+        gl.framebufferTexture2D(gl.DRAW_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, flat, 0);
+        const [w, h] = [this.width, this.height];
+        gl.blitFramebuffer(0, 0, w, h, 0, 0, w, h, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, heldRead);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, heldDraw);
+        gl.deleteFramebuffer(read);
+        gl.deleteFramebuffer(draw);
+        this.flat = flat;
+        return flat;
+    }
+    dropFlat(gl) {
+        if (this.flat !== null)
+            gl.deleteTexture(this.flat);
+        this.flat = null;
+    }
     dispose(gl) {
         if (this.texture === null)
             return;
+        this.dropFlat(gl);
         gl.deleteTexture(this.texture);
         this.texture = null;
         if (this.effectsTable !== null)

package/dist/render/temporalAa.d.ts

@@ -248,12 +248,26 @@ export declare class TemporalHistory {
     private picture;
     private width;
     private height;
+    /** Whether this frame of the renderer's has opened one of the sequence, and what it answered. */
+    private opened;
+    private answer;
+    /**
+     * A frame of the renderer's began: the next `openFrame` opens a frame of the sequence. Called at
+     * `beginFrame`, by both backends.
+     */
+    nextFrame(): void;
     /**
      * Open a frame at this target size, and answer whether the history may be sampled.
      *
      * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
      * resize or a cut discarded would sample the same position twice running, which is one sample
      * and not two.
+     *
+     * **Once a frame, however many times it is asked.** A renderer asks where the scene's camera
+     * arrives, and a frame binds that camera again after a scene capture or anything else that bound
+     * another; each asking opened a frame of its own, so the sequence stepped twice in such a frame
+     * and the edges of the picture swam. Asked again, it gives the answer it gave. What it gives up:
+     * a size changed between two asks in one frame is seen at the next frame, not at once.
      */
     openFrame(width: number, height: number): boolean;
     /**

package/dist/render/temporalAa.js

@@ -355,20 +355,40 @@ export class TemporalHistory {
     picture = false;
     width = 0;
     height = 0;
+    /** Whether this frame of the renderer's has opened one of the sequence, and what it answered. */
+    opened = false;
+    answer = false;
+    /**
+     * A frame of the renderer's began: the next `openFrame` opens a frame of the sequence. Called at
+     * `beginFrame`, by both backends.
+     */
+    nextFrame() {
+        this.opened = false;
+    }
     /**
      * Open a frame at this target size, and answer whether the history may be sampled.
      *
      * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
      * resize or a cut discarded would sample the same position twice running, which is one sample
      * and not two.
+     *
+     * **Once a frame, however many times it is asked.** A renderer asks where the scene's camera
+     * arrives, and a frame binds that camera again after a scene capture or anything else that bound
+     * another; each asking opened a frame of its own, so the sequence stepped twice in such a frame
+     * and the edges of the picture swam. Asked again, it gives the answer it gave. What it gives up:
+     * a size changed between two asks in one frame is seen at the next frame, not at once.
      */
     openFrame(width, height) {
+        if (this.opened)
+            return this.answer;
+        this.opened = true;
         this.frameIndex++;
         const usable = this.picture && width === this.width && height === this.height;
         if (!usable)
             this.picture = false;
         this.width = width;
         this.height = height;
+        this.answer = usable;
         return usable;
     }
     /**

package/dist/render/vertexDefaults.d.ts

@@ -38,6 +38,12 @@ export declare const ABSENT_ATTRIBUTE: Readonly<Record<string, readonly number[]
  * value that produces a picture. `flat.ts` reads `0` as none, `1` as sRGB and `2` as ACES.
  */
 export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
+/**
+ * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
+ * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
+ * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ */
+export declare function forwardTransformCode(transform: string): number;
 /**
  * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
  *
@@ -46,3 +52,14 @@ export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
  */
 export declare const RUSH_REACH_UV = 0.012;
 export declare const MOTION_BLUR_MAX_UV = 0.03;
+/**
+ * A longest smear as `setCameraMotionBlur` takes it: a share of the frame, above zero and at most
+ * half, and the default where the number is not one. Shared, so both backends cap one way.
+ */
+export declare function clampMotionShare(share: number): number;
+/**
+ * Said once where a draw names where it was last frame and the frame blurs by motion, but keeps no
+ * motion target to blur that draw by: each object's own motion is drawn only under a
+ * reconstruction on WebGPU, and anywhere else the camera's motion alone smears the frame.
+ */
+export declare const OBJECT_BLUR_UNKEPT: string;