@driftengine/core 4.4.2 → 4.6.0

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

@@ -255,7 +255,8 @@ export function createScatterDepthBindGroupLayout(device, fragBinding, fragSize,
             {
                 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/dist/render/backend/webgpu/sdfTextPass.js

@@ -125,7 +125,12 @@ export function createSdfTextBindGroupLayout(device) {
                 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/dist/render/backend/webgpu/shaders/instanceCull.wgsl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 declare const INSTANCE_CULL_WORKGROUP = 64;
+export declare const INSTANCE_CULL_WGSL = "\nstruct Params {\n  planes: array<vec4<f32>, 6>,\n  sphere: vec4<f32>,\n  count: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n@group(0) @binding(1) var<storage, read> source: array<f32>;\n@group(0) @binding(2) var<storage, read_write> kept: array<f32>;\n@group(0) @binding(3) var<storage, read_write> args: array<atomic<u32>, 5>;\n\nconst STRIDE: u32 = 20u;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  let i = id.x;\n  if (i >= params.count) { return; }\n  let at = i * STRIDE;\n  let c0 = vec3<f32>(source[at], source[at + 1u], source[at + 2u]);\n  let c1 = vec3<f32>(source[at + 4u], source[at + 5u], source[at + 6u]);\n  let c2 = vec3<f32>(source[at + 8u], source[at + 9u], source[at + 10u]);\n  let t = vec3<f32>(source[at + 12u], source[at + 13u], source[at + 14u]);\n  let local = params.sphere;\n  let centre = c0 * local.x + c1 * local.y + c2 * local.z + t;\n  let scale = sqrt(max(dot(c0, c0), max(dot(c1, c1), dot(c2, c2))));\n  let radius = local.w * scale;\n  for (var p = 0u; p < 6u; p = p + 1u) {\n    let plane = params.planes[p];\n    if (dot(plane.xyz, centre) + plane.w < -radius) { return; }\n  }\n  let slot = atomicAdd(&args[1], 1u);\n  let to = slot * STRIDE;\n  for (var k = 0u; k < STRIDE; k = k + 1u) {\n    kept[to + k] = source[at + k];\n  }\n}\n";

package/dist/render/backend/webgpu/shaders/instanceCull.wgsl.js

@@ -0,0 +1,59 @@
+import { INSTANCE_FLOATS } from '../../../instances.js';
+/**
+ * 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/dist/render/backend/webgpu/skinPaletteRing.d.ts

@@ -13,6 +13,10 @@
  * **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 declare const MAX_SKIN_PALETTES = 128;
 /**

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

@@ -14,6 +14,10 @@ import { SkinPaletteTexture } from './skinPaletteTexture.js';
  * **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/dist/render/backend/webgpu/snapshotMips.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';
+export declare class SnapshotMips {
+    private readonly label;
+    private readonly pipeline;
+    private readonly targets;
+    private readonly groups;
+    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, label?: string);
+    /** Fill every level from level 0, in `encoder`, after whatever wrote level 0 there. */
+    record(encoder: GPUCommandEncoder): void;
+}

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

@@ -0,0 +1,52 @@
+import { mipBlitPipeline } from './surfaceTexturePass.js';
+export class SnapshotMips {
+    label;
+    pipeline;
+    targets = [];
+    groups = [];
+    constructor(device, pipelines, texture, format, 
+    /** One layer of an array texture, where the chain is a layer's rather than the texture's. */
+    layer = null, label = 'refract.mips') {
+        this.label = label;
+        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', 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) {
+        for (let i = 0; i < this.targets.length; i++) {
+            const pass = encoder.beginRenderPass({
+                label: this.label,
+                colorAttachments: [
+                    {
+                        view: this.targets[i],
+                        loadOp: 'clear',
+                        storeOp: 'store',
+                        clearValue: [0, 0, 0, 0],
+                    },
+                ],
+            });
+            pass.setPipeline(this.pipeline);
+            pass.setBindGroup(0, this.groups[i]);
+            pass.draw(3);
+            pass.end();
+        }
+    }
+}

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

@@ -29,8 +29,19 @@ export interface MipPipelines {
  * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
  * thing, and the second copy is the one that would quietly disagree about the format.
  */
-export declare function generateMipChain(device: GPUDevice, pipelines: MipPipelines, texture: GPUTexture, format: GPUTextureFormat, levels: number): void;
-/** An image uploaded once and bound per material. */
+export declare function generateMipChain(device: GPUDevice, pipelines: MipPipelines, texture: GPUTexture, format: GPUTextureFormat, levels: number, 
+/** How many array layers to fill, each its own chain. One for a plain texture. */
+layers?: number): void;
+/**
+ * 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.
+ */
+export declare function mipBlitPipeline(device: GPUDevice, pipelines: MipPipelines, format: GPUTextureFormat): GPURenderPipeline;
+/**
+ * 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 declare class GpuSurfaceTexture {
     private readonly device;
     private readonly pipelines;
@@ -42,7 +53,15 @@ export declare class GpuSurfaceTexture {
     private levels;
     private width;
     private height;
-    constructor(device: GPUDevice, pipelines: PipelineCache, source: TexImageSource, options?: SurfaceTextureOptions);
+    /** 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;
+    /** Its view, which the flat group binds beside this image when it is a material's albedo. */
+    effectsView: GPUTextureView | null;
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
+    /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
+    private arrayView;
     /** The view every binding of this image holds. A new one when `update` changes the size. */
     get view(): GPUTextureView;
     /**

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

@@ -1,3 +1,6 @@
+import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.js';
+import { toHalfFloats } from '../../halfFloat.js';
+import { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
 import { shaderModule } from './shaderModules.js';
 /**
  * A caller's image on the device, and the mip chain WebGPU will not build for it.
@@ -65,7 +68,9 @@ export function mipLevelCount(width, height) {
  * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
  * thing, and the second copy is the one that would quietly disagree about the format.
  */
-export function generateMipChain(device, pipelines, texture, format, levels) {
+export function generateMipChain(device, pipelines, texture, format, levels, 
+/** How many array layers to fill, each its own chain. One for a plain texture. */
+layers = 1) {
     if (levels < 2)
         return;
     const pipeline = mipBlitPipeline(device, pipelines, format);
@@ -75,33 +80,37 @@ export function generateMipChain(device, pipelines, texture, format, levels) {
         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 },
-            ],
-        }));
-        pass.draw(3);
-        pass.end();
-    }
+    /* 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', 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.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()]);
 }
 /**
  * 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(device, pipelines, format) {
+export function mipBlitPipeline(device, pipelines, format) {
     return pipelines.get(`surface.mip:${format}`, () => ({
         label: `surface.mip:${format}`,
         layout: 'auto',
@@ -117,13 +126,11 @@ function mipBlitPipeline(device, pipelines, format) {
         primitive: { topology: 'triangle-list' },
     }));
 }
-function sourceSize(source) {
-    const candidate = source;
-    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 {
     device;
     pipelines;
@@ -135,10 +142,18 @@ export class GpuSurfaceTexture {
     levels;
     width;
     height;
+    /** How many images the array holds. */
+    layers;
+    /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
+    effectsTable = null;
+    /** Its view, which the flat group binds beside this image when it is a material's albedo. */
+    effectsView = null;
     constructor(device, pipelines, source, options = {}) {
         this.device = device;
         this.pipelines = pipelines;
-        const { width, height } = sourceSize(source);
+        const sources = 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. */
@@ -147,7 +162,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 = (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
         /*
          * Nearest where the caller said their pixels are the subject. `mipmapFilter` stays as it was:
@@ -178,7 +193,25 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 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. */
+    arrayView(texture) {
+        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. */
     get view() {
@@ -202,23 +235,24 @@ export class GpuSurfaceTexture {
         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;
     }
     allocate() {
         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,
             /*
@@ -243,8 +277,11 @@ export class GpuSurfaceTexture {
             return;
         this.texture.destroy();
         this.texture = null;
+        this.effectsTable?.destroy();
+        this.effectsTable = null;
+        this.effectsView = null;
     }
-    upload(source) {
+    upload(sources) {
         const texture = this.texture;
         if (texture === null)
             return;
@@ -259,7 +296,9 @@ 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, flipY: false }, { texture }, [this.width, this.height]);
+        for (let layer = 0; layer < sources.length; layer++) {
+            this.device.queue.copyExternalImageToTexture({ source: sources[layer], flipY: false }, { texture, origin: [0, 0, layer] }, [this.width, this.height]);
+        }
         if (this.levels > 1)
             this.generateMips(texture);
     }
@@ -271,6 +310,6 @@ export class GpuSurfaceTexture {
      * an attachment and a resource at once — rejected, and rejected silently enough to matter.
      */
     generateMips(texture) {
-        generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
+        generateMipChain(this.device, this.pipelines, texture, this.format, this.levels, this.layers);
     }
 }

package/dist/render/driftLight/bake.d.ts

@@ -32,3 +32,10 @@ export interface FieldLight extends LightReach {
  * `distance` is the scene's distance field, or null for no occlusion.
  */
 export declare function bakeBrick(layout: LightFieldLayout, brick: number, lights: readonly FieldLight[], falloff: PointLightFalloff, distance: DistanceAt | null, light: Float32Array, direction: Float32Array): void;
+/**
+ * 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 declare 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;

package/dist/render/driftLight/bake.js

@@ -33,63 +33,68 @@ export function bakeBrick(layout, brick, lights, falloff, distance, light, direc
     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]];
-                    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, py, pz, lights, candidates, first, last, falloff, distance, light, direction, texel) {
+    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]];
+        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;
+    }
+}

package/dist/render/driftLight/denseField.d.ts

@@ -0,0 +1,46 @@
+/**
+ * DriftLight for a whole world: every fixed light summed into one dense grid, baked offline.
+ *
+ * **Dense, where the courtyard field is sparse, because a city is lit nearly everywhere.** A brick
+ * earns its index and its shared faces where light is rare; street lamps reaching thirty metres
+ * forty metres apart leave almost no cell dark, so the sparseness buys nothing and the shared
+ * faces cost 2.4× the samples. At 8 m a sample, a two-kilometre city 128 m tall is 256 × 16 × 256
+ * samples, two half-float texels each: 16 MB on the GPU, and the renderer's lookup is one filtered
+ * fetch for the light and one for its direction.
+ *
+ * **The same sample as every other bake.** `sampleFieldLight` is shared with `bakeBrick`, so a dense
+ * volume and a brick agree bit for bit wherever both have a sample. The order a sample's lights are
+ * summed in does not have to match for that: the sum runs in double precision and is stored in
+ * single, which the last bits of a few terms in another order do not reach.
+ *
+ * **Lights are bucketed first**, four samples a bucket on every axis, so a sample sums only the
+ * lights whose reach touches its bucket rather than all of them: a city of ten thousand lamps is a
+ * few dozen candidates a sample. Offline and allocation-free per sample; it may take seconds.
+ *
+ * What it gives up is resolution: at 8 m a lamp's pool is a few samples across, which is why this
+ * stands in only past the exact lights, where a pool is a few dozen pixels.
+ */
+import type { FieldLight } from './bake.ts';
+import type { PointLightFalloff } from './falloff.ts';
+import type { DistanceAt } from './visibility.ts';
+/** The most samples along x or z: WebGL2 promises 256 on every axis of a 3D texture. */
+export declare const DENSE_MAX_AXIS = 256;
+/** The most along y, which holds the light and then the direction: two layers in 256. */
+export declare const DENSE_MAX_HEIGHT = 128;
+export interface DenseLightVolume {
+    /** The world position of sample (0, 0, 0). */
+    readonly origin: readonly [number, number, number];
+    /** Metres between two samples. */
+    readonly spacing: number;
+    /** Samples on each axis. */
+    readonly dims: readonly [number, number, number];
+    /** Four floats a sample, x fastest then y then z: the colour, then 1 for a sample and 0 inside. */
+    readonly light: Float32Array;
+    /** Four floats a sample: the direction light arrives from, weighted by brightness, then 0. */
+    readonly direction: Float32Array;
+}
+/**
+ * Sum `lights` over the box `bounds` (min xyz, max xyz) at `spacing` metres. `distance` occludes, or
+ * null for none. The first sample stands on the box's min corner.
+ */
+export declare function bakeDenseField(lights: readonly FieldLight[], falloff: PointLightFalloff, distance: DistanceAt | null, bounds: ArrayLike<number>, spacing: number): DenseLightVolume;