@woosh/meep-engine 3.57.0 → 3.59.0

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js

@@ -0,0 +1,487 @@
+import { assert } from "../../../../core/assert.js";
+import { BufferDescriptor } from "../../../descriptor/buffer/BufferDescriptor.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { GPUBrickClipmap } from "./brick/GPUBrickClipmap.js";
+import { MeshSDFBrickProvider } from "./brick/mesh/MeshSDFBrickProvider.js";
+import { VGeoBrickProvider } from "./brick/vgeo/VGeoBrickProvider.js";
+import { graph_probe_clipmap_debug_brick_clipmap } from "./debug/graph_probe_clipmap_debug_brick_clipmap.js";
+import { graph_probe_clipmap_debug_mesh_cards } from "./debug/graph_probe_clipmap_debug_mesh_cards.js";
+import { graph_probe_clipmap_debug_mesh_sdf } from "./debug/graph_probe_clipmap_debug_mesh_sdf.js";
+import { ProbeClipmapDebugView } from "./debug/ProbeClipmapDebugView.js";
+import { PROBE_RECORD_STRUCT } from "./probe/chunk_probe_clipmap.js";
+import { PROBE_SAMPLING_STRUCT } from "./probe/chunk_probe_clipmap_pick.js";
+import { GPUProbeClipmap } from "./probe/GPUProbeClipmap.js";
+import { PROBE_DEPTH_TEXEL_RAYS } from "./probe/PROBE_CLIPMAP.js";
+import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
+
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ * @typedef {import("./ProbeClipmapSettings.js").ProbeClipmapSettings} ProbeClipmapSettings
+ * @typedef {import("./brick/GPUBrickClipmap.js").BrickProvider} BrickProvider
+ */
+
+/**
+ * {@link ShadeIndirectLightingMode.ProbeClipmap} for one view (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §5):
+ * a {@link GPUBrickClipmap}, the world as rays see it, and a {@link GPUProbeClipmap}, what shading
+ * samples, both around the view.
+ *
+ * The renderer holds one for its main view, as it holds the view's volumetrics, and hands it the view
+ * and the settings on every frame the mode runs ({@link graph_update}). The clipmaps are made on the
+ * first such frame, and made again when a frame is for another view or a structural setting has
+ * changed; {@link release} gives them back on the first frame out of the mode, and {@link destroy}
+ * with the renderer. Nothing is allocated before the mode first runs but the placeholders the probes'
+ * readers bind while there are no probes ({@link write_sampling_bindings}): seven objects of a few bytes,
+ * made on the first ask and kept until {@link destroy}.
+ *
+ * Each frame it holds the geometry caches and card sets its scene's SDF world draws
+ * ({@link ProbeClipmapSceneHolds}), trims the caches nothing holds, and records their bake and the
+ * cards' capture (§6). Leaving the mode lets go of the holds and trims nothing, so the caches are
+ * there when the mode comes back (D28); the card sets go, and are captured again.
+ *
+ * Until its probes are traced (§13, S4) the mode lights as IBL.
+ */
+export class GPUProbeClipmapGI {
+    /**
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUBrickClipmap|undefined}
+     */
+    #brick_clipmap = undefined;
+
+    /**
+     * @type {GPUProbeClipmap|undefined}
+     */
+    #probe_clipmap = undefined;
+
+    /**
+     * {@link GPUViewContext#id} of the view the clipmaps were made for: they hold what is around that
+     * view's camera, in that view's scene.
+     * @type {number}
+     */
+    #view_id = -1;
+
+    /**
+     * The view's scene's rows, as holds on their geometry caches; made for a scene on the first frame
+     * of the mode in it.
+     * @type {ProbeClipmapSceneHolds|undefined}
+     */
+    #holds = undefined;
+
+    #destroyed = false;
+
+    /**
+     * The plugins that write the world's bricks after the engine's own providers, in the order they
+     * were added (§7.6).
+     * @type {BrickProvider[]}
+     */
+    #plugins = [];
+
+    /**
+     * The mesh provider, made with the clipmaps and given back with them.
+     * @type {MeshSDFBrickProvider|undefined}
+     */
+    #mesh_provider = undefined;
+
+    /**
+     * The virtual geometry provider (§7.8), made with the clipmaps and given back with them.
+     * @type {VGeoBrickProvider|undefined}
+     */
+    #vgeo_provider = undefined;
+
+    /**
+     * Every provider in its order, the mesh provider first and the virtual geometry provider next:
+     * what a frame's build runs.
+     * @type {BrickProvider[]}
+     */
+    #providers = [];
+
+    /**
+     * What the probes' readers bind while there are no probes: a clipmap of no cascade, so their pick
+     * finds nothing. Made on the first ask.
+     * @type {{buffers: GPUBuffer[], textures: GPUTexture[], bindings: Object}|undefined}
+     */
+    #placeholders = undefined;
+
+    /**
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        assert.defined(graphics, 'graphics');
+
+        this.#graphics = graphics;
+    }
+
+    /**
+     * @returns {GPUBrickClipmap|undefined} undefined while the mode is not running
+     */
+    get brick_clipmap() {
+        return this.#brick_clipmap;
+    }
+
+    /**
+     * @returns {GPUProbeClipmap|undefined} undefined while the mode is not running
+     */
+    get probe_clipmap() {
+        return this.#probe_clipmap;
+    }
+
+    /**
+     * @returns {ProbeClipmapSceneHolds|undefined} undefined while the mode is not running
+     */
+    get holds() {
+        return this.#holds;
+    }
+
+    /**
+     * Take a frame of the mode: make the clipmaps for `view` and the structure `settings` describe,
+     * unless they already are, hold the scene's geometry caches and record their bake. Allocates nothing
+     * on a frame that changes neither and has nothing to bake.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view
+     * @param {ProbeClipmapSettings} options.settings the renderer's, read for this frame
+     * @param {number} options.depth graph handle of the view's depth, which the probes are wanted from
+     * @param {number} options.normal graph handle of the G-buffer's normals
+     * @param {*} options.stbn the 2-channel spatio-temporal blue noise, `STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`
+     * @param {number} options.time the caller's clock, seconds: what the probes' retention and response
+     *   times run on
+     * @param {number} [options.movers] the graph handle of the scene's mover list for the frame,
+     *   which the world's bricks are built again over
+     * @param {number} options.shadowmap_atlas graph handle of the frame's shadow map atlas, which shadows
+     *   the local lights at the probes' hits
+     */
+    graph_update({ graph, view, settings, depth, normal, stbn, time, movers = -1, shadowmap_atlas }) {
+        assert.defined(graph, 'graph');
+        assert.defined(view, 'view');
+        assert.defined(settings, 'settings');
+        assert.isNonNegativeInteger(depth, 'depth');
+        assert.isNonNegativeInteger(normal, 'normal');
+        assert.isNonNegativeInteger(shadowmap_atlas, 'shadowmap_atlas');
+        assert.isFinite(time, 'time');
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        // the relations between fields, checked here because each setter sees only its own field
+        assert.greaterThanOrEqual(settings.rays_per_probe, settings.radiance_resolution * settings.radiance_resolution / 4, 'rays_per_probe must be at least radiance_resolution² / 4');
+        assert.lessThanOrEqual(settings.rays_per_probe, 4 * settings.radiance_resolution * settings.radiance_resolution, 'rays_per_probe must be at most 4·radiance_resolution²');
+        assert.greaterThanOrEqual(settings.ray_budget, settings.rays_per_probe, 'ray_budget must be at least rays_per_probe');
+        assert.lessThanOrEqual(settings.rays_per_probe, PROBE_DEPTH_TEXEL_RAYS * settings.depth_resolution * settings.depth_resolution, 'rays_per_probe must be at most 64·depth_resolution², the rays a depth texel gathers');
+
+        if (
+            this.#brick_clipmap !== undefined
+            && (
+                view.id !== this.#view_id
+                || !this.#brick_clipmap.built_for(settings)
+                || !this.#probe_clipmap.built_for(settings)
+            )
+        ) {
+            this.release();
+        }
+
+        if (this.#brick_clipmap === undefined) {
+            this.#build(view, settings);
+        }
+
+        if (this.#holds === undefined) {
+            this.#holds = new ProbeClipmapSceneHolds(view.scene, this.#graphics);
+            this.#holds.attach();
+        }
+
+        const scene = view.scene;
+        const sdf = scene.geometries.sdf;
+        const materials = this.#graphics.materials_resident;
+
+        // the scene's materials as they are this frame: a repack recaptures its pairs
+        materials.ensure_scene_materials(scene);
+        materials.update();
+
+        sdf.configure(settings.mesh_sdf_voxel_size, settings.mesh_sdf_max_bricks);
+        sdf.trim();
+        sdf.graph_bake({
+            graph,
+            budget: settings.mesh_sdf_bake_budget,
+            capture_budget: settings.card_capture_budget,
+            materials,
+        });
+
+        // the card sets the capture made resident, for this frame's readers
+        this.#holds.flush();
+
+        // the world's bricks around the view, every provider merged in order, built again where the
+        // movers went and where a row's field turned resident or its SDF membership changed
+        this.#brick_clipmap.invalidate_rows(this.#holds.invalidated);
+        this.#holds.clear_invalidated();
+
+        const transform = view.camera.camera.transform;
+
+        const bricks = this.#brick_clipmap.graph_update({
+            graph,
+            x: transform[12],
+            y: transform[13],
+            z: transform[14],
+            budget: settings.brick_build_budget,
+            providers: this.#providers,
+            scene,
+            movers,
+        });
+
+        // the probes the frame's pixels want, around the same anchor, updated through the bricks (§8)
+        this.#probe_clipmap.graph_update({
+            graph,
+            x: transform[12],
+            y: transform[13],
+            z: transform[14],
+            depth,
+            normal,
+            camera: view.camera.buffer,
+            stbn,
+            resolution: view.resolution,
+            time,
+            retention_time: settings.retention_time,
+            response_time: settings.response_time,
+            ray_budget: settings.ray_budget,
+            rays_per_probe: settings.rays_per_probe,
+            brick_clipmap: this.#brick_clipmap,
+            bricks,
+            scene,
+            materials,
+            card_rows: this.#holds.rows_buffer,
+            shadowmap_atlas,
+        });
+    }
+
+    /**
+     * Whether the probes are there to read: the mode has run a frame and not been left since.
+     * @returns {boolean}
+     */
+    get has_probes() {
+        return this.#probe_clipmap !== undefined;
+    }
+
+    /**
+     * Put what the probes' readers bind into `bindings`, `PROBE_CLIPMAP_SAMPLING_GROUP` but its sampler:
+     * once {@link has_probes}, the probes as this frame's {@link graph_update} left them
+     * (`GPUProbeClipmap.write_sampling_bindings`); before that, or out of the mode, a clipmap of no
+     * cascade, whose pick finds nothing. A shader that can take this mode's alternative binds the group in
+     * every mode, as its variants share their resources.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_sampling_bindings(bindings) {
+        if (this.has_probes) {
+            return this.#probe_clipmap.write_sampling_bindings(bindings);
+        }
+
+        if (this.#placeholders === undefined) {
+            this.#placeholders = this.#make_placeholders();
+        }
+
+        return Object.assign(bindings, this.#placeholders.bindings);
+    }
+
+    /**
+     * A clipmap of no cascade, zeroed as made: its sampling uniform counts no cascade, so the pick selects
+     * none and reads nothing past the levels.
+     */
+    #make_placeholders() {
+        const device = this.#graphics.device;
+
+        const buffer = (name, size, usage) => device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Probe clipmap / placeholder ${name}`,
+            size,
+            usage,
+        }));
+
+        const levels = buffer('levels', CLIPMAP_LEVEL_ARRAY.size, GPUBufferUsage.UNIFORM);
+        const sampling = buffer('sampling', PROBE_SAMPLING_STRUCT.size, GPUBufferUsage.UNIFORM);
+        // a state and a record, the least a binding of their arrays holds
+        const states = buffer('states', 8, GPUBufferUsage.STORAGE);
+        const records = buffer('records', PROBE_RECORD_STRUCT.size, GPUBufferUsage.STORAGE);
+
+        const indirection = device.createTexture({
+            label: 'Probe clipmap / placeholder indirection',
+            size: [1, 1, 1],
+            dimension: '3d',
+            format: 'r32uint',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const depth = device.createTexture({
+            label: 'Probe clipmap / placeholder depth',
+            size: [1, 1],
+            format: 'rg16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+        const radiance = device.createTexture({
+            label: 'Probe clipmap / placeholder radiance',
+            size: [1, 1],
+            format: 'rgba16float',
+            usage: GPUTextureUsage.TEXTURE_BINDING,
+        });
+
+        return {
+            buffers: [levels, sampling, states, records],
+            textures: [indirection, depth, radiance],
+            bindings: {
+                probe_levels: levels,
+                probe_sampling: sampling,
+                probe_indirection: indirection.createView(),
+                probe_states: states,
+                probe_records: records,
+                probe_depth: depth.createView(),
+                probe_radiance: radiance.createView(),
+            },
+        };
+    }
+
+    /**
+     * The debug view the settings ask for, in place of the frame's colour. Record it after
+     * {@link graph_update} in the same frame.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view
+     * @param {ProbeClipmapSettings} options.settings
+     * @param {number[]} options.resolution
+     * @returns {number} graph handle of an `rgba8unorm` image
+     */
+    graph_debug_view({ graph, view, settings, resolution }) {
+        switch (settings.debug_view) {
+            case ProbeClipmapDebugView.MeshSDF:
+                return graph_probe_clipmap_debug_mesh_sdf({ graph, view, resolution });
+            case ProbeClipmapDebugView.MeshCards:
+                return graph_probe_clipmap_debug_mesh_cards({
+                    graph,
+                    view,
+                    resolution,
+                    cards: view.scene.geometries.sdf.cards,
+                    rows: this.#holds.rows_buffer,
+                });
+            case ProbeClipmapDebugView.BrickClipmap:
+                return graph_probe_clipmap_debug_brick_clipmap({ graph, view, resolution, brick_clipmap: this.#brick_clipmap });
+            default:
+                throw new Error(`no debug view to record for ${settings.debug_view}`);
+        }
+    }
+
+    /**
+     * Have a plugin write the world's bricks too, after the engine's own providers and every
+     * provider added before it, over the same taken cells (§7.6).
+     *
+     * @param {BrickProvider} provider
+     */
+    add_provider(provider) {
+        assert.defined(provider, 'provider');
+        assert.isFunction(provider.graph_write_bricks, 'provider.graph_write_bricks');
+        assert.notOk(this.#plugins.includes(provider), 'provider is added already');
+
+        this.#plugins.push(provider);
+        this.#order_providers();
+    }
+
+    /**
+     * @param {BrickProvider} provider
+     * @returns {boolean} whether it had been added
+     */
+    remove_provider(provider) {
+        const at = this.#plugins.indexOf(provider);
+
+        if (at < 0) {
+            return false;
+        }
+
+        this.#plugins.splice(at, 1);
+        this.#order_providers();
+
+        return true;
+    }
+
+    #order_providers() {
+        const providers = this.#providers;
+
+        providers.length = 0;
+
+        if (this.#mesh_provider !== undefined) {
+            providers.push(this.#mesh_provider, this.#vgeo_provider);
+        }
+
+        providers.push(...this.#plugins);
+    }
+
+    /**
+     * @param {GPUViewContext} view
+     * @param {ProbeClipmapSettings} settings
+     */
+    #build(view, settings) {
+        const device = this.#graphics.device;
+
+        this.#mesh_provider = new MeshSDFBrickProvider(device);
+        this.#vgeo_provider = new VGeoBrickProvider(device);
+        this.#order_providers();
+
+        this.#brick_clipmap = new GPUBrickClipmap(device, {
+            cascade_count: settings.brick_cascade_count,
+            resolution: settings.brick_cascade_resolution,
+            voxel_size: settings.brick_voxel_size,
+        });
+
+        this.#probe_clipmap = new GPUProbeClipmap(device, {
+            cascade_count: settings.probe_cascade_count,
+            resolution: settings.probe_cascade_resolution,
+            spacing: settings.probe_spacing,
+            radiance_resolution: settings.radiance_resolution,
+            depth_resolution: settings.depth_resolution,
+        });
+
+        this.#view_id = view.id;
+    }
+
+    /**
+     * Give back everything the mode holds, as on the first frame out of it: the clipmaps, and the holds
+     * on the geometry caches, which stay baked. The next {@link graph_update} starts again from nothing.
+     */
+    release() {
+        if (this.#holds !== undefined) {
+            this.#holds.detach();
+            this.#holds = undefined;
+        }
+
+        if (this.#brick_clipmap === undefined) {
+            return;
+        }
+
+        this.#brick_clipmap.destroy();
+        this.#probe_clipmap.destroy();
+        this.#mesh_provider.destroy();
+        this.#vgeo_provider.destroy();
+
+        this.#mesh_provider = undefined;
+        this.#vgeo_provider = undefined;
+        this.#order_providers();
+
+        this.#brick_clipmap = undefined;
+        this.#probe_clipmap = undefined;
+        this.#view_id = -1;
+    }
+
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        this.release();
+
+        if (this.#placeholders !== undefined) {
+            this.#placeholders.buffers.forEach(buffer => buffer.destroy());
+            this.#placeholders.textures.forEach(texture => texture.destroy());
+            this.#placeholders = undefined;
+        }
+    }
+}