@driftengine/core 3.61.0

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

@@ -0,0 +1,366 @@
+import { FULLSCREEN_VERT_WGSL } from '../../shaders/generated/fullscreen.wgsl.js';
+import { RUSH_BINDINGS, RUSH_FRAG_WGSL } from '../../shaders/generated/rush.wgsl.js';
+import { BLOOM_BINDINGS, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_PREFILTER_FRAG_WGSL, BLOOM_UPSAMPLE_FRAG_WGSL, } from '../../shaders/generated/bloom.wgsl.js';
+import { AMBIENTOCCLUSION_BINDINGS as AO_BINDINGS, AO_BLUR_FRAG_WGSL, AO_FRAG_WGSL, } from '../../shaders/generated/ambientOcclusion.wgsl.js';
+import { TEMPORALRESOLVE_BINDINGS as TAA_BINDINGS, TEMPORAL_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/temporalResolve.wgsl.js';
+import { OITRESOLVE_BINDINGS as OIT_BINDINGS, OIT_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/oitResolve.wgsl.js';
+import { DECALPROJECT_BINDINGS as DECAL_BINDINGS, DECAL_PROJECT_FRAG_WGSL, } from '../../shaders/generated/decalProject.wgsl.js';
+import { SSRTRACE_BINDINGS as SSR_BINDINGS, SSR_TRACE_FRAG_WGSL, } from '../../shaders/generated/ssrTrace.wgsl.js';
+import { SSRRESOLVE_BINDINGS as SSR_RESOLVE_BINDINGS, SSR_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/ssrResolve.wgsl.js';
+import { GLOBALMEDIUM_BINDINGS as MEDIUM_BINDINGS, MEDIUM_FRAG_WGSL, MEDIUM_UPSAMPLE_FRAG_WGSL, } from '../../shaders/generated/globalMedium.wgsl.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The composite: everything that happens to the frame after the world is drawn.
+ *
+ * **The scene lands off-screen and one pass puts it on the canvas.** That pass is `rush.ts`, and
+ * it is one shader rather than four because every one of these effects reads the same resolved
+ * image: the speed blur, the camera motion blur, the occlusion it multiplies in, the bloom it
+ * adds and the tone curve it ends on. `sceneTarget.ts` makes the same argument on the other
+ * backend, and both are why `bindMeshPass` grades in the mesh pass *only* when there is no
+ * composite to grade in.
+ *
+ * **What differs here is depth.** WebGL2 resolves a multisampled depth buffer with
+ * `blitFramebuffer` and reads it back; WebGPU has no multisample depth resolve at all. So a
+ * frame that wants occlusion or motion blur gets a resolve of its own, written below, which
+ * reads sample zero through `texture_depth_multisampled_2d` and writes it to a single-sample
+ * float target the generated shaders can sample as an ordinary texture.
+ */
+export const RUSH_FRAG_FIELDS = RUSH_BINDINGS.RUSH_FRAG.fields;
+export const RUSH_FRAG_SIZE = RUSH_BINDINGS.RUSH_FRAG.uniformSize;
+const RUSH_UNIFORMS = RUSH_BINDINGS.RUSH_FRAG.uniforms;
+const RUSH_TEXTURES = RUSH_BINDINGS.RUSH_FRAG.textures;
+export const AO_FRAG_FIELDS = AO_BINDINGS.AO_FRAG.fields;
+export const AO_FRAG_SIZE = AO_BINDINGS.AO_FRAG.uniformSize;
+export const AO_BLUR_FIELDS = AO_BINDINGS.AO_BLUR_FRAG.fields;
+export const AO_BLUR_SIZE = AO_BINDINGS.AO_BLUR_FRAG.uniformSize;
+export const MEDIUM_FRAG_FIELDS = MEDIUM_BINDINGS.MEDIUM_FRAG.fields;
+export const MEDIUM_FRAG_SIZE = MEDIUM_BINDINGS.MEDIUM_FRAG.uniformSize;
+export const MEDIUM_UPSAMPLE_FIELDS = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.fields;
+export const MEDIUM_UPSAMPLE_SIZE = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.uniformSize;
+export const BLOOM_PREFILTER_FIELDS = BLOOM_BINDINGS.BLOOM_PREFILTER_FRAG.fields;
+/**
+ * The other two stages' blocks, read by name like every other block here.
+ *
+ * **Named rather than assumed to be the prefilter's**, because they are not: the downsample has
+ * a texel and no threshold, and the upsample has neither — it has a radius. All three happen to
+ * be sixteen bytes, which is exactly the coincidence that would let a wrong offset go unnoticed.
+ * `postField` throws on a name a block does not have, and that is the point of asking.
+ */
+export const BLOOM_DOWNSAMPLE_FIELDS = BLOOM_BINDINGS.BLOOM_DOWNSAMPLE_FRAG.fields;
+export const BLOOM_UPSAMPLE_FIELDS = BLOOM_BINDINGS.BLOOM_UPSAMPLE_FRAG.fields;
+/** The widest of the three, so one slot shape holds any stage's block. */
+export const BLOOM_STAGE_SIZE = Math.max(BLOOM_BINDINGS.BLOOM_PREFILTER_FRAG.uniformSize, BLOOM_BINDINGS.BLOOM_DOWNSAMPLE_FRAG.uniformSize, BLOOM_BINDINGS.BLOOM_UPSAMPLE_FRAG.uniformSize);
+const VISIBILITY_FRAGMENT = 0x2;
+/**
+ * What the scene is drawn into when the composite exists.
+ *
+ * `rgba16float` where the profile asks for an HDR scene, because that is the whole point of one:
+ * a bright pixel keeps its range until the tone curve, instead of being clipped at 1 by the mesh
+ * pass and then tone-mapped from a value that has already lost the information. `renderer.ts`
+ * calls the same option `hdrScene` and `keepsRange` for the same reason — a bloom threshold in
+ * scene units means nothing against a clamped buffer.
+ */
+export function sceneColorFormat(hdr) {
+    return hdr ? 'rgba16float' : 'rgba8unorm';
+}
+/** A single-sample depth the generated shaders can sample. See the module comment. */
+export const RESOLVED_DEPTH_FORMAT = 'r32float';
+/**
+ * Sample zero of a multisampled depth buffer, written to a colour target.
+ *
+ * **Because WebGPU cannot resolve depth.** `blitFramebuffer` does it on the other backend and
+ * this has no equivalent, so the choice is between this and switching occlusion off at any
+ * sample count above one. Sample zero rather than an average, deliberately: occlusion and
+ * reprojection both want *a* surface's depth, and the mean of four samples across a silhouette
+ * is a depth where no surface is — which reads as a halo along every edge.
+ */
+const DEPTH_RESOLVE_WGSL = `
+@group(0) @binding(0) var source: texture_depth_multisampled_2d;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  return vec4<f32>(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+}
+
+@fragment
+fn fragmentMain(@builtin(position) position: vec4<f32>) -> @location(0) f32 {
+  return textureLoad(source, vec2<i32>(position.xy), 0);
+}
+`;
+/** The same, for a frame drawn at one sample: a plain copy so the composite has one input shape. */
+const DEPTH_COPY_WGSL = `
+@group(0) @binding(0) var source: texture_depth_2d;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  return vec4<f32>(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+}
+
+@fragment
+fn fragmentMain(@builtin(position) position: vec4<f32>) -> @location(0) f32 {
+  return textureLoad(source, vec2<i32>(position.xy), 0);
+}
+`;
+export function createDepthResolveLayout(device, multisampled) {
+    return device.createBindGroupLayout({
+        label: 'post.depthResolveLayout',
+        entries: [
+            {
+                binding: 0,
+                visibility: VISIBILITY_FRAGMENT,
+                texture: { sampleType: 'depth', multisampled },
+            },
+        ],
+    });
+}
+export function depthResolvePipeline(cache, device, layout, multisampled) {
+    return cache.get(`post.depthResolve:${multisampled}`, () => {
+        const module = shaderModule(device, {
+            label: 'post.depthResolve',
+            code: multisampled ? DEPTH_RESOLVE_WGSL : DEPTH_COPY_WGSL,
+        });
+        return {
+            label: `post.depthResolve:${multisampled}`,
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            vertex: { module, entryPoint: 'vertexMain' },
+            fragment: {
+                module,
+                entryPoint: 'fragmentMain',
+                targets: [{ format: RESOLVED_DEPTH_FORMAT }],
+            },
+            primitive: { topology: 'triangle-list' },
+        };
+    });
+}
+/**
+ * One texture, one sampler, one uniform block: the shape every stage of this chain has.
+ *
+ * The bloom stages and the occlusion blur all read a source and a size, so they share a layout
+ * builder rather than three copies of the same six lines.
+ */
+export function createPostStageLayout(device, uniformBinding, uniformSize, textures) {
+    const entries = [
+        {
+            binding: uniformBinding,
+            visibility: VISIBILITY_FRAGMENT,
+            buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: uniformSize },
+        },
+    ];
+    for (const { binding, filterable = true, dimension = '2d' } of textures) {
+        /*
+         * **The resolved depth is `r32float`, which is `UnfilterableFloat` and nothing else.**
+         *
+         * The colour inputs are ordinary render targets and filter fine; this one does not, and
+         * declaring it alongside them is rejected in the words this backend has now heard three
+         * times: *"None of the supported sample types (UnfilterableFloat) of [Texture
+         * "post.resolvedDepth"] match the expected sample types (Float)"*. `depthPass.ts` learned
+         * it on a shadow map and `flatPass.ts` on the environment cube; the lesson is that a
+         * texture's filterability is a property of its format and never of the pass using it.
+         *
+         * `r16float` would filter, and would throw away the depth precision occlusion and
+         * reprojection are built on. So the format stays and the declaration bends.
+         */
+        entries.push({
+            binding: binding.texture,
+            visibility: VISIBILITY_FRAGMENT,
+            texture: filterable
+                ? { viewDimension: dimension }
+                : { sampleType: 'unfilterable-float', viewDimension: dimension },
+        });
+        entries.push({
+            binding: binding.sampler,
+            visibility: VISIBILITY_FRAGMENT,
+            sampler: { type: filterable ? 'filtering' : 'non-filtering' },
+        });
+    }
+    return device.createBindGroupLayout({ label: 'post.stageLayout', entries });
+}
+/**
+ * Additive, for the way back up the bloom pyramid.
+ *
+ * Each level is added *into* the one above it rather than replacing it, so level 0 ends up
+ * holding every octave at once — which is what makes the falloff the sum of the octaves rather
+ * than one kernel's. `bloomPass.ts` reaches the same place with `blendFunc(ONE, ONE)` and a
+ * `loadOp` of `load` is the other half of it here: a cleared attachment would discard the
+ * level the downsample just wrote and add the octave to nothing.
+ */
+/**
+ * What composites the order-independent buffers over the finished scene.
+ *
+ * Against a fragment carrying the average colour and the revealage, this computes
+ * `average * (1 - reveal) + scene * reveal` — which is the resolve. Doing it in the blend rather
+ * than by sampling means the pass never reads the target it writes.
+ */
+export const OIT_COMPOSITE_BLEND = {
+    color: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'one-minus-src-alpha', dstFactor: 'src-alpha', operation: 'add' },
+};
+/**
+ * What a drawn decal does to the pixel under it: `dst * src`.
+ *
+ * White is the identity, so a fragment the projector missed changes nothing and the shader needs
+ * no branch and no discard. It multiplies the *lit* pixel, which is the whole reason a mark placed
+ * this late still takes the receiver's lighting — `decalProject.ts` argues that where it is
+ * written, and `decalPass.ts` sets the same pair on the other backend.
+ */
+/**
+ * What a global medium does to the pixel under it: `dst * transmittance + inscatter`.
+ *
+ * **The transfer equation for one segment, written as a blend state.** The march puts scattered
+ * light in `rgb` and how much of the frame survives the journey in `a`, so `(one, src-alpha)` is
+ * exactly the integral — and the composite therefore never samples the colour it is modifying,
+ * which is the read both backends are entitled to call undefined.
+ *
+ * Alpha is `(zero, one)`: the frame's own alpha is not the medium's to spend. The scene target
+ * carries it to the canvas, and a medium that wrote there would make a foggy frame translucent.
+ */
+export const MEDIUM_TRANSMIT_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
+};
+export const DECAL_MULTIPLY_BLEND = {
+    color: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
+    alpha: { srcFactor: 'zero', dstFactor: 'src', operation: 'add' },
+};
+/**
+ * `over`, against colour a pass has already multiplied by its own coverage.
+ *
+ * What the screen-space reflection writes and what composites it: the trace multiplies what it
+ * found by how much of it lands, so two reflective surfaces overlapping layer the way two blended
+ * surfaces do rather than the way two independent guesses do — and the resolve then never has to
+ * sample the colour it is compositing onto.
+ */
+export const PREMULTIPLIED_OVER_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+};
+export const ADDITIVE_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+    alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+};
+/** A fullscreen pass over one or more inputs, writing to one colour target. */
+export function postPipeline(cache, device, layout, key, fragment, format, blend) {
+    return cache.get(key, () => ({
+        label: key,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'post.vert', code: FULLSCREEN_VERT_WGSL }),
+            entryPoint: 'main',
+        },
+        fragment: {
+            module: shaderModule(device, { label: key, code: fragment }),
+            entryPoint: 'main',
+            targets: [blend === undefined ? { format } : { format, blend }],
+        },
+        /*
+         * No depth at all, which is what makes this different from every other pipeline here: the
+         * composite writes over a finished frame and has nothing to sort against. `sceneTarget.ts`
+         * disables the test, the write and culling by hand for the same draw.
+         */
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+    }));
+}
+/**
+ * The temporal resolve's block and its three inputs.
+ *
+ * Named like the occlusion's beside it, and for the same reason `BLOOM_DOWNSAMPLE_FIELDS` is: a
+ * block read by assumption rather than by name is a uniform written to the wrong offset, which
+ * draws a plausible picture.
+ */
+export const TAA_FRAG_FIELDS = TAA_BINDINGS.TEMPORAL_RESOLVE_FRAG.fields;
+export const TAA_FRAG_SIZE = TAA_BINDINGS.TEMPORAL_RESOLVE_FRAG.uniformSize;
+export const TAA_UNIFORMS = TAA_BINDINGS.TEMPORAL_RESOLVE_FRAG.uniforms;
+export const TAA_TEXTURES = TAA_BINDINGS.TEMPORAL_RESOLVE_FRAG.textures;
+/**
+ * The order-independent resolve's inputs. It has no uniform block of its own — the whole pass is
+ * two texture fetches and a divide — so only the textures are named here.
+ */
+export const OIT_TEXTURES = OIT_BINDINGS.OIT_RESOLVE_FRAG.textures;
+/**
+ * A drawn decal's block and the one texture it reads.
+ *
+ * One block per mark and a frame may draw many, so the buffer holds an aligned slot each and the
+ * pass binds by dynamic offset — the arrangement the bloom chain already uses, and for the same
+ * reason: `queue.writeBuffer` does not interleave with recorded commands, so one block rewritten
+ * between two passes gives both passes the last write.
+ */
+export const DECAL_FRAG_FIELDS = DECAL_BINDINGS.DECAL_PROJECT_FRAG.fields;
+export const DECAL_FRAG_SIZE = DECAL_BINDINGS.DECAL_PROJECT_FRAG.uniformSize;
+export const DECAL_UNIFORMS = DECAL_BINDINGS.DECAL_PROJECT_FRAG.uniforms;
+export const DECAL_TEXTURES = DECAL_BINDINGS.DECAL_PROJECT_FRAG.textures;
+/**
+ * The reflection trace's block and its two inputs, and the resolve's one.
+ *
+ * One block per surface and a frame may draw several, so the buffer holds an aligned slot each and
+ * the pass binds by dynamic offset — the arrangement the bloom chain and the decals already use,
+ * and for the reason `bloomStaging` states: `queue.writeBuffer` does not interleave with recorded
+ * commands, so one block rewritten between two passes gives both passes the last write.
+ */
+export const SSR_FRAG_FIELDS = SSR_BINDINGS.SSR_TRACE_FRAG.fields;
+export const SSR_FRAG_SIZE = SSR_BINDINGS.SSR_TRACE_FRAG.uniformSize;
+export const SSR_UNIFORMS = SSR_BINDINGS.SSR_TRACE_FRAG.uniforms;
+export const SSR_TEXTURES = SSR_BINDINGS.SSR_TRACE_FRAG.textures;
+export const SSR_RESOLVE_TEXTURES = SSR_RESOLVE_BINDINGS.SSR_RESOLVE_FRAG.textures;
+/**
+ * The resolve's layout: one texture and no uniform block.
+ *
+ * `createPostStageLayout` cannot express this — it makes a block mandatory, every other stage in
+ * the chain having one — and this pass has nothing to parameterise: it fetches a texel and hands it
+ * to the blend state. A buffer allocated, bound and never read is worse than a second builder.
+ */
+export function createSsrResolveLayout(device) {
+    const binding = SSR_RESOLVE_TEXTURES.uSsrReflection;
+    return device.createBindGroupLayout({
+        label: 'post.ssrResolveLayout',
+        entries: [
+            {
+                binding: binding.texture,
+                visibility: VISIBILITY_FRAGMENT,
+                texture: { viewDimension: '2d' },
+            },
+            { binding: binding.sampler, visibility: VISIBILITY_FRAGMENT, sampler: { type: 'filtering' } },
+        ],
+    });
+}
+/**
+ * The resolve's layout: two textures and no uniform block.
+ *
+ * **`createPostStageLayout` cannot express this**, because every other pass in the chain has a
+ * block and it makes one mandatory. This pass has nothing to parameterise — it fetches the two
+ * buffers, divides and hands the result to the blend state — so a layout with a uniform binding
+ * nothing writes would be a buffer allocated, bound and never read.
+ */
+export function createOitResolveLayout(device) {
+    const entries = [];
+    for (const binding of [OIT_TEXTURES.uOitAccum, OIT_TEXTURES.uOitReveal]) {
+        entries.push({
+            binding: binding.texture,
+            visibility: VISIBILITY_FRAGMENT,
+            texture: { viewDimension: '2d' },
+        });
+        entries.push({
+            binding: binding.sampler,
+            visibility: VISIBILITY_FRAGMENT,
+            sampler: { type: 'filtering' },
+        });
+    }
+    return device.createBindGroupLayout({ label: 'post.oitResolveLayout', entries });
+}
+export { MEDIUM_FRAG_WGSL, MEDIUM_UPSAMPLE_FRAG_WGSL };
+export const MEDIUM_UNIFORMS = MEDIUM_BINDINGS.MEDIUM_FRAG.uniforms;
+export const MEDIUM_TEXTURES = MEDIUM_BINDINGS.MEDIUM_FRAG.textures;
+export const MEDIUM_UPSAMPLE_UNIFORMS = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.uniforms;
+export const MEDIUM_UPSAMPLE_TEXTURES = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.textures;
+export { RUSH_FRAG_WGSL, AO_FRAG_WGSL, AO_BLUR_FRAG_WGSL, TEMPORAL_RESOLVE_FRAG_WGSL, OIT_RESOLVE_FRAG_WGSL, DECAL_PROJECT_FRAG_WGSL, SSR_TRACE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, };
+export { BLOOM_PREFILTER_FRAG_WGSL, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_UPSAMPLE_FRAG_WGSL };
+export { RUSH_UNIFORMS, RUSH_TEXTURES };
+export const AO_UNIFORMS = AO_BINDINGS.AO_FRAG.uniforms;
+export const AO_TEXTURES = AO_BINDINGS.AO_FRAG.textures;
+export const AO_BLUR_UNIFORMS = AO_BINDINGS.AO_BLUR_FRAG.uniforms;
+export const AO_BLUR_TEXTURES = AO_BINDINGS.AO_BLUR_FRAG.textures;
+export const BLOOM_UNIFORMS = BLOOM_BINDINGS.BLOOM_PREFILTER_FRAG.uniforms;
+export const BLOOM_TEXTURES = BLOOM_BINDINGS.BLOOM_PREFILTER_FRAG.textures;

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

