@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -0,0 +1,590 @@
+import { MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { MESH_SDF_SAMPLER } from "../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { CLIPMAP_LEVEL_ARRAY, CLIPMAP_LEVEL_LIMIT, CLIPMAP_LEVEL_STRUCT } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_aabb3_distance_to_ray_v2 } from "../../../shader/chunk/geometry/aabb3/chunk_aabb3_distance_to_ray_v2.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { chunk_tile_atlas_slot_origin } from "../../../texture/atlas/chunk_tile_atlas_slot_origin.js";
+import {
+    BRICK_OBJECT_CELLS,
+    BRICK_OBJECT_CELLS_PER_AXIS,
+    BRICK_OCCUPANCY_BLOCK,
+    BRICK_TRACE_HIT,
+    BRICK_TRACE_MISS,
+    BRICK_TRACE_UNRESOLVED
+} from "./BRICK_CLIPMAP.js";
+import { chunk_brick_clipmap } from "./chunk_brick_clipmap.js";
+
+/**
+ * Steps a ray takes at most (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9, chosen). A step past empty
+ * space is a block or a cell, and one near a surface is at least half a voxel.
+ * @type {number}
+ */
+export const BRICK_TRACE_STEPS = 64;
+
+/**
+ * How far past a block's or a cell's exit a step lands, in voxels of its cascade: enough that the
+ * next cell is the one past the face, and far less than the half voxel a hit allows.
+ * @type {number}
+ */
+export const BRICK_TRACE_NUDGE = 1 / 64;
+
+/**
+ * The brick map as the tracer reads it: an entry a cell, the cascades stacked along z.
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_MAP_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("brick_map", "uint", "3d");
+
+/**
+ * The occupancy as the tracer reads it: a count a block of 4³ storage cells, the cascades stacked.
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_OCCUPANCY_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("brick_occupancy", "uint", "3d");
+
+/**
+ * The world's bricks: an `r8unorm` 3-D atlas of 8³ tiles, on the lattice the mesh bricks use (§7.2).
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_ATLAS_TEXTURE_RESOURCE = ShaderResourceDescriptor.texture("brick_atlas", "float", "3d");
+
+/**
+ * The mesh bricks' sampler: linear, clamped. A tap inside a brick never reaches past it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_SAMPLER_RESOURCE = ShaderResourceDescriptor.sampler("brick_sampler", "filtering", MESH_SDF_SAMPLER);
+
+/**
+ * Every cascade's window, finest first.
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_LEVELS_RESOURCE = ShaderResourceDescriptor.uniform("brick_levels", CLIPMAP_LEVEL_ARRAY);
+
+/**
+ * The object cells: {@link BRICK_OBJECT_CELLS} `meshes` rows a slot, 0 for none.
+ * @type {ShaderResourceDescriptor}
+ */
+export const BRICK_OBJECTS_RESOURCE = ShaderResourceDescriptor.storageBuffer("brick_objects", WebGPUArray.u32);
+
+/**
+ * A brick's distance at a point of its cell, and the field's gradient there.
+ *
+ * ```wgsl
+ * fn brick_clipmap_sample(slot: u32, local: vec3<f32>, voxel: f32) -> f32 // local in voxels from the cell's corner
+ * fn brick_clipmap_normal(slot: u32, local: vec3<f32>) -> vec3<f32>       // out of the solid, unit length
+ * ```
+ *
+ * One hardware trilinear tap of the atlas at texel `slot_origin + 0.5 + local`, `local` clamped to the
+ * brick's [0, 7]: it never reads a neighbouring slot (§7.2). The gradient is a tetrahedral one, four
+ * taps half a voxel off, each clamped the same way.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_sample = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_tap(slot: u32, local: vec3<f32>) -> f32 {
+    let atlas_size = textureDimensions(brick_atlas, 0);
+    let corner = tile_atlas_slot_origin(slot, atlas_size.xy / ${MESH_SDF_BRICK_TEXELS}u, vec3<u32>(${MESH_SDF_BRICK_TEXELS}u));
+    let uvw = (vec3<f32>(corner) + 0.5 + clamp(local, vec3<f32>(0.0), vec3<f32>(${MESH_SDF_BRICK_VOXELS}.0))) / vec3<f32>(atlas_size);
+
+    return textureSampleLevel(brick_atlas, brick_sampler, uvw, 0.0).r;
+}
+
+fn brick_clipmap_sample(slot: u32, local: vec3<f32>, voxel: f32) -> f32 {
+    return 2.0 * BRICK_CLIPMAP_BAND_VOXELS * voxel * (brick_clipmap_tap(slot, local) - 0.5);
+}
+
+fn brick_clipmap_normal(slot: u32, local: vec3<f32>) -> vec3<f32> {
+    let a = vec3<f32>(1.0, -1.0, -1.0);
+    let b = vec3<f32>(-1.0, -1.0, 1.0);
+    let c = vec3<f32>(-1.0, 1.0, -1.0);
+    let d = vec3<f32>(1.0, 1.0, 1.0);
+
+    let gradient = a * brick_clipmap_tap(slot, local + 0.5 * a)
+        + b * brick_clipmap_tap(slot, local + 0.5 * b)
+        + c * brick_clipmap_tap(slot, local + 0.5 * c)
+        + d * brick_clipmap_tap(slot, local + 0.5 * d);
+
+    let length_sqr = dot(gradient, gradient);
+
+    // a flat field, as clamped taps in a brick's corner can give: no direction to report
+    return select(vec3<f32>(0.0), gradient * inverseSqrt(length_sqr), length_sqr > 0.0);
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_tile_atlas_slot_origin,
+    ]);
+
+chunk_brick_clipmap_sample.requireResource(BRICK_ATLAS_TEXTURE_RESOURCE);
+chunk_brick_clipmap_sample.requireResource(BRICK_SAMPLER_RESOURCE);
+
+/**
+ * Where a point is in the cascades: whether a cascade's window holds it, inset by a margin, and the
+ * finest cascade that does.
+ *
+ * ```wgsl
+ * fn brick_clipmap_window_holds(level: ClipmapLevel, position: vec3<f32>, inset: f32) -> bool
+ * fn brick_clipmap_start(position: vec3<f32>, cascade_count: u32) -> u32 // cascade_count when none does
+ * ```
+ *
+ * The tracer starts in the finest window holding the point by half a voxel of its cascade (§7.9).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_window = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_window_holds(level: ${CLIPMAP_LEVEL_STRUCT.wgsl_ref}, position: vec3<f32>, inset: f32) -> bool {
+    let low = vec3<f32>(level.corner) * level.cell_size + inset;
+    let high = vec3<f32>(level.corner + level.size) * level.cell_size - inset;
+
+    return all(position >= low) && all(position <= high);
+}
+
+fn brick_clipmap_start(position: vec3<f32>, cascade_count: u32) -> u32 {
+    for (var c = 0u; c < min(cascade_count, ${CLIPMAP_LEVEL_LIMIT}u); c++) {
+        let level = brick_levels[c];
+
+        if (brick_clipmap_window_holds(level, position, 0.5 * level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0)) {
+            return c;
+        }
+    }
+
+    return cascade_count;
+}
+`, [
+        CLIPMAP_LEVEL_STRUCT.declaration_chunk,
+    ]);
+
+chunk_brick_clipmap_window.requireResource(BRICK_LEVELS_RESOURCE);
+
+/**
+ * A step of a march through the brick clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9): what the
+ * tracer and the soft shadow both walk.
+ *
+ * ```wgsl
+ * fn brick_clipmap_march(origin: vec3<f32>, direction: vec3<f32>, cascade_count: u32, march: ptr<function, BrickClipmapMarch>) -> u32
+ * ```
+ *
+ * `direction` is unit length, so `t` is a distance. A march starts at its `t` in the finest cascade
+ * whose window holds that point by half a voxel (`brick_clipmap_start`). A step reads one occupancy
+ * and one entry, and where it stands:
+ * - a point past the window, inset by half a voxel, carries the march to the next cascade, and past
+ *   the last it has left;
+ * - a block of no cells to read is passed whole, clamped to the window;
+ * - UNKNOWN goes on in the next cascade from the same `t`: space not built yet is read from the
+ *   parent, not passed through;
+ * - EMPTY is passed to the cell's exit;
+ * - a brick, or EMPTY inside, is a cell to read, which the march leaves to its caller: its entry, its
+ *   corner, its voxel and the point.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_march = CodeChunk.from(
+    //language=WGSL
+    `
+/** the step passed empty space, or went on in the next cascade */
+const BRICK_MARCH_MOVED = 0u;
+/** the step left the last window */
+const BRICK_MARCH_LEFT = 1u;
+/** the step stands in a cell to read: a brick, or EMPTY inside */
+const BRICK_MARCH_CELL = 2u;
+
+struct BrickClipmapMarch {
+    t: f32,
+    cascade: u32,
+    /** of the cell to read: a slot, or BRICK_CLIPMAP_EMPTY_INSIDE */
+    entry: u32,
+    /** the cell's least corner */
+    cell_min: vec3<f32>,
+    /** the voxel of the cell's cascade */
+    voxel: f32,
+    /** where the march stands */
+    position: vec3<f32>,
+}
+
+fn brick_clipmap_march(origin: vec3<f32>, direction: vec3<f32>, cascade_count: u32, march: ptr<function, BrickClipmapMarch>) -> u32 {
+    let level = brick_levels[(*march).cascade];
+    let voxel = level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+    let position = origin + (*march).t * direction;
+
+    if (!brick_clipmap_window_holds(level, position, 0.5 * voxel)) {
+        (*march).cascade++;
+
+        return select(BRICK_MARCH_MOVED, BRICK_MARCH_LEFT, (*march).cascade >= cascade_count);
+    }
+
+    let resolution = u32(level.size.x);
+    let cell = vec3<i32>(floor(position / level.cell_size));
+    let storage = vec3<u32>(cell) & vec3<u32>(resolution - 1u);
+    let block = storage / ${BRICK_OCCUPANCY_BLOCK}u;
+    let blocks = resolution / ${BRICK_OCCUPANCY_BLOCK}u;
+
+    if (textureLoad(brick_occupancy, vec3<u32>(block.xy, block.z + (*march).cascade * blocks), 0).x == 0u) {
+        // nothing in the block to read: past it, where it lies in the window
+        let first = cell - vec3<i32>(storage - block * ${BRICK_OCCUPANCY_BLOCK}u);
+        let low = max(first, level.corner);
+        let high = min(first + vec3<i32>(${BRICK_OCCUPANCY_BLOCK}), level.corner + level.size);
+
+        (*march).t = aabb3_distance_to_ray(vec3<f32>(low) * level.cell_size, vec3<f32>(high) * level.cell_size, origin, direction).y + ${BRICK_TRACE_NUDGE} * voxel;
+
+        return BRICK_MARCH_MOVED;
+    }
+
+    let entry = textureLoad(brick_map, brick_clipmap_map_texel((*march).cascade, storage, resolution), 0).x;
+
+    if (entry == BRICK_CLIPMAP_UNKNOWN) {
+        (*march).cascade++;
+
+        return select(BRICK_MARCH_MOVED, BRICK_MARCH_LEFT, (*march).cascade >= cascade_count);
+    }
+
+    let cell_min = vec3<f32>(cell) * level.cell_size;
+
+    if (entry == BRICK_CLIPMAP_EMPTY) {
+        (*march).t = aabb3_distance_to_ray(cell_min, cell_min + level.cell_size, origin, direction).y + ${BRICK_TRACE_NUDGE} * voxel;
+
+        return BRICK_MARCH_MOVED;
+    }
+
+    (*march).entry = entry;
+    (*march).cell_min = cell_min;
+    (*march).voxel = voxel;
+    (*march).position = position;
+
+    return BRICK_MARCH_CELL;
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_brick_clipmap_window,
+        chunk_aabb3_distance_to_ray_v2,
+    ]);
+
+chunk_brick_clipmap_march.requireResource(BRICK_MAP_TEXTURE_RESOURCE);
+chunk_brick_clipmap_march.requireResource(BRICK_OCCUPANCY_TEXTURE_RESOURCE);
+
+/**
+ * The first surface along a ray through the brick clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9).
+ *
+ * ```wgsl
+ * fn brick_clipmap_trace(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, cascade_count: u32) -> BrickClipmapHit
+ * ```
+ *
+ * The march (`brick_clipmap_march`) from `t_min`, at most {@link BRICK_TRACE_STEPS} steps, each
+ * reading in a brick one atlas tap:
+ * - EMPTY inside is a hit where the march stands: the ray is inside a solid, and its hit is a back
+ *   face (§7.2, §8.4), its normal along the ray;
+ * - in a brick, a distance under half a voxel is a hit, and any other is a step of at least half a
+ *   voxel.
+ *
+ * A march that spends its steps is unresolved, and its caller discards it (§8.8). One past `t_max`,
+ * or out of every window, is a miss.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_trace = CodeChunk.from(
+    //language=WGSL
+    `
+const BRICK_TRACE_MISS = ${BRICK_TRACE_MISS}u;
+const BRICK_TRACE_HIT = ${BRICK_TRACE_HIT}u;
+const BRICK_TRACE_UNRESOLVED = ${BRICK_TRACE_UNRESOLVED}u;
+
+struct BrickClipmapHit {
+    /** BRICK_TRACE_MISS, BRICK_TRACE_HIT or BRICK_TRACE_UNRESOLVED */
+    kind: u32,
+    /** the ray's distance at the hit, or where the march stopped */
+    t: f32,
+    cascade: u32,
+    /** the slot the hit is in, or BRICK_CLIPMAP_EMPTY_INSIDE for a ray inside a solid */
+    slot: u32,
+    position: vec3<f32>,
+    /** out of the solid; along the ray inside one, as a back face's gradient is (§8.4) */
+    normal: vec3<f32>,
+    /** the field where the hit stands, under half a voxel; -R inside a solid */
+    distance: f32,
+    /** the hit cell's least corner */
+    cell_min: vec3<f32>,
+}
+
+fn brick_clipmap_trace(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, cascade_count: u32) -> BrickClipmapHit {
+    var hit: BrickClipmapHit;
+
+    hit.kind = BRICK_TRACE_MISS;
+    hit.t = t_max;
+    hit.slot = BRICK_CLIPMAP_EMPTY;
+
+    var march: BrickClipmapMarch;
+
+    march.t = t_min;
+    march.cascade = brick_clipmap_start(origin + t_min * direction, cascade_count);
+
+    if (march.cascade >= cascade_count) {
+        return hit;
+    }
+
+    for (var step = 0u; step < ${BRICK_TRACE_STEPS}u; step++) {
+        if (march.t > t_max) {
+            return hit;
+        }
+
+        let stood = brick_clipmap_march(origin, direction, cascade_count, &march);
+
+        if (stood == BRICK_MARCH_LEFT) {
+            return hit;
+        }
+
+        if (stood == BRICK_MARCH_MOVED) {
+            continue;
+        }
+
+        if (march.entry == BRICK_CLIPMAP_EMPTY_INSIDE) {
+            hit.kind = BRICK_TRACE_HIT;
+            hit.t = march.t;
+            hit.cascade = march.cascade;
+            hit.slot = march.entry;
+            hit.position = march.position;
+            hit.normal = direction;
+            hit.distance = -BRICK_CLIPMAP_BAND_VOXELS * march.voxel;
+            hit.cell_min = march.cell_min;
+
+            return hit;
+        }
+
+        let local = (march.position - march.cell_min) / march.voxel;
+        let distance = brick_clipmap_sample(march.entry, local, march.voxel);
+
+        if (distance < 0.5 * march.voxel) {
+            hit.kind = BRICK_TRACE_HIT;
+            hit.t = march.t;
+            hit.cascade = march.cascade;
+            hit.slot = march.entry;
+            hit.position = march.position;
+            hit.normal = brick_clipmap_normal(march.entry, local);
+            hit.distance = distance;
+            hit.cell_min = march.cell_min;
+
+            return hit;
+        }
+
+        // past the hit's threshold, so at least half a voxel: UE's minimum step
+        march.t += distance;
+    }
+
+    hit.kind = BRICK_TRACE_UNRESOLVED;
+    hit.t = march.t;
+
+    return hit;
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_brick_clipmap_sample,
+        chunk_brick_clipmap_window,
+        chunk_brick_clipmap_march,
+    ]);
+
+/**
+ * How much of a light's disk a point sees along a ray through the brick clipmap (§7.9), from 0 to 1.
+ *
+ * ```wgsl
+ * fn brick_clipmap_soft_shadow(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, sin_angle: f32, cascade_count: u32) -> f32
+ * ```
+ *
+ * `direction` is toward the light, unit length, and `sin_angle` the sine of the light's angular
+ * radius (its `disk_radius`). The march is the tracer's (`brick_clipmap_march`), from `t_min`, at
+ * most {@link BRICK_TRACE_STEPS} steps.
+ *
+ * The estimate is Quílez's two-sided penumbra. The light's edge is a cone about the ray, of radius
+ * `t·sin θ`; in each brick the march reads the clearance, the field less the tracer's half-voxel
+ * expand, so that a wall thinner than a voxel shadows as it is hit. The least of the clearance over the
+ * cone's radius goes below zero inside the occluder:
+ * - the march goes on into the occluder, half a voxel a step, until the least reaches -1, which is
+ *   the light hidden whole;
+ * - clamped to [-1, 1], it maps through `¼(1 + x)²(2 - x)` to the visible part, which is half at the
+ *   shadow's geometric edge, as the analytic disk is. The classic, one-sided estimate reads 0 there.
+ *
+ * EMPTY inside hides the light whole. An EMPTY cell, or a block passed whole, is clear by at least a
+ * voxel, wider than a sun's cone within its cascade's range, and the march reads nothing in it. A march
+ * out of every window, or past `t_max`, sees what it has not found hidden; so does one that spends
+ * its steps.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_soft_shadow = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_soft_shadow(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, sin_angle: f32, cascade_count: u32) -> f32 {
+    var march: BrickClipmapMarch;
+
+    march.t = t_min;
+    march.cascade = brick_clipmap_start(origin + t_min * direction, cascade_count);
+
+    // the least clearance over the cone's radius, the light's edge
+    var least = 1.0;
+
+    for (var step = 0u; step < ${BRICK_TRACE_STEPS}u && march.cascade < cascade_count && march.t <= t_max; step++) {
+        let stood = brick_clipmap_march(origin, direction, cascade_count, &march);
+
+        if (stood != BRICK_MARCH_CELL) {
+            continue;
+        }
+
+        if (march.entry == BRICK_CLIPMAP_EMPTY_INSIDE) {
+            return 0.0;
+        }
+
+        let distance = brick_clipmap_sample(march.entry, (march.position - march.cell_min) / march.voxel, march.voxel);
+
+        least = min(least, (distance - 0.5 * march.voxel) / (march.t * sin_angle));
+
+        if (least <= -1.0) {
+            return 0.0;
+        }
+
+        // inside the occluder the field gives no step: half a voxel, the tracer's least
+        march.t += max(distance, 0.5 * march.voxel);
+    }
+
+    let x = clamp(least, -1.0, 1.0);
+
+    return 0.25 * (1.0 + x) * (1.0 + x) * (2.0 - x);
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_brick_clipmap_sample,
+        chunk_brick_clipmap_window,
+        chunk_brick_clipmap_march,
+    ]);
+
+/**
+ * The finest cascade's signed distance at a point (§7.9), for probe relocation.
+ *
+ * ```wgsl
+ * fn brick_clipmap_distance(position: vec3<f32>, cascade_count: u32) -> f32
+ * ```
+ *
+ * The finest window holding the point answers, unless its cell is UNKNOWN, which defers to the
+ * parent. EMPTY reads R of its cascade, EMPTY inside -R: the surface is at least that far. A point no
+ * window holds, or that only UNKNOWN cells cover, reads R of the coarsest cascade.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_distance = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_distance(position: vec3<f32>, cascade_count: u32) -> f32 {
+    let count = min(cascade_count, ${CLIPMAP_LEVEL_LIMIT}u);
+
+    for (var c = 0u; c < count; c++) {
+        let level = brick_levels[c];
+
+        if (!brick_clipmap_window_holds(level, position, 0.0)) {
+            continue;
+        }
+
+        let voxel = level.cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+        let resolution = u32(level.size.x);
+        let cell = vec3<i32>(floor(position / level.cell_size));
+        let storage = vec3<u32>(cell) & vec3<u32>(resolution - 1u);
+        let entry = textureLoad(brick_map, brick_clipmap_map_texel(c, storage, resolution), 0).x;
+
+        if (entry == BRICK_CLIPMAP_UNKNOWN) {
+            continue;
+        }
+
+        if (!brick_clipmap_entry_holds_slot(entry)) {
+            return select(1.0, -1.0, entry == BRICK_CLIPMAP_EMPTY_INSIDE) * BRICK_CLIPMAP_BAND_VOXELS * voxel;
+        }
+
+        return brick_clipmap_sample(entry, (position - vec3<f32>(cell) * level.cell_size) / voxel, voxel);
+    }
+
+    return BRICK_CLIPMAP_BAND_VOXELS * brick_levels[max(count, 1u) - 1u].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_brick_clipmap_sample,
+        chunk_brick_clipmap_window,
+    ]);
+
+chunk_brick_clipmap_distance.requireResource(BRICK_MAP_TEXTURE_RESOURCE);
+
+/**
+ * The direction the brick clipmap's field rises fastest at a point, unit length, or zero where it has
+ * no slope: for probe relocation (§8.4).
+ *
+ * ```wgsl
+ * fn brick_clipmap_gradient(position: vec3<f32>, cascade_count: u32) -> vec3<f32>
+ * ```
+ *
+ * Four taps of {@link chunk_brick_clipmap_distance} at the corners of a tetrahedron a voxel of the finest
+ * window holding the point across, as `brick_clipmap_normal` takes them inside a brick; here across
+ * bricks and cascades. On a field of slope one the taps sum to four voxels; under a tenth of that it
+ * reads as flat, inside a solid past the band or in the space beyond it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_gradient = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_gradient(position: vec3<f32>, cascade_count: u32) -> vec3<f32> {
+    let cascade = min(brick_clipmap_start(position, cascade_count), max(cascade_count, 1u) - 1u);
+    let h = brick_levels[cascade].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+
+    let k0 = vec3<f32>(1.0, -1.0, -1.0);
+    let k1 = vec3<f32>(-1.0, -1.0, 1.0);
+    let k2 = vec3<f32>(-1.0, 1.0, -1.0);
+    let k3 = vec3<f32>(1.0, 1.0, 1.0);
+
+    let sum = k0 * brick_clipmap_distance(position + h * k0, cascade_count)
+        + k1 * brick_clipmap_distance(position + h * k1, cascade_count)
+        + k2 * brick_clipmap_distance(position + h * k2, cascade_count)
+        + k3 * brick_clipmap_distance(position + h * k3, cascade_count);
+
+    let size = length(sum);
+
+    return select(vec3<f32>(0.0), sum / size, size > 0.4 * h);
+}
+`, [
+        chunk_brick_clipmap_window,
+        chunk_brick_clipmap_distance,
+    ]);
+
+/**
+ * The `meshes` row whose surface a hit is on (§7.9), 0 for none.
+ *
+ * ```wgsl
+ * fn brick_clipmap_object(hit: BrickClipmapHit) -> u32
+ * ```
+ *
+ * The object cell of the texel nearest the hit moved half a voxel along the normal, onto the ray's
+ * side: of a wall thinner than a voxel, whose two faces are in neighbouring object cells, it picks
+ * the face the ray hit, as UE's object lookup does. A front face's normal is against the ray, and a
+ * back face is counted, never shaded (§8.4), so the move is along the normal. A hit inside a solid
+ * has no face: none.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_brick_clipmap_object = CodeChunk.from(
+    //language=WGSL
+    `
+fn brick_clipmap_object(hit: BrickClipmapHit) -> u32 {
+    if (hit.kind != BRICK_TRACE_HIT || !brick_clipmap_entry_holds_slot(hit.slot)) {
+        return 0u;
+    }
+
+    let voxel = brick_levels[hit.cascade].cell_size / ${MESH_SDF_BRICK_VOXELS}.0;
+
+    let local = (hit.position + 0.5 * voxel * hit.normal - hit.cell_min) / voxel;
+    let texel = vec3<u32>(clamp(round(local), vec3<f32>(0.0), vec3<f32>(${MESH_SDF_BRICK_VOXELS}.0)));
+    let cell = min(texel / 2u, vec3<u32>(${BRICK_OBJECT_CELLS_PER_AXIS - 1}u));
+
+    return brick_objects[hit.slot * ${BRICK_OBJECT_CELLS}u + cell.x + ${BRICK_OBJECT_CELLS_PER_AXIS}u * (cell.y + ${BRICK_OBJECT_CELLS_PER_AXIS}u * cell.z)];
+}
+`, [
+        chunk_brick_clipmap,
+        chunk_brick_clipmap_trace,
+    ]);
+
+chunk_brick_clipmap_object.requireResource(BRICK_OBJECTS_RESOURCE);
+chunk_brick_clipmap_object.requireResource(BRICK_LEVELS_RESOURCE);

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Instances a cell's mesh provider samples at most (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): the
+ * rest are dropped and counted, and a dropped instance can leave a hole. Coarse cascades are where
+ * it binds.
+ * @type {number}
+ */
+export const MESH_BRICK_INSTANCE_LIMIT: number;
+/**
+ * The `meshes` rows an object cell can name: one more than the largest row that fits in the 24 bits
+ * the object decision packs a row into beside its distance byte. A row past it writes no object, as
+ * a provider that cannot name a row does (§7.6, contract 5).
+ * @type {number}
+ */
+export const MESH_BRICK_ROW_LIMIT: number;
+/**
+ * An instance as the mesh provider samples it, made once a cell (§7.7):
+ * - `to_local_0..2`: the rows of the inverse of the instance's `node.global`, from the world into the
+ *   geometry's space;
+ * - `box_min`, `box_max`: the row's world box, for the box test;
+ * - `sigma`: the smallest axis scale of `node.global`, exact for uniform scale and an under-estimate
+ *   otherwise, so `sigma` times a local distance never exceeds the world one (contract 4);
+ * - `level`: the coarsest level of the geometry's field no coarser than the cascade;
+ * - `geometry`: the header to sample, an alias followed;
+ * - `row`: the `meshes` row, the cell's object.
+ *
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_INSTANCE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=MESH_BRICK_INSTANCE_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MESH_BRICK_INSTANCE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;;;GAKG;AACH,mCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;GAYG;AACH,yCAFU,YAAY,CAYE;6BAzCK,yCAAyC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MESH_BRICK_INSTANCE_STRUCT.js

@@ -0,0 +1,43 @@
+import { f32, u32, vec3f, vec4f } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+
+/**
+ * Instances a cell's mesh provider samples at most (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): the
+ * rest are dropped and counted, and a dropped instance can leave a hole. Coarse cascades are where
+ * it binds.
+ * @type {number}
+ */
+export const MESH_BRICK_INSTANCE_LIMIT = 64;
+
+/**
+ * The `meshes` rows an object cell can name: one more than the largest row that fits in the 24 bits
+ * the object decision packs a row into beside its distance byte. A row past it writes no object, as
+ * a provider that cannot name a row does (§7.6, contract 5).
+ * @type {number}
+ */
+export const MESH_BRICK_ROW_LIMIT = 1 << 24;
+
+/**
+ * An instance as the mesh provider samples it, made once a cell (§7.7):
+ * - `to_local_0..2`: the rows of the inverse of the instance's `node.global`, from the world into the
+ *   geometry's space;
+ * - `box_min`, `box_max`: the row's world box, for the box test;
+ * - `sigma`: the smallest axis scale of `node.global`, exact for uniform scale and an under-estimate
+ *   otherwise, so `sigma` times a local distance never exceeds the world one (contract 4);
+ * - `level`: the coarsest level of the geometry's field no coarser than the cascade;
+ * - `geometry`: the header to sample, an alias followed;
+ * - `row`: the `meshes` row, the cell's object.
+ *
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_INSTANCE_STRUCT = WebGPUStruct.from({
+    to_local_0: vec4f,
+    to_local_1: vec4f,
+    to_local_2: vec4f,
+    box_min: vec3f,
+    sigma: f32,
+    box_max: vec3f,
+    level: u32,
+    geometry: u32,
+    row: u32,
+}, "MeshBrickInstance");