@woosh/meep-engine 3.57.0 → 3.59.0

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

@@ -0,0 +1,105 @@
+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 { chunk_texture_octahedral_wrap_texel_coordinates } from "../../../shader/chunk/texture/octahedral/chunk_texture_octahedral_wrap_texel_coordinates.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 { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_DEPTH_STORE_RESOURCE,
+    PROBE_MAPS_READ_RESOURCE,
+    PROBE_RADIANCE_STORE_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_PUBLISH_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: 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,
+}, "ProbePublishSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_PUBLISH_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_MAPS_READ_RESOURCE)
+    .add(PROBE_RADIANCE_STORE_RESOURCE)
+    .add(PROBE_DEPTH_STORE_RESOURCE);
+
+/**
+ * Publish (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.8): a thread a texel of each listed probe's two
+ * tiles, the radiance tile's (n_r + 2)² then the depth tile's (n_d + 2)², dispatched through
+ * `PROBE_DISPATCH_PUBLISH`. A tile is its map with a one-texel skirt, each skirt texel the interior texel
+ * the octahedral fold puts next to it, so a reader's bilinear tap across the edge reads what a wrap would
+ * (`texture_octahedral_skirt_uv`). Every texel is written from the probe's maps, which accumulation
+ * wrote whole: the atlases are only ever stored into here.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_publish = ComputeShader.from({
+    label: "Probe Clipmap Publish",
+    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 thread = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+
+    let n = settings.radiance_resolution;
+    let m = settings.depth_resolution;
+    let radiance_tile = (n + 2u) * (n + 2u);
+    let per_probe = radiance_tile + (m + 2u) * (m + 2u);
+
+    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 maps = k * probe_clipmap_maps_words(n, m);
+
+    if (i < radiance_tile) {
+        let at = vec2<u32>(i % (n + 2u), i / (n + 2u));
+        let source = texture_octahedral_wrap_texel_coordinates(vec2<i32>(at) - 1, i32(n));
+        let texel = source.y * n + source.x;
+        let value = vec4<f32>(unpack2x16float(probe_maps[maps + 2u * texel]), unpack2x16float(probe_maps[maps + 2u * texel + 1u]));
+
+        textureStore(probe_radiance, index_to_grid2d(slot, settings.radiance_tiles_per_row) * (n + 2u) + at, value);
+
+        return;
+    }
+
+    let j = i - radiance_tile;
+    let at = vec2<u32>(j % (m + 2u), j / (m + 2u));
+    let source = texture_octahedral_wrap_texel_coordinates(vec2<i32>(at) - 1, i32(m));
+    let moments = unpack2x16float(probe_maps[maps + 3u * n * n + source.y * m + source.x]);
+
+    textureStore(probe_depth, index_to_grid2d(slot, settings.depth_tiles_per_row) * (m + 2u) + at, vec4<f32>(moments, 0.0, 0.0));
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_index_to_grid2d,
+            chunk_texture_octahedral_wrap_texel_coordinates,
+        ]),
+});

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

@@ -0,0 +1,25 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RELOCATE_SETTINGS: WebGPUStruct;
+/**
+ * Relocate (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.4): a thread a probe the frame updates, at the
+ * start of its update, dispatched through `PROBE_DISPATCH_TRACED`.
+ *
+ * From its lattice point q, with d the brick clipmap's signed field there: while d is short of the
+ * clearance, a quarter of the cascade's spacing, `q += ∇d·(clearance − d)`, at most three times. A probe
+ * inside the field's band is pushed out of the solid, since the field is signed. The offset is clamped
+ * to 0.45 of the spacing on each axis, RTXGI's 45%, so the probe stays in its own lattice cell and the
+ * cages stay the lattice's. A field with no slope says nothing of the way out, as deep in a solid,
+ * and moves nothing: the probe's rays find the solid's inside, and classification takes it.
+ *
+ * The offset goes to the state's second word, where every reader that weighs the probe finds it, and
+ * the probe's origin at that offset, as the encoding holds it, to `probe_origins` at its place in the
+ * list, where the update's passes after it find it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_relocate: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_relocate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_relocate.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_relocate.js"],"names":[],"mappings":"AA6BA;;GAEG;AACH,sCAFU,YAAY,CAOM;AAiB5B;;;;;;;;;;;;;;;;GAgBG;AACH,4CAFU,aAAa,CAsDpB;6BAtH0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -0,0 +1,124 @@
+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 { 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_SAMPLER_RESOURCE,
+    chunk_brick_clipmap_distance,
+    chunk_brick_clipmap_gradient
+} from "../brick/chunk_brick_clipmap_trace.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_ORIGINS_WRITE_RESOURCE,
+    PROBE_RECORDS_READ_RESOURCE,
+    PROBE_STATES_STORE_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import {
+    PROBE_RELOCATION_CLEARANCE,
+    PROBE_RELOCATION_LIMIT,
+    PROBE_RELOCATION_STEPS,
+    PROBE_THREAD_WORKGROUP_SIZE
+} from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RELOCATE_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** the brick clipmap's cascades, what its field is read through */
+    brick_cascade_count: u32,
+}, "ProbeRelocateSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_RELOCATE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_STATES_STORE_RESOURCE)
+    .add(PROBE_RECORDS_READ_RESOURCE)
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_ORIGINS_WRITE_RESOURCE)
+    .add(BRICK_LEVELS_RESOURCE)
+    .add(BRICK_MAP_TEXTURE_RESOURCE)
+    .add(BRICK_ATLAS_TEXTURE_RESOURCE)
+    .add(BRICK_SAMPLER_RESOURCE);
+
+/**
+ * Relocate (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.4): a thread a probe the frame updates, at the
+ * start of its update, dispatched through `PROBE_DISPATCH_TRACED`.
+ *
+ * From its lattice point q, with d the brick clipmap's signed field there: while d is short of the
+ * clearance, a quarter of the cascade's spacing, `q += ∇d·(clearance − d)`, at most three times. A probe
+ * inside the field's band is pushed out of the solid, since the field is signed. The offset is clamped
+ * to 0.45 of the spacing on each axis, RTXGI's 45%, so the probe stays in its own lattice cell and the
+ * cages stay the lattice's. A field with no slope says nothing of the way out, as deep in a solid,
+ * and moves nothing: the probe's rays find the solid's inside, and classification takes it.
+ *
+ * The offset goes to the state's second word, where every reader that weighs the probe finds it, and
+ * the probe's origin at that offset, as the encoding holds it, to `probe_origins` at its place in the
+ * list, where the update's passes after it find it.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_relocate = ComputeShader.from({
+    label: "Probe Clipmap Relocate",
+    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;
+
+    if (index >= min(probe_trace.count, settings.trace_capacity)) {
+        return;
+    }
+
+    let slot = probe_trace.elements[index];
+    let spacing = probe_levels[probe_records[slot].cascade].cell_size;
+    let lattice = vec3<f32>(probe_records[slot].cell) * spacing;
+    let clearance = ${PROBE_RELOCATION_CLEARANCE} * spacing;
+
+    var position = lattice;
+
+    for (var step = 0u; step < ${PROBE_RELOCATION_STEPS}u; step++) {
+        let distance = brick_clipmap_distance(position, settings.brick_cascade_count);
+
+        if (distance >= clearance) {
+            break;
+        }
+
+        let gradient = brick_clipmap_gradient(position, settings.brick_cascade_count);
+
+        if (all(gradient == vec3<f32>(0.0))) {
+            break;
+        }
+
+        position += gradient * (clearance - distance);
+    }
+
+    // the encoding holds each axis to the limit, and the origin is where it puts the probe
+    let offset = probe_clipmap_offset_encode(position - lattice, spacing);
+
+    probe_states[slot].y = offset;
+    probe_origins[index] = vec4<f32>(lattice + probe_clipmap_offset_decode(offset, spacing), spacing);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_brick_clipmap_distance,
+            chunk_brick_clipmap_gradient,
+        ]),
+});

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

@@ -0,0 +1,21 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RETIRE_SETTINGS: WebGPUStruct;
+/**
+ * Retire (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a live probe, the first of the frame's
+ * lifetime passes, dispatched through `PROBE_DISPATCH_ACTIVE` over the list the frame before wrote.
+ *
+ * A probe is freed when its lattice point has left its cascade's window, or when nothing, pixel or hit,
+ * has wanted it for longer than the retention time: its slot goes back on the free list, its state to
+ * FREE, and its indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ *
+ * Running before want means a window's move needs no pass of its own: the storage cells it vacated
+ * are emptied before any point it exposed can claim them.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_retire: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_retire.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_retire.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_retire.js"],"names":[],"mappings":"AAuBA;;GAEG;AACH,oCAFU,YAAY,CAWI;AAgB1B;;;;;;;;;;;;GAYG;AACH,0CAFU,aAAa,CAuDpB;6BA5G0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -0,0 +1,118 @@
+import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
+import { chunk_slot_stack } from "../../../gpu_primitive/slot_stack/chunk_slot_stack.js";
+import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
+import { chunk_clipmap_storage_coord } from "../../../shader/chunk/clipmap/chunk_clipmap_storage_coord.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_READ_RESOURCE,
+    PROBE_ACTIVE_WRITE_RESOURCE,
+    PROBE_COUNTERS_RESOURCE,
+    PROBE_FREE_RESOURCE,
+    PROBE_INDIRECTION_STORE_RESOURCE,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_RECORDS_STORE_RESOURCE,
+    PROBE_STATES_STORE_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_RETIRE_SETTINGS = WebGPUStruct.from({
+    /** slots, which no active list outgrows */
+    capacity: u32,
+    /** lattice points a cascade's window has a side */
+    resolution: u32,
+    /** the frame's time, seconds since the clipmap was made */
+    time: f32,
+    /** seconds an unwanted probe keeps its slot, `retention_time` */
+    retention_time: f32,
+}, "ProbeRetireSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_RETIRE_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_ACTIVE_READ_RESOURCE)
+    .add(PROBE_ACTIVE_WRITE_RESOURCE);
+
+/**
+ * Retire (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a live probe, the first of the frame's
+ * lifetime passes, dispatched through `PROBE_DISPATCH_ACTIVE` over the list the frame before wrote.
+ *
+ * A probe is freed when its lattice point has left its cascade's window, or when nothing, pixel or hit,
+ * has wanted it for longer than the retention time: its slot goes back on the free list, its state to
+ * FREE, and its indirection entry, if it still names the slot, to none. The rest go on the frame's list.
+ *
+ * Running before want means a window's move needs no pass of its own: the storage cells it vacated
+ * are emptied before any point it exposed can claim them.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_retire = ComputeShader.from({
+    label: "Probe Clipmap Retire",
+    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 keep = false;
+
+    if (index < min(probe_active_read.count, settings.capacity)) {
+        slot = probe_active_read.elements[index];
+
+        let cell = probe_records[slot].cell;
+        let cascade = probe_records[slot].cascade;
+        let level = probe_levels[cascade];
+
+        // the lattice's window is one point wider than the cages' on each axis
+        let held = clipmap_contains(cell, level.corner, level.size + vec3<i32>(1));
+
+        keep = held && settings.time - probe_records[slot].wanted_time <= settings.retention_time;
+
+        if (!keep) {
+            let resolution = settings.resolution;
+            let storage = vec3<u32>(clipmap_storage_coord(cell, vec3<i32>(i32(resolution))));
+            let texel = probe_clipmap_indirection_texel(cascade, storage, resolution);
+
+            if (textureLoad(probe_indirection, texel).x == slot) {
+                textureStore(probe_indirection, texel, vec4<u32>(PROBE_CLIPMAP_NONE, 0u, 0u, 0u));
+            }
+
+            probe_states[slot] = vec2<u32>(PROBE_STATE_FREE, 0u);
+
+            slot_stack_push(&probe_counters[PROBE_COUNTER_FREE], &probe_free, slot);
+        }
+    }
+
+    collection_u32_append(&probe_active_write, keep, slot, settings.capacity);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_clipmap_contains,
+            chunk_clipmap_storage_coord,
+            chunk_slot_stack,
+            chunk_collection_u32_append,
+        ]),
+});

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

@@ -0,0 +1,19 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_SCHEDULE_SETTINGS: WebGPUStruct;
+/**
+ * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, after admit, when the frame's active
+ * list is whole.
+ * - The period: with P_w the points wanted this frame, `T = max(1, ⌈P_w / U⌉)` frames, so that every
+ *   wanted probe is updated once a period and the period follows the live count. It goes to
+ *   `probe_counters[PROBE_COUNTER_PERIOD]` for the due passes.
+ * - A thread an entry of the frame's active list, at `PROBE_DISPATCH_ACTIVE`: the due passes' launch, and
+ *   the next frame's retire's, which reads this list.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_schedule: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_schedule.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_schedule.js"],"names":[],"mappings":"AAcA;;GAEG;AACH,sCAFU,YAAY,CASM;AAY5B;;;;;;;;;;GAUG;AACH,4CAFU,aAAa,CA0BpB;6BAlE0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -0,0 +1,72 @@
+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 { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_ACTIVE_WRITTEN_RESOURCE,
+    PROBE_COUNTERS_RESOURCE,
+    PROBE_DISPATCH_RESOURCE,
+    PROBE_WANTED_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_SCHEDULE_SETTINGS = WebGPUStruct.from({
+    /** slots, which no active list outgrows */
+    capacity: u32,
+    /** keys over every cascade: what the wanted list holds at most */
+    key_count: u32,
+    /** probes a frame updates at most, U = ⌊ray_budget / rays_per_probe⌋ */
+    trace_capacity: u32,
+}, "ProbeScheduleSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_SCHEDULE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_ACTIVE_WRITTEN_RESOURCE)
+    .add(PROBE_WANTED_READ_RESOURCE)
+    .add(PROBE_COUNTERS_RESOURCE)
+    .add(PROBE_DISPATCH_RESOURCE);
+
+/**
+ * Schedule (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): one thread, after admit, when the frame's active
+ * list is whole.
+ * - The period: with P_w the points wanted this frame, `T = max(1, ⌈P_w / U⌉)` frames, so that every
+ *   wanted probe is updated once a period and the period follows the live count. It goes to
+ *   `probe_counters[PROBE_COUNTER_PERIOD]` for the due passes.
+ * - A thread an entry of the frame's active list, at `PROBE_DISPATCH_ACTIVE`: the due passes' launch, and
+ *   the next frame's retire's, which reads this list.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_schedule = ComputeShader.from({
+    label: "Probe Clipmap Schedule",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let wanted = min(probe_wanted.count, settings.key_count);
+    let traced = max(settings.trace_capacity, 1u);
+
+    atomicStore(&probe_counters[PROBE_COUNTER_PERIOD], max((wanted + traced - 1u) / traced, 1u));
+
+    let live = min(probe_active_write.count, settings.capacity);
+    let folded = folded_dispatch((live + PROBE_THREAD_WORKGROUP_SIZE - 1u) / PROBE_THREAD_WORKGROUP_SIZE);
+
+    probe_dispatch[PROBE_DISPATCH_ACTIVE] = folded.x;
+    probe_dispatch[PROBE_DISPATCH_ACTIVE + 1u] = folded.y;
+    probe_dispatch[PROBE_DISPATCH_ACTIVE + 2u] = folded.z;
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_dispatch,
+        ]),
+});

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

@@ -0,0 +1,25 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_SHADE_SETTINGS: WebGPUStruct;
+/**
+ * Shade (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a thread a ray of the frame's updates, R a listed
+ * probe, dispatched through `PROBE_DISPATCH_RAYS` after trace. The radiance the ray brings back goes
+ * over its light, three half floats:
+ *
+ * - a **miss** sees the environment along its direction, `sample_environment_color`;
+ * - a **front-face hit** is `emissive + ρ_d·E_dir/π` (D7), its surface from `probe_clipmap_hit_surface`
+ *   at the hit's position, the probe's origin plus t along the ray, with the hit's normal, at its
+ *   cascade's voxel; E_dir is what trace left in the light;
+ * - an **unresolved** ray and a **back face** bring nothing back: accumulation discards the one and
+ *   counts the other (§8.4, §8.8).
+ *
+ * A front-face hit's diffuse albedo goes over its `row`, `pack4x8unorm`, and every other ray's row to
+ * zero: the light pass adds ρ_d·(E_loc + E_ind)/π after it (S5).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_shade: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_shade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_shade.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_shade.js"],"names":[],"mappings":"AAyCA;;GAEG;AACH,mCAFU,YAAY,CAOG;AAyBzB;;;;;;;;;;;;;;;;GAgBG;AACH,yCAFU,aAAa,CAuDpB;6BA9H0B,sCAAsC;8BAHrC,kCAAkC"}