@driftengine/core 4.8.1 → 4.8.3

package/src/render/backend/webgpu/renderer.ts

@@ -254,6 +254,7 @@ import {
   DECAL_TEXTURES,
   DECAL_UNIFORMS,
   PREMULTIPLIED_OVER_BLEND,
+  REFLECTION_OVER_BLEND,
   SSR_FRAG_FIELDS,
   SSR_FRAG_SIZE,
   SSR_RESOLVE_FRAG_WGSL,
@@ -337,6 +338,8 @@ import {
 import type { GlobalMediumOptions } from '../../globalMedium.ts';
 import type { MeshData } from '../../mesh.ts';
 import { castsDepth, glassOf } from '../../shadowCasters.ts';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.ts';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.ts';
 import { GlassCasterList, type GlassReplaySink } from '../../glassCasters.ts';
 import { GpuGlassTint } from './glassTintPass.ts';
 import {
@@ -379,7 +382,7 @@ import {
   createDepthBindGroupLayout,
   depthPipeline,
 } from './depthPass.ts';
-import { PipelineCache } from './pipelineCache.ts';
+import { PipelineCache, type LitSwitch } from './pipelineCache.ts';
 import {
   SKY_FIELDS,
   SKY_UNIFORM_SIZE,
@@ -490,7 +493,7 @@ import {
 import { aimReflection, createGpuReflection, type GpuReflection } from './reflectionPass.ts';
 import { FrameBudget } from '../budget.ts';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.ts';
-import { FOG_RECEDE, fogModeOf } from '../drawFog.ts';
+import { FOG_OFF, FOG_RECEDE, fogModeOf } from '../drawFog.ts';
 import { DYNAMIC_ALIGNMENT as DYNAMIC_UNIFORM_ALIGNMENT, UniformRing } from './uniformRing.ts';
 import { DecalQueue, MAX_DRAWN_DECALS } from '../../decalQueue.ts';
 import { DistanceFieldScene } from '../../gi/fieldScene.ts';
@@ -2803,8 +2806,17 @@ export class WebGPURenderer implements RendererApi {
   private blankAlbedoBindGroup: GPUBindGroup;
   /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
   private readonly uvScale = new Float32Array([1, 1]);
+  /** Where the texture starts, after the scale. Per draw, beside `uvScale`. */
+  private readonly uvOffset = new Float32Array([0, 0]);
+  /**
+   * How the surfaces drawn next meet the medium: what `setSurfaceFog` set, and `FOG_RECEDE` from
+   * each `bindMeshPass`. A translucent draw's own fog is measured against this and puts it back.
+   */
+  private surfaceFog = FOG_RECEDE;
   /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
   private materialDoubleSided = false;
+  /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+  private materialHasMaps = false;
 
   createSurfaceTexture(
     source: TexImageSource,
@@ -2936,7 +2948,10 @@ export class WebGPURenderer implements RendererApi {
     const albedo = material?.albedo ?? null;
     this.uvScale[0] = material?.uScale ?? 1;
     this.uvScale[1] = material?.vScale ?? 1;
+    this.uvOffset[0] = material?.uOffset ?? 0;
+    this.uvOffset[1] = material?.vOffset ?? 0;
     this.materialDoubleSided = material?.doubleSided === true;
+    this.materialHasMaps = materialHasMaps(material);
     const normal = (material?.normal ?? null) as GpuSurfaceTexture | null;
     const orm = (material?.orm ?? null) as GpuSurfaceTexture | null;
     const emissiveMap = (material?.emissive ?? null) as GpuSurfaceTexture | null;
@@ -3099,6 +3114,14 @@ export class WebGPURenderer implements RendererApi {
     });
   }
 
+  /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
+  setSurfaceFog(enabled: boolean): void {
+    this.surfaceFog = enabled ? FOG_RECEDE : FOG_OFF;
+    this.material((_f, i) => {
+      i[this.materialField('uFogEnabled')] = this.surfaceFog;
+    });
+  }
+
   /**
    * How much of the surfaces drawn next survives a screen-door dither. See `renderer.ts`.
    *
@@ -5387,17 +5410,20 @@ export class WebGPURenderer implements RendererApi {
     return group;
   }
 
-  /** The cutoff and UV scale into a cutout draw's slot, at the offsets its own variant declares. */
+  /** The cutoff and UV scale and offset into a cutout draw's slot, at its own variant's offsets. */
   private writeCutout(
     slot: number,
     cutout: CutoutCaster<unknown>,
     fields: {
       readonly uUvScale: { readonly offset: number };
+      readonly uUvOffset: { readonly offset: number };
       readonly uAlphaCutout: { readonly offset: number };
     },
   ): void {
     this.shadowDraws.writeFloat(slot, fields.uUvScale.offset, cutout.u);
     this.shadowDraws.writeFloat(slot, fields.uUvScale.offset + 4, cutout.v);
+    this.shadowDraws.writeFloat(slot, fields.uUvOffset.offset, cutout.uOffset);
+    this.shadowDraws.writeFloat(slot, fields.uUvOffset.offset + 4, cutout.vOffset);
     this.shadowDraws.writeFloat(slot, fields.uAlphaCutout.offset, cutout.cutoff);
   }
 
@@ -5450,6 +5476,27 @@ export class WebGPURenderer implements RendererApi {
    */
   /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
   private readonly glassCasters = new GlassCasterList();
+  /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+  private glassSeen = false;
+
+  /**
+   * The first glass caster switches every lit pipeline to reading glass. See
+   * `PipelineCache.litSwitches`: until a pane exists the lookups would find nothing, and they cost
+   * the lit pass on every surface whether they find anything or not.
+   */
+  private noteGlassCaster(): void {
+    if (this.glassSeen) return;
+    this.glassSeen = true;
+    this.enableLit('GLASS_SHADOWS');
+  }
+
+  /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+  private enableLit(feature: LitSwitch): void {
+    if (this.pipelines.litSwitches[feature]) return;
+    void this.pipelines.enable(feature);
+    if (this.overlayPipelines !== this.pipelines) void this.overlayPipelines.enable(feature);
+    if (this.latePipelines !== this.pipelines) void this.latePipelines.enable(feature);
+  }
   /** One resolution every glass caster is read through, so recording one allocates nothing. */
   private readonly glassCasterScratch: ResolvedGlass = {
     transmission: 0,
@@ -5462,6 +5509,7 @@ export class WebGPURenderer implements RendererApi {
         /* Glass: kept aside for its own two passes rather than dropped. See `glassCasters.ts`. */
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordMesh(mesh, model, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5517,6 +5565,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordInstanced(batch, data, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5572,6 +5621,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordSkinned(mesh, model, palette, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5968,6 +6018,7 @@ export class WebGPURenderer implements RendererApi {
       quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format,
       this.samples,
       glassShadows,
+      quality.clusteredLights,
     );
     /*
      * The canvas' own state, for the pass `ensurePass` reopens after `endFrame`.
@@ -5980,11 +6031,11 @@ export class WebGPURenderer implements RendererApi {
     this.overlayPipelines =
       this.pipelines.format === surface.format && this.samples === 1
         ? this.pipelines
-        : new PipelineCache(device, surface.format, 1, glassShadows);
+        : new PipelineCache(device, surface.format, 1, glassShadows, quality.clusteredLights);
     this.latePipelines =
       this.pipelines.format === RECON_HISTORY_FORMAT && this.samples === 1
         ? this.pipelines
-        : new PipelineCache(device, RECON_HISTORY_FORMAT, 1, glassShadows);
+        : new PipelineCache(device, RECON_HISTORY_FORMAT, 1, glassShadows, quality.clusteredLights);
     this.issueBound = this.issueCommand.bind(this);
     this.pipelineTargets =
       this.overlayPipelines === this.pipelines
@@ -6288,7 +6339,10 @@ export class WebGPURenderer implements RendererApi {
       /* The albedo's effects table, or a one-texel stand-in the shader's size test reads as none.
          The albedo is the group's key, so its table needs no key of its own. */
       if (name === 'uSurfaceEffects') {
-        return { view: this.albedo?.effectsView ?? blankView, sampler: blankSampler };
+        const effects = this.albedo?.effectsView ?? null;
+        /* The first table bound is when the lit pipelines start reading one. See `litSwitches`. */
+        if (effects !== null) this.enableLit('SURFACE_EFFECTS');
+        return { view: effects ?? blankView, sampler: blankSampler };
       }
       /*
        * The room, once a bake has filled it. Unbaked reads as the blank cube: nothing to mirror.
@@ -7750,8 +7804,10 @@ export class WebGPURenderer implements RendererApi {
      * these per draw through the material block, the same shape `uOpacity` already uses.
      */
     i[at('uLightingEnabled')] = 1;
-    i[at('uFogEnabled')] = 1;
+    i[at('uFogEnabled')] = FOG_RECEDE;
+    this.surfaceFog = FOG_RECEDE;
     i[at('uAlbedoEnabled')] = 0;
+    this.materialHasMaps = false;
 
     /*
      * **The camera medium, which this pass did not upload until 2026-08-29.**
@@ -8201,6 +8257,8 @@ export class WebGPURenderer implements RendererApi {
     this.bindGroup = this.blankAlbedoBindGroup;
     this.uvScale[0] = 1;
     this.uvScale[1] = 1;
+    this.uvOffset[0] = 0;
+    this.uvOffset[1] = 0;
   }
 
   /**
@@ -8284,7 +8342,11 @@ export class WebGPURenderer implements RendererApi {
      * where it happened to pass, write motion for a surface no pixel of the frame belongs to.
      */
     if (this.tracksMotionNow()) this.recordDrawMotion(mesh, model, previousModel);
-    this.submitMesh(mesh, model, tint, 1, false, { depthLayer });
+    noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
+    /* An opaque draw meets the medium as the dial says: `submitMesh` reads an absent `fog` as
+       true, which is a translucent draw's default and would put every opaque draw back in the fog
+       `setSurfaceFog(false)` took it out of. */
+    this.submitMesh(mesh, model, tint, 1, false, { depthLayer, fog: this.surfaceFog !== FOG_OFF });
   }
 
   /**
@@ -8389,6 +8451,7 @@ export class WebGPURenderer implements RendererApi {
       return;
     }
 
+    noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
     /* The tint travels in the options here, where `drawMesh` takes it positionally — see
        `TranslucentMeshOptions.tint` for why, and for the fade it was added for. */
     this.submitMesh(
@@ -8465,6 +8528,7 @@ export class WebGPURenderer implements RendererApi {
     /* The material's repeats, not a constant: geometry authored in metres is textured at
        whatever density the material asks for without rebuilding it. */
     this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvScale.offset, this.uvScale);
+    this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvOffset.offset, this.uvOffset);
     this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uLightViewProj.offset, this.lightViewProj);
     /*
      * Whether this mesh's tangent frame is real. WebGPU has no disabled attribute, so location 10
@@ -8498,7 +8562,7 @@ export class WebGPURenderer implements RendererApi {
     /* 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;
-    const unlitOrUnfogged = !lit || fog !== FOG_RECEDE;
+    const unlitOrUnfogged = !lit || fog !== this.surfaceFog;
     if (unlitOrUnfogged) {
       if (!lit) this.perFrameInts[this.materialField('uLightingEnabled')] = 0;
       this.perFrameInts[this.materialField('uFogEnabled')] = fog;
@@ -8520,7 +8584,7 @@ export class WebGPURenderer implements RendererApi {
     const refracting = this.bindSeeThrough(options);
     /* Taken for itself when any of those 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 });
+    const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
     if (own) this.materials.dirty();
     const base = (mesh as GpuMesh & { key?: string }).key ?? 'flat:s0:u0';
     /*
@@ -8664,7 +8728,7 @@ export class WebGPURenderer implements RendererApi {
     }
     if (unlitOrUnfogged) {
       if (!lit) this.perFrameInts[this.materialField('uLightingEnabled')] = 1;
-      this.perFrameInts[this.materialField('uFogEnabled')] = FOG_RECEDE;
+      this.perFrameInts[this.materialField('uFogEnabled')] = this.surfaceFog;
     }
     /* Back to off for every other draw in the frame, exactly as `uOpacity` is: this scratch is
        shared, so a strength left set is worn by everything drawn after it. */
@@ -8911,6 +8975,7 @@ export class WebGPURenderer implements RendererApi {
       lands ? this.correctedViewProj : this.viewProj,
     );
     this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvScale.offset, this.uvScale);
+    this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uUvOffset.offset, this.uvOffset);
     this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uLightViewProj.offset, this.lightViewProj);
     this.perDraw.writeInt(slot, FLAT_VERT_FIELDS.uHasTangents.offset, mesh.hasTangents ? 1 : 0);
 
@@ -8921,7 +8986,7 @@ export class WebGPURenderer implements RendererApi {
     const lit = options.lit ?? true;
     const fog = fogModeOf(options.fog ?? true, blend && options.additive === true);
     const toneMapped = options.toneMapped ?? true;
-    const unlitOrUnfogged = !lit || fog !== FOG_RECEDE;
+    const unlitOrUnfogged = !lit || fog !== this.surfaceFog;
     if (unlitOrUnfogged) {
       if (!lit) this.perFrameInts[this.materialField('uLightingEnabled')] = 0;
       this.perFrameInts[this.materialField('uFogEnabled')] = fog;
@@ -8934,7 +8999,7 @@ export class WebGPURenderer implements RendererApi {
     const layer = Math.min(Math.max(Math.round(options.depthLayer ?? 0), 0), MAX_DEPTH_LAYER);
     /* A blended batch shows what is behind it — refraction or glass — as a single draw does. */
     const refracting = blend && this.bindSeeThrough(options);
-    const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+    const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
     if (own) this.materials.dirty();
     const base = (mesh as GpuMesh & { key?: string }).key ?? 'flat:s0:u0';
     /* `|inst` in the key, for the reason every other suffix is there: an instanced pipeline binds
@@ -9016,7 +9081,7 @@ export class WebGPURenderer implements RendererApi {
     }
     if (unlitOrUnfogged) {
       this.perFrameInts[this.materialField('uLightingEnabled')] = 1;
-      this.perFrameInts[this.materialField('uFogEnabled')] = FOG_RECEDE;
+      this.perFrameInts[this.materialField('uFogEnabled')] = this.surfaceFog;
     }
     if (!toneMapped) {
       this.perFrameInts[this.materialField('uOutputTransform')] = this.gradeCode();
@@ -11578,7 +11643,7 @@ export class WebGPURenderer implements RendererApi {
         'post.ssrResolve',
         SSR_RESOLVE_FRAG_WGSL,
         this.pipelines.format,
-        PREMULTIPLIED_OVER_BLEND,
+        REFLECTION_OVER_BLEND,
       ),
     );
     resolve.setBindGroup(0, resolveGroup);
@@ -12598,6 +12663,7 @@ export class WebGPURenderer implements RendererApi {
     command.instances = 1;
     command.indirect = null;
     recordNode(this.arena, VERB_DRAW, reads, writes, at, 0);
+    if (this.framePresented) this.queueOverlayFlush();
     return command;
   }
 
@@ -12613,11 +12679,7 @@ export class WebGPURenderer implements RendererApi {
     if (verb === VERB_PASS) {
       const definition = passAt(this.passes, nodeState(this.arena, at));
       if (definition === undefined) return;
-      this.passContext.pass = pass;
-      /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
-      this.passContext.outputTransform = this.gradeCode();
-      this.passContext.outputExposure = this.gradeExposure();
-      definition.draw(this.passContext as PassContext);
+      definition.draw(this.fillPassContext(pass));
       return;
     }
     if (verb !== VERB_DRAW) return;
@@ -12704,6 +12766,16 @@ export class WebGPURenderer implements RendererApi {
   }
 
   private openPass(): GPURenderPassEncoder | null {
+    const was = this.pass;
+    const pass = this.openAnyPass();
+    /* A pass opened while a view model is drawn starts with the whole depth range: squeeze it. */
+    if (this.viewModelActive && pass !== null && pass !== was && !this.reflectionPassActive) {
+      this.squeezeViewport(pass);
+    }
+    return pass;
+  }
+
+  private openAnyPass(): GPURenderPassEncoder | null {
     /* While the replay is running this is the only pass there is. See `oitEncoder`. */
     if (this.oitEncoder !== null) return this.oitEncoder;
     /*
@@ -12797,19 +12869,31 @@ export class WebGPURenderer implements RendererApi {
     });
     this.overlayActive = true;
 
-    /*
-     * **Submitted on a microtask, which runs before the browser presents.** There is no second
-     * `endFrame` to hang this on — a consumer thinks the frame is over — and presentation happens
-     * when the task ends, after the microtask checkpoint. Anything that needs the pixels sooner
-     * flushes synchronously; `copyRegionTo` is the one that does.
-     */
-    if (!this.overlayFlushQueued) {
-      this.overlayFlushQueued = true;
-      queueMicrotask(() => this.flushOverlay());
-    }
+    this.queueOverlayFlush();
     return this.pass;
   }
 
+  /**
+   * Submit what is drawn after the present on a microtask, which runs before the browser presents.
+   *
+   * There is no second `endFrame` to hang this on — a consumer thinks the frame is over — and
+   * presentation happens when the task ends, after the microtask checkpoint. Anything that needs
+   * the pixels sooner flushes synchronously; `copyRegionTo` is the one that does.
+   *
+   * **Queued wherever such work begins: where the overlay pass opens, and where a verb records.**
+   * With the graph on a verb records rather than opening a pass, and until 4.8.2 only an opening
+   * queued this, so `fillPanel` and a contributed pass drawn after `endFrame` waited for the next
+   * `beginFrame` — whose replay drew onto a canvas texture already presented and destroyed.
+   */
+  private queueOverlayFlush(): void {
+    if (this.overlayFlushQueued) return;
+    this.overlayFlushQueued = true;
+    queueMicrotask(this.flushOverlayBound);
+  }
+
+  /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+  private readonly flushOverlayBound = (): void => this.flushOverlay();
+
   /**
    * The cache whose pipelines match the pass this draw will land in.
    *
@@ -12873,6 +12957,8 @@ export class WebGPURenderer implements RendererApi {
   }
 
   endFrame(): void {
+    /* A view model left open would squeeze every pass after the world, the composite included. */
+    if (this.viewModelActive) this.endViewModel();
     this.inFrame = false;
     if (this.surface.lost || this.encoder === null) return;
     /*
@@ -13341,14 +13427,40 @@ export class WebGPURenderer implements RendererApi {
     outputTransform: number;
     outputExposure: number;
     jitter: Float32Array;
+    format: GPUTextureFormat;
+    depthFormat: GPUTextureFormat;
+    samples: number;
   } = {
     backend: 'webgpu',
     pass: null,
     outputTransform: 0,
     outputExposure: 1,
     jitter: this.passJitter,
+    format: 'rgba8unorm',
+    depthFormat: DEPTH_FORMAT,
+    samples: 1,
   };
 
+  /**
+   * Fill the context a contributed pass draws with, for the pass it is about to draw into.
+   *
+   * **The attachments as well as the encoder**: a pass drawn after `endFrame` lands on the canvas
+   * at one sample where the frame's own is the scene target at the scene's samples, and a pipeline
+   * built for the one is refused by the other. The cache a mesh drawn here would use is the answer,
+   * so the two cannot disagree.
+   */
+  private fillPassContext(pass: GPURenderPassEncoder): PassContext {
+    const target = this.targetPipelines();
+    const context = this.passContext;
+    context.pass = pass;
+    /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
+    context.outputTransform = this.gradeCode();
+    context.outputExposure = this.gradeExposure();
+    context.format = target.format;
+    context.samples = target.sampleCount;
+    return context as PassContext;
+  }
+
   /**
    * Let something outside this file draw into the frame. See `Renderer.registerPass`.
    *
@@ -13502,11 +13614,7 @@ export class WebGPURenderer implements RendererApi {
     if (!this.quality.frameGraph) {
       const pass = this.openPass();
       if (pass === null) return;
-      this.passContext.pass = pass;
-      /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
-      this.passContext.outputTransform = this.gradeCode();
-      this.passContext.outputExposure = this.gradeExposure();
-      definition.draw(this.passContext as PassContext);
+      definition.draw(this.fillPassContext(pass));
       return;
     }
     recordNode(
@@ -13517,6 +13625,7 @@ export class WebGPURenderer implements RendererApi {
       handle,
       0,
     );
+    if (this.framePresented) this.queueOverlayFlush();
   }
 
   /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
@@ -13728,7 +13837,10 @@ export class WebGPURenderer implements RendererApi {
    * **The clear is a drawn quad rather than a clear**, because WebGPU clears whole attachments
    * and cannot confine one to a scissor. See `insetPass.ts`.
    *
-   * Returns the drawing-buffer height of the inset, as the other backend does.
+   * Returns the **aspect** of the inset, width over height in the pixels its viewport got, as the
+   * other backend does — for `camera.updateMatrices`. With no pass to draw into, a lost device,
+   * it is the aspect of the box asked for: there are no pixels to measure, and a zero would be a
+   * projection of infinities in the caller's camera.
    */
   beginInset(rect: InsetRect, clearColor: Vec3 | null): number {
     /*
@@ -13738,7 +13850,8 @@ export class WebGPURenderer implements RendererApi {
      */
     if (this.quality.frameGraph) this.flushGraph();
     const pass = this.openPass();
-    if (this.surface.lost || pass === null) return 0;
+    if (this.surface.lost || pass === null)
+      return Math.max(rect.width, 1) / Math.max(rect.height, 1);
     const canvas = this.surface.context.canvas as HTMLCanvasElement;
     const cssWidth = Math.max(canvas.clientWidth, 1);
     const cssHeight = Math.max(canvas.clientHeight, 1);
@@ -13843,6 +13956,43 @@ export class WebGPURenderer implements RendererApi {
     return w / h;
   }
 
+  /**
+   * Draw what follows as a **view model**, in the nearest sliver of depth, until `endViewModel`.
+   *
+   * The twin of the WebGL2 method, which carries the reasons. Here the squeeze is the viewport's
+   * depth bounds, which are pass state applied when a draw is issued, so both ends flush the graph
+   * as an inset's do, and a pass opened in between is given the bounds again in `openPass`.
+   */
+  beginViewModel(share = VIEW_MODEL_DEPTH_SHARE): void {
+    if (this.quality.frameGraph) this.flushGraph();
+    viewModelDepthRange(this.reversedDepth, share, this.viewModelRange);
+    this.viewModelActive = true;
+    const pass = this.openPass();
+    if (this.surface.lost || pass === null) return;
+    this.squeezeViewport(pass);
+  }
+
+  /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+  endViewModel(): void {
+    if (!this.viewModelActive) return;
+    if (this.quality.frameGraph) this.flushGraph();
+    this.viewModelActive = false;
+    const pass = this.pass;
+    if (this.surface.lost || pass === null) return;
+    const [width, height] = this.passSize();
+    pass.setViewport(0, 0, width, height, 0, 1);
+  }
+
+  /** The view model's depth bounds on the whole of the pass. */
+  private squeezeViewport(pass: GPURenderPassEncoder): void {
+    const [width, height] = this.passSize();
+    pass.setViewport(0, 0, width, height, this.viewModelRange[0], this.viewModelRange[1]);
+  }
+
+  /** Whether a view model is being drawn: `openPass` re-applies it, `endFrame` closes it. */
+  private viewModelActive = false;
+  private readonly viewModelRange: [number, number] = [0, 1];
+
   /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
   endInset(): void {
     /*
@@ -15030,6 +15180,8 @@ export class WebGPURenderer implements RendererApi {
     this.iesRows = this.iesAtlas.height;
     this.iesPlanes = this.iesAtlas.planes;
     this.cookieTiles = this.cookieImages.length;
+    /* The first profile or cookie is when the lit pipelines start reading them. See `litSwitches`. */
+    if (this.iesRows > 1 || this.cookieTiles > 0) this.enableLit('LIGHT_FIXTURES');
     return this.fixtureView;
   }
 
@@ -15125,6 +15277,8 @@ export class WebGPURenderer implements RendererApi {
     );
     this.driftIndex = index;
     this.driftAtlas = atlas;
+    /* The first volume is when the lit pipelines start reading one. See `litSwitches`. */
+    this.enableLit('DRIFT_LIGHT');
     this.driftIndexView = index.createView({ dimension: '3d' });
     this.driftAtlasView = atlas.createView({ dimension: '3d' });
     this.bakeLightField = {

package/src/render/backend/webgpu/sdfTextPass.ts

@@ -11,6 +11,7 @@ import type { SdfFont } from '../../sdfFont.ts';
 import { SdfTextLayout, type SdfTextStyle } from '../../sdfTextLayout.ts';
 import type { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The SDF text pass: a string as flat, textured quads, drawn into the scene.
@@ -213,7 +214,7 @@ export function sdfTextPipeline(
           format: cache.format,
           blend: {
             color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
           },
         },
       ],

package/src/render/backend/webgpu/textPass.ts

@@ -9,6 +9,7 @@ import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The text pass: a string as instanced glyph cubes, drawn over the scene.
@@ -208,7 +209,7 @@ export function textPipeline(
           format: cache.format,
           blend: {
             color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
           },
         },
       ],

package/src/render/backend/webgpu/waterPass.ts

@@ -9,6 +9,7 @@ import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { UniformFields } from './scatterPass.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The water pass: two sheets and a patch, displaced by a wave field in the vertex stage.
@@ -199,7 +200,7 @@ export function waterPipeline(
           format: cache.format,
           blend: {
             color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
           },
         },
       ],

package/src/render/backend/webgpu/windStreakPass.ts

@@ -9,6 +9,7 @@ import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The wind-streak pass: a lattice of debris that follows the camera and wraps.
@@ -184,7 +185,7 @@ export function windStreakPipeline(
               dstFactor: 'one-minus-src-alpha',
               operation: 'add',
             },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
           },
         },
       ],

package/src/render/boltBatch.ts

@@ -2,6 +2,7 @@ import { compileProgram, uniformLocations } from './shader.ts';
 import { BOLT_FRAG, BOLT_VERT } from './shaders/bolt.ts';
 import { buildSegmentQuads, expandBoltSegments } from './segmentQuads.ts';
 import type { BoltSegments } from './boltPool.ts';
+import { blendKeeping } from './sceneCoverage.ts';
 
 /**
  * One draw call for a pool of electrical arcs.
@@ -86,7 +87,7 @@ export class BoltBatch {
   drawTo(gl: WebGL2RenderingContext, segmentCount: number): void {
     if (segmentCount === 0) return;
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+    blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
     gl.depthMask(false);
     gl.disable(gl.CULL_FACE);
 

package/src/render/causticsRenderer.ts

@@ -7,6 +7,7 @@ import type { Atmosphere } from './atmosphere.ts';
 import { buildSheets } from './surfaceSheet.ts';
 import type { SheetSpan } from './surfaceSheet.ts';
 import { seaStateForWind } from './seaState.ts';
+import { blendKeeping } from './sceneCoverage.ts';
 
 /**
  * A surface lit by nearby water: the floor of a pool, the bottom of a flooded
@@ -149,7 +150,7 @@ export class CausticsRenderer {
     bindAtmosphere(gl, u, atmosphere, camera.position[1] ?? 0, underwaterEnabled);
 
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.ONE, gl.ONE);
+    blendKeeping(gl, gl.ONE, gl.ONE);
     /*
      * No depth write, but depth *testing* stays on: the sheet sits a couple of
      * centimetres under the surface it lights, so geometry in front of it — the