@driftengine/core 4.4.1 → 4.5.0

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

@@ -34,6 +34,16 @@ export class PipelineCache {
    */
   readonly sampleCount: number;
 
+  /**
+   * Whether the lit pipelines here read glass in their shadows: `glassShadows` other than `'off'`.
+   *
+   * **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.
+   */
+  readonly glassShadows: boolean;
+
   private readonly device: GPUDevice;
   private readonly pipelines = new Map<string, GPURenderPipeline>();
   /**
@@ -52,10 +62,11 @@ export class PipelineCache {
    */
   private readonly compiling = new Map<string, Promise<GPURenderPipeline>>();
 
-  constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount = 1) {
+  constructor(device: GPUDevice, format: GPUTextureFormat, sampleCount = 1, glassShadows = true) {
     this.device = device;
     this.format = format;
     this.sampleCount = sampleCount;
+    this.glassShadows = glassShadows;
   }
 
   /** How many distinct pipelines have been built. Read by tests and diagnostics. */

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

@@ -0,0 +1,233 @@
+/**
+ * What a lamp's light keeps through glass, on this device: an `rgba8unorm` array of one layer a
+ * light, the face-sized colour scratch a face's glass is multiplied into, and the resolve that
+ * copies a face into its octahedral region. The twin of `pointGlassTint.ts`, which says what the
+ * channels hold and why the chain exists.
+ *
+ * **The chain is a `SnapshotMips` per layer**, made the first time that layer is touched and
+ * recorded once a round for the layers the round touched — a layer's levels are its own
+ * subresources here, so nothing is staged the way the other backend must.
+ */
+import { mat3 } from 'gl-matrix';
+
+import { pointShadowFaceRotation } from '../../pointShadowImage.ts';
+import {
+  OCTAHEDRAL_RESOLVE_TINT_FRAG_WGSL,
+  OCTAHEDRAL_RESOLVE_VERT_WGSL,
+  OCTAHEDRALRESOLVE_BINDINGS,
+} from '../../shaders/generated/octahedralResolve.wgsl.ts';
+import { SnapshotMips } from './snapshotMips.ts';
+import type { MipPipelines } from './surfaceTexturePass.ts';
+import { UniformRing } from './uniformRing.ts';
+
+const USAGE_RENDER_ATTACHMENT = 0x10;
+const USAGE_TEXTURE_BINDING = 0x4;
+const USAGE_UNIFORM_DST = 0x40 | 0x8; // UNIFORM | COPY_DST
+const VISIBILITY_FRAGMENT = 0x2;
+const TINT = OCTAHEDRALRESOLVE_BINDINGS.OCTAHEDRAL_RESOLVE_TINT_FRAG;
+
+const faceRotation = mat3.create();
+const rotationColumn = new Float32Array(3);
+
+export class GpuPointGlassTint {
+  readonly texture: GPUTexture;
+  /** The whole array, for the lit pass. */
+  readonly view: GPUTextureView;
+  /** The colour scratch a face's glass is multiplied into. */
+  readonly scratchView: GPUTextureView;
+  readonly edge: number;
+
+  private readonly device: GPUDevice;
+  private readonly pipelines: MipPipelines;
+  private readonly scratch: GPUTexture;
+  private readonly layerViews: GPUTextureView[] = [];
+  private readonly mips: (SnapshotMips | undefined)[] = [];
+  private readonly pipeline: GPURenderPipeline;
+  private readonly bindGroup: GPUBindGroup;
+  private readonly ring: UniformRing;
+  private readonly heldFaces: Uint8Array;
+  private readonly dirty: Uint8Array;
+
+  constructor(
+    device: GPUDevice,
+    pipelines: MipPipelines,
+    faceSize: number,
+    edge: number,
+    layers: number,
+    /** Resolves a frame can make: the array's own figure, since every face resolves once. */
+    slots: number,
+    encoder: GPUCommandEncoder,
+  ) {
+    this.device = device;
+    this.pipelines = pipelines;
+    this.edge = edge;
+    this.heldFaces = new Uint8Array(layers);
+    /* Every layer's chain is filled once at birth, so a level nothing has touched is white too. */
+    this.dirty = new Uint8Array(layers).fill(1);
+    this.texture = device.createTexture({
+      label: 'pointShadow.tint',
+      size: [edge, edge, layers],
+      format: 'rgba8unorm',
+      mipLevelCount: Math.floor(Math.log2(Math.max(1, edge))) + 1,
+      usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING,
+    });
+    this.view = this.texture.createView({ dimension: '2d-array' });
+    for (let layer = 0; layer < layers; layer++) {
+      this.layerViews.push(
+        this.texture.createView({
+          label: `pointShadow.tint.layer${layer}`,
+          dimension: '2d',
+          baseArrayLayer: layer,
+          arrayLayerCount: 1,
+          baseMipLevel: 0,
+          mipLevelCount: 1,
+        }),
+      );
+    }
+    this.scratch = device.createTexture({
+      label: 'pointShadow.tint.scratch',
+      size: [faceSize, faceSize],
+      format: 'rgba8unorm',
+      usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING,
+    });
+    this.scratchView = this.scratch.createView();
+
+    this.ring = new UniformRing(
+      device,
+      TINT.uniformSize,
+      slots,
+      USAGE_UNIFORM_DST,
+      'pointShadow.tint.uniforms',
+    );
+    const layout = device.createBindGroupLayout({
+      label: 'pointShadow.tint.resolve.layout',
+      entries: [
+        {
+          binding: TINT.uniforms,
+          visibility: VISIBILITY_FRAGMENT,
+          buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: TINT.uniformSize },
+        },
+        {
+          binding: TINT.textures.uFace.texture,
+          visibility: VISIBILITY_FRAGMENT,
+          texture: { sampleType: 'float' },
+        },
+        {
+          binding: TINT.textures.uFace.sampler,
+          visibility: VISIBILITY_FRAGMENT,
+          sampler: { type: 'non-filtering' },
+        },
+      ],
+    });
+    this.bindGroup = device.createBindGroup({
+      label: 'pointShadow.tint.resolve',
+      layout,
+      entries: [
+        { binding: TINT.uniforms, resource: { buffer: this.ring.buffer, size: TINT.uniformSize } },
+        { binding: TINT.textures.uFace.texture, resource: this.scratchView },
+        {
+          binding: TINT.textures.uFace.sampler,
+          resource: device.createSampler({ label: 'pointShadow.tint.resolve.sampler' }),
+        },
+      ],
+    });
+    this.pipeline = device.createRenderPipeline({
+      label: 'pointShadow.tint.resolve',
+      layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      vertex: {
+        module: device.createShaderModule({ code: OCTAHEDRAL_RESOLVE_VERT_WGSL }),
+        entryPoint: 'main',
+      },
+      fragment: {
+        module: device.createShaderModule({ code: OCTAHEDRAL_RESOLVE_TINT_FRAG_WGSL }),
+        entryPoint: 'main',
+        targets: [{ format: 'rgba8unorm' }],
+      },
+      primitive: { topology: 'triangle-list' },
+    });
+
+    /* Every layer born clear: a light no pane has reached lets everything through. */
+    for (const view of this.layerViews) {
+      encoder
+        .beginRenderPass({
+          label: 'pointShadow.tint.clear',
+          colorAttachments: [{ view, loadOp: 'clear', clearValue: [1, 1, 1, 1], storeOp: 'store' }],
+        })
+        .end();
+    }
+  }
+
+  /** Whether `face` of `layer` holds glass: a face that does must be cleared before it is reused. */
+  held(layer: number, face: number): boolean {
+    return (((this.heldFaces[layer] ?? 0) >> face) & 1) === 1;
+  }
+
+  /** Copy the colour scratch into `face`'s region of `layer`, and remember whether it held glass. */
+  resolve(encoder: GPUCommandEncoder, layer: number, face: number, drawn: boolean): void {
+    const view = this.layerViews[layer];
+    if (view === undefined) return;
+    const slot = this.ring.allocate();
+    if (slot === null) return;
+    pointShadowFaceRotation(face, faceRotation);
+    /* WGSL pads a mat3x3 to three four-float columns; the generated struct expects that. */
+    const rotation = TINT.fields.uFaceRotation.offset;
+    for (let column = 0; column < 3; column++) {
+      rotationColumn[0] = faceRotation[column * 3] as number;
+      rotationColumn[1] = faceRotation[column * 3 + 1] as number;
+      rotationColumn[2] = faceRotation[column * 3 + 2] as number;
+      this.ring.writeFloats(slot, rotation + column * 16, rotationColumn);
+    }
+    this.ring.writeInt(slot, TINT.fields.uFaceIndex.offset, face);
+    this.ring.writeFloat(slot, TINT.fields.uEdge.offset, this.edge);
+
+    const pass = encoder.beginRenderPass({
+      label: 'pointShadow.tint.resolve',
+      colorAttachments: [{ view, loadOp: 'load', storeOp: 'store' }],
+    });
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.bindGroup, [slot]);
+    pass.draw(3);
+    pass.end();
+
+    const bit = 1 << face;
+    const was = this.heldFaces[layer] ?? 0;
+    this.heldFaces[layer] = drawn ? was | bit : was & ~bit;
+    this.dirty[layer] = 1;
+  }
+
+  /** The chain frost reads, for every layer touched since the last call. */
+  recordMips(encoder: GPUCommandEncoder): void {
+    for (let layer = 0; layer < this.dirty.length; layer++) {
+      if (this.dirty[layer] !== 1) continue;
+      this.dirty[layer] = 0;
+      let chain = this.mips[layer];
+      if (chain === undefined) {
+        chain = new SnapshotMips(
+          this.device,
+          this.pipelines,
+          this.texture,
+          'rgba8unorm',
+          layer,
+          'pointShadow.tint.mips',
+        );
+        this.mips[layer] = chain;
+      }
+      chain.record(encoder);
+    }
+  }
+
+  beginFrame(): void {
+    this.ring.reset();
+  }
+
+  /** Before the round's submit: the slots are written and must be up before any pass reads. */
+  flush(): void {
+    this.ring.flush();
+  }
+
+  dispose(): void {
+    this.texture.destroy();
+    this.scratch.destroy();
+    this.ring.dispose();
+  }
+}

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

