@driftengine/core 4.8.1 → 4.8.3

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

@@ -1113,8 +1113,17 @@ export declare class WebGPURenderer implements RendererApi {
     private blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
     private readonly uvScale;
+    /** Where the texture starts, after the scale. Per draw, beside `uvScale`. */
+    private readonly uvOffset;
+    /**
+     * 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;
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     private materialDoubleSided;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    private materialHasMaps;
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): GpuSurfaceTexture;
     /** Several images of one size as an array's layers. See `RendererApi.createSurfaceTextureArray`. */
     createSurfaceTextureArray(sources: readonly TexImageSource[], options?: SurfaceTextureOptions): GpuSurfaceTexture;
@@ -1196,6 +1205,8 @@ export declare class WebGPURenderer implements RendererApi {
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
     setEnvironmentGain(gain: number): void;
     setSurfaceGrain(amount: number): void;
+    /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
+    setSurfaceFog(enabled: boolean): void;
     /**
      * How much of the surfaces drawn next survives a screen-door dither. See `renderer.ts`.
      *
@@ -1814,7 +1825,7 @@ export declare class WebGPURenderer implements RendererApi {
      */
     /** The cutout bind group for `texture` in the open layer, built the first time it casts there. */
     private cutoutGroup;
-    /** 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;
     private shadowGroup;
     /**
@@ -1834,6 +1845,16 @@ export declare class WebGPURenderer implements RendererApi {
      */
     /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
     private readonly glassCasters;
+    /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+    private glassSeen;
+    /**
+     * 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;
+    /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+    private enableLit;
     /** One resolution every glass caster is read through, so recording one allocates nothing. */
     private readonly glassCasterScratch;
     private readonly casterSink;
@@ -2944,6 +2965,22 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private canDraw;
     private openPass;
+    private openAnyPass;
+    /**
+     * 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;
+    /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+    private readonly flushOverlayBound;
     /**
      * The cache whose pipelines match the pass this draw will land in.
      *
@@ -3159,6 +3196,15 @@ export declare class WebGPURenderer implements RendererApi {
      * context is valid for the duration of the call for exactly this reason.
      */
     private readonly passContext;
+    /**
+     * 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;
     /**
      * Let something outside this file draw into the frame. See `Renderer.registerPass`.
      *
@@ -3313,9 +3359,27 @@ export declare 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;
+    /**
+     * 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?: number): void;
+    /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+    endViewModel(): void;
+    /** The view model's depth bounds on the whole of the pass. */
+    private squeezeViewport;
+    /** Whether a view model is being drawn: `openPass` re-applies it, `endFrame` closes it. */
+    private viewModelActive;
+    private readonly viewModelRange;
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset(): void;
     /**

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

@@ -61,7 +61,7 @@ import { ExposurePass } from './exposurePass.js';
 import { AO_STORE } from '../../shaders/ambientOcclusion.js';
 import { clampAutoExposure } from '../../shaders/exposure.js';
 import { clampLocalExposure } from '../../shaders/localExposure.js';
-import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, postPipelineTargets, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
+import { createDepthResolveLayout, createPostStageLayout, depthResolvePipeline, postPipeline, postPipelineTargets, sceneColorFormat, AO_BLUR_FIELDS, AO_BLUR_FRAG_WGSL, AO_BLUR_SIZE, AO_BLUR_TEXTURES, AO_BLUR_UNIFORMS, AO_FRAG_FIELDS, AO_FRAG_SIZE, AO_FRAG_WGSL, AO_TEXTURES, AO_UNIFORMS, ADDITIVE_BLEND, BLOOM_DOWNSAMPLE_FIELDS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FIELDS, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_STAGE_SIZE, BLOOM_TEXTURES, BLOOM_UNIFORMS, BLOOM_UPSAMPLE_FIELDS, BLOOM_UPSAMPLE_FRAG_WGSL, RESOLVED_DEPTH_FORMAT, RUSH_FRAG_FIELDS, RUSH_FRAG_SIZE, RUSH_FRAG_WGSL, RUSH_TEXTURES, RUSH_UNIFORMS, TAA_FRAG_FIELDS, TAA_FRAG_SIZE, TAA_TEXTURES, TAA_UNIFORMS, TEMPORAL_RESOLVE_FRAG_WGSL, MEDIUM_FRAG_FIELDS, MEDIUM_FRAG_SIZE, MEDIUM_FRAG_WGSL, MEDIUM_TEXTURES, MEDIUM_TRANSMIT_BLEND, MEDIUM_UNIFORMS, MEDIUM_UPSAMPLE_FIELDS, MEDIUM_UPSAMPLE_FRAG_WGSL, MEDIUM_UPSAMPLE_SIZE, MEDIUM_UPSAMPLE_TEXTURES, MEDIUM_UPSAMPLE_UNIFORMS, OIT_COMPOSITE_BLEND, OIT_RESOLVE_FRAG_WGSL, OIT_TEXTURES, DECAL_FRAG_FIELDS, DECAL_FRAG_SIZE, DECAL_MULTIPLY_BLEND, DECAL_PROJECT_FRAG_WGSL, DECAL_TEXTURES, DECAL_UNIFORMS, PREMULTIPLIED_OVER_BLEND, REFLECTION_OVER_BLEND, SSR_FRAG_FIELDS, SSR_FRAG_SIZE, SSR_RESOLVE_FRAG_WGSL, SSR_RESOLVE_TEXTURES, SSR_TEXTURES, SSR_TRACE_FRAG_WGSL, SSR_UNIFORMS, createOitResolveLayout, createSsrResolveLayout, } from './postPass.js';
 import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from '../../colourGrade.js';
 import { FILM_LOOK_WITHOUT_COMPOSITE, clampGrain, clampVignette, grainSeed, } from '../../shaders/filmLook.js';
 import { createProbeMipBindGroupLayout, createProbePrefilterBindGroupLayout, PREFILTER_UNIFORM_OFFSETS, probeLevels, probeMipPipeline, probePrefilterPipeline, PROBE_FACES, PROBE_FACE_BASIS, PROBE_FAR_M, PROBE_FOV_DEG, PROBE_MIP_UNIFORM_SIZE, PROBE_NEAR_M, } from './probePass.js';
@@ -77,6 +77,8 @@ import { resolvePointLights } from '../../lightBudget.js';
 import { resolveRenderQuality } from '../../renderQuality.js';
 import { DEFAULT_GLOBAL_MEDIUM, mediumActive, mediumTargetSize, WEAK_GPU_MEDIUM_STEPS, resolveGlobalMedium, } from '../../globalMedium.js';
 import { castsDepth, glassOf } from '../../shadowCasters.js';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.js';
 import { GlassCasterList } from '../../glassCasters.js';
 import { GpuGlassTint } from './glassTintPass.js';
 import { SUN_DYNAMIC_LAYER, SUN_GLASS_MOVING_LAYER, SUN_GLASS_STATIC_LAYER, SUN_PEELED_LAYER, SUN_STATIC_LAYER, } from '../../shadowMap.js';
@@ -98,7 +100,7 @@ import { LIGHT_VOLUME_VERT_FIELDS, LIGHT_VOLUME_VERT_SIZE, createLightVolumeBind
 import { aimReflection, createGpuReflection } from './reflectionPass.js';
 import { FrameBudget } from '../budget.js';
 import { MaterialChanges, ownsMaterial } from '../materialChanges.js';
-import { FOG_RECEDE, fogModeOf } from '../drawFog.js';
+import { FOG_OFF, FOG_RECEDE, fogModeOf } from '../drawFog.js';
 import { DYNAMIC_ALIGNMENT as DYNAMIC_UNIFORM_ALIGNMENT, UniformRing } from './uniformRing.js';
 import { DecalQueue, MAX_DRAWN_DECALS } from '../../decalQueue.js';
 import { DistanceFieldScene } from '../../gi/fieldScene.js';
@@ -2129,8 +2131,17 @@ export class WebGPURenderer {
     blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
     uvScale = new Float32Array([1, 1]);
+    /** Where the texture starts, after the scale. Per draw, beside `uvScale`. */
+    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.
+     */
+    surfaceFog = FOG_RECEDE;
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     materialDoubleSided = false;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    materialHasMaps = false;
     createSurfaceTexture(source, options = {}) {
         return new GpuSurfaceTexture(this.surface.device, this.pipelines, source, options);
     }
@@ -2256,7 +2267,10 @@ export class WebGPURenderer {
         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);
         const orm = (material?.orm ?? null);
         const emissiveMap = (material?.emissive ?? null);
@@ -2403,6 +2417,13 @@ export class WebGPURenderer {
             f[this.materialField('uGrain')] = Math.min(1, Math.max(0, amount));
         });
     }
