@woosh/meep-engine 3.61.2 → 3.62.0

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

@@ -10,16 +10,23 @@ import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.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_indirect } from "./debug/graph_probe_clipmap_debug_indirect.js";
+import {
+    graph_probe_clipmap_debug_brick_material,
+    ProbeClipmapDebugBrickMaterialChannel
+} from "./debug/graph_probe_clipmap_debug_brick_material.js";
 import { graph_probe_clipmap_debug_mesh_sdf } from "./debug/graph_probe_clipmap_debug_mesh_sdf.js";
+import { graph_probe_clipmap_debug_mesh_surfaces } from "./debug/graph_probe_clipmap_debug_mesh_surfaces.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, PROBE_RAY_CASCADE_MASK, PROBE_TEXEL_RAYS } from "./probe/PROBE_CLIPMAP.js";
 import { ProbeClipmapHitWants } from "./probe/ProbeClipmapHitWants.js";
+import { ProbeClipmapIndirectLobe } from "./probe/ProbeClipmapIndirectLobe.js";
 import { ProbeClipmapScreenWants } from "./probe/ProbeClipmapScreenWants.js";
 import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
+import { GPUBrickMaterial } from "./material/GPUBrickMaterial.js";
 
 /**
  * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
@@ -44,10 +51,11 @@ import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
  * 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.
+ * Each frame it holds the geometry caches and the Model Surface Caches its scene's SDF world draws
+ * ({@link ProbeClipmapSceneHolds}), trims the geometry caches nothing holds, and records their bakes
+ * (§6). The bricks' material is gathered from the surface caches as each brick is built
+ * ({@link GPUBrickMaterial}). Leaving the mode lets go of the holds and trims nothing, so the geometry
+ * caches are there when the mode comes back (D28); the surface caches go, and are baked again.
  *
  * Until its probes are traced (§13, S4) the mode lights as IBL.
  */
@@ -127,6 +135,19 @@ export class GPUProbeClipmapGI {
      */
     #placeholders = undefined;
 
+    /**
+     * The bricks' surface material, which the probes' hits read: made with the clipmaps and given back
+     * with them.
+     * @type {GPUBrickMaterial|undefined}
+     */
+    #material = undefined;
+
+    /**
+     * What the frame's build writes after its store: the material.
+     * @type {GPUBrickMaterial[]}
+     */
+    #material_writers = [];
+
     /**
      * @param {GraphicsContext} graphics
      */
@@ -226,18 +247,18 @@ export class GPUProbeClipmapGI {
         const sdf = scene.geometries.sdf;
         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,
+            surface_budget: settings.surface_bake_budget,
             materials: this.#graphics.materials_resident,
-            material_contexts: this.#graphics.materials,
         });
 
-        // the card sets the capture made resident, for this frame's readers
+        // the surface caches the bake made resident, for this frame's readers
         this.#holds.flush();
 
+        this.#material.surface_rows = this.#holds.surface_rows_buffer;
+
         // 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);
@@ -252,10 +273,13 @@ export class GPUProbeClipmapGI {
             z: transform[14],
             budget: settings.brick_build_budget,
             providers: this.#providers,
+            material_writers: this.#material_writers,
             scene,
             movers,
         });
 
+        const material = this.#material;
+
         const clusters = this.#graph_clusters(graph, scene);
 
         // the probes around the same anchor, updated through the bricks (§8): the frustum's windows, and the
