@driftengine/core 3.61.0

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

@@ -0,0 +1,402 @@
+import { boundsOfPositions, createBounds } from '../../../math/bounds.js';
+import { MorphTexture } from './morphTexture.js';
+import { ABSENT_ATTRIBUTE } from '../../vertexDefaults.js';
+import { UPLOAD_BYTES_PER_STEP } from '../../uploadStep.js';
+import { INSTANCE_STRIDE } from '../../instances.js';
+/**
+ * Mesh geometry as WebGPU buffers.
+ *
+ * The vertex layout mirrors `mesh.ts` exactly, locations included, because both backends
+ * draw from shaders generated out of the same GLSL. Renumbering an attribute here would
+ * bind normals into the colour slot and produce a picture that is lit, plausible and wrong.
+ */
+/**
+ * Buffer usage flags, named here rather than read off the `GPUBufferUsage` global.
+ *
+ * The values are normative in the WebGPU specification, so nothing is being guessed. The
+ * global does not exist outside a browser, and depending on it would mean the buffer code
+ * could only ever be exercised on a device — which is precisely the code most worth testing
+ * without one.
+ */
+const USAGE = {
+    COPY_DST: 0x0008,
+    INDEX: 0x0010,
+    VERTEX: 0x0020,
+    UNIFORM: 0x0040,
+};
+/**
+ * Bytes reserved per absent attribute in the constants buffer.
+ *
+ * Sixteen so a `float32x3` starts aligned, and one slot each rather than all sharing offset
+ * zero so a reader can see which zero belongs to which attribute.
+ */
+const CONSTANT_SLOT = 16;
+/**
+ * Locations 0–9, matching `ATTR_POSITION` … `ATTR_RELIEF` in `mesh.ts`.
+ *
+ * **All ten, not the four that a simple mesh supplies.** WebGL2 lets the pipeline ignore an
+ * attribute the shader declares but the mesh omits; WebGPU validates the whole vertex state
+ * against the shader module and rejects the pipeline outright:
+ *
+ *     Vertex attribute slot 9 used in [flat.vert] is not present in the VertexState
+ *
+ * Six were listed here first, because six is what `Mesh` names in the obvious place. The
+ * shader declares ten, and the four extra are exactly the ones added late enough to be easy
+ * to miss: emissive colour, roughness, grain and relief.
+ */
+export const VERTEX_LAYOUT = [
+    { name: 'positions', shaderLocation: 0, format: 'float32x3', components: 3, optional: false },
+    { name: 'normals', shaderLocation: 1, format: 'float32x3', components: 3, optional: false },
+    { name: 'colors', shaderLocation: 2, format: 'float32x3', components: 3, optional: false },
+    { name: 'emissive', shaderLocation: 3, format: 'float32', components: 1, optional: false },
+    { name: 'specular', shaderLocation: 4, format: 'float32', components: 1, optional: true },
+    { name: 'uvs', shaderLocation: 5, format: 'float32x2', components: 2, optional: true },
+    { name: 'emissiveColor', shaderLocation: 6, format: 'float32x3', components: 3, optional: true },
+    { name: 'roughness', shaderLocation: 7, format: 'float32', components: 1, optional: true },
+    { name: 'grain', shaderLocation: 8, format: 'float32', components: 1, optional: true },
+    { name: 'relief', shaderLocation: 9, format: 'float32', components: 1, optional: true },
+    /* Four components, which makes it the widest the layout carries. See `generateTangents`. */
+    { name: 'tangents', shaderLocation: 10, format: 'float32x4', components: 4, optional: true },
+    /*
+     * Skinning, at the two locations after the tangent. Thirteen of WebGL2's guaranteed sixteen are
+     * now spoken for, which is the budget worth knowing before a fourteenth is proposed.
+     *
+     * **An instanced pipeline takes these two back**, and the channel below with them, because it
+     * cannot skin and cannot bend — see `INSTANCE_ATTRIBUTES`, which is the list of what it reclaims.
+     * That is the whole of the remaining budget: eleven base attributes plus five per-instance is
+     * exactly sixteen, and there is no room for a fourteenth base attribute and instancing at the
+     * same time. The channel below is that fourteenth attribute, and it is refused on an instanced
+     * draw for exactly this arithmetic.
+     */
+    { name: 'joints', shaderLocation: 11, format: 'float32x4', components: 4, optional: true },
+    { name: 'weights', shaderLocation: 12, format: 'float32x4', components: 4, optional: true },
+    /*
+     * The four-lane per-vertex channel: sway, skyDirect, alpha, and one reserved.
+     *
+     * **Fourteen of WebGL2's guaranteed sixteen are now spoken for, and this is the attribute that
+     * made the budget bite.** Eleven base attributes plus five per-instance is exactly sixteen, so
+     * an instanced draw has nothing to spare and a mesh carrying this cannot be drawn through that
+     * path — `flatVert` refuses the pair rather than dropping the attribute silently.
+     *
+     * Four components for the price of the one location a `float` would have cost, which is why
+     * three lanes and a spare live here instead of three attributes that do not fit.
+     */
+    { name: 'channel', shaderLocation: 13, format: 'float32x4', components: 4, optional: true },
+];
+/**
+ * Upload a mesh, all of it, now.
+ *
+ * The whole of `createGpuMeshIncremental` driven to the end in one call — deliberately, so the
+ * two paths cannot write different bytes. The one that spreads the work is the one with the
+ * interesting decisions in it; read that.
+ */
+export function createGpuMesh(device, data, dynamic = false) {
+    const { mesh, upload } = createGpuMeshIncremental(device, data, dynamic);
+    while (upload.next().done !== true)
+        ;
+    return mesh;
+}
+/**
+ * Upload a mesh over as many frames as the caller gives it.
+ *
+ * **The absent-attribute trick is the interesting part.** WebGL2 lets an attribute be
+ * *disabled* and read a constant the driver supplies, which is why `mesh.ts` can leave
+ * `specular` and `uvs` off entirely and a world with no shiny or textured geometry uploads
+ * nothing for them. WebGPU has no disabled attribute: every location in a vertex layout must
+ * be backed by a buffer.
+ *
+ * `arrayStride: 0` is the equivalent and it is exact. A stride of zero means every vertex
+ * reads element zero, so a one-element buffer of zeroes serves a mesh of any size. Eight
+ * bytes, allocated per mesh that omits the attribute, and **no shader variant** — which is
+ * what keeps both backends drawing from one generated set of WGSL instead of two.
+ *
+ * **Why the work is divisible here and not on the other backend.** This one interleaves every
+ * vertex on the CPU into a new array before it writes anything, where `mesh.ts` skips the
+ * interleave in favour of three tight buffers and says so in its first line. So the cost is
+ * WebGPU's alone and proportional to geometry, which is why a consumer measured the same drive
+ * as smooth on WebGL2 and hitching here.
+ *
+ * **What is paid at creation and not spread:** validation, the bounds, the allocation of the
+ * interleave array, the three buffers, and the constants. The bounds are the deliberate one — a
+ * streamer places and culls a region from them before a byte of it has landed, so a handle whose
+ * bounds were not yet known would not be usable at once, which is the whole promise here.
+ */
+export function createGpuMeshIncremental(device, data, dynamic = false) {
+    const bounds = boundsOfPositions(data.positions, createBounds());
+    const vertexCount = data.positions.length / 3;
+    const supplied = VERTEX_LAYOUT.filter((attribute) => !attribute.optional || data[attribute.name] !== undefined);
+    /* Interleaved: one stride holding every attribute the mesh actually supplied. */
+    const stride = supplied.reduce((sum, attribute) => sum + attribute.components * 4, 0);
+    const step = stride / 4;
+    const interleaved = new Float32Array(step * vertexCount);
+    /*
+     * **Refused here, in one sentence, rather than by the driver a hundred times.**
+     *
+     * A buffer past `maxBufferSize` is not created; what comes back is an invalid buffer, and
+     * every command encoder that so much as binds it is invalidated too. The result is the
+     * console reported from outside: one line naming the real cause, then a hundred and
+     * twenty-five repeats of *"is invalid due to a previous error"* from the shadow pass and the
+     * frame, with the actual number buried at the top and the model simply missing.
+     *
+     * `select.ts` asks for the adapter's own ceiling, which is 4 GiB on the part this was measured
+     * on against a 256 MiB default, so the models that hit this now load. What is left is the part
+     * whose adapter caps at the default, and it deserves a sentence naming the model's size and
+     * the device's rather than a wall of validation.
+     */
+    const byteLength = align4(interleaved.byteLength);
+    const ceiling = device.limits.maxBufferSize;
+    if (typeof ceiling === 'number' && byteLength > ceiling) {
+        throw new Error(`this mesh needs a ${Math.round(byteLength / 1024 / 1024)} MB vertex buffer and this GPU ` +
+            `allows ${Math.round(ceiling / 1024 / 1024)} MB, so it cannot be drawn. A model this ` +
+            'large has to be split or simplified before it is baked.');
+    }
+    const vertices = device.createBuffer({
+        label: 'mesh.vertices',
+        size: byteLength,
+        usage: USAGE.VERTEX | USAGE.COPY_DST,
+    });
+    /*
+     * One buffer holding what each omitted attribute reads as, at its own offset and read with a
+     * stride of zero. Ninety-six bytes at most, whatever the mesh's size, so it is written now
+     * rather than spread.
+     *
+     * **The values come from `vertexDefaults.ts` and are not all zero.** They were zeroes here,
+     * against the constants `mesh.ts` hands WebGL2, and `emissiveColor` is the one that bit:
+     * `flat.ts` treats a negative red as "inherit the albedo", so a zero meant *glow black* and
+     * every emissive surface whose mesh omitted the attribute stopped emitting on this backend.
+     */
+    const constants = device.createBuffer({
+        label: 'mesh.constants',
+        size: CONSTANT_SLOT * VERTEX_LAYOUT.length,
+        usage: USAGE.VERTEX | USAGE.COPY_DST,
+    });
+    const absent = new Float32Array((CONSTANT_SLOT / 4) * VERTEX_LAYOUT.length);
+    for (let slot = 0; slot < VERTEX_LAYOUT.length; slot++) {
+        const attribute = VERTEX_LAYOUT[slot];
+        const value = ABSENT_ATTRIBUTE[attribute.name];
+        if (value === undefined)
+            continue;
+        absent.set(value, slot * (CONSTANT_SLOT / 4));
+    }
+    device.queue.writeBuffer(constants, 0, absent);
+    const indexBuffer = device.createBuffer({
+        label: 'mesh.indices',
+        size: align4(data.indices.byteLength),
+        usage: USAGE.INDEX | USAGE.COPY_DST,
+    });
+    /*
+     * Where the position and normal fields sit inside one vertex, in floats. Found from the same
+     * `supplied` list the interleave walks, so the two cannot disagree — reading them off
+     * `VERTEX_LAYOUT` instead would be right until a mesh omits an optional attribute before them,
+     * which is the bug `present` already records once in this file.
+     */
+    let positionField = -1;
+    let normalField = -1;
+    let walked = 0;
+    for (const attribute of supplied) {
+        if (attribute.name === 'positions')
+            positionField = walked;
+        if (attribute.name === 'normals')
+            normalField = walked;
+        walked += attribute.components;
+    }
+    /*
+     * The chunks, in whole vertices and whole indices: a step never writes half of either, so the
+     * buffer never holds a torn one even for the frame between two steps.
+     */
+    const verticesPerStep = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / stride));
+    const indexWidth = data.indices.BYTES_PER_ELEMENT;
+    const indicesPerStep = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / indexWidth));
+    const totalSteps = Math.max(1, Math.ceil(vertexCount / verticesPerStep)) +
+        Math.max(1, Math.ceil(data.indices.length / indicesPerStep));
+    let uploaded = false;
+    function* uploadSteps() {
+        let taken = 0;
+        for (let from = 0; from < vertexCount; from += verticesPerStep) {
+            const to = Math.min(from + verticesPerStep, vertexCount);
+            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;
+            }
+            device.queue.writeBuffer(vertices, from * stride, interleaved, from * step, (to - from) * step);
+            taken += 1;
+            if (taken < totalSteps)
+                yield;
+        }
+        for (let from = 0; from < data.indices.length; from += indicesPerStep) {
+            const to = Math.min(from + indicesPerStep, data.indices.length);
+            device.queue.writeBuffer(indexBuffer, from * indexWidth, data.indices, from, to - from);
+            taken += 1;
+            if (taken < totalSteps)
+                yield;
+        }
+        uploaded = true;
+    }
+    const mesh = {
+        vertexBuffers: [vertices, constants],
+        indexBuffer,
+        indexCount: data.indices.length,
+        bounds,
+        get complete() {
+            return uploaded;
+        },
+        hasTangents: data.tangents !== undefined,
+        isSkinned: data.joints !== undefined,
+        hasChannel: data.channel !== undefined,
+        morph: data.morphTargets === undefined || data.morphTargetCount === undefined
+            ? null
+            : new MorphTexture(device, data.morphTargets, data.positions.length / 3, data.morphTargetCount),
+        update: !dynamic
+            ? null
+            : (target, positions, normals) => {
+                if (positions.length !== vertexCount * 3) {
+                    throw new Error(`this mesh has ${vertexCount} vertices and the update has ${positions.length / 3}. ` +
+                        "A mesh's vertex count is fixed at creation: the index buffer, the pipeline and " +
+                        'every other attribute are sized against it.');
+                }
+                /* Everything that decides whether this is on screen starts from the bounds, so a cloth
+                   that blew sideways out of its original box would be culled while still visible. */
+                boundsOfPositions(positions, bounds);
+                for (let vertex = 0; vertex < vertexCount; vertex++) {
+                    const at = vertex * step;
+                    interleaved[at + positionField] = positions[vertex * 3] ?? 0;
+                    interleaved[at + positionField + 1] = positions[vertex * 3 + 1] ?? 0;
+                    interleaved[at + positionField + 2] = positions[vertex * 3 + 2] ?? 0;
+                    if (normals === undefined)
+                        continue;
+                    interleaved[at + normalField] = normals[vertex * 3] ?? 0;
+                    interleaved[at + normalField + 1] = normals[vertex * 3 + 1] ?? 0;
+                    interleaved[at + normalField + 2] = normals[vertex * 3 + 2] ?? 0;
+                }
+                target.queue.writeBuffer(vertices, 0, interleaved);
+            },
+        dispose() {
+            vertices.destroy();
+            constants.destroy();
+            indexBuffer.destroy();
+        },
+    };
+    return { mesh, upload: uploadSteps() };
+}
+/**
+ * The buffer layouts a pipeline is built with, matching what `createGpuMesh` uploaded.
+ *
+ * `present` says which optional attributes came from real data. An absent one gets a stride
+ * of zero so every vertex reads the single element written for it.
+ */
+/**
+ * The per-instance buffer's five attributes: four matrix columns and a tint.
+ *
+ * **One list, because it answers two questions that must not disagree** — which locations the
+ * instance buffer declares, and therefore which locations a base attribute may not also declare.
+ * They were two lists: this one, and a `shaderLocation === 11 || shaderLocation === 12` test a few
+ * lines below it. That is what shipped a duplicate location 13 the day the per-vertex channel took
+ * it — every instanced pipeline, in the colour pass and the shadow pass alike, rejected with
+ * *"attribute shader location (13) is used more than once"*, which surfaces as an invalid command
+ * buffer two calls later rather than as anything about attributes.
+ *
+ * `INSTANCE_STRIDE` and the offsets are shared with the other backend through `instances.ts`,
+ * because which floats go where is a decision rather than a binding.
+ */
+const INSTANCE_ATTRIBUTES = [
+    { shaderLocation: 11, offset: 0, format: 'float32x4' },
+    { shaderLocation: 12, offset: 16, format: 'float32x4' },
+    { shaderLocation: 13, offset: 32, format: 'float32x4' },
+    { shaderLocation: 14, offset: 48, format: 'float32x4' },
+    { shaderLocation: 15, offset: 64, format: 'float32x3' },
+];
+/** The locations above, as the set the base layout must stand clear of on an instanced draw. */
+const INSTANCE_LOCATIONS = new Set(INSTANCE_ATTRIBUTES.map((attribute) => attribute.shaderLocation));
+export function vertexBufferLayouts(present, 
+/**
+ * Whether a third buffer carries one placement and colour per instance.
+ *
+ * Appended rather than woven in, at `stepMode: 'instance'`, so an instanced pipeline binds the
+ * mesh's own two buffers unchanged and its batch's third. The flat pipeline binds two of a
+ * limit of eight, so there is room, and a mesh needs no second upload to be instanced.
+ */
+instanced = false) {
+    const interleaved = [];
+    const constants = [];
+    let offset = 0;
+    VERTEX_LAYOUT.forEach((attribute, index) => {
+        /*
+         * **The instanced pipeline reclaims the two skinning locations, and it is allowed to because
+         * it cannot skin.** Locations 11 and 12 are the joint indices and weights; the INSTANCED
+         * shader variant declares neither, and the flat pass refuses a variant that is both. Leaving
+         * them declared here is what the device rejected — *"attribute shader location (11) is used
+         * more than once"*, reported at pipeline creation and surfacing as an invalid command buffer
+         * two calls later.
+         *
+         * Free for any mesh that may legitimately be instanced: an unskinned mesh supplies neither,
+         * so both sit in the constants buffer at `arrayStride: 0` and dropping them moves no offset
+         * in the interleaved one. A *skinned* mesh interleaves them, so removing them would shift
+         * the stride under every other attribute — which is why `createInstanced` refuses one.
+         */
+        const supplied = !attribute.optional || present[String(attribute.name)] === true;
+        if (instanced && INSTANCE_LOCATIONS.has(attribute.shaderLocation)) {
+            /*
+             * **Free to drop only because the mesh does not supply it.** An absent optional attribute
+             * sits in the constants buffer at `arrayStride: 0`, so removing it moves no offset in the
+             * interleaved one. A *supplied* one is interleaved, and dropping that would shift the stride
+             * under every attribute after it and draw scrambled geometry — which is why `createInstanced`
+             * refuses a skinned mesh and a channelled one. This is the same refusal one level down,
+             * where it cannot be reached around: a caller that finds another way to an instanced layout
+             * gets an error rather than a picture.
+             */
+            if (supplied) {
+                throw new Error(`vertexBufferLayouts: an instanced pipeline claims attribute location ` +
+                    `${attribute.shaderLocation} for its per-instance buffer, and this mesh supplies ` +
+                    `"${String(attribute.name)}" there. Dropping a supplied attribute would shift the ` +
+                    `stride under every attribute after it — draw this mesh without instancing instead.`);
+            }
+            return;
+        }
+        if (supplied) {
+            interleaved.push({
+                shaderLocation: attribute.shaderLocation,
+                offset,
+                format: attribute.format,
+            });
+            offset += attribute.components * 4;
+            return;
+        }
+        constants.push({
+            shaderLocation: attribute.shaderLocation,
+            offset: index * CONSTANT_SLOT,
+            format: attribute.format,
+        });
+    });
+    const layouts = [{ arrayStride: offset, attributes: interleaved }];
+    /*
+     * The constants buffer is always bound, even with nothing in it: the pipeline layout has
+     * to match the buffers a draw sets, and a mesh supplying every attribute would otherwise
+     * need a different layout from one that does not.
+     */
+    layouts.push({ arrayStride: 0, attributes: constants });
+    /*
+     * The four matrix columns and the tint — the five the flat shader's INSTANCED variant declares
+     * and exactly the five left once the base mesh has spent eleven of WebGL2's guaranteed sixteen.
+     * See `INSTANCE_ATTRIBUTES`, which the filter above reads too.
+     */
+    if (instanced) {
+        layouts.push({
+            arrayStride: INSTANCE_STRIDE,
+            stepMode: 'instance',
+            attributes: INSTANCE_ATTRIBUTES,
+        });
+    }
+    return layouts;
+}
+/** WebGPU requires a buffer size that is a multiple of four. */
+function align4(bytes) {
+    return Math.max(4, Math.ceil(bytes / 4) * 4);
+}

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