+    /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
+    setSurfaceFog(enabled) {
+        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`.
      *
@@ -4358,10 +4379,12 @@ export class WebGPURenderer {
         groups.set(texture, group);
         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. */
     writeCutout(slot, cutout, fields) {
         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);
     }
     shadowGroup() {
@@ -4400,6 +4423,29 @@ export class WebGPURenderer {
      */
     /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
     glassCasters = new GlassCasterList();
+    /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+    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.
+     */
+    noteGlassCaster() {
+        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. */
+    enableLit(feature) {
+        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. */
     glassCasterScratch = {
         transmission: 0,
@@ -4412,6 +4458,7 @@ export class WebGPURenderer {
                 /* 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;
             }
@@ -4451,6 +4498,7 @@ export class WebGPURenderer {
             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;
             }
@@ -4491,6 +4539,7 @@ export class WebGPURenderer {
             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;
             }
@@ -4833,7 +4882,7 @@ export class WebGPURenderer {
          */
         /* Off compiles none of the glass lookup into a lit pipeline: see `PipelineCache.glassShadows`. */
         const glassShadows = quality.glassShadows !== 'off';
-        this.pipelines = new PipelineCache(device, quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format, this.samples, glassShadows);
+        this.pipelines = new PipelineCache(device, quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format, this.samples, glassShadows, quality.clusteredLights);
         /*
          * The canvas' own state, for the pass `ensurePass` reopens after `endFrame`.
          *
@@ -4845,11 +4894,11 @@ export class WebGPURenderer {
         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
@@ -5123,7 +5172,11 @@ export class WebGPURenderer {
             /* 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.
@@ -6213,8 +6266,10 @@ export class WebGPURenderer {
          * 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.**
          *
@@ -6630,6 +6685,8 @@ export class WebGPURenderer {
         this.bindGroup = this.blankAlbedoBindGroup;
         this.uvScale[0] = 1;
         this.uvScale[1] = 1;
+        this.uvOffset[0] = 0;
+        this.uvOffset[1] = 0;
     }
     /**
      * The slot the next draw's material lives in, taking a new one when something dirtied it.
@@ -6707,7 +6764,11 @@ export class WebGPURenderer {
          */
         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 });
     }
     /**
      * Draw a mesh that lets the world through, at `opacity`.
@@ -6801,6 +6862,7 @@ export class WebGPURenderer {
             this.translucentQueue.record(mesh, model, opacity, options);
             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(mesh, model, options.tint ?? null, Math.min(opacity, 1), true, options);
@@ -6856,6 +6918,7 @@ export class WebGPURenderer {
         /* 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
@@ -6888,7 +6951,7 @@ export class WebGPURenderer {
         /* 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;
@@ -6911,7 +6974,7 @@ export class WebGPURenderer {
         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.key ?? 'flat:s0:u0';
@@ -7041,7 +7104,7 @@ export class WebGPURenderer {
         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. */
@@ -7246,6 +7309,7 @@ export class WebGPURenderer {
         const lands = blend && options.reconstructed !== true && this.drawsLate();
         this.perDraw.writeFloats(slot, FLAT_VERT_FIELDS.uViewProj.offset, 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);
         const dimmed = opacity < 1;
@@ -7255,7 +7319,7 @@ export class WebGPURenderer {
         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;
@@ -7268,7 +7332,7 @@ export class WebGPURenderer {
         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.key ?? 'flat:s0:u0';
@@ -7337,7 +7401,7 @@ export class WebGPURenderer {
         }
         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();
@@ -9545,7 +9609,7 @@ export class WebGPURenderer {
             label: 'post.ssr.resolve',
             colorAttachments: [{ view: scene, loadOp: 'load', storeOp: 'store' }],
         });
-        resolve.setPipeline(postPipeline(this.pipelines, device, this.ssrResolveLayout, 'post.ssrResolve', SSR_RESOLVE_FRAG_WGSL, this.pipelines.format, PREMULTIPLIED_OVER_BLEND));
+        resolve.setPipeline(postPipeline(this.pipelines, device, this.ssrResolveLayout, 'post.ssrResolve', SSR_RESOLVE_FRAG_WGSL, this.pipelines.format, REFLECTION_OVER_BLEND));
         resolve.setBindGroup(0, resolveGroup);
         resolve.draw(3);
         resolve.end();
@@ -10442,6 +10506,8 @@ export class WebGPURenderer {
         command.instances = 1;
         command.indirect = null;
         recordNode(this.arena, VERB_DRAW, reads, writes, at, 0);
+        if (this.framePresented)
+            this.queueOverlayFlush();
         return command;
     }
     /** Replay one recorded draw into an open pass. */
@@ -10457,11 +10523,7 @@ export class WebGPURenderer {
             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);
+            definition.draw(this.fillPassContext(pass));
             return;
         }
         if (verb !== VERB_DRAW)
@@ -10558,6 +10620,15 @@ export class WebGPURenderer {
         return this.framePresented;
     }
     openPass() {
+        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;
+    }
+    openAnyPass() {
         /* While the replay is running this is the only pass there is. See `oitEncoder`. */
         if (this.oitEncoder !== null)
             return this.oitEncoder;
@@ -10649,18 +10720,29 @@ export class WebGPURenderer {
                 },
         });
         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.
+     */
+    queueOverlayFlush() {
+        if (this.overlayFlushQueued)
+            return;
+        this.overlayFlushQueued = true;
+        queueMicrotask(this.flushOverlayBound);
+    }
+    /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+    flushOverlayBound = () => this.flushOverlay();
     /**
      * The cache whose pipelines match the pass this draw will land in.
      *
@@ -10725,6 +10807,9 @@ export class WebGPURenderer {
         this.encoder = null;
     }
     endFrame() {
+        /* 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;
@@ -11148,7 +11233,29 @@ export class WebGPURenderer {
         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.
+     */
+    fillPassContext(pass) {
+        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;
+    }
     /**
      * Let something outside this file draw into the frame. See `Renderer.registerPass`.
      *
@@ -11286,14 +11393,12 @@ export class WebGPURenderer {
             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);
+            definition.draw(this.fillPassContext(pass));
             return;
         }
         recordNode(this.arena, VERB_PASS, this.passReads.get(handle) ?? 0, this.currentTarget(), handle, 0);
+        if (this.framePresented)
+            this.queueOverlayFlush();
     }
     /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
     unregisterPass(handle) {
@@ -11485,7 +11590,10 @@ export class WebGPURenderer {
      * **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, clearColor) {
         /*
@@ -11497,7 +11605,7 @@ export class WebGPURenderer {
             this.flushGraph();
         const pass = this.openPass();
         if (this.surface.lost || pass === null)
-            return 0;
+            return Math.max(rect.width, 1) / Math.max(rect.height, 1);
         const canvas = this.surface.context.canvas;
         const cssWidth = Math.max(canvas.clientWidth, 1);
         const cssHeight = Math.max(canvas.clientHeight, 1);
@@ -11594,6 +11702,44 @@ export class WebGPURenderer {
          */
         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) {
+        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() {
+        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. */
+    squeezeViewport(pass) {
+        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. */
+    viewModelActive = false;
+    viewModelRange = [0, 1];
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset() {
         /*
@@ -12663,6 +12809,9 @@ export class WebGPURenderer {
         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;
     }
     /**
@@ -12739,6 +12888,8 @@ export class WebGPURenderer {
         device.queue.writeTexture({ texture: atlas }, field.atlas, { bytesPerRow: aw * 8, rowsPerImage: ah }, [aw, ah, ad]);
         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/dist/render/backend/webgpu/sdfTextPass.js

@@ -3,6 +3,7 @@ import { SDFTEXT_BINDINGS, SDF_TEXT_FRAG_WGSL, SDF_TEXT_VERT_WGSL, } from '../..
 import { DEPTH_FORMAT } from './flatPass.js';
 import { SdfTextLayout } from '../../sdfTextLayout.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The SDF text pass: a string as flat, textured quads, drawn into the scene.
  *
@@ -183,7 +184,7 @@ export function sdfTextPipeline(cache, device, layout) {
                     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/dist/render/backend/webgpu/textPass.js

@@ -3,6 +3,7 @@ import { TEXT_BINDINGS, TEXT_FRAG_WGSL, TEXT_VERT_WGSL, } from '../../shaders/ge
 import { MAX_CELLS, TEXT_CUBE, TextLayout } from '../../textLayout.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
 /**
  * The text pass: a string as instanced glyph cubes, drawn over the scene.
  *
@@ -174,7 +175,7 @@ export function textPipeline(cache, device, layout) {
                     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,
                     },
                 },
             ],