@driftengine/core 4.3.0 → 4.4.0

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

@@ -179,7 +179,9 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
          * other kind against a `uint` texture, and the shader never samples it — every read is a
          * `texelFetch`, which is why the declaration shares a sampler rather than bringing its own.
          */
-        const integer = texture.type === 'usampler2D';
+        const integer = texture.type === 'usampler2D' || texture.type === 'usampler3D';
+        /* DriftLight's brick index and atlas, the lit pass's only volumes. See `driftLight.ts`. */
+        const volume = texture.type === 'sampler3D' || texture.type === 'usampler3D';
         const isShadow = integer || (name !== 'uEnvironment' && (name.endsWith('ShadowMap') || cube || array));
         entries.push({
             binding: texture.texture,
@@ -188,6 +190,7 @@ export function createFlatBindGroupLayout(device, variant, skinned = false, morp
                 sampleType: integer ? 'uint' : isShadow ? 'unfilterable-float' : 'float',
                 ...(cube ? { viewDimension: 'cube' } : {}),
                 ...(array ? { viewDimension: '2d-array' } : {}),
+                ...(volume ? { viewDimension: '3d' } : {}),
             },
         });
         /*
@@ -347,8 +350,10 @@ depthWrite = true, depthLayer = 0,
 /** Whether placement and tint arrive per instance. See `FlatVertexOptions`. */
 instanced = false, 
 /** Which order-independent buffer this pipeline writes, if any. The key must carry it. */
-oit = 'none') {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit));
+oit = 'none', 
+/** Culls nothing, for a surface seen from both faces. The key must carry it: `|2s`. */
+doubleSided = false) {
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided));
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -418,7 +423,9 @@ instanced = false,
  * ordinary translucent path uses, weighted by a uniform. That is what keeps this off
  * `flatFrag`'s permutation axis, which `scripts/wgsl.ts` measures at about 247 KB gzipped.
  */
-oit = 'none') {
+oit = 'none', 
+/** Culls nothing: a surface seen from both faces. */
+doubleSided = false) {
     const offset = depthOffsetForLayer(depthLayer);
     return {
         label: key,
@@ -459,7 +466,7 @@ oit = 'none') {
                         : { format: cache.format }),
             ],
         },
-        primitive: { topology: 'triangle-list', cullMode: 'back' },
+        primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back' },
         multisample: { count: cache.sampleCount },
         /*
          * `less`, matching the WebGL2 path's `LESS` rather than `LEQUAL`, and for the reason

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

@@ -50,6 +50,14 @@ export interface GpuParticles {
     readonly fragInts: Int32Array;
     readonly fields: UniformFields;
     readonly bindGroup: GPUBindGroup;
+    /**
+     * The encoder this batch was last drawn into, by the renderer's count, or -1.
+     *
+     * **A second draw into the same encoder is refused**, because this batch's buffers are written
+     * at each draw and every write lands before the encoder runs: both draws would show the second.
+     * WebGL2 has no such limit, and a limit one backend has is said, not left to a wrong picture.
+     */
+    drawnInEncoder: number;
     dispose(): void;
 }
 /**

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

@@ -145,6 +145,7 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
     const vertStaging = new ArrayBuffer(PARTICLE_VERT_SIZE);
     const fragStaging = new ArrayBuffer(fragSize);
     return {
+        drawnInEncoder: -1,
         corners: cornerBuffer,
         instances,
         indexBuffer,

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

@@ -26,7 +26,7 @@ import type { PipelineCache } from './pipelineCache.ts';
  * float target the generated shaders can sample as an ordinary texture.
  */
 export declare const RUSH_FRAG_FIELDS: UniformFields;
