@driftengine/core 4.8.1 → 4.8.3

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

@@ -781,8 +781,8 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     get presentedFrames(): number;
     private presentedFrameCount;
-    private readonly flatProgram;
-    private readonly flatUniforms;
+    private flatProgram;
+    private flatUniforms;
     /**
      * The lit fragment source every flat program is built from, and the budget it was built at.
      *
@@ -793,7 +793,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * for a lazily compiled variant to end up at a different light budget from the one the renderer
      * uploads for, which is a picture nobody could explain.
      */
-    private readonly flatFragSource;
+    private flatFragSource;
     /**
      * How many lights this renderer's shader has room for, after the device had its say.
      *
@@ -936,6 +936,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly surfaceScene;
     /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
     private oitWeight;
+    /**
+     * 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;
     private ditherFade;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     private oitRefused;
@@ -1294,6 +1299,27 @@ export declare class WebGL2Renderer implements RendererApi {
      * each such draw and handed back, where the other backend bakes it into a pipeline.
      */
     private materialDoubleSided;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    private materialHasMaps;
+    /** The material last set, so a lit program rebuilt for glass can be given it. */
+    private currentMaterial;
+    /**
+     * The lit stage's switches: what the lit programs were compiled with (`litOn`), and what the
+     * profile and the content have asked for since (`litWanted`).
+     *
+     * **Each is off until it is used** — glass until a pane is offered, a fixture until one is loaded,
+     * the effects until a material carries a table, DriftLight until a volume is set — and then on for
+     * good, rebuilt at the next `beginFrame`. Clustering is the profile's. The code costs the lit pass
+     * registers on every surface whether it finds anything or not, and a world without the feature
+     * draws the same picture without it. `PipelineCache.litSwitches` makes the same decision on the
+     * other backend. The frame a feature is first used in draws without it; the rebuild is a
+     * synchronous compile, and the next frame waits for it.
+     */
+    private readonly litOn;
+    private readonly litWanted;
+    private litAsked;
+    /** Ask for a switch, which the next `beginFrame` compiles in. Never glass with it turned off. */
+    private askLit;
     /**
      * The one sink handed to every caster enumeration.
      *
@@ -1845,6 +1871,22 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     setEnvironmentAmbient(_amount: number): void;
     setSurfaceGrain(amount: number): void;
+    /**
+     * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
+     * True is the default, and what `bindMeshPass` restores.
+     *
+     * **The opaque counterpart of `TranslucentMeshOptions.fog`**, which a translucent draw has had
+     * all along; the shader's per-draw switch was there, and nothing reached it for an ordinary mesh.
+     * What it is for is a medium that darkens one thing and not another — a floor receding into the
+     * distance under figures that must keep their full value however far from the camera they stand.
+     * Material state like `setSurfaceGrain`: instanced and skinned draws read it too, and a
+     * translucent draw's own `fog` is measured against it and puts it back.
+     *
+     * **What it gives up** is the medium's honesty: a surface out of the fog is drawn as though the
+     * air between it and the eye were empty, so it should be a surface the scene means to stand
+     * apart, not one whose distance is the point.
+     */
+    setSurfaceFog(enabled: boolean): void;
     /**
      * One float of material state, into every flat program.
      *
@@ -1855,6 +1897,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * reads, drew what was asked.
      */
     private writeFlatFloat;
+    /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
+    private writeFlatInt;
     /**
      * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
      * of detail of one thing.
@@ -2523,6 +2567,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * rather than propagating. Only a shader that will not link at *any* budget throws, and it
      * throws a sentence with the device's numbers in it rather than a bare driver string.
      */
