@driftengine/core 4.8.6 → 4.8.7

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

@@ -44,7 +44,7 @@ import { COOKIE_TILE } from '../../lightBudget.js';
 import { FULL_LIGHT_BUDGET } from '../../uniformVectorBudget.js';
 import { toHalfFloats } from '../../halfFloat.js';
 import { DEFAULT_SOURCE_RADIUS, FACE_COUNT, createResolvedPointShadows, } from '../../pointShadowImage.js';
-import { MAX_AREA_LIGHTS } from '../../areaLights.js';
+import { MAX_AREA_LIGHTS, packAreaSizesAndDoors } from '../../areaLights.js';
 import { areaShadowLayerCount, castingRange, createResolvedAreaShadows, firstAreaShadowLayer, AreaShadowSet, } from '../../areaShadowSet.js';
 import { createBakeScratch, runPointShadowBakes, selectCastingLights, } from '../../pointShadowBudget.js';
 import { POINT_SHADOW_SAMPLER, PointShadowSystem, } from '../../pointShadowSystem.js';
@@ -54,9 +54,11 @@ import { createPanelBindGroup, createPanelBindGroupLayout, createPanelCorners, p
 import { createGpuTextCube, createTextBindGroup, createTextBindGroupLayout, GpuText, textPipeline, TEXT_FRAG_FIELDS, TEXT_FRAG_SIZE, TEXT_VERT_FIELDS, TEXT_VERT_SIZE, } from './textPass.js';
 import { deviceSnappedCellSize, deviceSnappedOrigin } from '../../textLayout.js';
 import { GpuSurfaceTexture } from './surfaceTexturePass.js';
+import { GpuSceneCaptureTarget } from './sceneCaptureTarget.js';
+import { sceneCaptureTexels } from '../../sceneCapture.js';
 import { gpuCompressedFormats } from './compressedUpload.js';
 import { GpuClothBinding, GpuClothParticles, clothStandIn } from './clothTextures.js';
-import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel } from '../../surfaceModel.js';
+import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel, skinProfileDistance, } from '../../surfaceModel.js';
 import { validateClothBinding } from '../../clothBindingData.js';
 import { createSdfTextBindGroup, createSdfTextBindGroupLayout, GpuSdfText, sdfTextPipeline, SDF_TEXT_FRAG_FIELDS, SDF_TEXT_FRAG_SIZE, SDF_TEXT_VERT_FIELDS, SDF_TEXT_VERT_SIZE, } from './sdfTextPass.js';
 import { createFilmBindGroup, createFilmBindGroupLayout, filmPipeline, FILM_FRAG_FIELDS, FILM_FRAG_SIZE, FILM_VERT_FIELDS, FILM_VERT_SIZE, } from './filmPass.js';
