@driftengine/core 4.3.0 → 4.4.0

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

@@ -1,5 +1,6 @@
 import { boundsOfPositions, createBounds } from '../../../math/bounds.js';
 import { MorphTexture } from './morphTexture.js';
+import { validateMeshData } from '../../mesh.js';
 import { ABSENT_ATTRIBUTE } from '../../vertexDefaults.js';
 import { UPLOAD_BYTES_PER_STEP } from '../../uploadStep.js';
 import { INSTANCE_STRIDE } from '../../instances.js';
@@ -122,6 +123,11 @@ export function createGpuMesh(device, data, dynamic = false) {
  * bounds were not yet known would not be usable at once, which is the whole promise here.
  */
 export function createGpuMeshIncremental(device, data, dynamic = false) {
+    /*
+     * The other backend's refusal, and the premise of the interleave below: every attribute holds
+     * exactly a vertex's worth for every vertex, so nothing reads past the end of its array.
+     */
+    validateMeshData(data);
     const bounds = boundsOfPositions(data.positions, createBounds());
     const vertexCount = data.positions.length / 3;
     const supplied = VERTEX_LAYOUT.filter((attribute) => !attribute.optional || data[attribute.name] !== undefined);
@@ -264,14 +270,8 @@ function* uploadSteps(job) {
         let fieldOffset = 0;
         for (const attribute of supplied) {
             const source = data[attribute.name];
-            const width = attribute.components;
-            for (let vertex = from; vertex < to; vertex++) {
-                for (let component = 0; component < width; component++) {
-                    interleaved[vertex * step + fieldOffset + component] =
-                        source[vertex * width + component] ?? 0;
-                }
-            }
-            fieldOffset += width;
+            interleaveField(interleaved, source, attribute.components, step, fieldOffset, from, to);
+            fieldOffset += attribute.components;
         }
         device.queue.writeBuffer(vertices, from * stride, interleaved, from * step, (to - from) * step);
         taken += 1;
@@ -291,6 +291,44 @@ function* uploadSteps(job) {
     job.interleaved = null;
     job.progress.uploaded = true;
 }
+/**
+ * One attribute of vertices `from` to `to` into its field of the interleaved rows.
+ *
+ * **Unrolled by width, because the general loop was most of a heavy load's upload.** A loop over
+ * components inside a loop over vertices, with the index recomputed from both, cost 1.5 s of main
+ * thread on a courtyard of five packs; a loop per width walking two cursors does the same writes in
+ * about a third of the time, measured on four million vertices in Node. Every width the layout
+ * carries is one, two, three or four, so the last arm is the one-float case and nothing else.
+ */
+function interleaveField(rows, source, width, step, fieldOffset, from, to) {
+    let write = from * step + fieldOffset;
+    const end = to * width;
+    if (width === 3) {
+        for (let read = from * 3; read < end; read += 3, write += step) {
+            rows[write] = source[read];
+            rows[write + 1] = source[read + 1];
+            rows[write + 2] = source[read + 2];
+        }
+    }
+    else if (width === 4) {
+        for (let read = from * 4; read < end; read += 4, write += step) {
+            rows[write] = source[read];
+            rows[write + 1] = source[read + 1];
+            rows[write + 2] = source[read + 2];
+            rows[write + 3] = source[read + 3];
+        }
+    }
+    else if (width === 2) {
+        for (let read = from * 2; read < end; read += 2, write += step) {
+            rows[write] = source[read];
+            rows[write + 1] = source[read + 1];
+        }
+    }
+    else {
+        for (let read = from; read < end; read++, write += step)
+            rows[write] = source[read];
+    }
+}
 /** The handle, made where it can see only what it hands out. */
 function gpuMeshOf(parts) {
     const { vertices, constants, indexBuffer, progress } = parts;

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

@@ -46,6 +46,71 @@ export declare const DEPTH_VERT_FIELDS: {
 };
 export declare const DEPTH_VERT_SIZE: 160;
 export declare const DEPTH_FRAG_SIZE: 16;
+export declare const DEPTH_CUTOUT_VERT_FIELDS: {
+    readonly uLightViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uModel: {
+        readonly offset: 64;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uWindDirection: {
+        readonly offset: 128;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uWindSpeed: {
+        readonly offset: 136;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindGust: {
+        readonly offset: 140;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindTime: {
+        readonly offset: 144;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uWindSpatialPhase: {
+        readonly offset: 152;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uUvScale: {
+        readonly offset: 160;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uAlphaCutout: {
+        readonly offset: 168;
+        readonly size: 4;
+        readonly type: "float";
+    };
+};
+export declare const DEPTH_CUTOUT_VERT_SIZE: 176;
+export declare const DEPTH_INSTANCED_CUTOUT_VERT_FIELDS: {
+    readonly uLightViewProj: {
+        readonly offset: 0;
+        readonly size: 64;
+        readonly type: "mat4";
+    };
+    readonly uUvScale: {
+        readonly offset: 64;
+        readonly size: 8;
+        readonly type: "vec2";
+    };
+    readonly uAlphaCutout: {
+        readonly offset: 72;
+        readonly size: 4;
+        readonly type: "float";
+    };
+};
 /** Re-exported so the scatter depth pass can pair with the same fragment stage. */
 export { DEPTH_FRAG_WGSL };
 export declare const DEPTH_FRAG_BINDING: 1;
@@ -78,10 +143,21 @@ export declare function createDepthBindGroupLayout(device: GPUDevice,
  * the rigid path is untouched: no extra binding, no one-pixel texture to keep alive, and a
  * frame that skins nothing pays nothing at all.
  */
-skinned?: boolean): GPUBindGroupLayout;
+skinned?: boolean, 
+/**
+ * Whether this layout carries a cutout map, for a caster whose shape is in its texture's alpha.
+ * Separate for the palette's reason: the plain layout stays exactly what it was, and a frame with
+ * no cutout caster pays nothing.
+ */
+cutout?: boolean): GPUBindGroupLayout;
 export declare function createDepthBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perPass: GPUBuffer, previous: GPUTextureView, sampler: GPUSampler, 
 /** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
-palette?: GPUTextureView | null): GPUBindGroup;
+palette?: GPUTextureView | null, 
+/** The cutout map and its sampler, for a layout built with `cutout`. */
+cutout?: {
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+} | null): GPUBindGroup;
 /**
  * The depth pipeline.
  *
@@ -111,4 +187,6 @@ skinned?: boolean,
  * Excludes `skinned`, and the layout is why rather than the shader: an instanced pipeline
  * reclaims the two attribute locations the joint indices and weights occupy.
  */
-instanced?: boolean): GPURenderPipeline;
+instanced?: boolean, 
+/** Whether this pipeline casts a cutout: the variant that reads a map and discards by it. */
+cutout?: boolean): GPURenderPipeline;

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

@@ -1,4 +1,4 @@
-import { DEPTH_BINDINGS, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
+import { DEPTH_BINDINGS, DEPTH_CUTOUT_FRAG_WGSL, DEPTH_CUTOUT_VERT_WGSL, DEPTH_FRAG_WGSL, DEPTH_INSTANCED_CUTOUT_VERT_WGSL, DEPTH_INSTANCED_VERT_WGSL, DEPTH_SKINNED_VERT_WGSL, DEPTH_VERT_WGSL, } from '../../shaders/generated/depth.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
 import { shaderModule } from './shaderModules.js';
 /**
@@ -11,6 +11,15 @@ import { shaderModule } from './shaderModules.js';
 export const DEPTH_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_VERT.fields;
 export const DEPTH_VERT_SIZE = DEPTH_BINDINGS.DEPTH_VERT.uniformSize;
 export const DEPTH_FRAG_SIZE = DEPTH_BINDINGS.DEPTH_FRAG.uniformSize;
+/*
+ * The cutout variants' vertex blocks. The rigid one is the plain block with `uUvScale` and
+ * `uAlphaCutout` after every other field, so a slot written for it is written with the plain
+ * offsets plus these two; the instanced one has no model and no wind, so its two sit earlier.
+ */
+export const DEPTH_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.fields;
+export const DEPTH_CUTOUT_VERT_SIZE = DEPTH_BINDINGS.DEPTH_CUTOUT_VERT.uniformSize;
+export const DEPTH_INSTANCED_CUTOUT_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_INSTANCED_CUTOUT_VERT.fields;
+const CUTOUT_MAP = DEPTH_BINDINGS.DEPTH_CUTOUT_FRAG.textures.uCutoutMap;
 /** Re-exported so the scatter depth pass can pair with the same fragment stage. */
 export { DEPTH_FRAG_WGSL };
 export const DEPTH_FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
@@ -40,9 +49,15 @@ export function createDepthBindGroupLayout(device,
  * the rigid path is untouched: no extra binding, no one-pixel texture to keep alive, and a
  * frame that skins nothing pays nothing at all.
  */
-skinned = false) {
+skinned = false, 
+/**
+ * Whether this layout carries a cutout map, for a caster whose shape is in its texture's alpha.
+ * Separate for the palette's reason: the plain layout stays exactly what it was, and a frame with
+ * no cutout caster pays nothing.
+ */
+cutout = false) {
     return device.createBindGroupLayout({
-        label: skinned ? 'depth.layout.skinned' : 'depth.layout',
+        label: skinned ? 'depth.layout.skinned' : cutout ? 'depth.layout.cutout' : 'depth.layout',
         entries: [
             /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
                coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
@@ -59,7 +74,11 @@ skinned = false) {
             {
                 binding: VERT_BINDING,
                 visibility: VISIBILITY_VERTEX,
-                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: DEPTH_VERT_SIZE },
+                buffer: {
+                    type: 'uniform',
+                    hasDynamicOffset: true,
+                    minBindingSize: cutout ? DEPTH_CUTOUT_VERT_SIZE : DEPTH_VERT_SIZE,
+                },
             },
             {
                 binding: FRAG_BINDING,
@@ -92,21 +111,55 @@ skinned = false) {
                 visibility: VISIBILITY_FRAGMENT,
                 sampler: { type: 'non-filtering' },
             },
+            /* A colour map sampled with its own filter and mips, so a leaf's edge in the map is the edge
+               a colour pass at that distance would draw. */
+            ...(cutout
+                ? [
+                    {
+                        binding: CUTOUT_MAP.texture,
+                        visibility: VISIBILITY_FRAGMENT,
+                        texture: { sampleType: 'float' },
+                    },
+                    {
+                        binding: CUTOUT_MAP.sampler,
+                        visibility: VISIBILITY_FRAGMENT,
+                        sampler: { type: 'filtering' },
+                    },
+                ]
+                : []),
         ],
     });
 }
 export function createDepthBindGroup(device, layout, perDraw, perPass, previous, sampler, 
 /** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
-palette = null) {
+palette = null, 
+/** The cutout map and its sampler, for a layout built with `cutout`. */
+cutout = null) {
     return device.createBindGroup({
-        label: palette === null ? 'depth.bindGroup' : 'depth.bindGroup.skinned',
+        label: palette !== null
+            ? 'depth.bindGroup.skinned'
+            : cutout !== null
+                ? 'depth.bindGroup.cutout'
+                : 'depth.bindGroup',
         layout,
         entries: [
-            { binding: VERT_BINDING, resource: { buffer: perDraw, size: DEPTH_VERT_SIZE } },
+            {
+                binding: VERT_BINDING,
+                resource: {
+                    buffer: perDraw,
+                    size: cutout !== null ? DEPTH_CUTOUT_VERT_SIZE : DEPTH_VERT_SIZE,
+                },
+            },
             { binding: FRAG_BINDING, resource: { buffer: perPass, size: DEPTH_FRAG_SIZE } },
             { binding: PREVIOUS.texture, resource: previous },
             { binding: PREVIOUS.sampler, resource: sampler },
             ...(palette !== null ? [{ binding: DEPTH_PALETTE_BINDING.texture, resource: palette }] : []),
+            ...(cutout !== null
+                ? [
+                    { binding: CUTOUT_MAP.texture, resource: cutout.view },
+                    { binding: CUTOUT_MAP.sampler, resource: cutout.sampler },
+                ]
+                : []),
         ],
     });
 }
@@ -139,21 +192,29 @@ skinned = false,
  * Excludes `skinned`, and the layout is why rather than the shader: an instanced pipeline
  * reclaims the two attribute locations the joint indices and weights occupy.
  */
-instanced = false) {
+instanced = false, 
+/** Whether this pipeline casts a cutout: the variant that reads a map and discards by it. */
+cutout = false) {
     return cache.get(key, () => ({
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
         vertex: {
-            module: shaderModule(device, instanced
-                ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
-                : skinned
-                    ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
-                    : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
+            module: shaderModule(device, cutout
+                ? instanced
+                    ? { label: 'depth.instanced.cutout.vert', code: DEPTH_INSTANCED_CUTOUT_VERT_WGSL }
+                    : { label: 'depth.cutout.vert', code: DEPTH_CUTOUT_VERT_WGSL }
+                : instanced
+                    ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+                    : skinned
+                        ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+                        : { label: 'depth.vert', code: DEPTH_VERT_WGSL }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
         },
         fragment: {
-            module: shaderModule(device, { label: 'depth.frag', code: DEPTH_FRAG_WGSL }),
+            module: shaderModule(device, cutout
+                ? { label: 'depth.cutout.frag', code: DEPTH_CUTOUT_FRAG_WGSL }
+                : { label: 'depth.frag', code: DEPTH_FRAG_WGSL }),
             entryPoint: 'main',
             targets: [],
         },

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

@@ -0,0 +1,39 @@
+import type { PipelineCache } from './pipelineCache.ts';
+export declare class ExposurePass {
+    private readonly device;
+    private readonly pipelines;
+    private readonly sampler;
+    private readonly meter;
+    private readonly meterView;
+    private readonly held;
+    /** The texel the composite binds, for its bind group. */
+    readonly heldView: GPUTextureView;
+    private readonly scratch;
+    private readonly scratchView;
+    private readonly localGrid;
+    /** Local exposure's grid, for the composite's bind group. */
+    readonly localView: GPUTextureView;
+    private readonly localLayout;
+    private localGroup;
+    private localSource;
+    private readonly meterLayout;
+    private readonly adaptLayout;
+    private readonly adaptGroup;
+    private readonly uniforms;
+    private readonly blend;
+    private meterGroup;
+    private meterSource;
+    /** Whether anything is held yet: the first frame, and the first after a cut, snaps. */
+    private holding;
+    constructor(device: GPUDevice, pipelines: PipelineCache, sampler: GPUSampler);
+    /** Forget what is held, so the next frame meters afresh rather than easing from another shot. */
+    cut(): void;
+    /**
+     * Meter `scene` and move the held brightness toward it by `dtSec` of adaptation, and with `local`
+     * draw local exposure's grid too.
+     */
+    run(encoder: GPUCommandEncoder, scene: GPUTextureView, dtSec: number, local?: boolean): void;
+    /** Local exposure's grid, from the same scene the meter read. */
+    private drawLocal;
+    dispose(): void;
+}

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

@@ -0,0 +1,190 @@
+import { EXPOSURE_ADAPT_FRAG_WGSL, EXPOSURE_BINDINGS, EXPOSURE_METER_FRAG_WGSL, } from '../../shaders/generated/exposure.wgsl.js';
+import { EXPOSURE_LOCAL_FRAG_WGSL, LOCALEXPOSURE_BINDINGS, } from '../../shaders/generated/localExposure.wgsl.js';
+import { METER_GRID, adaptBlend } from '../../shaders/exposure.js';
+import { LOCAL_GRID_WIDTH } from '../../shaders/localExposure.js';
+import { createPostStageLayout, postPipeline } from './postPass.js';
+/**
+ * Eye adaptation on WebGPU: meter the finished scene into the frame's own encoder, and follow it
+ * with a held brightness the composite reads. See `shaders/exposure.ts` for the design.
+ *
+ * **One held texel the composite always binds, and a scratch the adaptation writes.** Reading and
+ * writing one texture in a pass is refused, and a pair that swapped roles would mean a composite
+ * bind group per role; so the adaptation writes the scratch from the held value and a copy puts it
+ * back, on the same encoder, before the composite reads it. Recorded into the frame's encoder
+ * rather than submitted apart, because a separate submission would run before the frame that
+ * draws the scene it is meant to measure.
+ *
+ * **And local exposure's grid, when that is asked for**, in the same encoder after the meter:
+ * `rg16float`, a sum and a count per tile per band, sampled filtered by the composite. See
+ * `localExposure.ts`.
+ */
+const METER = EXPOSURE_BINDINGS.EXPOSURE_METER_FRAG.textures;
+const ADAPT = EXPOSURE_BINDINGS.EXPOSURE_ADAPT_FRAG;
+const LOCAL = LOCALEXPOSURE_BINDINGS.EXPOSURE_LOCAL_FRAG.textures;
+const USAGE_RENDER = 0x10;
+const USAGE_TEXTURE = 0x04;
+const USAGE_COPY_SRC = 0x01;
+const USAGE_COPY_DST = 0x02;
+const USAGE_UNIFORM_DST = 0x40 | 0x08;
+const VISIBILITY_FRAGMENT = 0x2;
+export class ExposurePass {
+    device;
+    pipelines;
+    sampler;
+    meter;
+    meterView;
+    held;
+    /** The texel the composite binds, for its bind group. */
+    heldView;
+    scratch;
+    scratchView;
+    localGrid;
+    /** Local exposure's grid, for the composite's bind group. */
+    localView;
+    localLayout;
+    localGroup = null;
+    localSource = null;
+    meterLayout;
+    adaptLayout;
+    adaptGroup;
+    uniforms;
+    blend = new Float32Array(4);
+    meterGroup = null;
+    meterSource = null;
+    /** Whether anything is held yet: the first frame, and the first after a cut, snaps. */
+    holding = false;
+    constructor(device, pipelines, sampler) {
+        this.device = device;
+        this.pipelines = pipelines;
+        this.sampler = sampler;
+        const target = (label, size, usage) => device.createTexture({ label, size: [size, size], format: 'r16float', usage });
+        this.meter = target('exposure.meter', METER_GRID, USAGE_RENDER | USAGE_TEXTURE);
+        this.held = target('exposure.held', 1, USAGE_RENDER | USAGE_TEXTURE | USAGE_COPY_DST);
+        this.scratch = target('exposure.scratch', 1, USAGE_RENDER | USAGE_COPY_SRC);
+        this.localGrid = device.createTexture({
+            label: 'exposure.localGrid',
+            size: [LOCAL_GRID_WIDTH, METER_GRID],
+            format: 'rg16float',
+            usage: USAGE_RENDER | USAGE_TEXTURE,
+        });
+        this.localView = this.localGrid.createView();
+        this.meterView = this.meter.createView();
+        this.heldView = this.held.createView();
+        this.scratchView = this.scratch.createView();
+        /* The meter has no uniforms, so its layout is its one texture and sampler and nothing else. */
+        this.meterLayout = device.createBindGroupLayout({
+            label: 'exposure.meterLayout',
+            entries: [
+                { binding: METER.uScene.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+                { binding: METER.uScene.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+            ],
+        });
+        this.localLayout = device.createBindGroupLayout({
+            label: 'exposure.localLayout',
+            entries: [
+                { binding: LOCAL.uScene.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+                { binding: LOCAL.uScene.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+            ],
+        });
+        this.adaptLayout = createPostStageLayout(device, ADAPT.uniforms, ADAPT.uniformSize, [
+            { binding: ADAPT.textures.uMeter },
+            { binding: ADAPT.textures.uHeld },
+        ]);
+        this.uniforms = device.createBuffer({
+            label: 'exposure.uniforms',
+            size: ADAPT.uniformSize,
+            usage: USAGE_UNIFORM_DST,
+        });
+        this.adaptGroup = device.createBindGroup({
+            label: 'exposure.adaptGroup',
+            layout: this.adaptLayout,
+            entries: [
+                { binding: ADAPT.uniforms, resource: { buffer: this.uniforms, size: ADAPT.uniformSize } },
+                { binding: ADAPT.textures.uMeter.texture, resource: this.meterView },
+                { binding: ADAPT.textures.uMeter.sampler, resource: sampler },
+                { binding: ADAPT.textures.uHeld.texture, resource: this.heldView },
+                { binding: ADAPT.textures.uHeld.sampler, resource: sampler },
+            ],
+        });
+    }
+    /** Forget what is held, so the next frame meters afresh rather than easing from another shot. */
+    cut() {
+        this.holding = false;
+    }
+    /**
+     * Meter `scene` and move the held brightness toward it by `dtSec` of adaptation, and with `local`
+     * draw local exposure's grid too.
+     */
+    run(encoder, scene, dtSec, local = false) {
+        const { device } = this;
+        if (this.meterSource !== scene || this.meterGroup === null) {
+            this.meterGroup = device.createBindGroup({
+                label: 'exposure.meterGroup',
+                layout: this.meterLayout,
+                entries: [
+                    { binding: METER.uScene.texture, resource: scene },
+                    { binding: METER.uScene.sampler, resource: this.sampler },
+                ],
+            });
+            this.meterSource = scene;
+        }
+        this.blend[0] = adaptBlend(dtSec, !this.holding);
+        device.queue.writeBuffer(this.uniforms, 0, this.blend);
+        const meter = encoder.beginRenderPass({
+            label: 'exposure.meter',
+            colorAttachments: [
+                { view: this.meterView, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+        });
+        meter.setPipeline(postPipeline(this.pipelines, device, this.meterLayout, 'exposure.meter', EXPOSURE_METER_FRAG_WGSL, 'r16float'));
+        meter.setBindGroup(0, this.meterGroup);
+        meter.draw(3);
+        meter.end();
+        if (local)
+            this.drawLocal(encoder, scene);
+        const adapt = encoder.beginRenderPass({
+            label: 'exposure.adapt',
+            colorAttachments: [
+                { view: this.scratchView, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+        });
+        adapt.setPipeline(postPipeline(this.pipelines, device, this.adaptLayout, 'exposure.adapt', EXPOSURE_ADAPT_FRAG_WGSL, 'r16float'));
+        adapt.setBindGroup(0, this.adaptGroup, [0]);
+        adapt.draw(3);
+        adapt.end();
+        encoder.copyTextureToTexture({ texture: this.scratch }, { texture: this.held }, [1, 1, 1]);
+        this.holding = true;
+    }
+    /** Local exposure's grid, from the same scene the meter read. */
+    drawLocal(encoder, scene) {
+        const { device } = this;
+        if (this.localSource !== scene || this.localGroup === null) {
+            this.localGroup = device.createBindGroup({
+                label: 'exposure.localGroup',
+                layout: this.localLayout,
+                entries: [
+                    { binding: LOCAL.uScene.texture, resource: scene },
+                    { binding: LOCAL.uScene.sampler, resource: this.sampler },
+                ],
+            });
+            this.localSource = scene;
+        }
+        const pass = encoder.beginRenderPass({
+            label: 'exposure.local',
+            colorAttachments: [
+                { view: this.localView, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+        });
+        pass.setPipeline(postPipeline(this.pipelines, device, this.localLayout, 'exposure.local', EXPOSURE_LOCAL_FRAG_WGSL, 'rg16float'));
+        pass.setBindGroup(0, this.localGroup);
+        pass.draw(3);
+        pass.end();
+    }
+    dispose() {
+        this.localGrid.destroy();
+        this.meter.destroy();
+        this.held.destroy();
+        this.scratch.destroy();
+        this.uniforms.destroy();
+    }
+}

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

@@ -39,6 +39,15 @@ export type ComposedField = PassDistanceField;
  * which the chain's probe level answers and never declines.
  */
 export declare const DEFAULT_FIELD_COMPOSE: FieldComposeOptions;
+/**
+ * The most cascades a field is given to reach a probe grid, which is `cascadesForGrid`'s ceiling.
+ *
+ * Six from the 4 m default reach 128 m, and each is the same 49 cubed samples, about half a
+ * megabyte, so the bound is on memory rather than on distance. What would make it wrong is a scene
+ * whose probe grid is longer than about a hundred metres, whose far probes are then left untraced
+ * rather than traced against a field that is not there.
+ */
+export declare const MAX_FIELD_CASCADES = 6;
 export interface FieldComposeOptions {
     /** Samples a side, every cascade. */
     readonly resolution: number;
@@ -106,6 +115,8 @@ export declare class FieldComposer {
     private queryMapping;
     private timed;
     private composeMsValue;
+    /** How many cascades this composer was built with. */
+    get cascadeCount(): number;
     constructor(device: GPUDevice, options: FieldComposeOptions);
     /** One bind group a cascade. Rebuilt whenever the source buffer is replaced by a larger one. */
     private rebuildGroups;

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

@@ -41,6 +41,15 @@ export const DEFAULT_FIELD_COMPOSE = {
     cascades: 3,
     radius: 4,
 };
+/**
+ * The most cascades a field is given to reach a probe grid, which is `cascadesForGrid`'s ceiling.
+ *
+ * Six from the 4 m default reach 128 m, and each is the same 49 cubed samples, about half a
+ * megabyte, so the bound is on memory rather than on distance. What would make it wrong is a scene
+ * whose probe grid is longer than about a hundred metres, whose far probes are then left untraced
+ * rather than traced against a field that is not there.
+ */
+export const MAX_FIELD_CASCADES = 6;
 export class FieldComposer {
     options;
     samples;
@@ -101,6 +110,10 @@ export class FieldComposer {
     queryMapping = false;
     timed = false;
     composeMsValue = 0;
+    /** How many cascades this composer was built with. */
+    get cascadeCount() {
+        return this.options.cascades;
+    }
     constructor(device, options) {
         if (!(Math.trunc(options.resolution) >= 2)) {
             throw new Error(`FieldComposer: resolution is ${String(options.resolution)}; the minimum is 2.`);

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

@@ -194,7 +194,9 @@ depthWrite?: boolean, depthLayer?: number,
 /** Whether placement and tint arrive per instance. See `FlatVertexOptions`. */
 instanced?: boolean, 
 /** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
-oit?: OitTarget): GPURenderPipeline;
+oit?: OitTarget, 
+/** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
+doubleSided?: boolean): GPURenderPipeline;
 /**
  * The same pipeline, compiled off the main thread.
  *