+    /** The lit fragment source this renderer's profile compiles, at a light budget. */
+    private flatFragAt;
+    /**
+     * Every lit program that exists, compiled again with the switches asked for since, at the budget
+     * the renderer already uploads for, and given the pass and the material the old one held.
+     *
+     * At `beginFrame`, not where a feature was first used: a pane is offered inside a shadow pass
+     * with the depth program bound, and a program swapped under it would draw the next caster with
+     * the lit one.
+     */
+    private rebuildLit;
     private fitFlatProgram;
     /**
      * How many point lights this renderer's shader shades at once.
@@ -2716,6 +2771,23 @@ export declare class WebGL2Renderer implements RendererApi {
     fillPanel(rect: InsetRect, color: Vec3, alpha: number): void;
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset(): void;
+    /**
+     * Draw what follows as a **view model**, in the nearest sliver of depth, until `endViewModel`.
+     *
+     * A first-person view model — arms and a held weapon — drawn with the frame's camera, or with one
+     * of its own through `bindMeshPass`, lands in front of anything past the near plane without the
+     * world's depth being cleared, so every pass that reads depth afterwards still sees the world.
+     * `share` is how much of the range it takes, 1% by default. See `viewModel.ts` for what it gives
+     * up, which includes temporal reconstruction: draw a view model with multisampling.
+     *
+     * Not inside an inset: an inset has its own depth, cleared for it, and needs no squeeze.
+     */
+    beginViewModel(share?: number): void;
+    /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+    endViewModel(): void;
+    /** Whether a view model is being drawn, so `endFrame` can close one the caller left open. */
+    private viewModelActive;
+    private readonly viewModelRange;
     /**
      * How much speed blur the frame about to be drawn should resolve with, 0 to 1.
      *

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

@@ -1,6 +1,7 @@
 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 { blendCovering, blendKeeping } from '../../sceneCoverage.js';
 import { mat4 } from 'gl-matrix';
 import { GL_DEPTH_REMAP, MAX_DEPTH_LAYER, depthClearFor, depthOffsetForLayer, GL_SHADOW_REMAP, REVERSED_DEPTH, SHADOW_DEPTH_CLEAR, glDepthFuncEqual, glShadowDepthFunc, } from '../../depthConvention.js';
 import { resolveGlass } from '../../glass.js';
@@ -93,6 +94,9 @@ import { deviceSnappedCellSize } from '../../textLayout.js';
 import { WindStreakRenderer } from '../../windStreakRenderer.js';
 import { InstancedBatch } from './instanced.js';
 import { cutoutOf } from '../../cutoutCaster.js';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.js';
+import { noLitSwitches } from '../../shaders/flat/glassTint.js';
 /**
  * How many frames `firstFrameSettled` will ask before it stops asking.
  *
@@ -557,6 +561,11 @@ export class WebGL2Renderer {
     surfaceScene = new Float32Array(4);
     /** The two halves of `uWriteMode`, kept here because a `vec2` is written whole. */
     oitWeight = 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;
     ditherFade = 0;
     /** Said once, not per frame, where the context cannot give the float target the sum needs. */
     oitRefused = false;
