@driftengine/core 3.63.0 → 4.0.0

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

@@ -0,0 +1,396 @@
+/**
+ * The world's distance field, composed on the device from what the frame declared.
+ *
+ * **Extracted from `GiFieldPass` rather than written beside it**, because two copies of this
+ * arithmetic is exactly the hazard `composeField.wgsl.ts` opens by naming: a shader and a
+ * TypeScript function cannot import a struct from each other, so every restatement of the layout
+ * is a place the two can drift. There was already one restatement — the reference and the shader,
+ * which `scripts/gi-parity.mjs` holds together. A third, in a renderer that composed its own field
+ * while a contributed pass composed another, would be one nothing checks.
+ *
+ * **What changed from the pass is where the instances come from.** `GiFieldPass` took them in its
+ * constructor and uploaded them once at `init`, which is right for a rig whose scene is fixed and
+ * wrong for a renderer whose consumer declares its fields every frame. Here the instances arrive
+ * in a `DistanceFieldScene`, the instance count reaches the shader through the params, and the
+ * samples live in a buffer that grows to fit the scene and is never reallocated by a steady one.
+ *
+ * **The samples are uploaded only when the packing changed.** A field is megabytes and a placement
+ * is bytes; a composer that rewrote the samples every frame would move the whole world across the
+ * bus to say what it said last frame. `DistanceFieldScene.packingChanged` is what knows.
+ */
+import { placeCascade } from '../../gi/globalField.js';
+import { MAX_DISTANCE_FIELDS } from '../../gi/fieldScene.js';
+import { COMPOSE_FIELD_WGSL, COMPOSE_INSTANCE_FLOATS, COMPOSE_OUTPUT_BASE, COMPOSE_PARAM_FLOATS, COMPOSE_PARAM_STRIDE, COMPOSE_WORKGROUP, INSTANCE_ALBEDO, INSTANCE_BOUNDS, INSTANCE_DIMS, INSTANCE_OFFSET, INSTANCE_SCALE, } from '../../shaders/gi/composeField.wgsl.js';
+import { CASCADE_FLOATS } from '../../shaders/gi/sampleField.wgsl.js';
+const COPY_SRC = 0x0004;
+const COPY_DST = 0x0008;
+const STORAGE = 0x0080;
+const QUERY_RESOLVE = 0x0200;
+const MAP_READ = 0x0001;
+/**
+ * What the renderer composes with when a consumer only said `quality.indirectLight`.
+ *
+ * **Three cascades of 49, four metres at the innermost**, which is `demo/giFieldRig.ts`'s
+ * measurement and its reasoning: 49 rather than 33 puts the innermost cascade's step at 16.7 cm
+ * rather than 25, the difference between a 1.1 m object having six samples across it and four.
+ * The three together are 1.4 MB on the device, and the outermost reaches sixteen metres — beyond
+ * which the chain's probe level answers and never declines.
+ */
+export const DEFAULT_FIELD_COMPOSE = {
+    resolution: 49,
+    cascades: 3,
+    radius: 4,
+};
+export class FieldComposer {
+    options;
+    samples;
+    /** The cascade geometry, kept on the CPU because `placeCascade` is what decides it. */
+    cascades = [];
+    device;
+    pipeline;
+    /** One a cascade, each binding that cascade's own params at its own aligned offset. */
+    groups = [];
+    paramBuffer;
+    instanceBuffer;
+    fieldBuffer;
+    /** The colour of whatever won the union at each sample, three floats. */
+    albedoBuffer;
+    /**
+     * Where each cascade stands, as the field's readers see it: moved by a copy encoded after the
+     * composition, never written by the queue. See `cascadeStaged`.
+     */
+    cascadeBuffer;
+    /**
+     * **This frame's bounds, on their way to `cascadeBuffer`.** A queue write lands when it is made
+     * and an encoded command when its command buffer runs, and a reader of the field — the march in
+     * a contributed pass's `prepare` — is encoded before the composition. Written straight into the
+     * buffer readers bind, the bounds arrived a frame ahead of the samples they describe, and every
+     * frame a cascade stepped the field was read one voxel off. Staged here and copied after the
+     * composition's dispatches, a reader before them sees last frame's bounds with last frame's
+     * samples and a reader after them sees this frame's with this frame's.
+     */
+    cascadeStaged;
+    /**
+     * The declared sources' samples, grown to fit rather than allocated at the budget.
+     *
+     * **The budget is a ceiling and not a size.** `MAX_DISTANCE_FIELD_SAMPLES` is sixteen megabytes;
+     * a scene with two 33-cubed fields wants two hundred and eighty kilobytes, and a renderer that
+     * reserved the ceiling would charge every consumer for the largest one imaginable. It grows when
+     * a frame declares more than it holds and never shrinks, so a scene that cycles between two sets
+     * of fields settles rather than reallocating.
+     */
+    sourceBuffer;
+    sourceFloats = 0;
+    paramScratch = new Float32Array(COMPOSE_PARAM_FLOATS);
+    cascadeScratch;
+    instanceScratch = new Float32Array(MAX_DISTANCE_FIELDS * COMPOSE_INSTANCE_FLOATS);
+    outerBounds = new Float32Array(6);
+    /** False until a frame has actually composed something, so a reader knows not to trace. */
+    composed = false;
+    /**
+     * The device's own clock around the dispatch, where it has one.
+     *
+     * **Moved here from `GiFieldPass` with the dispatch it measures.** A timestamp belongs beside
+     * the work, and this is now the only place the world's field is composed — so the figure a rig
+     * reports is the figure the renderer actually pays rather than a second composition's.
+     */
+    queries = null;
+    queryResolve = null;
+    queryRead = null;
+    queryCopied = false;
+    queryMapping = false;
+    timed = false;
+    composeMsValue = 0;
+    constructor(device, options) {
+        if (!(Math.trunc(options.resolution) >= 2)) {
+            throw new Error(`FieldComposer: resolution is ${String(options.resolution)}; the minimum is 2.`);
+        }
+        if (!(Math.trunc(options.cascades) >= 1)) {
+            throw new Error(`FieldComposer: cascade count is ${String(options.cascades)}; the minimum is 1.`);
+        }
+        if (!(options.radius > 0)) {
+            throw new Error(`FieldComposer: radius is ${String(options.radius)} and must be positive.`);
+        }
+        this.device = device;
+        this.options = options;
+        this.samples = Math.trunc(options.resolution) ** 3;
+        for (let level = 0; level < Math.trunc(options.cascades); level += 1) {
+            this.cascades.push({
+                /* Empty on the CPU: the samples live on the device and are never read back. */
+                field: new Float32Array(0),
+                albedo: new Float32Array(0),
+                dims: [options.resolution, options.resolution, options.resolution],
+                bounds: new Float32Array(6),
+                step: 0,
+            });
+        }
+        this.cascadeScratch = new Float32Array(this.cascades.length * CASCADE_FLOATS);
+        /* One float, grown at the first frame that declares a source. See `sourceBuffer`. */
+        this.sourceBuffer = this.storage('sources', 4);
+        this.instanceBuffer = this.storage('instances', this.instanceScratch.byteLength);
+        this.cascadeBuffer = this.storage('cascades', this.cascadeScratch.byteLength);
+        this.cascadeStaged = device.createBuffer({
+            label: 'gi-field cascades, staged',
+            size: Math.max(4, this.cascadeScratch.byteLength),
+            usage: COPY_SRC | COPY_DST,
+        });
+        this.paramBuffer = this.storage('params', this.cascades.length * COMPOSE_PARAM_STRIDE);
+        this.fieldBuffer = this.storage('samples', this.samples * this.cascades.length * 4);
+        this.albedoBuffer = this.storage('albedo', this.samples * this.cascades.length * 3 * 4);
+        const module = device.createShaderModule({ label: 'gi compose', code: COMPOSE_FIELD_WGSL });
+        this.pipeline = device.createComputePipeline({
+            label: 'gi compose',
+            layout: 'auto',
+            compute: { module, entryPoint: 'main' },
+        });
+        this.rebuildGroups();
+        if (device.features.has('timestamp-query')) {
+            this.queries = device.createQuerySet({
+                label: 'gi-field timings',
+                type: 'timestamp',
+                count: 2,
+            });
+            this.queryResolve = device.createBuffer({
+                label: 'gi-field timings resolve',
+                size: 16,
+                usage: QUERY_RESOLVE | COPY_SRC,
+            });
+            this.queryRead = device.createBuffer({
+                label: 'gi-field timings read',
+                size: 16,
+                usage: COPY_DST | MAP_READ,
+            });
+        }
+    }
+    /** One bind group a cascade. Rebuilt whenever the source buffer is replaced by a larger one. */
+    rebuildGroups() {
+        const layout = this.pipeline.getBindGroupLayout(0);
+        this.groups = this.cascades.map((_, level) => this.device.createBindGroup({
+            label: `gi compose ${String(level)}`,
+            layout,
+            entries: [
+                {
+                    binding: 0,
+                    resource: {
+                        buffer: this.paramBuffer,
+                        offset: level * COMPOSE_PARAM_STRIDE,
+                        size: COMPOSE_PARAM_FLOATS * 4,
+                    },
+                },
+                { binding: 1, resource: { buffer: this.instanceBuffer } },
+                { binding: 2, resource: { buffer: this.sourceBuffer } },
+                { binding: 3, resource: { buffer: this.fieldBuffer } },
+                { binding: 4, resource: { buffer: this.albedoBuffer } },
+            ],
+        }));
+    }
+    /**
+     * Make room for `floats` of samples, replacing the buffer and its bind groups if it is short.
+     *
+     * **Grown to exactly what is asked rather than doubled.** A doubling policy is for something
+     * appended to; this is rewritten whole whenever the packing changes, and the sizes involved are
+     * a scene's whole set of baked fields — a quantity that changes when the world does and not
+     * between frames of a steady one.
+     */
+    ensureSources(floats) {
+        if (floats <= this.sourceFloats)
+            return;
+        this.sourceBuffer.destroy();
+        this.sourceBuffer = this.storage('sources', floats * 4);
+        this.sourceFloats = floats;
+        this.rebuildGroups();
+    }
+    storage(label, bytes) {
+        return this.device.createBuffer({
+            label: `gi-field ${label}`,
+            size: Math.max(4, bytes),
+            usage: STORAGE | COPY_DST,
+        });
+    }
+    /** The composed field, or null until a frame has composed one. */
+    get field() {
+        if (!this.composed)
+            return null;
+        return {
+            samples: this.fieldBuffer,
+            albedo: this.albedoBuffer,
+            cascades: this.cascadeBuffer,
+            levels: this.cascades.length,
+            side: Math.trunc(this.options.resolution),
+            finestStep: this.cascades[0].step,
+            outerBounds: this.outerBounds,
+        };
+    }
+    /**
+     * Compose every cascade from what the frame declared, centred on the eye.
+     *
+     * One dispatch a cascade rather than one for all of them: each has its own origin and step, and
+     * a single dispatch would carry them in a buffer indexed by the invocation's own cascade — a
+     * divide and a dependent read per thread to save a handful of dispatches.
+     *
+     * **A frame that declared nothing composes nothing and says so.** An empty instance list would
+     * otherwise fill every cascade with the "no surface anywhere" value, which a march reads as an
+     * infinite empty room — a ray that travels its whole reach and reports a miss. That is the right
+     * answer, but it costs a full dispatch to write it and the field it produces was already there.
+     */
+    compose(encoder, scene, eye) {
+        if (scene.length === 0) {
+            this.composed = false;
+            return;
+        }
+        const queue = this.device.queue;
+        /*
+         * **The samples only when the packing changed.** Sixteen megabytes a frame to say what it said
+         * last frame is the upload this flag exists to avoid; `DistanceFieldScene` is what knows,
+         * because it is what assigns the offsets and they are positional.
+         */
+        this.ensureSources(scene.sampleCount);
+        if (scene.packingChanged) {
+            /* Each source straight to its own offset: no staging copy, and no gap between them. */
+            for (const source of scene.sources) {
+                queue.writeBuffer(this.sourceBuffer, scene.offsetOf(source) * 4, source.field);
+            }
+        }
+        let at = 0;
+        scene.replay((instance) => {
+            const base = at * COMPOSE_INSTANCE_FLOATS;
+            writeInverse(instance.transform, this.instanceScratch, base);
+            this.instanceScratch[base + INSTANCE_SCALE] = Math.hypot(instance.transform[0] ?? 0, instance.transform[1] ?? 0, instance.transform[2] ?? 0);
+            this.instanceScratch.set(instance.source.bounds, base + INSTANCE_BOUNDS);
+            this.instanceScratch[base + INSTANCE_DIMS] = instance.source.dims[0];
+            this.instanceScratch[base + INSTANCE_DIMS + 1] = instance.source.dims[1];
+            this.instanceScratch[base + INSTANCE_DIMS + 2] = instance.source.dims[2];
+            this.instanceScratch[base + INSTANCE_OFFSET] = scene.offsetOf(instance.source);
+            this.instanceScratch[base + INSTANCE_ALBEDO] = instance.albedo[0];
+            this.instanceScratch[base + INSTANCE_ALBEDO + 1] = instance.albedo[1];
+            this.instanceScratch[base + INSTANCE_ALBEDO + 2] = instance.albedo[2];
+            at += 1;
+        });
+        queue.writeBuffer(this.instanceBuffer, 0, this.instanceScratch, 0, at * COMPOSE_INSTANCE_FLOATS);
+        /* Where the cascades stand this frame. `placeCascade` is shared with the reference. */
+        for (let level = 0; level < this.cascades.length; level += 1) {
+            const cascade = this.cascades[level];
+            placeCascade(cascade, level, this.options.radius, eye);
+            const slot = level * CASCADE_FLOATS;
+            this.cascadeScratch.set(cascade.bounds, slot);
+            this.cascadeScratch[slot + 6] = cascade.step;
+        }
+        queue.writeBuffer(this.cascadeStaged, 0, this.cascadeScratch);
+        this.outerBounds.set(this.cascades[this.cascades.length - 1].bounds);
+        /*
+         * **Every cascade's params written before the pass opens, each at its own offset.**
+         * `queue.writeBuffer` is a queue operation and is not ordered against an encoder's commands,
+         * so rewriting one region between dispatches would give all of them the last write — every
+         * cascade composed with the outermost one's origin and step.
+         */
+        for (let level = 0; level < this.cascades.length; level += 1) {
+            const cascade = this.cascades[level];
+            this.paramScratch[0] = cascade.bounds[0];
+            this.paramScratch[1] = cascade.bounds[1];
+            this.paramScratch[2] = cascade.bounds[2];
+            this.paramScratch[3] = cascade.step;
+            this.paramScratch[4] = this.options.resolution;
+            this.paramScratch[5] = this.options.resolution;
+            this.paramScratch[6] = this.options.resolution;
+            /* The reach, which is the cascade's half-extent. `composeGlobalField` fills with the same. */
+            this.paramScratch[7] = (cascade.bounds[3] - cascade.bounds[0]) / 2;
+            this.paramScratch[8] = at;
+            this.paramScratch[COMPOSE_OUTPUT_BASE] = level * this.samples;
+            queue.writeBuffer(this.paramBuffer, level * COMPOSE_PARAM_STRIDE, this.paramScratch);
+        }
+        const pass = encoder.beginComputePass({
+            label: 'gi compose',
+            timestampWrites: this.queries === null
+                ? undefined
+                : { querySet: this.queries, beginningOfPassWriteIndex: 0, endOfPassWriteIndex: 1 },
+        });
+        pass.setPipeline(this.pipeline);
+        for (let level = 0; level < this.cascades.length; level += 1) {
+            pass.setBindGroup(0, this.groups[level]);
+            pass.dispatchWorkgroups(Math.ceil(this.samples / COMPOSE_WORKGROUP), 1, 1);
+        }
+        pass.end();
+        /* The bounds reach readers here, in step with the samples just written. See `cascadeStaged`. */
+        encoder.copyBufferToBuffer(this.cascadeStaged, 0, this.cascadeBuffer, 0, this.cascadeScratch.byteLength);
+        this.composed = true;
+        if (this.queries !== null && this.queryResolve !== null && this.queryRead !== null) {
+            if (!this.queryCopied && !this.queryMapping) {
+                encoder.resolveQuerySet(this.queries, 0, 2, this.queryResolve, 0);
+                encoder.copyBufferToBuffer(this.queryResolve, 0, this.queryRead, 0, 16);
+                this.queryCopied = true;
+            }
+        }
+    }
+    /**
+     * The device milliseconds the last measured composition took, or null where nothing measured it.
+     *
+     * One frame behind, because a timestamp is read back and a readback that blocked would be the
+     * measurement changing what it measures.
+     */
+    get composeMs() {
+        return this.timed ? this.composeMsValue : null;
+    }
+    /** Ask for the last frame's figure, once the frame that recorded it has been submitted. */
+    readTimings() {
+        if (this.queryRead === null || !this.queryCopied || this.queryMapping)
+            return;
+        this.queryMapping = true;
+        const buffer = this.queryRead;
+        void buffer
+            .mapAsync(MAP_READ)
+            .then(() => {
+            const stamps = new BigUint64Array(buffer.getMappedRange().slice(0));
+            buffer.unmap();
+            const from = stamps[0] ?? 0n;
+            const to = stamps[1] ?? 0n;
+            /* Nanoseconds, and a pair that never ran reads zero rather than a negative span. */
+            this.composeMsValue = to > from ? Number(to - from) / 1e6 : 0;
+            this.timed = true;
+        })
+            .catch(() => {
+            /* A device that will not map its own query buffer reports no timing and composes anyway. */
+        })
+            .finally(() => {
+            this.queryMapping = false;
+            this.queryCopied = false;
+        });
+    }
+    dispose() {
+        this.paramBuffer.destroy();
+        this.instanceBuffer.destroy();
+        this.sourceBuffer.destroy();
+        this.fieldBuffer.destroy();
+        this.albedoBuffer.destroy();
+        this.cascadeBuffer.destroy();
+        this.cascadeStaged.destroy();
+        this.queryResolve?.destroy();
+        this.queryRead?.destroy();
+        this.queries?.destroy();
+    }
+}
+/**
+ * The inverse of a rigid transform with a uniform scale, written into `out` at `at`.
+ *
+ * **Not a general inverse**, because `composeGlobalField` refuses anything else: a distance is not
+ * preserved by a non-uniform scale and there is no factor to correct one by. Transposing the
+ * rotation and dividing by the scale squared is exact for what is allowed, and a general inverse
+ * here would be a fourth spelling of a constraint stated three times already.
+ */
+export function writeInverse(m, out, at) {
+    const scale = Math.hypot(m[0] ?? 0, m[1] ?? 0, m[2] ?? 0);
+    const inverse = scale > 0 ? 1 / (scale * scale) : 0;
+    for (let row = 0; row < 3; row += 1) {
+        for (let col = 0; col < 3; col += 1) {
+            out[at + col * 4 + row] = (m[row * 4 + col] ?? 0) * inverse;
+        }
+    }
+    for (let row = 0; row < 3; row += 1) {
+        out[at + 12 + row] = -(out[at + row] * (m[12] ?? 0) +
+            out[at + 4 + row] * (m[13] ?? 0) +
+            out[at + 8 + row] * (m[14] ?? 0));
+    }
+    out[at + 3] = 0;
+    out[at + 7] = 0;
+    out[at + 11] = 0;
+    out[at + 15] = 1;
+}

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