-export declare const RUSH_FRAG_SIZE: 160;
+export declare const RUSH_FRAG_SIZE: 192;
 declare const RUSH_UNIFORMS: 1;
 declare const RUSH_TEXTURES: {
     readonly uScene: {
@@ -49,9 +49,19 @@ declare const RUSH_TEXTURES: {
         readonly sampler: 39;
         readonly type: "sampler2D";
     };
-    readonly uGradeLut: {
+    readonly uExposureHeld: {
         readonly texture: 40;
         readonly sampler: 41;
+        readonly type: "sampler2D";
+    };
+    readonly uExposureLocal: {
+        readonly texture: 42;
+        readonly sampler: 43;
+        readonly type: "sampler2D";
+    };
+    readonly uGradeLut: {
+        readonly texture: 44;
+        readonly sampler: 45;
         readonly type: "sampler3D";
     };
 };

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

@@ -51,6 +51,19 @@ import type { PassDistanceField } from '../../pass.ts';
  * thirteen frames, which at sixty a second is a fifth of a second for a light that moved.
  */
 export declare const PROBES_PER_FRAME = 5;
+/**
+ * How much of what a probe held each refresh keeps, once the grid has been traced whole.
+ *
+ * Four fifths, so a probe is about the mean of its last five refreshes. The directions no longer
+ * turn, so a still scene gives the same estimate every time and this has nothing to average there;
+ * what it smooths is a light that moves, whose sun crosses from one direction of the set to the next
+ * in steps. What it gives up is how fast the bounce follows: a fifth of the way each time a probe
+ * comes round, which with 64
+ * probes at five a frame is a time constant of about half a second at 120 frames and a second at
+ * 60. It is counted in refreshes rather than seconds, because the renderer is given no clock; what
+ * would make it wrong is a scene whose light jumps and has to be followed at once.
+ */
+export declare const PROBE_HISTORY = 0.8;
 export interface ProbeBakeTargets {
     /** The array the shading samples, whose irradiance level this writes. */
     readonly array: GPUTexture;
@@ -61,6 +74,25 @@ export interface ProbeBakeTargets {
     readonly edge: number;
     readonly format: GPUTextureFormat;
 }
+/**
+ * A DriftLight field as the bake reads it: its two volumes and its two uniform rows, resolved for a
+ * probe by `resolveDriftLight` (radius zero, every fixed light through the volume).
+ */
+/**
+ * The frame's exact lights as the bake lights a hit with them: `resolveBounceLights`'s packing,
+ * how many it packed, and the frame's falloff code.
+ */
+export interface ProbeBakeLamps {
+    readonly data: Float32Array;
+    readonly count: number;
+    readonly falloff: number;
+}
+export interface ProbeBakeLightField {
+    readonly index: GPUTextureView;
+    readonly atlas: GPUTextureView;
+    readonly light: ArrayLike<number>;
+    readonly origin: ArrayLike<number>;
+}
 export declare class ProbeBaker {
     private readonly device;
     private readonly targets;
@@ -75,14 +107,21 @@ export declare class ProbeBaker {
     private readonly marchBuffer;
     private readonly bakeBuffer;
     private readonly volumeBuffer;
+    private readonly lampBuffer;
     private readonly scheduleBuffer;
     private readonly rayBuffer;
     private readonly irradianceBuffer;
     private readonly blitParams;
     private readonly blitGroup;
-    /** Rebuilt only when the field it was built against is a different object. */
+    /** Rebuilt only when the field or the light field's volumes it was built against change. */
     private computeGroup;
     private boundTo;
+    private boundAtlas;
+    /** DriftLight's volumes while a scene has none whole: one texel each, never read while off. */
+    private readonly emptyIndex;
+    private readonly emptyAtlas;
+    private readonly emptyIndexView;
+    private readonly emptyAtlasView;
     private readonly marchScratch;
     private readonly marchInts;
     private readonly bakeScratch;
@@ -134,15 +173,32 @@ export declare class ProbeBaker {
     setGrid(layers: number): void;
     /** Whether every layer has had its chain written, which is what makes the array safe to sample. */
     get complete(): boolean;
+    /**
+     * Whether the trace has written `layer`'s irradiance, after which that level is the trace's alone.
+     *
+     * A rasterised bake of a traced layer refreshes only its roughness chain. Two writers of one
+     * level is a layer that jumps to the raster's answer and is pulled back over the next refreshes,
+     * which on screen is light sweeping across a scene a probe at a time. What it gives up is the
+     * raster's own diffuse answer for that layer, which the trace replaces within a few frames anyway.
+     */
+    traced(layer: number): boolean;
     /**
      * Refresh this frame's share of the grid.
      *
      * Returns how many probes were baked, which is zero when there is nothing to trace against.
      */
-    bake(encoder: GPUCommandEncoder, field: PassDistanceField, grid: ProbeGrid, seeded: boolean, sun: {
+    bake(encoder: GPUCommandEncoder, field: PassDistanceField, grid: ProbeGrid, seeded: boolean, lightField: ProbeBakeLightField | null, lamps: ProbeBakeLamps, sun: {
         readonly direction: ArrayLike<number>;
         readonly colour: ArrayLike<number>;
-        readonly sky: ArrayLike<number>;
+        /** Outside, flat, for a frame that drew no sky: the environment's ambient. */
+        readonly ambient: ArrayLike<number>;
+        /** The sky the frame drew, which an escaping ray reads when there is one. */
+        readonly sky: {
+            readonly top: ArrayLike<number>;
+            readonly horizon: ArrayLike<number>;
+            readonly deep: ArrayLike<number>;
+            readonly sunDir: ArrayLike<number>;
+        } | null;
     }): number;
     dispose(): void;
 }

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

@@ -41,9 +41,11 @@
  * irradiance level is rewritten, which is the level the diffuse term reads.
  */
 import { PROBE_DIRECTIONS } from '../../gi/probeTrace.js';
+import { BOUNCE_LIGHT_FLOATS } from '../../gi/bounceLights.js';
 import { probeUpdateSchedule } from '../../gi/probeVolume.js';
+import { probesTheFieldReaches } from '../../gi/fieldReach.js';
 import { irradianceLevelFor } from '../../prefilterEnvMap.js';
-import { BAKE_COUNTS, BAKE_EDGE, BAKE_FRAME, BAKE_ORIGIN, BAKE_SCHEDULED, BAKE_SPACING, BAKE_SKY_COLOUR, BAKE_SUN_COLOUR, BAKE_SUN_DIR, PROBE_BAKE_FLOATS, PROBE_BAKE_WORKGROUP, PROBE_BLIT_FLOATS, PROBE_BLIT_STRIDE, PROBE_BLIT_WGSL, PROBE_RAY_FLOATS, PROBE_TEXEL_FLOATS, probeBakeWgsl, } from '../../shaders/gi/probeBake.wgsl.js';
+import { BAKE_COUNTS, BAKE_DRIFT_LIGHT, BAKE_DRIFT_ORIGIN, BAKE_EDGE, BAKE_FALLOFF, BAKE_LIGHT_COUNT, BOUNCE_LIGHT_ROWS, BAKE_FRAME, BAKE_ORIGIN, BAKE_SCHEDULED, BAKE_SPACING, BAKE_HISTORY, BAKE_SKY_COLOUR, BAKE_SKY_DEEP, BAKE_SKY_DRAWN, BAKE_SKY_SUN, BAKE_SKY_TOP, BAKE_SUN_COLOUR, BAKE_SUN_DIR, PROBE_BAKE_FLOATS, PROBE_BAKE_WORKGROUP, PROBE_BLIT_FLOATS, PROBE_BLIT_STRIDE, PROBE_BLIT_WGSL, PROBE_RAY_FLOATS, PROBE_TEXEL_FLOATS, probeBakeWgsl, } from '../../shaders/gi/probeBake.wgsl.js';
 import { PROBE_MARCH_DEFAULTS, PROBE_MARCH_FLOATS } from '../../shaders/gi/probeTrace.wgsl.js';
 import { PROBE_VOLUME_FLOATS, VOLUME_COUNTS, VOLUME_EDGE, VOLUME_INV_SPACING, VOLUME_LEVEL, VOLUME_ORIGIN, VOLUME_RADIANCE_EDGE, VOLUME_RADIANCE_LEVEL, } from '../../shaders/gi/probeVolume.wgsl.js';
 const COPY_DST = 0x0008;
@@ -63,6 +65,19 @@ const VISIBILITY_COMPUTE = 0x4;
  * thirteen frames, which at sixty a second is a fifth of a second for a light that moved.
  */
 export const PROBES_PER_FRAME = 5;
+/**
+ * How much of what a probe held each refresh keeps, once the grid has been traced whole.
+ *
+ * Four fifths, so a probe is about the mean of its last five refreshes. The directions no longer
+ * turn, so a still scene gives the same estimate every time and this has nothing to average there;
+ * what it smooths is a light that moves, whose sun crosses from one direction of the set to the next
+ * in steps. What it gives up is how fast the bounce follows: a fifth of the way each time a probe
+ * comes round, which with 64
+ * probes at five a frame is a time constant of about half a second at 120 frames and a second at
+ * 60. It is counted in refreshes rather than seconds, because the renderer is given no clock; what
+ * would make it wrong is a scene whose light jumps and has to be followed at once.
+ */
+export const PROBE_HISTORY = 0.8;
 export class ProbeBaker {
     device;
     targets;
@@ -77,14 +92,21 @@ export class ProbeBaker {
     marchBuffer;
     bakeBuffer;
     volumeBuffer;
+    lampBuffer;
     scheduleBuffer;
     rayBuffer;
     irradianceBuffer;
     blitParams;
     blitGroup;
-    /** Rebuilt only when the field it was built against is a different object. */
+    /** Rebuilt only when the field or the light field's volumes it was built against change. */
     computeGroup = null;
     boundTo = null;
+    boundAtlas = null;
+    /** DriftLight's volumes while a scene has none whole: one texel each, never read while off. */
+    emptyIndex;
+    emptyAtlas;
+    emptyIndexView;
+    emptyAtlasView;
     marchScratch = new Float32Array(PROBE_MARCH_FLOATS);
     marchInts = new Uint32Array(this.marchScratch.buffer);
     bakeScratch = new Float32Array(PROBE_BAKE_FLOATS);
@@ -146,8 +168,25 @@ export class ProbeBaker {
                 },
                 { binding: 9, visibility: VISIBILITY_COMPUTE, sampler: { type: 'filtering' } },
                 { binding: 10, visibility: VISIBILITY_COMPUTE, buffer: storageRead },
+                {
+                    binding: 11,
+                    visibility: VISIBILITY_COMPUTE,
+                    texture: { sampleType: 'uint', viewDimension: '3d' },
+                },
+                {
+                    binding: 12,
+                    visibility: VISIBILITY_COMPUTE,
+                    texture: { sampleType: 'float', viewDimension: '3d' },
+                },
+                { binding: 13, visibility: VISIBILITY_COMPUTE, sampler: { type: 'filtering' } },
+                { binding: 14, visibility: VISIBILITY_COMPUTE, buffer: { type: 'uniform' } },
             ],
         });
+        const emptyVolume = (label, format) => device.createTexture({ label, size: [1, 1, 1], dimension: '3d', format, usage: 0x4 });
+        this.emptyIndex = emptyVolume('probe bake.emptyDriftLightIndex', 'r32uint');
+        this.emptyAtlas = emptyVolume('probe bake.emptyDriftLightAtlas', 'rgba16float');
+        this.emptyIndexView = this.emptyIndex.createView({ dimension: '3d' });
+        this.emptyAtlasView = this.emptyAtlas.createView({ dimension: '3d' });
         const computeLayout = device.createPipelineLayout({
             bindGroupLayouts: [this.computeLayout],
         });
@@ -202,6 +241,7 @@ export class ProbeBaker {
         this.marchBuffer = this.uniform('march', PROBE_MARCH_FLOATS * 4);
         this.bakeBuffer = this.uniform('bake', PROBE_BAKE_FLOATS * 4);
         this.volumeBuffer = this.uniform('volume', PROBE_VOLUME_FLOATS * 4);
+        this.lampBuffer = this.uniform('lamps', BOUNCE_LIGHT_ROWS * 16);
         this.scheduleBuffer = this.storage('schedule', PROBES_PER_FRAME * 4);
         this.rayBuffer = this.storage('rays', PROBES_PER_FRAME * PROBE_DIRECTIONS * PROBE_RAY_FLOATS * 4);
         this.irradianceBuffer = this.storage('irradiance', PROBES_PER_FRAME * this.texels * PROBE_TEXEL_FLOATS * 4);
@@ -348,15 +388,27 @@ export class ProbeBaker {
         }
         return true;
     }
+    /**
+     * Whether the trace has written `layer`'s irradiance, after which that level is the trace's alone.
+     *
+     * A rasterised bake of a traced layer refreshes only its roughness chain. Two writers of one
+     * level is a layer that jumps to the raster's answer and is pulled back over the next refreshes,
+     * which on screen is light sweeping across a scene a probe at a time. What it gives up is the
+     * raster's own diffuse answer for that layer, which the trace replaces within a few frames anyway.
+     */
+    traced(layer) {
+        return this.filled[layer] === 1;
+    }
     /**
      * Refresh this frame's share of the grid.
      *
      * Returns how many probes were baked, which is zero when there is nothing to trace against.
      */
-    bake(encoder, field, grid, seeded, sun) {
+    bake(encoder, field, grid, seeded, lightField, lamps, sun) {
         if (this.layers !== grid.layers)
             this.setGrid(grid.layers);
-        const scheduled = probeUpdateSchedule(grid.layers, PROBES_PER_FRAME, this.frameIndex, this.scheduleScratch);
+        /* A probe the field does not reach keeps what it has. See `gi/fieldReach.ts`. */
+        const scheduled = probesTheFieldReaches(grid, this.scheduleScratch, probeUpdateSchedule(grid.layers, PROBES_PER_FRAME, this.frameIndex, this.scheduleScratch), field.outerBounds);
         if (scheduled === 0)
             return 0;
         const queue = this.device.queue;
@@ -389,8 +441,19 @@ export class ProbeBaker {
             this.volumeScratch[VOLUME_COUNTS + axis] = grid.counts[axis];
         }
         this.bakeScratch[BAKE_EDGE] = this.levelEdge;
-        this.bakeScratch[BAKE_FRAME] = this.frameIndex;
+        /*
+         * **The same directions at every refresh.** The set used to turn with the frame so a probe
+         * would converge, but only a running mean converges and a blended history never stops moving:
+         * every refresh was a new estimate a few per cent from the last, and a courtyard held still
+         * flickered, 77% of its pixels moving by more than 3 levels over a dozen frames against 2.5%
+         * rasterised. Held, it is 4.8%. What it gives up is the quadrature error of one set of 256
+         * directions, which stays where it is rather than averaging away: the held frame read 2.5 levels
+         * brighter than the turning one's mean. What would make it wrong is a small bright source that
+         * falls between the directions of every probe that sees it.
+         */
+        this.bakeScratch[BAKE_FRAME] = 0;
         this.bakeScratch[BAKE_SCHEDULED] = scheduled;
+        this.bakeScratch[BAKE_HISTORY] = this.complete ? PROBE_HISTORY : 0;
         /*
          * **The sun, because the trace shades what it hits rather than reading a capture.** That is
          * the whole of what a traced grid buys over a rasterised one: a light that moves changes the
@@ -399,7 +462,24 @@ export class ProbeBaker {
         for (let axis = 0; axis < 3; axis += 1) {
             this.bakeScratch[BAKE_SUN_DIR + axis] = sun.direction[axis] ?? 0;
             this.bakeScratch[BAKE_SUN_COLOUR + axis] = sun.colour[axis] ?? 0;
-            this.bakeScratch[BAKE_SKY_COLOUR + axis] = sun.sky[axis] ?? 0;
+            const sky = sun.sky;
+            this.bakeScratch[BAKE_SKY_COLOUR + axis] =
+                sky === null ? (sun.ambient[axis] ?? 0) : (sky.horizon[axis] ?? 0);
+            this.bakeScratch[BAKE_SKY_TOP + axis] = sky === null ? 0 : (sky.top[axis] ?? 0);
+            this.bakeScratch[BAKE_SKY_DEEP + axis] = sky === null ? 0 : (sky.deep[axis] ?? 0);
+            this.bakeScratch[BAKE_SKY_SUN + axis] = sky === null ? 0 : (sky.sunDir[axis] ?? 0);
+        }
+        this.bakeScratch[BAKE_SKY_DRAWN] = sun.sky === null ? 0 : 1;
+        /* The summed light of the scene's fixed lights, or zeros that switch it off. */
+        for (let lane = 0; lane < 4; lane += 1) {
+            this.bakeScratch[BAKE_DRIFT_LIGHT + lane] = lightField?.light[lane] ?? 0;
+            this.bakeScratch[BAKE_DRIFT_ORIGIN + lane] = lightField?.origin[lane] ?? 0;
+        }
+        /* And the frame's exact lights, which light what a ray strikes as they light the frame. */
+        this.bakeScratch[BAKE_LIGHT_COUNT] = lamps.count;
+        this.bakeScratch[BAKE_FALLOFF] = lamps.falloff;
+        if (lamps.count > 0) {
+            queue.writeBuffer(this.lampBuffer, 0, lamps.data, 0, lamps.count * BOUNCE_LIGHT_FLOATS);
         }
         queue.writeBuffer(this.bakeBuffer, 0, this.bakeScratch);
         this.volumeScratch[VOLUME_EDGE] = this.levelEdge;
@@ -412,7 +492,8 @@ export class ProbeBaker {
         this.volumeScratch[VOLUME_RADIANCE_EDGE] = this.targets.edge;
         this.volumeScratch[VOLUME_RADIANCE_LEVEL] = 0;
         queue.writeBuffer(this.volumeBuffer, 0, this.volumeScratch);
-        if (this.boundTo !== field || this.computeGroup === null) {
+        const atlas = lightField?.atlas ?? this.emptyAtlasView;
+        if (this.boundTo !== field || this.boundAtlas !== atlas || this.computeGroup === null) {
             this.computeGroup = this.device.createBindGroup({
                 label: 'probe bake',
                 layout: this.computeLayout,
@@ -428,9 +509,14 @@ export class ProbeBaker {
                     { binding: 8, resource: this.targets.view },
                     { binding: 9, resource: this.targets.sampler },
                     { binding: 10, resource: { buffer: field.albedo } },
+                    { binding: 11, resource: lightField?.index ?? this.emptyIndexView },
+                    { binding: 12, resource: atlas },
+                    { binding: 13, resource: this.targets.sampler },
+                    { binding: 14, resource: { buffer: this.lampBuffer } },
                 ],
             });
             this.boundTo = field;
+            this.boundAtlas = atlas;
         }
         const pass = encoder.beginComputePass({
             label: 'probe bake',
@@ -485,9 +571,13 @@ export class ProbeBaker {
         this.rayBuffer.destroy();
         this.irradianceBuffer.destroy();
         this.blitParams.destroy();
+        this.lampBuffer.destroy();
+        this.emptyIndex.destroy();
+        this.emptyAtlas.destroy();
         this.views = [];
         this.computeGroup = null;
         this.boundTo = null;
+        this.boundAtlas = null;
     }
 }
 const BLACK = { r: 0, g: 0, b: 0, a: 1 };

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

@@ -0,0 +1,65 @@
+/**
+ * What a probe bake draws into and reads from, made once and kept rather than made per bake.
+ *
+ * **A bake is a per-frame path now, and it was written as a one-off.** It created a depth and a
+ * multisampled colour texture per call and destroyed them after, a view per face, and for each
+ * probe it completed a view and a bind group per level and face of the blur and the convolution.
+ * That was a load-time cost while a scene baked its probes once. Since a bake can be spread a few
+ * faces a frame (`ProbeBakeOptions.faces`) and a crossfading grid re-bakes as the light moves, it
+ * is every frame, and on the native host, where each object costs most, a courtyard with the sun
+ * moving spent a third of its CPU in bakes. The capture cube lives as long as the renderer, so
+ * every view of it can too; the array is replaced only when the grid is, and `forgetArray` drops
+ * what was made against the old one.
+ *
+ * What it gives up is holding the attachments between bakes: a depth and a colour texture the size
+ * of one face, at the scene's sample count, kept for as long as the renderer is.
+ */
+export declare class ProbeTargets {
+    private readonly device;
+    private readonly probe;
+    private readonly size;
+    /** Level 0 of each face, which the bake's passes resolve into. */
+    readonly faceViews: readonly GPUTextureView[];
+    /** The whole chain as a cube, which the convolution samples. */
+    readonly wholeCube: GPUTextureView;
+    /** Level `l - 1` as a cube, which the blur into level `l` samples; index 0 unused. */
+    private readonly chainSources;
+    /** Level `l` of face `f`, at `l * faces + f`, which the blur writes. */
+    private readonly chainTargets;
+    private depth;
+    private depthView;
+    private colorMsaa;
+    private colorMsaaView;
+    private attachmentKey;
+    private readonly arrayViews;
+    private chainGroups;
+    private prefilterGroup;
+    private groupsBuffer;
+    constructor(device: GPUDevice, probe: GPUTexture, size: number);
+    /**
+     * The depth and, above one sample, the multisampled colour a face is drawn into: made on the first
+     * bake and again only if the sample count or the format has changed since.
+     */
+    attachments(samples: number, format: GPUTextureFormat): {
+        depth: GPUTextureView;
+        colorMsaa: GPUTextureView | null;
+    };
+    /** The blur's target for `level` of `face`. */
+    chainTarget(level: number, face: number): GPUTextureView;
+    /**
+     * The blur's group for `level`, over `buffer`: the uniforms, the level above as a cube, the
+     * sampler. Remade only if the ring's buffer has been replaced.
+     */
+    chainGroup(layout: GPUBindGroupLayout, buffer: GPUBuffer, sampler: GPUSampler, level: number): GPUBindGroup;
+    /** The convolution's group over `buffer`: the uniforms, the whole chain, the sampler. */
+    prefilterGroupFor(layout: GPUBindGroupLayout, buffer: GPUBuffer, sampler: GPUSampler): GPUBindGroup;
+    /** `level` of `layer` of the grid's array, which the convolution writes. */
+    arrayView(array: GPUTexture, layer: number, level: number): GPUTextureView;
+    /** The grid's array has been replaced: nothing made against the old one may be handed out. */
+    forgetArray(): void;
+    dispose(): void;
+    private faceLevel;
+    /** Groups hold the ring's buffer, so a replaced buffer makes every one of them stale. */
+    private forBuffer;
+    private destroyAttachments;
+}

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

@@ -0,0 +1,180 @@
+/**
+ * What a probe bake draws into and reads from, made once and kept rather than made per bake.
+ *
+ * **A bake is a per-frame path now, and it was written as a one-off.** It created a depth and a
+ * multisampled colour texture per call and destroyed them after, a view per face, and for each
+ * probe it completed a view and a bind group per level and face of the blur and the convolution.
+ * That was a load-time cost while a scene baked its probes once. Since a bake can be spread a few
+ * faces a frame (`ProbeBakeOptions.faces`) and a crossfading grid re-bakes as the light moves, it
+ * is every frame, and on the native host, where each object costs most, a courtyard with the sun
+ * moving spent a third of its CPU in bakes. The capture cube lives as long as the renderer, so
+ * every view of it can too; the array is replaced only when the grid is, and `forgetArray` drops
+ * what was made against the old one.
+ *
+ * What it gives up is holding the attachments between bakes: a depth and a colour texture the size
+ * of one face, at the scene's sample count, kept for as long as the renderer is.
+ */
+import { DEPTH_FORMAT } from '../../depthConvention.js';
+import { PREFILTER_SAMPLER_BINDING, PREFILTER_TEXTURE_BINDING, PREFILTER_UNIFORM_BINDING, PROBE_FACE_BASIS, PROBE_MIP_UNIFORM_SIZE, probeLevels, } from './probePass.js';
+export class ProbeTargets {
+    device;
+    probe;
+    size;
+    /** Level 0 of each face, which the bake's passes resolve into. */
+    faceViews;
+    /** The whole chain as a cube, which the convolution samples. */
+    wholeCube;
+    /** Level `l - 1` as a cube, which the blur into level `l` samples; index 0 unused. */
+    chainSources = [];
+    /** Level `l` of face `f`, at `l * faces + f`, which the blur writes. */
+    chainTargets = [];
+    depth = null;
+    depthView = null;
+    colorMsaa = null;
+    colorMsaaView = null;
+    attachmentKey = '';
+    /* The array's level-and-layer views and the groups over this ring's buffer, each made once. */
+    arrayViews = new Map();
+    chainGroups = [];
+    prefilterGroup = null;
+    groupsBuffer = null;
+    constructor(device, probe, size) {
+        this.device = device;
+        this.probe = probe;
+        this.size = size;
+        const faces = [];
+        for (let face = 0; face < PROBE_FACE_BASIS.length; face++) {
+            faces.push(this.faceLevel(face, 0));
+        }
+        this.faceViews = faces;
+        this.wholeCube = probe.createView({ dimension: 'cube' });
+        const levels = probeLevels(size);
+        for (let level = 1; level < levels; level++) {
+            this.chainSources[level] = probe.createView({
+                dimension: 'cube',
+                baseMipLevel: level - 1,
+                mipLevelCount: 1,
+            });
+            for (let face = 0; face < PROBE_FACE_BASIS.length; face++) {
+                this.chainTargets[level * PROBE_FACE_BASIS.length + face] = this.faceLevel(face, level);
+            }
+        }
+    }
+    /**
+     * The depth and, above one sample, the multisampled colour a face is drawn into: made on the first
+     * bake and again only if the sample count or the format has changed since.
+     */
+    attachments(samples, format) {
+        const key = `${samples}:${format}`;
+        if (this.depthView === null || key !== this.attachmentKey) {
+            this.destroyAttachments();
+            this.attachmentKey = key;
+            this.depth = this.device.createTexture({
+                label: 'probe.depth',
+                size: [this.size, this.size],
+                format: DEPTH_FORMAT,
+                /* The world's sample count, because a bake draws the world with the world's pipelines. */
+                sampleCount: samples,
+                usage: 0x10, // RENDER_ATTACHMENT
+            });
+            this.depthView = this.depth.createView();
+            this.colorMsaa =
+                samples > 1
+                    ? this.device.createTexture({
+                        label: 'probe.colorMsaa',
+                        size: [this.size, this.size],
+                        format,
+                        sampleCount: samples,
+                        usage: 0x10, // RENDER_ATTACHMENT
+                    })
+                    : null;
+            this.colorMsaaView = this.colorMsaa?.createView() ?? null;
+        }
+        return { depth: this.depthView, colorMsaa: this.colorMsaaView };
+    }
+    /** The blur's target for `level` of `face`. */
+    chainTarget(level, face) {
+        return this.chainTargets[level * PROBE_FACE_BASIS.length + face];
+    }
+    /**
+     * The blur's group for `level`, over `buffer`: the uniforms, the level above as a cube, the
+     * sampler. Remade only if the ring's buffer has been replaced.
+     */
+    chainGroup(layout, buffer, sampler, level) {
+        this.forBuffer(buffer);
+        let group = this.chainGroups[level];
+        if (group === undefined) {
+            group = this.device.createBindGroup({
+                layout,
+                entries: [
+                    { binding: 0, resource: { buffer, size: PROBE_MIP_UNIFORM_SIZE } },
+                    { binding: 1, resource: this.chainSources[level] },
+                    { binding: 2, resource: sampler },
+                ],
+            });
+            this.chainGroups[level] = group;
+        }
+        return group;
+    }
+    /** The convolution's group over `buffer`: the uniforms, the whole chain, the sampler. */
+    prefilterGroupFor(layout, buffer, sampler) {
+        this.forBuffer(buffer);
+        this.prefilterGroup ??= this.device.createBindGroup({
+            layout,
+            entries: [
+                { binding: PREFILTER_UNIFORM_BINDING, resource: { buffer, size: PROBE_MIP_UNIFORM_SIZE } },
+                { binding: PREFILTER_TEXTURE_BINDING, resource: this.wholeCube },
+                { binding: PREFILTER_SAMPLER_BINDING, resource: sampler },
+            ],
+        });
+        return this.prefilterGroup;
+    }
+    /** `level` of `layer` of the grid's array, which the convolution writes. */
+    arrayView(array, layer, level) {
+        const key = layer * 32 + level;
+        let view = this.arrayViews.get(key);
+        if (view === undefined) {
+            view = array.createView({
+                dimension: '2d',
+                baseArrayLayer: layer,
+                arrayLayerCount: 1,
+                baseMipLevel: level,
+                mipLevelCount: 1,
+            });
+            this.arrayViews.set(key, view);
+        }
+        return view;
+    }
+    /** The grid's array has been replaced: nothing made against the old one may be handed out. */
+    forgetArray() {
+        this.arrayViews.clear();
+    }
+    dispose() {
+        this.destroyAttachments();
+    }
+    faceLevel(face, level) {
+        return this.probe.createView({
+            dimension: '2d',
+            baseArrayLayer: face,
+            arrayLayerCount: 1,
+            baseMipLevel: level,
+            mipLevelCount: 1,
+        });
+    }
+    /** Groups hold the ring's buffer, so a replaced buffer makes every one of them stale. */
+    forBuffer(buffer) {
+        if (buffer === this.groupsBuffer)
+            return;
+        this.groupsBuffer = buffer;
+        this.chainGroups = [];
+        this.prefilterGroup = null;
+    }
+    destroyAttachments() {
+        this.depth?.destroy();
+        this.colorMsaa?.destroy();
+        this.depth = null;
+        this.depthView = null;
+        this.colorMsaa = null;
+        this.colorMsaaView = null;
+    }
+}