@driftengine/core 4.8.1 → 4.8.2

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

@@ -257,6 +257,9 @@ import type { InstancedOptions, MeshInstances } from '../../instances.ts';
 import { cutoutOf } from '../../cutoutCaster.ts';
 import type { CutoutCaster } from '../../cutoutCaster.ts';
 import type { SurfaceTextureHandle } from '../api.ts';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.ts';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.ts';
+import { noLitSwitches, type LitSwitch } from '../../shaders/flat/glassTint.ts';
 
 /**
  * How many frames `firstFrameSettled` will ask before it stops asking.
@@ -1087,8 +1090,8 @@ export class WebGL2Renderer implements RendererApi {
 
   private presentedFrameCount = 0;
 
-  private readonly flatProgram: WebGLProgram;
-  private readonly flatUniforms: Record<string, WebGLUniformLocation>;
+  private flatProgram: WebGLProgram;
+  private flatUniforms: Record<string, WebGLUniformLocation>;
   /**
    * The lit fragment source every flat program is built from, and the budget it was built at.
    *
@@ -1099,7 +1102,7 @@ export 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: string;
+  private flatFragSource: string;
   /**
    * How many lights this renderer's shader has room for, after the device had its say.
    *
@@ -1683,6 +1686,33 @@ export class WebGL2Renderer implements RendererApi {
    * each such draw and handed back, where the other backend bakes it into a pipeline.
    */
   private materialDoubleSided = false;
+  /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+  private materialHasMaps = false;
+  /** The material last set, so a lit program rebuilt for glass can be given it. */
+  private currentMaterial: SurfaceMaterial | null = 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.
+   */
+  private readonly litOn = noLitSwitches();
+  private readonly litWanted = noLitSwitches();
+  private litAsked = false;
+
+  /** Ask for a switch, which the next `beginFrame` compiles in. Never glass with it turned off. */
+  private askLit(feature: LitSwitch): void {
+    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.
@@ -1715,6 +1745,7 @@ export class WebGL2Renderer implements RendererApi {
         /* Glass: kept aside for its own two passes rather than dropped. See `glassCasters.ts`. */
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordMesh(mesh, model, material, this.glassCasterScratch);
+          this.askLit('GLASS_SHADOWS');
         }
         return;
       }
@@ -1756,6 +1787,7 @@ export class WebGL2Renderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordInstanced(batch, data, material, this.glassCasterScratch);
+          this.askLit('GLASS_SHADOWS');
         }
         return;
       }
@@ -1789,6 +1821,7 @@ export class WebGL2Renderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordSkinned(mesh, model, palette, material, this.glassCasterScratch);
+          this.askLit('GLASS_SHADOWS');
         }
         return;
       }