@@ -0,0 +1,66 @@
+/** The renderer's distance field, marched into the frame so it can be looked at. */
+import type { ReadonlyMat4, ReadonlyVec3 } from 'gl-matrix';
+import type { PassContext, PassDefinition, PassDevice, PrepareContext } from '../../pass.ts';
+/**
+ * **It no longer composes the field, and that is the whole of what changed on 2026-09-18.**
+ *
+ * This pass used to take a list of instances, compose the world's distance field from them and
+ * march the result. It was the only thing in the engine that composed a field at all — which meant
+ * the *renderer* had none, and the indirect-light plan had four tasks written on the assumption
+ * that it did. The lesson is in `CONTRIBUTING.md`, under auditing a closed plan: grep for who
+ * calls a thing, not only for whether it exists.
+ *
+ * The composition now belongs to the renderer, from what a consumer declares with
+ * `addDistanceField`, and this marches what the renderer composed. So there is one field in a
+ * frame rather than two, and what this draws is the field the indirect light actually traces
+ * — which is the only thing that makes the picture worth looking at.
+ *
+ * **What `draw` does is a visualisation, and that is deliberate.** A distance field is a thing you
+ * can look at, and looking is what a number cannot replace: if the geometry is in the right places
+ * at the right sizes the composition is right, and if a cascade boundary shows as a seam the fade
+ * is wrong. Wave 4A's own recorded failure — a phantom surface that passed 111,907 parity samples
+ * and was found by looking at a picture — is why this exists at all.
+ *
+ * **The field it marches is one frame old**, because the renderer composes at `endFrame` and
+ * `prepare` runs at `beginFrame`. `PrepareContext.distanceField` says why that is right rather
+ * than merely what happens.
+ */
+export interface GiFieldOptions {
+    /** How many steps a marched ray may take before it gives up. */
+    readonly marchSteps?: number;
+}
+export declare class GiFieldPass implements PassDefinition {
+    readonly label = "driftengine.gi-field";
+    private readonly marchSteps;
+    private device;
+    private pipeline;
+    private group;
+    private params;
+    /** The field the current bind group was built against, so a replaced buffer is noticed. */
+    private boundTo;
+    private readonly scratch;
+    private readonly eye;
+    constructor(options?: GiFieldOptions);
+    /**
+     * Where the camera is and how to unproject from it, for this frame.
+     *
+     * **Taken rather than derived**, which is the contributed-pass contract: a pass gets its camera
+     * from its caller and never sees the renderer's. `invViewProj` is column-major, as `gl-matrix`
+     * stores one, and a caller that inverts the same matrix it drew the scene with gets rays that
+     * land on the same pixels.
+     */
+    setView(eye: ReadonlyVec3, invViewProj: ReadonlyMat4): void;
+    init(device: PassDevice): void;
+    /**
+     * Bind whatever field the renderer composed, and tell the march where to look.
+     *
+     * **The bind group is rebuilt only when the field it was built against is a different object.**
+     * The renderer replaces its samples buffer when a scene's fields grow, and a group holding a
+     * destroyed buffer is a validation error at the next draw rather than a wrong picture — but
+     * rebuilding one every frame is the per-frame allocation the house rules are about.
+     */
+    prepare(ctx: PrepareContext): void;
+    /** March the field into the frame. Nothing is written where the ray found nothing. */
+    draw(ctx: PassContext): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,137 @@
+/** The renderer's distance field, marched into the frame so it can be looked at. */
+import { MARCH_EPSILON, MARCH_EYE, MARCH_FIELD_WGSL, MARCH_INV_VIEW_PROJ, MARCH_LEVELS, MARCH_PARAM_FLOATS, MARCH_SIDE, MARCH_STEPS, } from '../../shaders/gi/marchField.wgsl.js';
+const COPY_DST = 0x0008;
+const STORAGE = 0x0080;
+const DEFAULT_MARCH_STEPS = 96;
+export class GiFieldPass {
+    label = 'driftengine.gi-field';
+    marchSteps;
+    device = null;
+    pipeline = null;
+    group = null;
+    params = null;
+    /** The field the current bind group was built against, so a replaced buffer is noticed. */
+    boundTo = null;
+    scratch = new Float32Array(MARCH_PARAM_FLOATS);
+    eye = [0, 0, 0];
+    constructor(options = {}) {
+        this.marchSteps = options.marchSteps ?? DEFAULT_MARCH_STEPS;
+    }
+    /**
+     * Where the camera is and how to unproject from it, for this frame.
+     *
+     * **Taken rather than derived**, which is the contributed-pass contract: a pass gets its camera
+     * from its caller and never sees the renderer's. `invViewProj` is column-major, as `gl-matrix`
+     * stores one, and a caller that inverts the same matrix it drew the scene with gets rays that
+     * land on the same pixels.
+     */
+    setView(eye, invViewProj) {
+        this.eye[0] = eye[0] ?? 0;
+        this.eye[1] = eye[1] ?? 0;
+        this.eye[2] = eye[2] ?? 0;
+        for (let at = 0; at < 16; at += 1) {
+            this.scratch[MARCH_INV_VIEW_PROJ + at] = invViewProj[at] ?? 0;
+        }
+    }
+    init(device) {
+        if (device.backend !== 'webgpu') {
+            /*
+             * Loud at registration rather than silent at the first frame. Marching a distance field
+             * means having one, and the field is composed by compute that WebGL2 does not have — the
+             * same refusal `INDIRECT_LIGHT_WEBGL2_REFUSAL` makes, arriving at the seam where a consumer
+             * can act on it.
+             */
+            throw new Error('[driftengine] the global illumination field needs compute and this backend is WebGL2. ' +
+                'Ask for WebGPU, or leave the field unregistered; nothing else in the frame depends on it.');
+        }
+        const gpu = device.device;
+        this.device = gpu;
+        this.params = gpu.createBuffer({
+            label: 'gi-field march params',
+            size: this.scratch.byteLength,
+            usage: STORAGE | COPY_DST,
+        });
+        const march = gpu.createShaderModule({ label: 'gi march', code: MARCH_FIELD_WGSL });
+        this.pipeline = gpu.createRenderPipeline({
+            label: 'gi march',
+            layout: 'auto',
+            vertex: { module: march, entryPoint: 'vertexMain' },
+            fragment: {
+                module: march,
+                entryPoint: 'fragmentMain',
+                targets: [{ format: device.format }],
+            },
+            primitive: { topology: 'triangle-list' },
+            /*
+             * **Depth tested against the frame's own attachment and not written to.** The field is drawn
+             * where nothing else did, so geometry in front of it hides it; writing depth would make a
+             * visualisation occlude the scene it is standing in for. `PassDevice.depthFormat` exists for
+             * exactly this and was missing for as long as nobody depth-tested through this seam.
+             */
+            depthStencil: {
+                format: device.depthFormat,
+                depthWriteEnabled: false,
+                depthCompare: 'always',
+            },
+            multisample: { count: device.samples },
+        });
+    }
+    /**
+     * Bind whatever field the renderer composed, and tell the march where to look.
+     *
+     * **The bind group is rebuilt only when the field it was built against is a different object.**
+     * The renderer replaces its samples buffer when a scene's fields grow, and a group holding a
+     * destroyed buffer is a validation error at the next draw rather than a wrong picture — but
+     * rebuilding one every frame is the per-frame allocation the house rules are about.
+     */
+    prepare(ctx) {
+        if (ctx.backend !== 'webgpu')
+            return;
+        const gpu = this.device;
+        if (gpu === null || this.pipeline === null || this.params === null)
+            return;
+        const field = ctx.distanceField;
+        if (field === null) {
+            /* Nothing composed: no group, and `draw` then draws nothing rather than reading a stale one. */
+            this.group = null;
+            this.boundTo = null;
+            return;
+        }
+        if (this.boundTo !== field) {
+            this.group = gpu.createBindGroup({
+                label: 'gi march',
+                layout: this.pipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: { buffer: this.params } },
+                    { binding: 1, resource: { buffer: field.cascades } },
+                    { binding: 2, resource: { buffer: field.samples } },
+                ],
+            });
+            this.boundTo = field;
+        }
+        this.scratch[MARCH_EYE] = this.eye[0];
+        this.scratch[MARCH_EYE + 1] = this.eye[1];
+        this.scratch[MARCH_EYE + 2] = this.eye[2];
+        this.scratch[MARCH_LEVELS] = field.levels;
+        this.scratch[MARCH_SIDE] = field.side;
+        this.scratch[MARCH_STEPS] = this.marchSteps;
+        /* Half a voxel of the finest cascade: below that a march is polishing a value it cannot see. */
+        this.scratch[MARCH_EPSILON] = field.finestStep * 0.5;
+        gpu.queue.writeBuffer(this.params, 0, this.scratch);
+    }
+    /** March the field into the frame. Nothing is written where the ray found nothing. */
+    draw(ctx) {
+        if (ctx.backend !== 'webgpu')
+            return;
+        if (this.pipeline === null || this.group === null)
+            return;
+        ctx.pass.setPipeline(this.pipeline);
+        ctx.pass.setBindGroup(0, this.group);
+        ctx.pass.draw(3, 1, 0, 0);
+    }
+    dispose() {
+        this.params?.destroy();
+        this.group = null;
+        this.boundTo = null;
+    }
+}