@@ -0,0 +1,36 @@
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The caustics pass: a surface lit by nearby water.
+ *
+ * `causticsRenderer.ts` carries the argument for the feature and for its limits, including why
+ * the ambient term is not decoration and why either side of the water works. The geometry comes
+ * from `buildSheets`, which both backends call, so this owns three buffers and a pipeline.
+ */
+export declare const CAUSTICS_VERT_FIELDS: UniformFields;
+export declare const CAUSTICS_VERT_SIZE: 64;
+export declare const CAUSTICS_FRAG_FIELDS: UniformFields;
+export declare const CAUSTICS_FRAG_SIZE: 144;
+/** A lit surface on the device, behind the API's opaque handle. */
+export interface GpuCaustics {
+    readonly vertexBuffers: readonly GPUBuffer[];
+    readonly vertexCount: number;
+    dispose(): void;
+}
+export declare function createGpuCaustics(device: GPUDevice, positions: Float32Array, locals: Float32Array, params: Float32Array, vertexCount: number): GpuCaustics;
+/** `aRest`, `aLocal`, `aParams` — three arrays on both sides, so three buffers. */
+export declare function causticsVertexLayouts(): GPUVertexBufferLayout[];
+export declare function createCausticsBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createCausticsBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * **Added, not blended over**, because this is light arriving at a surface rather than the
+ * surface: `gl.blendFunc(ONE, ONE)` on the other backend. Nothing culled, because a sheet is
+ * seen from either side — a pool floor from above and a soffit from below.
+ *
+ * **Depth tested and depth not written**, and the test is the part that matters:
+ * `causticsRenderer.ts` records that the sheet sits a couple of centimetres under the surface it
+ * lights, so geometry in front of it — a character, a lamp, a parapet — still occludes the light.
+ */
+export declare function causticsPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

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

