@driftengine/core 4.5.0 → 4.6.0

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

@@ -1,5 +1,6 @@
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
+import { FOG_RECEDE, fogModeOf } from '../drawFog.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 { resolveGlass } from '../../glass.js';
@@ -16,6 +17,7 @@ import { OIT_MULTISAMPLE_REFUSAL } from '../../orderIndependent.js';
 import { INDIRECT_LIGHT_WEBGL2_REFUSAL } from '../../gi/probeTrace.js';
 import { TranslucentQueue } from '../../translucentQueue.js';
 import { createFrustum, frustumFromViewProjection } from '../../../math/frustum.js';
+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';
@@ -32,6 +34,7 @@ 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 { WorldLightField } from '../../driftLight/worldLightField.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';
@@ -47,6 +50,8 @@ import { ProbeSweeps } from '../../probeSweeps.js';
 import { octahedralEdgeFor } from '../../prefilterEnvMap.js';
 import { EnvironmentPrefilterPass } from '../../prefilterPass.js';
 import { packIesAtlas } from '../../iesProfile.js';
+import { fixtureAtlasLayout, fixtureAtlasTexels } from '../../fixtureAtlas.js';
+import { resolveSurfaceScene } from '../../surfaceScene.js';
 import { MAX_AREA_LIGHTS } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { equirectToCubeFaces } from '../../equirectToCube.js';