@@ -0,0 +1,108 @@
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The room, captured into a cubemap so reflective surfaces can mirror it.
+ *
+ * `reflectionProbe.ts` carries the argument for the feature: a reflection is an improvement to
+ * an appearance rather than a requirement, the scene still renders without one, and a device
+ * that cannot afford six faces keeps everything else.
+ *
+ * **Two things differ from the other backend and both are the same difference.** WebGPU has no
+ * `generateMipmap`, and the chain here *is* the roughness — a polished surface samples level 0
+ * and a satin one samples further up, which is a blur that costs a fetch rather than a pass. So
+ * the chain is built by rendering each level from the one above it, six faces at a time, with a
+ * blit that samples a **cube** rather than a 2D texture.
+ */
+/** Where each face looks, in the order a cubemap's layers are indexed. */
+export declare const PROBE_FACES: readonly {
+    readonly yaw: number;
+    readonly pitch: number;
+}[];
+export declare const PROBE_FOV_DEG = 90;
+export declare const PROBE_NEAR_M = 0.1;
+export declare const PROBE_FAR_M = 200;
+/** `basisX`, `basisY`, `forward`, `level` — four vec4s, so one aligned block. */
+export declare const PROBE_MIP_UNIFORM_SIZE = 64;
+/**
+ * The axes of each cube face, as the direction of its centre and its two in-plane steps.
+ *
+ * Written out rather than derived from the yaw and pitch above, because a cube's face basis has
+ * a handedness convention that a camera does not: getting one sign wrong mirrors a single face
+ * of the blur and shows up as one edge of a reflection that does not line up.
+ */
+export declare const PROBE_FACE_BASIS: readonly {
+    readonly forward: readonly [number, number, number];
+    readonly basisX: readonly [number, number, number];
+    readonly basisY: readonly [number, number, number];
+}[];
+export declare function createProbeMipBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function probeMipPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, format: GPUTextureFormat): GPURenderPipeline;
+/** How many levels a cube of this size has, counting the one the bake fills. */
+export declare function probeLevels(size: number): number;
+/**
+ * The convolution's bind group, whose numbering is the generator's rather than this file's.
+ *
+ * **It cannot share `probe.mipLayout` and the reason is worth stating.** That layout was written
+ * by hand and numbered 0, 1, 2. The prefilter's WGSL is generated from GLSL, and the transform
+ * assigns its own numbers — the uniform block at 1 and a combined sampler split into a texture at
+ * 32 and a sampler at 33. Reusing the hand-written layout would be a pipeline whose bind group
+ * does not match its shader, which WebGPU reports at `finish` rather than at the call that caused
+ * it, as no picture from a frame that recorded correctly.
+ *
+ * The numbers are read from `PREFILTER_BINDINGS` rather than written again here, so the generator
+ * moving one cannot leave this silently wrong.
+ */
+export declare function createProbePrefilterBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/**
+ * Where each field lands in the convolution's uniform block, from the generator's own table.
+ *
+ * Restating these as literals at the write site is how a struct layout and its writer drift, and
+ * the drift is invisible: a roughness written at the wrong offset is a level convolved for some
+ * other roughness, which looks like a plausible reflection.
+ */
+export declare const PREFILTER_UNIFORM_OFFSETS: {
+    readonly uPrefilterEdge: {
+        readonly offset: 0;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterIrradiance: {
+        readonly offset: 4;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterBox: {
+        readonly offset: 8;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterLevel: {
+        readonly offset: 12;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterRoughness: {
+        readonly offset: 16;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterSamples: {
+        readonly offset: 20;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterSourceTexels: {
+        readonly offset: 24;
+        readonly size: 4;
+        readonly type: "float";
+    };
+    readonly uPrefilterSourceMaxLod: {
+        readonly offset: 28;
+        readonly size: 4;
+        readonly type: "float";
+    };
+};
+/** The generator's binding numbers, named once so a bind group and its layout cannot disagree. */
+export declare const PREFILTER_UNIFORM_BINDING: 1;
+export declare const PREFILTER_TEXTURE_BINDING: 32;
+export declare const PREFILTER_SAMPLER_BINDING: 33;
+export declare function probePrefilterPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, format: GPUTextureFormat): GPURenderPipeline;

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

@@ -0,0 +1,188 @@
+import { FULLSCREEN_VERT_WGSL } from '../../shaders/generated/fullscreen.wgsl.js';
+import { PREFILTER_BINDINGS, PREFILTER_FRAG_WGSL } from '../../shaders/generated/prefilter.wgsl.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The room, captured into a cubemap so reflective surfaces can mirror it.
+ *
+ * `reflectionProbe.ts` carries the argument for the feature: a reflection is an improvement to
+ * an appearance rather than a requirement, the scene still renders without one, and a device
+ * that cannot afford six faces keeps everything else.
+ *
+ * **Two things differ from the other backend and both are the same difference.** WebGPU has no
+ * `generateMipmap`, and the chain here *is* the roughness — a polished surface samples level 0
+ * and a satin one samples further up, which is a blur that costs a fetch rather than a pass. So
+ * the chain is built by rendering each level from the one above it, six faces at a time, with a
+ * blit that samples a **cube** rather than a 2D texture.
+ */
+/** Where each face looks, in the order a cubemap's layers are indexed. */
+export const PROBE_FACES = [
+    { yaw: Math.PI / 2, pitch: 0 },
+    { yaw: -Math.PI / 2, pitch: 0 },
+    { yaw: 0, pitch: Math.PI / 2 },
+    { yaw: 0, pitch: -Math.PI / 2 },
+    /*
+     * **`+Z` is yaw `PI`, not yaw 0, and these two were the wrong way round.**
+     *
+     * `Camera`'s convention is that yaw 0 looks toward **-Z** and positive yaw turns toward +X, so
+     * cubemap layer 4, which the hardware reads as +Z, has to be rendered from yaw `PI`. This table
+     * had layer 4 at yaw 0, which put the -Z view in the +Z slot and the +Z view in the -Z slot —
+     * and it contradicted `PROBE_FACE_BASIS` in this same file, which has always said layer 4 is
+     * `forward: [0, 0, 1]`. `reflectionProbe.ts`'s table on the other backend has always been right.
+     *
+     * **It survived because a reflection of a swapped pair still looks like a reflection.** What
+     * finally separated them was projecting both backends' cubes onto spherical harmonics with one
+     * shared basis: every coefficient agreed except the linear Z, which came back +0.005 on one and
+     * -0.003 on the other. A sign, on the one axis these two faces span.
+     */
+    { yaw: Math.PI, pitch: 0 },
+    { yaw: 0, pitch: 0 },
+];
+export const PROBE_FOV_DEG = 90;
+export const PROBE_NEAR_M = 0.1;
+export const PROBE_FAR_M = 200;
+/**
+ * The blur that fills one mip level of one face from the level above.
+ *
+ * **Directions, not texture coordinates.** A cube level cannot be filled by sampling the 2D
+ * face above it: the neighbouring texels across an edge belong to a different face, and taking
+ * them from the same face is exactly how a seam appears along every edge. So the fragment
+ * rebuilds the direction its texel stands for and samples the cube, which crosses edges the way
+ * the hardware does when the shader reads it later.
+ */
+const PROBE_MIP_WGSL = `
+struct Face { basisX: vec4<f32>, basisY: vec4<f32>, forward: vec4<f32>, level: vec4<f32> }
+@group(0) @binding(0) var<uniform> face: Face;
+@group(0) @binding(1) var source: texture_cube<f32>;
+@group(0) @binding(2) var samp: sampler;
+
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+}
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> Varying {
+  var out: Varying;
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  out.uv = vec2<f32>(x, y);
+  out.position = vec4<f32>(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+  return out;
+}
+
+@fragment
+fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
+  // The texel's place on the face, in [-1, 1], and the direction it stands for.
+  let plane = in.uv * 2.0 - 1.0;
+  let dir = normalize(face.forward.xyz + face.basisX.xyz * plane.x + face.basisY.xyz * plane.y);
+  return textureSampleLevel(source, samp, dir, face.level.x);
+}
+`;
+/** `basisX`, `basisY`, `forward`, `level` — four vec4s, so one aligned block. */
+export const PROBE_MIP_UNIFORM_SIZE = 64;
+/**
+ * The axes of each cube face, as the direction of its centre and its two in-plane steps.
+ *
+ * Written out rather than derived from the yaw and pitch above, because a cube's face basis has
+ * a handedness convention that a camera does not: getting one sign wrong mirrors a single face
+ * of the blur and shows up as one edge of a reflection that does not line up.
+ */
+export const PROBE_FACE_BASIS = [
+    { forward: [1, 0, 0], basisX: [0, 0, -1], basisY: [0, -1, 0] },
+    { forward: [-1, 0, 0], basisX: [0, 0, 1], basisY: [0, -1, 0] },
+    { forward: [0, 1, 0], basisX: [1, 0, 0], basisY: [0, 0, 1] },
+    { forward: [0, -1, 0], basisX: [1, 0, 0], basisY: [0, 0, -1] },
+    { forward: [0, 0, 1], basisX: [1, 0, 0], basisY: [0, -1, 0] },
+    { forward: [0, 0, -1], basisX: [-1, 0, 0], basisY: [0, -1, 0] },
+];
+export function createProbeMipBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'probe.mipLayout',
+        entries: [
+            {
+                binding: 0,
+                visibility: 0x1 | 0x2,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PROBE_MIP_UNIFORM_SIZE },
+            },
+            { binding: 1, visibility: 0x2, texture: { viewDimension: 'cube' } },
+            { binding: 2, visibility: 0x2, sampler: {} },
+        ],
+    });
+}
+export function probeMipPipeline(cache, device, layout, format) {
+    return cache.get(`probe.mip:${format}`, () => {
+        const module = shaderModule(device, { label: 'probe.mip', code: PROBE_MIP_WGSL });
+        return {
+            label: `probe.mip:${format}`,
+            layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+            vertex: { module, entryPoint: 'vertexMain' },
+            fragment: { module, entryPoint: 'fragmentMain', targets: [{ format }] },
+            primitive: { topology: 'triangle-list' },
+        };
+    });
+}
+/** How many levels a cube of this size has, counting the one the bake fills. */
+export function probeLevels(size) {
+    return Math.floor(Math.log2(size)) + 1;
+}
+/**
+ * The convolution's bind group, whose numbering is the generator's rather than this file's.
+ *
+ * **It cannot share `probe.mipLayout` and the reason is worth stating.** That layout was written
+ * by hand and numbered 0, 1, 2. The prefilter's WGSL is generated from GLSL, and the transform
+ * assigns its own numbers — the uniform block at 1 and a combined sampler split into a texture at
+ * 32 and a sampler at 33. Reusing the hand-written layout would be a pipeline whose bind group
+ * does not match its shader, which WebGPU reports at `finish` rather than at the call that caused
+ * it, as no picture from a frame that recorded correctly.
+ *
+ * The numbers are read from `PREFILTER_BINDINGS` rather than written again here, so the generator
+ * moving one cannot leave this silently wrong.
+ */
+export function createProbePrefilterBindGroupLayout(device) {
+    const bindings = PREFILTER_BINDINGS.PREFILTER_FRAG;
+    const source = bindings.textures.uPrefilterSource;
+    return device.createBindGroupLayout({
+        label: 'probe.prefilterLayout',
+        entries: [
+            {
+                binding: bindings.uniforms,
+                visibility: 0x1 | 0x2,
+                buffer: {
+                    type: 'uniform',
+                    hasDynamicOffset: true,
+                    minBindingSize: PROBE_MIP_UNIFORM_SIZE,
+                },
+            },
+            { binding: source.texture, visibility: 0x2, texture: { viewDimension: 'cube' } },
+            { binding: source.sampler, visibility: 0x2, sampler: {} },
+        ],
+    });
+}
+/**
+ * Where each field lands in the convolution's uniform block, from the generator's own table.
+ *
+ * Restating these as literals at the write site is how a struct layout and its writer drift, and
+ * the drift is invisible: a roughness written at the wrong offset is a level convolved for some
+ * other roughness, which looks like a plausible reflection.
+ */
+export const PREFILTER_UNIFORM_OFFSETS = PREFILTER_BINDINGS.PREFILTER_FRAG.fields;
+/** The generator's binding numbers, named once so a bind group and its layout cannot disagree. */
+export const PREFILTER_UNIFORM_BINDING = PREFILTER_BINDINGS.PREFILTER_FRAG.uniforms;
+export const PREFILTER_TEXTURE_BINDING = PREFILTER_BINDINGS.PREFILTER_FRAG.textures.uPrefilterSource.texture;
+export const PREFILTER_SAMPLER_BINDING = PREFILTER_BINDINGS.PREFILTER_FRAG.textures.uPrefilterSource.sampler;
+export function probePrefilterPipeline(cache, device, layout, format) {
+    return cache.get(`probe.prefilter:${format}`, () => ({
+        label: `probe.prefilter:${format}`,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'probe.prefilter.vert', code: FULLSCREEN_VERT_WGSL }),
+            entryPoint: 'main',
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'probe.prefilter', code: PREFILTER_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [{ format }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+    }));
+}