@driftengine/core 4.4.2 → 4.6.0

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

@@ -334,7 +334,8 @@ export function createScatterDepthBindGroupLayout(
       {
         binding: previous.texture,
         visibility: VISIBILITY_FRAGMENT,
-        texture: { sampleType: 'unfilterable-float' },
+        /* The depth program's peel read, an array since the sun's maps became one. */
+        texture: { sampleType: 'unfilterable-float', viewDimension: '2d-array' },
       },
       {
         binding: previous.sampler,

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

@@ -142,7 +142,12 @@ export function createSdfTextBindGroupLayout(device: GPUDevice): GPUBindGroupLay
         visibility: VISIBILITY_FRAGMENT,
         buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SDF_TEXT_FRAG_SIZE },
       },
-      { binding: ATLAS.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+      /* The atlas is a surface texture, and every surface texture is a `2d-array` view. */
+      {
+        binding: ATLAS.texture,
+        visibility: VISIBILITY_FRAGMENT,
+        texture: { viewDimension: '2d-array' },
+      },
       { binding: ATLAS.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
     ],
   });

package/src/render/backend/webgpu/shaders/instanceCull.wgsl.ts

@@ -0,0 +1,61 @@
+import { INSTANCE_FLOATS } from '../../../instances.ts';
+
+/**
+ * The instance cull, in WGSL, hand-authored under the compute exception `AGENTS.md` records
+ * (2026-08-24): a compute shader has no WebGL2 twin to generate from, and `npm run wgsl` neither
+ * writes nor polices this file.
+ *
+ * **It keeps exactly what `cullInstances` keeps**, and `gpu-parity.mjs` runs both on a device: an
+ * instance's world sphere is the mesh's sphere with its centre through the model matrix and its
+ * radius scaled by the largest column, and it is kept unless wholly beyond one of the six planes.
+ * The one difference is order — survivors are compacted by `atomicAdd`, so they arrive in whatever
+ * order the invocations reached it. That is invisible to an opaque draw and is why a blended draw
+ * is never culled here.
+ *
+ * `args` is a `drawIndexedIndirect` record, `(indexCount, instanceCount, firstIndex, baseVertex,
+ * firstInstance)`; the renderer writes it with a zero instance count before each dispatch and this
+ * counts the survivors into it.
+ */
+export const INSTANCE_CULL_WORKGROUP = 64;
+
+export const INSTANCE_CULL_WGSL = /* wgsl */ `
+struct Params {
+  planes: array<vec4<f32>, 6>,
+  sphere: vec4<f32>,
+  count: u32,
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+}
+
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> source: array<f32>;
+@group(0) @binding(2) var<storage, read_write> kept: array<f32>;
+@group(0) @binding(3) var<storage, read_write> args: array<atomic<u32>, 5>;
+
+const STRIDE: u32 = ${INSTANCE_FLOATS}u;
+
+@compute @workgroup_size(${INSTANCE_CULL_WORKGROUP})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let i = id.x;
+  if (i >= params.count) { return; }
+  let at = i * STRIDE;
+  let c0 = vec3<f32>(source[at], source[at + 1u], source[at + 2u]);
+  let c1 = vec3<f32>(source[at + 4u], source[at + 5u], source[at + 6u]);
+  let c2 = vec3<f32>(source[at + 8u], source[at + 9u], source[at + 10u]);
+  let t = vec3<f32>(source[at + 12u], source[at + 13u], source[at + 14u]);
+  let local = params.sphere;
+  let centre = c0 * local.x + c1 * local.y + c2 * local.z + t;
+  let scale = sqrt(max(dot(c0, c0), max(dot(c1, c1), dot(c2, c2))));
+  let radius = local.w * scale;
+  for (var p = 0u; p < 6u; p = p + 1u) {
+    let plane = params.planes[p];
+    if (dot(plane.xyz, centre) + plane.w < -radius) { return; }
+  }
+  let slot = atomicAdd(&args[1], 1u);
+  let to = slot * STRIDE;
+  for (var k = 0u; k < STRIDE; k = k + 1u) {
+    kept[to + k] = source[at + k];
+  }
+}
+`;

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

@@ -15,6 +15,10 @@ import { SkinPaletteTexture } from './skinPaletteTexture.ts';
  * **What would make it wrong** is a genuine crowd — a stadium, a swarm of rigged birds — and the
  * fix is then the one `skinPalette.ts` names: one texture holding every palette with a per-draw
  * row offset, which spends a uniform and a shader change to stop spending textures.
