@woosh/meep-engine 3.61.2 → 3.62.0

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_brick_material.js

@@ -0,0 +1,208 @@
+import { assert } from "../../../../../core/assert.js";
+import { TextureResourceDescriptor } from "../../../../device/graph/TextureResourceDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_camera_ray_from_uv } from "../../../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ImageShader } from "../../../shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shader/ShaderDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    BRICK_ATLAS_TEXTURE_RESOURCE,
+    BRICK_LEVELS_RESOURCE,
+    BRICK_MAP_TEXTURE_RESOURCE,
+    BRICK_OCCUPANCY_TEXTURE_RESOURCE,
+    BRICK_SAMPLER_RESOURCE,
+    chunk_brick_clipmap_trace
+} from "../brick/chunk_brick_clipmap_trace.js";
+import {
+    BRICK_MATERIAL_ALBEDO_RESOURCE,
+    BRICK_MATERIAL_EMISSIVE_RESOURCE,
+    BRICK_MATERIAL_METAL_ROUGH_RESOURCE
+} from "../material/chunk_brick_material.js";
+import { chunk_probe_clipmap_hit_material, chunk_probe_clipmap_hit_metal_rough } from "../probe/chunk_probe_clipmap_hit_material.js";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ * @typedef {import("../brick/GPUBrickClipmap.js").GPUBrickClipmap} GPUBrickClipmap
+ */
+
+/**
+ * As far as a camera ray is traced: past every cascade, where the trace has already missed.
+ * @type {number}
+ */
+const FAR = 1e4;
+
+/**
+ * What {@link graph_probe_clipmap_debug_brick_material} shows of each hit.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ProbeClipmapDebugBrickMaterialChannel = {
+    /** diffuse albedo plus emissive */
+    Albedo: 0,
+    /** metalness in red, roughness in green */
+    MetalRough: 1,
+};
+
+/**
+ * @type {WebGPUStruct}
+ */
+const DEBUG_BRICK_MATERIAL_SETTINGS = WebGPUStruct.from({
+    cascade_count: u32,
+    /** a {@link ProbeClipmapDebugBrickMaterialChannel} */
+    channel: u32,
+}, "ProbeClipmapDebugBrickMaterialSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", DEBUG_BRICK_MATERIAL_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_LEVELS_RESOURCE)
+    .add(BRICK_MAP_TEXTURE_RESOURCE)
+    .add(BRICK_OCCUPANCY_TEXTURE_RESOURCE)
+    .add(BRICK_ATLAS_TEXTURE_RESOURCE)
+    .add(BRICK_SAMPLER_RESOURCE);
+
+resources.createGroup()
+    .add(BRICK_MATERIAL_ALBEDO_RESOURCE)
+    .add(BRICK_MATERIAL_METAL_ROUGH_RESOURCE)
+    .add(BRICK_MATERIAL_EMISSIVE_RESOURCE)
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+  @builtin(position) coord: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+) -> @location(0) vec4<f32> {
+    let ray = camera_ray_from_uv(uv, camera);
+
+    let hit = brick_clipmap_trace(ray.origin, ray.direction, 0.0, ${FAR.toFixed(1)}, settings.cascade_count);
+
+    if (hit.kind == BRICK_TRACE_MISS) {
+        return vec4<f32>(0.08, 0.08, 0.1, 1.0);
+    }
+
+    if (hit.kind == BRICK_TRACE_UNRESOLVED) {
+        // the march ran out of steps
+        return vec4<f32>(1.0, 0.0, 1.0, 1.0);
+    }
+
+    if (dot(hit.normal, ray.direction) > 0.0) {
+        // a back face: the probes count it and shade nothing (§8.4)
+        return vec4<f32>(0.1, 0.1, 0.4, 1.0);
+    }
+
+    if (settings.channel == ${ProbeClipmapDebugBrickMaterialChannel.Albedo}u) {
+        let material = probe_clipmap_hit_material(hit.position, hit.normal, hit.cascade);
+
+        if (!material.found) {
+            // the source does not know the surface: the hit is black to the probes
+            return vec4<f32>(0.3, 0.0, 0.0, 1.0);
+        }
+
+        return vec4<f32>(material.albedo + material.emissive, 1.0);
+    }
+
+    let metal_rough = probe_clipmap_hit_metal_rough(hit.position, hit.normal, hit.cascade);
+
+    if (metal_rough.z == 0.0) {
+        return vec4<f32>(0.3, 0.0, 0.0, 1.0);
+    }
+
+    return vec4<f32>(metal_rough.xy, 0.0, 1.0);
+}
+`, [
+        chunk_camera_ray_from_uv,
+        chunk_brick_clipmap_trace,
+        chunk_probe_clipmap_hit_material,
+        chunk_probe_clipmap_hit_metal_rough,
+    ]);
+
+/**
+ * The view's scene as the probes' rays read its material: each pixel's camera ray traced through the
+ * brick clipmap as {@link ProbeClipmapDebugView.BrickClipmap} traces it, and the hit's material read as
+ * the shade reads a probe ray's (`probe_clipmap_hit_material`), from the brick material: its diffuse
+ * albedo plus emissive, or its metalness and roughness.
+ *
+ * Dark red is a hit whose source does not know its surface, black to the probes; dark blue a back
+ * face, which they count and do not shade; magenta a ray whose steps ran out.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_brick_material = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap Debug / Brick Material",
+        resources,
+        body,
+    }),
+    targets: [{
+        format: "rgba8unorm"
+    }]
+});
+
+/**
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number[]} options.resolution
+ * @param {GPUBrickClipmap} options.brick_clipmap built this frame, before this pass
+ * @param {{write_bindings: function(Object): Object}} options.material what binds the brick material's planes
+ * @param {ProbeClipmapDebugBrickMaterialChannel} options.channel
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_brick_material({
+    graph,
+    view,
+    resolution,
+    brick_clipmap,
+    material,
+    channel
+}) {
+    assert.defined(graph, 'graph');
+    assert.defined(view, 'view');
+    assert.isArrayLike(resolution, 'resolution');
+    assert.defined(brick_clipmap, 'brick_clipmap');
+    assert.isFunction(material?.write_bindings, 'material.write_bindings');
+    assert.enum(channel, ProbeClipmapDebugBrickMaterialChannel, 'channel');
+
+    const data = {};
+    const settings = { cascade_count: brick_clipmap.cascade_count, channel };
+
+    const pass = graph.add("Probe Clipmap Debug / Brick Material", data, (data, resources, context) => {
+        const output = resources.get(data.output);
+        const bindings = {
+            settings,
+            camera: view.camera.buffer,
+        };
+
+        brick_clipmap.write_bindings(bindings);
+        material.write_bindings(bindings);
+
+        shader_probe_clipmap_debug_brick_material.draw({
+            encoder: context.encoder,
+            bindings,
+            colorAttachments: [{
+                loadOp: "clear",
+                storeOp: "store",
+                clearValue: [0, 0, 0, 1],
+                view: output.obtainView(),
+            }],
+        });
+    });
+
+    data.output = pass.create("probe_clipmap_debug", TextureResourceDescriptor.from({
+        format: "rgba8unorm",
+        resolution,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+    }));
+
+    return data.output;
+}

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_indirect.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+/**
+ * The light one lobe of the probe clipmap's indirect light is made of, before the surface's material and occlusion:
+ * the fused indirect pass's variant that writes only that ({@link PROBE_CLIPMAP_INDIRECT_LOBE}), drawn over opaque black, so the background, which the pass does
+ * not draw, stays black.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {ProbeClipmapIndirectLobe} options.lobe
+ * @param {Object} options.inputs the fused pass's inputs, the probes' sampling bindings among them
+ * @param {number[]} options.resolution the G-buffer's
+ * @returns {number} graph handle of the `rgba16float` image
+ */
+export function graph_probe_clipmap_debug_indirect({ graph, lobe, inputs, resolution }: {
+    graph: FrameGraph;
+    lobe: ProbeClipmapIndirectLobe;
+    inputs: any;
+    resolution: number[];
+}): number;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+import { ProbeClipmapIndirectLobe } from "../probe/ProbeClipmapIndirectLobe.js";
+//# sourceMappingURL=graph_probe_clipmap_debug_indirect.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_indirect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_debug_indirect.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_indirect.js"],"names":[],"mappings":"AAOA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH;IAN+B,KAAK,EAAzB,UAAU;IACwB,IAAI,EAAtC,wBAAwB;IACR,MAAM;IACJ,UAAU,EAA5B,MAAM,EAAE;IACN,MAAM,CAkBlB;yBA/BY,OAAO,iEAAiE,EAAE,UAAU;yCAJxD,sCAAsC"}

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_indirect.js

@@ -0,0 +1,40 @@
+import { assert } from "../../../../../core/assert.js";
+import { ShaderSwitchSet } from "../../../shader/compiler/ShaderSwitchSet.js";
+import { graph_image_pass } from "../../../shader/graph/graph_image_pass.js";
+import { PROBE_CLIPMAP_INDIRECT_LOBE } from "../probe/PROBE_CLIPMAP_INDIRECT_LOBE.js";
+import { ProbeClipmapIndirectLobe } from "../probe/ProbeClipmapIndirectLobe.js";
+import { shader_probe_clipmap_indirect_lighting } from "../probe/shader_probe_clipmap_indirect_lighting.js";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * The light one lobe of the probe clipmap's indirect light is made of, before the surface's material and occlusion:
+ * the fused indirect pass's variant that writes only that ({@link PROBE_CLIPMAP_INDIRECT_LOBE}), drawn over opaque black, so the background, which the pass does
+ * not draw, stays black.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {ProbeClipmapIndirectLobe} options.lobe
+ * @param {Object} options.inputs the fused pass's inputs, the probes' sampling bindings among them
+ * @param {number[]} options.resolution the G-buffer's
+ * @returns {number} graph handle of the `rgba16float` image
+ */
+export function graph_probe_clipmap_debug_indirect({ graph, lobe, inputs, resolution }) {
+    assert.defined(graph, 'graph');
+    assert.enum(lobe, ProbeClipmapIndirectLobe, 'lobe');
+    assert.defined(inputs, 'inputs');
+    assert.isArrayLike(resolution, 'resolution');
+
+    const [image] = graph_image_pass({
+        graph,
+        shader: shader_probe_clipmap_indirect_lighting.variant(ShaderSwitchSet.EMPTY.with(PROBE_CLIPMAP_INDIRECT_LOBE, lobe)),
+        inputs,
+        input_depth: inputs.tDepth,
+        output_resolution: resolution,
+        clear_value: [0, 0, 0, 1],
+    });
+
+    return image;
+}

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_surfaces.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number[]} options.resolution
+ * @param {GPUMeshSurfaceCaches} options.surfaces
+ * @param {GPUBuffer} options.rows the row → surface cache table
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_mesh_surfaces({ graph, view, resolution, surfaces, rows }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    resolution: number[];
+    surfaces: GPUMeshSurfaceCaches;
+    rows: GPUBuffer;
+}): number;
+/**
+ * The view's scene through its geometry caches and Model Surface Caches: each pixel's camera ray is
+ * marched through the meshes' sparse fields as in {@link ProbeClipmapDebugView.MeshSDF}, and at the
+ * nearest hit the row's surface cache is read at the field's finest level (`mesh_surface_sample`), as
+ * the brick material's gather reads it for a texel. It shows the diffuse albedo plus emissive the cache
+ * holds.
+ *
+ * Purple is a row with no surface cache readers may use yet; dark red a point no texel of the cache
+ * holds, which a GI hit takes as black.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_mesh_surfaces: ImageShader;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUViewContext = import("../../../view/GPUViewContext.js").GPUViewContext;
+export type GPUMeshSurfaceCaches = import("../../../geometry/sdf/surface/GPUMeshSurfaceCaches.js").GPUMeshSurfaceCaches;
+import { ImageShader } from "../../../shader/ImageShader.js";
+//# sourceMappingURL=graph_probe_clipmap_debug_mesh_surfaces.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_debug_mesh_surfaces.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_surfaces.js"],"names":[],"mappings":"AA2HA;;;;;;;;GAQG;AACH;IAP+B,KAAK,EAAzB,UAAU;IACc,IAAI,EAA5B,cAAc;IACI,UAAU,EAA5B,MAAM,EAAE;IACsB,QAAQ,EAAtC,oBAAoB;IACD,IAAI;IACrB,MAAM,CAuClB;AArED;;;;;;;;;;;GAWG;AACH,uDAFU,WAAW,CAWlB;yBAzFU,OAAO,iEAAiE,EAAE,UAAU;6BACpF,OAAO,iCAAiC,EAAE,cAAc;mCACxD,OAAO,uDAAuD,EAAE,oBAAoB;4BAVrE,gCAAgC"}

package/src/shade/renderer/global_illumination/probe_clipmap/debug/{graph_probe_clipmap_debug_mesh_cards.js → graph_probe_clipmap_debug_mesh_surfaces.js}

@@ -2,14 +2,6 @@ import { assert } from "../../../../../core/assert.js";
 import { TextureResourceDescriptor } from "../../../../device/graph/TextureResourceDescriptor.js";
 import { GPU_DATABASE_NULL } from "../../../buffer/table/GPU_DATABASE_NULL.js";
 import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { chunk_mesh_card_surface } from "../../../geometry/sdf/cards/chunk_mesh_card_surface.js";
-import {
-    MESH_CARD_ALBEDO_RESOURCE,
-    MESH_CARD_EMISSIVE_RESOURCE,
-    MESH_CARD_ROWS_RESOURCE,
-    MESH_CARD_SETS_RESOURCE
-} from "../../../geometry/sdf/cards/MESH_CARD_RESOURCES.js";
-import { chunk_mesh_sdf_normal } from "../../../geometry/sdf/chunk_mesh_sdf_normal.js";
 import { chunk_mesh_sdf_header } from "../../../geometry/sdf/chunk_mesh_sdf_sample.js";
 import {
     MESH_SDF_ATLAS_RESOURCE,
@@ -17,6 +9,12 @@ import {
     MESH_SDF_INDIRECTION_RESOURCE,
     MESH_SDF_SAMPLER_RESOURCE
 } from "../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { chunk_mesh_surface_sample } from "../../../geometry/sdf/surface/chunk_mesh_surface_sample.js";
+import {
+    MESH_SURFACE_DATA_RESOURCE,
+    MESH_SURFACE_RECORDS_RESOURCE,
+    MESH_SURFACE_ROWS_RESOURCE
+} from "../../../geometry/sdf/surface/MESH_SURFACE_RESOURCES.js";
 import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
 import { BVH_STRUCT } from "../../../shader/chunk/bvh/BVH_STRUCT.js";
 import { chunk_mat4_inverse } from "../../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
@@ -29,19 +27,13 @@ import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderReso
 import { ShaderDescriptor } from "../../../shader/ShaderDescriptor.js";
 import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { BRICK_TRACE_HIT_VOXELS } from "../brick/chunk_brick_clipmap_trace.js";
 
 /**
  * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
  * @typedef {import("../../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
- * @typedef {import("../../../geometry/sdf/cards/GPUMeshCardSets.js").GPUMeshCardSets} GPUMeshCardSets
- */
-
-/**
- * The tolerance a card's depth is held to, in voxels of the hit's geometry: a hit marched through a
- * mesh's own field is as exact as its finest cascade would be (§6.6).
- * @type {number}
+ * @typedef {import("../../../geometry/sdf/surface/GPUMeshSurfaceCaches.js").GPUMeshSurfaceCaches} GPUMeshSurfaceCaches
  */
-const TOLERANCE_VOXELS = 1.5;
 
 const resources = new ShaderResourceSetDescriptor();
 
@@ -54,10 +46,9 @@ resources.createGroup()
     .addStorageBuffer("tlas", BVH_STRUCT);
 
 resources.createGroup()
-    .add(MESH_CARD_SETS_RESOURCE)
-    .add(MESH_CARD_ROWS_RESOURCE)
-    .add(MESH_CARD_ALBEDO_RESOURCE)
-    .add(MESH_CARD_EMISSIVE_RESOURCE)
+    .add(MESH_SURFACE_RECORDS_RESOURCE)
+    .add(MESH_SURFACE_ROWS_RESOURCE)
+    .add(MESH_SURFACE_DATA_RESOURCE)
     .addUniform("camera", CAMERA_UNIFORM_STRUCT);
 
 const body = CodeChunk.from(
@@ -76,31 +67,26 @@ fn main(
         return vec4<f32>(0.08, 0.08, 0.1, 1.0);
     }
 
-    let point = ray.origin + hit.t * ray.direction;
-    let card_set = mesh_card_rows[hit.mesh];
+    let cache = mesh_surface_rows[hit.mesh];
 
-    if (card_set == ${GPU_DATABASE_NULL}u) {
-        // no card set readers may use yet: the pair is waiting or capturing
+    if (cache == ${GPU_DATABASE_NULL}u) {
+        // no surface cache readers may use yet: the pair is waiting or baking
         return vec4<f32>(0.3, 0.0, 0.3, 1.0);
     }
 
     let mesh = scene_read_mesh(&scene_database, hit.mesh);
     let node = scene_read_node(&scene_database, mesh.node);
 
-    let p = (mat4_inverse(node.global) * vec4<f32>(point, 1.0)).xyz;
-
-    // the field's own normal there: a screen-space one turns to the wrong axis at grazing angles
-    let header = mesh_sdf_header(mesh.geometry);
-    let n = mesh_sdf_normal(header, 0u, p);
+    let p = (mat4_inverse(node.global) * vec4<f32>(ray.origin + hit.t * ray.direction, 1.0)).xyz;
 
-    let surface = mesh_card_surface(card_set, p, n, ${TOLERANCE_VOXELS.toFixed(1)} * header.voxel);
+    let seen = mesh_surface_sample(mesh_surface_records[cache], mesh_sdf_header(mesh.geometry), 0u, p, ${BRICK_TRACE_HIT_VOXELS});
 
-    if (!surface.found) {
-        // no card sees the point: the hit would take the material's mean
+    if (!seen.found) {
+        // no texel of the cache holds the point's surface: a GI hit there is black
         return vec4<f32>(0.3, 0.0, 0.0, 1.0);
     }
 
-    return vec4<f32>(surface.albedo + surface.emissive, 1.0);
+    return vec4<f32>(seen.albedo + seen.emissive, 1.0);
 }
 `, [
         F32_MAX_DEFINITION,
@@ -109,25 +95,24 @@ fn main(
         chunk_mat4_inverse,
         chunk_scene_sdf_raymarch_hit,
         chunk_mesh_sdf_header,
-        chunk_mesh_sdf_normal,
-        chunk_mesh_card_surface,
+        chunk_mesh_surface_sample,
     ]);
 
 /**
- * The view's scene through its geometry caches and cards: each pixel's camera ray is marched through
- * the meshes' sparse fields as in {@link ProbeClipmapDebugView.MeshSDF}, and at the nearest hit the
- * row's card set is asked what the surface is (`mesh_card_surface`), with the field's normal there
- * and at the tolerance of a hit as exact as the mesh's own voxel. It shows the diffuse albedo plus
- * emissive the cards hold.
+ * The view's scene through its geometry caches and Model Surface Caches: each pixel's camera ray is
+ * marched through the meshes' sparse fields as in {@link ProbeClipmapDebugView.MeshSDF}, and at the
+ * nearest hit the row's surface cache is read at the field's finest level (`mesh_surface_sample`), as
+ * the brick material's gather reads it for a texel. It shows the diffuse albedo plus emissive the cache
+ * holds.
  *
- * Purple is a row with no card set readers may use yet; dark red a point no card sees, which a GI
- * hit would give the material's mean.
+ * Purple is a row with no surface cache readers may use yet; dark red a point no texel of the cache
+ * holds, which a GI hit takes as black.
  *
  * @type {ImageShader}
  */