@@ -2227,6 +2229,97 @@ export class WebGPURenderer {
             mipmap: false,
         });
     }
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. At the world's own format, which under `hdrScene` is half floats.
+     */
+    createSceneCapture(width, height) {
+        const texture = new GpuSurfaceTexture(this.surface.device, this.pipelines, sceneCaptureTexels(width, height, this.quality.hdrScene), { wrap: 'clamp', mipmap: false });
+        this.captureTargets.set(texture, new GpuSceneCaptureTarget(this.surface.device, width, height));
+        return texture;
+    }
+    /** Each capture's attachments, beside the texture a material binds. */
+    captureTargets = new WeakMap();
+    /**
+     * Whether a scene capture is being drawn: an off-screen pass as a probe bake is, so the frame's
+     * camera, jitter, motion, refraction copy, skin's spread and late routing are left alone, but
+     * lit by the probes and DriftLight as the frame is. See `captureScene`.
+     */
+    capturePassActive = false;
+    /**
+     * Draw the scene into a capture from `camera`. See `RendererApi.captureScene`.
+     *
+     * **Its own encoder, as a probe bake's**: the frame's pass is set aside and restored, the rings
+     * are marked and rewound around the submit, and the frame graph is flushed at both boundaries so
+     * no recorded draw crosses one. **Radiance**: the output transform and exposure are held off.
+     */
+    captureScene(capture, camera, clearColor, draw) {
+        if (this.surface.lost)
+            return false;
+        const target = this.captureTargets.get(capture);
+        const resolve = capture.layerView();
+        if (target === undefined || resolve === null)
+            return false;
+        camera.updateMatrices(target.width / target.height);
+        const { device } = this.surface;
+        const { depth, colorMsaa } = target.attachments(this.samples, this.pipelines.format);
+        const savedPass = this.pass;
+        if (this.quality.frameGraph)
+            this.flushGraph();
+        const savedEncoder = this.encoder;
+        this.markRings();
+        const skinMark = this.skinPalettes.mark();
+        const frameEpoch = this.encoderEpoch;
+        this.encoderEpoch = ++this.encoderEpochs;
+        const encoder = device.createCommandEncoder({ label: 'capture' });
+        this.encoder = encoder;
+        this.capturePassActive = true;
+        const heldGrade = this.perFrameInts[this.materialField('uOutputTransform')] ?? 0;
+        const heldExposure = this.perFrameFloats[this.materialField('uOutputExposure')] ?? 1;
+        this.perFrameInts[this.materialField('uOutputTransform')] = 0;
+        this.perFrameFloats[this.materialField('uOutputExposure')] = 1;
+        this.materials.dirty();
+        const pass = encoder.beginRenderPass({
+            label: 'capture',
+            colorAttachments: [
+                {
+                    view: colorMsaa ?? resolve,
+                    resolveTarget: colorMsaa === null ? undefined : resolve,
+                    loadOp: 'clear',
+                    storeOp: resolvedStoreOp(colorMsaa !== null, true, this.quality.discardResolvedAttachments),
+                    clearValue: { r: clearColor[0], g: clearColor[1], b: clearColor[2], a: 1 },
+                },
+            ],
+            depthStencilAttachment: {
+                view: depth,
+                depthClearValue: DEPTH_CLEAR,
+                depthLoadOp: 'clear',
+                depthStoreOp: 'discard',
+            },
+        });
+        this.pass = pass;
+        try {
+            draw(camera);
+            /* The callback's draws replayed into this pass before it ends: see `bakeProbe`. */
+            if (this.quality.frameGraph)
+                this.flushGraph();
+        }
+        finally {
+            pass.end();
+            this.pass = null;
+            this.flushRings();
+            device.queue.submit([encoder.finish()]);
+            this.rewindRings(skinMark);
+            this.encoderEpoch = frameEpoch;
+            this.encoder = savedEncoder;
+            this.pass = savedPass;
+            this.perFrameInts[this.materialField('uOutputTransform')] = heldGrade;
+            this.perFrameFloats[this.materialField('uOutputExposure')] = heldExposure;
+            this.materials.dirty();
+            this.capturePassActive = false;
+        }
+        return true;
+    }
     /**
      * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
      *
@@ -2280,6 +2373,8 @@ export class WebGPURenderer {
             this.modelMap = null;
         this.forgetBindingsOf(texture);
         texture.dispose();
+        this.captureTargets.get(texture)?.dispose();
+        this.captureTargets.delete(texture);
     }
     /**
      * Drop every bind group that may hold `texture`'s view, and rebuild the ones bound now.
@@ -2458,7 +2553,7 @@ export class WebGPURenderer {
         const model = material?.model;
         warnUnpagedLightmap(model, modelMap);
         if (model?.kind === 'skin' && this.skinScatter !== null) {
-            this.skinScatter.setProfile(model.profile, model.scatterColor[0] * model.radius, model.scatterColor[1] * model.radius, model.scatterColor[2] * model.radius);
+            this.skinScatter.setProfile(model.profile, skinProfileDistance(model, 0), skinProfileDistance(model, 1), skinProfileDistance(model, 2));
         }
         this.material((f, i) => {
             /* The material's four switches, one row: albedo, ORM map, emissive map, two-sided. */
