@driftengine/core 4.8.0 → 4.8.2

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

@@ -93,6 +93,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.
  *
@@ -961,6 +964,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 +1023,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 +1069,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 +1108,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;
             }
@@ -1538,6 +1572,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 +1933,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 +2450,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
@@ -2508,6 +2550,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) {
@@ -4132,16 +4177,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 = {
@@ -4673,6 +4778,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 +5295,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 +5372,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 +5937,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) {
@@ -6094,6 +6236,8 @@ export class WebGL2Renderer {
         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 +6357,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 +6550,7 @@ export class WebGL2Renderer {
            and `Mesh.indexCount`. */
         if (!mesh.complete || mesh.indexCount === 0)
             return;
+        noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
         if (opacity <= 0)
             return;
         /*

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/flatPass.js

@@ -115,18 +115,27 @@ export function flatFragmentBindings(variant) {
     return found;
 }
 /**
- * The lit fragment stage's constants, set from the cache: the glass switch, keyed by its **id**.
+ * The lit fragment stage's constants, set from the cache's switches, keyed by each one's **id**.
  *
  * Not by its name, because an override declared with `@id` answers to the id alone — WebGPU's
  * "pipeline-overridable constant identifier string" — and naga writes one on every specialisation
  * constant. Keyed by name, Chrome refused every lit pipeline: *Pipeline overridable constant
- * "GLASS_SHADOWS" not found*, and the frame drew nothing.
+ * "GLASS_SHADOWS" not found*, and the frame drew nothing. Every override the variant declares is
+ * set, so a switch added to the shader and not to the cache is refused here rather than defaulted.
  */
 function flatFragmentConstants(variant, cache) {
-    const id = flatFragmentBindings(variant).overrides?.['GLASS_SHADOWS'];
-    if (id === undefined)
+    const overrides = flatFragmentBindings(variant).overrides;
+    if (overrides?.['GLASS_SHADOWS'] === undefined) {
         throw new Error(`flatPass: variant "${variant}" has no glass switch`);
-    return { [String(id)]: cache.glassShadows ? 1 : 0 };
+    }
+    const constants = {};
+    for (const [name, id] of Object.entries(overrides)) {
+        if (!(name in cache.litSwitches)) {
+            throw new Error(`flatPass: variant "${variant}" declares a switch "${name}" no cache sets`);
+        }
+        constants[String(id)] = cache.litSwitches[name] ? 1 : 0;
+    }
+    return constants;
 }
 /** The depth format both backends compare with. */
 /* Re-exported so the twenty passes that already import it from here do not each learn a new
@@ -391,7 +400,7 @@ instanced = false,
 oit = 'none', 
 /** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
 doubleSided = false) {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided));
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided), true);
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -407,7 +416,7 @@ export function flatPipelineAsync(cache, device, layout, variant, key, present,
 skinned = false, 
 /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
 morphed = false) {
-    return cache.getAsync(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed));
+    return cache.getAsync(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed), true);
 }
 /**
  * The colour target for an order-independent pass, or null where this is an ordinary draw.

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

@@ -1,3 +1,5 @@
+import { type LitSwitch } from '../../shaders/flat/glassTint.ts';
+export type { LitSwitch };
 /**
  * Render pipelines, built once and looked up by name.
  *
@@ -33,14 +35,27 @@ export declare class PipelineCache {
      */
     readonly sampleCount: number;
     /**
-     * Whether the lit pipelines here read glass in their shadows: `glassShadows` other than `'off'`.
+     * Which of the lit stage's switches the pipelines built now have on: the pipeline-overridable
+     * constants the generated lit shader branches on (`GLASS_SHADOWS` and `litSwitchesGlsl`), which
+     * the device compiles away where they are off. Read by `flatPass` when it describes a pipeline.
      *
-     * **Carried by the cache for the reason the format is**: one value every lit pipeline is built
-     * with, chosen once by the renderer. It is the `GLASS_SHADOWS` override the generated lit shader
-     * branches on (see `FlatShaderOptions.glassShadows`), so off specialises the lookups away rather
-     * than leaving code that returns at its first line and still costs the pass its registers.
+     * **Each is code a scene pays for in every lit pixel's registers whether it uses it or not**, so
+     * each is off until it is used: glass until the renderer is offered a pane, 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, through `enable`. Clustering is the profile's, fixed at construction. Every
+     * scene paid for all of it from 4.5.0 to 4.8.1, and on a phone that was the lit pass: about 30%
+     * of the lit shader's instructions for glass alone, measured on RADV. **What it costs** is the
+     * frames between a feature's first use and its recompiled pipelines, which draw without it.
      */
+    readonly litSwitches: Record<LitSwitch, boolean>;
+    /** Whether glass may ever be switched on here: `glassShadows` other than `'off'`. */
     readonly glassShadows: boolean;
+    /** How to describe each lit pipeline again, so `enable` can rebuild every one. */
+    private readonly litDescribers;
+    /** Bumped by every switch, so a lit build started before one is not kept after it. */
+    private litGeneration;
+    /** The last rebuild, which the next one waits for so they land in the order they were asked. */
+    private litRebuild;
     private readonly device;
     private readonly pipelines;
     /**
@@ -58,7 +73,9 @@ export declare class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     private readonly compiling;
-    constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number, glassShadows?: boolean);
+    constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount?: number, glassShadows?: boolean, 
+    /** The profile's `clusteredLights`, which compiles the clustered arm in or leaves it out. */
+    clusteredLights?: boolean);
     /** How many distinct pipelines have been built. Read by tests and diagnostics. */
     get size(): number;
     /**
@@ -69,7 +86,9 @@ export declare class PipelineCache {
      * difference is only *when* the driver does the work, and that difference is the whole bug
      * this exists for.
      */
-    getAsync(key: string, describe: () => GPURenderPipelineDescriptor): Promise<GPURenderPipeline>;
+    getAsync(key: string, describe: () => GPURenderPipelineDescriptor, 
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit?: boolean): Promise<GPURenderPipeline>;
     /**
      * Resolve once every pipeline asked for so far has finished compiling.
      *
@@ -90,7 +109,20 @@ export declare class PipelineCache {
      * too**: a nested object with vertex buffer layouts and blend state, constructed to be
      * thrown away on every hit. Passing a function means a hit costs one `Map` lookup.
      */
-    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+    get(key: string, describe: () => GPURenderPipelineDescriptor, 
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit?: boolean): GPURenderPipeline;
+    /**
+     * Turn one of the lit stage's switches on, for every lit pipeline built from now on and every one
+     * already built. See `litSwitches`.
+     *
+     * **The rebuilt set lands at once**, when every one of them has compiled, so no frame draws some
+     * surfaces with a feature and others without. Until then the pipelines already built go on drawing
+     * as they were. Once only: a switch is not turned off again when the last user of it leaves,
+     * because a second switch would cost a second compile for a saving the first use showed was not
+     * needed. Glass is never turned on where the profile asked for no glass shadows.
+     */
+    enable(feature: LitSwitch): Promise<void>;
     /**
      * Drop every pipeline.
      *

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

@@ -1,3 +1,4 @@
+import { noLitSwitches } from '../../shaders/flat/glassTint.js';
 /**
  * Render pipelines, built once and looked up by name.
  *
@@ -33,14 +34,27 @@ export class PipelineCache {
      */
     sampleCount;
     /**
-     * Whether the lit pipelines here read glass in their shadows: `glassShadows` other than `'off'`.
+     * Which of the lit stage's switches the pipelines built now have on: the pipeline-overridable
+     * constants the generated lit shader branches on (`GLASS_SHADOWS` and `litSwitchesGlsl`), which
+     * the device compiles away where they are off. Read by `flatPass` when it describes a pipeline.
      *
-     * **Carried by the cache for the reason the format is**: one value every lit pipeline is built
-     * with, chosen once by the renderer. It is the `GLASS_SHADOWS` override the generated lit shader
-     * branches on (see `FlatShaderOptions.glassShadows`), so off specialises the lookups away rather
-     * than leaving code that returns at its first line and still costs the pass its registers.
+     * **Each is code a scene pays for in every lit pixel's registers whether it uses it or not**, so
+     * each is off until it is used: glass until the renderer is offered a pane, 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, through `enable`. Clustering is the profile's, fixed at construction. Every
+     * scene paid for all of it from 4.5.0 to 4.8.1, and on a phone that was the lit pass: about 30%
+     * of the lit shader's instructions for glass alone, measured on RADV. **What it costs** is the
+     * frames between a feature's first use and its recompiled pipelines, which draw without it.
      */
+    litSwitches = noLitSwitches();
+    /** Whether glass may ever be switched on here: `glassShadows` other than `'off'`. */
     glassShadows;
+    /** How to describe each lit pipeline again, so `enable` can rebuild every one. */
+    litDescribers = new Map();
+    /** Bumped by every switch, so a lit build started before one is not kept after it. */
+    litGeneration = 0;
+    /** The last rebuild, which the next one waits for so they land in the order they were asked. */
+    litRebuild = Promise.resolve();
     device;
     pipelines = new Map();
     /**
@@ -58,11 +72,14 @@ export class PipelineCache {
      * wait for readiness rather than discovering it mid-frame.
      */
     compiling = new Map();
-    constructor(device, format, sampleCount = 1, glassShadows = true) {
+    constructor(device, format, sampleCount = 1, glassShadows = true, 
+    /** The profile's `clusteredLights`, which compiles the clustered arm in or leaves it out. */
+    clusteredLights = false) {
         this.device = device;
         this.format = format;
         this.sampleCount = sampleCount;
         this.glassShadows = glassShadows;
+        this.litSwitches.CLUSTERED_LIGHTS = clusteredLights;
     }
     /** How many distinct pipelines have been built. Read by tests and diagnostics. */
     get size() {
@@ -76,13 +93,18 @@ export class PipelineCache {
      * difference is only *when* the driver does the work, and that difference is the whole bug
      * this exists for.
      */
-    async getAsync(key, describe) {
+    async getAsync(key, describe, 
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit = false) {
+        if (lit)
+            this.litDescribers.set(key, describe);
         const existing = this.pipelines.get(key);
         if (existing !== undefined)
             return existing;
         const inFlight = this.compiling.get(key);
         if (inFlight !== undefined)
             return inFlight;
+        const generation = this.litGeneration;
         /*
          * **Falls back where the async form is missing.** It is part of the standard, but a device
          * can be a test double, a polyfill or an older implementation, and a renderer that throws
@@ -94,7 +116,9 @@ export class PipelineCache {
             ? this.device.createRenderPipelineAsync(describe())
             : Promise.resolve(this.device.createRenderPipeline(describe()));
         const promise = build.then((built) => {
-            this.pipelines.set(key, built);
+            /* A lit pipeline started before a switch is not kept: the switch rebuilds it. */
+            if (!lit || generation === this.litGeneration)
+                this.pipelines.set(key, built);
             this.compiling.delete(key);
             return built;
         });
@@ -129,7 +153,11 @@ export class PipelineCache {
      * too**: a nested object with vertex buffer layouts and blend state, constructed to be
      * thrown away on every hit. Passing a function means a hit costs one `Map` lookup.
      */
-    get(key, describe) {
+    get(key, describe, 
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit = false) {
+        if (lit)
+            this.litDescribers.set(key, describe);
         const existing = this.pipelines.get(key);
         if (existing !== undefined)
             return existing;
@@ -137,6 +165,45 @@ export class PipelineCache {
         this.pipelines.set(key, built);
         return built;
     }
+    /**
+     * Turn one of the lit stage's switches on, for every lit pipeline built from now on and every one
+     * already built. See `litSwitches`.
+     *
+     * **The rebuilt set lands at once**, when every one of them has compiled, so no frame draws some
+     * surfaces with a feature and others without. Until then the pipelines already built go on drawing
+     * as they were. Once only: a switch is not turned off again when the last user of it leaves,
+     * because a second switch would cost a second compile for a saving the first use showed was not
+     * needed. Glass is never turned on where the profile asked for no glass shadows.
+     */
+    enable(feature) {
+        if (this.litSwitches[feature])
+            return this.litRebuild;
+        if (feature === 'GLASS_SHADOWS' && !this.glassShadows)
+            return this.litRebuild;
+        this.litSwitches[feature] = true;
+        this.litGeneration += 1;
+        const generation = this.litGeneration;
+        this.litRebuild = this.litRebuild.then(async () => {
+            /* A later switch has its own rebuild, which describes every pipeline with this one on too. */
+            if (generation !== this.litGeneration)
+                return;
+            const rebuilt = [...this.litDescribers].map(([key, describe]) => {
+                const descriptor = describe();
+                const build = typeof this.device.createRenderPipelineAsync === 'function'
+                    ? this.device.createRenderPipelineAsync(descriptor)
+                    : Promise.resolve(this.device.createRenderPipeline(descriptor));
+                return build.then((pipeline) => [key, pipeline]);
+            });
+            const results = await Promise.allSettled(rebuilt);
+            if (generation !== this.litGeneration)
+                return;
+            for (const result of results) {
+                if (result.status === 'fulfilled')
+                    this.pipelines.set(result.value[0], result.value[1]);
+            }
+        });
+        return this.litRebuild;
+    }
     /**
      * Drop every pipeline.
      *