@driftengine/core 4.8.5 → 4.8.7

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

@@ -22,7 +22,7 @@ import { batchBoxVisible, cullsInstances } from '../../instanceCull.js';
 import { OcclusionBuffer } from '../../occlusion.js';
 import { boundsVisible } from '../../visibility.js';
 import { createPassRegistry, drainRegistry, passAt, registerIn, unregisterIn } from '../../pass.js';
-import { TABLE_HEIGHT, TABLE_WIDTH, buildLightClusters, clusteredMode, createClusterLightSet, createClusterTable, fillClusterLightSet, } from '../../clusteredLights.js';
+import { TABLE_HEIGHT, TABLE_WIDTH, buildLightClusters, clusteredMode, createClusterLightSet, createClusterTable, clusteredLightTotal, fillClusterLightSet, lightChannelsOf, } from '../../clusteredLights.js';
 import { clamp } from '../../../math/scalar.js';
 import { attachContextLoss } from '../../contextLoss.js';
 import { isWeakGpuFamily, webgl2RendererName } from '../../gpuCapability.js';
@@ -32,7 +32,8 @@ import { FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../unif
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
-import { bloomProfileWarning, bloomThresholdOf } from '../../bloomChain.js';
+import { AMBIENT_SH_FLOATS, packAmbientSH } from '../../ambientHarmonics.js';
+import { bloomProfileWarning, bloomThresholdOf, defaultBloomResponse, resolveBloomResponse, } from '../../bloomChain.js';
 import { createEmptyTexture2D, createEmptyTexture2DArray, createEmptyTexture3D, createEmptyTextureCube, } from '../../emptyTexture.js';
 import { LightField } from '../../driftLight/lightField.js';
 import { WorldLightField } from '../../driftLight/worldLightField.js';
@@ -40,8 +41,9 @@ 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 { modelBound, skinHalfBound } from '../../shaders/flat/models.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';
 import { CLOTH_BINDING_TEXTURE_UNIT, CLOTH_PARTICLES_TEXTURE_UNIT, CLOTH_REST_TEXTURE_UNIT, } from '../../lightBudget.js';
 import { SkinPaletteTexture } from './skinPaletteTexture.js';
@@ -79,11 +81,13 @@ import { GlassTintPrograms } from './glassTintPrograms.js';
 import { FACE_COUNT, PointShadowMap } from '../../pointShadowMap.js';
 import { createResolvedPointShadows, DEFAULT_SOURCE_RADIUS } from '../../pointShadowImage.js';
 import { createBakeScratch, runPointShadowBakes, selectCastingLights, } from '../../pointShadowBudget.js';
-import { DIRECTIONAL_SHADOW_UNITS, SUN_GLASS_TINT_TEXTURE_UNIT, POINT_GLASS_TINT_TEXTURE_UNIT, LIVE_POINT_SHADOW_MAPS, MAX_POINT_LIGHTS, NORMAL_TEXTURE_UNIT, ORM_TEXTURE_UNIT, POINT_SHADOW_POOL, POINT_SHADOW_UNITS, CLUSTER_TABLE_TEXTURE_UNIT, EMISSIVE_TEXTURE_UNIT, ENVIRONMENT_TEXTURE_UNIT, SURFACE_TEXTURE_UNIT, bindPointLights, REFRACT_SCENE_TEXTURE_UNIT, DRIFT_LIGHT_ATLAS_TEXTURE_UNIT, DRIFT_LIGHT_INDEX_TEXTURE_UNIT, COOKIE_TILE, FIXTURE_ATLAS_TEXTURE_UNIT, SURFACE_EFFECTS_TEXTURE_UNIT, bindAreaLights, bindAreaShadows, openCones, } from '../../lightBudget.js';
+import { DIRECTIONAL_SHADOW_UNITS, SUN_GLASS_TINT_TEXTURE_UNIT, POINT_GLASS_TINT_TEXTURE_UNIT, LIVE_POINT_SHADOW_MAPS, MAX_POINT_LIGHTS, NORMAL_TEXTURE_UNIT, ORM_TEXTURE_UNIT, POINT_SHADOW_POOL, POINT_SHADOW_UNITS, CLUSTER_TABLE_TEXTURE_UNIT, EMISSIVE_TEXTURE_UNIT, ENVIRONMENT_TEXTURE_UNIT, SURFACE_TEXTURE_UNIT, bindPointLights, REFRACT_SCENE_TEXTURE_UNIT, DRIFT_LIGHT_ATLAS_TEXTURE_UNIT, DRIFT_LIGHT_INDEX_TEXTURE_UNIT, COOKIE_TILE, FIXTURE_ATLAS_TEXTURE_UNIT, SURFACE_EFFECTS_TEXTURE_UNIT, bindAreaLights, bindAreaShadows, openCones, PARTICLE_DEPTH_UNIT, } from '../../lightBudget.js';
 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';
@@ -180,6 +184,8 @@ export function createEnvironment(overrides = {}) {
         lightIesAxes: new Float32Array(MAX_POINT_LIGHTS * 3),
         /* −1, because tile 0 is a real cookie and no light here has asked for one. */
         lightCookies: new Float32Array(MAX_POINT_LIGHTS).fill(-1),
+        /* Channel 1, the default every surface is on, so every light lights everything. */
+        lightChannels: new Float32Array(MAX_POINT_LIGHTS).fill(1),
         /* None, so the shader's loop breaks before it reads anything. */
         areaLights: null,
         activeLightWorldIndices: new Int32Array(MAX_POINT_LIGHTS).fill(-1),
@@ -257,6 +263,8 @@ const IDENTITY_MAT4 = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
  */
 export { MAX_DEPTH_LAYER } from '../../depthConvention.js';
 /** The identity tint, handed back after any draw that asked for one. See `drawMesh`. */
+/** The far corner of no highlight box: what an environment that names none reads. */
+const NO_HIGHLIGHT = [0, 0, 0];
 const WHITE_TINT = new Float32Array([1, 1, 1]);
 /** The lit stage's clip plane when there is no mirror: zero, which clips nothing. */
 const NO_CLIP_PLANE = new Float32Array(4);
@@ -640,6 +648,23 @@ export class WebGL2Renderer {
     motionBlurScale = 1;
     /** How much of the bloom ceiling this frame takes. See `setBloom`. */
     bloomScale = 1;
+    /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
+    ambientSH = new Float32Array(AMBIENT_SH_FLOATS);
+    /** Scratch for a sprite's depth conversion, so a particle draw allocates nothing. */
+    spriteInverseProjection = mat4.create();
+    /** Said once: a sprite asked for a soft edge where no depth copy could be had. */
+    warnedSpriteDepth = false;
+    /** Said once: more rectangles than the fixed arm shades, and no froxel table for the rest. */
+    warnedAreaOverflow = false;
+    /**
+     * `uEnvironmentDials` as it stands: which chain the probe holds, the reflectivity, the gain. One
+     * vector on the device, so written whole, and kept here so a setter moving one keeps the others.
+     */
+    environmentDials = new Float32Array(3);
+    /** `uEmission` as it stands: the emissive gain and the night factor. */
+    emission = new Float32Array([1, 0]);
+    /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
+    bloomResponse = defaultBloomResponse();
     /** In scene units, once `setBloom` has moved it; null reads the profile's. */
     bloomThresholdSet = null;
     /**
@@ -852,6 +877,15 @@ export class WebGL2Renderer {
     warnedEnvironmentAmbient = 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. */
@@ -918,7 +952,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);
         /*
@@ -1675,9 +1710,7 @@ export class WebGL2Renderer {
         gl.activeTexture(gl.TEXTURE0 + FIXTURE_ATLAS_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D, this.fixtureTexture);
         gl.uniform1i(u['uFixtureAtlas'] ?? null, FIXTURE_ATLAS_TEXTURE_UNIT);
-        gl.uniform1f(u['uIesAtlasRows'] ?? null, this.iesRows);
-        gl.uniform1f(u['uIesPlaneCount'] ?? null, this.iesPlanes);
-        gl.uniform1f(u['uCookieTiles'] ?? null, this.cookieTiles);
+        gl.uniform3f(u['uFixtureShape'] ?? null, this.iesRows, this.iesPlanes, this.cookieTiles);
         gl.activeTexture(gl.TEXTURE0);
     }
     bindClusters(u, camera, env) {
@@ -1723,7 +1756,8 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uClusterFrustum'] ?? null, this.clusterFrustum);
         gl.uniformMatrix4fv(u['uView'] ?? null, false, camera.view);
         this.clusterTable ??= createClusterTable();
-        const lights = fillClusterLightSet(env, this.clusterLights);
+        /* The rectangles past the fixed arm's go into the table. See `ClusterLightSet.areas`. */
+        const lights = fillClusterLightSet(env, this.clusterLights, this.shadedAreaLights);
         /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
         const shadowSlots = this.quality.pointShadows ? this.lightBudget.maxLights : 0;
         buildLightClusters(lights, camera.view, near, far, tanHalfFovY, aspect, this.clusterTable, 
@@ -1735,7 +1769,7 @@ export class WebGL2Renderer {
          * guards the read as well, for a build that reaches it another way.
          */
         shadowSlots);
-        gl.uniform1i(u['uClustered'] ?? null, clusteredMode(lights, lights.count, shadowSlots));
+        gl.uniform1i(u['uClustered'] ?? null, clusteredMode(lights, clusteredLightTotal(lights), shadowSlots));
         gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, TABLE_WIDTH, TABLE_HEIGHT, gl.RGBA_INTEGER, gl.UNSIGNED_INT, this.clusterTable);
     }
     /**
@@ -2340,8 +2374,9 @@ export class WebGL2Renderer {
          * one. Measured on hardware: WebGL2 drew neither the bend nor the bulge while WebGPU drew
          * both, which is the two-backend comparison doing exactly what it is for.
          */
-        this.warmVariants(data);
-        return new Mesh(this.gl, data, options.dynamic === true);
+        const drawn = withLightmapUvs(data);
+        this.warmVariants(drawn);
+        return new Mesh(this.gl, drawn, options.dynamic === true);
     }
     /**
      * Geometry in, handle out — but the geometry lands over as many frames as the caller gives it.
@@ -2353,8 +2388,9 @@ export class WebGL2Renderer {
      * the signal that it was abandoned.
      */
     createMeshIncremental(data, options = {}) {
-        this.warmVariants(data);
-        const { mesh, upload } = createMeshIncremental(this.gl, data, options.dynamic === true);
+        const drawn = withLightmapUvs(data);
+        this.warmVariants(drawn);
+        const { mesh, upload } = createMeshIncremental(this.gl, drawn, options.dynamic === true);
         return {
             mesh,
             upload: {
@@ -2517,6 +2553,80 @@ export class WebGL2Renderer {
     createSurfaceTextureArray(sources, options = {}) {
         return new SurfaceTexture(this.gl, sources, options, this.compressedFormats);
     }
+    /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
+    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.
      *
@@ -2538,6 +2648,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         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.
@@ -2590,7 +2702,7 @@ export class WebGL2Renderer {
             return held;
         const { gl } = this;
         const label = `flat.${variant}.${kind}.${half}`;
-        const program = compileProgram(gl, litVertexOf(variant), skinHalfBound(modelBound(this.flatFragSource, kind), half), label);
+        const program = compileProgram(gl, modelVertexOf(variant, kind), skinHalfBound(modelBound(this.flatFragSource, kind), half), label);
         const made = { program, uniforms: uniformLocations(gl, program, label) };
         this.modelFlat.set(key, made);
         this.flatTargets.push(made);
@@ -2738,8 +2850,9 @@ export class WebGL2Renderer {
         this.currentMaterial = material;
         /* What the blur spreads this skin by: the last material to name a profile says. */
         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
@@ -2773,7 +2886,8 @@ export class WebGL2Renderer {
         v[0] = material?.cutout ?? 0;
         v[1] = CUTOUT_RESOLVE_CODE[this.cutoutResolveNow(material, translucent)];
         v[2] = this.cutoutFrame;
-        v[3] = 0;
+        /* The material's lighting channels, which the lamps' are compared with. See `uCutout`. */
+        v[3] = lightChannelsOf(material?.lightChannels);
         return v;
     }
     /**
@@ -2862,7 +2976,10 @@ 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 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. */
@@ -2884,6 +3001,8 @@ export class WebGL2Renderer {
             gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
             this.materialFlags[0] = 0;
             gl.uniform4iv(u['uMaterialFlags'] ?? null, this.materialFlags);
+            /* No image to cut, and the channels all the same: a material needs no albedo to name them. */
+            gl.uniform4f(u['uCutout'] ?? null, 0, 0, 0, lightChannelsOf(material?.lightChannels));
             return;
         }
         albedo.bind(gl, SURFACE_TEXTURE_UNIT);
@@ -2921,17 +3040,27 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     }
     /**
-     * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+     * 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:
+     * the sky's gradient, or the probes'. See `ambientHarmonics.ts` for the basis and the axes.
      *
-     * 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.
+     * **For a thing lit by where it stands**: a consumer sampling a stage's baked volume of indirect
+     * light at a character every frame sets the result around that character's draws, and the
+     * character takes the light of its spot rather than the frame's. It replaces the diffuse ambient
+     * 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.
      */
+    setAmbientSH(coefficients) {
+        if (this.contextLost)
+            return;
+        packAmbientSH(coefficients, this.ambientSH);
+        this.materials.dirty();
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.gl.uniform4fv(target.uniforms['uAmbientSH[0]'] ?? null, this.ambientSH);
+        }
+        this.useFlatProgram();
+    }
     /**
      * How much of the environment the following draws mirror, 0 to 1.
      *
@@ -2946,7 +3075,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.writeFlatFloat('uReflectivity', Math.min(1, Math.max(0, amount)));
+        this.environmentDials[1] = Math.min(1, Math.max(0, amount));
+        this.writeFlatVector('uEnvironmentDials', this.environmentDials);
     }
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
@@ -2964,7 +3094,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.writeFlatFloat('uEnvironmentGain', Math.max(0, gain));
+        this.environmentDials[2] = Math.max(0, gain);
+        this.writeFlatVector('uEnvironmentDials', this.environmentDials);
     }
     /**
      * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
@@ -2987,6 +3118,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;
@@ -3031,6 +3174,20 @@ export class WebGL2Renderer {
         }
         this.useFlatProgram();
     }
+    /** A vector of material state, two to four floats, into every flat program. */
+    writeFlatVector(name, value) {
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            const at = target.uniforms[name] ?? null;
+            if (value.length === 2)
+                this.gl.uniform2fv(at, value);
+            else if (value.length === 3)
+                this.gl.uniform3fv(at, value);
+            else
+                this.gl.uniform4fv(at, value);
+        }
+        this.useFlatProgram();
+    }
     /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
     writeFlatInt(name, value) {
         for (const target of this.flatTargets) {
@@ -3094,8 +3251,13 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.writeFlatFloat('uRelief', Math.min(1, Math.max(0, amount)));
-        this.writeFlatFloat('uReliefCycles', Math.max(0.01, cyclesPerMetre));
+        const strength = Math.min(1, Math.max(0, amount));
+        const cycles = Math.max(0.01, cyclesPerMetre);
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.gl.uniform2f(target.uniforms['uRelief'] ?? null, strength, cycles);
+        }
+        this.useFlatProgram();
     }
     /**
      * How hard the bound surface texture's own luminance turns the shading normal, 0 for not at all.
@@ -3153,7 +3315,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.writeFlatFloat('uEmissiveGain', gain);
+        this.emission[0] = gain;
+        this.writeFlatVector('uEmission', this.emission);
     }
     /* -- Instanced meshes --------------------------------------------------------------- */
     /** The instanced program, compiled on first use. See `ensureInstancedProgram`. */
@@ -3241,6 +3404,7 @@ export class WebGL2Renderer {
     submitInstanced(batch, data, opacity, blend, options) {
         if (this.contextLost)
             return;
+        warnRegionsWithoutPage(this.currentMaterial?.model, data.lightmapRegions);
         const mesh = batch.mesh;
         /* Nor a batch of a mesh with nothing in it: see `Mesh.indexCount`. */
         if (!mesh.complete || mesh.indexCount === 0)
@@ -3387,7 +3551,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)
@@ -3686,6 +3850,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.
      *
@@ -3702,8 +3880,10 @@ export class WebGL2Renderer {
         const { gl } = this;
         const u = batch.uniforms;
         gl.useProgram(batch.program);
-        batch.upload(gl, data);
+        batch.upload(gl, data, camera.position);
         batch.bindMaterial(gl);
+        if (batch.material === 'sprite')
+            this.bindSpriteFades(batch, camera);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, this.viewProjFor(camera));
         gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
         gl.uniform1f(u['uTime'] ?? null, timeSeconds);
@@ -3730,6 +3910,38 @@ export class WebGL2Renderer {
         if (this.materialDoubleSided)
             gl.enable(gl.CULL_FACE);
     }
+    /**
+     * A sprite's two fades and the depth copy the soft one reads. The copy is the frame's opaque
+     * depth, so it is taken only in the frame's own picture: in a mirror or a probe's face it would
+     * be another view's, and the edge stays hard there. Without a scene target there is no copy at
+     * all, and the renderer says so once rather than drawing a hard edge that was asked to be soft.
+     */
+    bindSpriteFades(batch, camera) {
+        const { gl } = this;
+        const u = batch.uniforms;
+        const scene = this.sceneTarget;
+        let depth = null;
+        if (batch.softDepth > 0 &&
+            !this.reflectionPassActive &&
+            !this.probePassActive &&
+            !this.capturePassActive) {
+            depth = scene?.snapshotDepth(true) ?? null;
+            if (depth === null && !this.warnedSpriteDepth) {
+                this.warnedSpriteDepth = true;
+                console.warn("WebGL2: a 'sprite' asked for a soft edge, which reads a copy of the frame's depth, and " +
+                    'this profile keeps none — screenEffects is off, or the driver refused the copy. The ' +
+                    'edge is hard.');
+            }
+        }
+        gl.activeTexture(gl.TEXTURE0 + PARTICLE_DEPTH_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, depth ?? this.emptyTexture2D);
+        gl.uniform1i(u['uDepth'] ?? null, PARTICLE_DEPTH_UNIT);
+        gl.uniform4f(u['uFade'] ?? null, batch.softDepth, batch.cameraFade, depth === null ? 0 : 1, 0);
+        mat4.invert(this.spriteInverseProjection, camera.projection);
+        const inverse = this.spriteInverseProjection;
+        gl.uniform4f(u['uDepthToViewZ'] ?? null, inverse[10] ?? 0, inverse[14] ?? 0, inverse[11] ?? 0, inverse[15] ?? 1);
+        gl.uniform2f(u['uViewport'] ?? null, scene?.frameWidth ?? gl.drawingBufferWidth, scene?.frameHeight ?? gl.drawingBufferHeight);
+    }
     /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
     createBolts(segmentCapacity, label = 'bolts') {
         return new BoltBatch(this.gl, segmentCapacity, label);
@@ -4584,6 +4796,7 @@ export class WebGL2Renderer {
             lightFixtures: this.litOn.LIGHT_FIXTURES,
             surfaceEffects: this.litOn.SURFACE_EFFECTS,
             driftLight: this.litOn.DRIFT_LIGHT,
+            physicalSpecular: this.litOn.PHYSICAL_SPECULAR,
             maxLights: budget.maxLights,
             maxAreaLights: budget.maxAreaLights,
         });
@@ -4643,7 +4856,7 @@ export class WebGL2Renderer {
         for (const [key, entry] of this.modelFlat) {
             const [variant, kind, half] = key.split('|');
             const label = `flat.${variant}.${kind}.${half}`;
-            const program = compileProgram(gl, litVertexOf(variant), skinHalfBound(modelBound(this.flatFragSource, kind), half), label);
+            const program = compileProgram(gl, modelVertexOf(variant, kind), skinHalfBound(modelBound(this.flatFragSource, kind), half), label);
             gl.deleteProgram(entry.program);
             this.modelFlat.set(key, { program, uniforms: uniformLocations(gl, program, label) });
         }
@@ -5386,11 +5599,19 @@ export class WebGL2Renderer {
      * and wrong for a day whose exposure spans 2.5 to 14: a courtyard blooming at noon, or candles
      * never blooming at night. A caller whose exposure moves passes what it wants on screen over the
      * exposure. Omitted leaves it where it was, so a caller that never passes one keeps the profile's.
+     *
+     * **`response` is how a colour comes in past the threshold and what colour each octave of the
+     * halo takes** — a ramp in place of the subtraction, and a tint a level — held until moved like
+     * the threshold; `null` goes back to the subtraction and white. See `BloomResponse`: it is what
+     * matches a stage built for another engine's bloom, whose tints are how a strength past 1 is
+     * asked for.
      */
-    setBloom(scale, threshold) {
+    setBloom(scale, threshold, response) {
         this.bloomScale = Math.min(Math.max(scale, 0), 1);
         if (threshold !== undefined)
             this.bloomThresholdSet = bloomThresholdOf(threshold);
+        if (response !== undefined)
+            resolveBloomResponse(response, this.bloomResponse);
     }
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
@@ -5906,6 +6127,7 @@ export class WebGL2Renderer {
             ? {
                 strength: bloomStrength,
                 threshold: this.bloomThresholdSet ?? this.quality.bloomThreshold,
+                response: this.bloomResponse,
             }
             : undefined;
         /* The grade travels to the resolve only where the mesh pass gave it up. See `bindMeshPass`. */
@@ -6188,6 +6410,15 @@ export class WebGL2Renderer {
     bindMeshPass(camera, env) {
         /* The pass's own material is reopened, so the next draw opens one. See `materialChanges.ts`. */
         this.materials.dirty();
+        /* Rectangles past the fixed arm's are the froxel table's, and without it nobody shades them. */
+        if (!this.warnedAreaOverflow &&
+            !this.quality.clusteredLights &&
+            (env.areaLights?.count ?? 0) > this.shadedAreaLights) {
+            this.warnedAreaOverflow = true;
+            console.warn(`WebGL2: ${env.areaLights?.count ?? 0} rectangular lights and ${this.shadedAreaLights} ` +
+                'shaded without clusteredLights: the rest are not drawn. Turn clusteredLights on, and the ' +
+                'froxel table shades every one past the fixed ones, unshadowed.');
+        }
         /*
          * Captured here rather than taken as an argument to `endFrame`, because this is the
          * camera the world was drawn with and a caller should not have to hand it over twice.
@@ -6202,7 +6433,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. */
@@ -6297,6 +6531,13 @@ export class WebGL2Renderer {
         this.materialHasMaps = false;
         this.currentMaterial = null;
         this.currentSurfaceTexture = 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. */
+        this.environmentDials[1] = 0;
+        this.environmentDials[2] = 1;
+        this.emission[0] = env.emissiveGain;
+        this.emission[1] = env.nightFactor;
         for (const target of this.flatTargets) {
             this.gl.useProgram(target.program);
             this.writeMeshPassState(target.uniforms, camera, env);
@@ -6492,13 +6733,18 @@ export class WebGL2Renderer {
         this.oitWeight = 0;
         this.ditherFade = 0;
         gl.uniform2f(u['uWriteMode'] ?? null, 0, 0);
-        /* No environment reflection unless a caller asks, so existing scenes are unchanged. */
-        gl.uniform1f(u['uReflectivity'] ?? null, 0);
-        /* 1, not 0: this one is a multiplier and its identity is one. See `setEnvironmentGain`. */
-        gl.uniform1f(u['uEnvironmentGain'] ?? null, 1);
+        /* The draw's own ambient as it stands, which `bindMeshPass` has just cleared: a program built
+           in the middle of a pass takes what the caller set. See `setAmbientSH`. */
+        gl.uniform4fv(u['uAmbientSH[0]'] ?? null, this.ambientSH);
+        /*
+         * Which chain the probe holds, no environment reflection, and an environment at its own
+         * brightness — the reflectivity's identity is 0 and the gain's is 1 — as `bindMeshPass` set
+         * them, or as a draw since has: a program built in the middle of a pass takes what stands.
+         * See `setSurfaceReflectivity` and `setEnvironmentGain`.
+         */
+        gl.uniform3fv(u['uEnvironmentDials'] ?? null, this.environmentDials);
         /* And no relief unless a caller asks, for the same reason. */
-        gl.uniform1f(u['uRelief'] ?? null, 0);
-        gl.uniform1f(u['uReliefCycles'] ?? null, 60);
+        gl.uniform2f(u['uRelief'] ?? null, 0, 60);
         /* And no relief read off a surface texture either, for the same reason. */
         gl.uniform1f(u['uTextureRelief'] ?? null, 0);
         /* The mirror's plane in a reflection pass, and zero — which clips nothing — in every other. */
@@ -6507,8 +6753,8 @@ export class WebGL2Renderer {
         resolveSurfaceScene(env, this.surfaceScene);
         gl.uniform4fv(u['uSurfaceScene'] ?? null, this.surfaceScene);
         bindAtmosphere(gl, u, env, this.reflectionPassActive ? this.reflectionAtmosphereY : (camera.position[1] ?? 0), this.quality.underwaterAtmosphere);
-        gl.uniform1f(u['uEmissiveGain'] ?? null, env.emissiveGain);
-        gl.uniform1f(u['uNightFactor'] ?? null, env.nightFactor);
+        /* The emissive gain and the night factor, as the pass set them. See `uEmission`. */
+        gl.uniform2fv(u['uEmission'] ?? null, this.emission);
         /* Absent means zero, so a world written before this term existed adds nothing. */
         gl.uniform1f(u['uNightEmissive'] ?? null, env.nightEmissive ?? 0);
         /*
@@ -6530,8 +6776,10 @@ export class WebGL2Renderer {
         gl.uniform1f(u['uShadowMaxSlope'] ?? null, this.quality.directionalShadowMaxSlope);
         gl.uniform1i(u['uShadowFilterTaps'] ?? null, this.quality.shadowFilterTaps);
         gl.uniform3fv(u['uHighlightMin'] ?? null, env.highlightMin);
-        gl.uniform3fv(u['uHighlightMax'] ?? null, env.highlightMax);
-        gl.uniform1f(u['uHighlightGain'] ?? null, env.highlightGain);
+        /* The far corner, and the gain in its w. See `uHighlightMax`. */
+        /* An environment written by hand may leave the box out; then there is none, as before. */
+        const max = env.highlightMax ?? NO_HIGHLIGHT;
+        gl.uniform4f(u['uHighlightMax'] ?? null, max[0] ?? 0, max[1] ?? 0, max[2] ?? 0, env.highlightGain ?? 0);
         bindPointLights(gl, u, env, this.quality.pointLightFalloff);
         this.bindClusters(u, camera, env);
         this.bindIesAtlas(u);
@@ -6627,7 +6875,8 @@ export class WebGL2Renderer {
              * between them; there is one array, so `RenderQuality.environmentPrefilter` decides what the
              * convolution writes and a profile that changes it has to bake again.
              */
-            gl.uniform1f(u['uEnvironmentPrefiltered'] ?? null, this.quality.environmentPrefilter ? 1 : 0);
+            this.environmentDials[0] = this.quality.environmentPrefilter ? 1 : 0;
+            gl.uniform3fv(u['uEnvironmentDials'] ?? null, this.environmentDials);
             gl.uniform1f(u['uEnvironmentMaxLod'] ?? null, array?.ggxMaxLevel ?? 0);
             /*
              * The map's edge, which used to be `exp2(maxLod)` and is not any more: the chain stops one
@@ -6817,12 +7066,17 @@ export class WebGL2Renderer {
             return;
         this.drawBudget.ask();
         this.takeMaterial();
-        /* Skin under the screen-space blur draws its two halves: the frame's, then at once its diffuse. */
+        /*
+         * Skin under the screen-space blur draws its halves: the frame's, then at once its diffuse's
+         * light and its colour, each into the blur's own target.
+         */
         const splits = this.skinSplits();
         this.drawMeshHalf(mesh, model, depthLayer, tint, splits ? 'scene' : 'whole');
         if (splits && this.skinScatter !== null) {
             this.skinScatter.begin();
             this.drawMeshHalf(mesh, model, depthLayer, tint, 'diffuse');
+            this.skinScatter.beginAlbedo();
+            this.drawMeshHalf(mesh, model, depthLayer, tint, 'albedo');
             this.sceneTarget?.bind();
         }
     }
@@ -6840,6 +7094,7 @@ export class WebGL2Renderer {
             !this.skinScattered &&
             !this.reflectionPassActive &&
             !this.probePassActive &&
+            !this.capturePassActive &&
             !this.framePresented &&
             skin.ready(scene));
     }
@@ -6860,7 +7115,9 @@ export class WebGL2Renderer {
         this.skinScattered = true;
         if (!skin.pending)
             return;
-        if (this.reflectionPassActive || this.probePassActive || projection === null)
+        if (this.reflectionPassActive || this.probePassActive || this.capturePassActive)
+            return;
+        if (projection === null)
             return;
         const depth = scene.snapshotDepth(true);
         mat4.invert(this.skinInverseProjection, projection);
@@ -6996,8 +7253,9 @@ export class WebGL2Renderer {
          * depth 1.0 against a buffer cleared to 1.0, and under `LESS` it would not draw at
          * all. Film, caustics and text lie flush on surfaces for the same reason.
          */
-        /* A skin's diffuse half is the same surface again: it finds the depth its frame half wrote. */
-        const again = half === 'diffuse';
+        /* A skin's diffuse and colour halves are the same surface again: each finds the depth its
+           frame half wrote. */
+        const again = half === 'diffuse' || half === 'albedo';
         gl.depthFunc(again ? gl.EQUAL : this.reversedDepth ? gl.GREATER : gl.LESS);
         if (again)
             gl.depthMask(false);
@@ -7441,6 +7699,43 @@ export class WebGL2Renderer {
         this.probeSweeps?.baked(0);
         return true;
     }
+    /**
+     * One layer of the declared probe grid from an image, the way `setEnvironmentImage` fills a
+     * single probe: the same equirectangular image of linear RGB floats, projected onto the capture
+     * cube and prefiltered into that layer, the others left as they are. Returns false — and says
+     * why — where there is no probe, no grid, or no such layer.
+     *
+     * **What it is for**: a scene baked somewhere else. Another engine's reflection captures are
+     * images taken where each one stands; a consumer fits them to a lattice — for each point, the
+     * capture whose reach holds it — and hands each point its image here, where `bakeProbe` would
+     * have drawn this engine's own world into it.
+     *
+     * `options.irradiance` decides, at grid scope as a bake's does, whether the grid also lights the
+     * scene's diffuse ambient. A grid that crossfades writes the set being swept, as a bake does.
+     */
+    setProbeLayerImage(layer, image, options) {
+        if (this.contextLost)
+            return false;
+        const probe = this.probeCapture;
+        const array = this.probeArray;
+        const grid = this.probes;
+        const sweeps = this.probeSweeps;
+        if (probe === null || array === null || grid === null || sweeps === null) {
+            console.warn('Renderer: setProbeLayerImage needs a reflection probe (`reflectionProbeSize`) and a grid ' +
+                'declared with setProbeGrid; the image was ignored.');
+            return false;
+        }
+        if (!Number.isInteger(layer) || layer < 0 || layer >= grid.layers) {
+            console.warn(`Renderer: setProbeLayerImage was given layer ${layer}, and the grid has ${grid.layers}.`);
+            return false;
+        }
+        if (!probe.upload(this.gl, equirectToCubeFaces(image, probe.size)))
+            return false;
+        this.probeAmbient = options?.irradiance ?? true;
+        this.environmentPrefilter?.run(this.gl, probe, array, sweeps.writeLayer(layer), ENVIRONMENT_TEXTURE_UNIT, this.quality.environmentPrefilterSamples, this.quality.environmentPrefilter);
+        sweeps.baked(layer);
+        return true;
+    }
     /**
      * Draw a volume of light: a beam from a lamp, a shaft through a window, the cone under a
      * street light.
@@ -7758,6 +8053,14 @@ const NO_MODEL_PARAMS = new Float32Array(MODEL_PARAM_FLOATS);
  * The lit vertex stage a program of this variant compiles: the standard programs' and the cloth's,
  * which `modelProgram` pairs a model's fragment stage with.
  */
+/**
+ * The vertex stage a model's program draws with: the variant's own, but for a lightmapped instanced
+ * batch, whose tint lane is each instance's region of the page. See `lightmap.ts`.
+ */
+function modelVertexOf(variant, kind) {
+    const vertex = litVertexOf(variant);
+    return kind === 'lightmap' && variant === 'instanced' ? lightmapRegionsBound(vertex) : vertex;
+}
 function litVertexOf(variant) {
     if (variant.startsWith('cloth')) {
         const eight = variant[5] === '8';