@@ -2503,7 +2598,10 @@ export class WebGPURenderer {
             f[emissive + 1] = asked?.[1] ?? 1;
             f[emissive + 2] = asked?.[2] ?? 1;
             /* The model's numbers and whether its map is bound. See `packModel`. */
-            packModel(material?.model ?? null, modelMap !== null, this.modelParams);
+            packModel(material?.model ?? null, modelMap !== null, this.modelParams, material?.physicalSpecular === true);
+            /* The first physical highlight asked for is when the lit pipelines start carrying one. */
+            if (material?.physicalSpecular === true)
+                this.enableLit('PHYSICAL_SPECULAR');
             f.set(this.modelParams, this.materialField('uModelParams'));
         });
         /*
@@ -3321,6 +3419,30 @@ export class WebGPURenderer {
             return;
         const device = this.surface.device;
         device.queue.writeBuffer(batch.instances, 0, batch.staging, 0, live * PARTICLE_INSTANCE_FLOATS);
+        this.drawParticleInstances(batch, batch.instances, live, camera, env, timeSeconds);
+    }
+    /**
+     * Draw particles a caller's own compute wrote, where they lie. See `DeviceParticles`.
+     *
+     * **The pool's draw with its instance stream swapped**: the same material, blend, flipbook, soft
+     * edge and fog, reading the caller's buffer in place of the one the pool uploads into — so nothing
+     * crosses back to the CPU. Not sorted, and a count past what the buffer holds is cut to it rather
+     * than handed to a draw the device would refuse with the frame.
+     */
+    drawDeviceParticles(batch, particles, camera, env, timeSeconds) {
+        const fits = Math.floor(particles.buffer.size / (PARTICLE_INSTANCE_FLOATS * 4));
+        const live = Math.min(Math.max(0, Math.floor(particles.count)), fits);
+        /* Not above zero covers a NaN as well: a count or a size that is no number draws nothing. */
+        if (!this.canDraw() || !(live > 0))
+            return;
+        if (batch.drawnInEncoder === this.encoderEpoch)
+            return;
+        batch.drawnInEncoder = this.encoderEpoch;
+        this.drawParticleInstances(batch, particles.buffer, live, camera, env, timeSeconds);
+    }
+    /** A pool's uniforms for this view, and its draw from `instances`: both entry points' tail. */
+    drawParticleInstances(batch, instances, live, camera, env, timeSeconds) {
+        const device = this.surface.device;
         const v = batch.vertFloats;
         const atV = (name) => (PARTICLE_VERT_FIELDS[name]?.offset ?? -4) / 4;
         mat4.multiply(this.correctedViewProj, CLIP_CORRECTION, camera.viewProjection);
@@ -3392,7 +3514,7 @@ export class WebGPURenderer {
             particleCommand.pipeline = particlePipe;
             particleCommand.bindGroup = group;
             particleCommand.vertexBuffers[0] = batch.corners;
-            particleCommand.vertexBuffers[1] = batch.instances;
+            particleCommand.vertexBuffers[1] = instances;
             particleCommand.vertexCount = 2;
             particleCommand.indexBuffer = batch.indexBuffer;
             particleCommand.indexed = true;
@@ -3406,7 +3528,7 @@ export class WebGPURenderer {
             pass.setPipeline(particlePipe);
             pass.setBindGroup(0, group);
             pass.setVertexBuffer(0, batch.corners);
-            pass.setVertexBuffer(1, batch.instances);
+            pass.setVertexBuffer(1, instances);
             pass.setIndexBuffer(batch.indexBuffer, 'uint32');
             pass.drawIndexed(PARTICLE_INDICES, live);
         }
@@ -3424,7 +3546,10 @@ export class WebGPURenderer {
         const fields = batch.fields;
         const atF = (name) => (fields[name]?.offset ?? -4) / 4;
         let depth = null;
-        if (batch.softDepth > 0 && !this.reflectionPassActive && !this.probePassActive) {
+        if (batch.softDepth > 0 &&
+            !this.reflectionPassActive &&
+            !this.probePassActive &&
+            !this.capturePassActive) {
             if (this.openPass() !== null && this.takeVolumeDepth())
                 depth = this.resolvedDepthView;
             if (depth === null && !this.warnedSpriteDepth) {
@@ -3717,6 +3842,7 @@ export class WebGPURenderer {
         scatterInto(f, WATER_FRAG_FIELDS['uLightRadius'], lights.radii, 1);
         scatterInto(f, WATER_FRAG_FIELDS['uLightSourceRadius'], lights.sourceRadii, 1);
         scatterInto(f, WATER_FRAG_FIELDS['uLightWeight'], lights.weights, 1);
+        scatterInto(f, WATER_FRAG_FIELDS['uLightCone'], lights.conesAndFalloffs, 4);
         const medium = resolveAtmosphere(env, camera.position[1] ?? 0, this.quality.underwaterAtmosphere, this.medium);
         f.set(medium.fogColor, atF('uFogColor'));
         f[atF('uFogDensity')] = medium.fogDensity;
@@ -4509,8 +4635,11 @@ export class WebGPURenderer {
         cookies: new Float32Array(0),
         heldSourceRadii: new Float32Array(MAX_POINT_LIGHTS),
         axesAndChannels: new Float32Array(MAX_POINT_LIGHTS * 4),
+        conesAndFalloffs: new Float32Array(MAX_POINT_LIGHTS * 4),
         heldWeights: new Float32Array(MAX_POINT_LIGHTS),
     };
+    /** The fixed arm's rectangles as `uAreaLightSize` holds them. See `packAreaSizesAndDoors`. */
+    areaSizesAndDoors = new Float32Array(MAX_AREA_LIGHTS * 4);
     /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
     medium = {
         fogColor: new Float32Array(3),
@@ -6566,7 +6695,7 @@ export class WebGPURenderer {
          * the viewer sees, and bounding it through a mirrored camera puts it in the wrong half of the
          * screen.
          */
-        if (!this.reflectionPassActive) {
+        if (!this.reflectionPassActive && !this.capturePassActive) {
             mat4.copy(this.frameRawViewProj, camera.viewProjection);
             /* The eye in world space, which the resolve's normals are turned to face. */
             this.reconEye.set(camera.position);
@@ -6600,7 +6729,8 @@ export class WebGPURenderer {
          * second temporal frame stepped the sequence twice a frame, so the world saw every other
          * position and the anti-flicker's period never started.
          */
-        if (this.framePresented)
+        /* A capture has no resolve to undo a jitter and is no frame of the sequence. */
+        if (this.framePresented || this.capturePassActive)
             this.viewProj = this.correctedViewProj;
         else
             this.jitterFrame();
@@ -6928,7 +7058,8 @@ export class WebGPURenderer {
          * uniform added on one backend is bound on both in the same change.
          */
         scatterInto(f, this.fragment.fields['uLightDir'], lights.directions, 3);
-        scatterInto(f, this.fragment.fields['uLightCone'], lights.coneCos, 2);
+        /* The cone and, in z, the light's own falloff exponent. See `conesAndFalloffs`. */
+        scatterInto(f, this.fragment.fields['uLightCone'], lights.conesAndFalloffs, 4);
         scatterInto(f, this.fragment.fields['uLightIesProfile'], lights.iesProfiles, 1);
         /* The azimuth and, in w, the light's channels. See `axesAndChannels`. */
         scatterInto(f, this.fragment.fields['uLightIesAxis'], lights.axesAndChannels, 4);
@@ -6949,7 +7080,9 @@ export class WebGPURenderer {
             scatterInto(f, this.fragment.fields['uAreaLightColor'], area.colors, 3);
             scatterInto(f, this.fragment.fields['uAreaLightRight'], area.right, 3);
             scatterInto(f, this.fragment.fields['uAreaLightUp'], area.up, 3);
-            scatterInto(f, this.fragment.fields['uAreaLightSize'], area.sizes, 2);
+            /* The half extents and, in zw, the barn doors. See `packAreaSizesAndDoors`. */
+            packAreaSizesAndDoors(area, this.areaSizesAndDoors);
+            scatterInto(f, this.fragment.fields['uAreaLightSize'], this.areaSizesAndDoors, 4);
             scatterInto(f, this.fragment.fields['uAreaLightTwoSided'], area.twoSided, 1);
         }
         /*
@@ -9631,7 +9764,7 @@ export class WebGPURenderer {
     drawsLate() {
         return (this.latePass !== null &&
             this.oitEncoder === null &&
-            routesLate(this.reconstructing, this.reflectionPassActive, this.probePassActive, this.framePresented));
+            routesLate(this.reconstructing, this.reflectionPassActive, this.probePassActive || this.capturePassActive, this.framePresented));
     }
     /**
      * The command a blended draw records into: the late pool while reconstructing, the frame graph
@@ -9693,7 +9826,7 @@ export class WebGPURenderer {
     }
     /** Whether this draw lands in the reconstructed picture. See `lateRouting.ts`. */
     tracksMotionNow() {
-        return tracksMotion(this.reconstructing, this.reflectionPassActive, this.probePassActive, this.framePresented);
+        return tracksMotion(this.reconstructing, this.reflectionPassActive, this.probePassActive || this.capturePassActive, this.framePresented);
     }
     /**
      * What this draw's motion is, recorded for the motion pass.
@@ -10094,6 +10227,8 @@ export class WebGPURenderer {
             f.set(surface.axis, base + at('uSsrAxis'));
             f.set(surface.tint, base + at('uSsrTint'));
             f[base + at('uSsrStrength')] = surface.strength;
+            f[base + at('uSsrFresnel')] = surface.fresnel ? 1 : 0;
+            f[base + at('uSsrFresnel') + 1] = surface.roughness;
             f[base + at('uSsrFacingCos')] = surface.facingCos;
             f[base + at('uSsrReach')] = surface.reachM;
             f[base + at('uSsrThickness')] = surface.thicknessM;
@@ -10654,7 +10789,7 @@ export class WebGPURenderer {
      * glass, and a frame that refracts nothing breaks no pass at all.
      */
     takeRefractSnapshot() {
-        if (this.reflectionPassActive || this.probePassActive)
+        if (this.reflectionPassActive || this.probePassActive || this.capturePassActive)
             return false;
         if (this.refractSnapshotTaken)
             return true;
@@ -10737,6 +10872,7 @@ export class WebGPURenderer {
             !this.skinScattered &&
             !this.reflectionPassActive &&
             !this.probePassActive &&
+            !this.capturePassActive &&
             !this.framePresented &&
             !this.overlayActive &&
             this.oitMode === 'none');
@@ -10794,6 +10930,8 @@ export class WebGPURenderer {
             return;
         if (this.reflectionPassActive || this.probePassActive || this.oitReplaying)
             return;
+        if (this.capturePassActive)
+            return;
         const encoder = this.encoder;
         const depth = this.depthView;
         const resolved = this.resolvedDepthView;
@@ -10851,7 +10989,7 @@ export class WebGPURenderer {
          * own terms: `resolvedDepthView` holds the *frame's* depth, and clamping a mirrored beam
          * against it would stop it at geometry that is not in front of it.
          */
-        if (this.reflectionPassActive)
+        if (this.reflectionPassActive || this.capturePassActive)
             return false;
         if (this.resolvedDepthView === null)
             return false;
@@ -11408,8 +11546,9 @@ export class WebGPURenderer {
      * any future branch added to one belongs in the other.
      */
     targetPipelines() {
-        if (this.probePassActive || this.reflectionPassActive)
+        if (this.probePassActive || this.reflectionPassActive || this.capturePassActive) {
             return this.pipelines;
+        }
         return this.overlayActive || this.framePresented ? this.overlayPipelines : this.pipelines;
     }
     /** End and submit a reopened pass. Safe to call when there is none. */

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

@@ -0,0 +1,24 @@
+/**
+ * A scene capture's attachments on WebGPU: the depth and, above one sample, the multisampled colour
+ * its pass draws into and resolves from — the capture's own texture being the resolve, since **a
+ * texture cannot be both multisampled and sampled**. At the world's sample count and format, because
+ * a capture draws the world with the world's pipelines: a pipeline whose count or format disagrees
+ * with its attachment is rejected at `finish` and takes the whole capture with it. Remade only if
+ * either has changed since. See `sceneCapture.ts` for what a capture is.
+ */
+export declare class GpuSceneCaptureTarget {
+    private readonly device;
+    readonly width: number;
+    readonly height: number;
+    private depth;
+    private depthView;
+    private colorMsaa;
+    private colorMsaaView;
+    private key;
+    constructor(device: GPUDevice, width: number, height: number);
+    attachments(samples: number, format: GPUTextureFormat): {
+        depth: GPUTextureView;
+        colorMsaa: GPUTextureView | null;
+    };
+    dispose(): void;
+}

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

@@ -0,0 +1,59 @@
+import { DEPTH_FORMAT } from '../../depthConvention.js';
+/**
+ * A scene capture's attachments on WebGPU: the depth and, above one sample, the multisampled colour
+ * its pass draws into and resolves from — the capture's own texture being the resolve, since **a
+ * texture cannot be both multisampled and sampled**. At the world's sample count and format, because
+ * a capture draws the world with the world's pipelines: a pipeline whose count or format disagrees
+ * with its attachment is rejected at `finish` and takes the whole capture with it. Remade only if
+ * either has changed since. See `sceneCapture.ts` for what a capture is.
+ */
+export class GpuSceneCaptureTarget {
+    device;
+    width;
+    height;
+    depth = null;
+    depthView = null;
+    colorMsaa = null;
+    colorMsaaView = null;
+    key = '';
+    constructor(device, width, height) {
+        this.device = device;
+        this.width = width;
+        this.height = height;
+    }
+    attachments(samples, format) {
+        const key = `${samples}:${format}`;
+        if (this.depthView === null || key !== this.key) {
+            this.dispose();
+            this.key = key;
+            this.depth = this.device.createTexture({
+                label: 'capture.depth',
+                size: [this.width, this.height],
+                format: DEPTH_FORMAT,
+                sampleCount: samples,
+                usage: 0x10, // RENDER_ATTACHMENT
+            });
+            this.depthView = this.depth.createView();
+            this.colorMsaa =
+                samples > 1
+                    ? this.device.createTexture({
+                        label: 'capture.colorMsaa',
+                        size: [this.width, this.height],
+                        format,
+                        sampleCount: samples,
+                        usage: 0x10, // RENDER_ATTACHMENT
+                    })
+                    : null;
+            this.colorMsaaView = this.colorMsaa?.createView() ?? null;
+        }
+        return { depth: this.depthView, colorMsaa: this.colorMsaaView };
+    }
+    dispose() {
+        this.depth?.destroy();
+        this.colorMsaa?.destroy();
+        this.depth = null;
+        this.depthView = null;
+        this.colorMsaa = null;
+        this.colorMsaaView = null;
+    }
+}

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -20,4 +20,4 @@
  * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
  * implementations of one decision is why it exists at all.
  */
-export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n/**\n * Whether a spot's cone misses this froxel: `coneBoxGap` in `clusteredLights.ts`, the same\n * arithmetic in the same order \u2014 the froxel's bounding sphere against the infinite cone, its apex\n * included, which can keep a light the shader would not draw and never drop one it would. A light\n * with no cone carries a cosine of -2 and never reaches the test.\n */\nfn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {\n  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);\n  if (cosOuter <= -1.0) {\n    return false;\n  }\n  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);\n  let a = (params.view * vec4<f32>(world, 0.0)).xyz;\n  let axis = vec3<f32>(a.x, a.y, -a.z);\n  let len = length(axis);\n  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */\n  if (len <= 1e-6 || cosOuter / len <= -1.0) {\n    return false;\n  }\n  let cosA = cosOuter / len;\n  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));\n  let unit = axis / len;\n  let extent = (hi - lo) * 0.5;\n  let toCentre = (lo + hi) * 0.5 - apex;\n  let along = dot(toCentre, unit);\n  let lengthSq = dot(toCentre, toCentre);\n  let across = sqrt(max(lengthSq - along * along, 0.0));\n  let reach = sqrt(lengthSq);\n  var distance = cosA * across - along * sinA;\n  if (along < -sinA * reach) {\n    distance = reach;\n  }\n  return distance - length(extent) > 0.0;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */\n    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let radius = abs(signedRadius);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 6u;\nconst LIGHT_REGION_TEXELS: u32 = 1920u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n/**\n * Whether a spot's cone misses this froxel: `coneBoxGap` in `clusteredLights.ts`, the same\n * arithmetic in the same order \u2014 the froxel's bounding sphere against the infinite cone, its apex\n * included, which can keep a light the shader would not draw and never drop one it would. A light\n * with no cone carries a cosine of -2 and never reaches the test.\n */\nfn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {\n  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);\n  if (cosOuter <= -1.0) {\n    return false;\n  }\n  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);\n  let a = (params.view * vec4<f32>(world, 0.0)).xyz;\n  let axis = vec3<f32>(a.x, a.y, -a.z);\n  let len = length(axis);\n  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */\n  if (len <= 1e-6 || cosOuter / len <= -1.0) {\n    return false;\n  }\n  let cosA = cosOuter / len;\n  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));\n  let unit = axis / len;\n  let extent = (hi - lo) * 0.5;\n  let toCentre = (lo + hi) * 0.5 - apex;\n  let along = dot(toCentre, unit);\n  let lengthSq = dot(toCentre, toCentre);\n  let across = sqrt(max(lengthSq - along * along, 0.0));\n  let reach = sqrt(lengthSq);\n  var distance = cosA * across - along * sinA;\n  if (along < -sinA * reach) {\n    distance = reach;\n  }\n  return distance - length(extent) > 0.0;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */\n    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let radius = abs(signedRadius);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

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

@@ -1,5 +1,6 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { LightmapTexels } from '../../lightmap.ts';
+import type { SceneCaptureTexels } from '../../sceneCapture.ts';
 import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
@@ -63,11 +64,13 @@ export declare class GpuSurfaceTexture {
     effectsView: GPUTextureView | null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     private readonly blockFormat;
-    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels | SceneCaptureTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
     private arrayView;
     /** The view every binding of this image holds. A new one when `update` changes the size. */
     get view(): GPUTextureView;
+    /** The only layer as a plain 2D view, which a scene capture's pass resolves into. */
+    layerView(): GPUTextureView | null;
     /**
      * Replace the pixels, keeping the handle and its sampler.
      *

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

@@ -1,6 +1,7 @@
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.js';
 import { toHalfFloats } from '../../halfFloat.js';
 import { isLightmapTexels } from '../../lightmap.js';
+import { isSceneCaptureTexels } from '../../sceneCapture.js';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.js';
 import { createCompressedTexture } from './compressedUpload.js';
@@ -156,24 +157,44 @@ export class GpuSurfaceTexture {
     constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
-        /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+        /* A scene capture's target: one empty layer the world is drawn into. See `sceneCapture.ts`. */
+        const capture = isSceneCaptureTexels(source) ? source : null;
+        /* A lightmap's page: two layers of bytes, uploaded as they are. See `lightmap.ts`. */
         const baked = isLightmapTexels(source) ? source : null;
-        const listed = (baked !== null ? [] : Array.isArray(source) ? source : [source]);
+        const listed = (baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]);
         const blocks = compressedLayers(listed);
         const srgb = (options.colorSpace ?? 'linear') === 'srgb';
         /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
-           place it is correct — `surfaceTexture.ts` makes the argument in full. */
-        this.format = baked !== null ? 'rgba16float' : srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-        if (baked !== null) {
+           place it is correct — `surfaceTexture.ts` makes the argument in full. A capture takes the
+           world's own format, which its pass resolves into. */
+        this.format =
+            capture !== null
+                ? pipelines.format
+                : srgb && baked === null
+                    ? 'rgba8unorm-srgb'
+                    : 'rgba8unorm';
+        if (capture !== null) {
+            this.layers = 1;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            this.width = capture.width;
+            this.height = capture.height;
+            this.levels = 1;
+            this.texture = this.allocate();
+        }
+        else if (baked !== null) {
             /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
-            this.layers = baked.layers;
+            this.layers = baked.layers.length;
             this.blockFormat = null;
             this.mipmapped = false;
             this.width = baked.width;
             this.height = baked.height;
             this.levels = 1;
             this.texture = this.allocate();
-            device.queue.writeTexture({ texture: this.texture }, baked.texels, { bytesPerRow: baked.width * 8, rowsPerImage: baked.height }, { width: baked.width, height: baked.height, depthOrArrayLayers: baked.layers });
+            /* A layer at a time, so a page's arrays are uploaded where they lie rather than joined. */
+            for (let layer = 0; layer < this.layers; layer++) {
+                device.queue.writeTexture({ texture: this.texture, origin: [0, 0, layer] }, baked.layers[layer], { bytesPerRow: baked.width * 4, rowsPerImage: baked.height }, { width: baked.width, height: baked.height, depthOrArrayLayers: 1 });
+            }
         }
         else if (blocks !== null) {
             /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
@@ -230,8 +251,9 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 1,
         });
-        if (blocks === null && baked === null)
+        if (blocks === null && baked === null && capture === null) {
             this.upload(listed);
+        }
         /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
            and read by `textureLoad` alone, so the filter never runs. */
         const effects = options.effects ?? [];
@@ -255,6 +277,10 @@ export class GpuSurfaceTexture {
     get view() {
         return this.current;
     }
+    /** The only layer as a plain 2D view, which a scene capture's pass resolves into. */
+    layerView() {
+        return (this.texture?.createView({ dimension: '2d', baseArrayLayer: 0, arrayLayerCount: 1 }) ?? null);
+    }
     /**
      * Replace the pixels, keeping the handle and its sampler.
      *

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

@@ -11,7 +11,7 @@ import type { UniformFields } from './scatterPass.ts';
 export declare const WATER_VERT_FIELDS: UniformFields;
 export declare const WATER_VERT_SIZE: 208;
 export declare const WATER_FRAG_FIELDS: UniformFields;
-export declare const WATER_FRAG_SIZE: 1248;
+export declare const WATER_FRAG_SIZE: 1504;
 /** The two meshes and the numbers the grid decided, behind the surface's opaque handle. */
 export interface GpuWater {
     /** The ocean: near sheet and far skirt in one buffer. */