@@ -62,7 +67,7 @@ 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, 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 { 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 { resolveRenderQuality } from '../../renderQuality.js';
 import { drawingBufferSize } from '../../drawingBuffer.js';
 import { Mesh, createMeshIncremental } from '../../mesh.js';
@@ -236,6 +241,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`. */
 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);
 /** Handed to the shader when a batch has no press field. See `drawScatter`. */
 /**
  * What a contributed pass pre-multiplies its projection by on this backend: nothing.
@@ -546,6 +553,11 @@ export class WebGL2Renderer {
     oitActive = false;
     /** True while the queue is being replayed, so a replayed draw does not record itself again. */
     oitReplaying = false;
+    /** `uSurfaceScene`, resolved once a pass. See `surfaceScene.ts`. */
+    surfaceScene = new Float32Array(4);
+    /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
+    oitWeight = 0;
+    ditherFade = 0;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     oitRefused = false;
     /** Said once for the whole renderer. See `refuseOitMultisampled`. */
@@ -639,6 +651,8 @@ export class WebGL2Renderer {
     taaDepthToViewZ = Float32Array.of(0, 0, 0, 1);
     aoInvProjection = mat4.create();
     aoProjScale = new Float32Array(2);
+    /** Where this frame's jitter put the occlusion, in the composite's uv. See `uAoOffset`. */
+    aoOffset = new Float32Array(2);
     /**
      * Whether this frame has already been resolved to the canvas.
      *
@@ -730,12 +744,15 @@ export class WebGL2Renderer {
      * world. See `prepareStaticPointShadows`.
      */
     pointShadowArray = null;
-    /** The photometric atlas, allocated on first use. See `setIesProfiles`. */
-    iesTexture = null;
-    /** Rows in that atlas. One until a consumer loads a profile, which is the row of ones. */
+    /** The fixture atlas — cookies over profiles — allocated on first use. See `fixtureAtlas.ts`. */
+    fixtureTexture = null;
+    /** The profiles as packed, kept so a new set of cookies can rebuild the atlas around them. */
+    iesAtlas = packIesAtlas([]);
+    /** The cookie images, kept so a new set of profiles can rebuild the atlas around them. */
+    cookieImages = [];
+    /** Rows of profile in the atlas. One until a consumer loads a profile, which is the row of ones. */
     iesRows = 1;
-    cookieTexture = null;
-    /** Tiles in the cookie atlas. 0 is the white placeholder and the whole off path. */
+    /** Cookie tiles in the atlas. 0 is none, and the whole off path. */
     cookieTiles = 0;
     /** Horizontal planes each profile occupies. 1 unless something asymmetric was loaded. */
     iesPlanes = 1;
@@ -1036,7 +1053,7 @@ export class WebGL2Renderer {
             if (cutout !== null) {
                 gl.useProgram(this.depthInstancedCutoutProgram);
                 this.bindCutoutDepth(this.depthInstancedCutoutUniforms, cutout);
-                gpuBatch.mesh.drawInstances(gl, count);
+                gpuBatch.draw(gl, count);
                 if (twoSided && this.depthPassCullsFaces)
                     gl.enable(gl.CULL_FACE);
                 gl.useProgram(this.depthProgram);
@@ -1049,7 +1066,7 @@ export class WebGL2Renderer {
             gl.uniform1i(u['uPeelShadowLayer'] ?? null, this.activeDepthPeel ? 1 : 0);
             if (this.activeDepthPeel)
                 gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
-            gpuBatch.mesh.drawInstances(gl, count);
+            gpuBatch.draw(gl, count);
             if (twoSided && this.depthPassCullsFaces)
                 gl.enable(gl.CULL_FACE);
             gl.useProgram(this.depthProgram);
@@ -1305,6 +1322,13 @@ export class WebGL2Renderer {
     occluded(bounds, model) {
         return this.occlusion?.occluded(bounds, model) ?? false;
     }
+    /**
+     * Whether a world-space box is wholly behind the declared occluders — the tighter question for
+     * something that is a box, such as a region. False with no occlusion buffer. See `occluded`.
+     */
+    occludedBox(min, max) {
+        return this.occlusion?.occludedBox(min, max) ?? false;
+    }
     /* -- Registered passes ---------------------------------------------------------------- */
     passes = createPassRegistry();
     /** Built once so invoking somebody else's pass allocates nothing. See `PassDefinition.draw`. */
@@ -1478,80 +1502,57 @@ export class WebGL2Renderer {
      * `createSurfaceTexture` and the material maps take.
      */
     setSpotCookies(images) {
-        const { gl } = this;
-        this.cookieTiles = images.length;
-        if (this.cookieTexture === null)
-            this.cookieTexture = gl.createTexture();
-        gl.activeTexture(gl.TEXTURE0 + COOKIE_ATLAS_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.cookieTexture);
-        if (images.length === 0) {
-            /* White, not black: this multiplies a light's colour. */
-            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([255, 255, 255, 255]));
-        }
-        else {
-            gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, COOKIE_TILE * images.length, COOKIE_TILE, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
-            for (let tile = 0; tile < images.length; tile++) {
-                const image = images[tile];
-                if (image === undefined)
-                    continue;
-                gl.texSubImage2D(gl.TEXTURE_2D, 0, tile * COOKIE_TILE, 0, gl.RGBA, gl.UNSIGNED_BYTE, image);
-            }
-        }
-        /* Linear and clamped: a cookie is an image, and the shader's own inset is what keeps a tile
-           from reaching its neighbour — clamping alone cannot, the seam being interior to the row. */
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-        gl.activeTexture(gl.TEXTURE0);
+        this.cookieImages = images.slice();
+        this.buildFixtureAtlas();
     }
     setIesProfiles(profiles) {
+        this.iesAtlas = packIesAtlas(profiles);
+        this.buildFixtureAtlas();
+    }
+    /**
+     * The fixture atlas from the profiles and cookies in hand: the profiles' rows at the bottom, the
+     * cookies' tiles on top, one `RGBA16F` texture. See `fixtureAtlas.ts` for the layout.
+     *
+     * **Half float, matching what the other backend must use**: a 32-bit float texture is not
+     * filterable in core WebGPU, and both tables are curves and images that want linear filtering.
+     * Linear and clamped: a profile is sampled between two angles, and a cookie's own inset is what
+     * keeps a tile from its neighbour — clamping alone cannot, the seam being interior to the row.
+     */
+    buildFixtureAtlas() {
         const { gl } = this;
-        const atlas = packIesAtlas(profiles);
-        if (this.iesTexture === null)
-            this.iesTexture = gl.createTexture();
-        gl.activeTexture(gl.TEXTURE0 + IES_ATLAS_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.iesTexture);
-        /*
-         * `LINEAR` across a row and clamped, unlike the froxel table's `NEAREST`. This one *is* a
-         * curve rather than data addressed by index: interpolating between two columns is sampling
-         * the distribution between two angles, which is exactly what is wanted, and clamping stops a
-         * row bleeding into its neighbour at the edges.
-         */
+        const layout = fixtureAtlasLayout(this.iesAtlas.height, this.cookieImages.length);
+        if (this.fixtureTexture === null)
+            this.fixtureTexture = gl.createTexture();
+        gl.activeTexture(gl.TEXTURE0 + FIXTURE_ATLAS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, this.fixtureTexture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, layout.width, layout.height, 0, gl.RGBA, gl.FLOAT, fixtureAtlasTexels(layout, this.iesAtlas));
+        for (let tile = 0; tile < this.cookieImages.length; tile++) {
+            const image = this.cookieImages[tile];
+            if (image === undefined)
+                continue;
+            gl.texSubImage2D(gl.TEXTURE_2D, 0, tile * COOKIE_TILE, 0, gl.RGBA, gl.HALF_FLOAT, image);
+        }
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
         gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
-        /*
-         * One channel, because a row holds one number per angle and the other three would be three
-         * quarters of the upload spent on nothing — and **half float rather than full**, matching what
-         * the other backend must use: a 32-bit float texture is not filterable in core WebGPU, and this
-         * row is a curve that wants linear filtering. Keeping the two formats the same is the
-         * 2026-08-13 rule rather than tidiness; the driver converts the float data on the way in.
-         */
-        gl.texImage2D(gl.TEXTURE_2D, 0, gl.R16F, atlas.width, atlas.height, 0, gl.RED, gl.FLOAT, atlas.data);
-        this.iesRows = atlas.height;
-        this.iesPlanes = atlas.planes;
+        this.iesRows = this.iesAtlas.height;
+        this.iesPlanes = this.iesAtlas.planes;
+        this.cookieTiles = this.cookieImages.length;
         gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.activeTexture(gl.TEXTURE0);
     }
-    /** Bind the atlas and say how many rows it has. Always, for the reason `bindClusters` gives. */
+    /** Bind the fixture atlas and say what is in it. Always, for the reason `bindClusters` gives. */
     bindIesAtlas(u) {
         const { gl } = this;
-        if (this.iesTexture === null)
-            this.setIesProfiles([]);
-        gl.activeTexture(gl.TEXTURE0 + IES_ATLAS_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.iesTexture);
-        gl.uniform1i(u['uIesAtlas'] ?? null, IES_ATLAS_TEXTURE_UNIT);
+        /* Built on demand rather than at construction, for the reason the grade's placeholder is. */
+        if (this.fixtureTexture === null)
+            this.buildFixtureAtlas();
+        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);
-        /* Built on demand rather than at construction, for the reason the grade's placeholder is: a
-           scene that never projects a cookie should not carry a texture, and a declared sampler still
-           needs a complete one. */
-        if (this.cookieTexture === null)
-            this.setSpotCookies([]);
-        gl.activeTexture(gl.TEXTURE0 + COOKIE_ATLAS_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.cookieTexture);
-        gl.uniform1i(u['uCookieAtlas'] ?? null, COOKIE_ATLAS_TEXTURE_UNIT);
         gl.uniform1f(u['uCookieTiles'] ?? null, this.cookieTiles);
         gl.activeTexture(gl.TEXTURE0);
     }
@@ -2180,10 +2181,8 @@ export class WebGL2Renderer {
             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.fixtureTexture !== null)
+                gl.deleteTexture(this.fixtureTexture);
             if (this.clusterTexture !== null)
                 gl.deleteTexture(this.clusterTexture);
         }
@@ -2331,6 +2330,15 @@ export class WebGL2Renderer {
     createSurfaceTexture(source, options = {}) {
         return new SurfaceTexture(this.gl, source, options);
     }
+    /**
+     * Upload several images of one size as the layers of one array, for a merged mesh that names a
+     * layer per vertex (`MeshData.layers`). One material binding then covers every image, which is
+     * what makes a block wearing forty facades one draw. Every layer must be the same size, and the
+     * refusal names the first that is not.
+     */
+    createSurfaceTextureArray(sources, options = {}) {
+        return new SurfaceTexture(this.gl, sources, options);
+    }
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -2444,7 +2452,7 @@ export class WebGL2Renderer {
          * page-faulted an RDNA4 card and wedged the device. See `emptyTexture.ts`.
          */
         gl.activeTexture(gl.TEXTURE0 + NORMAL_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (normal !== null)
             normal.bind(gl, NORMAL_TEXTURE_UNIT);
         gl.uniform1i(u['uNormalMap'] ?? null, NORMAL_TEXTURE_UNIT);
@@ -2462,7 +2470,7 @@ export class WebGL2Renderer {
          */
         const orm = material?.orm ?? null;
         gl.activeTexture(gl.TEXTURE0 + ORM_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (orm !== null)
             orm.bind(gl, ORM_TEXTURE_UNIT);
         gl.uniform1i(u['uOrmMap'] ?? null, ORM_TEXTURE_UNIT);
@@ -2480,7 +2488,7 @@ export class WebGL2Renderer {
          */
         const emissiveMap = material?.emissive ?? null;
         gl.activeTexture(gl.TEXTURE0 + EMISSIVE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         if (emissiveMap !== null)
             emissiveMap.bind(gl, EMISSIVE_TEXTURE_UNIT);
         gl.uniform1i(u['uEmissiveMap'] ?? null, EMISSIVE_TEXTURE_UNIT);
@@ -2496,7 +2504,21 @@ export class WebGL2Renderer {
          */
         gl.uniform2f(u['uUvScale'] ?? null, material?.uScale ?? 1, material?.vScale ?? 1);
         gl.uniform1i(u['uDoubleSided'] ?? null, material?.doubleSided === true ? 1 : 0);
+        /* 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) {
+            gl.activeTexture(gl.TEXTURE0 + SURFACE_EFFECTS_TEXTURE_UNIT);
+            gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        }
+        else {
+            albedo.bindEffects(gl, SURFACE_EFFECTS_TEXTURE_UNIT, this.emptyTexture2D);
+        }
+        gl.uniform1i(u['uSurfaceEffects'] ?? null, SURFACE_EFFECTS_TEXTURE_UNIT);
+        if (albedo === null) {
+            /* The array stand-in, for the reason the maps above take one: a sampler reads its unit's
+               array target, and with nothing there it is incomplete. */
+            gl.activeTexture(gl.TEXTURE0 + SURFACE_TEXTURE_UNIT);
+            gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
             gl.uniform1i(u['uAlbedoEnabled'] ?? null, 0);
             return;
         }
@@ -2531,7 +2553,7 @@ export class WebGL2Renderer {
             return;
         }
         gl.activeTexture(gl.TEXTURE0 + SURFACE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     }
     /**
      * A pass-level scale over the grain the geometry itself declared, 0 to 1.
@@ -2559,8 +2581,7 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.useFlatProgram();
-        this.gl.uniform1f(this.flatUniforms['uReflectivity'] ?? null, Math.min(1, Math.max(0, amount)));
+        this.writeFlatFloat('uReflectivity', Math.min(1, Math.max(0, amount)));
     }
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
@@ -2578,8 +2599,7 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.useFlatProgram();
-        this.gl.uniform1f(this.flatUniforms['uEnvironmentGain'] ?? null, Math.max(0, gain));
+        this.writeFlatFloat('uEnvironmentGain', Math.max(0, gain));
     }
     /**
      * Kept as a no-op that says so once, because it was a stand-in for a term that now exists.
@@ -2606,8 +2626,51 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
+        this.writeFlatFloat('uGrain', Math.min(1, Math.max(0, amount)));
+    }
+    /**
+     * One float of material state, into every flat program.
+     *
+     * **Every one, for `setMaterial`'s reason**: an instanced or skinned draw runs a program of its
+     * own and is entitled to the material its caller set before it. These setters wrote the plain
+     * program alone until 2026-09-30, so on this backend a batch drew with the pass defaults — grain
+     * full, no reflection, no relief — while the other backend, whose material block every variant
+     * reads, drew what was asked.
+     */
+    writeFlatFloat(name, value) {
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.gl.uniform1f(target.uniforms[name] ?? null, value);
+        }
+        this.useFlatProgram();
+    }
+    /**
+     * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
+     * of detail of one thing.
+     *
+     * 0 is off and is what `bindMeshPass` restores. A positive amount keeps that share of the
+     * pattern's cells, a negative one keeps the complement, so the level fading in drawn at `t` and
+     * the one fading out at `-t` cover every pixel exactly once — no hole, no pixel drawn twice.
+     * Material state like `setSurfaceGrain`; instanced draws read it too, and shadow casters, which
+     * are a pass of their own, do not. See `uDither` in `flat/preamble.ts` for what it costs.
+     */
+    setDitherFade(amount) {
+        if (this.contextLost)
+            return;
+        this.materials.dirty();
+        this.useFlatProgram();
+        this.ditherFade = Math.min(1, Math.max(-1, amount));
+        /* Every flat program, as `setMaterial` writes them: an instanced or skinned draw is entitled
+           to the fade the caller set before it, and a second program holding none draws whole. */
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.writeMode(target.uniforms);
+        }
         this.useFlatProgram();
-        this.gl.uniform1f(this.flatUniforms['uGrain'] ?? null, Math.min(1, Math.max(0, amount)));
+    }
+    /** `uWriteMode`: the order-independent weight and the dither, which share one uniform row. */
+    writeMode(u) {
+        this.gl.uniform2f(u['uWriteMode'] ?? null, this.oitWeight, this.ditherFade);
     }
     /**
      * How strong the microscopic relief on the surfaces drawn next is, and how coarse.
@@ -2636,10 +2699,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.useFlatProgram();
-        const u = this.flatUniforms;
-        this.gl.uniform1f(u['uRelief'] ?? null, Math.min(1, Math.max(0, amount)));
-        this.gl.uniform1f(u['uReliefCycles'] ?? null, Math.max(0.01, cyclesPerMetre));
+        this.writeFlatFloat('uRelief', Math.min(1, Math.max(0, amount)));
+        this.writeFlatFloat('uReliefCycles', Math.max(0.01, cyclesPerMetre));
     }
     /**
      * How hard the bound surface texture's own luminance turns the shading normal, 0 for not at all.
@@ -2670,8 +2731,7 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.useFlatProgram();
-        this.gl.uniform1f(this.flatUniforms['uTextureRelief'] ?? null, Number.isFinite(scale) ? scale : 0);
+        this.writeFlatFloat('uTextureRelief', Number.isFinite(scale) ? scale : 0);
     }
     /**
      * Release a mesh's GPU buffers.
@@ -2698,8 +2758,7 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.materials.dirty();
-        this.useFlatProgram();
-        this.gl.uniform1f(this.flatUniforms['uEmissiveGain'] ?? null, gain);
+        this.writeFlatFloat('uEmissiveGain', gain);
     }
     /* -- Instanced meshes --------------------------------------------------------------- */
     /** The instanced program, compiled on first use. See `ensureInstancedProgram`. */
@@ -2738,7 +2797,7 @@ export class WebGL2Renderer {
      * One batch per mesh: the attributes bind to the mesh's own vertex array, of which a mesh has
      * one. `Mesh.attachInstances` is what refuses a second, and says why.
      */
-    createInstanced(mesh, capacity) {
+    createInstanced(mesh, capacity, options = {}) {
         /* The same refusal as the other backend, for the same reason: the instanced attributes take
            the two locations a skinned mesh's joints and weights already occupy. */
         if (mesh.isSkinned) {
@@ -2746,7 +2805,7 @@ export class WebGL2Renderer {
                 'locations the joint indices and weights occupy, and this mesh supplies them.');
         }
         this.ensureInstancedProgram();
-        return new InstancedBatch(this.gl, mesh, capacity);
+        return new InstancedBatch(this.gl, mesh, capacity, options.cull ?? false);
     }
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch, data) {
@@ -2790,6 +2849,12 @@ export class WebGL2Renderer {
         const count = Math.min(data.count, batch.capacity);
         if (count === 0)
             return;
+        /* A culling batch's camera draw: the whole batch against the view and the occluders first,
+           then instance by instance where it survives. Blended draws keep every instance and their
+           order. See `InstancedOptions.cull`. */
+        const culling = !blend && batch.cull;
+        if (culling && !batchBoxVisible(batch.box, this.frustum, this.occlusion))
+            return;
         this.drawBudget.ask();
         this.ensureInstancedProgram();
         const program = this.flatInstancedProgram;
@@ -2800,7 +2865,8 @@ export class WebGL2Renderer {
         gl.useProgram(program);
         gl.uniform1i(u['uHasTangents'] ?? null, mesh.hasTangents ? 1 : 0);
         const lit = options.lit ?? true;
-        const fog = options.fog ?? true;
+        /* Added light fades in the medium rather than receding into it. See `drawFog.ts`. */
+        const fog = fogModeOf(options.fog ?? true, blend && options.additive === true);
         const toneMapped = options.toneMapped ?? true;
         /* A blended batch shows what is behind it — refraction or glass — as a single draw does, and
            counts a material of its own for it by the rule both backends share (`materialChanges.ts`). */
@@ -2831,13 +2897,16 @@ export class WebGL2Renderer {
          */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (!fog)
-            gl.uniform1i(u['uFogEnabled'] ?? null, 0);
+        if (fog !== FOG_RECEDE)
+            gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.gradeCode(), 1));
         if (blend) {
             gl.enable(gl.BLEND);
-            gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+            if (options.additive === true)
+                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+            else
+                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
             if (!depthWrite)
                 gl.depthMask(false);
         }
@@ -2852,7 +2921,10 @@ export class WebGL2Renderer {
            for both: without it a batch's far faces were culled here alone. */
         if (this.materialDoubleSided)
             gl.disable(gl.CULL_FACE);
-        mesh.drawInstances(gl, count);
+        if (culling && cullsInstances(count, mesh.indexCount))
+            batch.drawCulled(gl, data, this.frustum);
+        else
+            batch.draw(gl, count);
         if (this.materialDoubleSided)
             gl.enable(gl.CULL_FACE);
         if (layer > 0) {
@@ -2874,8 +2946,8 @@ export class WebGL2Renderer {
             this.unbindSeeThrough(u);
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (!fog)
-            gl.uniform1i(u['uFogEnabled'] ?? null, 1);
+        if (fog !== FOG_RECEDE)
+            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)
@@ -3997,7 +4069,7 @@ export class WebGL2Renderer {
             const cutout = cutoutOf(material);
             this.bindGlassTint(cutout !== null ? programs.instancedCutout : programs.instanced, glass, cutout);
             gl.disable(gl.CULL_FACE);
-            gpuBatch.mesh.drawInstances(gl, count);
+            gpuBatch.draw(gl, count);
             if (this.depthPassCullsFaces)
                 gl.enable(gl.CULL_FACE);
             if (cutout !== null)
@@ -5247,11 +5319,20 @@ export class WebGL2Renderer {
                metres into a radius in UV. */
             this.aoProjScale[0] = projection[0] ?? 1;
             this.aoProjScale[1] = projection[5] ?? 1;
+            /* The occlusion read where this frame's jitter put it (`uAoOffset`): a texel stands at its
+               index plus a half less the jitter, in the drawing buffer the jitter was spread over. */
+            this.aoOffset[0] = this.temporalJittering
+                ? this.temporalJitterX / Math.max(1, this.gl.drawingBufferWidth)
+                : 0;
+            this.aoOffset[1] = this.temporalJittering
+                ? this.temporalJitterY / Math.max(1, this.gl.drawingBufferHeight)
+                : 0;
             ao = {
                 strength: aoStrength,
                 radius: this.quality.ambientOcclusionRadius,
                 projScale: this.aoProjScale,
                 invProjection: this.aoInvProjection,
+                offset: this.aoOffset,
             };
         }
         /*
@@ -5375,7 +5456,8 @@ export class WebGL2Renderer {
             this.oit.accumulateOit(this.canvas.width, this.canvas.height, oitDepth, (weighted) => {
                 this.oitReplaying = true;
                 this.useFlatProgram();
-                this.gl.uniform1f(flat['uOitWeighted'] ?? null, weighted ? 1 : 0);
+                this.oitWeight = weighted ? 1 : 0;
+                this.writeMode(flat);
                 this.translucentQueue.replay((draw) => {
                     options.lit = draw.lit;
                     options.fog = draw.fog;
@@ -5392,7 +5474,8 @@ export class WebGL2Renderer {
                     this.drawTranslucentMesh(draw.mesh, draw.model, draw.opacity, options);
                 });
                 /* Back to zero for every other draw in the frame, exactly as `uOpacity` and `uTint` are. */
-                this.gl.uniform1f(flat['uOitWeighted'] ?? null, 0);
+                this.oitWeight = 0;
+                this.writeMode(flat);
                 this.oitReplaying = false;
             });
             this.sceneTarget?.bind();
@@ -5551,7 +5634,15 @@ export class WebGL2Renderer {
          * A reflection pass binds its own camera and is skipped: blurring toward a mirror's
          * previous view is not what a viewer moved through.
          */
-        if (!this.reflectionPassActive && !this.probePassActive) {
+        /*
+         * **Not after the present**: a mesh pass bound then is the interface's, over a picture already
+         * resolved. Deciding the frame again drew the interface jittered with nothing to resolve it,
+         * and opened a second temporal frame, so the sequence stepped twice a frame, the world saw every
+         * other position, and the anti-flicker's period never started.
+         */
+        if (this.framePresented)
+            this.temporalJittering = false;
+        if (!this.reflectionPassActive && !this.probePassActive && !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. */
@@ -5657,6 +5748,19 @@ export class WebGL2Renderer {
         this.lightField = field;
         return field;
     }
+    /**
+     * Hand a world's DriftLight volume to the renderer: every fixed light of a city, summed offline by
+     * `bakeDenseField`, standing in past the frame's exact choice. Replaces any field made before, of
+     * either kind; the scene calls `field.follow(buffer.complete, ...)` each frame as it would for
+     * `createLightField`, and marks the lights the volume summed `inLightField` so none is counted
+     * twice. See `driftLight/worldLightField.ts`.
+     */
+    createWorldLightField(volume, options = {}) {
+        this.forgetLightFieldVolumes();
+        const field = new WorldLightField(volume, options);
+        this.lightField = field;
+        return field;
+    }
     /** Let go of the field and its volumes; the scene's lights are all exact again. */
     disposeLightField() {
         this.forgetLightFieldVolumes();
@@ -5676,14 +5780,14 @@ export class WebGL2Renderer {
      */
     uploadLightField() {
         const field = this.lightField;
-        if (field === null || this.driftAtlas !== null || !field.ready || field.layout.count === 0) {
+        if (field === null || this.driftAtlas !== null || !field.ready || field.empty) {
             return;
         }
         const { gl } = this;
-        const [ix, iy, iz] = field.layout.dims;
+        const [ix, iy, iz] = field.indexDims;
         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.texImage3D(gl.TEXTURE_3D, 0, gl.R32UI, ix, iy, iz, 0, gl.RED_INTEGER, gl.UNSIGNED_INT, field.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;
@@ -5811,6 +5915,10 @@ export class WebGL2Renderer {
         gl.uniform1i(u['uFogEnabled'] ?? null, 1);
         /* Grain on by default, so every scene written before it was a choice looks unchanged. */
         gl.uniform1f(u['uGrain'] ?? null, 1);
+        /* No dither and no weighting: every draw whole, until a crossfade asks. See `setDitherFade`. */
+        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`. */
@@ -5820,11 +5928,11 @@ export class WebGL2Renderer {
         gl.uniform1f(u['uReliefCycles'] ?? null, 60);
         /* And no relief read off a surface texture either, for the same reason. */
         gl.uniform1f(u['uTextureRelief'] ?? null, 0);
-        gl.uniform1i(u['uClipEnabled'] ?? null, this.reflectionPassActive ? 1 : 0);
+        /* The mirror's plane in a reflection pass, and zero — which clips nothing — in every other. */
         const reflection = this.planarReflection;
-        if (this.reflectionPassActive && reflection !== null) {
-            gl.uniform4fv(u['uClipPlane'] ?? null, reflection.clipPlane);
-        }
+        gl.uniform4fv(u['uClipPlane'] ?? null, this.reflectionPassActive && reflection !== null ? reflection.clipPlane : NO_CLIP_PLANE);
+        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);
@@ -5981,9 +6089,13 @@ export class WebGL2Renderer {
         }
         this.bindDriftLight(u, camera.position);
         gl.activeTexture(gl.TEXTURE0 + SURFACE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         gl.uniform1i(u['uAlbedo'] ?? null, SURFACE_TEXTURE_UNIT);
         gl.uniform1i(u['uAlbedoEnabled'] ?? null, 0);
+        /* No albedo, so no effects table: the stand-in, which the shader reads as none. */
+        gl.activeTexture(gl.TEXTURE0 + SURFACE_EFFECTS_TEXTURE_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.uniform1i(u['uSurfaceEffects'] ?? null, SURFACE_EFFECTS_TEXTURE_UNIT);
         gl.uniform2f(u['uUvScale'] ?? null, 1, 1);
         gl.uniform1f(u['uAlbedoCutout'] ?? null, 0);
         gl.uniform1i(u['uDoubleSided'] ?? null, 0);
@@ -6007,18 +6119,18 @@ export class WebGL2Renderer {
          * fetch a sampler's descriptor before it evaluates the branch that would have skipped the read.
          */
         gl.activeTexture(gl.TEXTURE0 + NORMAL_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         gl.uniform1i(u['uNormalMap'] ?? null, NORMAL_TEXTURE_UNIT);
         gl.uniform1f(u['uNormalStrength'] ?? null, 0);
         /* And the ORM map, for the reason directly above and the one above that. */
         gl.activeTexture(gl.TEXTURE0 + ORM_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         gl.uniform1i(u['uOrmMap'] ?? null, ORM_TEXTURE_UNIT);
         gl.uniform1i(u['uOrmEnabled'] ?? null, 0);
         gl.uniform3f(u['uOrmScale'] ?? null, 1, 1, 1);
         /* And the emissive map. The scale goes back to one, which is the identity it multiplies by. */
         gl.activeTexture(gl.TEXTURE0 + EMISSIVE_TEXTURE_UNIT);
-        gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
         gl.uniform1i(u['uEmissiveMap'] ?? null, EMISSIVE_TEXTURE_UNIT);
         gl.uniform1i(u['uEmissiveMapEnabled'] ?? null, 0);
         gl.uniform3f(u['uEmissiveScale'] ?? null, 1, 1, 1);
@@ -6304,7 +6416,7 @@ export class WebGL2Renderer {
          * The two buffers are two blend states over the same geometry, so the set has to survive until
          * the end of the pass. Everything is copied — see `TranslucentQueue`.
          */
-        if (this.oitActive && !this.oitReplaying) {
+        if (this.oitActive && !this.oitReplaying && options.additive !== true) {
             this.translucentQueue.record(mesh, model, opacity, options);
             return;
         }
@@ -6322,12 +6434,13 @@ export class WebGL2Renderer {
          * drew with, and only a caller that asks pays for the branch that skips them.
          */
         const lit = options.lit ?? true;
-        const fog = options.fog ?? true;
+        /* Added light fades in the medium rather than receding into it. See `drawFog.ts`. */
+        const fog = fogModeOf(options.fog ?? true, options.additive === true);
         const toneMapped = options.toneMapped ?? true;
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (!fog)
-            gl.uniform1i(u['uFogEnabled'] ?? null, 0);
+        if (fog !== FOG_RECEDE)
+            gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         /* `1` is sRGB alone: the conversion without the curve, which is what dropping the tone map
            means rather than dropping the whole transform. `Math.min` rather than a literal, so a
            renderer asked for `none` stays at none and one asked for `srgb` is already there. */
@@ -6368,7 +6481,11 @@ export class WebGL2Renderer {
         const ownsState = !this.oitReplaying;
         if (ownsState) {
             gl.enable(gl.BLEND);
-            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+            /* Added, where asked: colour times alpha onto what is there, and the target's alpha kept. */
+            if (options.additive === true)
+                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+            else
+                gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         }
         /*
          * The two depth options, both scoped to this draw and handed straight back — the same
@@ -6408,8 +6525,8 @@ export class WebGL2Renderer {
            cannot inherit a material from the draw before it. */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (!fog)
-            gl.uniform1i(u['uFogEnabled'] ?? null, 1);
+        if (fog !== FOG_RECEDE)
+            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)