@@ -18,6 +18,8 @@ import {
   OCTAHEDRAL_RESOLVE_VERT_WGSL,
 } from '../../shaders/generated/octahedralResolve.wgsl.ts';
 import { SHADOW_FORMAT } from './depthPass.ts';
+import { GpuPointGlassTint } from './pointGlassTintPass.ts';
+import type { MipPipelines } from './surfaceTexturePass.ts';
 import { UniformRing } from './uniformRing.ts';
 
 /**
@@ -47,6 +49,9 @@ const VISIBILITY_FRAGMENT = 0x2;
  * silently not landing in its layer.
  */
 const RESOLVE_SLOTS = (POINT_SHADOW_POOL + LIVE_POINT_SHADOW_MAPS) * FACE_COUNT;
+/** Twice once glass arrives: a face resolves its opaque depth and then its glass. */
+const DEPTH_RESOLVE_SLOTS = 2 * RESOLVE_SLOTS;
+const USAGE_COPY = 0x01 | 0x02; // COPY_SRC | COPY_DST
 
 /** `mat3x3<f32>` then four scalars, at std140's sixteen-byte columns: see the generated struct. */
 const RESOLVE_UNIFORM_SIZE = 64;
@@ -66,15 +71,19 @@ const rotationColumn = new Float32Array(3);
  * both say the resolve reads the scratch.
  */
 export class GpuPointShadowArray {
-  /** The array, as the shader samples it. */
-  readonly view: GPUTextureView;
+  /** Lights this array holds; the storage doubles under it once glass arrives. */
   readonly layers: number;
   /** Where a face is rendered before it is resolved. One, shared by every light. */
   readonly scratchView: GPUTextureView;
 
-  private readonly texture: GPUTexture;
+  /** Replaced once, when glass first casts: see `growForGlass`. */
+  private texture: GPUTexture;
+  private arrayView: GPUTextureView;
+  private tint: GpuPointGlassTint | null = null;
+  private readonly device: GPUDevice;
+  private readonly faceSize: number;
   private readonly scratch: GPUTexture;
-  private readonly layerViews: GPUTextureView[] = [];
+  private layerViews: GPUTextureView[] = [];
   private readonly pipeline: GPURenderPipeline;
   private readonly bindGroup: GPUBindGroup;
   /**
@@ -102,24 +111,12 @@ export class GpuPointShadowArray {
   ) {
     this.layers =
       Math.min(lightCount, POINT_SHADOW_POOL) + LIVE_POINT_SHADOW_MAPS + Math.max(0, extraLayers);
+    this.device = device;
+    this.faceSize = faceSize;
 
-    this.texture = device.createTexture({
-      label: 'pointShadow.array',
-      size: [OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, this.layers],
-      format: SHADOW_FORMAT,
-      usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING,
-    });
-    this.view = this.texture.createView({ dimension: '2d-array' });
-    for (let layer = 0; layer < this.layers; layer++) {
-      this.layerViews.push(
-        this.texture.createView({
-          label: `pointShadow.layer${layer}`,
-          dimension: '2d',
-          baseArrayLayer: layer,
-          arrayLayerCount: 1,
-        }),
-      );
-    }
+    this.texture = depthArray(device, this.layers);
+    this.arrayView = this.texture.createView({ dimension: '2d-array' });
+    this.layerViews = layerViewsOf(this.texture, this.layers);
 
     this.scratch = device.createTexture({
       label: 'pointShadow.scratch',
@@ -132,7 +129,7 @@ export class GpuPointShadowArray {
     this.ring = new UniformRing(
       device,
       RESOLVE_UNIFORM_SIZE,
-      RESOLVE_SLOTS,
+      DEPTH_RESOLVE_SLOTS,
       USAGE_UNIFORM_DST,
       'pointShadow.resolve.uniforms',
     );
@@ -206,7 +203,102 @@ export class GpuPointShadowArray {
     far: number,
     near: number,
   ): void {
-    const view = this.layerViews[layer];
+    this.resolveInto(encoder, layer * this.stride, face, far, near);
+  }
+
+  /** The face's glass depth into light `layer`'s glass layer, 2L + 1. */
+  resolveGlass(
+    encoder: GPUCommandEncoder,
+    layer: number,
+    face: number,
+    far: number,
+    near: number,
+  ): void {
+    if (this.tint === null) return;
+    this.resolveInto(encoder, 2 * layer + 1, face, far, near);
+  }
+
+  /** The array, as the shader samples it. Replaced once, when glass first casts. */
+  get view(): GPUTextureView {
+    return this.arrayView;
+  }
+
+  get hasGlass(): boolean {
+    return this.tint !== null;
+  }
+
+  /** Physical layers a light: 1, or 2 once glass has interleaved the array. */
+  get stride(): number {
+    return this.tint === null ? 1 : 2;
+  }
+
+  /** The lights' glass tint, once glass has cast. */
+  get glassTint(): GpuPointGlassTint | null {
+    return this.tint;
+  }
+
+  /**
+   * Interleave the array for glass, on `encoder`: light L's depth moves to 2L and its glass takes
+   * 2L + 1, every glass layer born at the far plane, and the tint made. The reasoning, and why no
+   * map re-bakes, is `PointShadowArray.growForGlass`'s.
+   *
+   * Returns the texture it replaced, which the caller destroys once `encoder` is submitted — the
+   * copies out of it are recorded there — or null when the array had already grown.
+   */
+  growForGlass(
+    encoder: GPUCommandEncoder,
+    tintEdge: number,
+    pipelines: MipPipelines,
+  ): GPUTexture | null {
+    if (this.tint !== null) return null;
+    const old = this.texture;
+    const texture = depthArray(this.device, this.layers * 2);
+    for (let layer = 0; layer < this.layers; layer++) {
+      encoder.copyTextureToTexture(
+        { texture: old, origin: { x: 0, y: 0, z: layer } },
+        { texture, origin: { x: 0, y: 0, z: 2 * layer } },
+        [OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, 1],
+      );
+    }
+    this.texture = texture;
+    this.arrayView = texture.createView({ dimension: '2d-array' });
+    this.layerViews = layerViewsOf(texture, this.layers * 2);
+    /* Nothing is nearer a lamp than a pane that has not been drawn. */
+    for (let layer = 0; layer < this.layers; layer++) {
+      encoder
+        .beginRenderPass({
+          label: 'pointShadow.glass.clear',
+          colorAttachments: [],
+          depthStencilAttachment: {
+            view: this.layerViews[2 * layer + 1] as GPUTextureView,
+            depthClearValue: 1,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+          },
+        })
+        .end();
+    }
+    this.tint = new GpuPointGlassTint(
+      this.device,
+      pipelines,
+      this.faceSize,
+      tintEdge,
+      this.layers,
+      RESOLVE_SLOTS,
+      encoder,
+    );
+    return old;
+  }
+
+  /** The scratch into physical layer `physical`'s region for `face`. */
+  private resolveInto(
+    encoder: GPUCommandEncoder,
+    physical: number,
+    face: number,
+    far: number,
+    near: number,
+  ): void {
+    const view = this.layerViews[physical];
     if (view === undefined) return;
     const slot = this.ring.allocate();
     if (slot === null) return;
@@ -242,25 +334,39 @@ export class GpuPointShadowArray {
   /** Start a frame's bakes. See the ring: slots are reused and nothing is freed. */
   beginFrame(): void {
     this.ring.reset();
+    this.tint?.beginFrame();
   }
 
   /** Upload every slot this frame's resolves took, in one write, before the encoder is submitted. */
   flush(): void {
     this.ring.flush();
+    this.tint?.flush();
   }
 
   dispose(): void {
     this.texture.destroy();
     this.scratch.destroy();
     this.ring.dispose();
+    this.tint?.dispose();
   }
 }
 
 /** What a face's pass needs from the caller: somewhere to record, and the casters to record. */
 export type PointShadowFacePass = (view: GPUTextureView, viewProj: mat4) => void;
 
-/** And what turns that face into its region of the light's octahedral layer. */
-export type PointShadowResolve = (layer: number, face: number, far: number, near: number) => void;
+/**
+ * And what turns that face into its region of the light's octahedral layer — and, where the face
+ * offered glass, draws and resolves that too, lit from the bake origin `x`, `y`, `z`.
+ */
+export type PointShadowResolve = (
+  layer: number,
+  face: number,
+  far: number,
+  near: number,
+  x: number,
+  y: number,
+  z: number,
+) => void;
 
 export class GpuPointShadowMap implements PointShadowSource {
   readonly size: number;
@@ -369,7 +475,7 @@ export class GpuPointShadowMap implements PointShadowSource {
         array.scratchView,
         pointShadowFaceViewProj(face, plan.x, plan.y, plan.z, plan.near, plan.range, scratch),
       );
-      resolveFace(this.layer, face, plan.range, plan.near);
+      resolveFace(this.layer, face, plan.range, plan.near, plan.x, plan.y, plan.z);
     }
 
     this.image.completeBake(last, plan.x, plan.y, plan.z, plan.range, plan.near, plan.sourceRadius);
@@ -379,3 +485,29 @@ export class GpuPointShadowMap implements PointShadowSource {
   /** Nothing to free: every GPU object belongs to `GpuPointShadowArray` now. */
   dispose(): void {}
 }
+
+/** The depth array, copyable so glass can interleave it without a re-bake. */
+function depthArray(device: GPUDevice, layers: number): GPUTexture {
+  return device.createTexture({
+    label: 'pointShadow.array',
+    size: [OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, layers],
+    format: SHADOW_FORMAT,
+    usage: USAGE_RENDER_ATTACHMENT | USAGE_TEXTURE_BINDING | USAGE_COPY,
+  });
+}
+
+/** One single-layer view per physical layer: a depth attachment takes exactly one. */
+function layerViewsOf(texture: GPUTexture, layers: number): GPUTextureView[] {
+  const views: GPUTextureView[] = [];
+  for (let layer = 0; layer < layers; layer++) {
+    views.push(
+      texture.createView({
+        label: `pointShadow.layer${layer}`,
+        dimension: '2d',
+        baseArrayLayer: layer,
+        arrayLayerCount: 1,
+      }),
+    );
+  }
+  return views;
+}

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

@@ -331,7 +331,37 @@ export function postPipeline(
   format: GPUTextureFormat,
   blend?: GPUBlendState,
 ): GPURenderPipeline {
-  return cache.get(key, () => ({
+  return cache.get(key, () =>
+    describePost(device, layout, key, fragment, [
+      blend === undefined ? { format } : { format, blend },
+    ]),
+  );
+}
+
+/**
+ * The same over several colour targets, in the fragment's output order: the temporal resolve
+ * writes its picture and each pixel's flicker record in one pass. `targets` is the caller's, held
+ * rather than built per call, since this is asked for every frame.
+ */
+export function postPipelineTargets(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  key: string,
+  fragment: string,
+  targets: GPUColorTargetState[],
+): GPURenderPipeline {
+  return cache.get(key, () => describePost(device, layout, key, fragment, targets));
+}
+
+function describePost(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  key: string,
+  fragment: string,
+  targets: GPUColorTargetState[],
+): GPURenderPipelineDescriptor {
+  return {
     label: key,
     layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
     vertex: {
@@ -341,7 +371,7 @@ export function postPipeline(
     fragment: {
       module: shaderModule(device, { label: key, code: fragment }),
       entryPoint: 'main',
-      targets: [blend === undefined ? { format } : { format, blend }],
+      targets,
     },
     /*
      * No depth at all, which is what makes this different from every other pipeline here: the
@@ -349,11 +379,11 @@ export function postPipeline(
      * disables the test, the write and culling by hand for the same draw.
      */
     primitive: { topology: 'triangle-list' as const, cullMode: 'none' as const },
-  }));
+  };
 }
 
 /**
- * The temporal resolve's block and its three inputs.
+ * The temporal resolve's block and its four inputs.
  *
  * Named like the occlusion's beside it, and for the same reason `BLOOM_DOWNSAMPLE_FIELDS` is: a
  * block read by assumption rather than by name is a uniform written to the wrong offset, which