@driftengine/core 3.63.0 → 4.1.0

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

@@ -1,4 +1,5 @@
 import { FrameBudget } from '../budget.js';
+import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
 import { mat4 } from 'gl-matrix';
 import { DEPTH_CLEAR, DEPTH_OFFSET_SIGN, GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { PickableSet } from '../../pickable.js';
@@ -11,6 +12,7 @@ import { REFLECTION_EDGE_FADE, ReflectionQueue } from '../../screenSpaceReflecti
 import { DecalQueue } from '../../decalQueue.js';
 import { OitPass } from '../../oitPass.js';
 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 { OcclusionBuffer } from '../../occlusion.js';
@@ -34,7 +36,7 @@ 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 } from '../../reflectionProbe.js';
+import { ReflectionProbe, cubeFaceProjection } from '../../reflectionProbe.js';
 import { EnvProbeArray } from '../../envProbeArray.js';
 import { ProbeGrid, SINGLE_PROBE, UNIT_STEP, WORLD_ORIGIN, sameGrid } from '../../probeGrid.js';
 import { octahedralEdgeFor } from '../../prefilterEnvMap.js';
@@ -749,6 +751,13 @@ export class WebGL2Renderer {
     reversedDepth = false;
     /** `GL_DEPTH_REMAP * camera.viewProjection`, rebuilt once a frame. */
     sceneViewProj = new Float32Array(16);
+    /**
+     * The same matrix with clip y negated, for the six faces of a probe.
+     *
+     * Its own buffer rather than `sceneViewProj`, because `cubeFaceProjection` reads what
+     * `sceneMatrix` just wrote and the two would be the same array.
+     */
+    cubeFaceViewProj = new Float32Array(16);
     /**
      * One buffer per shadow matrix that outlives a call, and that is not fussiness.
      *
@@ -776,7 +785,9 @@ export class WebGL2Renderer {
      * the camera's matrix unchanged and multiplies nothing.
      */
     viewProjFor(camera) {
-        const scene = this.sceneMatrix(camera.viewProjection);
+        const scene = this.probePassActive
+            ? cubeFaceProjection(this.cubeFaceViewProj, this.sceneMatrix(camera.viewProjection))
+            : this.sceneMatrix(camera.viewProjection);
         /*
          * **The jitter goes on here and nowhere else.** This is the one funnel every geometry upload
          * passes through, so one line covers the mesh passes, the sky, the water and the effects
@@ -865,6 +876,7 @@ export class WebGL2Renderer {
      */
     casterSink = {
         mesh: (mesh, model) => {
+            this.shadowDrawBudget.ask();
             const { gl } = this;
             gl.uniformMatrix4fv(this.depthUniforms['uModel'] ?? null, false, model);
             /*
@@ -886,6 +898,7 @@ export class WebGL2Renderer {
             const count = Math.min(data.count, gpuBatch.capacity);
             if (count === 0)
                 return;
+            this.shadowDrawBudget.ask();
             const u = this.depthInstancedUniforms;
             gl.useProgram(this.depthInstancedProgram);
             gl.uniformMatrix4fv(u['uLightViewProj'] ?? null, false, this.activeDepthViewProj);
@@ -896,6 +909,7 @@ export class WebGL2Renderer {
             gl.useProgram(this.depthProgram);
         },
         skinnedMesh: (mesh, model, palette) => {
+            this.shadowDrawBudget.ask();
             const { gl } = this;
             const u = this.depthSkinnedUniforms;
             gl.useProgram(this.depthSkinnedProgram);
@@ -920,6 +934,7 @@ export class WebGL2Renderer {
         scatter: (scatter, data, windX, windZ, windGust, timeSeconds, trample = null) => {
             if (data.count === 0)
                 return;
+            this.scatterDepthBudget.ask();
             const { gl } = this;
             const u = this.scatterDepthUniforms;
             gl.useProgram(this.scatterDepthProgram);
@@ -1035,6 +1050,39 @@ export class WebGL2Renderer {
     addOccluder(min, max, model) {
         this.occlusion?.addOccluder(min, max, model);
     }
+    /**
+     * Declare a baked distance field that indirect light may be traced against.
+     *
+     * **Recorded by nothing on this backend, and that is the refusal rather than an oversight.**
+     * Composing the world's field and marching probes through it is compute, and WebGL2 has no
+     * compute stage — `INDIRECT_LIGHT_WEBGL2_REFUSAL` says so once a frame-loop when
+     * `quality.indirectLight` is on. The method exists here because `RendererApi` is this class's
+     * shape, and a consumer that declares its fields unconditionally must not have to ask which
+     * backend it got: this is a no-op for the same reason `addOccluder` is one when the profile
+     * asked for no occlusion buffer.
+     *
+     * The field is in the model matrix's own space and the matrix must carry uniform scale only.
+     * `composeGlobalField` gives the reason: a distance is not preserved by a non-uniform scale.
+     */
+    addDistanceField(_field, _model, _albedo) {
+        /* Deliberately nothing. See the comment above. */
+    }
+    /** Forget the fields declared this frame. A no-op here, as `addDistanceField` is. */
+    clearDistanceFields() {
+        /* Deliberately nothing. See `addDistanceField`. */
+    }
+    /** Never measured here, because nothing is composed. See `addDistanceField`. */
+    get distanceFieldMs() {
+        return null;
+    }
+    /** Never traced here either, so there is no refresh to time. See `addDistanceField`. */
+    get indirectBakeMs() {
+        return null;
+    }
+    /** Nothing to read, for the same reason. A consumer may call it unconditionally. */
+    readDistanceFieldTimings() {
+        /* Deliberately nothing. See `addDistanceField`. */
+    }
     /**
      * Whether a mesh is entirely behind the occluders declared this frame.
      *
@@ -1066,7 +1114,14 @@ export class WebGL2Renderer {
     registerPass(definition) {
         const handle = registerIn(this.passes, definition);
         /* Identity: this backend's clip space is the one the projections are built for. */
-        this.passDevice ??= { backend: 'webgl2', gl: this.gl, clipCorrection: IDENTITY_CLIP };
+        /* Both are identity here: this backend runs the GLSL natively, so there is nothing to
+           correct and nothing a generator has flipped. */
+        this.passDevice ??= {
+            backend: 'webgl2',
+            gl: this.gl,
+            clipCorrection: IDENTITY_CLIP,
+            depthCorrection: IDENTITY_CLIP,
+        };
         if (definition.prepare !== undefined)
             this.preparingPasses++;
         definition.init?.(this.passDevice);
@@ -2093,6 +2148,7 @@ export class WebGL2Renderer {
     setMaterial(material) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.currentSurfaceTexture = material?.albedo ?? null;
         /*
          * Written to every flat program, because material state persists across draws and a skinned
@@ -2244,6 +2300,7 @@ export class WebGL2Renderer {
     setSurfaceReflectivity(amount) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.useFlatProgram();
         this.gl.uniform1f(this.flatUniforms['uReflectivity'] ?? null, Math.min(1, Math.max(0, amount)));
     }
@@ -2262,6 +2319,7 @@ export class WebGL2Renderer {
     setEnvironmentGain(gain) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.useFlatProgram();
         this.gl.uniform1f(this.flatUniforms['uEnvironmentGain'] ?? null, Math.max(0, gain));
     }
@@ -2289,6 +2347,7 @@ export class WebGL2Renderer {
     setSurfaceGrain(amount) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.useFlatProgram();
         this.gl.uniform1f(this.flatUniforms['uGrain'] ?? null, Math.min(1, Math.max(0, amount)));
     }
@@ -2318,6 +2377,7 @@ export class WebGL2Renderer {
     setSurfaceRelief(amount, cyclesPerMetre = 60) {
         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)));
@@ -2351,6 +2411,7 @@ export class WebGL2Renderer {
     setSurfaceTextureRelief(scale) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.useFlatProgram();
         this.gl.uniform1f(this.flatUniforms['uTextureRelief'] ?? null, Number.isFinite(scale) ? scale : 0);
     }
@@ -2378,6 +2439,7 @@ export class WebGL2Renderer {
     setEmissiveGain(gain) {
         if (this.contextLost)
             return;
+        this.materials.dirty();
         this.useFlatProgram();
         this.gl.uniform1f(this.flatUniforms['uEmissiveGain'] ?? null, gain);
     }
@@ -2482,6 +2544,11 @@ export class WebGL2Renderer {
         const lit = options.lit ?? true;
         const fog = options.fog ?? true;
         const toneMapped = options.toneMapped ?? true;
+        /* An instanced draw does not refract. See `materialChanges.ts`. */
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting: false });
+        if (own)
+            this.materials.dirty();
+        this.takeMaterial();
         const depthWrite = options.depthWrite ?? true;
         const layer = Math.min(Math.max(Math.round(options.depthLayer ?? 0), 0), MAX_DEPTH_LAYER);
         if (opacity < 1)
@@ -2559,6 +2626,8 @@ export class WebGL2Renderer {
             gl.uniform1i(u['uFogEnabled'] ?? null, 1);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
+        if (own)
+            this.materials.dirty();
         this.useFlatProgram();
     }
     disposeMesh(mesh) {
@@ -2657,7 +2726,9 @@ export class WebGL2Renderer {
         // raining dust into the sea.
         const surface = env.underwater?.surfaceY;
         const submerged = surface !== undefined && (camera.position[1] ?? 0) < surface;
-        streaks.draw(this.gl, this.frameViewFor(camera), wind, timeSeconds, tint, submerged);
+        if (streaks.draw(this.gl, this.frameViewFor(camera), wind, timeSeconds, tint, submerged)) {
+            this.windStreakBudget.ask();
+        }
     }
     /**
      * A 3D text object: one string, drawn as instanced glyph cubes over the
@@ -2682,7 +2753,9 @@ export class WebGL2Renderer {
      * whatever box the caller lays out in, and the game's own card is not always the canvas.
      */
     drawText(text, viewportWidth, viewportHeight, originX, originY, style, timeSec) {
-        text.draw(viewportWidth, viewportHeight, originX, originY, style, timeSec);
+        if (text.draw(viewportWidth, viewportHeight, originX, originY, style, timeSec)) {
+            this.textBudget.ask();
+        }
     }
     /** Width of the string this handle currently holds, in pixels at a given cell size. */
     textWidth(text, cellSize) {
@@ -2757,6 +2830,7 @@ export class WebGL2Renderer {
             return;
         /* Geometry, so the remapped matrix: `frameViewProj` itself stays raw for the motion blur. */
         if (handle.draw(this.sceneMatrix(viewProj), model, color, opacity, this.gradeCode(), this.gradeExposure())) {
+            this.sdfTextBudget.ask();
             this.restoreSurfaceTextureUnit();
         }
     }
@@ -2768,6 +2842,7 @@ export class WebGL2Renderer {
         return new FlockRenderer(this.gl, count);
     }
     drawFlock(flock, camera, timeSeconds, params, tint, windX = 0, windZ = 0) {
+        this.flockBudget.ask();
         flock.draw(this.gl, this.frameViewFor(camera), timeSeconds, params, tint, windX, windZ);
     }
     /**
@@ -2864,8 +2939,11 @@ export class WebGL2Renderer {
             return;
         const { gl } = this;
         const u = batch.uniforms;
-        gl.useProgram(batch.program);
         const count = batch.upload(gl, data);
+        if (count === 0)
+            return;
+        this.boltBudget.ask();
+        gl.useProgram(batch.program);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, this.viewProjFor(camera));
         gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
         gl.uniform1f(u['uTime'] ?? null, timeSeconds);
@@ -2917,8 +2995,11 @@ export class WebGL2Renderer {
             return;
         const { gl } = this;
         const u = lines.uniforms;
-        gl.useProgram(lines.program);
         const count = lines.upload(gl, data);
+        if (count === 0)
+            return;
+        this.lineBudget.ask();
+        gl.useProgram(lines.program);
         gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, this.viewProjFor(camera));
         gl.uniformMatrix4fv(u['uModel'] ?? null, false, model);
         gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
@@ -3093,6 +3174,7 @@ export class WebGL2Renderer {
     drawWater(water, camera, timeSeconds, settings, env, windX = 0, windZ = 0) {
         if (!this.quality.water)
             return;
+        this.waterBudget.ask();
         water.draw(this.gl, this.frameViewFor(camera), timeSeconds, settings, env.directionalDir, env.directionalColor, env.ambient, env, this.quality.underwaterAtmosphere, this.reflectionReadyThisFrame ? this.planarReflection : null, env, this.quality.pointLightFalloff, windX, windZ);
     }
     /**
@@ -3102,7 +3184,9 @@ export class WebGL2Renderer {
     drawCaustics(caustics, camera, timeSeconds, env, windX = 0, windZ = 0, strength = 1) {
         if (caustics === null || !this.quality.water)
             return;
-        caustics.draw(this.gl, this.frameViewFor(camera), timeSeconds, env.directionalDir, env.directionalColor, env.ambient, env, this.quality.underwaterAtmosphere, windX, windZ, strength);
+        const drew = caustics.draw(this.gl, this.frameViewFor(camera), timeSeconds, env.directionalDir, env.directionalColor, env.ambient, env, this.quality.underwaterAtmosphere, windX, windZ, strength);
+        if (drew)
+            this.causticsBudget.ask();
     }
     /**
      * Begin a scene render mirrored across a horizontal plane. Draw ordinary
@@ -3160,6 +3244,21 @@ export class WebGL2Renderer {
     get aspect() {
         return this.canvas.width / Math.max(this.canvas.height, 1);
     }
+    /**
+     * The size the world is drawn at, which on this backend is always the drawing buffer.
+     *
+     * **Here so that a contributed pass has one question to ask on both backends.** WebGPU can draw
+     * the world smaller than the canvas and let its composite enlarge it — `quality.reconstruction`
+     * — and a pass filling a target of its own has to follow that size or draw a picture the frame
+     * pass clips. This backend has no compute stage and no reconstruction, so the answer never moves;
+     * a pass that reads it is correct on both, and one that reads `canvas.width` is correct on one.
+     */
+    get sceneWidth() {
+        return Math.max(1, this.canvas.width);
+    }
+    get sceneHeight() {
+        return Math.max(1, this.canvas.height);
+    }
     /**
      * Point rendering back at the frame's own target, whole.
      *
@@ -4001,6 +4100,9 @@ export class WebGL2Renderer {
     fillPanel(rect, color, alpha) {
         if (alpha <= 0 || rect.width <= 0 || rect.height <= 0)
             return;
+        /* Counted against no ceiling: the other backend refuses past its own, and a consumer here
+           should be able to see that coming. See `budget.ts`. */
+        this.panelBudget.ask();
         const { gl } = this;
         gl.useProgram(this.panelProgram);
         gl.bindVertexArray(this.panelVao);
@@ -4271,6 +4373,25 @@ export class WebGL2Renderer {
      */
     budget = new FrameBudget();
     drawBudget = this.budget.line('draws', null);
+    /**
+     * Every line the other backend declares, in its order and with none of its ceilings.
+     *
+     * **Counted after the same guards**, so one scene reports one number on both: the verbs each
+     * ask once they are past the checks that make them draw nothing on either backend — a panel
+     * with no alpha, a string with no glyphs, a beam with no strength, a calm wind — and a material
+     * change is counted by the rule both share (`materialChanges.ts`). `webgpu/renderer.test.ts`
+     * runs one scene through both and compares every line.
+     */
+    materialBudget = this.budget.line('materials', null);
+    /** Whether the next mesh draw shares the open material or opens one, by the rule both count. */
+    materials = new MaterialChanges();
+    /** A mesh draw: counted as a material change when something has changed the material since. */
+    takeMaterial() {
+        if (this.materials.open)
+            return;
+        this.materialBudget.ask();
+        this.materials.slot = 0;
+    }
     /**
      * Declared here and never asked, because this backend builds none.
      *
@@ -4282,6 +4403,19 @@ export class WebGL2Renderer {
      * being compared against should also be zero once the other backend's cache is warm.
      */
     bindGroupBudget = this.budget.line('bind groups', null);
+    shadowDrawBudget = this.budget.line('shadow draws', null);
+    scatterDepthBudget = this.budget.line('scatter shadow draws', null);
+    waterBudget = this.budget.line('water bodies', null);
+    lightVolumeBudget = this.budget.line('light volumes', null);
+    windStreakBudget = this.budget.line('wind streak fields', null);
+    flockBudget = this.budget.line('flocks', null);
+    boltBudget = this.budget.line('bolt batches', null);
+    causticsBudget = this.budget.line('caustics', null);
+    textBudget = this.budget.line('text draws', null);
+    sdfTextBudget = this.budget.line('sdf text draws', null);
+    lineBudget = this.budget.line('line draws', null);
+    /** The other backend's panel ceiling, reported here as a count with none. */
+    panelBudget = this.budget.line('panels', null);
     /** What the frame just drawn asked for. See `budget.ts`, and the note on `budget` above. */
     get frameBudget() {
         return this.budget;
@@ -4372,6 +4506,8 @@ export class WebGL2Renderer {
      * from one `RenderQuality` — see `OIT_MULTISAMPLE_REFUSAL` for why it is a constant and not two
      * literals kept in step by hand.
      */
+    /** Said once rather than every frame, as the translucent set's own refusal is. */
+    indirectLightRefused = false;
     refuseOitMultisampled() {
         if (this.oitMultisampleRefused)
             return;
@@ -4382,6 +4518,15 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         this.budget.reset();
+        this.materials.dirty();
+        /*
+         * Said once, for the reason `refuseOitMultisampled` gives: a quality setting that is enabled
+         * and does nothing is the fault the capability clamp exists to prevent.
+         */
+        if (this.quality.indirectLight && !this.indirectLightRefused) {
+            this.indirectLightRefused = true;
+            console.warn(INDIRECT_LIGHT_WEBGL2_REFUSAL);
+        }
         const { gl } = this;
         this.reflectionReadyThisFrame = false;
         /*
@@ -4624,6 +4769,16 @@ export class WebGL2Renderer {
             this.translucentQueue.length > 0) {
             const flat = this.flatUniforms;
             const options = this.oitReplayOptions;
+            /*
+             * **The copy a refracting pane reads is taken here, before the buffers are bound.** Taking
+             * it puts the scene's framebuffer back as the one drawn into, so taken inside the replay —
+             * at the first pane that refracts, which is where it was taken until 2026-09-19 — it sent
+             * that pane into the scene instead of the accumulation, and every refracting pane came out
+             * flat paint with the effect on. The opaque frame is finished here, which is what a pane
+             * should show; the latch then serves every pane in the replay. Only when something refracts.
+             */
+            if (this.translucentQueue.refracts)
+                this.sceneTarget?.snapshotColor();
             this.oit.accumulateOit(this.canvas.width, this.canvas.height, oitDepth, (weighted) => {
                 this.oitReplaying = true;
                 this.useFlatProgram();
@@ -4795,6 +4950,8 @@ export class WebGL2Renderer {
     }
     /** Bind the flat pass once per frame; then issue any number of drawMesh calls. */
     bindMeshPass(camera, env) {
+        /* The pass's own material is reopened, so the next draw opens one. See `materialChanges.ts`. */
+        this.materials.dirty();
         /*
          * 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.
@@ -5121,6 +5278,8 @@ export class WebGL2Renderer {
              * are two numbers now.
              */
             gl.uniform1f(u['uEnvironmentEdge'] ?? null, array?.edge ?? 1);
+            /* Never on this backend: what fills a visibility map is a compute dispatch. See `probeGrid.ts`. */
+            gl.uniform1f(u['uProbeVisibilityEnabled'] ?? null, 0);
             gl.uniform1f(u['uEnvironmentIrradianceLevel'] ?? null, array?.irradianceLevel ?? 0);
             /*
              * Where the probes stand: four uniforms whatever the probe count, because this shader is
@@ -5249,7 +5408,15 @@ export class WebGL2Renderer {
      * rebuilding vertex data every frame. Reset to white after the call, so a caller that
      * passes one cannot leak it into the next draw.
      */
-    tint = null) {
+    tint = null, 
+    /**
+     * Where the mesh was last frame, which this backend takes and ignores.
+     *
+     * Accepted rather than absent so that one scene draws through both renderers unchanged — the
+     * parity rule this repository is built on. Reconstruction is WebGPU's, having no compute stage
+     * here, so there is no motion target for this to be written into.
+     */
+    _previousModel = null) {
         if (this.contextLost)
             return;
         /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
@@ -5276,6 +5443,7 @@ export class WebGL2Renderer {
         if (this.quality.cullDraws && this.occluded(mesh.bounds, model))
             return;
         this.drawBudget.ask();
+        this.takeMaterial();
         const { gl } = this;
         /*
          * A rigged mesh takes the skinned program, an unrigged one the plain program.
@@ -5439,7 +5607,6 @@ export class WebGL2Renderer {
             return;
         if (opacity <= 0)
             return;
-        this.drawBudget.ask();
         /*
          * **Recorded rather than drawn**, when the effect is on and this is not already the replay.
          * The two buffers are two blend states over the same geometry, so the set has to survive until
@@ -5449,6 +5616,9 @@ export class WebGL2Renderer {
             this.translucentQueue.record(mesh, model, opacity, options);
             return;
         }
+        /* Counted where it is submitted, as the other backend counts it: once per replay pass under
+           order-independent transparency, and not once more when it was recorded. */
+        this.drawBudget.ask();
         const { gl } = this;
         const u = this.flatUniforms;
         this.useFlatProgram();
@@ -5509,6 +5679,12 @@ export class WebGL2Renderer {
          * or a multiplicative blend for the whole set and turned depth writes off for all of it. A
          * replayed draw that reset either would break the pass around it.
          */
+        /* Taken for itself when any option differs from the pass, and put back below: the rule both
+           backends count material changes by. See `materialChanges.ts`. */
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+        if (own)
+            this.materials.dirty();
+        this.takeMaterial();
         const ownsState = !this.oitReplaying;
         if (ownsState) {
             gl.enable(gl.BLEND);
@@ -5550,6 +5726,8 @@ export class WebGL2Renderer {
             gl.uniform1i(u['uFogEnabled'] ?? null, 1);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
+        if (own)
+            this.materials.dirty();
     }
     /**
      * Capture the room into a cubemap, once, so reflective surfaces can mirror it.
@@ -5647,6 +5825,23 @@ export class WebGL2Renderer {
         this.useFlatProgram();
         this.gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, 0);
         this.gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, 1);
+        this.materials.dirty();
+        /*
+         * **Clockwise for the duration, because a face is rendered mirrored.** `cubeFaceProjection`
+         * negates clip y so the face is stored the way a cubemap reads it, and negating one axis
+         * reverses every triangle's winding: without this the room is culled inside out and the cube
+         * holds its own back faces.
+         *
+         * **A perturbation survives this line and it is kept anyway**, which is worth the sentence.
+         * Deleting it moves `ibl-check.mjs`'s figures — 12.5 to 13.1 of 255 on the movement check and
+         * 182.0 to 184.9 on the mirror rung — so it is not dead; but no check *fails*, because every
+         * room this repository bakes into a probe is made of closed boxes whose two sides carry the
+         * same colour, and looking at the far one's outside instead of the near one's inside draws
+         * almost the same picture. What it actually decides is a scene with **one-sided** geometry: a
+         * room built from single quads facing inward disappears from its own probe without it, and
+         * there is no such scene here to fail on.
+         */
+        this.gl.frontFace(this.gl.CW);
         let baked = false;
         try {
             baked = probe.bake(this.gl, this.probeOrigin, clearColor, drawFace);
@@ -5660,9 +5855,11 @@ export class WebGL2Renderer {
             }
         }
         finally {
+            this.gl.frontFace(this.gl.CCW);
             this.useFlatProgram();
             this.gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.gradeCode());
             this.gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.gradeExposure());
+            this.materials.dirty();
             /*
              * Cleared even if a caller's own draw threw, because leaving this set would keep every
              * later frame reading the placeholder and quietly reflecting nothing.
@@ -5804,6 +6001,7 @@ export class WebGL2Renderer {
            where the beam has no medium to be seen in and skipping it is the whole saving. */
         if (shown <= 0)
             return;
+        this.lightVolumeBudget.ask();
         const { gl } = this;
         const u = this.lightVolumeUniforms;
         gl.useProgram(this.lightVolumeProgram);

package/dist/render/backend/webgpu/buffers.d.ts

@@ -27,8 +27,27 @@ export interface VertexAttribute {
 export declare const VERTEX_LAYOUT: readonly VertexAttribute[];
 /** Geometry on the device, with the buffers bound in layout order. */
 export interface GpuMesh {
-    /** One buffer per attribute, indexed by position in `VERTEX_LAYOUT`. */
+    /**
+     * The buffers a draw binds, in the order `vertexBufferLayouts` describes them.
+     *
+     * **Two, and the first is interleaved** — every attribute this mesh actually supplied, woven
+     * into one stride — while the second holds one value per *absent* optional attribute at a stride
+     * of zero. It is emphatically not one buffer per attribute, which this comment said until
+     * 2026-09-17 and which cost the motion pass an afternoon: a pipeline built to that description
+     * reads a position out of every twelve bytes of an interleaved vertex, draws geometry that is
+     * not the mesh, and fails no validation at all.
+     */
     readonly vertexBuffers: readonly GPUBuffer[];
+    /**
+     * Bytes a vertex takes in the first of those buffers.
+     *
+     * Kept because it is a function of which *optional* attributes this mesh supplied, so it differs
+     * between two meshes drawn by the same pipeline — and a pass that reads only the position still
+     * has to step by the whole of it. `submitMesh` never needs it, the generated pipelines being
+     * keyed by the same `present` map that decides it; anything drawing a mesh through a shader of
+     * its own does.
+     */
+    readonly vertexStride: number;
     readonly indexBuffer: GPUBuffer;
     readonly indexCount: number;
     /**