+ *
+ * **A reconstructing frame spends one more per skinned mover**: last frame's pose is uploaded into
+ * a slot of its own for the motion pass. So the same budget is about twelve such characters with a
+ * reflection and three shadow layers each.
  */
 export const MAX_SKIN_PALETTES = 128;
 

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

@@ -0,0 +1,80 @@
+/**
+ * The mip chain of the frame's refraction copy, recorded into the frame's own encoder.
+ *
+ * **Frosted glass reads a blurrier level of what is behind it** (`glass.ts`), so on a frame that draws
+ * glass the copy needs every level filled from the one above. `generateMipChain` does that for an
+ * upload, on an encoder of its own that it submits at once — which here would run before the frame's
+ * encoder had even made the copy, and would build views and bind groups on every call. So this
+ * makes them once per copy texture and records one pass per level wherever the copy was taken.
+ *
+ * What it costs is a render pass per level on every frame that takes the copy — about a dozen for a
+ * 1080p copy, each a quarter of the one before, together about a third of the copy itself — and
+ * nothing on a frame that shows nothing through anything. **A frame that refracts and draws no glass
+ * pays it too**, and that is the trade: the copy is taken at the first draw that asks and shared by
+ * every later one, so a glass pane drawn after a refracting one would otherwise read levels nothing
+ * filled. WebGL2 fills its chain on the first glass draw instead, because a `generateMipmap` there
+ * ends no pass. What would change it is knowing at the copy whether glass follows in the frame.
+ */
+import type { MipPipelines } from './surfaceTexturePass.ts';
+import { mipBlitPipeline } from './surfaceTexturePass.ts';
+
+export class SnapshotMips {
+  private readonly pipeline: GPURenderPipeline;
+  private readonly targets: GPUTextureView[] = [];
+  private readonly groups: GPUBindGroup[] = [];
+
+  constructor(
+    device: GPUDevice,
+    pipelines: MipPipelines,
+    texture: GPUTexture,
+    format: GPUTextureFormat,
+    /** One layer of an array texture, where the chain is a layer's rather than the texture's. */
+    layer: number | null = null,
+    private readonly label = 'refract.mips',
+  ) {
+    this.pipeline = mipBlitPipeline(device, pipelines, format);
+    const sampler = device.createSampler({
+      label: 'refract.mips.sampler',
+      magFilter: 'linear',
+      minFilter: 'linear',
+    });
+    const layout = this.pipeline.getBindGroupLayout(0);
+    const at =
+      layer === null ? {} : { dimension: '2d' as const, baseArrayLayer: layer, arrayLayerCount: 1 };
+    for (let level = 1; level < texture.mipLevelCount; level++) {
+      const source = texture.createView({ ...at, baseMipLevel: level - 1, mipLevelCount: 1 });
+      this.targets.push(texture.createView({ ...at, baseMipLevel: level, mipLevelCount: 1 }));
+      this.groups.push(
+        device.createBindGroup({
+          label: `refract.mips.${String(level)}`,
+          layout,
+          entries: [
+            { binding: 0, resource: source },
+            { binding: 1, resource: sampler },
+          ],
+        }),
+      );
+    }
+  }
+
+  /** Fill every level from level 0, in `encoder`, after whatever wrote level 0 there. */
+  record(encoder: GPUCommandEncoder): void {
+    for (let i = 0; i < this.targets.length; i++) {
+      const pass = encoder.beginRenderPass({
+        label: this.label,
+        colorAttachments: [
+          {
+            view: this.targets[i] as GPUTextureView,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 0],
+          },
+        ],
+      });
+      pass.setPipeline(this.pipeline);
+      pass.setBindGroup(0, this.groups[i] as GPUBindGroup);
+      pass.draw(3);
+      pass.end();
+    }
+  }
+}

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

@@ -1,4 +1,7 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.ts';
+import { toHalfFloats } from '../../halfFloat.ts';
+import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import { shaderModule } from './shaderModules.ts';
 
@@ -89,6 +92,8 @@ export function generateMipChain(
   texture: GPUTexture,
   format: GPUTextureFormat,
   levels: number,
+  /** How many array layers to fill, each its own chain. One for a plain texture. */
+  layers = 1,
 ): void {
   if (levels < 2) return;
   const pipeline = mipBlitPipeline(device, pipelines, format);
@@ -98,29 +103,33 @@ export function generateMipChain(
     minFilter: 'linear',
   });
   const encoder = device.createCommandEncoder({ label: 'mip.chain' });
