@driftengine/core 4.8.1 → 4.8.3

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

@@ -5,8 +5,9 @@ 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';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS: ReadonlySet<string> = new Set([
@@ -199,17 +200,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 +518,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 +563,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,
   );
 }
 
@@ -665,7 +682,7 @@ function flatDescriptor(
                       dstFactor: 'one-minus-src-alpha',
                       operation: 'add',
                     },
-                    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    alpha: SCENE_ALPHA_COVERS,
                   },
                 }
               : { format: cache.format }),

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

@@ -9,6 +9,7 @@ import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The line pass: a polyline with a real width, four vertices a segment.
@@ -222,7 +223,7 @@ export function linePipeline(
                   dstFactor: 'one-minus-src-alpha',
                   operation: 'add',
                 },
-                alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                alpha: SCENE_ALPHA_COVERS,
               },
         },
       ],

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

@@ -7,6 +7,7 @@ import type { UniformFields } from './scatterPass.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The panel pass: two triangles in screen space, one colour, one alpha.
@@ -121,7 +122,7 @@ export function panelPipeline(
           format: cache.format,
           blend: {
             color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: SCENE_ALPHA_COVERS,
           },
         },
       ],

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

@@ -8,6 +8,7 @@ import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { UniformFields } from './scatterPass.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The particle pass: a crossed pair of quads per live particle, rebuilt every frame.
@@ -367,7 +368,7 @@ export function particlePipeline(
                     dstFactor: 'one-minus-src-alpha',
                     operation: 'add',
                   },
-                  alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                  alpha: SCENE_ALPHA_COVERS,
                 },
         },
       ],

package/src/render/backend/webgpu/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.
    *

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

@@ -9,6 +9,7 @@ import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { UniformFields } from './scatterPass.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
 
 /**
  * The plume pass: crossed quads per plume, displaced and faded in the shaders.
@@ -251,7 +252,7 @@ function blendState(blend: 'additive' | 'alpha'): GPUBlendState {
       }
     : {
         color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
-        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+        alpha: SCENE_ALPHA_COVERS,
       };
 }
 

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

@@ -39,6 +39,7 @@ import {
 import type { UniformFields } from './scatterPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
+import { SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS } from '../../sceneCoverage.ts';
 
 /**
  * The composite: everything that happens to the frame after the world is drawn.
@@ -271,7 +272,7 @@ export function createPostStageLayout(
  */
 export const OIT_COMPOSITE_BLEND: GPUBlendState = {
   color: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
-  alpha: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
+  alpha: SCENE_ALPHA_TRANSMITS,
 };
 
 /**
@@ -290,17 +291,19 @@ export const OIT_COMPOSITE_BLEND: GPUBlendState = {
  * exactly the integral — and the composite therefore never samples the colour it is modifying,
  * which is the read both backends are entitled to call undefined.
  *
- * Alpha is `(zero, one)`: the frame's own alpha is not the medium's to spend. The scene target
- * carries it to the canvas, and a medium that wrote there would make a foggy frame translucent.
+ * Alpha is the transmittance again, `share * a`: the scene's alpha is how much of the pixel is
+ * still the opaque surface, which is what the composite lets ambient occlusion darken, and a
+ * medium thick enough to hide a corner hides its occlusion too (`sceneCoverage.ts`). It reaches
+ * no canvas: both are opaque, and the composite writes 1.
  */
 export const MEDIUM_TRANSMIT_BLEND: GPUBlendState = {
   color: { srcFactor: 'one', dstFactor: 'src-alpha', operation: 'add' },
-  alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+  alpha: SCENE_ALPHA_TRANSMITS,
 };
 
 export const DECAL_MULTIPLY_BLEND: GPUBlendState = {
   color: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
-  alpha: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
+  alpha: SCENE_ALPHA_KEEPS,
 };
 
 /**
@@ -316,6 +319,18 @@ export const PREMULTIPLIED_OVER_BLEND: GPUBlendState = {
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
 };
 
+/**
+ * The same `over` for the resolve that lands a reflection on the scene, keeping the scene's alpha.
+ *
+ * A reflection is a layer of the surface it is seen in, so the surface's share of the pixel is
+ * unchanged (`sceneCoverage.ts`). The trace keeps `PREMULTIPLIED_OVER_BLEND`, because its target is
+ * the reflection's own and its alpha is the coverage this resolve reads.
+ */
+export const REFLECTION_OVER_BLEND: GPUBlendState = {
+  color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+  alpha: SCENE_ALPHA_KEEPS,
+};
+
 export const ADDITIVE_BLEND: GPUBlendState = {
   color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
   alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },