@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -1,12 +1,16 @@
 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 { 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 { PROBE_DEPTH_TEXEL_RAYS, PROBE_RAYS_PER_TEXEL_MAX, PROBE_RAYS_PER_TEXEL_MIN } from "./probe/PROBE_CLIPMAP.js";
 import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
 
 /**
@@ -26,7 +30,9 @@ import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
  * 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.
+ * 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
@@ -86,6 +92,13 @@ export class GPUProbeClipmapGI {
      */
     #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
      */
@@ -128,23 +141,20 @@ export class GPUProbeClipmapGI {
      * @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
      */
-    graph_update({ graph, view, settings, depth, normal, stbn, time, movers = -1 }) {
+    graph_update({ graph, view, settings, depth, normal, stbn, movers = -1 }) {
         assert.defined(graph, 'graph');
         assert.defined(view, 'view');
         assert.defined(settings, 'settings');
         assert.isNonNegativeInteger(depth, 'depth');
         assert.isNonNegativeInteger(normal, 'normal');
-        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.rays_per_probe, PROBE_RAYS_PER_TEXEL_MIN * settings.radiance_resolution * settings.radiance_resolution, 'rays_per_probe must be at least radiance_resolution² / 4');
+        assert.lessThanOrEqual(settings.rays_per_probe, PROBE_RAYS_PER_TEXEL_MAX * 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');
 
@@ -178,11 +188,13 @@ export class GPUProbeClipmapGI {
 
         sdf.configure(settings.mesh_sdf_voxel_size, settings.mesh_sdf_max_bricks);
         sdf.trim();
+        sdf.cards.capture_mode = settings.card_capture_mode;
         sdf.graph_bake({
             graph,
             budget: settings.mesh_sdf_bake_budget,
             capture_budget: settings.card_capture_budget,
             materials,
+            material_contexts: this.#graphics.materials,
         });
 
         // the card sets the capture made resident, for this frame's readers
@@ -217,9 +229,7 @@ export class GPUProbeClipmapGI {
             camera: view.camera.buffer,
             stbn,
             resolution: view.resolution,
-            time,
-            retention_time: settings.retention_time,
-            response_time: settings.response_time,
+            response_frames: settings.response_frames,
             ray_budget: settings.ray_budget,
             rays_per_probe: settings.rays_per_probe,
             brick_clipmap: this.#brick_clipmap,
@@ -230,6 +240,90 @@ export class GPUProbeClipmapGI {
         });
     }
 
+    /**
+     * 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.
@@ -365,5 +459,11 @@ export class GPUProbeClipmapGI {
         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;
+        }
     }
 }