@@ -0,0 +1,138 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { CAUSTICS_BINDINGS, CAUSTICS_FRAG_WGSL, CAUSTICS_VERT_WGSL, } from '../../shaders/generated/caustics.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The caustics pass: a surface lit by nearby water.
+ *
+ * `causticsRenderer.ts` carries the argument for the feature and for its limits, including why
+ * the ambient term is not decoration and why either side of the water works. The geometry comes
+ * from `buildSheets`, which both backends call, so this owns three buffers and a pipeline.
+ */
+export const CAUSTICS_VERT_FIELDS = CAUSTICS_BINDINGS.CAUSTICS_VERT.fields;
+export const CAUSTICS_VERT_SIZE = CAUSTICS_BINDINGS.CAUSTICS_VERT.uniformSize;
+export const CAUSTICS_FRAG_FIELDS = CAUSTICS_BINDINGS.CAUSTICS_FRAG.fields;
+export const CAUSTICS_FRAG_SIZE = CAUSTICS_BINDINGS.CAUSTICS_FRAG.uniformSize;
+const VERT_BINDING = CAUSTICS_BINDINGS.CAUSTICS_VERT.uniforms;
+const FRAG_BINDING = CAUSTICS_BINDINGS.CAUSTICS_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+export function createGpuCaustics(device, positions, locals, params, vertexCount) {
+    const upload = (data, label) => {
+        const buffer = device.createBuffer({
+            label,
+            size: Math.max(4, data.byteLength),
+            usage: USAGE_VERTEX,
+        });
+        device.queue.writeBuffer(buffer, 0, data);
+        return buffer;
+    };
+    const buffers = [
+        upload(positions, 'caustics.rest'),
+        upload(locals, 'caustics.local'),
+        upload(params, 'caustics.params'),
+    ];
+    return {
+        vertexBuffers: buffers,
+        vertexCount,
+        dispose() {
+            for (const buffer of buffers)
+                buffer.destroy();
+        },
+    };
+}
+/** `aRest`, `aLocal`, `aParams` — three arrays on both sides, so three buffers. */
+export function causticsVertexLayouts() {
+    return [
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x2' }],
+        },
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' }],
+        },
+    ];
+}
+export function createCausticsBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'caustics.layout',
+        entries: [
+            /*
+             * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+             *
+             * With one buffer rewritten between draws, every batch reads whatever was written last:
+             * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+             * every one of them. The picture is each batch wearing the last one's colour, width, time
+             * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+             * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+             * nothing drew two, which is exactly how water kept it for eight releases.
+             *
+             * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+             */
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: CAUSTICS_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: CAUSTICS_FRAG_SIZE },
+            },
+        ],
+    });
+}
+export function createCausticsBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'caustics.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: CAUSTICS_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: CAUSTICS_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Added, not blended over**, because this is light arriving at a surface rather than the
+ * surface: `gl.blendFunc(ONE, ONE)` on the other backend. Nothing culled, because a sheet is
+ * seen from either side — a pool floor from above and a soffit from below.
+ *
+ * **Depth tested and depth not written**, and the test is the part that matters:
+ * `causticsRenderer.ts` records that the sheet sits a couple of centimetres under the surface it
+ * lights, so geometry in front of it — a character, a lamp, a parapet — still occludes the light.
+ */
+export function causticsPipeline(cache, device, layout) {
+    return cache.get('caustics', () => ({
+        label: 'caustics',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'caustics.vert', code: CAUSTICS_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: causticsVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'caustics.frag', code: CAUSTICS_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format: cache.format,
+                    blend: {
+                        color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                        alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+    }));
+}

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

@@ -0,0 +1,51 @@
+import { type ClusterLightSet } from '../../clusteredLights.ts';
+import type { ComputeDefinition } from '../../compute.ts';
+/** What the caller sets before each dispatch. Held rather than passed, so `dispatch` allocates none. */
+export interface ClusterBinnerFrame {
+    lights: ClusterLightSet;
+    /** Column-major, as gl-matrix builds it. */
+    view: Float32Array;
+    near: number;
+    far: number;
+    tanHalfFovY: number;
+    aspect: number;
+    /** How many shadow uniform slots are live. See `LIGHT_TEXELS` in `clusteredLights.ts`. */
+    shadowSlots: number;
+}
+export declare class ClusterBinner {
+    /** The table the lit pass samples. Written by the dispatch, never by the CPU on this backend. */
+    private texture;
+    private view;
+    private pipeline;
+    private group;
+    private params;
+    private lightBuffer;
+    private device;
+    /** Staging for the two uploads, allocated once: `dispatch` is a per-frame path. */
+    private readonly paramsStaging;
+    private readonly paramsFloats;
+    private readonly paramsUints;
+    private readonly lightStaging;
+    private frame;
+    /** The table's view, for whoever binds it into the lit pass. Null before `init`. */
+    get tableView(): GPUTextureView | null;
+    /** The table itself, which a readback needs and the lit pass does not. */
+    get tableTexture(): GPUTexture | null;
+    /**
+     * The device `init` was handed, for a caller that needs to encode a copy of its own.
+     *
+     * **Exposed rather than fetched from somewhere else**, because there is nowhere else: a
+     * `GPUTexture` does not name its device and `createRenderer` does not return one. The seam
+     * hands a definition the device precisely so it can do work of its own outside a dispatch, and
+     * a readback is that work.
+     */
+    get gpuDevice(): GPUDevice | null;
+    /** What the next dispatch bins. Set per frame; nothing is copied until `dispatch`. */
+    setFrame(frame: ClusterBinnerFrame): void;
+    definition(): ComputeDefinition;
+    private build;
+    private run;
+    private release;
+}
+/** The shadow slots a frame has, which is the fixed budget the pool is sized for. */
+export declare const DEFAULT_SHADOW_SLOTS = 16;