@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_take.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_brick_clipmap_take.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_take.js"],"names":[],"mappings":"AASA;;GAEG;AACH,kCAFU,YAAY,CAKE;AAUxB;;;;;;;;;;;GAWG;AACH,wCAFU,aAAa,CA2CpB;6BAxE0B,sCAAsC;8BAJrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_take.js

@@ -0,0 +1,79 @@
+import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { BRICK_STATE_RESOURCE, chunk_brick_clipmap } from "./chunk_brick_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const BRICK_TAKE_SETTINGS = WebGPUStruct.from({
+    /** cells built a frame at most, `brick_build_budget` */
+    budget: u32,
+}, "BrickTakeSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", BRICK_TAKE_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_STATE_RESOURCE)
+    .addStorageBuffer("brick_take", WebGPUArray.u32, true);
+
+/**
+ * Take (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.4): one thread. The frame's keys off the ring, as many
+ * as are queued up to the budget, and no more than there are free slots, since every cell taken may
+ * need one: so no pop of store's fails. A take the free slots held back counts itself starved, and the
+ * host grows the capacity, as the mesh bake does (§6.4).
+ *
+ * Build slot `b` is taken key `b`, at ring position `taken_first + b`. Writes them, and the frame's
+ * two dispatches, folded past the per-dimension limit, into `brick_take`: a workgroup a taken cell,
+ * and a thread a staging word of the taken cells.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_brick_clipmap_take = ComputeShader.from({
+    label: "Brick Clipmap Take",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+fn write_folded_dispatch(at: u32, groups: u32) {
+    let folded = folded_dispatch(groups);
+
+    brick_take[at] = folded.x;
+    brick_take[at + 1u] = folded.y;
+    brick_take[at + 2u] = folded.z;
+}
+
+@compute @workgroup_size(1)
+fn main() {
+    let head = atomicLoad(&brick_state[BRICK_STATE_HEAD]);
+    let tail = atomicLoad(&brick_state[BRICK_STATE_TAIL]);
+    let free_slots = atomicLoad(&brick_state[BRICK_STATE_FREE]);
+
+    // positions run on through the u32 wrap; the ring's capacity is a power of two, which divides it
+    let queued = tail - head;
+    let wanted = min(queued, settings.budget);
+    let taken = min(wanted, free_slots);
+
+    atomicStore(&brick_state[BRICK_STATE_HEAD], head + taken);
+
+    brick_take[BRICK_TAKE_FIRST] = head;
+    brick_take[BRICK_TAKE_COUNT] = taken;
+
+    if (taken < wanted) {
+        atomicAdd(&brick_state[BRICK_STATE_STARVED], 1u);
+    }
+
+    write_folded_dispatch(BRICK_TAKE_CELL_DISPATCH, taken);
+    write_folded_dispatch(BRICK_TAKE_WORD_DISPATCH, (taken * BRICK_STAGING_WORDS + BRICK_THREAD_WORKGROUP_SIZE - 1u) / BRICK_THREAD_WORKGROUP_SIZE);
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_folded_dispatch,
+        ]),
+});

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

@@ -0,0 +1,11 @@
+/**
+ * What {@link ProbeClipmapSettingsdebug_view } shows in place of the frame's colour, before TAA.
+ */
+export type ProbeClipmapDebugView = number;
+export namespace ProbeClipmapDebugView {
+    let None: number;
+    let MeshSDF: number;
+    let MeshCards: number;
+    let BrickClipmap: number;
+}
+//# sourceMappingURL=ProbeClipmapDebugView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ProbeClipmapDebugView.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/ProbeClipmapDebugView.js"],"names":[],"mappings":";;;oCAIU,MAAM"}

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

@@ -0,0 +1,16 @@
+/**
+ * What {@link ProbeClipmapSettings#debug_view} shows in place of the frame's colour, before TAA.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const ProbeClipmapDebugView = {
+    /** the frame as rendered */
+    None: 0,
+    /** the scene as its geometry caches have it: camera rays marched through every mesh's sparse field */
+    MeshSDF: 1,
+    /** the same hits, each shown as its row's cards see it: diffuse albedo plus emissive */
+    MeshCards: 2,
+    /** the scene as the probe clipmap's rays see it: camera rays traced through the brick clipmap */
+    BrickClipmap: 3,
+};

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

