@driftengine/core 4.8.6 → 4.9.0

package/dist/render/backend/webgl2/renderer.js

@@ -4,11 +4,17 @@ import { FOG_OFF, FOG_RECEDE, fogModeOf } from '../drawFog.js';
 import { blendCovering, blendKeeping } from '../../sceneCoverage.js';
 import { mat4 } from 'gl-matrix';
 import { GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
+import { maskOf } from '../../frame/resources.js';
+/** The two copies a registered pass may declare it reads. See `drawPass`. */
+const COLOR_SNAPSHOT = maskOf('colorSnapshot');
+const DEPTH_SNAPSHOT = maskOf('depthSnapshot');
 import { resolveGlass } from '../../glass.js';
 import { PickableSet } from '../../pickable.js';
 import { TEMPORAL_HISTORY_BLEND, TemporalHistory, jitterOffset, jitterProjection, } from '../../temporalAa.js';
 import { DecalPass } from '../../decalPass.js';
 import { SsrPass } from '../../ssrPass.js';
+import { ReflectionSurfaceTargets } from '../../reflectionSurfaceTargets.js';
+import { frameReflectionsRefused, resolveFrameReflections, } from '../../frameReflections.js';
 import { GlobalMediumPass } from '../../globalMediumPass.js';
 import { DEFAULT_GLOBAL_MEDIUM, WEAK_GPU_MEDIUM_STEPS, mediumActive, resolveGlobalMedium, } from '../../globalMedium.js';
 import { REFLECTION_EDGE_FADE, ReflectionQueue } from '../../screenSpaceReflection.js';
@@ -28,7 +34,8 @@ import { attachContextLoss } from '../../contextLoss.js';
 import { isWeakGpuFamily, webgl2RendererName } from '../../gpuCapability.js';
 import { GpuTimer } from '../../gpuTimer.js';
 import { compileProgram, uniformLocations } from '../../shader.js';
-import { FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../uniformVectorBudget.js';
+import { countUniformVectors, FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../uniformVectorBudget.js';
+import { OVERLAY_FLOATS, overlayLays, packSurfaceOverlay, } from '../../surfaceOverlay.js';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
@@ -41,7 +48,7 @@ import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/un
 import { flatFrag, flatVert } from '../../shaders/flat/index.js';
 import { skinEight } from '../../shaders/skinning.js';
 import { MODEL_MAP_TEXTURE_UNIT, MORPH_DELTA_TEXTURE_UNIT, SKIN_PALETTE_TEXTURE_UNIT, } from '../../lightBudget.js';
-import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel } from '../../surfaceModel.js';
+import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel, skinProfileDistance, } from '../../surfaceModel.js';
 import { lightmapRegionsBound, modelBound, skinHalfBound } from '../../shaders/flat/models.js';
 import { lightmapTexels, warnRegionsWithoutPage, warnUnpagedLightmap, withLightmapUvs, } from '../../lightmap.js';
 import { GlSkinScatter } from './skinScatter.js';
@@ -86,6 +93,8 @@ import { resolveRenderQuality } from '../../renderQuality.js';
 import { drawingBufferSize } from '../../drawingBuffer.js';
 import { Mesh, createMeshIncremental } from '../../mesh.js';
 import { SurfaceTexture } from '../../surfaceTexture.js';
+import { sceneCaptureTexels } from '../../sceneCapture.js';
+import { GlSceneCaptureTarget } from './sceneCaptureTarget.js';
 import { glCompressedFormats } from '../../glCompressed.js';
 import { PlumeRenderer } from '../../plumeRenderer.js';
 import { createScatterDeform, resolveScatterDeform } from '../../scatterDeform.js';
@@ -102,8 +111,9 @@ import { SCATTER_DEPTH_VERT, SCATTER_FRAG, SCATTER_VERT } from '../../shaders/sc
 import { FlockRenderer } from '../../flockRenderer.js';
 import { TextRenderer } from '../../textRenderer.js';
 import { SdfTextRenderer } from '../../sdfTextRenderer.js';
-import { MOTION_BLUR_MAX_UV, RUSH_REACH_UV } from '../../vertexDefaults.js';
-import { OUTPUT_TRANSFORM_CODE } from '../../vertexDefaults.js';
+import { MOTION_BLUR_MAX_UV, OBJECT_BLUR_UNKEPT, RUSH_REACH_UV, clampMotionShare, } from '../../vertexDefaults.js';
+import { OUTPUT_TRANSFORM_CODE, forwardTransformCode } from '../../vertexDefaults.js';
+import { DEFAULT_FILMIC_CURVE, FILMIC_CLAMPED, FILMIC_CONSTANTS, FILMIC_WITHOUT_COMPOSITE, resolveFilmicCurve, } from '../../filmicCurve.js';
 import { deviceSnappedCellSize } from '../../textLayout.js';
 import { WindStreakRenderer } from '../../windStreakRenderer.js';
 import { InstancedBatch } from './instanced.js';
@@ -602,6 +612,10 @@ export class WebGL2Renderer {
     reflectionQueue = new ReflectionQueue();
     /** Built on the first frame that submits a surface, and never for a scene with none. */
     ssr = null;
+    /** The frame's materials' reflections, resolved; null where off. See `frameReflections.ts`. */
+    frameReflections;
+    /** Their two maps on the scene's framebuffer, null where they cannot be drawn. */
+    reflectionTargets;
     /** Said once where a reflection cannot be traced at all. */
     reflectionsRefused = false;
     /** Where the frame's camera stands, which is what gives a reconstructed normal its sign. */
@@ -672,6 +686,8 @@ export class WebGL2Renderer {
      * exactly as it asked to be and nothing about it changes.
      */
     exposure;
+    /** The `filmic` curve's eight constants, held until `setFilmicCurve` is called again. */
+    filmConstants = new Float32Array(FILMIC_CONSTANTS);
     /**
      * This frame's veil colour, and how much of it to composite. See `setFrameVeil`.
      *
@@ -873,8 +889,26 @@ export class WebGL2Renderer {
     warnedNoPointShadowArray = false;
     /** Said once, for the retired ambient dial. */
     warnedEnvironmentAmbient = false;
+    /** The overlay the draws wear, `uOverlay`: see `setSurfaceOverlay`. */
+    overlayFloats = new Float32Array(OVERLAY_FLOATS);
+    /** Its atlas, and the 2D copy of it bound where the refraction copy goes. */
+    overlayMaps = null;
+    overlayTexture = null;
+    /** Whether this device's lit stage has room for the overlay's vectors: asked once. */
+    overlayRoom = null;
+    warnedOverlayRoom = false;
+    warnedOverlayBlocks = false;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     probePassActive = false;
+    /**
+     * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
+     * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
+     */
+    capturePassActive = false;
+    /** Each capture's framebuffer, beside the texture a material binds. See `createSceneCapture`. */
+    captureTargets = new WeakMap();
+    /** Said once, where a driver refuses to draw into a capture. */
+    warnedCapture = false;
     /** Whether the bake under way lights its faces by the grid. `ProbeBakeOptions.bounce`. */
     probeBounce = false;
     /** The clip-control extension, or null where this context does not offer it. */
@@ -941,7 +975,8 @@ export class WebGL2Renderer {
      * the camera's matrix unchanged and multiplies nothing.
      */
     viewProjFor(camera) {
-        const scene = this.probePassActive
+        /* A capture's rows are flipped as a probe face's are, so it reads as an image does. */
+        const scene = this.probePassActive || this.capturePassActive
             ? cubeFaceProjection(this.cubeFaceViewProj, this.sceneMatrix(camera.viewProjection))
             : this.sceneMatrix(camera.viewProjection);
         /*
@@ -1491,6 +1526,8 @@ export class WebGL2Renderer {
      * call. `init` runs now rather than at the first frame, because building a pipeline in the
      * frame loop is the allocation the house rules are about.
      */
+    /** Each registered pass's declared reads, as a mask, resolved once at registration. */
+    passReads = new Map();
     registerPass(definition) {
         const handle = registerIn(this.passes, definition);
         /*
@@ -1510,6 +1547,8 @@ export class WebGL2Renderer {
         };
         if (definition.prepare !== undefined)
             this.preparingPasses++;
+        /* Resolved once: `maskOf` builds an array, and the frame path may not. */
+        this.passReads.set(handle, maskOf(...(definition.reads ?? [])));
         definition.init?.(this.passDevice);
         return handle;
     }
@@ -1561,10 +1600,28 @@ export class WebGL2Renderer {
             gl: this.gl,
             outputTransform: 0,
             outputExposure: 1,
+            sceneColor: null,
+            sceneDepth: null,
         };
         const context = this.passContext;
         context.outputTransform = this.gradeCode();
         context.outputExposure = this.gradeExposure();
+        /*
+         * The copies a pass declared it reads, taken here with everything drawn before it: colour
+         * afresh at each reading pass, as WebGPU's `takePassColour` does, so a full-screen effect drawn
+         * last reads the whole frame; depth afresh too, since a blit is the whole cost of either here.
+         * Not in a mirror, a probe's face or a capture, whose pictures are not the frame's.
+         */
+        const reads = this.passReads.get(handle) ?? 0;
+        const own = !this.reflectionPassActive && !this.probePassActive && !this.capturePassActive;
+        context.sceneColor =
+            own && (reads & COLOR_SNAPSHOT) !== 0
+                ? (this.sceneTarget?.snapshotColor(true) ?? null)
+                : null;
+        context.sceneDepth =
+            own && (reads & DEPTH_SNAPSHOT) !== 0
+                ? (this.sceneTarget?.snapshotDepth(true) ?? null)
+                : null;
         definition.draw(context);
     }
     /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
@@ -1572,6 +1629,7 @@ export class WebGL2Renderer {
         const definition = unregisterIn(this.passes, handle);
         if (definition?.prepare !== undefined)
             this.preparingPasses--;
+        this.passReads.delete(handle);
         if (definition !== undefined && this.passDevice !== null)
             definition.dispose?.(this.passDevice);
     }
@@ -1722,10 +1780,10 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D, this.clusterTexture);
         gl.uniform1i(u['uClusterTable'] ?? null, CLUSTER_TABLE_TEXTURE_UNIT);
         gl.uniform1i(u['uClustered'] ?? null, on ? 1 : 0);
-        if (!on)
-            return;
         /*
-         * The frustum, read off the projection rather than taken as a parameter.
+         * The frustum, read off the projection rather than taken as a parameter — **and with the view,
+         * written whether or not the lights are clustered**: a surface overlay's rim finds its place on
+         * the screen through the same two (`overlayScreen`).
          *
          * A perspective matrix carries `1 / tan(fovY/2)` at [5] and that over the aspect at [0], and
          * the near and far planes in [14] and [10]. Deriving them here means the binner and the shader
@@ -1743,6 +1801,8 @@ export class WebGL2Renderer {
         this.clusterFrustum[3] = aspect;
         gl.uniform4fv(u['uClusterFrustum'] ?? null, this.clusterFrustum);
         gl.uniformMatrix4fv(u['uView'] ?? null, false, camera.view);
+        if (!on)
+            return;
         this.clusterTable ??= createClusterTable();
         /* The rectangles past the fixed arm's go into the table. See `ClusterLightSet.areas`. */
         const lights = fillClusterLightSet(env, this.clusterLights, this.shadedAreaLights);
@@ -1816,6 +1876,11 @@ export class WebGL2Renderer {
         this.quality = resolveRenderQuality(qualityOptions);
         /* The grade this world asked for, until a frame says otherwise. See `setOutputExposure`. */
         this.exposure = this.quality.outputExposure;
+        resolveFilmicCurve(DEFAULT_FILMIC_CURVE, this.filmConstants);
+        if (this.quality.outputTransform === 'filmic' &&
+            !(this.quality.screenEffects && this.quality.hdrScene)) {
+            console.warn(FILMIC_WITHOUT_COMPOSITE);
+        }
         /*
          * Multisampling, but only when anything can use it.
          *
@@ -2074,6 +2139,29 @@ export class WebGL2Renderer {
         this.sceneTarget = this.quality.screenEffects
             ? new SceneTarget(gl, this.quality.sceneSamples, this.quality.hdrScene, this.quality.discardResolvedAttachments)
             : null;
+        /*
+         * The frame's materials' reflections, where the frame can carry them: scene light to swap the
+         * probe's share in, and one sample, which the trace's depth copy and both maps are. Said once
+         * where it cannot, in the words the other backend uses. See `frameReflections.ts`.
+         */
+        this.frameReflections = resolveFrameReflections(this.quality.screenSpaceReflections);
+        const reflectionsRefusal = this.frameReflections === null
+            ? null
+            : this.sceneTarget === null || !this.sceneTarget.keepsRange
+                ? 'the frame keeps no scene light to swap the probe in (`screenEffects` and `hdrScene`)'
+                : this.sceneTarget.sampleCount > 1
+                    ? 'a multisampled frame has no single depth or colour to march through'
+                    : null;
+        if (reflectionsRefusal !== null) {
+            console.warn(`WebGL2: ${frameReflectionsRefused(reflectionsRefusal)}`);
+        }
+        this.reflectionTargets =
+            this.frameReflections !== null && reflectionsRefusal === null
+                ? new ReflectionSurfaceTargets(gl)
+                : null;
+        /* The lit programs write the maps from the first frame they are rebuilt in. See `litOn`. */
+        if (this.reflectionTargets !== null)
+            this.askLit('REFLECTION_MAPS');
         /* Screen-space skin needs the composite to add into; without one it is pre-integrated, said once. */
         if (this.quality.skinScattering === 'screen-space' && this.sceneTarget === null) {
             console.warn("WebGL2: skinScattering 'screen-space' needs screenEffects to add into; skin is pre-integrated");
@@ -2545,6 +2633,76 @@ export class WebGL2Renderer {
     createLightmap(page) {
         return new SurfaceTexture(this.gl, lightmapTexels(page), { wrap: 'clamp', mipmap: false });
     }
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. Half floats where the frame keeps range, as a probe does.
+     */
+    createSceneCapture(width, height) {
+        const float = this.quality.hdrScene && this.gl.getExtension('EXT_color_buffer_float') !== null;
+        const texture = new SurfaceTexture(this.gl, sceneCaptureTexels(width, height, float), {
+            wrap: 'clamp',
+            mipmap: false,
+        });
+        this.captureTargets.set(texture, new GlSceneCaptureTarget(this.gl, texture, width, height, this.sceneTarget?.sampleCount ?? 1, float));
+        return texture;
+    }
+    /**
+     * Draw the scene into a capture from `camera`: `draw` is handed the camera, its matrices updated
+     * for the capture's shape, and submits the scene as it would to the screen. See `RendererApi`.
+     *
+     * **Radiance, as a probe bake stores it**: the output transform and exposure are held off for the
+     * pass, so the frame grades a screen showing it once. No temporal jitter, which a capture has no
+     * resolve to undo. Returns whether it drew: false for a texture that is not a capture, or one the
+     * driver will not draw into.
+     */
+    captureScene(capture, camera, clearColor, draw) {
+        if (this.contextLost)
+            return false;
+        const target = this.captureTargets.get(capture);
+        if (target === undefined)
+            return false;
+        if (!target.usable) {
+            if (!this.warnedCapture) {
+                this.warnedCapture = true;
+                console.warn('Renderer: this driver will not draw into a scene capture, so it keeps its clear. ' +
+                    'Nothing else is affected.');
+            }
+            return false;
+        }
+        camera.updateMatrices(target.width / target.height);
+        const { gl } = this;
+        const jittering = this.temporalJittering;
+        this.temporalJittering = false;
+        this.capturePassActive = true;
+        this.useFlatProgram();
+        gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, 0);
+        gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, 1);
+        this.materials.dirty();
+        target.begin(gl, clearColor, this.depthClear);
+        /*
+         * **Rows flipped, as a probe face's are.** A GL framebuffer's first row is its bottom and an
+         * image's is its top, so a capture drawn upright would be shown upside down by every material
+         * reading it as the image it is; `viewProjFor` negates clip y for the pass, and negating one axis
+         * reverses every triangle's winding, which the front face follows. WebGPU's rows already run
+         * the image's way.
+         */
+        gl.frontFace(gl.CW);
+        try {
+            draw(camera);
+        }
+        finally {
+            target.end(gl);
+            gl.frontFace(gl.CCW);
+            this.useFlatProgram();
+            gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.gradeCode());
+            gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.gradeExposure());
+            this.materials.dirty();
+            this.capturePassActive = false;
+            this.temporalJittering = jittering;
+            this.restoreViewport();
+        }
+        return true;
+    }
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -2561,11 +2719,18 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         texture.update(this.gl, source);
+        /* New pixels are a new copy for the overlay's slot: see `SurfaceTexture.flatLayer`. */
+        if (texture === this.overlayMaps)
+            this.bindOverlayMaps(texture);
     }
     disposeSurfaceTexture(texture) {
         if (this.contextLost)
             return;
+        if (texture === this.overlayMaps)
+            this.bindOverlayMaps(null);
         texture.dispose(this.gl);
+        this.captureTargets.get(texture)?.dispose(this.gl);
+        this.captureTargets.delete(texture);
     }
     /**
      * Choose the surface texture the following `drawMesh` calls sample, or `null` for none.
@@ -2768,7 +2933,7 @@ export class WebGL2Renderer {
         const model = material?.model;
         warnUnpagedLightmap(model, material?.modelMap);
         if (model?.kind === 'skin' && this.skinScatter !== null) {
-            this.skinScatter.setProfile(model.profile, model.scatterColor[0] * model.radius, model.scatterColor[1] * model.radius, model.scatterColor[2] * model.radius);
+            this.skinScatter.setProfile(model.profile, skinProfileDistance(model, 0), skinProfileDistance(model, 1), skinProfileDistance(model, 2));
         }
         /*
          * Written to every flat program, because material state persists across draws and a skinned
@@ -2892,8 +3057,13 @@ export class WebGL2Renderer {
         if (modelMap !== null)
             modelMap.bind(gl, MODEL_MAP_TEXTURE_UNIT);
         gl.uniform1i(u['uModelMap'] ?? null, MODEL_MAP_TEXTURE_UNIT);
-        packModel(material?.model ?? null, modelMap !== null, this.modelParams);
+        packModel(material?.model ?? null, modelMap !== null, this.modelParams, material?.physicalSpecular === true);
+        /* The first physical highlight asked for is when the lit programs start carrying one. */
+        if (material?.physicalSpecular === true)
+            this.askLit('PHYSICAL_SPECULAR');
         gl.uniform4fv(u['uModelParams'] ?? null, this.modelParams);
+        /* The draw's overlay, which a program born mid-pass must wear too: see `setSurfaceOverlay`. */
+        gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         /* The albedo's effects table, or the stand-in the shader reads as none. Before the early
            return, so a material with no albedo still leaves a complete texture on the unit. */
         if (albedo === null) {
@@ -2952,18 +3122,6 @@ export class WebGL2Renderer {
         gl.activeTexture(gl.TEXTURE0 + SURFACE_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     }
-    /**
-     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
-     *
-     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
-     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
-     * This stays as the override for the case that has no answer to state: an imported model
-     * arrives with no grain information at all, and a caller drawing one decides for it.
-     *
-     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
-     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
-     * leaves geometry that did not exactly as it is.
-     */
     /**
      * The ambient the following draws take, as nine spherical-harmonic coefficients of incoming
      * radiance — red, green and blue of each, twenty-seven numbers — or `null` for the frame's own:
@@ -2975,16 +3133,6 @@ export class WebGL2Renderer {
      * only — a glossy surface still reflects the probes — and it is pass state like the material,
      * which `bindMeshPass` clears, so a mirror or a probe bake drawn after does not inherit it.
      */
-    /**
-     * How much of the environment the following draws mirror, 0 to 1.
-     *
-     * Pass state beside the grain, and the counterpart to it: grain is a surface being uneven,
-     * this is a surface being smooth enough to carry an image. Polished paint, glass, chrome
-     * and still water want it; plaster and stone want none.
-     *
-     * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
-     * exactly as it did.
-     */
     setAmbientSH(coefficients) {
         if (this.contextLost)
             return;
@@ -2996,6 +3144,16 @@ export class WebGL2Renderer {
         }
         this.useFlatProgram();
     }
+    /**
+     * How much of the environment the following draws mirror, 0 to 1.
+     *
+     * Pass state beside the grain, and the counterpart to it: grain is a surface being uneven,
+     * this is a surface being smooth enough to carry an image. Polished paint, glass, chrome
+     * and still water want it; plaster and stone want none.
+     *
+     * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
+     * exactly as it did.
+     */
     setSurfaceReflectivity(amount) {
         if (this.contextLost)
             return;
@@ -3003,6 +3161,67 @@ export class WebGL2Renderer {
         this.environmentDials[1] = Math.min(1, Math.max(0, amount));
         this.writeFlatVector('uEnvironmentDials', this.environmentDials);
     }
+    /**
+     * The overlay the following draws wear — a rim of light, a dissolve, wrinkles by region — or null
+     * for none. Pass state, as the material is: `bindMeshPass` puts it back to none. See
+     * `surfaceOverlay.ts` for what it lays and `shaders/flat/overlay.ts` for how.
+     *
+     * **Refused, said once, where the lit stage has no room for it.** Fifteen vectors more than the
+     * program this device fits: counted from the source as `fitFlatProgram` counts, and on a device
+     * whose limit is the 256 an Adreno 740 reports, the eight-light build at 254 has none. The draws
+     * then wear nothing, which is the picture a game without the feature draws. Its atlas is bound as
+     * a 2D copy of its first layer, in the refraction copy's unit (`SurfaceTexture.flatLayer`); a
+     * compressed atlas has no copy and is read as none, also said once.
+     */
+    setSurfaceOverlay(overlay) {
+        if (this.contextLost)
+            return;
+        let wanted = overlay;
+        if (overlayLays(wanted) && !this.overlayFits()) {
+            if (!this.warnedOverlayRoom) {
+                this.warnedOverlayRoom = true;
+                console.warn('Renderer: setSurfaceOverlay is refused on this device. The overlay takes fifteen ' +
+                    'fragment uniform vectors and the lit shader already uses all but ' +
+                    `${this.overlayRoomLeft()} of the ${this.fragmentVectorLimit()} this GPU offers; ` +
+                    'draws wear no overlay. A lower `maxLights` makes the room, or WebGPU has it.');
+            }
+            wanted = null;
+        }
+        packSurfaceOverlay(wanted, this.overlayFloats);
+        if (overlayLays(wanted))
+            this.askLit('SURFACE_OVERLAY');
+        this.materials.dirty();
+        this.writeFlatVector('uOverlay', this.overlayFloats);
+        this.bindOverlayMaps((wanted?.maps ?? null));
+    }
+    /** The overlay's atlas into the refraction copy's unit, as a 2D copy, or the empty texture. */
+    bindOverlayMaps(maps) {
+        const { gl } = this;
+        this.overlayMaps = maps;
+        this.overlayTexture = maps === null ? null : maps.flatLayer(gl);
+        if (maps !== null && this.overlayTexture === null && !this.warnedOverlayBlocks) {
+            this.warnedOverlayBlocks = true;
+            console.warn("Renderer: a surface overlay's maps are a compressed texture, which WebGL2 cannot copy " +
+                'into the 2D image the lit stage reads them from. The overlay is drawn without its ' +
+                'images; upload the atlas from an image instead.');
+        }
+        gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, this.overlayTexture ?? this.emptyTexture2D);
+    }
+    /** The most fragment uniform vectors this GPU offers a stage. */
+    fragmentVectorLimit() {
+        return this.gl.getParameter(this.gl.MAX_FRAGMENT_UNIFORM_VECTORS);
+    }
+    /** What the lit shader at this renderer's budget leaves of the limit, with no overlay. */
+    overlayRoomLeft() {
+        return (this.fragmentVectorLimit() - countUniformVectors(this.flatFragAt(this.lightBudget, false)));
+    }
+    /** Whether the lit shader with the overlay compiled in fits this GPU: counted once. */
+    overlayFits() {
+        this.overlayRoom ??=
+            countUniformVectors(this.flatFragAt(this.lightBudget, true)) <= this.fragmentVectorLimit();
+        return this.overlayRoom;
+    }
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
      *
@@ -3043,6 +3262,18 @@ export class WebGL2Renderer {
         console.warn('Renderer: setEnvironmentAmbient no longer does anything. A baked probe now lights a ' +
             'surface through projected irradiance, and there is nothing left to tune.');
     }
+    /**
+     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     *
+     * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
+     * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
+     * This stays as the override for the case that has no answer to state: an imported model
+     * arrives with no grain information at all, and a caller drawing one decides for it.
+     *
+     * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
+     * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
+     * leaves geometry that did not exactly as it is.
+     */
     setSurfaceGrain(amount) {
         if (this.contextLost)
             return;
@@ -3409,10 +3640,15 @@ export class WebGL2Renderer {
             gl.enable(gl.SAMPLE_ALPHA_TO_COVERAGE);
         if (ditheredBlend)
             gl.uniform4fv(u['uCutout'] ?? null, this.cutoutUniform(this.currentMaterial, true));
+        const keeps = !blend && this.reflectionKeeps();
+        if (keeps)
+            this.reflectionTargets?.on();
         if (culling && cullsInstances(count, mesh.indexCount))
             batch.drawCulled(gl, data, this.frustum);
         else
             batch.draw(gl, count);
+        if (keeps)
+            this.reflectionTargets?.off();
         if (coverage)
             gl.disable(gl.SAMPLE_ALPHA_TO_COVERAGE);
         if (ditheredBlend)
@@ -3464,7 +3700,7 @@ export class WebGL2Renderer {
         const glassy = resolveGlass(options.glass, this.glassScratch);
         if (refraction <= 0 && !glassy)
             return false;
-        if (this.probePassActive || this.reflectionPassActive)
+        if (this.probePassActive || this.reflectionPassActive || this.capturePassActive)
             return false;
         const snapshot = this.sceneTarget?.snapshotColor(false, glassy) ?? null;
         if (snapshot === null)
@@ -3483,7 +3719,8 @@ export class WebGL2Renderer {
         const { gl } = this;
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
         gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        /* The overlay's atlas, where one is held: it shares the unit. See `setSurfaceOverlay`. */
+        gl.bindTexture(gl.TEXTURE_2D, this.overlayTexture ?? this.emptyTexture2D);
     }
     disposeMesh(mesh) {
         /*
@@ -3694,7 +3931,7 @@ export class WebGL2Renderer {
      */
     gradeCode() {
         return this.sceneTarget === null || !this.quality.hdrScene
-            ? OUTPUT_TRANSFORM_CODE[this.quality.outputTransform]
+            ? forwardTransformCode(this.quality.outputTransform)
             : 0;
     }
     gradeExposure() {
@@ -3763,6 +4000,20 @@ export class WebGL2Renderer {
     createParticles(capacity, options) {
         return new ParticleBatch(this.gl, capacity, options);
     }
+    /**
+     * Particles a caller's own compute wrote: WebGPU's alone, since this backend has no compute stage
+     * to have written them (`computeSupported`). Said once, and nothing is drawn.
+     */
+    drawDeviceParticles(_batch, _particles, _camera, _env, _timeSeconds) {
+        if (this.warnedDeviceParticles)
+            return;
+        this.warnedDeviceParticles = true;
+        console.warn('Renderer: drawDeviceParticles draws particles a compute shader wrote, and WebGL2 has no ' +
+            'compute stage, so nothing is drawn. Check `computeSupported`, and draw a pool with ' +
+            '`drawParticles` where it is false.');
+    }
+    /** Said once: see `drawDeviceParticles`. */
+    warnedDeviceParticles = false;
     /**
      * Draw a live particle pool.
      *
@@ -3820,7 +4071,10 @@ export class WebGL2Renderer {
         const u = batch.uniforms;
         const scene = this.sceneTarget;
         let depth = null;
-        if (batch.softDepth > 0 && !this.reflectionPassActive && !this.probePassActive) {
+        if (batch.softDepth > 0 &&
+            !this.reflectionPassActive &&
+            !this.probePassActive &&
+            !this.capturePassActive) {
             depth = scene?.snapshotDepth(true) ?? null;
             if (depth === null && !this.warnedSpriteDepth) {
                 this.warnedSpriteDepth = true;
@@ -4680,7 +4934,7 @@ export class WebGL2Renderer {
      * throws a sentence with the device's numbers in it rather than a bare driver string.
      */
     /** The lit fragment source this renderer's profile compiles, at a light budget. */
-    flatFragAt(budget) {
+    flatFragAt(budget, overlay = this.litOn.SURFACE_OVERLAY) {
         return flatFrag({
             pointShadows: this.quality.pointShadows,
             directionalShadows: this.quality.directionalShadows,
@@ -4692,6 +4946,9 @@ export class WebGL2Renderer {
             lightFixtures: this.litOn.LIGHT_FIXTURES,
             surfaceEffects: this.litOn.SURFACE_EFFECTS,
             driftLight: this.litOn.DRIFT_LIGHT,
+            physicalSpecular: this.litOn.PHYSICAL_SPECULAR,
+            surfaceOverlay: overlay,
+            reflectionMaps: this.litOn.REFLECTION_MAPS,
             maxLights: budget.maxLights,
             maxAreaLights: budget.maxAreaLights,
         });
@@ -5363,10 +5620,20 @@ export class WebGL2Renderer {
      * Set before `beginFrame` and held until changed, like `setSpeedRush`, which it sits
      * beside for the same reason: both describe how the finished image is presented rather
      * than anything in the world.
+     *
+     * `maxShare` is the longest smear, as a share of the frame (0.03 unless given, at most half): a
+     * fast turn softens the frame rather than erasing it. **Each drawn object's own motion is
+     * followed only under a reconstruction on WebGPU**, which draws the motion target it reads; here,
+     * and on WebGPU without one, the camera's motion alone smears the frame, and a draw that names
+     * where it was last frame is told so once.
      */
-    setCameraMotionBlur(scale) {
+    setCameraMotionBlur(scale, maxShare = MOTION_BLUR_MAX_UV) {
         this.motionBlurScale = Math.min(Math.max(scale, 0), 1);
+        this.motionBlurMax = clampMotionShare(maxShare);
     }
+    /** The longest smear, as a share of the frame. See `setCameraMotionBlur`. */
+    motionBlurMax = MOTION_BLUR_MAX_UV;
+    warnedObjectBlur = false;
     /**
      * The camera has cut: this frame is a new shot, not the next moment of the last one.
      *
@@ -5566,6 +5833,42 @@ export class WebGL2Renderer {
             ? Math.max(exposure, 1e-3)
             : this.quality.outputExposure;
     }
+    /**
+     * The `filmic` curve this and every later frame is graded through, until it is set again: a
+     * grading volume's five numbers, solved once here into the constants the resolve reads. Ignored
+     * unless `outputTransform` is `filmic`. A number out of range is clamped into it and said once,
+     * since a frame loop must not throw. See `filmicCurve.ts`.
+     */
+    setFilmicCurve(curve) {
+        if (resolveFilmicCurve(curve, this.filmConstants) && !this.warnedFilmClamped) {
+            this.warnedFilmClamped = true;
+            console.warn(FILMIC_CLAMPED);
+        }
+    }
+    warnedFilmClamped = false;
+    /**
+     * The range the frame goes out in: `'high'` where the profile asked for `highDynamicRange`, the
+     * frame holds light past white and the display shows it — on WebGPU — and `'standard'` otherwise.
+     * **Always standard here**: this backend draws into a canvas of eight bits a channel, which has
+     * nothing above white to show. Typed as the question rather than this backend's answer, because
+     * the shared surface is derived from this class.
+     */
+    displayRange = 'standard';
+    /** Why it is that range, in words, for a game choosing its look and for a bug report. */
+    get displayRangeReason() {
+        return this.quality.highDynamicRange
+            ? 'WebGL2 draws into an eight-bit canvas, which has no range above white'
+            : 'highDynamicRange was not asked for';
+    }
+    /**
+     * How bright paper white and the display's peak are, in one unit, held until changed: their
+     * ratio is how far above white the highlights may run where `displayRange` is `'high'`, and
+     * nothing changes where it is standard, which is always here.
+     */
+    setDisplayLuminance(paperWhite, peak) {
+        void paperWhite;
+        void peak;
+    }
     /**
      * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
      *
@@ -5652,6 +5955,20 @@ export class WebGL2Renderer {
         }
         this.sceneTarget.setVignette(strength);
     }
+    /**
+     * The lens's colour fringe, held until changed: `intensity` is a percentage, 0 is none, and red
+     * and green are pulled toward the centre by their wavelength's distance from blue, growing from
+     * `start` — a share of the half-frame, 0 the centre — to the whole of it at the edge. Applied to
+     * scene light at the composite's first read. Needs `screenEffects`, and says so once rather than
+     * doing nothing. See `shaders/fringe.ts`.
+     */
+    setChromaticAberration(intensity, start = 0) {
+        if (this.sceneTarget === null) {
+            this.warnLookWithoutComposite(intensity);
+            return;
+        }
+        this.sceneTarget.setChromaticAberration(intensity, start);
+    }
     /**
      * Film grain, held until changed: an amplitude in display values (0 is none, 0.03 is a fine
      * grain) and this frame's seed. **The seed is the caller's**, because the engine takes time from
@@ -5832,6 +6149,8 @@ export class WebGL2Renderer {
     beginFrame(clearColor) {
         if (this.contextLost)
             return;
+        /* One frame of the jitter's sequence however many times the frame binds its camera. */
+        this.temporalHistory.nextFrame();
         this.skinScattered = false;
         this.skinScatter?.reset();
         if (this.litAsked) {
@@ -5898,6 +6217,8 @@ export class WebGL2Renderer {
             }
         }
         this.sceneTarget?.begin(this.canvas.width, this.canvas.height);
+        /* The materials' maps on the scene's framebuffer, cleared and disabled: `reflectionKeeps`. */
+        this.reflectionTargets?.begin(this.canvas.width, this.canvas.height);
         gl.clearColor(clearColor[0], clearColor[1], clearColor[2], 1);
         gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
     }
@@ -5947,7 +6268,7 @@ export class WebGL2Renderer {
                     motion = {
                         reprojection: this.reprojection,
                         strength: blur,
-                        max: MOTION_BLUR_MAX_UV,
+                        max: this.motionBlurMax,
                     };
                 }
             }
@@ -6027,7 +6348,11 @@ export class WebGL2Renderer {
             : undefined;
         /* The grade travels to the resolve only where the mesh pass gave it up. See `bindMeshPass`. */
         const lateGrade = this.quality.hdrScene
-            ? { transform: OUTPUT_TRANSFORM_CODE[this.quality.outputTransform], exposure: this.exposure }
+            ? {
+                transform: OUTPUT_TRANSFORM_CODE[this.quality.outputTransform] ?? 0,
+                exposure: this.exposure,
+                film: this.filmConstants,
+            }
             : { transform: 0, exposure: 1 };
         /*
          * Depth of field, on the same ceiling-and-dial split as bloom above: `depthOfField` decides
@@ -6089,6 +6414,30 @@ export class WebGL2Renderer {
          * drawn over a reflective floor rather than under it, and before the post chain so bloom and
          * the grade see a reflection exactly as they would see any other part of the picture.
          */
+        /*
+         * **The frame's materials' reflections first**, on the same terms: every pixel the opaque lit
+         * draws left a reflection for, marched and swapped for the probe's share. The maps leave the
+         * scene's framebuffer before the resolve draws into it while sampling them.
+         */
+        const reflectionTargets = this.reflectionTargets;
+        const probeMap = reflectionTargets?.probeTexture ?? null;
+        const tintMap = reflectionTargets?.tintTexture ?? null;
+        if (reflectionTargets !== null &&
+            this.frameReflections !== null &&
+            probeMap !== null &&
+            tintMap !== null &&
+            this.frameViewProj !== null &&
+            this.sceneTarget !== null) {
+            const scene = this.sceneTarget.colorAttachment();
+            const depth = this.sceneTarget.snapshotDepth(true);
+            if (scene !== null && depth !== null) {
+                this.ssr ??= new SsrPass(this.gl, this.sceneTarget.keepsRange);
+                this.ssr.traceMaterials(scene, depth, probeMap, tintMap, this.frameViewProj, this.frameEye, this.canvas.width, this.canvas.height, REFLECTION_EDGE_FADE, this.frameReflections);
+                this.sceneTarget.bind();
+                reflectionTargets.detach();
+                this.ssr.resolveMaterials(probeMap, tintMap, this.canvas.width, this.canvas.height, this.frameReflections);
+            }
+        }
         if (this.reflectionQueue.length > 0 && this.frameViewProj !== null) {
             const scene = this.sceneTarget?.colorAttachment() ?? null;
             const depth = this.sceneTarget?.snapshotDepth(true) ?? null;
@@ -6328,7 +6677,10 @@ export class WebGL2Renderer {
          */
         if (this.framePresented)
             this.temporalJittering = false;
-        if (!this.reflectionPassActive && !this.probePassActive && !this.framePresented) {
+        if (!this.reflectionPassActive &&
+            !this.probePassActive &&
+            !this.capturePassActive &&
+            !this.framePresented) {
             this.frameViewProj = camera.viewProjection;
             /* Copied rather than referenced: a caller moves its camera in place, and the decal pass
                reads this at the end of the frame. */
@@ -6423,6 +6775,10 @@ export class WebGL2Renderer {
         this.materialHasMaps = false;
         this.currentMaterial = null;
         this.currentSurfaceTexture = null;
+        /* Nor an overlay: the atlas's unit is given the empty texture with the refraction copy's. */
+        this.overlayFloats.fill(0);
+        this.overlayMaps = null;
+        this.overlayTexture = null;
         /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
         this.ambientSH.fill(0);
         /* No reflection and an environment at its own brightness; the emission the world asks for. */
@@ -6548,8 +6904,10 @@ export class WebGL2Renderer {
          * unless a draw sets the strength above zero.
          */
         gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D, this.overlayTexture ?? this.emptyTexture2D);
         gl.uniform1i(u['uRefractScene'] ?? null, REFRACT_SCENE_TEXTURE_UNIT);
+        /* The draws' overlay, none at a pass's start, and its atlas above: see `setSurfaceOverlay`. */
+        gl.uniform4fv(u['uOverlay'] ?? null, this.overlayFloats);
         /* Neither refracting nor glass, which is every draw that does not say otherwise. See
            `bindSeeThrough` for the four numbers in the one vector. */
         gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);
@@ -6928,9 +7286,16 @@ export class WebGL2Renderer {
      * here, so there is no motion target for this to be written into, and a mover passed here is
      * neither read nor advanced.
      */
-    _previousModel = null) {
+    previousModel = null) {
         if (this.contextLost)
             return;
+        /* A mover's own motion is not blurred here: see `setCameraMotionBlur`. Said once. */
+        if (previousModel !== null &&
+            !this.warnedObjectBlur &&
+            this.quality.cameraMotionBlur * this.motionBlurScale > 0) {
+            this.warnedObjectBlur = true;
+            console.warn(OBJECT_BLUR_UNKEPT);
+        }
         /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
            and `Mesh.indexCount`. */
         if (!mesh.complete || mesh.indexCount === 0)
@@ -6963,7 +7328,13 @@ export class WebGL2Renderer {
          * light and its colour, each into the blur's own target.
          */
         const splits = this.skinSplits();
+        /* An opaque lit draw into the frame writes its material's reflection too: see `reflectionKeeps`. */
+        const keeps = this.reflectionKeeps();
+        if (keeps)
+            this.reflectionTargets?.on();
         this.drawMeshHalf(mesh, model, depthLayer, tint, splits ? 'scene' : 'whole');
+        if (keeps)
+            this.reflectionTargets?.off();
         if (splits && this.skinScatter !== null) {
             this.skinScatter.begin();
             this.drawMeshHalf(mesh, model, depthLayer, tint, 'diffuse');
@@ -6977,6 +7348,18 @@ export class WebGL2Renderer {
      * skin yet, this is the frame's own picture — not a mirror's or a probe's, nor an overlay after
      * the frame — and the blur's target can be had.
      */
+    /**
+     * Whether a draw now is the frame's own, opaque and lit, and so writes the two maps beside its
+     * colour: not a mirror's, a probe's or a capture's, whose framebuffers have no maps, and not after
+     * the frame. See `reflectionSurfaceTargets.ts`.
+     */
+    reflectionKeeps() {
+        return (this.reflectionTargets !== null &&
+            !this.reflectionPassActive &&
+            !this.probePassActive &&
+            !this.capturePassActive &&
+            !this.framePresented);
+    }
     skinSplits() {
         const skin = this.skinScatter;
         const scene = this.sceneTarget;
@@ -6986,6 +7369,7 @@ export class WebGL2Renderer {
             !this.skinScattered &&
             !this.reflectionPassActive &&
             !this.probePassActive &&
+            !this.capturePassActive &&
             !this.framePresented &&
             skin.ready(scene));
     }
@@ -7002,11 +7386,19 @@ export class WebGL2Renderer {
         const projection = this.frameProjection;
         if (skin === null || scene === null || this.skinScattered)
             return;
+        /*
+         * **Not the frame's picture, so not the frame's moment**: a blended draw in a mirror, a probe
+         * bake or a scene capture lands over none of the frame's skin. Latching there switched the
+         * spread off for the frame, so a capture with a glowing sign in it left every face drawn after
+         * it flat. `scripts/capture-check.mjs`.
+         */
+        if (this.reflectionPassActive || this.probePassActive || this.capturePassActive)
+            return;
         /* Latched whether or not skin was drawn: a skin drawn after this point is the whole surface. */
         this.skinScattered = true;
         if (!skin.pending)
             return;
-        if (this.reflectionPassActive || this.probePassActive || projection === null)
+        if (projection === null)
             return;
         const depth = scene.snapshotDepth(true);
         mat4.invert(this.skinInverseProjection, projection);