-  for (let level = 1; level < levels; level++) {
-    const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
-    const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
-    const pass = encoder.beginRenderPass({
-      label: `mip.level${level}`,
-      colorAttachments: [
-        { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
-      ],
-    });
-    pass.setPipeline(pipeline);
-    pass.setBindGroup(
-      0,
-      device.createBindGroup({
-        layout: pipeline.getBindGroupLayout(0),
-        entries: [
-          { binding: 0, resource: source },
-          { binding: 1, resource: sampler },
+  /* One level of one layer at a time: a render target is a single 2D subresource, and the source
+     view is one level of the same layer, so no pass reads what it writes. */
+  for (let layer = 0; layer < layers; layer++)
+    for (let level = 1; level < levels; level++) {
+      const one = { dimension: '2d' as const, baseArrayLayer: layer, arrayLayerCount: 1 };
+      const source = texture.createView({ ...one, baseMipLevel: level - 1, mipLevelCount: 1 });
+      const target = texture.createView({ ...one, baseMipLevel: level, mipLevelCount: 1 });
+      const pass = encoder.beginRenderPass({
+        label: `mip.level${level}`,
+        colorAttachments: [
+          { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
         ],
-      }),
-    );
-    pass.draw(3);
-    pass.end();
-  }
+      });
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({
+          layout: pipeline.getBindGroupLayout(0),
+          entries: [
+            { binding: 0, resource: source },
+            { binding: 1, resource: sampler },
+          ],
+        }),
+      );
+      pass.draw(3);
+      pass.end();
+    }
   device.queue.submit([encoder.finish()]);
 }
 
@@ -128,7 +137,7 @@ export function generateMipChain(
  * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting a
  * linear chain through a pipeline declared for the other one is a gamma error per level.
  */
-function mipBlitPipeline(
+export function mipBlitPipeline(
   device: GPUDevice,
   pipelines: MipPipelines,
   format: GPUTextureFormat,
@@ -149,19 +158,11 @@ function mipBlitPipeline(
   }));
 }
 
-function sourceSize(source: TexImageSource): { width: number; height: number } {
-  const candidate = source as {
-    width?: number;
-    height?: number;
-    videoWidth?: number;
-    videoHeight?: number;
-  };
-  const width = candidate.videoWidth ?? candidate.width ?? 0;
-  const height = candidate.videoHeight ?? candidate.height ?? 0;
-  return { width: Math.max(1, width), height: Math.max(1, height) };
-}
-
-/** An image uploaded once and bound per material. */
+/**
+ * An image uploaded once and bound per material — or several of one size, as an array's layers.
+ * Every surface texture is a `2d-array` view, a plain image an array of one; `surfaceTexture.ts`
+ * says why.
+ */
 export class GpuSurfaceTexture {
   readonly sampler: GPUSampler;
 
@@ -172,14 +173,22 @@ export class GpuSurfaceTexture {
   private levels: number;
   private width: number;
   private height: number;
+  /** How many images the array holds. */
+  readonly layers: number;
+  /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
+  private effectsTable: GPUTexture | null = null;
+  /** Its view, which the flat group binds beside this image when it is a material's albedo. */
+  effectsView: GPUTextureView | null = null;
 
   constructor(
     private readonly device: GPUDevice,
     private readonly pipelines: PipelineCache,
-    source: TexImageSource,
+    source: TexImageSource | readonly TexImageSource[],
     options: SurfaceTextureOptions = {},
   ) {
-    const { width, height } = sourceSize(source);
+    const sources: readonly TexImageSource[] = isSourceList(source) ? source : [source];
+    const { width, height } = layerSize(sources);
+    this.layers = sources.length;
     this.mipmapped = options.mipmap ?? true;
     /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
        place it is correct — `surfaceTexture.ts` makes the argument in full. */
@@ -188,7 +197,7 @@ export class GpuSurfaceTexture {
     this.height = height;
     this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
     this.texture = this.allocate();
-    this.current = this.texture.createView();
+    this.current = this.arrayView(this.texture);
 
     const wrap: GPUAddressMode =
       (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
@@ -223,7 +232,32 @@ export class GpuSurfaceTexture {
           : 1,
     });
 
-    this.upload(source);
+    this.upload(sources);
+
+    /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
+       and read by `textureLoad` alone, so the filter never runs. */
+    const effects = options.effects ?? [];
+    if (effects.length > 0) {
+      const table = device.createTexture({
+        label: 'surface.effects',
+        size: [SURFACE_EFFECT_TEXELS, effects.length],
+        format: 'rgba16float',
+        usage: 0x4 | 0x2, // TEXTURE_BINDING | COPY_DST
+      });
+      device.queue.writeTexture(
+        { texture: table },
+        toHalfFloats(packSurfaceEffects(effects)),
+        { bytesPerRow: SURFACE_EFFECT_TEXELS * 8, rowsPerImage: effects.length },
+        { width: SURFACE_EFFECT_TEXELS, height: effects.length, depthOrArrayLayers: 1 },
+      );
+      this.effectsTable = table;
+      this.effectsView = table.createView();
+    }
+  }
+
+  /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
+  private arrayView(texture: GPUTexture): GPUTextureView {
+    return texture.createView({ dimension: '2d-array', arrayLayerCount: this.layers });
   }
 
   /** The view every binding of this image holds. A new one when `update` changes the size. */
@@ -248,24 +282,25 @@ export class GpuSurfaceTexture {
   update(source: TexImageSource): GPUTexture | null {
     const replaced = this.texture;
     if (replaced === null) return null;
+    refuseArrayUpdate(this.layers);
     const { width, height } = sourceSize(source);
     if (width === this.width && height === this.height) {
-      this.upload(source);
+      this.upload([source]);
       return null;
     }
     this.width = width;
     this.height = height;
     this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
     this.texture = this.allocate();
-    this.current = this.texture.createView();
-    this.upload(source);
+    this.current = this.arrayView(this.texture);
+    this.upload([source]);
     return replaced;
   }
 
   private allocate(): GPUTexture {
     return this.device.createTexture({
       label: 'surface.texture',
-      size: [this.width, this.height],
+      size: [this.width, this.height, this.layers],
       format: this.format,
       mipLevelCount: this.levels,
       /*
@@ -290,9 +325,12 @@ export class GpuSurfaceTexture {
     if (this.texture === null) return;
     this.texture.destroy();
     this.texture = null;
+    this.effectsTable?.destroy();
+    this.effectsTable = null;
+    this.effectsView = null;
   }
 
-  private upload(source: TexImageSource): void {
+  private upload(sources: readonly TexImageSource[]): void {
     const texture = this.texture;
     if (texture === null) return;
     /*
@@ -306,11 +344,13 @@ export class GpuSurfaceTexture {
      * The orientation check that passed this backend was run on a canvas alone, where the two
      * agreed. Measure both source types, or a texture pipeline is half tested.
      */
-    this.device.queue.copyExternalImageToTexture(
-      { source: source as GPUCopyExternalImageSource, flipY: false },
-      { texture },
-      [this.width, this.height],
-    );
+    for (let layer = 0; layer < sources.length; layer++) {
+      this.device.queue.copyExternalImageToTexture(
+        { source: sources[layer] as GPUCopyExternalImageSource, flipY: false },
+        { texture, origin: [0, 0, layer] },
+        [this.width, this.height],
+      );
+    }
     if (this.levels > 1) this.generateMips(texture);
   }
 
@@ -322,6 +362,6 @@ export class GpuSurfaceTexture {
    * an attachment and a resource at once — rejected, and rejected silently enough to matter.
    */
   private generateMips(texture: GPUTexture): void {
-    generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
+    generateMipChain(this.device, this.pipelines, texture, this.format, this.levels, this.layers);
   }
 }

package/src/render/driftLight/bake.ts

@@ -57,69 +57,92 @@ export function bakeBrick(
   for (let k = 0; k < BRICK_SAMPLES; k++) {
     for (let j = 0; j < BRICK_SAMPLES; j++) {
       for (let i = 0; i < BRICK_SAMPLES; i++) {
-        const texel = (i + BRICK_SAMPLES * (j + BRICK_SAMPLES * k)) * 4;
-        const px = bx + i * spacing;
-        const py = by + j * spacing;
-        const pz = bz + k * spacing;
-        light.fill(0, texel, texel + 4);
-        direction.fill(0, texel, texel + 4);
-        if (distance !== null && distance(px, py, pz) < 0) continue;
-
-        let r = 0;
-        let g = 0;
-        let b = 0;
-        let towardX = 0;
-        let towardY = 0;
-        let towardZ = 0;
-        let weight = 0;
-        for (let listed = first; listed < last; listed++) {
-          const source = lights[layout.lights[listed] as number];
-          if (source === undefined) continue;
-          const dx = source.x - px;
-          const dy = source.y - py;
-          const dz = source.z - pz;
-          const dist = Math.hypot(dx, dy, dz);
-          if (dist >= source.radius) continue;
-          const shape = pointLightShape(dist, source.radius, falloff);
-          if (shape <= 0) continue;
-          const seen =
-            distance === null
-              ? 1
-              : softVisibility(
-                  distance,
-                  px,
-                  py,
-                  pz,
-                  source.x,
-                  source.y,
-                  source.z,
-                  source.sourceRadius,
-                );
-          if (seen <= 0) continue;
-          const lr = source.r * shape * seen;
-          const lg = source.g * shape * seen;
-          const lb = source.b * shape * seen;
-          r += lr;
-          g += lg;
-          b += lb;
-          const bright = 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
-          if (dist > 1e-6 && bright > 0) {
-            towardX += (bright * dx) / dist;
-            towardY += (bright * dy) / dist;
-            towardZ += (bright * dz) / dist;
-            weight += bright;
-          }
-        }
-        light[texel] = r;
-        light[texel + 1] = g;
-        light[texel + 2] = b;
-        light[texel + 3] = 1;
-        if (weight > 0) {
-          direction[texel] = towardX / weight;
-          direction[texel + 1] = towardY / weight;
-          direction[texel + 2] = towardZ / weight;
-        }
+        sampleFieldLight(
+          bx + i * spacing,
+          by + j * spacing,
+          bz + k * spacing,
+          lights,
+          layout.lights,
+          first,
+          last,
+          falloff,
+          distance,
+          light,
+          direction,
+          (i + BRICK_SAMPLES * (j + BRICK_SAMPLES * k)) * 4,
+        );
       }
     }
   }
 }
+
+/**
+ * One sample: the light arriving at (px, py, pz) from `lights[candidates[first..last)]`, written at
+ * `texel` in `light` (colour, then 1 for a sample and 0 for one inside solid geometry) and in
+ * `direction` (the brightness-weighted way it arrives from). Shared by every bake, so a brick and a
+ * dense volume cannot come to disagree about what a sample is.
+ */
+export function sampleFieldLight(
+  px: number,
+  py: number,
+  pz: number,
+  lights: readonly FieldLight[],
+  candidates: ArrayLike<number>,
+  first: number,
+  last: number,
+  falloff: PointLightFalloff,
+  distance: DistanceAt | null,
+  light: Float32Array,
+  direction: Float32Array,
+  texel: number,
+): void {
+  light.fill(0, texel, texel + 4);
+  direction.fill(0, texel, texel + 4);
+  if (distance !== null && distance(px, py, pz) < 0) return;
+
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let towardX = 0;
+  let towardY = 0;
+  let towardZ = 0;
+  let weight = 0;
+  for (let listed = first; listed < last; listed++) {
+    const source = lights[candidates[listed] as number];
+    if (source === undefined) continue;
+    const dx = source.x - px;
+    const dy = source.y - py;
+    const dz = source.z - pz;
+    const dist = Math.hypot(dx, dy, dz);
+    if (dist >= source.radius) continue;
+    const shape = pointLightShape(dist, source.radius, falloff);
+    if (shape <= 0) continue;
+    const seen =
+      distance === null
+        ? 1
+        : softVisibility(distance, px, py, pz, source.x, source.y, source.z, source.sourceRadius);
+    if (seen <= 0) continue;
+    const lr = source.r * shape * seen;
+    const lg = source.g * shape * seen;
+    const lb = source.b * shape * seen;
+    r += lr;
+    g += lg;
+    b += lb;
+    const bright = 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+    if (dist > 1e-6 && bright > 0) {
+      towardX += (bright * dx) / dist;
+      towardY += (bright * dy) / dist;
+      towardZ += (bright * dz) / dist;
+      weight += bright;
+    }
+  }
+  light[texel] = r;
+  light[texel + 1] = g;
+  light[texel + 2] = b;
+  light[texel + 3] = 1;
+  if (weight > 0) {
+    direction[texel] = towardX / weight;
+    direction[texel + 1] = towardY / weight;
+    direction[texel + 2] = towardZ / weight;
+  }
+}