-export const shader_probe_clipmap_debug_mesh_cards = new ImageShader({
+export const shader_probe_clipmap_debug_mesh_surfaces = new ImageShader({
     descriptor: ShaderDescriptor.from({
-        label: "Probe Clipmap Debug / Mesh Cards",
+        label: "Probe Clipmap Debug / Mesh Surfaces",
         resources,
         body,
     }),
@@ -141,35 +126,31 @@ export const shader_probe_clipmap_debug_mesh_cards = new ImageShader({
  * @param {FrameGraph} options.graph
  * @param {GPUViewContext} options.view
  * @param {number[]} options.resolution
- * @param {GPUMeshCardSets} options.cards
- * @param {GPUBuffer} options.rows the row → card set table
+ * @param {GPUMeshSurfaceCaches} options.surfaces
+ * @param {GPUBuffer} options.rows the row → surface cache table
  * @returns {number} graph handle of the `rgba8unorm` image
  */
-export function graph_probe_clipmap_debug_mesh_cards({ graph, view, resolution, cards, rows }) {
+export function graph_probe_clipmap_debug_mesh_surfaces({ graph, view, resolution, surfaces, rows }) {
     assert.defined(graph, 'graph');
     assert.defined(view, 'view');
     assert.isArrayLike(resolution, 'resolution');
-    assert.defined(cards, 'cards');
+    assert.defined(surfaces, 'surfaces');
     assert.defined(rows, 'rows');
 
     const data = {};
 
-    const pass = graph.add("Probe Clipmap Debug / Mesh Cards", data, (data, resources, context) => {
+    const pass = graph.add("Probe Clipmap Debug / Mesh Surfaces", data, (data, resources, context) => {
         const scene = view.scene;
         const output = resources.get(data.output);
-        const atlas = cards.atlas;
 
-        shader_probe_clipmap_debug_mesh_cards.draw({
+        shader_probe_clipmap_debug_mesh_surfaces.draw({
             encoder: context.encoder,
-            bindings: scene.geometries.sdf.write_bindings({
+            bindings: surfaces.write_bindings(scene.geometries.sdf.write_bindings({
                 scene_database: scene.scene_database_buffer,
                 tlas: scene.tlas.buffer,
                 camera: view.camera.buffer,
-                mesh_card_sets: cards.records,
-                mesh_card_rows: rows,
-                mesh_card_albedo: atlas.texture_at(0).obtainView(),
-                mesh_card_emissive: atlas.texture_at(1).obtainView(),
-            }),
+                mesh_surface_rows: rows,
+            })),
             colorAttachments: [{
                 loadOp: "clear",
                 storeOp: "store",

package/src/shade/renderer/global_illumination/probe_clipmap/material/GPUBrickMaterial.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The brick clipmap's surface material (`chunk_brick_material.js`): a texel of material a texel of
+ * every brick, gathered from the Model Surface Caches of the surfaces the brick's texels hold when the
+ * brick is built.
+ *
+ * **Storage**: a {@link GPUTileAtlas3D} of the planes `SURFACE_MATERIAL_FORMATS` lists, 8³ a tile, a tile
+ * for each of the brick clipmap's slots, at the slot's index: it reserves the clipmap's capacity at
+ * every build, so it grows when the clipmap does. Readers bind its planes through
+ * {@link write_bindings}.
+ *
+ * **A frame**: the brick clipmap runs it after its store ({@link graph_write_material}), over the
+ * cells the frame took: the gather (`shader_brick_material_gather`) clears their texels and gives each
+ * that holds a surface the material of that surface's cache, through {@link surface_rows}. It reads the
+ * caches, the fields and the transforms the mesh provider read: no ray, no BLAS, no material table.
+ *
+ * A cell that is not rebuilt keeps its material: a cache baked again reaches the bricks through its
+ * rows being invalidated (`ProbeClipmapSceneHolds`).
+ */
+export class GPUBrickMaterial {
+    /**
+     * @param {GPUDevice} device
+     * @param {object} options
+     * @param {number} options.capacity slots to start with: the brick clipmap's
+     */
+    constructor(device: GPUDevice, { capacity }: {
+        capacity: number;
+    });
+    /**
+     * The row → Model Surface Cache table the gather finds a texel's cache in, a word a `meshes` row
+     * (`ProbeClipmapSceneHolds#surface_rows_buffer`). Replaced when it grows: set it each frame.
+     * @type {GPUBuffer|null}
+     */
+    surface_rows: GPUBuffer | null;
+    /**
+     * @returns {GPUTileAtlas3D}
+     */
+    get atlas(): GPUTileAtlas3D;
+    /**
+     * Put what the material's readers (`chunk_brick_material.js`) take into their bindings, under the
+     * names they take. The planes are replaced when the capacity grows: take them each frame.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_bindings(bindings: any): any;
+    /**
+     * Record the gather of the frame's taken cells, after the brick clipmap's store: `GPUBrickClipmap`
+     * calls it from its build with the build's context, the store's state handle in it, and its handle
+     * is replaced with this pass's, which the bricks' readers come after.
+     *
+     * @param {FrameGraph} graph
+     * @param {BrickProviderContext} context
+     */
+    graph_write_material(graph: FrameGraph, context: BrickProviderContext): void;
+    destroy(): void;
+    #private;
+}
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type BrickProviderContext = import("../brick/GPUBrickClipmap.js").BrickProviderContext;
+import { GPUTileAtlas3D } from "../../../texture/atlas/GPUTileAtlas3D.js";
+//# sourceMappingURL=GPUBrickMaterial.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/material/GPUBrickMaterial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUBrickMaterial.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/material/GPUBrickMaterial.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;GAiBG;AACH;IAyBI;;;;OAIG;IACH;QAF2B,QAAQ,EAAxB,MAAM;OAsBhB;IAhCD;;;;OAIG;IACH,cAFU,YAAU,IAAI,CAEJ;IA6BpB;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,mCAMC;IAED;;;;;;;OAOG;IACH,4BAHW,UAAU,WACV,oBAAoB,QAuB9B;IAuCD,gBAQC;;CACJ;yBAnLY,OAAO,iEAAiE,EAAE,UAAU;mCACpF,OAAO,6BAA6B,EAAE,oBAAoB;+BANxC,0CAA0C"}