@@ -0,0 +1,29 @@
+/**
+ * @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
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_brick_clipmap({ graph, view, resolution, brick_clipmap }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    resolution: number[];
+    brick_clipmap: GPUBrickClipmap;
+}): number;
+/**
+ * The view's scene as the brick clipmap has it: each pixel's camera ray traced through the world's
+ * bricks (`brick_clipmap_trace`, §7.9), from the finest cascade holding the camera outward. A hit is
+ * shaded by the field's normal, tinted warmer the coarser its cascade, and red where the ray met a
+ * back face; magenta is a ray whose steps ran out. A cell not built yet defers to its parent, so the
+ * view shows the clipmap filling, coarsest first.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_brick_clipmap: ImageShader;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUViewContext = import("../../../view/GPUViewContext.js").GPUViewContext;
+export type GPUBrickClipmap = import("../brick/GPUBrickClipmap.js").GPUBrickClipmap;
+import { ImageShader } from "../../../shader/ImageShader.js";
+//# sourceMappingURL=graph_probe_clipmap_debug_brick_clipmap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_debug_brick_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_brick_clipmap.js"],"names":[],"mappings":"AAqHA;;;;;;;GAOG;AACH;IAN+B,KAAK,EAAzB,UAAU;IACc,IAAI,EAA5B,cAAc;IACI,UAAU,EAA5B,MAAM,EAAE;IACiB,aAAa,EAAtC,eAAe;IACb,MAAM,CAoClB;AA9DD;;;;;;;;GAQG;AACH,uDAFU,WAAW,CAWlB;yBA/FU,OAAO,iEAAiE,EAAE,UAAU;6BACpF,OAAO,iCAAiC,EAAE,cAAc;8BACxD,OAAO,6BAA6B,EAAE,eAAe;4BAjBtC,gCAAgC"}

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

@@ -0,0 +1,160 @@
+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";
+
+/**
+ * @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;
+
+/**
+ * @type {WebGPUStruct}
+ */
+const DEBUG_BRICK_CLIPMAP_SETTINGS = WebGPUStruct.from({
+    cascade_count: u32,
+}, "ProbeClipmapDebugBrickClipmapSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", DEBUG_BRICK_CLIPMAP_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()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+/** a cascade's tint: finest white, then warmer to the coarsest */
+fn cascade_tint(cascade: u32) -> vec3<f32> {
+    let k = f32(cascade) / f32(max(settings.cascade_count, 2u) - 1u);
+
+    return mix(vec3<f32>(1.0), vec3<f32>(1.0, 0.55, 0.15), k);
+}
+
+@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);
+    }
+
+    let fade = 0.35 + 0.65 / (1.0 + 0.02 * hit.t);
+
+    if (dot(hit.normal, ray.direction) > 0.0) {
+        // a back face: the ray came from inside a solid (§8.4)
+        return vec4<f32>(vec3<f32>(0.8, 0.1, 0.1) * fade, 1.0);
+    }
+
+    // the field's normal as a colour, tinted by the hit's cascade, dimmed with distance
+    let shade = (0.5 + 0.5 * hit.normal) * cascade_tint(hit.cascade);
+
+    return vec4<f32>(shade * fade, 1.0);
+}
+`, [
+        chunk_camera_ray_from_uv,
+        chunk_brick_clipmap_trace,
+    ]);
+
+/**
+ * The view's scene as the brick clipmap has it: each pixel's camera ray traced through the world's
+ * bricks (`brick_clipmap_trace`, §7.9), from the finest cascade holding the camera outward. A hit is
+ * shaded by the field's normal, tinted warmer the coarser its cascade, and red where the ray met a
+ * back face; magenta is a ray whose steps ran out. A cell not built yet defers to its parent, so the
+ * view shows the clipmap filling, coarsest first.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_brick_clipmap = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap Debug / Brick Clipmap",
+        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
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_brick_clipmap({ graph, view, resolution, brick_clipmap }) {
+    assert.defined(graph, 'graph');
+    assert.defined(view, 'view');
+    assert.isArrayLike(resolution, 'resolution');
+    assert.defined(brick_clipmap, 'brick_clipmap');
+
+    const data = {};
+    const settings = { cascade_count: brick_clipmap.cascade_count };
+
+    const pass = graph.add("Probe Clipmap Debug / Brick Clipmap", data, (data, resources, context) => {
+        const output = resources.get(data.output);
+
+        shader_probe_clipmap_debug_brick_clipmap.draw({
+            encoder: context.encoder,
+            bindings: brick_clipmap.write_bindings({
+                settings,
+                camera: view.camera.buffer,
+            }),
+            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_mesh_cards.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @param {Object} options
+ * @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
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_mesh_cards({ graph, view, resolution, cards, rows }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    resolution: number[];
+    cards: GPUMeshCardSets;
+    rows: GPUBuffer;
+}): number;
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_mesh_cards: ImageShader;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUViewContext = import("../../../view/GPUViewContext.js").GPUViewContext;
+export type GPUMeshCardSets = import("../../../geometry/sdf/cards/GPUMeshCardSets.js").GPUMeshCardSets;
+import { ImageShader } from "../../../shader/ImageShader.js";
+//# sourceMappingURL=graph_probe_clipmap_debug_mesh_cards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_debug_mesh_cards.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_cards.js"],"names":[],"mappings":"AA0IA;;;;;;;;GAQG;AACH;IAP+B,KAAK,EAAzB,UAAU;IACc,IAAI,EAA5B,cAAc;IACI,UAAU,EAA5B,MAAM,EAAE;IACiB,KAAK,EAA9B,eAAe;IACI,IAAI;IACrB,MAAM,CA2ClB;AAzED;;;;;;;;;;;GAWG;AACH,oDAFU,WAAW,CAWlB;yBAvGU,OAAO,iEAAiE,EAAE,UAAU;6BACpF,OAAO,iCAAiC,EAAE,cAAc;8BACxD,OAAO,gDAAgD,EAAE,eAAe;4BATzD,gCAAgC"}

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

@@ -0,0 +1,189 @@
+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 { 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_CARD_ALBEDO_RESOURCE,
+    MESH_CARD_EMISSIVE_RESOURCE,
+    MESH_CARD_ROWS_RESOURCE,
+    MESH_CARD_SETS_RESOURCE
+} from "../../../geometry/sdf/cards/MESH_CARD_RESOURCES.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../../../geometry/sdf/MESH_SDF_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";
+import { chunk_camera_ray_from_uv } from "../../../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { F32_MAX_DEFINITION } from "../../../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { chunk_scene_sdf_raymarch_hit } from "../../../shader/chunk/sdf/chunk_scene_sdf_raymarch.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 { WebGPUArray } from "../../../shader/type/WebGPUArray.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}
+ */
+const TOLERANCE_VOXELS = 1.5;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .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)
+    .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 = scene_sdf_raymarch_hit(ray);
+
+    if (hit.t >= F32_MAX) {
+        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];
+
+    if (card_set == ${GPU_DATABASE_NULL}u) {
+        // no card set readers may use yet: the pair is waiting or capturing
+        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 surface = mesh_card_surface(card_set, p, n, ${TOLERANCE_VOXELS.toFixed(1)} * header.voxel);
+
+    if (!surface.found) {
+        // no card sees the point: the hit would take the material's mean
+        return vec4<f32>(0.3, 0.0, 0.0, 1.0);
+    }
+
+    return vec4<f32>(surface.albedo + surface.emissive, 1.0);
+}
+`, [
+        F32_MAX_DEFINITION,
+        chunk_camera_ray_from_uv,
+        chunk_scene_database_access,
+        chunk_mat4_inverse,
+        chunk_scene_sdf_raymarch_hit,
+        chunk_mesh_sdf_header,
+        chunk_mesh_sdf_normal,
+        chunk_mesh_card_surface,
+    ]);
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_mesh_cards = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap Debug / Mesh Cards",
+        resources,
+        body,
+    }),
+    targets: [{
+        format: "rgba8unorm"
+    }]
+});
+
+/**
+ * @param {Object} options
+ * @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
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_mesh_cards({ graph, view, resolution, cards, rows }) {
+    assert.defined(graph, 'graph');
+    assert.defined(view, 'view');
+    assert.isArrayLike(resolution, 'resolution');
+    assert.defined(cards, 'cards');
+    assert.defined(rows, 'rows');
+
+    const data = {};
+
+    const pass = graph.add("Probe Clipmap Debug / Mesh Cards", 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({
+            encoder: context.encoder,
+            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(),
+            }),
+            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_mesh_sdf.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number[]} options.resolution
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_mesh_sdf({ graph, view, resolution }: {
+    graph: FrameGraph;
+    view: GPUViewContext;
+    resolution: number[];
+}): number;
+/**
+ * The view's scene through its geometry caches alone: each pixel's camera ray walks the TLAS and,
+ * in every instance it meets, marches that geometry's sparse field at level 0 (`mesh_sdf_raymarch`)
+ * — the bricks a bake has stored so far, EMPTY ones read as the band. The nearest hit is shaded by
+ * its normal. A geometry with no cache yet draws nothing, so the view shows the caches filling.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_mesh_sdf: ImageShader;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUViewContext = import("../../../view/GPUViewContext.js").GPUViewContext;
+import { ImageShader } from "../../../shader/ImageShader.js";
+//# sourceMappingURL=graph_probe_clipmap_debug_mesh_sdf.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph_probe_clipmap_debug_mesh_sdf.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_sdf.js"],"names":[],"mappings":"AAgGA;;;;;;GAMG;AACH;IAL+B,KAAK,EAAzB,UAAU;IACc,IAAI,EAA5B,cAAc;IACI,UAAU,EAA5B,MAAM,EAAE;IACN,MAAM,CAoClB;AA5DD;;;;;;;GAOG;AACH,kDAFU,WAAW,CAWlB;yBAzEU,OAAO,iEAAiE,EAAE,UAAU;6BACpF,OAAO,iCAAiC,EAAE,cAAc;4BARzC,gCAAgC"}