@@ -2297,6 +2330,8 @@ export class WebGL2Renderer implements RendererApi {
     this.iesRows = this.iesAtlas.height;
     this.iesPlanes = this.iesAtlas.planes;
     this.cookieTiles = this.cookieImages.length;
+    /* The first profile or cookie is when the lit 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);
   }
@@ -2714,6 +2749,9 @@ export class WebGL2Renderer implements RendererApi {
      * 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;
@@ -3306,6 +3344,8 @@ export class WebGL2Renderer implements RendererApi {
     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
@@ -3422,6 +3462,8 @@ export class WebGL2Renderer implements RendererApi {
       gl.bindTexture(gl.TEXTURE_2D, this.emptyTexture2D);
     } 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) {
@@ -5317,21 +5359,91 @@ export 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.
    */
-  private fitFlatProgram(gl: WebGL2RenderingContext): {
-    program: WebGLProgram;
-    source: string;
-    budget: LightBudget;
-  } {
-    const variant = {
+  /** The lit fragment source this renderer's profile compiles, at a light budget. */
+  private flatFragAt(budget: LightBudget): string {
+    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.
+   */
+  private rebuildLit(): void {
+    const { gl } = this;
+    Object.assign(this.litOn, this.litWanted);
+    this.flatFragSource = this.flatFragAt(this.lightBudget);
+    const recompile = (
+      old: WebGLProgram | null,
+      skinned: boolean,
+      morphed: boolean,
+      instanced: boolean,
+      label: string,
+    ): { program: WebGLProgram; uniforms: Record<string, WebGLUniformLocation> } | null => {
+      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: LightBudget): string =>
-      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();
+  }
+
+  private fitFlatProgram(gl: WebGL2RenderingContext): {
+    program: WebGLProgram;
+    source: string;
+    budget: LightBudget;
+  } {
+    const build = (budget: LightBudget): string => this.flatFragAt(budget);
     const vert = flatVert({ skinned: false, morphed: false, instanced: false });
     const limit = gl.getParameter(gl.MAX_FRAGMENT_UNIFORM_VECTORS) as number;
     const ceiling: LightBudget = {
@@ -5989,6 +6101,35 @@ export class WebGL2Renderer implements RendererApi {
     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): void {
+    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(): void {
+    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. */
+  private viewModelActive = false;
+  private readonly viewModelRange: [number, number] = [0, 1];
+
   /**
    * How much speed blur the frame about to be drawn should resolve with, 0 to 1.
    *
@@ -6508,6 +6649,10 @@ export class WebGL2Renderer implements RendererApi {
 
   beginFrame(clearColor: Vec3): void {
     if (this.contextLost) return;
+    if (this.litAsked) {
+      this.litAsked = false;
+      this.rebuildLit();
+    }
     this.budget.reset();
     this.materials.dirty();
     /*
@@ -6584,6 +6729,8 @@ export class WebGL2Renderer implements RendererApi {
    */
   endFrame(): void {
     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.
@@ -7240,6 +7387,8 @@ export class WebGL2Renderer implements RendererApi {
     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. */
@@ -7563,6 +7712,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform1f(u['uAlbedoCutout'] ?? null, 0);
     gl.uniform1i(u['uDoubleSided'] ?? null, 0);
     this.materialDoubleSided = false;
+    this.materialHasMaps = false;
+    this.currentMaterial = null;
     this.currentSurfaceTexture = null;
 
     /*
@@ -7689,6 +7840,7 @@ export class WebGL2Renderer implements RendererApi {
     /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
        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.
@@ -7877,6 +8029,7 @@ export class WebGL2Renderer implements RendererApi {
     /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
        and `Mesh.indexCount`. */
     if (!mesh.complete || mesh.indexCount === 0) return;
+    noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
 
     if (opacity <= 0) return;
 

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

@@ -200,6 +200,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.
    *
@@ -425,6 +427,7 @@ export function createGpuMeshIncremental(
     progress,
     hasTangents: data.tangents !== undefined,
     isSkinned: data.joints !== undefined,
+    hasUvs: data.uvs !== undefined,
     skinOffsets: skinOffsetsOf(supplied),
     hasChannel: data.channel !== undefined,
     morph:
@@ -595,6 +598,7 @@ function gpuMeshOf(parts: {
   readonly progress: { readonly uploaded: boolean };
   readonly hasTangents: boolean;
   readonly isSkinned: boolean;
+  readonly hasUvs: boolean;
   readonly skinOffsets: GpuMesh['skinOffsets'];
   readonly hasChannel: boolean;
   readonly morph: MorphTexture | null;
@@ -614,6 +618,7 @@ function gpuMeshOf(parts: {
     },
     hasTangents: parts.hasTangents,
     isSkinned: parts.isSkinned,
+    hasUvs: parts.hasUvs,
     hasChannel: parts.hasChannel,
     morph: parts.morph,
     update: parts.update,

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

@@ -5,7 +5,7 @@ import {
   FLAT_VERT_WGSL,
 } from '../../shaders/generated/flat.wgsl.ts';
 import { vertexBufferLayouts } from './buffers.ts';
-import type { PipelineCache } from './pipelineCache.ts';
+import type { LitSwitch, PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
 
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
@@ -199,17 +199,27 @@ export function flatFragmentBindings(variant: FlatVariant): StageBindings {
 }
 
 /**
- * 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: FlatVariant, cache: PipelineCache): Record<string, number> {
-  const id = flatFragmentBindings(variant).overrides?.['GLASS_SHADOWS'];
-  if (id === undefined) throw new Error(`flatPass: variant "${variant}" has no glass switch`);
-  return { [String(id)]: cache.glassShadows ? 1 : 0 };
+  const overrides = flatFragmentBindings(variant).overrides;
+  if (overrides?.['GLASS_SHADOWS'] === undefined) {
+    throw new Error(`flatPass: variant "${variant}" has no glass switch`);
+  }
+  const constants: Record<string, number> = {};
+  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 as LitSwitch] ? 1 : 0;
+  }
+  return constants;
 }
 
 /** The depth format both backends compare with. */
@@ -507,23 +517,26 @@ export function flatPipeline(
   /** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
   doubleSided = false,
 ): GPURenderPipeline {
-  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,
   );
 }
 
@@ -549,8 +562,11 @@ export function flatPipelineAsync(
   /** Whether this pipeline reads morph deltas. See `FlatVertexOptions`. */
   morphed = false,
 ): Promise<GPURenderPipeline> {
-  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,
   );
 }
 

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

@@ -1,3 +1,7 @@
+import { noLitSwitches, type LitSwitch } from '../../shaders/flat/glassTint.ts';
+
+export type { LitSwitch };
+
 /**
  * Render pipelines, built once and looked up by name.
  *
@@ -35,15 +39,30 @@ export 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> = noLitSwitches();
+
+  /** 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 = new Map<string, () => GPURenderPipelineDescriptor>();
+  /** Bumped by every switch, so a lit build started before one is not kept after it. */
+  private litGeneration = 0;
+  /** The last rebuild, which the next one waits for so they land in the order they were asked. */
+  private litRebuild: Promise<void> = Promise.resolve();
+
   private readonly device: GPUDevice;
   private readonly pipelines = new Map<string, GPURenderPipeline>();
   /**
@@ -62,11 +81,19 @@ export class PipelineCache {
    */
   private readonly compiling = new Map<string, Promise<GPURenderPipeline>>();
 
-  constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount = 1, glassShadows = true) {
+  constructor(
+    device: GPUDevice,
+    format: GPUTextureFormat,
+    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. */
@@ -85,11 +112,15 @@ export class PipelineCache {
   async getAsync(
     key: string,
     describe: () => GPURenderPipelineDescriptor,
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit = false,
   ): Promise<GPURenderPipeline> {
+    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
@@ -103,7 +134,8 @@ 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;
     });
@@ -142,7 +174,13 @@ 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: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline {
+  get(
+    key: string,
+    describe: () => GPURenderPipelineDescriptor,
+    /** Whether this is a lit pipeline, which `enable` rebuilds. See `litSwitches`. */
+    lit = false,
+  ): GPURenderPipeline {
+    if (lit) this.litDescribers.set(key, describe);
     const existing = this.pipelines.get(key);
     if (existing !== undefined) return existing;
     const built = this.device.createRenderPipeline(describe());
@@ -150,6 +188,42 @@ export class PipelineCache {
     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: LitSwitch): Promise<void> {
+    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] as const);
+      });
+      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.
    *