@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_hit_surface.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The tolerance a card's depth is held to at a GI hit, in voxels of the hit's brick cascade: a hit is
+ * only as exact as its cascade, and UE's bias for a global-SDF hit is three half-voxels of its clipmap
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6).
+ * @type {number}
+ */
+export const PROBE_HIT_SURFACE_TOLERANCE_VOXELS: number;
+/**
+ * The resident materials' table, as the ray passes read it: `materials[mesh.material]`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_HIT_MATERIALS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Each resident texture slot's mean, `GPUResidentMaterialContext.buffer_texture_means`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_HIT_TEXTURE_MEANS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * What a GI hit's surface is (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6), its diffuse albedo and its
+ * emissive, from the `meshes` row the hit is on:
+ *
+ * ```wgsl
+ * fn probe_clipmap_hit_surface(row: u32, position: vec3<f32>, normal: vec3<f32>, voxel: f32) -> ProbeClipmapHitSurface
+ * ```
+ *
+ * - **The cards**: the row's card set, when it has one readers may use, asked at the hit moved into
+ *   the geometry's local space through its node, the normal by the transpose of the node's linear
+ *   part, and the tolerance {@link PROBE_HIT_SURFACE_TOLERANCE_VOXELS} voxels of the hit's cascade,
+ *   `voxel`, in local units by the transform's mean scale, the cube root of its determinant.
+ * - **The material's mean**, where no card set is resident or no card sees the hit: the colour factor
+ *   × the albedo slot's mean colour × (1 − the metallic factor × the ORM slot's mean metalness), and the
+ *   emissive factor × the emissive slot's mean. What a card would have held, Lumen's diffuse colour,
+ *   from the means of what it is made of.
+ * - **Row 0** names no object, the scene root never being a mesh: the hit is black.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_hit_surface: CodeChunk;
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_probe_clipmap_hit_surface.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_hit_surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_probe_clipmap_hit_surface.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_hit_surface.js"],"names":[],"mappings":"AAcA;;;;;GAKG;AACH,iDAFU,MAAM,CAEsC;AAEtD;;;GAGG;AACH,2CAFU,wBAAwB,CAEsF;AAExH;;;GAGG;AACH,+CAFU,wBAAwB,CAE+F;AAEjI;;;;;;;;;;;;;;;;;;;GAmBG;AACH,8CAFU,SAAS,CAoDZ;yCA9FkC,sDAAsD;0BADrE,uCAAuC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/chunk_probe_clipmap_hit_surface.js

@@ -0,0 +1,110 @@
+import { GPU_DATABASE_NULL } from "../../../buffer/table/GPU_DATABASE_NULL.js";
+import { chunk_mesh_card_surface } from "../../../geometry/sdf/cards/chunk_mesh_card_surface.js";
+import { MESH_CARD_ROWS_RESOURCE } from "../../../geometry/sdf/cards/MESH_CARD_RESOURCES.js";
+import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
+import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
+import { SCENE_DATABASE_RESOURCE } from "../../../scene/SCENE_DATABASE_RESOURCE.js";
+import { chunk_mat4_inverse } from "../../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
+import { chunk_mat4_linear_determinant } from "../../../shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js";
+import { chunk_albedo_unpremultiply } from "../../../shader/chunk/material/chunk_albedo_unpremultiply.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+
+/**
+ * The tolerance a card's depth is held to at a GI hit, in voxels of the hit's brick cascade: a hit is
+ * only as exact as its cascade, and UE's bias for a global-SDF hit is three half-voxels of its clipmap
+ * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6).
+ * @type {number}
+ */
+export const PROBE_HIT_SURFACE_TOLERANCE_VOXELS = 1.5;
+
+/**
+ * The resident materials' table, as the ray passes read it: `materials[mesh.material]`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_HIT_MATERIALS_RESOURCE = ShaderResourceDescriptor.uniform("materials", INDIRECT_MATERIAL_ARRAY_TYPE);
+
+/**
+ * Each resident texture slot's mean, `GPUResidentMaterialContext.buffer_texture_means`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_HIT_TEXTURE_MEANS_RESOURCE = ShaderResourceDescriptor.storageBuffer("texture_means", WebGPUArray.from(vec4f));
+
+/**
+ * What a GI hit's surface is (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.6), its diffuse albedo and its
+ * emissive, from the `meshes` row the hit is on:
+ *
+ * ```wgsl
+ * fn probe_clipmap_hit_surface(row: u32, position: vec3<f32>, normal: vec3<f32>, voxel: f32) -> ProbeClipmapHitSurface
+ * ```
+ *
+ * - **The cards**: the row's card set, when it has one readers may use, asked at the hit moved into
+ *   the geometry's local space through its node, the normal by the transpose of the node's linear
+ *   part, and the tolerance {@link PROBE_HIT_SURFACE_TOLERANCE_VOXELS} voxels of the hit's cascade,
+ *   `voxel`, in local units by the transform's mean scale, the cube root of its determinant.
+ * - **The material's mean**, where no card set is resident or no card sees the hit: the colour factor
+ *   × the albedo slot's mean colour × (1 − the metallic factor × the ORM slot's mean metalness), and the
+ *   emissive factor × the emissive slot's mean. What a card would have held, Lumen's diffuse colour,
+ *   from the means of what it is made of.
+ * - **Row 0** names no object, the scene root never being a mesh: the hit is black.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_probe_clipmap_hit_surface = CodeChunk.from(
+    //language=WGSL
+    `
+struct ProbeClipmapHitSurface {
+    albedo: vec3<f32>,
+    emissive: vec3<f32>,
+}
+
+fn probe_clipmap_hit_surface(row: u32, position: vec3<f32>, normal: vec3<f32>, voxel: f32) -> ProbeClipmapHitSurface {
+    var out: ProbeClipmapHitSurface;
+
+    if (row == 0u) {
+        return out;
+    }
+
+    let mesh = scene_read_mesh(&scene_database, row);
+    let card_set = mesh_card_rows[row];
+
+    if (card_set != ${GPU_DATABASE_NULL}u) {
+        let global = scene_read_node(&scene_database, mesh.node).global;
+        let linear = mat3x3<f32>(global[0].xyz, global[1].xyz, global[2].xyz);
+
+        let p = (mat4_inverse(global) * vec4<f32>(position, 1.0)).xyz;
+        let n = normalize(transpose(linear) * normal);
+        let scale = pow(abs(mat4_linear_determinant(global)), 1.0 / 3.0);
+
+        let seen = mesh_card_surface(card_set, p, n, ${PROBE_HIT_SURFACE_TOLERANCE_VOXELS.toFixed(1)} * voxel / scale);
+
+        if (seen.found) {
+            out.albedo = seen.albedo;
+            out.emissive = seen.emissive;
+
+            return out;
+        }
+    }
+
+    let material = materials[mesh.material];
+    let metalness = material.metallic_factor * texture_means[material.texture_orm].b;
+
+    out.albedo = albedo_unpremultiply(texture_means[material.texture_albedo]) * material.color_albedo.rgb * (1.0 - metalness);
+    out.emissive = texture_means[material.texture_emissive].rgb * material.emissive_factor;
+
+    return out;
+}
+`, [
+        chunk_scene_database_access,
+        chunk_mat4_inverse,
+        chunk_mat4_linear_determinant,
+        chunk_albedo_unpremultiply,
+        chunk_mesh_card_surface,
+    ]);
+
+chunk_probe_clipmap_hit_surface.requireResource(SCENE_DATABASE_RESOURCE);
+chunk_probe_clipmap_hit_surface.requireResource(MESH_CARD_ROWS_RESOURCE);
+chunk_probe_clipmap_hit_surface.requireResource(PROBE_HIT_MATERIALS_RESOURCE);
+chunk_probe_clipmap_hit_surface.requireResource(PROBE_HIT_TEXTURE_MEANS_RESOURCE);

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ACCUMULATE_SETTINGS: WebGPUStruct;
+/**
+ * Accumulate (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a texel of each listed probe's maps,
+ * the n_r² radiance texels then the n_d² depth texels, dispatched through `PROBE_DISPATCH_TEXELS`. Each
+ * gathers its own rays and writes the texel, blended with its history, to the probe's maps in
+ * `probe_maps` (`probe_clipmap_maps_words`): two words a radiance texel, rgba as half floats; then a
+ * word a radiance texel, its rays this update, resolved in the low half and back faces in the high,
+ * which classification sums; then a word a depth texel, its moments as half floats.
+ *
+ * - **Radiance**: the mean of the texel's resolved rays, a back face's being zero, blended by
+ *   α = max(1/(a+1), 1 − e^(−Δt·p/τ)). a is the texel's own count of the updates that reached it, held
+ *   in its alpha; p the updates between a texel's rays, n_r²/R below one ray a texel. Counting a texel
+ *   rather than the probe keeps α right where an update covers a subset: a texel's first ray is taken
+ *   whole whenever it comes. A texel no ray reached keeps its history.
+ * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss √3, a back
+ *   face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to √3 (D9). Blended by the probe's
+ *   α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At most 64 rays a texel, which the settings hold
+ *   R to (R ≤ 64·n_d²).
+ * - **A new probe's history is another probe's**, its slot's last owner: on its first update a texel
+ *   no ray reached is cleared, radiance to nothing seen, depth to the moments of a miss.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_accumulate: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_accumulate.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_accumulate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.js"],"names":[],"mappings":"AA4BA;;GAEG;AACH,wCAFU,YAAY,CAmBQ;AAgB9B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,8CAFU,aAAa,CAgLpB;6BA9P0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_accumulate.js

@@ -0,0 +1,261 @@
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_index_to_grid2d } from "../../../shader/chunk/grid/chunk_index_to_grid2d.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { BRICK_TRACE_MISS, BRICK_TRACE_UNRESOLVED } from "../brick/BRICK_CLIPMAP.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_ray_texel,
+    PROBE_DEPTH_HISTORY_RESOURCE,
+    PROBE_MAPS_WRITE_RESOURCE,
+    PROBE_ORIGINS_READ_RESOURCE,
+    PROBE_RADIANCE_HISTORY_RESOURCE,
+    PROBE_RAY_STRUCT,
+    PROBE_RAYS_READ_RESOURCE,
+    PROBE_RECORDS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import {
+    PROBE_BACK_FACE_DEPTH,
+    PROBE_DEPTH_LIMIT,
+    PROBE_RADIANCE_SAMPLES_LIMIT,
+    PROBE_THREAD_WORKGROUP_SIZE
+} from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ACCUMULATE_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays an update casts, R */
+    rays_per_probe: u32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** octahedral depth texels a side, n_d */
+    depth_resolution: u32,
+    /** tiles a row of the radiance atlas */
+    radiance_tiles_per_row: u32,
+    /** tiles a row of the depth atlas */
+    depth_tiles_per_row: u32,
+    /** the frame's time on the records' clock, seconds */
+    time: f32,
+    /** the blend's response time, τ, seconds */
+    response_time: f32,
+}, "ProbeAccumulateSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_ACCUMULATE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_READ_RESOURCE)
+    .add(PROBE_RAYS_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_MAPS_WRITE_RESOURCE)
+    .add(PROBE_RADIANCE_HISTORY_RESOURCE)
+    .add(PROBE_DEPTH_HISTORY_RESOURCE);
+
+/**
+ * Accumulate (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a texel of each listed probe's maps,
+ * the n_r² radiance texels then the n_d² depth texels, dispatched through `PROBE_DISPATCH_TEXELS`. Each
+ * gathers its own rays and writes the texel, blended with its history, to the probe's maps in
+ * `probe_maps` (`probe_clipmap_maps_words`): two words a radiance texel, rgba as half floats; then a
+ * word a radiance texel, its rays this update, resolved in the low half and back faces in the high,
+ * which classification sums; then a word a depth texel, its moments as half floats.
+ *
+ * - **Radiance**: the mean of the texel's resolved rays, a back face's being zero, blended by
+ *   α = max(1/(a+1), 1 − e^(−Δt·p/τ)). a is the texel's own count of the updates that reached it, held
+ *   in its alpha; p the updates between a texel's rays, n_r²/R below one ray a texel. Counting a texel
+ *   rather than the probe keeps α right where an update covers a subset: a texel's first ray is taken
+ *   whole whenever it comes. A texel no ray reached keeps its history.
+ * - **Depth**: the moments (d, d²) of the rays landing in the texel, in spacings: a miss √3, a back
+ *   face 0.2·t (DDGI 2021's shortening), a hit t, every sample held to √3 (D9). Blended by the probe's
+ *   α = max(1/(n+1), 1 − e^(−Δt/τ)), n its updates. At most 64 rays a texel, which the settings hold
+ *   R to (R ≤ 64·n_d²).
+ * - **A new probe's history is another probe's**, its slot's last owner: on its first update a texel
+ *   no ray reached is cleared, radiance to nothing seen, depth to the moments of a miss.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_accumulate = ComputeShader.from({
+    label: "Probe Clipmap Accumulate",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+fn probe_accumulate_light(ray: ${PROBE_RAY_STRUCT.wgsl_ref}) -> vec3<f32> {
+    return vec3<f32>(unpack2x16float(ray.light_rg), unpack2x16float(ray.light_b).x);
+}
+
+// a ray's depth sample, in spacings: past a miss's, as far as a sample goes
+fn probe_accumulate_depth(ray: ${PROBE_RAY_STRUCT.wgsl_ref}, spacing: f32) -> f32 {
+    if ((ray.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_MISS}u) {
+        return ${PROBE_DEPTH_LIMIT};
+    }
+
+    let t = ray.t / spacing;
+
+    return min(select(t, ${PROBE_BACK_FACE_DEPTH} * t, (ray.flags & PROBE_RAY_BACK_FACE) != 0u), ${PROBE_DEPTH_LIMIT});
+}
+
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let thread = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+
+    let n = settings.radiance_resolution;
+    let m = settings.depth_resolution;
+    let texels = n * n;
+    let per_probe = texels + m * m;
+
+    if (thread >= min(probe_trace.count, settings.trace_capacity) * per_probe) {
+        return;
+    }
+
+    let k = thread / per_probe;
+    let i = thread % per_probe;
+    let slot = probe_trace.elements[k];
+
+    let rays = settings.rays_per_probe;
+    let first_ray = k * rays;
+    let updates = probe_state_updates(probe_states[slot].x);
+    let elapsed = max(settings.time - probe_records[slot].traced_time, 0.0);
+    let rounds = max(rays / texels, 1u);
+
+    let maps = k * probe_clipmap_maps_words(n, m);
+
+    if (i < texels) {
+        var sum = vec3<f32>(0.0);
+        var count = 0u;
+        var back_faces = 0u;
+
+        for (var round = 0u; round < rounds; round++) {
+            let ray = probe_clipmap_texel_ray(i, round, updates, rays, texels);
+
+            if (ray == PROBE_CLIPMAP_NONE) {
+                continue;
+            }
+
+            let record = probe_rays[first_ray + ray];
+
+            if ((record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_UNRESOLVED}u) {
+                continue;
+            }
+
+            sum += probe_accumulate_light(record);
+            count++;
+            back_faces += select(0u, 1u, (record.flags & PROBE_RAY_BACK_FACE) != 0u);
+        }
+
+        let tile = index_to_grid2d(slot, settings.radiance_tiles_per_row) * (n + 2u) + 1u;
+        let history = select(textureLoad(probe_radiance, tile + vec2<u32>(i % n, i / n), 0), vec4<f32>(0.0), updates == 0u);
+
+        var texel = history;
+
+        if (count > 0u) {
+            let period = max(1.0, f32(texels) / f32(rays));
+            let alpha = max(1.0 / (history.a + 1.0), 1.0 - exp(-elapsed * period / settings.response_time));
+
+            texel = vec4<f32>(mix(history.rgb, sum / f32(count), alpha), min(history.a + 1.0, ${PROBE_RADIANCE_SAMPLES_LIMIT}.0));
+        }
+
+        probe_maps[maps + 2u * i] = pack2x16float(texel.rg);
+        probe_maps[maps + 2u * i + 1u] = pack2x16float(texel.ba);
+        probe_maps[maps + 2u * texels + i] = count | (back_faces << 16u);
+
+        return;
+    }
+
+    let j = i - texels;
+    let at = vec2<u32>(j % m, j / m);
+    let spacing = probe_origins[k].w;
+
+    var sum = vec2<f32>(0.0);
+    var count = 0u;
+
+    if (n >= m) {
+        // the radiance texels inside this one: their rays land in it
+        let f = n / m;
+
+        for (var v = 0u; v < f; v++) {
+            for (var u = 0u; u < f; u++) {
+                let texel = (at.y * f + v) * n + at.x * f + u;
+
+                for (var round = 0u; round < rounds; round++) {
+                    let ray = probe_clipmap_texel_ray(texel, round, updates, rays, texels);
+
+                    if (ray == PROBE_CLIPMAP_NONE) {
+                        continue;
+                    }
+
+                    let record = probe_rays[first_ray + ray];
+
+                    if ((record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_UNRESOLVED}u) {
+                        continue;
+                    }
+
+                    let d = probe_accumulate_depth(record, spacing);
+
+                    sum += vec2<f32>(d, d * d);
+                    count++;
+                }
+            }
+        }
+    } else {
+        // the radiance texel this one is inside: those of its rays whose direction lands here
+        let f = m / n;
+        let texel = (at.y / f) * n + at.x / f;
+
+        for (var round = 0u; round < rounds; round++) {
+            let ray = probe_clipmap_texel_ray(texel, round, updates, rays, texels);
+
+            if (ray == PROBE_CLIPMAP_NONE) {
+                continue;
+            }
+
+            let record = probe_rays[first_ray + ray];
+            // the record holds the direction as its octahedral uv
+            let landing = min(vec2<u32>(unpack2x16unorm(record.direction) * f32(m)), vec2<u32>(m - 1u));
+
+            if (any(landing != at) || (record.flags & PROBE_RAY_KIND_MASK) == ${BRICK_TRACE_UNRESOLVED}u) {
+                continue;
+            }
+
+            let d = probe_accumulate_depth(record, spacing);
+
+            sum += vec2<f32>(d, d * d);
+            count++;
+        }
+    }
+
+    let tile = index_to_grid2d(slot, settings.depth_tiles_per_row) * (m + 2u) + 1u;
+
+    var moments = textureLoad(probe_depth, tile + at, 0).rg;
+
+    if (count > 0u) {
+        let alpha = max(1.0 / f32(updates + 1u), 1.0 - exp(-elapsed / settings.response_time));
+
+        moments = mix(moments, sum / f32(count), alpha);
+    } else if (updates == 0u) {
+        moments = vec2<f32>(${PROBE_DEPTH_LIMIT}, ${PROBE_DEPTH_LIMIT} * ${PROBE_DEPTH_LIMIT});
+    }
+
+    probe_maps[maps + 3u * texels + j] = pack2x16float(moments);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_probe_clipmap_ray_texel,
+            chunk_folded_workgroup_index,
+            chunk_index_to_grid2d,
+            PROBE_RAY_STRUCT.declaration_chunk,
+        ]),
+});

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ADMIT_COMMAND_SETTINGS: WebGPUStruct;
+/**
+ * Admit's command (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): one thread, after want. A thread a
+ * wanted point, folded past the per-dimension limit, at `PROBE_DISPATCH_ADMIT`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_admit_command: ComputeShader;
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ADMIT_SETTINGS: WebGPUStruct;
+/**
+ * Admit (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a point wanted this frame, dispatched
+ * through `PROBE_DISPATCH_ADMIT`.
+ *
+ * A point that has a probe has its wanted time brought to the frame's. One that has none pops a slot:
+ * the slot becomes a NEW probe at the point the cascade's window holds in that storage cell, with
+ * nothing traced, its indirection entry names it, and it goes on the frame's active list. A pop the
+ * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
+ * point is wanted again the next frame.
+ *
+ * Retire ran first, so an entry that names a slot names the probe of this very point: the window holds
+ * one point a storage cell, and a probe whose point left was freed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_admit: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_admit.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_admit.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH,2CAFU,YAAY,CAKU;AAUhC;;;;;GAKG;AACH,iDAFU,aAAa,CAqBpB;AAEH;;GAEG;AACH,mCAFU,YAAY,CAWG;AAgBzB;;;;;;;;;;;;;;GAcG;AACH,yCAFU,aAAa,CA6DpB;6BAhK0B,sCAAsC;8BAHrC,kCAAkC"}

package/src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_admit.js

@@ -0,0 +1,169 @@
+import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
+import { chunk_folded_dispatch } from "../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_ACTIVE_WRITE_RESOURCE,
+    PROBE_COUNTERS_RESOURCE,
+    PROBE_DISPATCH_RESOURCE,
+    PROBE_FREE_RESOURCE,
+    PROBE_INDIRECTION_STORE_RESOURCE,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_RECORDS_STORE_RESOURCE,
+    PROBE_STATES_STORE_RESOURCE,
+    PROBE_WANTED_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ADMIT_COMMAND_SETTINGS = WebGPUStruct.from({
+    /** keys over every cascade: what the wanted list holds at most */
+    key_count: u32,
+}, "ProbeAdmitCommandSettings");
+
+const command_resources = new ShaderResourceSetDescriptor();
+
+command_resources.setImmediate("settings", PROBE_ADMIT_COMMAND_SETTINGS);
+
+command_resources.createGroup()
+    .add(PROBE_WANTED_READ_RESOURCE)
+    .add(PROBE_DISPATCH_RESOURCE);
+
+/**
+ * Admit's command (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): one thread, after want. A thread a
+ * wanted point, folded past the per-dimension limit, at `PROBE_DISPATCH_ADMIT`.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_admit_command = ComputeShader.from({
+    label: "Probe Clipmap Admit Command",
+    resources: command_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let wanted = min(probe_wanted.count, settings.key_count);
+    let folded = folded_dispatch((wanted + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_ADMIT] = folded.x;
+    probe_dispatch[PROBE_DISPATCH_ADMIT + 1u] = folded.y;
+    probe_dispatch[PROBE_DISPATCH_ADMIT + 2u] = folded.z;
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_dispatch,
+        ]),
+});
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_ADMIT_SETTINGS = WebGPUStruct.from({
+    /** slots: the free list's bound, and the active list's */
+    capacity: u32,
+    /** lattice points a cascade's window has a side */
+    resolution: u32,
+    /** keys over every cascade: what the wanted list holds at most */
+    key_count: u32,
+    /** the frame's time, seconds since the clipmap was made */
+    time: f32,
+}, "ProbeAdmitSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_ADMIT_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_INDIRECTION_STORE_RESOURCE)
+    .add(PROBE_STATES_STORE_RESOURCE)
+    .add(PROBE_RECORDS_STORE_RESOURCE)
+    .add(PROBE_COUNTERS_RESOURCE)
+    .add(PROBE_FREE_RESOURCE)
+    .add(PROBE_WANTED_READ_RESOURCE)
+    .add(PROBE_ACTIVE_WRITE_RESOURCE);
+
+/**
+ * Admit (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a point wanted this frame, dispatched
+ * through `PROBE_DISPATCH_ADMIT`.
+ *
+ * A point that has a probe has its wanted time brought to the frame's. One that has none pops a slot:
+ * the slot becomes a NEW probe at the point the cascade's window holds in that storage cell, with
+ * nothing traced, its indirection entry names it, and it goes on the frame's active list. A pop the
+ * free list cannot serve is counted, and the host grows the capacity on it (§7.10's pattern); the
+ * point is wanted again the next frame.
+ *
+ * Retire ran first, so an entry that names a slot names the probe of this very point: the window holds
+ * one point a storage cell, and a probe whose point left was freed.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_admit = ComputeShader.from({
+    label: "Probe Clipmap Admit",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let index = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+
+    var slot = 0u;
+    var admitted = false;
+
+    if (index < min(probe_wanted.count, settings.key_count)) {
+        let resolution = settings.resolution;
+        let key = probe_wanted.elements[index];
+        let cascade = probe_clipmap_key_cascade(key, resolution);
+        let storage = probe_clipmap_key_storage(key, resolution);
+        let texel = probe_clipmap_indirection_texel(cascade, storage, resolution);
+        let entry = textureLoad(probe_indirection, texel).x;
+
+        if (entry != PROBE_CLIPMAP_NONE) {
+            probe_records[entry].wanted_time = settings.time;
+        } else {
+            slot = slot_stack_pop(&probe_counters[PROBE_COUNTER_FREE], &probe_free, settings.capacity);
+
+            if (slot == SLOT_STACK_NONE) {
+                atomicAdd(&probe_counters[PROBE_COUNTER_STARVED], 1u);
+            } else {
+                // field by field: nothing of the slot's last probe stays
+                probe_records[slot].cell = probe_clipmap_window_point(storage, probe_levels[cascade].corner, resolution);
+                probe_records[slot].cascade = cascade;
+                probe_records[slot].wanted_time = settings.time;
+                probe_records[slot].traced_time = settings.time;
+                probe_records[slot].back_face = 0.0;
+                probe_records[slot].sh.CoCg = vec2<f32>(0.0);
+                probe_records[slot].sh.Y = vec4<f32>(0.0);
+
+                // at its lattice point until its first update relocates it
+                probe_states[slot] = vec2<u32>(probe_state(PROBE_STATE_NEW, 0u), 0u);
+
+                textureStore(probe_indirection, texel, vec4<u32>(slot, 0u, 0u, 0u));
+
+                admitted = true;
+            }
+        }
+    }
+
+    collection_u32_append(&probe_active_write, admitted, slot, settings.capacity);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_slot_stack,
+            chunk_collection_u32_append,
+        ]),
+});