@driftengine/core 4.3.0 → 4.4.0

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

@@ -1,7 +1,7 @@
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
 import { mat4 } from 'gl-matrix';
-import { DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
+import { GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { PickableSet } from '../../pickable.js';
 import { TEMPORAL_HISTORY_BLEND, TemporalHistory, jitterOffset, jitterProjection, } from '../../temporalAa.js';
 import { DecalPass } from '../../decalPass.js';
@@ -27,8 +27,11 @@ import { compileProgram, uniformLocations } from '../../shader.js';
 import { FULL_LIGHT_BUDGET, nextLightBudget, planLightBudget, } from '../../uniformVectorBudget.js';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.js';
 import { SceneTarget } from '../../sceneTarget.js';
-import { bloomProfileWarning } from '../../bloomChain.js';
-import { createEmptyTexture2D, createEmptyTexture2DArray, createEmptyTextureCube, } from '../../emptyTexture.js';
+import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.js';
+import { bloomProfileWarning, bloomThresholdOf } from '../../bloomChain.js';
+import { createEmptyTexture2D, createEmptyTexture2DArray, createEmptyTexture3D, createEmptyTextureCube, } from '../../emptyTexture.js';
+import { LightField } from '../../driftLight/lightField.js';
+import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.js';
 import { flatFrag, flatVert } from '../../shaders/flat/index.js';
 import { MORPH_DELTA_TEXTURE_UNIT, SKIN_PALETTE_TEXTURE_UNIT } from '../../lightBudget.js';
 import { SkinPaletteTexture } from './skinPaletteTexture.js';
@@ -36,9 +39,10 @@ import { SkinPaletteTexture } from './skinPaletteTexture.js';
 /* The codes the shader reads, stated once in `vertexDefaults.ts` for both backends. */
 import { LIGHT_VOLUME_VERT, lightVolumeFrag } from '../../shaders/lightVolume.js';
 import { PANEL_FRAG, PANEL_VERT } from '../../shaders/panel.js';
-import { ReflectionProbe, cubeFaceProjection } from '../../reflectionProbe.js';
+import { ReflectionProbe, cubeFaceProjection, probeFaceRange } from '../../reflectionProbe.js';
 import { EnvProbeArray } from '../../envProbeArray.js';
 import { ProbeGrid, SINGLE_PROBE, UNIT_STEP, WORLD_ORIGIN, sameGrid } from '../../probeGrid.js';
+import { ProbeSweeps } from '../../probeSweeps.js';
 import { octahedralEdgeFor } from '../../prefilterEnvMap.js';
 import { EnvironmentPrefilterPass } from '../../prefilterPass.js';
 import { packIesAtlas } from '../../iesProfile.js';
@@ -46,14 +50,14 @@ import { MAX_AREA_LIGHTS } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { equirectToCubeFaces } from '../../equirectToCube.js';
 import { SKY_FRAG, skyVertFor } from '../../shaders/sky.js';
-import { DEPTH_FRAG, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
+import { DEPTH_CUTOUT_FRAG, DEPTH_CUTOUT_VERT, DEPTH_FRAG, DEPTH_INSTANCED_CUTOUT_VERT, DEPTH_INSTANCED_VERT, DEPTH_SKINNED_VERT, DEPTH_VERT, } from '../../shaders/depth.js';
 import { PointShadowArray } from '../../pointShadowArray.js';
 import { ShadowMap } from '../../shadowMap.js';
 import { POINT_SHADOW_SAMPLER, PointShadowSystem } from '../../pointShadowSystem.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, 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, COOKIE_ATLAS_TEXTURE_UNIT, REFRACT_SCENE_TEXTURE_UNIT, COOKIE_TILE, IES_ATLAS_TEXTURE_UNIT, bindAreaLights, bindAreaShadows, openCones, } from '../../lightBudget.js';
+import { DIRECTIONAL_SHADOW_UNITS, 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, COOKIE_ATLAS_TEXTURE_UNIT, REFRACT_SCENE_TEXTURE_UNIT, DRIFT_LIGHT_ATLAS_TEXTURE_UNIT, DRIFT_LIGHT_INDEX_TEXTURE_UNIT, COOKIE_TILE, IES_ATLAS_TEXTURE_UNIT, bindAreaLights, bindAreaShadows, openCones, } from '../../lightBudget.js';
 import { resolveRenderQuality } from '../../renderQuality.js';
 import { drawingBufferSize } from '../../drawingBuffer.js';
 import { Mesh, createMeshIncremental } from '../../mesh.js';
@@ -78,6 +82,7 @@ import { OUTPUT_TRANSFORM_CODE } from '../../vertexDefaults.js';
 import { deviceSnappedCellSize } from '../../textLayout.js';
 import { WindStreakRenderer } from '../../windStreakRenderer.js';
 import { InstancedBatch } from './instanced.js';
+import { cutoutOf } from '../../cutoutCaster.js';
 /**
  * How many frames `firstFrameSettled` will ask before it stops asking.
  *
@@ -451,6 +456,8 @@ export class WebGL2Renderer {
     panelProgram;
     panelUniforms;
     panelVao;
+    /** The unit quad behind `panelVao`, held so `dispose` can release it. */
+    panelBuffer;
     filmProgram;
     /**
      * The off-screen colour target, when screen effects are on. Null is not a failure —
@@ -481,6 +488,14 @@ export class WebGL2Renderer {
     /** Whether a palette is currently chosen. Distinct from whether one was ever uploaded. */
     skinPaletteSet = false;
     emptyTexture2D;
+    /** DriftLight's stand-ins while no field is whole: no brick anywhere, and no light. */
+    emptyDriftIndex;
+    emptyDriftAtlas;
+    /** The scene's DriftLight field, and its two volumes once it is whole. See `createLightField`. */
+    lightField = null;
+    driftIndex = null;
+    driftAtlas = null;
+    driftUniforms = createDriftLightUniforms();
     emptyTexture2DArray;
     emptyTextureCube;
     /** How hard the rush blurs this frame, and how far its outermost tap reaches. */
@@ -549,6 +564,8 @@ export class WebGL2Renderer {
     motionBlurScale = 1;
     /** How much of the bloom ceiling this frame takes. See `setBloom`. */
     bloomScale = 1;
+    /** In scene units, once `setBloom` has moved it; null reads the profile's. */
+    bloomThresholdSet = null;
     /**
      * This frame's exposure into the tone curve. See `setOutputExposure`.
      *
@@ -656,6 +673,15 @@ export class WebGL2Renderer {
     depthUniforms;
     depthInstancedProgram;
     depthInstancedUniforms;
+    /**
+     * The cutout casters' depth programs, rigid and instanced: a leaf or a chain link casts the shape
+     * in its texture's alpha, not its whole card. See `DEPTH_CUTOUT_FRAG`. Chosen per draw by
+     * `cutoutOf`, so an opaque caster never touches them.
+     */
+    depthCutoutProgram;
+    depthCutoutUniforms;
+    depthInstancedCutoutProgram;
+    depthInstancedCutoutUniforms;
     scatterDepthProgram;
     scatterDepthUniforms;
     shadowMap;
@@ -714,6 +740,10 @@ export class WebGL2Renderer {
     probeCapture;
     /** Every probe of the grid, as one array texture. Allocated when a grid is declared. */
     probeArray = null;
+    /** Which layers a bake writes and the shading reads. See `probeSweeps.ts`. */
+    probeSweeps = null;
+    /** `uProbeGridSets`, rewritten in place. */
+    probeSets = new Float32Array(3);
     /**
      * Where those probes stand. A single baked probe is a grid of one at that probe's own origin.
      *
@@ -739,6 +769,8 @@ export class WebGL2Renderer {
     warnedEnvironmentAmbient = false;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     probePassActive = 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. */
     clipControl = null;
     /**
@@ -876,6 +908,17 @@ export class WebGL2Renderer {
      */
     activeDepthViewProj = IDENTITY_MAT4;
     activeDepthPeel = false;
+    /**
+     * Whether a peel pass has filled the second layer since the first one last opened, which is
+     * what the frame samples it on: the rule the other backend's `peelFilled` states, held here too.
+     *
+     * **Not whether the map exists.** That was the test here, on the belief that a GL texture is
+     * born reading as the far plane; it is born zeroed, and a scene that built the layer and never
+     * peeled it sampled an occluder at the light. `ShadowMap` now clears itself at birth, so an
+     * unfilled layer would read as lit either way — this is what keeps the two backends one
+     * decision, and a frame that does not peel from paying a fetch per tap for nothing.
+     */
+    peelFilled = false;
     /**
      * Whether the depth pass this scatter draw interrupts wants back-face culling.
      *
@@ -886,6 +929,11 @@ export class WebGL2Renderer {
      * cubemap — so the pass states what it wants and this restores that.
      */
     depthPassCullsFaces = true;
+    /**
+     * Whether the bound material is seen from both faces, so its draws cull nothing. Toggled around
+     * each such draw and handed back, where the other backend bakes it into a pipeline.
+     */
+    materialDoubleSided = false;
     /**
      * The one sink handed to every caster enumeration.
      *
@@ -893,16 +941,38 @@ export class WebGL2Renderer {
      * per pass would allocate six objects per light per frame.
      */
     casterSink = {
-        mesh: (mesh, model) => {
+        mesh: (mesh, model, material) => {
             this.shadowDrawBudget.ask();
             const { gl } = this;
+            /* A two-sided caster casts from whichever face the light sees: nothing culled. */
+            const twoSided = material?.doubleSided === true;
+            const cutout = cutoutOf(material);
+            if (cutout !== null) {
+                const u = this.depthCutoutUniforms;
+                gl.useProgram(this.depthCutoutProgram);
+                this.bindCutoutDepth(u, cutout);
+                gl.uniformMatrix4fv(u['uModel'] ?? null, false, model);
+                if (twoSided)
+                    gl.disable(gl.CULL_FACE);
+                mesh.draw(gl);
+                if (twoSided && this.depthPassCullsFaces)
+                    gl.enable(gl.CULL_FACE);
+                /* Hand the pass back as it was found: the next caster may be rigid and opaque. */
+                gl.useProgram(this.depthProgram);
+                this.restoreSurfaceTextureUnit();
+                return;
+            }
             gl.uniformMatrix4fv(this.depthUniforms['uModel'] ?? null, false, model);
             /*
              * The sink takes the opaque handle both backends share, and this renderer only ever
              * handed out its own `Mesh`. Narrowing is safe here for that reason and nowhere else:
              * a handle from the other backend would have to have crossed renderers to arrive.
              */
+            if (twoSided)
+                gl.disable(gl.CULL_FACE);
             mesh.draw(gl);
+            if (twoSided && this.depthPassCullsFaces)
+                gl.enable(gl.CULL_FACE);
         },
         /**
          * A batch into the depth map, placed by the same matrices the visible draw uses.
@@ -910,13 +980,27 @@ export class WebGL2Renderer {
          * No `uModel`: the instanced depth program has none, its placement being the four attribute
          * columns the batch's own buffer supplies.
          */
-        instanced: (batch, data) => {
+        instanced: (batch, data, material) => {
             const { gl } = this;
             const gpuBatch = batch;
             const count = Math.min(data.count, gpuBatch.capacity);
             if (count === 0)
                 return;
             this.shadowDrawBudget.ask();
+            const twoSided = material?.doubleSided === true;
+            if (twoSided)
+                gl.disable(gl.CULL_FACE);
+            const cutout = cutoutOf(material);
+            if (cutout !== null) {
+                gl.useProgram(this.depthInstancedCutoutProgram);
+                this.bindCutoutDepth(this.depthInstancedCutoutUniforms, cutout);
+                gpuBatch.mesh.drawInstances(gl, count);
+                if (twoSided && this.depthPassCullsFaces)
+                    gl.enable(gl.CULL_FACE);
+                gl.useProgram(this.depthProgram);
+                this.restoreSurfaceTextureUnit();
+                return;
+            }
             const u = this.depthInstancedUniforms;
             gl.useProgram(this.depthInstancedProgram);
             gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, this.activeDepthViewProj);
@@ -924,6 +1008,8 @@ export class WebGL2Renderer {
             if (this.activeDepthPeel)
                 gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
             gpuBatch.mesh.drawInstances(gl, count);
+            if (twoSided && this.depthPassCullsFaces)
+                gl.enable(gl.CULL_FACE);
             gl.useProgram(this.depthProgram);
         },
         skinnedMesh: (mesh, model, palette) => {
@@ -973,6 +1059,21 @@ export class WebGL2Renderer {
             gl.useProgram(this.depthProgram);
         },
     };
+    /**
+     * What a cutout depth draw needs beyond the plain one: the pass's matrix and peel, the material's
+     * cutoff and UV scale, and its albedo on the surface unit, which the caller gives back after.
+     */
+    bindCutoutDepth(u, cutout) {
+        const { gl } = this;
+        gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, this.activeDepthViewProj);
+        gl.uniform1i(u['uPeelShadowLayer'] ?? null, this.activeDepthPeel ? 1 : 0);
+        if (this.activeDepthPeel)
+            gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
+        gl.uniform2f(u['uUvScale'] ?? null, cutout.u, cutout.v);
+        gl.uniform1f(u['uAlphaCutout'] ?? null, cutout.cutoff);
+        /* Narrowed for the reason the sink's own `mesh` gives: this renderer only hands out its own. */
+        cutout.albedo.bind(gl, SURFACE_TEXTURE_UNIT);
+    }
     drawPointShadowFace = (viewProj) => {
         const casters = this.pointShadowCasters;
         if (casters === null)
@@ -1529,6 +1630,8 @@ export class WebGL2Renderer {
          * "unbound". Two 1x1 uploads for the life of the renderer.
          */
         this.emptyTexture2D = createEmptyTexture2D(gl);
+        this.emptyDriftIndex = createEmptyTexture3D(gl, true);
+        this.emptyDriftAtlas = createEmptyTexture3D(gl, false);
         this.emptyTexture2DArray = createEmptyTexture2DArray(gl);
         this.emptyTextureCube = createEmptyTextureCube(gl);
         this.gpuTimer = new GpuTimer(gl);
@@ -1720,6 +1823,7 @@ export class WebGL2Renderer {
         this.panelVao = panelVao;
         gl.bindVertexArray(panelVao);
         const panelBuffer = gl.createBuffer();
+        this.panelBuffer = panelBuffer;
         gl.bindBuffer(gl.ARRAY_BUFFER, panelBuffer);
         // A unit quad. The rectangle it becomes is a uniform, so this is uploaded once
         // for the life of the renderer however many panels are drawn.
@@ -1786,6 +1890,19 @@ export class WebGL2Renderer {
          */
         this.scatterDepthProgram = compileProgram(gl, SCATTER_DEPTH_VERT, DEPTH_FRAG, 'scatterDepth');
         this.scatterDepthUniforms = uniformLocations(gl, this.scatterDepthProgram, 'scatterDepth');
+        this.depthCutoutProgram = compileProgram(gl, DEPTH_CUTOUT_VERT, DEPTH_CUTOUT_FRAG, 'depth-cutout');
+        this.depthCutoutUniforms = uniformLocations(gl, this.depthCutoutProgram, 'depth-cutout');
+        this.depthInstancedCutoutProgram = compileProgram(gl, DEPTH_INSTANCED_CUTOUT_VERT, DEPTH_CUTOUT_FRAG, 'depth-instanced-cutout');
+        this.depthInstancedCutoutUniforms = uniformLocations(gl, this.depthInstancedCutoutProgram, 'depth-instanced-cutout');
+        /* The cutout map is always read from the surface unit, which the draw borrows and gives back. */
+        for (const [program, uniforms] of [
+            [this.depthCutoutProgram, this.depthCutoutUniforms],
+            [this.depthInstancedCutoutProgram, this.depthInstancedCutoutUniforms],
+        ]) {
+            gl.useProgram(program);
+            gl.uniform1i(uniforms['uCutoutMap'] ?? null, SURFACE_TEXTURE_UNIT);
+        }
+        gl.useProgram(null);
         this.shadowMap = this.quality.directionalShadows
             ? new ShadowMap(gl, this.quality.directionalShadowMapSize)
             : null;
@@ -1928,6 +2045,7 @@ export class WebGL2Renderer {
                 this.flatSkinnedProgram,
                 this.flatMorphedProgram,
                 this.flatBothProgram,
+                this.flatInstancedProgram,
             ]) {
                 if (extra !== null)
                     gl.deleteProgram(extra);
@@ -1939,12 +2057,20 @@ export class WebGL2Renderer {
                 this.skyProgram,
                 this.scatterProgram,
                 this.depthProgram,
+                this.depthSkinnedProgram,
+                this.depthInstancedProgram,
                 this.scatterDepthProgram,
+                this.lightVolumeProgram,
+                this.depthCutoutProgram,
+                this.depthInstancedCutoutProgram,
             ]) {
                 gl.deleteProgram(program);
             }
             this.skinPalette.dispose(gl);
             gl.deleteTexture(this.emptyTexture2D);
+            gl.deleteTexture(this.emptyDriftIndex);
+            gl.deleteTexture(this.emptyDriftAtlas);
+            this.forgetLightFieldVolumes();
             gl.deleteTexture(this.emptyTexture2DArray);
             gl.deleteTexture(this.emptyTextureCube);
             /* A cubemap and its whole mip chain, which is the largest single thing this
@@ -1952,6 +2078,28 @@ export class WebGL2Renderer {
             this.probeCapture?.dispose(gl);
             this.probeArray?.dispose(gl);
             this.environmentPrefilter?.dispose(gl);
+            /*
+             * **Everything else the constructor made, which this method never released.** The screen
+             * chain and its bloom and occlusion, three sun maps, the mirror, the point-shadow array, two
+             * vertex arrays, a quad and three textures made on first use. A page swapping renderers kept
+             * every one of them, per renderer, for as long as it lived; `renderer.test.ts` counts them.
+             */
+            this.sceneTarget?.dispose();
+            this.shadowMap?.dispose(gl);
+            this.peeledShadowMap?.dispose(gl);
+            this.dynamicShadowMap?.dispose(gl);
+            this.planarReflection?.dispose(gl);
+            this.pointShadows?.dispose();
+            gl.deleteVertexArray(this.panelVao);
+            gl.deleteVertexArray(this.skyVao);
+            if (this.panelBuffer !== null)
+                gl.deleteBuffer(this.panelBuffer);
+            if (this.cookieTexture !== null)
+                gl.deleteTexture(this.cookieTexture);
+            if (this.iesTexture !== null)
+                gl.deleteTexture(this.iesTexture);
+            if (this.clusterTexture !== null)
+                gl.deleteTexture(this.clusterTexture);
         }
         if (options.releaseContext === true) {
             gl.getExtension('WEBGL_lose_context')?.loseContext();
@@ -2171,6 +2319,7 @@ export class WebGL2Renderer {
             return;
         this.materials.dirty();
         this.currentSurfaceTexture = material?.albedo ?? null;
+        this.materialDoubleSided = material?.doubleSided === true;
         /*
          * Written to every flat program, because material state persists across draws and a skinned
          * draw is entitled to the material the caller set before it. A second program holding none of
@@ -2237,10 +2386,11 @@ export class WebGL2Renderer {
          * The emissive map, on exactly the terms the two maps above it are bound: before the albedo
          * early return, and the stand-in rather than `null`.
          *
-         * **White is the right stand-in here and black would be a bug.** The shader multiplies by this
-         * map, so the placeholder has to be the multiplicative identity; `emptyTexture2D` is white,
-         * which is what makes an unbound material collapse to the arithmetic it had before. A black
-         * placeholder would switch every glow in the scene off the moment the gate was ever wrong.
+         * **The stand-in is black, so the gate is what keeps a glow on.** The shader multiplies by
+         * this map, and `emptyTexture2D` is opaque black rather than the multiplicative identity, so an
+         * unbound material keeps the arithmetic it had before only because `uEmissiveMapEnabled` is 0
+         * and the read never happens. What would make that wrong is a read taken outside that branch:
+         * every glow on a material without a map would go out.
          */
         const emissiveMap = material?.emissive ?? null;
         gl.activeTexture(gl.TEXTURE0 + EMISSIVE_TEXTURE_UNIT);
@@ -2259,6 +2409,7 @@ export class WebGL2Renderer {
          * how big a dome was — WebGPU writes it before its own early return and WebGL2 did not.
          */
         gl.uniform2f(u['uUvScale'] ?? null, material?.uScale ?? 1, material?.vScale ?? 1);
+        gl.uniform1i(u['uDoubleSided'] ?? null, material?.doubleSided === true ? 1 : 0);
         if (albedo === null) {
             gl.uniform1i(u['uAlbedoEnabled'] ?? null, 0);
             return;
@@ -2963,7 +3114,11 @@ export class WebGL2Renderer {
          */
         bindPointLights(gl, u, env, this.quality.pointLightFalloff);
         bindAtmosphere(gl, u, env, this.reflectionPassActive ? this.reflectionAtmosphereY : (camera.position[1] ?? 0), this.quality.underwaterAtmosphere);
+        if (this.materialDoubleSided)
+            gl.disable(gl.CULL_FACE);
         batch.drawTo(gl, data.count);
+        if (this.materialDoubleSided)
+            gl.enable(gl.CULL_FACE);
     }
     /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
     createBolts(segmentCapacity, label = 'bolts') {
@@ -3470,6 +3625,9 @@ export class WebGL2Renderer {
         this.gpuTimer.begin('shadows');
         this.shadowPassActive = true;
         this.activeShadowMap = shadowMap;
+        /* The static layer opens first, so a frame's peel counts from here. See `peelFilled`. */
+        if (layer === 'static')
+            this.peelFilled = false;
         /*
          * **Range-corrected but not reversed.** `EXT_clip_control` is context state, so a light matrix
          * that still emits OpenGL's `[-1, 1]` loses everything below zero the moment it is on. See
@@ -3523,6 +3681,8 @@ export class WebGL2Renderer {
         this.uploadWind(this.depthUniforms, this.frameWind);
         gl.useProgram(this.depthSkinnedProgram);
         this.uploadWind(this.depthSkinnedUniforms, this.frameWind);
+        gl.useProgram(this.depthCutoutProgram);
+        this.uploadWind(this.depthCutoutUniforms, this.frameWind);
         gl.useProgram(this.depthProgram);
     }
     /**
@@ -3614,6 +3774,8 @@ export class WebGL2Renderer {
         if (!this.shadowPassActive || shadowMap === null)
             return;
         shadowMap.end(this.gl);
+        if (shadowMap === this.peeledShadowMap)
+            this.peelFilled = true;
         /* Back to the frame's sense; see `beginShadowPass` for why it left it. */
         this.gl.depthFunc(glDepthFuncEqual(this.gl));
         this.gl.clearDepth(this.depthClear);
@@ -4212,6 +4374,70 @@ export class WebGL2Renderer {
     setCameraMotionBlur(scale) {
         this.motionBlurScale = Math.min(Math.max(scale, 0), 1);
     }
+    /**
+     * The camera has cut: this frame is a new shot, not the next moment of the last one.
+     *
+     * **Everything temporal reprojects through the previous frame's view**: the motion blur measures
+     * its smear against it, and the temporal resolve reads its history through it. A cut is a jump
+     * the renderer cannot tell from a fast camera, so without this a transport that seeks, a respawn
+     * or an edit smears its first frame along the whole jump and blends in a picture of somewhere
+     * else. The caller knows it cut; this is how it says so, before the frame's `beginFrame`.
+     *
+     * What it gives up is one frame of history: the frame after a cut has no blur and no temporal
+     * blend, as the first frame of a session has none. Nothing else is reset.
+     */
+    cameraCut() {
+        this.hasPreviousView = false;
+        this.temporalHistory.invalidate();
+        /* The eye was adapted to the last shot. */
+        this.sceneTarget?.cutExposure();
+    }
+    /**
+     * **Eye adaptation**: how far the frame's exposure follows its own brightness, 0 to 1, and the
+     * seconds since the last frame. 0 is off and the default, and at 0 nothing is metered or allocated.
+     *
+     * The finished scene is metered on the GPU each frame — the log-mean of its luminance — and a
+     * held brightness moves toward it at a fixed rate, about 78% of the way in a second; the composite
+     * then scales scene light toward middle grey by \`strength\` of the stops between them, at most six
+     * either way. So a shaded courtyard floor opens up the way a camera or an eye would, and
+     * \`setOutputExposure\` becomes a bias on top: a night kept darker than a day is a bias under one.
+     * **The time is the caller's**, because the engine takes time from its caller; a held capture
+     * passes 0 and holds. \`cameraCut\` snaps it, so a new shot is metered rather than eased into.
+     *
+     * What it gives up is regional metering: every pixel counts the same. Needs \`screenEffects\` and
+     * \`hdrScene\`, and says so once rather than doing nothing. See \`shaders/exposure.ts\`.
+     */
+    setAutoExposure(strength, dtSec) {
+        if (this.sceneTarget === null || !this.quality.hdrScene) {
+            this.warnLookWithoutComposite(strength);
+            return;
+        }
+        this.sceneTarget.setAutoExposure(strength, dtSec);
+    }
+    /**
+     * **Local exposure**: how far each region of the frame is brought toward the frame's own
+     * brightness, 0 to 1. 0 is off and the default, and at 0 nothing more is measured or allocated.
+     *
+     * A tone curve maps one range, and a sunlit courtyard is two: its shaded arcades hold a fiftieth
+     * of the light on its sunlit paving, so exposed for either the other is black or white. This moves
+     * each region `strength` of the stops between it and the frame's held brightness, at most three,
+     * read from a bilateral grid over the exposure meter's tiles, so shade beside sun is lifted as
+     * shade rather than as the average of the two. The eye's held brightness is what regions move
+     * toward, so it is measured whether or not `setAutoExposure` is on; with adaptation off the frame
+     * as a whole keeps the exposure it was given. About 0.5 is a photograph's latitude, and 1 is a
+     * frame with no light and shade left in it.
+     *
+     * What it gives up is contrast between regions, which is the point, and a halo a tile wide where
+     * two regions of one brightness band differ. Needs `screenEffects` and `hdrScene`, and says so
+     * once rather than doing nothing. See `shaders/localExposure.ts`.
+     */
+    setLocalExposure(strength) {
+        if (this.sceneTarget === null || !this.quality.hdrScene) {
+            this.warnLookWithoutComposite(strength);
+            return;
+        }
+        this.sceneTarget.setLocalExposure(strength);
+    }
     /**
      * Where this frame's lens is focused, how deep the sharp zone is, and how much of the ceiling
      * to take.
@@ -4264,9 +4490,18 @@ export class WebGL2Renderer {
      *
      * Set before `beginFrame` and held until changed. Ignored entirely when `bloom` is 0, since
      * the chain is never built.
+     *
+     * **`threshold` moves `bloomThreshold` for this frame and every one after**, in the same scene
+     * units. A threshold is compared before exposure is applied, so one fixed at construction means a
+     * different brightness on screen at every exposure. That is harmless while exposure stands still
+     * 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.
      */
-    setBloom(scale) {
+    setBloom(scale, threshold) {
         this.bloomScale = Math.min(Math.max(scale, 0), 1);
+        if (threshold !== undefined)
+            this.bloomThresholdSet = bloomThresholdOf(threshold);
     }
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
@@ -4400,6 +4635,38 @@ export class WebGL2Renderer {
         }
         this.sceneTarget.setColourGrade(lut, strength);
     }
+    /**
+     * How strongly the lens darkens the frame's corners, held until changed: 0 is none, 0.5 is about
+     * 1.2 stops at the corner. Applied to scene light before the tone curve, as a lens loses light;
+     * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
+     */
+    setVignette(strength) {
+        if (this.sceneTarget === null) {
+            this.warnLookWithoutComposite(strength);
+            return;
+        }
+        this.sceneTarget.setVignette(strength);
+    }
+    /**
+     * 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
+     * its caller: pass a new one each frame for grain that moves, and the same one for a still that
+     * is identical run to run. Applied last, after the grade and the veil; see `filmLook.ts`.
+     */
+    setFilmGrain(strength, seed) {
+        if (this.sceneTarget === null) {
+            this.warnLookWithoutComposite(strength);
+            return;
+        }
+        this.sceneTarget.setFilmGrain(strength, seed);
+    }
+    warnedLookWithoutComposite = false;
+    warnLookWithoutComposite(strength) {
+        if (strength > 0 && !this.warnedLookWithoutComposite) {
+            this.warnedLookWithoutComposite = true;
+            console.warn(FILM_LOOK_WITHOUT_COMPOSITE);
+        }
+    }
     /**
      * What this frame asked for. **Every ceiling here is `null`, and that is the finding.**
      *
@@ -4716,7 +4983,10 @@ export class WebGL2Renderer {
          */
         const bloomStrength = this.quality.bloom * this.bloomScale;
         const bloom = bloomStrength > 0
-            ? { strength: bloomStrength, threshold: this.quality.bloomThreshold }
+            ? {
+                strength: bloomStrength,
+                threshold: this.bloomThresholdSet ?? this.quality.bloomThreshold,
+            }
             : undefined;
         /* The grade travels to the resolve only where the mesh pass gave it up. See `bindMeshPass`. */
         const lateGrade = this.quality.hdrScene
@@ -4885,11 +5155,12 @@ export class WebGL2Renderer {
                     sunShadow,
                     lightViewProj: env?.lightViewProj ?? IDENTITY_MAT4,
                     /* The placeholder rather than null where a map is merely absent, for the reason
-                       `emptyTexture.ts` gives: white is depth 1, the far plane, nothing in the way. */
+                       `emptyTexture.ts` gives. It is black, which as a depth is an occluder at the light,
+                       so it is safe only because `sunShadow` is 0 whenever these maps do not exist. */
                     staticShadowMap: this.shadowMap?.texture ?? this.emptyTexture2D,
                     peeledShadowMap: this.peeledShadowMap?.texture ?? this.emptyTexture2D,
                     dynamicShadowMap: this.dynamicShadowMap?.texture ?? this.emptyTexture2D,
-                    peeledEnabled: this.peeledShadowMap !== null,
+                    peeledEnabled: this.peelFilled,
                 });
                 if (marched) {
                     /* The march finished on the default framebuffer, which is not where the frame is being
@@ -5093,6 +5364,78 @@ export class WebGL2Renderer {
         /* Leave the plain program current, which is what every other pass expects to find. */
         this.useFlatProgram();
     }
+    /**
+     * Sum a scene's many fixed lights into a DriftLight field, which stands in for each of them
+     * wherever the frame's choice of exact lights does not reach. See `driftLight/lightField.ts`.
+     *
+     * Replaces any field made before. The scene then paces `field.bake(bricks)` and calls
+     * `field.follow(buffer.complete, ...)` each frame with the selection that chose its exact lights;
+     * the volume is summed into the frame once every brick has landed.
+     */
+    createLightField(lights, options = {}) {
+        this.forgetLightFieldVolumes();
+        const field = new LightField(lights, { ...options, falloff: this.quality.pointLightFalloff });
+        this.lightField = field;
+        return field;
+    }
+    /** Let go of the field and its volumes; the scene's lights are all exact again. */
+    disposeLightField() {
+        this.forgetLightFieldVolumes();
+        this.lightField = null;
+    }
+    forgetLightFieldVolumes() {
+        if (this.driftIndex !== null)
+            this.gl.deleteTexture(this.driftIndex);
+        if (this.driftAtlas !== null)
+            this.gl.deleteTexture(this.driftAtlas);
+        this.driftIndex = null;
+        this.driftAtlas = null;
+    }
+    /**
+     * Upload the field's two volumes, once, when its last brick has baked: nothing samples them
+     * before that, so uploading as bricks land would be work for no picture.
+     */
+    uploadLightField() {
+        const field = this.lightField;
+        if (field === null || this.driftAtlas !== null || !field.ready || field.layout.count === 0) {
+            return;
+        }
+        const { gl } = this;
+        const [ix, iy, iz] = field.layout.dims;
+        const index = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_3D, index);
+        gl.texImage3D(gl.TEXTURE_3D, 0, gl.R32UI, ix, iy, iz, 0, gl.RED_INTEGER, gl.UNSIGNED_INT, field.layout.index);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        const [aw, ah, ad] = field.atlasSize;
+        const atlas = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_3D, atlas);
+        gl.texImage3D(gl.TEXTURE_3D, 0, gl.RGBA16F, aw, ah, ad, 0, gl.RGBA, gl.HALF_FLOAT, field.atlas);
+        /* Filtered, because a brick's samples share their faces: the lookup is seamless inside one. */
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_3D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        for (const wrap of [gl.TEXTURE_WRAP_S, gl.TEXTURE_WRAP_T, gl.TEXTURE_WRAP_R]) {
+            gl.texParameteri(gl.TEXTURE_3D, wrap, gl.CLAMP_TO_EDGE);
+        }
+        gl.bindTexture(gl.TEXTURE_3D, null);
+        this.driftIndex = index;
+        this.driftAtlas = atlas;
+    }
+    /** The field's uniforms and volumes for this pass, or the stand-ins that switch it off. */
+    bindDriftLight(u, eye) {
+        const { gl } = this;
+        this.uploadLightField();
+        const d = this.driftUniforms;
+        resolveDriftLight(this.driftAtlas === null ? null : this.lightField, this.probePassActive, eye, d);
+        gl.uniform4fv(u['uDriftLight'] ?? null, d.light);
+        gl.uniform4fv(u['uDriftLightOrigin'] ?? null, d.origin);
+        gl.activeTexture(gl.TEXTURE0 + DRIFT_LIGHT_INDEX_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_3D, this.driftIndex ?? this.emptyDriftIndex);
+        gl.uniform1i(u['uDriftLightIndex'] ?? null, DRIFT_LIGHT_INDEX_TEXTURE_UNIT);
+        gl.activeTexture(gl.TEXTURE0 + DRIFT_LIGHT_ATLAS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_3D, this.driftAtlas ?? this.emptyDriftAtlas);
+        gl.uniform1i(u['uDriftLightAtlas'] ?? null, DRIFT_LIGHT_ATLAS_TEXTURE_UNIT);
+    }
     /**
      * Everything one flat program needs to know about this frame.
      *
@@ -5221,7 +5564,7 @@ export class WebGL2Renderer {
         gl.uniform1f(u['uShadowMapSize'] ?? null, this.quality.directionalShadowMapSize);
         gl.uniform1f(u['uShadowDepthSpan'] ?? null, env.shadowDepthSpan);
         gl.uniform1f(u['uShadowMaxDistance'] ?? null, this.quality.directionalShadowMaxDistance);
-        gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, this.peeledShadowMap === null ? 0 : 1);
+        gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, this.peelFilled ? 1 : 0);
         gl.uniform1f(u['uShadowMaxSlope'] ?? null, this.quality.directionalShadowMaxSlope);
         gl.uniform1i(u['uShadowFilterTaps'] ?? null, this.quality.shadowFilterTaps);
         gl.uniform3fv(u['uHighlightMin'] ?? null, env.highlightMin);
@@ -5296,11 +5639,19 @@ export class WebGL2Renderer {
          * zero would not be enough on its own — a driver may fetch a sampler's descriptor before it
          * evaluates the arithmetic that discards the result, which is the same reason
          * `emptyTexture.ts` exists.
+         *
+         * **Except a bounce bake, which reads it on purpose.** Its faces are drawn into the capture
+         * cube, and the array is attached only by the convolution after them, so no pass both samples
+         * and attaches it.
          */
         if (this.probeCapture !== null) {
             const array = this.probeArray;
             const grid = this.probes;
-            const usable = array !== null && grid !== null && array.ready && !this.probePassActive;
+            const usable = array !== null &&
+                grid !== null &&
+                array.usable &&
+                this.probeSweeps?.ready === true &&
+                (!this.probePassActive || this.probeBounce);
             gl.activeTexture(gl.TEXTURE0 + ENVIRONMENT_TEXTURE_UNIT);
             gl.bindTexture(gl.TEXTURE_2D_ARRAY, usable ? array.texture : this.emptyTexture2DArray);
             gl.uniform1i(u['uEnvironment'] ?? null, ENVIRONMENT_TEXTURE_UNIT);
@@ -5341,13 +5692,19 @@ export class WebGL2Renderer {
              * times over two days as four different bugs before it could be asked for.
              */
             gl.uniform1f(u['uProbeGridAmbient'] ?? null, usable && this.probeAmbient ? 1 : 0);
+            /* Which sets the shading reads, and how far between them. See `probeSweeps.ts`. */
+            const sets = this.probeSweeps?.uniforms(this.probeSets) ?? this.probeSets.fill(0);
+            gl.uniform3f(u['uProbeGridSets'] ?? null, sets[0] ?? 0, sets[1] ?? 0, sets[2] ?? 0);
         }
+        this.bindDriftLight(u, camera.position);
         gl.activeTexture(gl.TEXTURE0 + SURFACE_TEXTURE_UNIT);
         gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
         gl.uniform1i(u['uAlbedo'] ?? null, SURFACE_TEXTURE_UNIT);
         gl.uniform1i(u['uAlbedoEnabled'] ?? null, 0);
         gl.uniform2f(u['uUvScale'] ?? null, 1, 1);
         gl.uniform1f(u['uAlbedoCutout'] ?? null, 0);
+        gl.uniform1i(u['uDoubleSided'] ?? null, 0);
+        this.materialDoubleSided = false;
         this.currentSurfaceTexture = null;
         /*
          * **And the normal map, which this did not reset and had to.**
@@ -5573,7 +5930,11 @@ export class WebGL2Renderer {
          */
         gl.depthFunc(this.reversedDepth ? gl.GREATER : gl.LESS);
         if (layer === 0) {
+            if (this.materialDoubleSided)
+                gl.disable(gl.CULL_FACE);
             mesh.draw(gl);
+            if (this.materialDoubleSided)
+                gl.enable(gl.CULL_FACE);
             gl.depthFunc(this.reversedDepth ? gl.GEQUAL : gl.LEQUAL);
             if (tint !== null)
                 gl.uniform3fv(u['uTint'] ?? null, WHITE_TINT);
@@ -5594,7 +5955,11 @@ export class WebGL2Renderer {
          */
         const offset = depthOffsetForLayer(layer, this.reversedDepth);
         gl.polygonOffset(offset.slope, offset.units);
+        if (this.materialDoubleSided)
+            gl.disable(gl.CULL_FACE);
         mesh.draw(gl);
+        if (this.materialDoubleSided)
+            gl.enable(gl.CULL_FACE);
         gl.polygonOffset(0, 0);
         gl.disable(gl.POLYGON_OFFSET_FILL);
         if (program !== null)
@@ -5749,7 +6114,11 @@ export class WebGL2Renderer {
             gl.enable(gl.POLYGON_OFFSET_FILL);
             gl.polygonOffset(offset.slope, offset.units);
         }
+        if (this.materialDoubleSided)
+            gl.disable(gl.CULL_FACE);
         mesh.draw(gl);
+        if (this.materialDoubleSided)
+            gl.enable(gl.CULL_FACE);
         if (offset.units !== 0) {
             gl.polygonOffset(0, 0);
             gl.disable(gl.POLYGON_OFFSET_FILL);
@@ -5824,7 +6193,8 @@ export class WebGL2Renderer {
             return true;
         this.probeArray?.dispose(this.gl);
         this.probes = grid;
-        this.probeArray = new EnvProbeArray(this.gl, octahedralEdgeFor(this.quality.reflectionProbeSize), grid.layers, this.quality.hdrScene);
+        this.probeSweeps = new ProbeSweeps(grid.layers, grid.crossfade);
+        this.probeArray = new EnvProbeArray(this.gl, octahedralEdgeFor(this.quality.reflectionProbeSize), grid.layers * this.probeSweeps.sets, this.quality.hdrScene);
         return this.probeArray.usable;
     }
     /**
@@ -5844,12 +6214,14 @@ export class WebGL2Renderer {
         const probe = this.probeCapture;
         const array = this.probeArray;
         const grid = this.probes;
-        if (probe === null || array === null || grid === null)
+        const sweeps = this.probeSweeps;
+        if (probe === null || array === null || grid === null || sweeps === null)
             return false;
         if (layer < 0 || layer >= grid.layers)
             return false;
         this.probeAmbient = options?.irradiance ?? true;
         grid.positionOf(layer, this.probeOrigin);
+        this.probeBounce = options?.bounce ?? false;
         this.probePassActive = true;
         /*
          * **A probe stores radiance, not display pixels.**
@@ -5887,14 +6259,19 @@ export class WebGL2Renderer {
         this.gl.frontFace(this.gl.CW);
         let baked = false;
         try {
-            baked = probe.bake(this.gl, this.probeOrigin, clearColor, drawFace);
+            const [first, end] = probeFaceRange(options);
+            baked = probe.bake(this.gl, this.probeOrigin, clearColor, drawFace, first, end);
+            /* A bake that has not reached its sixth face has nothing whole to convolve yet. */
+            if (end < 6)
+                return baked;
             /*
              * The convolution, immediately after the faces and inside the same guard, because it reads
              * the chain `bake` has just generated. A bake that failed leaves the layer untouched rather
              * than convolving whatever the driver left in the capture.
              */
             if (baked && this.environmentPrefilter !== null) {
-                this.environmentPrefilter.run(this.gl, probe, array, layer, ENVIRONMENT_TEXTURE_UNIT, this.quality.environmentPrefilterSamples, this.quality.environmentPrefilter);
+                this.environmentPrefilter.run(this.gl, probe, array, sweeps.writeLayer(layer), ENVIRONMENT_TEXTURE_UNIT, this.quality.environmentPrefilterSamples, this.quality.environmentPrefilter);
+                sweeps.baked(layer);
             }
         }
         finally {
@@ -5908,6 +6285,7 @@ export class WebGL2Renderer {
              * later frame reading the placeholder and quietly reflecting nothing.
              */
             this.probePassActive = false;
+            this.probeBounce = false;
             /* Back to the canvas, or to the frame's own target if one is bound. See `SceneTarget`. */
             if (this.sceneTarget !== null && !this.framePresented)
                 this.sceneTarget.bind();
@@ -5963,6 +6341,7 @@ export class WebGL2Renderer {
             return false;
         this.probeAmbient = options?.irradiance ?? true;
         this.environmentPrefilter?.run(this.gl, probe, array, 0, ENVIRONMENT_TEXTURE_UNIT, this.quality.environmentPrefilterSamples, this.quality.environmentPrefilter);
+        this.probeSweeps?.baked(0);
         return true;
     }
     /**
@@ -6085,7 +6464,7 @@ export class WebGL2Renderer {
                    lookup does its own `* 0.5 + 0.5` and correcting the matrix as well doubles it. */
                 gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, env.lightViewProj);
                 gl.uniform1f(u['uShadowMapSize'] ?? null, this.quality.directionalShadowMapSize);
-                gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, this.peeledShadowMap === null ? 0 : 1);
+                gl.uniform1i(u['uPeeledShadowEnabled'] ?? null, this.peelFilled ? 1 : 0);
                 gl.activeTexture(gl.TEXTURE0);
                 gl.bindTexture(gl.TEXTURE_2D, this.shadowMap?.texture ?? this.emptyTexture2D);
                 gl.uniform1i(u['uStaticShadowMap'] ?? null, 0);