@@ -279,7 +303,7 @@ export class GPUProbeClipmapGI {
             brick_clipmap: this.#brick_clipmap,
             bricks,
             scene,
-            card_rows: this.#holds.rows_buffer,
+            material,
             // a world cache probe re-samples nothing: its radiance has no skirt for the history's taps, and the
             // rays are the frustum's switch
             history_resampling: false,
@@ -301,7 +325,7 @@ export class GPUProbeClipmapGI {
             brick_clipmap: this.#brick_clipmap,
             bricks,
             scene,
-            card_rows: this.#holds.rows_buffer,
+            material,
             history_resampling: settings.history_resampling,
             ray_resampling: settings.ray_resampling,
             clusters,
@@ -450,27 +474,59 @@ export class GPUProbeClipmapGI {
      * The debug view the settings ask for, in place of the frame's colour. Record it after
      * {@link graph_update} in the same frame.
      *
+     * The indirect views draw the fused indirect pass (`shader_probe_clipmap_indirect_lighting`) with one lobe
+     * alone, from `indirect`, the inputs the frame's own fused pass takes, to which they add the probes' sampling
+     * bindings ({@link write_sampling_bindings}).
+     *
      * @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
+     * @param {Object} options.indirect the fused indirect pass's inputs this frame, without the probes' bindings
+     * @returns {number} graph handle of the image: `rgba8unorm` for the geometry views, `rgba16float` for the
+     * indirect ones
      */
-    graph_debug_view({ graph, view, settings, resolution }) {
+    graph_debug_view({ graph, view, settings, resolution, indirect }) {
         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({
+            case ProbeClipmapDebugView.MeshSurfaces:
+                return graph_probe_clipmap_debug_mesh_surfaces({
                     graph,
                     view,
                     resolution,
-                    cards: view.scene.geometries.sdf.cards,
-                    rows: this.#holds.rows_buffer,
+                    surfaces: view.scene.geometries.sdf.surfaces,
+                    rows: this.#holds.surface_rows_buffer,
                 });
             case ProbeClipmapDebugView.BrickClipmap:
                 return graph_probe_clipmap_debug_brick_clipmap({ graph, view, resolution, brick_clipmap: this.#brick_clipmap });
+            case ProbeClipmapDebugView.IndirectDiffuse:
+                return graph_probe_clipmap_debug_indirect({
+                    graph,
+                    lobe: ProbeClipmapIndirectLobe.Diffuse,
+                    inputs: this.write_sampling_bindings(indirect),
+                    resolution,
+                });
+            case ProbeClipmapDebugView.IndirectSpecular:
+                return graph_probe_clipmap_debug_indirect({
+                    graph,
+                    lobe: ProbeClipmapIndirectLobe.Specular,
+                    inputs: this.write_sampling_bindings(indirect),
+                    resolution,
+                });
+            case ProbeClipmapDebugView.BrickMaterial:
+            case ProbeClipmapDebugView.BrickMetalRough:
+                return graph_probe_clipmap_debug_brick_material({
+                    graph,
+                    view,
+                    resolution,
+                    brick_clipmap: this.#brick_clipmap,
+                    material: this.#material,
+                    channel: settings.debug_view === ProbeClipmapDebugView.BrickMaterial
+                        ? ProbeClipmapDebugBrickMaterialChannel.Albedo
+                        : ProbeClipmapDebugBrickMaterialChannel.MetalRough,
+                });
             default:
                 throw new Error(`no debug view to record for ${settings.debug_view}`);
         }
@@ -536,6 +592,11 @@ export class GPUProbeClipmapGI {
             voxel_size: settings.brick_voxel_size,
         });
 
+        this.#material = new GPUBrickMaterial(device, {
+            capacity: this.#brick_clipmap.capacity,
+        });
+        this.#material_writers.push(this.#material);
+
         // the frustum's slots start at 2·N²·C, a power of two: a visible surface crosses each cascade as a shell a
         // cell thick, doubled for the cage. The world cache's start there too: the surfaces that want it are the
         // frustum's hits', not the screen's, so its own lattice says nothing of how many there are
@@ -588,6 +649,10 @@ export class GPUProbeClipmapGI {
         this.#probe_clipmap.destroy();
         this.#world_cache.destroy();
         this.#mesh_provider.destroy();
+        this.#material.destroy();
+
+        this.#material = undefined;
+        this.#material_writers.length = 0;
 
         this.#mesh_provider = undefined;
         this.#order_providers();

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts

@@ -1,32 +1,38 @@
 /**
  * What the probe clipmap GI holds of one scene's geometry caches (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md
- * §6.1, §6.5), kept by entity and moved as the rows' events say, O(changes):
+ * §6.1), kept by entity and moved as the rows' events say, O(changes):
  *
  * - a hold on the cache of the geometry each mesh row in the SDF world draws, drawing both sides
  *   when the row's material does;
- * - one card set per (geometry, material) pair those rows draw, with the rows drawing each pair;
- * - the row → card set table readers find a row's card set in: the pair's once it is resident,
+ * - one Model Surface Cache per (geometry, material) pair those rows draw, with the rows drawing each
+ *   pair, which the brick material is gathered from;
+ * - the row → surface cache table readers find a row's cache in: the pair's once it is resident,
  *   `GPU_DATABASE_NULL` until then and for a row out of the SDF world.
  *
  * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`, whatever its geometry: a
  * virtual geometry's cache is held as a mesh's is, and is its proxy's once `VGeoSDFProxies` aliases it: the
- * hold and its side move to the proxy, and the pair's card set captures the proxy's layout.
+ * hold and its side move to the proxy, and the pair's cache follows the proxy's field.
  * A skinned row draws a clone: the hold and the pair are its source's,
- * whose unskinned field and cards the clone's header is aliased to (§6.3). A row written again moves
- * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps
- * drawing is never let go in between.
+ * whose unskinned field and caches the clone's header is aliased to (§6.3). A row written again moves
+ * its hold and its pair, the new ones taken before the old ones go, so a cache a row keeps drawing is
+ * never let go in between.
+ *
+ * Rows the world's bricks must be built again over are kept until drained: a row whose geometry's field
+ * turned resident, one that joined or left the SDF world (§6.4, §7.4), and each row of a pair whose
+ * surface cache a bake completed, the first and every one after, since the bricks hold the materials
+ * their caches held when each was gathered.
  *
  * When the material manager restages a material whose version moved, each of that material's pairs
- * is recaptured (§6.5), and the holds of its rows move to the side it draws now.
+ * is baked again, and the holds of its rows move to the side it draws now.
  *
- * {@link attach} subscribes and walks the rows already there; {@link detach} gives every hold and card
- * set back. Neither trims: a cache with no holder stays until its user trims, so leaving the mode keeps
- * the caches for the next time (D28). Card sets go with their last row, and are captured again.
+ * {@link attach} subscribes and walks the rows already there; {@link detach} gives every hold and cache
+ * back. Neither trims: a field with no holder stays until its user trims, so leaving the mode keeps
+ * the fields for the next time (D28). Caches go with their last row, and are made again.
  */
 export class ProbeClipmapSceneHolds {
     /**
      * @param {GPUSceneContext} scene
-     * @param {GraphicsContext} graphics whose material manager's restages recapture the pairs of the material
+     * @param {GraphicsContext} graphics whose material manager's restages bake the pairs of the material again
      */
     constructor(scene: GPUSceneContext, graphics: GraphicsContext);
     /**
@@ -39,12 +45,12 @@ export class ProbeClipmapSceneHolds {
      */
     get hold_count(): number;
     /**
-     * (geometry, material) pairs the rows draw, a card set each.
+     * (geometry, material) pairs the rows draw, a cache each.
      * @returns {number}
      */
     get pair_count(): number;
     /**
-     * Recaptures asked for, a pair each time its material was restaged.
+     * Bakes again asked for, a pair each time its material was restaged.
      * @returns {number}
      */
     get recaptures_requested(): number;
@@ -55,19 +61,20 @@ export class ProbeClipmapSceneHolds {
     get invalidated(): readonly number[];
     clear_invalidated(): void;
     /**
-     * The card set of the pair `material` makes with a geometry, or undefined when no row draws it.
+     * The Model Surface Cache of the pair `material` makes with a geometry, or undefined when no row
+     * draws it.
      *
      * @param {GPUGeometryMetadata} record
      * @param {ShadeMaterial} material
      * @returns {number|undefined}
      */
-    card_set_of(record: GPUGeometryMetadata, material: ShadeMaterial): number | undefined;
+    surface_cache_of(record: GPUGeometryMetadata, material: ShadeMaterial): number | undefined;
     /**
-     * The row → card set table: a word a `meshes` row. Made on first use, replaced when it grows; take it
-     * each frame, after {@link flush}.
+     * The row → Model Surface Cache table: a word a `meshes` row. Made on first use, replaced when it
+     * grows; take it each frame, after {@link flush}.
      * @returns {GPUBuffer}
      */
-    get rows_buffer(): GPUBuffer;
+    get surface_rows_buffer(): GPUBuffer;
     attach(): void;
     detach(): void;
     /**

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAwEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;OAMG;IACH,oBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,6BAIC;IAED,eAiBC;IAED,eAuCC;IAED;;OAEG;IACH,cAiBC;;CA4TJ;8BA3mBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;iCACvD,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,0BAA0B,EAAE,eAAe"}
+{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAyLA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAiEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;;OAOG;IACH,yBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,qCAEC;IAED,eAmBC;IAED,eAoCC;IAED;;OAEG;IACH,cAEC;;CA2RJ;8BAzrBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;iCACvD,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,0BAA0B,EAAE,eAAe"}