@@ -961,6 +970,34 @@ export class WebGL2Renderer {
      * each such draw and handed back, where the other backend bakes it into a pipeline.
      */
     materialDoubleSided = false;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    materialHasMaps = false;
+    /** The material last set, so a lit program rebuilt for glass can be given it. */
+    currentMaterial = null;
+    /**
+     * The lit stage's switches: what the lit programs were compiled with (`litOn`), and what the
+     * profile and the content have asked for since (`litWanted`).
+     *
+     * **Each is off until it is used** — glass until a pane is offered, a fixture until one is loaded,
+     * the effects until a material carries a table, DriftLight until a volume is set — and then on for
+     * good, rebuilt at the next `beginFrame`. Clustering is the profile's. The code costs the lit pass
+     * registers on every surface whether it finds anything or not, and a world without the feature
+     * draws the same picture without it. `PipelineCache.litSwitches` makes the same decision on the
+     * other backend. The frame a feature is first used in draws without it; the rebuild is a
+     * synchronous compile, and the next frame waits for it.
+     */
+    litOn = noLitSwitches();
+    litWanted = noLitSwitches();
+    litAsked = false;
+    /** Ask for a switch, which the next `beginFrame` compiles in. Never glass with it turned off. */
+    askLit(feature) {
+        if (this.litWanted[feature])
+            return;
+        if (feature === 'GLASS_SHADOWS' && this.quality.glassShadows === 'off')
+            return;
+        this.litWanted[feature] = true;
+        this.litAsked = true;
+    }
     /**
      * The one sink handed to every caster enumeration.
      *
@@ -992,6 +1029,7 @@ export class WebGL2Renderer {
                 /* 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.askLit('GLASS_SHADOWS');
                 }
                 return;
             }
@@ -1037,6 +1075,7 @@ export class WebGL2Renderer {
             if (!this.drawingGlassDepth && !castsDepth(material)) {
                 if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
                     this.glassCasters.recordInstanced(batch, data, material, this.glassCasterScratch);
+                    this.askLit('GLASS_SHADOWS');
                 }
                 return;
             }
@@ -1075,6 +1114,7 @@ export class WebGL2Renderer {
             if (!this.drawingGlassDepth && !castsDepth(material)) {
                 if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
                     this.glassCasters.recordSkinned(mesh, model, palette, material, this.glassCasterScratch);
+                    this.askLit('GLASS_SHADOWS');
                 }
                 return;
             }
@@ -1135,6 +1175,7 @@ export class WebGL2Renderer {
         if (this.activeDepthPeel)
             gl.uniform1i(u['uPreviousShadowMap'] ?? null, 0);
         gl.uniform2f(u['uUvScale'] ?? null, cutout.u, cutout.v);
+        gl.uniform2f(u['uUvOffset'] ?? null, cutout.uOffset, cutout.vOffset);
         gl.uniform1f(u['uAlphaCutout'] ?? null, cutout.cutoff);
         /* Narrowed for the reason the sink's own `mesh` gives: this renderer only hands out its own. */
         cutout.albedo.bind(gl, SURFACE_TEXTURE_UNIT);
@@ -1538,6 +1579,9 @@ export class WebGL2Renderer {
         this.iesRows = this.iesAtlas.height;
         this.iesPlanes = this.iesAtlas.planes;
         this.cookieTiles = this.cookieImages.length;
+        /* The first profile or cookie is when the lit programs start reading them. See `litOn`. */
+        if (this.iesRows > 1 || this.cookieTiles > 0)
+            this.askLit('LIGHT_FIXTURES');
         gl.bindTexture(gl.TEXTURE_2D, null);
         gl.activeTexture(gl.TEXTURE0);
     }
@@ -1896,6 +1940,9 @@ export class WebGL2Renderer {
          * Built for the profile this renderer resolved, not for every profile at once — so a
          * world with shadows off compiles none of the shadow path. See `shaders/flat.ts`.
          */
+        /* The one switch the profile decides; the rest wait for their content. See `litOn`. */
+        this.litOn.CLUSTERED_LIGHTS = this.quality.clusteredLights;
+        this.litWanted.CLUSTERED_LIGHTS = this.quality.clusteredLights;
         const fitted = this.fitFlatProgram(gl);
         this.flatProgram = fitted.program;
         this.flatFragSource = fitted.source;
@@ -2410,6 +2457,8 @@ export class WebGL2Renderer {
         this.materials.dirty();
         this.currentSurfaceTexture = material?.albedo ?? null;
         this.materialDoubleSided = material?.doubleSided === true;
+        this.materialHasMaps = materialHasMaps(material);
+        this.currentMaterial = material;
         /*
          * Written to every flat program, because material state persists across draws and a skinned
          * draw is entitled to the material the caller set before it. A second program holding none of
@@ -2499,6 +2548,7 @@ export class WebGL2Renderer {
          * how big a dome was — WebGPU writes it before its own early return and WebGL2 did not.
          */
         gl.uniform2f(u['uUvScale'] ?? null, material?.uScale ?? 1, material?.vScale ?? 1);
+        gl.uniform2f(u['uUvOffset'] ?? null, material?.uOffset ?? 0, material?.vOffset ?? 0);
         gl.uniform1i(u['uDoubleSided'] ?? null, material?.doubleSided === true ? 1 : 0);
         /* The albedo's effects table, or the stand-in the shader reads as none. Before the early
            return, so a material with no albedo still leaves a complete texture on the unit. */
@@ -2508,6 +2558,9 @@ export class WebGL2Renderer {
         }
         else {
             albedo.bindEffects(gl, SURFACE_EFFECTS_TEXTURE_UNIT, this.emptyTexture2D);
+            /* The first table bound is when the lit programs start reading one. See `litOn`. */
+            if (albedo.hasEffects)
+                this.askLit('SURFACE_EFFECTS');
         }
         gl.uniform1i(u['uSurfaceEffects'] ?? null, SURFACE_EFFECTS_TEXTURE_UNIT);
         if (albedo === null) {
@@ -2624,6 +2677,28 @@ export class WebGL2Renderer {
         this.materials.dirty();
         this.writeFlatFloat('uGrain', Math.min(1, Math.max(0, amount)));
     }
+    /**
+     * Whether the surfaces drawn next meet the medium: distance fog and the global medium's haze.
+     * True is the default, and what `bindMeshPass` restores.
+     *
+     * **The opaque counterpart of `TranslucentMeshOptions.fog`**, which a translucent draw has had
+     * all along; the shader's per-draw switch was there, and nothing reached it for an ordinary mesh.
+     * What it is for is a medium that darkens one thing and not another — a floor receding into the
+     * distance under figures that must keep their full value however far from the camera they stand.
+     * Material state like `setSurfaceGrain`: instanced and skinned draws read it too, and a
+     * translucent draw's own `fog` is measured against it and puts it back.
+     *
+     * **What it gives up** is the medium's honesty: a surface out of the fog is drawn as though the
+     * air between it and the eye were empty, so it should be a surface the scene means to stand
+     * apart, not one whose distance is the point.
+     */
+    setSurfaceFog(enabled) {
+        if (this.contextLost)
+            return;
+        this.materials.dirty();
+        this.surfaceFog = enabled ? FOG_RECEDE : FOG_OFF;
+        this.writeFlatInt('uFogEnabled', this.surfaceFog);
+    }
     /**
      * One float of material state, into every flat program.
      *
@@ -2640,6 +2715,14 @@ export class WebGL2Renderer {
         }
         this.useFlatProgram();
     }
+    /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
+    writeFlatInt(name, value) {
+        for (const target of this.flatTargets) {
+            this.gl.useProgram(target.program);
+            this.gl.uniform1i(target.uniforms[name] ?? null, value);
+        }
+        this.useFlatProgram();
+    }
     /**
      * How much of the surfaces drawn next survives a screen-door dither, for crossfading two levels
      * of detail of one thing.
@@ -2868,7 +2951,7 @@ export class WebGL2Renderer {
         /* A blended batch shows what is behind it — refraction or glass — as a single draw does, and
            counts a material of its own for it by the rule both backends share (`materialChanges.ts`). */
         const refracting = blend && this.bindSeeThrough(u, options);
-        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting });
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
         if (own)
             this.materials.dirty();
         this.takeMaterial();
@@ -2894,16 +2977,16 @@ export class WebGL2Renderer {
          */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (fog !== FOG_RECEDE)
+        if (fog !== this.surfaceFog)
             gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, Math.min(this.gradeCode(), 1));
         if (blend) {
             gl.enable(gl.BLEND);
             if (options.additive === true)
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+                blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
             else
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+                blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
             if (!depthWrite)
                 gl.depthMask(false);
         }
@@ -2943,8 +3026,8 @@ export class WebGL2Renderer {
             this.unbindSeeThrough(u);
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (fog !== FOG_RECEDE)
-            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        if (fog !== this.surfaceFog)
+            gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)
@@ -4023,6 +4106,7 @@ export class WebGL2Renderer {
         gl.uniform4fv(u['uGlassLight'] ?? null, this.glassLight);
         if (cutout !== null) {
             gl.uniform2f(u['uUvScale'] ?? null, cutout.u, cutout.v);
+            gl.uniform2f(u['uUvOffset'] ?? null, cutout.uOffset, cutout.vOffset);
             gl.uniform1f(u['uAlphaCutout'] ?? null, cutout.cutoff);
             cutout.albedo.bind(gl, SURFACE_TEXTURE_UNIT);
             gl.uniform1i(u['uCutoutMap'] ?? null, SURFACE_TEXTURE_UNIT);
@@ -4132,16 +4216,76 @@ export class WebGL2Renderer {
      * rather than propagating. Only a shader that will not link at *any* budget throws, and it
      * throws a sentence with the device's numbers in it rather than a bare driver string.
      */
-    fitFlatProgram(gl) {
-        const variant = {
+    /** The lit fragment source this renderer's profile compiles, at a light budget. */
+    flatFragAt(budget) {
+        return flatFrag({
             pointShadows: this.quality.pointShadows,
             directionalShadows: this.quality.directionalShadows,
             environmentProbe: this.probeCapture !== null,
             nightEmissive: this.quality.nightEmissive,
-            /* Off compiles none of the glass lookup: see `FlatShaderOptions.glassShadows`. */
-            glassShadows: this.quality.glassShadows !== 'off',
+            /* Each off until it is used: see `litOn`. */
+            glassShadows: this.litOn.GLASS_SHADOWS,
+            clusteredLights: this.litOn.CLUSTERED_LIGHTS,
+            lightFixtures: this.litOn.LIGHT_FIXTURES,
+            surfaceEffects: this.litOn.SURFACE_EFFECTS,
+            driftLight: this.litOn.DRIFT_LIGHT,
+            maxLights: budget.maxLights,
+            maxAreaLights: budget.maxAreaLights,
+        });
+    }
+    /**
+     * Every lit program that exists, compiled again with the switches asked for since, at the budget
+     * the renderer already uploads for, and given the pass and the material the old one held.
+     *
+     * At `beginFrame`, not where a feature was first used: a pane is offered inside a shadow pass
+     * with the depth program bound, and a program swapped under it would draw the next caster with
+     * the lit one.
+     */
+    rebuildLit() {
+        const { gl } = this;
+        Object.assign(this.litOn, this.litWanted);
+        this.flatFragSource = this.flatFragAt(this.lightBudget);
+        const recompile = (old, skinned, morphed, instanced, label) => {
+            if (old === null)
+                return null;
+            const program = compileProgram(gl, flatVert({ skinned, morphed, instanced }), this.flatFragSource, label);
+            gl.deleteProgram(old);
+            return { program, uniforms: uniformLocations(gl, program, label) };
         };
-        const build = (budget) => flatFrag({ ...variant, maxLights: budget.maxLights, maxAreaLights: budget.maxAreaLights });
+        const plain = recompile(this.flatProgram, false, false, false, 'flat');
+        if (plain !== null) {
+            this.flatProgram = plain.program;
+            this.flatUniforms = plain.uniforms;
+        }
+        const skinned = recompile(this.flatSkinnedProgram, true, false, false, 'flat.skinned');
+        this.flatSkinnedProgram = skinned?.program ?? null;
+        this.flatSkinnedUniforms = skinned?.uniforms ?? null;
+        const morphed = recompile(this.flatMorphedProgram, false, true, false, 'flat.morphed');
+        this.flatMorphedProgram = morphed?.program ?? null;
+        this.flatMorphedUniforms = morphed?.uniforms ?? null;
+        const both = recompile(this.flatBothProgram, true, true, false, 'flat.morphedskinned');
+        this.flatBothProgram = both?.program ?? null;
+        this.flatBothUniforms = both?.uniforms ?? null;
+        const instanced = recompile(this.flatInstancedProgram, false, false, true, 'flat.instanced');
+        this.flatInstancedProgram = instanced?.program ?? null;
+        this.flatInstancedUniforms = instanced?.uniforms ?? null;
+        this.flatTargets.length = 0;
+        for (const target of [plain, skinned, morphed, both, instanced]) {
+            if (target !== null)
+                this.flatTargets.push(target);
+        }
+        const camera = this.lastPassCamera;
+        const env = this.lastPassEnv;
+        for (const target of this.flatTargets) {
+            gl.useProgram(target.program);
+            if (camera !== null && env !== null)
+                this.writeMeshPassState(target.uniforms, camera, env);
+            this.writeMaterialState(target.uniforms, this.currentMaterial);
+        }
+        this.useFlatProgram();
+    }
+    fitFlatProgram(gl) {
+        const build = (budget) => this.flatFragAt(budget);
         const vert = flatVert({ skinned: false, morphed: false, instanced: false });
         const limit = gl.getParameter(gl.MAX_FRAGMENT_UNIFORM_VECTORS);
         const ceiling = {
@@ -4652,7 +4796,7 @@ export class WebGL2Renderer {
          */
         gl.disable(gl.CULL_FACE);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.uniform4f(this.panelUniforms['uRect'] ?? null, rect.left, rect.top, rect.width, rect.height);
         gl.uniform2f(this.panelUniforms['uViewport'] ?? null, Math.max(this.canvas.clientWidth, 1), Math.max(this.canvas.clientHeight, 1));
         /* Identity: this backend's clip space is the one the shader was written against. */
@@ -4673,6 +4817,34 @@ export class WebGL2Renderer {
         gl.disable(gl.SCISSOR_TEST);
         this.restoreViewport();
     }
+    /**
+     * Draw what follows as a **view model**, in the nearest sliver of depth, until `endViewModel`.
+     *
+     * A first-person view model — arms and a held weapon — drawn with the frame's camera, or with one
+     * of its own through `bindMeshPass`, lands in front of anything past the near plane without the
+     * world's depth being cleared, so every pass that reads depth afterwards still sees the world.
+     * `share` is how much of the range it takes, 1% by default. See `viewModel.ts` for what it gives
+     * up, which includes temporal reconstruction: draw a view model with multisampling.
+     *
+     * Not inside an inset: an inset has its own depth, cleared for it, and needs no squeeze.
+     */
+    beginViewModel(share = VIEW_MODEL_DEPTH_SHARE) {
+        if (this.contextLost)
+            return;
+        viewModelDepthRange(this.reversedDepth, share, this.viewModelRange);
+        this.gl.depthRange(this.viewModelRange[0], this.viewModelRange[1]);
+        this.viewModelActive = true;
+    }
+    /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+    endViewModel() {
+        this.viewModelActive = false;
+        if (this.contextLost)
+            return;
+        this.gl.depthRange(0, 1);
+    }
+    /** Whether a view model is being drawn, so `endFrame` can close one the caller left open. */
+    viewModelActive = false;
+    viewModelRange = [0, 1];
     /**
      * How much speed blur the frame about to be drawn should resolve with, 0 to 1.
      *
@@ -5162,6 +5334,10 @@ export class WebGL2Renderer {
     beginFrame(clearColor) {
         if (this.contextLost)
             return;
+        if (this.litAsked) {
+            this.litAsked = false;
+            this.rebuildLit();
+        }
         this.budget.reset();
         this.materials.dirty();
         /*
@@ -5235,6 +5411,9 @@ export class WebGL2Renderer {
     endFrame() {
         if (this.contextLost)
             return;
+        /* A view model left open would squeeze every pass after the world, the composite included. */
+        if (this.viewModelActive)
+            this.endViewModel();
         /*
          * Camera motion blur, built from the camera the frame was *rendered* with.
          *
@@ -5797,6 +5976,8 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_3D, null);
         this.driftIndex = index;
         this.driftAtlas = atlas;
+        /* The first volume is when the lit programs start reading one. See `litOn`. */
+        this.askLit('DRIFT_LIGHT');
     }
     /** The field's uniforms and volumes for this pass, or the stand-ins that switch it off. */
     bindDriftLight(u, eye) {
@@ -5906,7 +6087,8 @@ export class WebGL2Renderer {
          * shape `uOpacity` and `uTint` already use.
          */
         gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        gl.uniform1i(u['uFogEnabled'] ?? null, 1);
+        gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        this.surfaceFog = FOG_RECEDE;
         /* Grain on by default, so every scene written before it was a choice looks unchanged. */
         gl.uniform1f(u['uGrain'] ?? null, 1);
         /* No dither and no weighting: every draw whole, until a crossfade asks. See `setDitherFade`. */
@@ -6091,9 +6273,12 @@ export class WebGL2Renderer {
         gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
         gl.uniform1i(u['uSurfaceEffects'] ?? null, SURFACE_EFFECTS_TEXTURE_UNIT);
         gl.uniform2f(u['uUvScale'] ?? null, 1, 1);
+        gl.uniform2f(u['uUvOffset'] ?? null, 0, 0);
         gl.uniform1f(u['uAlbedoCutout'] ?? null, 0);
         gl.uniform1i(u['uDoubleSided'] ?? null, 0);
         this.materialDoubleSided = false;
+        this.materialHasMaps = false;
+        this.currentMaterial = null;
         this.currentSurfaceTexture = null;
         /*
          * **And the normal map, which this did not reset and had to.**
@@ -6213,6 +6398,7 @@ export class WebGL2Renderer {
            and `Mesh.indexCount`. */
         if (!mesh.complete || mesh.indexCount === 0)
             return;
+        noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
         /*
          * Skipped where the flag asks and the bounds say so.
          *
@@ -6405,6 +6591,7 @@ export class WebGL2Renderer {
            and `Mesh.indexCount`. */
         if (!mesh.complete || mesh.indexCount === 0)
             return;
+        noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
         if (opacity <= 0)
             return;
         /*
@@ -6435,7 +6622,7 @@ export class WebGL2Renderer {
         const toneMapped = options.toneMapped ?? true;
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 0);
-        if (fog !== FOG_RECEDE)
+        if (fog !== this.surfaceFog)
             gl.uniform1i(u['uFogEnabled'] ?? null, fog);
         /* `1` is sRGB alone: the conversion without the curve, which is what dropping the tone map
            means rather than dropping the whole transform. `Math.min` rather than a literal, so a
@@ -6470,7 +6657,7 @@ export class WebGL2Renderer {
          */
         /* 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 });
+        const own = ownsMaterial({ opacity, lit, fog, toneMapped, refracting }, this.surfaceFog);
         if (own)
             this.materials.dirty();
         this.takeMaterial();
@@ -6479,9 +6666,9 @@ export class WebGL2Renderer {
             gl.enable(gl.BLEND);
             /* Added, where asked: colour times alpha onto what is there, and the target's alpha kept. */
             if (options.additive === true)
-                gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE, gl.ZERO, gl.ONE);
+                blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
             else
-                gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+                blendCovering(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         }
         /*
          * The two depth options, both scoped to this draw and handed straight back — the same
@@ -6521,8 +6708,8 @@ export class WebGL2Renderer {
            cannot inherit a material from the draw before it. */
         if (!lit)
             gl.uniform1i(u['uLightingEnabled'] ?? null, 1);
-        if (fog !== FOG_RECEDE)
-            gl.uniform1i(u['uFogEnabled'] ?? null, FOG_RECEDE);
+        if (fog !== this.surfaceFog)
+            gl.uniform1i(u['uFogEnabled'] ?? null, this.surfaceFog);
         if (!toneMapped)
             gl.uniform1i(u['uOutputTransform'] ?? null, this.gradeCode());
         if (own)
@@ -6890,7 +7077,7 @@ export class WebGL2Renderer {
             gl.uniform1i(u['uSceneDepth'] ?? null, 3);
         }
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE);
         gl.depthMask(false);
         gl.cullFace(inside ? gl.FRONT : gl.BACK);
         mesh.draw(gl);
@@ -6958,7 +7145,7 @@ export class WebGL2Renderer {
         }
         bindAtmosphere(gl, u, env, this.reflectionPassActive ? this.reflectionAtmosphereY : (camera.position[1] ?? 0), this.quality.underwaterAtmosphere);
         gl.enable(gl.BLEND);
-        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        blendKeeping(gl, gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         gl.depthMask(false);
         mesh.draw(gl);
         gl.depthMask(true);

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

@@ -114,6 +114,8 @@ export interface GpuMesh {
      * the key is built before the present map is consulted.
      */
     readonly isSkinned: boolean;
+    /** Whether it has texture coordinates, without which a material's maps read one texel. */
+    readonly hasUvs: boolean;
     /**
      * Whether this mesh carries the per-vertex channel, which an instanced draw cannot.
      *

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

@@ -257,6 +257,7 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
         progress,
         hasTangents: data.tangents !== undefined,
         isSkinned: data.joints !== undefined,
+        hasUvs: data.uvs !== undefined,
         skinOffsets: skinOffsetsOf(supplied),
         hasChannel: data.channel !== undefined,
         morph: data.morphTargets === undefined || data.morphTargetCount === undefined
@@ -392,6 +393,7 @@ function gpuMeshOf(parts) {
         },
         hasTangents: parts.hasTangents,
         isSkinned: parts.isSkinned,
+        hasUvs: parts.hasUvs,
         hasChannel: parts.hasChannel,
         morph: parts.morph,
         update: parts.update,

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

@@ -2,6 +2,7 @@ import { DEPTH_COMPARE } from '../../depthConvention.js';
 import { CAUSTICS_BINDINGS, CAUSTICS_FRAG_WGSL, CAUSTICS_VERT_WGSL, } from '../../shaders/generated/caustics.wgsl.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
+import { SCENE_ALPHA_KEEPS } from '../../sceneCoverage.js';
 /**
  * The caustics pass: a surface lit by nearby water.
  *
@@ -126,7 +127,7 @@ export function causticsPipeline(cache, device, layout) {
                     format: cache.format,
                     blend: {
                         color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
-                        alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                        alpha: SCENE_ALPHA_KEEPS,
                     },
                 },
             ],