@woosh/meep-engine 3.67.0 → 3.68.0

package/src/shade/renderer/global_illumination/screen_probe/GPUScreenProbeGI.js

@@ -0,0 +1,938 @@
+import { assert } from "../../../../core/assert.js";
+import { hammersley_sequence_2d } from "../../../../core/math/statistics/hammersley_sequence_2d.js";
+import { BufferDescriptor } from "../../../descriptor/buffer/BufferDescriptor.js";
+import { TextureDescriptor } from "../../../descriptor/texture/TextureDescriptor.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import { graph_import_texture } from "../../shader/graph/graph_import_texture.js";
+import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
+import {
+    SCREEN_PROBE_FRAME_STRUCT,
+    SCREEN_PROBE_PICK_STRUCT,
+    SCREEN_PROBE_RAY_STRUCT,
+    SCREEN_PROBE_STRUCT
+} from "./chunk_screen_probe.js";
+import {
+    SCREEN_PROBE_COUNTER_WORDS,
+    screen_probe_adaptive_capacity,
+    screen_probe_adaptive_levels,
+    screen_probe_adaptive_tile_capacity,
+    SCREEN_PROBE_DISPATCH_BRICK_RAYS,
+    SCREEN_PROBE_DISPATCH_PROBES,
+    SCREEN_PROBE_DISPATCH_RAYS,
+    SCREEN_PROBE_DISPATCH_THREADS,
+    SCREEN_PROBE_DISPATCH_WORDS,
+    SCREEN_PROBE_JITTER_PERIOD,
+    SCREEN_PROBE_OCTAHEDRON_LIMIT,
+    SCREEN_PROBE_RAY_SLOT_BITS,
+    SCREEN_PROBE_TILE_WORKGROUP_SIZE
+} from "./SCREEN_PROBE.js";
+import {
+    shader_screen_probe_brick_bounce,
+    shader_screen_probe_brick_light,
+    shader_screen_probe_brick_shade,
+    shader_screen_probe_brick_trace,
+    shader_screen_probe_brick_want
+} from "./shader_screen_probe_brick.js";
+import {
+    shader_screen_probe_composite,
+    shader_screen_probe_filter,
+    shader_screen_probe_irradiance
+} from "./shader_screen_probe_gather.js";
+import {
+    shader_screen_probe_brdf_pdf,
+    shader_screen_probe_generate_rays,
+    shader_screen_probe_lighting_pdf
+} from "./shader_screen_probe_importance.js";
+import { shader_screen_probe_color_capture } from "./shader_screen_probe_indirect_lighting.js";
+import { shader_screen_probe_pick } from "./shader_screen_probe_pick.js";
+import {
+    shader_screen_probe_brick_command,
+    shader_screen_probe_command,
+    shader_screen_probe_place_adaptive,
+    shader_screen_probe_place_uniform
+} from "./shader_screen_probe_place.js";
+import { shader_screen_probe_integrate, shader_screen_probe_temporal } from "./shader_screen_probe_resolve.js";
+import { shader_screen_probe_trace_screen } from "./shader_screen_probe_trace_screen.js";
+
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ * @typedef {import("./ScreenProbeSettings.js").ScreenProbeSettings} ScreenProbeSettings
+ * @typedef {import("../probe_clipmap/GPUProbeClipmapGI.js").GPUProbeClipmapGI} GPUProbeClipmapGI
+ */
+
+/**
+ * @param {string} name a field of the frame uniform
+ * @returns {number} its offset in words
+ */
+const frame_word = name => SCREEN_PROBE_FRAME_STRUCT.get(name).offset >>> 2;
+
+/**
+ * {@link ShadeIndirectLightingMode.ScreenProbes} for one view: Lumen's screen probe gather, over the world the probe
+ * clipmap holds (`GPUProbeClipmapGI`): its bricks, which rays traverse, its surface material, which hits read, its
+ * world light clusters, and its two sets of world-space probes, which stand in for what lies past a screen probe's reach
+ * and give a hit its next bounce.
+ *
+ * **A frame**, in three passes and a capture:
+ * 1. **Place** ({@link graph_update}): a uniform probe in every tile of `downsample_factor` pixels at the frame's
+ *    jitter, then the adaptive levels, finest last, each placing a probe where the probes so far would not
+ *    interpolate to a point of its grid; then the commands over the frame's probes.
+ * 2. **Trace**, after the world's bricks: each probe's world-space pick, reach and brick origin (and the world probes
+ *    it wants); its BRDF and lighting densities and its rays, reassigned to where its light is; the screen trace; the
+ *    bricks' trace, shade, local light and bounce of what the screen left; the hits' wants; the composite into each
+ *    probe's radiance, the spatial filter's passes, and the probes' SH3.
+ * 3. **Resolve** ({@link graph_resolve}), once the bent normals exist: each pixel's irradiance from its probes, then
+ *    the temporal filter into the frame's diffuse, which the deferred passes read.
+ * 4. **Capture** ({@link graph_capture}): the lit colour of the opaque surfaces, for the next frame's screen hits.
+ *
+ * **Its history**: last frame's probes (their records and filtered radiance, for the lighting density), its diffuse
+ * and frames (for the temporal filter) and its colour (for the screen hits) are kept while the structure and the view
+ * stay, until {@link reset_history}; any change starts it again. Nothing is allocated on a frame that changes neither: the adaptive probes' slots
+ * are made with the rest, as many as the uniform probes (`screen_probe_adaptive_capacity`), and a frame that would
+ * place more places no more.
+ */
+export class GPUScreenProbeGI {
+    /** @type {GPUDevice} */
+    #device;
+
+    #destroyed = false;
+
+    /** The structure the resources were made for. */
+    #view_width = 0;
+    #view_height = 0;
+    #downsample_factor = 0;
+    #octahedron_resolution = 0;
+    #adaptive_min_downsample_factor = 0;
+
+    #downsample_shift = 0;
+    #octahedron_shift = 0;
+    #adaptive_levels = 0;
+    #adaptive_tile_capacity = 0;
+    #tiles_x = 0;
+    #tiles_y = 0;
+    #uniform_count = 0;
+    #adaptive_capacity = 0;
+
+    /** Whether the resources stand. */
+    #built = false;
+
+    /** @type {GPUBuffer|null} */
+    #frame_buffer = null;
+    #frame_data = new ArrayBuffer(SCREEN_PROBE_FRAME_STRUCT.size);
+    #frame_u32 = new Uint32Array(this.#frame_data);
+    #frame_f32 = new Float32Array(this.#frame_data);
+
+    /** This frame's and last frame's probes; {@link #parity} names this frame's. @type {GPUBuffer[]} */
+    #probes = [];
+    #parity = 0;
+
+    /** @type {GPUBuffer|null} */
+    #picks = null;
+    /** @type {GPUBuffer|null} */
+    #brdf = null;
+    /** @type {GPUBuffer|null} */
+    #moving = null;
+    /** @type {GPUBuffer|null} */
+    #sh = null;
+    /** @type {GPUBuffer|null} */
+    #tile_counts = null;
+    /** @type {GPUBuffer|null} */
+    #tile_probes = null;
+    /** @type {GPUBuffer|null} */
+    #rays = null;
+    #ray_capacity = 0;
+    /** @type {GPUBuffer|null} */
+    #dispatch = null;
+    /** @type {GPUBuffer|null} */
+    #counters = null;
+
+    /** @type {GPUTextureContext|null} */
+    #ray_info = null;
+    /** @type {GPUTextureContext|null} */
+    #trace_radiance = null;
+    /** @type {GPUTextureContext|null} */
+    #trace_hit = null;
+    /** @type {GPUTextureContext|null} */
+    #lighting_pdf = null;
+    /** Two radiance atlases the composite and the filter's passes trade; {@link #radiance_final} holds last frame's. @type {GPUTextureContext[]} */
+    #radiance = [];
+    #radiance_final = 0;
+    /** @type {GPUTextureContext|null} */
+    #integrated = null;
+    /** This frame's and last frame's diffuse and frames; {@link #temporal_parity} names this frame's. @type {GPUTextureContext[]} */
+    #diffuse = [];
+    /** @type {GPUTextureContext[]} */
+    #frames = [];
+    #temporal_parity = 0;
+    /** @type {GPUTextureContext|null} */
+    #color_history = null;
+    /** The exposure each of the last two frames pre-exposed its probes' radiance by; {@link #parity} names this frame's. @type {GPUBuffer[]} */
+    #exposure_history = [];
+
+    /** Frames recorded. */
+    #frame = 0;
+
+    /** Whether last frame's probes, radiance, diffuse and colour describe this structure and view. */
+    #history = false;
+
+    /** Whether a frame has been recorded since the resources were made, so the next frame has a last frame. */
+    #recorded = false;
+
+    /** The view the last frame was recorded for. */
+    #view_id = -1;
+
+    #jitter = new Float64Array(2);
+    #jitter_scratch = new Float64Array(2);
+    #previous_jitter = new Float64Array(2);
+
+    /** The frame's inputs, as {@link graph_update} took them. */
+    #view = null;
+    /** @type {ScreenProbeSettings|null} */
+    #settings = null;
+    /** @type {GPUProbeClipmapGI|null} */
+    #world = null;
+    #stbn = null;
+
+    #b = {};
+    #want = {};
+    #sets = {};
+
+    #adaptive_settings = { level: 0 };
+    #brick_command_settings = { capacity: 0 };
+    #trace_screen_settings = { capacity: 0 };
+
+    #place_data = {};
+    #trace_data = {};
+    #resolve_data = {};
+    #capture_data = {};
+
+    /** The graph handle of the frame's diffuse, as {@link graph_resolve} wrote it. */
+    #diffuse_handle = -1;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+    }
+
+    /**
+     * Drop the history: the next frame takes nothing from the frames before it, as a first frame does. For a cut, or a
+     * change of scene or lighting the temporal filters must not blend across (`Renderer#indicate_view_change`).
+     */
+    reset_history() {
+        this.#recorded = false;
+    }
+
+    /**
+     * @returns {boolean} whether its resources stand: a frame of the mode has run and not been left since
+     */
+    get built() {
+        return this.#built;
+    }
+
+    /**
+     * @returns {number} uniform probes this frame's structure places
+     */
+    get uniform_count() {
+        return this.#uniform_count;
+    }
+
+    /**
+     * @returns {number} adaptive probe slots
+     */
+    get adaptive_capacity() {
+        return this.#adaptive_capacity;
+    }
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     * @param {ScreenProbeSettings} settings
+     * @returns {boolean} whether the resources are made for this view's size and the settings' structure
+     */
+    #built_for(width, height, settings) {
+        return this.#built
+            && this.#view_width === width
+            && this.#view_height === height
+            && this.#downsample_factor === settings.downsample_factor
+            && this.#octahedron_resolution === settings.octahedron_resolution
+            && this.#adaptive_min_downsample_factor === settings.adaptive_min_downsample_factor;
+    }
+
+    /**
+     * Take the frame's placement and traces, after the world's update ({@link GPUProbeClipmapGI#graph_update}) in the
+     * same frame: make the resources for the view and the structure the settings describe, unless they already are,
+     * and record the place and trace passes. {@link graph_resolve} follows once the bent normals exist.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view
+     * @param {ScreenProbeSettings} options.settings
+     * @param {GPUProbeClipmapGI} options.world the probe clipmap GI, updated this frame: the bricks, material, light
+     *   clusters and world-space probes the screen probes trace and read
+     * @param {*} options.stbn the 2-channel spatio-temporal blue noise, `STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`
+     * @param {number} options.depth graph handle of the view's reverse-Z depth
+     * @param {number} options.normal graph handle of the G-buffer's shading normals
+     * @param {number} options.pbr graph handle of the G-buffer's PBR target, which holds the face normal
+     * @param {number} options.velocity graph handle of the frame's motion, internal pixels
+     * @param {number} options.occlusion graph handle of the TAA's history confidence (`shader_depth_occlusion_clip`)
+     * @param {number} options.hzb graph handle of the view's hierarchical Z buffer, from mip 1
+     * @param {number} options.exposure graph handle of the factor the display multiplies radiance by, as the last frame
+     *   was shown
+     */
+    graph_update({ graph, view, settings, world, stbn, depth, normal, pbr, velocity, occlusion, hzb, exposure }) {
+        assert.defined(graph, 'graph');
+        assert.defined(view, 'view');
+        assert.defined(settings, 'settings');
+        assert.defined(world, 'world');
+        assert.ok(world.has_probes, 'world: the probe clipmap GI updated this frame');
+        assert.defined(stbn, 'stbn');
+        assert.isNonNegativeInteger(depth, 'depth');
+        assert.isNonNegativeInteger(normal, 'normal');
+        assert.isNonNegativeInteger(pbr, 'pbr');
+        assert.isNonNegativeInteger(velocity, 'velocity');
+        assert.isNonNegativeInteger(occlusion, 'occlusion');
+        assert.isNonNegativeInteger(hzb, 'hzb');
+        assert.isNonNegativeInteger(exposure, 'exposure');
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        const width = view.resolution[0];
+        const height = view.resolution[1];
+
+        if (!this.#built_for(width, height, settings)) {
+            this.#build(width, height, settings);
+        }
+
+        this.#view = view;
+        this.#settings = settings;
+        this.#world = world;
+        this.#stbn = stbn;
+
+        // the probes' place in their tiles, a Hammersley set over the period
+        this.#previous_jitter.set(this.#jitter);
+
+        hammersley_sequence_2d(this.#jitter_scratch, 0, this.#frame % SCREEN_PROBE_JITTER_PERIOD, SCREEN_PROBE_JITTER_PERIOD);
+
+        this.#jitter[0] = Math.floor(this.#jitter_scratch[0] * this.#downsample_factor);
+        this.#jitter[1] = Math.floor(this.#jitter_scratch[1] * this.#downsample_factor);
+
+        this.#parity = 1 - this.#parity;
+        this.#temporal_parity = 1 - this.#temporal_parity;
+
+        // another view's frames are no history of this one
+        if (view.id !== this.#view_id) {
+            this.#recorded = false;
+            this.#view_id = view.id;
+        }
+
+        // last frame's probes, radiance, diffuse and colour are this structure's where a frame was recorded since it was made
+        this.#history = this.#recorded;
+
+        this.#write_frame(world.brick_clipmap, settings);
+
+        const counters = graph_import_buffer(graph, this.#counters, 'screen probe counters');
+
+        const place = this.#place_data;
+        const place_pass = graph.add("Screen Probe Place", place, this.#execute_place);
+
+        place.counters = place_pass.write(counters);
+        place.depth = place_pass.read(depth);
+        place.pbr = place_pass.read(pbr);
+        place.velocity = place_pass.read(velocity);
+
+        place_pass.make_side_effect();
+
+        const trace = this.#trace_data;
+        const trace_pass = graph.add("Screen Probe Trace", trace, this.#execute_trace);
+
+        trace.counters = trace_pass.write(place.counters);
+        trace.depth = trace_pass.read(depth);
+        trace.normal = trace_pass.read(normal);
+        trace.pbr = trace_pass.read(pbr);
+        trace.velocity = trace_pass.read(velocity);
+        trace.occlusion = trace_pass.read(occlusion);
+        trace.hzb = trace_pass.read(hzb);
+        trace.exposure = trace_pass.read(exposure);
+        trace.bricks = trace_pass.read(world.bricks);
+        trace.cluster_lookup = trace_pass.read(world.clusters.lookup);
+        trace.cluster_data = trace_pass.read(world.clusters.data);
+
+        trace_pass.make_side_effect();
+
+        this.#recorded = true;
+        this.#frame++;
+    }
+
+    /**
+     * Take the frame's resolve, once the bent normals exist: each pixel's irradiance from its probes, then the temporal
+     * filter into the frame's diffuse.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.depth graph handle of the view's reverse-Z depth
+     * @param {number} options.depth_previous graph handle of last frame's
+     * @param {number} options.pbr graph handle of the G-buffer's PBR target
+     * @param {number} options.velocity graph handle of the frame's motion
+     * @param {number} options.bent_normals graph handle of the bent normals (the shading normals where GTAO is off)
+     * @param {number} options.exposure graph handle of the factor the display multiplies radiance by, as the last frame
+     *   was shown, the one {@link graph_update} took: what the probes' radiance is pre-exposed by
+     * @returns {number} graph handle of the frame's diffuse, `rgba16float`: E at the bent normal, before AO
+     */
+    graph_resolve({ graph, depth, depth_previous, pbr, velocity, bent_normals, exposure }) {
+        assert.ok(this.#built, 'graph_update() first');
+
+        const data = this.#resolve_data;
+        const pass = graph.add("Screen Probe Resolve", data, this.#execute_resolve);
+
+        data.depth = pass.read(depth);
+        data.depth_previous = pass.read(depth_previous);
+        data.pbr = pass.read(pbr);
+        data.velocity = pass.read(velocity);
+        data.bent_normals = pass.read(bent_normals);
+        data.exposure = pass.read(exposure);
+        data.diffuse = pass.write(graph_import_texture(graph, this.#diffuse[this.#temporal_parity], 'screen probe diffuse'));
+
+        pass.make_side_effect();
+
+        this.#diffuse_handle = data.diffuse;
+
+        return data.diffuse;
+    }
+
+    /**
+     * @returns {number} graph handle of the diffuse this frame's {@link graph_resolve} wrote
+     */
+    get diffuse_handle() {
+        return this.#diffuse_handle;
+    }
+
+    /**
+     * Put what the debug views read of the frame's probes into `bindings`: the frame uniform, the probes and their
+     * tiles' adaptive lists, the integration's output and the rays' hit words, as this frame left them.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_debug_bindings(bindings) {
+        bindings.screen_probe_frame = this.#frame_buffer;
+        bindings.screen_probes = this.#probes[this.#parity];
+        bindings.screen_probe_tile_counts = this.#tile_counts;
+        bindings.screen_probe_tile_probes = this.#tile_probes;
+        bindings.screen_probe_integrated = this.#integrated;
+        bindings.screen_probe_trace_hit = this.#trace_hit;
+
+        return bindings;
+    }
+
+    /**
+     * Keep the frame's lit colour of the opaque surfaces for the next frame's screen hits: once the indirect light is
+     * added, before fog and transparencies.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.color graph handle of the scene's colour, the view's size
+     */
+    graph_capture({ graph, color }) {
+        assert.ok(this.#built, 'graph_update() first');
+
+        const data = this.#capture_data;
+        const pass = graph.add("Screen Probe Capture", data, this.#execute_capture);
+
+        data.color = pass.read(color);
+
+        pass.make_side_effect();
+    }
+
+    /**
+     * The frame uniform, written as the frame is recorded.
+     *
+     * @param {import("../probe_clipmap/brick/GPUBrickClipmap.js").GPUBrickClipmap} bricks
+     * @param {ScreenProbeSettings} settings
+     */
+    #write_frame(bricks, settings) {
+        const u = this.#frame_u32;
+        const f = this.#frame_f32;
+        u[frame_word('view_size')] = this.#view_width;
+        u[frame_word('view_size') + 1] = this.#view_height;
+        u[frame_word('tile_count')] = this.#tiles_x;
+        u[frame_word('tile_count') + 1] = this.#tiles_y;
+        u[frame_word('jitter')] = this.#jitter[0];
+        u[frame_word('jitter') + 1] = this.#jitter[1];
+        u[frame_word('previous_jitter')] = this.#previous_jitter[0];
+        u[frame_word('previous_jitter') + 1] = this.#previous_jitter[1];
+        // the structure holds while the history does, so last frame's grid is this one's
+        u[frame_word('previous_tile_count')] = this.#tiles_x;
+        u[frame_word('previous_tile_count') + 1] = this.#tiles_y;
+        f[frame_word('tile_count_x_reciprocal')] = 1 / this.#tiles_x;
+        u[frame_word('downsample_shift')] = this.#downsample_shift;
+        u[frame_word('octahedron_resolution')] = this.#octahedron_resolution;
+        u[frame_word('octahedron_shift')] = this.#octahedron_shift;
+        u[frame_word('uniform_count')] = this.#uniform_count;
+        u[frame_word('adaptive_capacity')] = this.#adaptive_capacity;
+        u[frame_word('adaptive_tile_capacity')] = this.#adaptive_tile_capacity;
+        u[frame_word('frame_index')] = this.#frame;
+        u[frame_word('history')] = this.#history ? 1 : 0;
+
+        const coarsest = bricks.cascade_count - 1;
+
+        // past the coarsest window's far corner every ray has left the world
+        f[frame_word('brick_t_max')] = Math.sqrt(3) * bricks.resolution * bricks.cell_size(coarsest);
+        u[frame_word('importance_sampling')] = settings.importance_sampling && this.#octahedron_resolution <= SCREEN_PROBE_OCTAHEDRON_LIMIT ? 1 : 0;
+        u[frame_word('screen_traces')] = settings.screen_traces ? 1 : 0;
+        u[frame_word('brick_cascade_count')] = bricks.cascade_count;
+        u[frame_word('brick_atlas_shift')] = bricks.atlas_shift;
+        f[frame_word('temporal_frames')] = settings.temporal_frames;
+
+        this.#device.queue.writeBuffer(this.#frame_buffer, 0, this.#frame_data);
+
+    }
+
+    /**
+     * Make every resource for a view of `width` × `height` and the settings' structure, giving back what stood.
+     *
+     * @param {number} width
+     * @param {number} height
+     * @param {ScreenProbeSettings} settings
+     */
+    #build(width, height, settings) {
+        const D = settings.downsample_factor;
+        const n = settings.octahedron_resolution;
+        const limits = this.#device.limits;
+
+        const levels = screen_probe_adaptive_levels(D, settings.adaptive_min_downsample_factor);
+        const tile_capacity = screen_probe_adaptive_tile_capacity(levels);
+        const tiles_x = Math.ceil(width / D);
+        const tiles_y = Math.ceil(height / D);
+        const uniform_count = tiles_x * tiles_y;
+        const adaptive_capacity = screen_probe_adaptive_capacity(uniform_count, levels);
+        const probes = uniform_count + adaptive_capacity;
+        const rows = tiles_y + Math.ceil(adaptive_capacity / tiles_x);
+
+        // every limit before anything is given back or made, so a structure the device refuses leaves what stood
+        assert.lessThanOrEqual(n, SCREEN_PROBE_OCTAHEDRON_LIMIT, 'octahedron_resolution, what a probe\'s workgroup sorts and accumulates in its memory (SCREEN_PROBE_OCTAHEDRON_LIMIT)');
+        assert.lessThan(probes, 2 ** (32 - SCREEN_PROBE_RAY_SLOT_BITS), 'the frame\'s probes, a ray id\'s probe bits');
+        assert.lessThanOrEqual(tiles_x * n, limits.maxTextureDimension2D, 'the probes\' atlas width, the view over downsample_factor times octahedron_resolution, past maxTextureDimension2D');
+        assert.lessThanOrEqual(rows * n, limits.maxTextureDimension2D, 'the probes\' atlas height past maxTextureDimension2D');
+
+        const buffer_sizes = [
+            ['tile counts', 4 * uniform_count],
+            ['tile probes', 4 * uniform_count * tile_capacity],
+            ['probes', SCREEN_PROBE_STRUCT.size * probes],
+            ['picks', SCREEN_PROBE_PICK_STRUCT.size * probes],
+            ['brdf', 48 * probes],
+            ['moving', 4 * probes],
+            ['sh', 28 * probes],
+            ['rays', SCREEN_PROBE_RAY_STRUCT.size * probes * n * n],
+        ];
+
+        for (const [name, size] of buffer_sizes) {
+            assert.lessThanOrEqual(size, limits.maxStorageBufferBindingSize, `screen probe ${name} past maxStorageBufferBindingSize: fewer probes (a larger downsample_factor) or rays (a smaller octahedron_resolution)`);
+            assert.lessThanOrEqual(size, limits.maxBufferSize, `screen probe ${name} past maxBufferSize`);
+        }
+
+        this.release();
+
+        this.#view_width = width;
+        this.#view_height = height;
+        this.#downsample_factor = D;
+        this.#octahedron_resolution = n;
+        this.#adaptive_min_downsample_factor = settings.adaptive_min_downsample_factor;
+
+        this.#downsample_shift = Math.log2(D);
+        this.#octahedron_shift = Math.log2(n);
+        this.#adaptive_levels = levels;
+        this.#adaptive_tile_capacity = tile_capacity;
+
+        this.#tiles_x = tiles_x;
+        this.#tiles_y = tiles_y;
+        this.#uniform_count = uniform_count;
+        this.#adaptive_capacity = adaptive_capacity;
+
+        const device = this.#device;
+        const buffer = (name, size, usage = 0) => device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Screen probe / ${name}`,
+            size: Math.max(16, size),
+            usage: GPUBufferUsage.STORAGE | usage,
+        }));
+
+        this.#frame_buffer = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Screen probe / frame',
+            size: SCREEN_PROBE_FRAME_STRUCT.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        }));
+
+        this.#tile_counts = buffer('tile counts', 4 * uniform_count);
+        this.#tile_probes = buffer('tile probes', 4 * uniform_count * tile_capacity);
+        this.#dispatch = buffer('dispatch', 4 * SCREEN_PROBE_DISPATCH_WORDS, GPUBufferUsage.INDIRECT);
+        this.#counters = buffer('counters', 4 * SCREEN_PROBE_COUNTER_WORDS, GPUBufferUsage.COPY_DST);
+
+        const view_texture = (name, format) => this.#texture(`screen probe ${name}`, [width, height], format);
+
+        this.#integrated = view_texture('integrated', 'rgba16float');
+        this.#diffuse = [view_texture('diffuse 0', 'rgba16float'), view_texture('diffuse 1', 'rgba16float')];
+        this.#frames = [view_texture('frames 0', 'r32uint'), view_texture('frames 1', 'r32uint')];
+        this.#color_history = view_texture('color history', 'rgba16float');
+
+        const exposure_slot = name => device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Screen probe / ${name}`,
+            size: 16,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        }));
+
+        this.#exposure_history = [exposure_slot('exposure 0'), exposure_slot('exposure 1')];
+
+        this.#probes = [buffer('probes 0', SCREEN_PROBE_STRUCT.size * probes), buffer('probes 1', SCREEN_PROBE_STRUCT.size * probes)];
+        this.#picks = buffer('picks', SCREEN_PROBE_PICK_STRUCT.size * probes);
+        this.#brdf = buffer('brdf', 48 * probes);
+        this.#moving = buffer('moving', 4 * probes);
+        this.#sh = buffer('sh', 28 * probes);
+
+        this.#ray_capacity = probes * n * n;
+        this.#rays = buffer('rays', SCREEN_PROBE_RAY_STRUCT.size * this.#ray_capacity);
+
+        const atlas = [tiles_x * n, rows * n];
+
+        this.#ray_info = this.#texture('screen probe ray info', atlas, 'r32uint');
+        this.#trace_radiance = this.#texture('screen probe trace radiance', atlas, 'rgba16float');
+        this.#trace_hit = this.#texture('screen probe trace hit', atlas, 'r32uint');
+        this.#lighting_pdf = this.#texture('screen probe lighting pdf', atlas, 'r32float');
+        this.#radiance = [this.#texture('screen probe radiance 0', atlas, 'rgba16float'), this.#texture('screen probe radiance 1', atlas, 'rgba16float')];
+
+        this.#brick_command_settings.capacity = this.#ray_capacity;
+        this.#trace_screen_settings.capacity = this.#ray_capacity;
+
+        this.#built = true;
+        this.#history = false;
+        this.#recorded = false;
+    }
+
+    /**
+     * @param {string} label
+     * @param {number[]} size
+     * @param {GPUTextureFormat} format
+     * @returns {GPUTextureContext}
+     */
+    #texture(label, size, format) {
+        const texture = new GPUTextureContext(this.#device);
+
+        texture.descriptor = TextureDescriptor.from({
+            label,
+            size,
+            format,
+            mipLevelCount: 1,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        });
+
+        return texture;
+    }
+
+    #execute_place = (data, resources, context) => {
+        const encoder = context.encoder;
+        const b = this.#b;
+        const counters = resources.get(data.counters);
+
+        encoder.clearBuffer(counters);
+
+        b.screen_probe_frame = this.#frame_buffer;
+        b.camera = this.#view.camera.gpu_buffer;
+        b.camera_previous = this.#view.gpu_previous_camera_state.gpu_buffer;
+        b.tDepth = resources.get(data.depth);
+        b.tPBR = resources.get(data.pbr);
+        b.tVelocity = resources.get(data.velocity);
+        b.screen_probes = this.#probes[this.#parity];
+        b.screen_probe_tile_counts = this.#tile_counts;
+        b.screen_probe_tile_probes = this.#tile_probes;
+        b.screen_probe_counters = counters;
+        b.screen_probe_dispatch = this.#dispatch;
+
+        const groups = SCREEN_PROBE_TILE_WORKGROUP_SIZE;
+
+        shader_screen_probe_place_uniform.dispatch({
+            encoder,
+            bindings: b,
+            group_count_x: Math.ceil(this.#tiles_x / groups),
+            group_count_y: Math.ceil(this.#tiles_y / groups),
+        });
+
+        const settings = this.#adaptive_settings;
+
+        b.settings = settings;
+
+        for (let level = 1; level <= this.#adaptive_levels; level++) {
+            settings.level = level;
+
+            const spacing = this.#downsample_factor >>> level;
+
+            shader_screen_probe_place_adaptive.dispatch({
+                encoder,
+                bindings: b,
+                group_count_x: Math.ceil(Math.ceil(this.#view_width / spacing) / groups),
+                group_count_y: Math.ceil(Math.ceil(this.#view_height / spacing) / groups),
+            });
+        }
+
+        shader_screen_probe_command.dispatch({ encoder, bindings: b });
+    };
+
+    #execute_trace = (data, resources, context) => {
+        const encoder = context.encoder;
+        const b = this.#b;
+        const world = this.#world;
+        const view = this.#view;
+        const scene = view.scene;
+        const lights = scene.lights;
+        const dispatch = this.#dispatch;
+
+        const current = this.#probes[this.#parity];
+        const previous = this.#probes[1 - this.#parity];
+        const history_radiance = this.#radiance[this.#radiance_final];
+
+        b.screen_probe_frame = this.#frame_buffer;
+        b.camera = view.camera.gpu_buffer;
+        b.camera_previous = view.gpu_previous_camera_state.gpu_buffer;
+        b.screen_probes = current;
+        b.screen_probes_previous = previous;
+        b.screen_probe_picks = this.#picks;
+        b.screen_probe_dispatch = dispatch;
+        b.screen_probe_counters = resources.get(data.counters);
+        b.screen_probe_brdf = this.#brdf;
+        b.screen_probe_moving = this.#moving;
+        b.screen_probe_sh = this.#sh;
+        b.screen_probe_rays = this.#rays;
+        b.tSTBN_vec2 = this.#stbn;
+        b.tDepth = resources.get(data.depth);
+        b.tNormal = resources.get(data.normal);
+        b.tPBR = resources.get(data.pbr);
+        b.tVelocity = resources.get(data.velocity);
+        b.tOcclusion = resources.get(data.occlusion);
+        b.tHZB = resources.get(data.hzb);
+        b.screen_probe_exposure = resources.get(data.exposure);
+        b.screen_probe_exposure_previous = this.#exposure_history[1 - this.#parity];
+        b.screen_probe_color_history = this.#color_history.obtainView();
+        b.screen_probe_radiance_history = history_radiance.obtainView();
+        b.screen_probe_ray_info = this.#ray_info.obtainView();
+        b.screen_probe_trace_radiance = this.#trace_radiance.obtainView();
+        b.screen_probe_trace_hit = this.#trace_hit.obtainView();
+        b.screen_probe_lighting_pdf = this.#lighting_pdf.obtainView();
+
+        // the exposure this frame pre-exposes by, which next frame's lighting density brings last frame's radiance from
+        encoder.copyBufferToBuffer(b.screen_probe_exposure, 0, this.#exposure_history[this.#parity], 0, 4);
+
+        // the frustum's world-space probes: what the pick reads and the late set it wants into; the bricks' field, which
+        // places its rays' origin
+        world.probe_clipmap.write_sampling_bindings(b);
+        world.probe_clipmap.write_want_bindings(b);
+        world.brick_clipmap.write_bindings(b);
+
+        shader_screen_probe_pick.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_THREADS });
+
+        // the densities and the rays, a workgroup a probe
+        shader_screen_probe_brdf_pdf.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_PROBES });
+
+        if (this.#settings.importance_sampling) {
+            // the want pass's settings were the late set's; the pick's bindings stand for the radiance read here
+            world.probe_clipmap.write_sampling_bindings(b);
+
+            shader_screen_probe_lighting_pdf.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_PROBES });
+        }
+
+        shader_screen_probe_generate_rays.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_PROBES });
+
+        // the screen, then the bricks for what it left
+        b.settings = this.#trace_screen_settings;
+
+        shader_screen_probe_trace_screen.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_RAYS });
+
+        b.settings = this.#brick_command_settings;
+
+        shader_screen_probe_brick_command.dispatch({ encoder, bindings: b });
+
+        world.material.write_bindings(b);
+
+        b.light_data = lights.buffer_data;
+        b.tEnvironment = lights.environment.obtainView();
+        b.world_cluster_lookup = resources.get(data.cluster_lookup);
+        b.world_cluster_data = resources.get(data.cluster_data);
+
+        shader_screen_probe_brick_trace.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_BRICK_RAYS });
+
+        world.probe_clipmap.write_sampling_bindings(b);
+
+        shader_screen_probe_brick_shade.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_BRICK_RAYS });
+        shader_screen_probe_brick_light.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_BRICK_RAYS });
+
+        // the bounce from the frustum's world probes, the world cache's where they have none
+        const sets = this.#sets;
+
+        world.probe_clipmap.write_sampling_bindings(sets);
+        b.bounce_first_levels = sets.probe_levels;
+        b.bounce_first_sampling = sets.probe_sampling;
+        b.bounce_first_indirection = sets.probe_indirection;
+        b.bounce_first_states = sets.probe_states;
+        b.bounce_first_records = sets.probe_records;
+        b.bounce_first_depth = sets.probe_depth;
+
+        world.world_cache.write_sampling_bindings(sets);
+        b.bounce_fallback_levels = sets.probe_levels;
+        b.bounce_fallback_sampling = sets.probe_sampling;
+        b.bounce_fallback_indirection = sets.probe_indirection;
+        b.bounce_fallback_states = sets.probe_states;
+        b.bounce_fallback_records = sets.probe_records;
+        b.bounce_fallback_depth = sets.probe_depth;
+
+        shader_screen_probe_brick_bounce.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_BRICK_RAYS });
+
+        // the hits the frustum's probes did not serve want the world cache's
+        world.world_cache.write_want_bindings(b);
+
+        shader_screen_probe_brick_want.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_BRICK_RAYS });
+
+        // each probe's radiance from its rays, then the filter's passes trading the two atlases
+        const radiance = this.#radiance;
+        let write = 1 - this.#radiance_final;
+
+        b.screen_probe_radiance_out = radiance[write].obtainView();
+
+        shader_screen_probe_composite.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_PROBES });
+
+        for (let pass = 0; pass < this.#settings.spatial_filter_passes; pass++) {
+            b.screen_probe_radiance = radiance[write].obtainView();
+
+            write = 1 - write;
+
+            b.screen_probe_radiance_out = radiance[write].obtainView();
+
+            shader_screen_probe_filter.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_RAYS });
+        }
+
+        this.#radiance_final = write;
+
+        b.screen_probe_radiance = radiance[write].obtainView();
+
+        shader_screen_probe_irradiance.dispatchIndirect({ encoder, bindings: b, command: dispatch, command_offset: 4 * SCREEN_PROBE_DISPATCH_PROBES });
+    };
+
+    #execute_resolve = (data, resources, context) => {
+        const encoder = context.encoder;
+        const b = this.#b;
+        const groups = SCREEN_PROBE_TILE_WORKGROUP_SIZE;
+
+        b.screen_probe_frame = this.#frame_buffer;
+        b.camera = this.#view.camera.gpu_buffer;
+        b.camera_previous = this.#view.gpu_previous_camera_state.gpu_buffer;
+        b.screen_probes = this.#probes[this.#parity];
+        b.screen_probe_tile_counts = this.#tile_counts;
+        b.screen_probe_tile_probes = this.#tile_probes;
+        b.screen_probe_sh = this.#sh;
+        b.screen_probe_moving = this.#moving;
+        b.tSTBN_vec2 = this.#stbn;
+        b.tDepth = resources.get(data.depth);
+        b.tDepthPrevious = resources.get(data.depth_previous);
+        b.tPBR = resources.get(data.pbr);
+        b.tVelocity = resources.get(data.velocity);
+        b.tBentNormals = resources.get(data.bent_normals);
+        b.screen_probe_exposure = resources.get(data.exposure);
+        b.screen_probe_integrated = this.#integrated.obtainView();
+
+        const x = Math.ceil(this.#view_width / groups);
+        const y = Math.ceil(this.#view_height / groups);
+
+        shader_screen_probe_integrate.dispatch({ encoder, bindings: b, group_count_x: x, group_count_y: y });
+
+        const now = this.#temporal_parity;
+
+        b.screen_probe_diffuse_history = this.#diffuse[1 - now].obtainView();
+        b.screen_probe_frames_history = this.#frames[1 - now].obtainView();
+        b.screen_probe_diffuse = resources.get(data.diffuse);
+        b.screen_probe_frames = this.#frames[now].obtainView();
+
+        shader_screen_probe_temporal.dispatch({ encoder, bindings: b, group_count_x: x, group_count_y: y });
+    };
+
+    #execute_capture = (data, resources, context) => {
+        const b = this.#b;
+        const groups = SCREEN_PROBE_TILE_WORKGROUP_SIZE;
+
+        b.tColor = resources.get(data.color);
+        b.screen_probe_color_history = this.#color_history.obtainView();
+
+        shader_screen_probe_color_capture.dispatch({
+            encoder: context.encoder,
+            bindings: b,
+            group_count_x: Math.ceil(this.#view_width / groups),
+            group_count_y: Math.ceil(this.#view_height / groups),
+        });
+    };
+
+    #release_probe_resources() {
+        for (const buffer of [...this.#probes, this.#picks, this.#brdf, this.#moving, this.#sh, this.#rays]) {
+            buffer?.destroy();
+        }
+
+        for (const texture of [this.#ray_info, this.#trace_radiance, this.#trace_hit, this.#lighting_pdf, ...this.#radiance]) {
+            texture?.destroy();
+        }
+
+        this.#probes = [];
+        this.#picks = null;
+        this.#brdf = null;
+        this.#moving = null;
+        this.#sh = null;
+        this.#rays = null;
+        this.#ray_info = null;
+        this.#trace_radiance = null;
+        this.#trace_hit = null;
+        this.#lighting_pdf = null;
+        this.#radiance = [];
+    }
+
+    /**
+     * Give back every resource, as on the first frame out of the mode: the next {@link graph_update} starts again
+     * from nothing.
+     */
+    release() {
+        if (!this.#built) {
+            return;
+        }
+
+        this.#release_probe_resources();
+
+        for (const buffer of [this.#frame_buffer, this.#tile_counts, this.#tile_probes, this.#dispatch, this.#counters, ...this.#exposure_history]) {
+            buffer?.destroy();
+        }
+
+        for (const texture of [this.#integrated, ...this.#diffuse, ...this.#frames, this.#color_history]) {
+            texture?.destroy();
+        }
+
+        this.#frame_buffer = null;
+        this.#tile_counts = null;
+        this.#tile_probes = null;
+        this.#dispatch = null;
+        this.#counters = null;
+        this.#exposure_history = [];
+        this.#integrated = null;
+        this.#diffuse = [];
+        this.#frames = [];
+        this.#color_history = null;
+
+        this.#built = false;
+        this.#history = false;
+        this.#recorded = false;
+        this.#view = null;
+        this.#world = null;
+    }
+
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        this.release();
+    }
+}