@woosh/meep-engine 3.59.0 → 3.60.1

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

@@ -12,10 +12,9 @@ import {
     PROBE_COUNTERS_READ_RESOURCE,
     PROBE_RECORDS_READ_RESOURCE,
     PROBE_STATES_READ_RESOURCE,
-    PROBE_TRACE_WRITE_RESOURCE,
-    PROBE_WANTED_BITS_READ_RESOURCE
+    PROBE_TRACE_WRITE_RESOURCE
 } from "./chunk_probe_clipmap.js";
-import { PROBE_DEAD_PERIODS, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
 
 /**
  * @type {WebGPUStruct}
@@ -23,8 +22,6 @@ import { PROBE_DEAD_PERIODS, PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP
 export const PROBE_DUE_SETTINGS = WebGPUStruct.from({
     /** slots, which no active list outgrows */
     capacity: u32,
-    /** lattice points a cascade's window has a side */
-    resolution: u32,
     /** probes a frame updates at most, U = ⌊ray_budget / rays_per_probe⌋: the trace list's bound */
     trace_capacity: u32,
     /** the frame's index, what a probe's turn in its period is counted by */
@@ -41,21 +38,29 @@ resources.createGroup()
     .add(PROBE_STATES_READ_RESOURCE)
     .add(PROBE_RECORDS_READ_RESOURCE)
     .add(PROBE_COUNTERS_READ_RESOURCE)
-    .add(PROBE_WANTED_BITS_READ_RESOURCE)
     .add(PROBE_ACTIVE_WRITTEN_RESOURCE)
     .add(PROBE_TRACE_WRITE_RESOURCE);
 
 /**
  * Due (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.5): a thread an entry of the frame's active list,
  * dispatched twice through `PROBE_DISPATCH_ACTIVE` after schedule has set the period T. A probe is due
- * when a pixel or a hit wanted it this frame, its point's bit set, and:
- * - it is NEW, in the first pass, which lists them first;
- * - in the second pass, it is ALIVE and `(frame + h(slot)) mod T` is 0, or DEAD and
- *   `(frame + h(slot)) mod 8T` is 0, so that a probe inside a solid notices when the scene changes.
+ * when a want waits on it:
+ * - it is NEW, in the first pass, which lists them first: it has had no update;
+ * - in the second pass, it is ALIVE or DEAD, a pixel or a hit wanted it since its last update, its
+ *   wanted time past its traced time, and `(frame + h(slot)) mod T` is 0. A DEAD probe's update casts
+ *   the fewest rays (`PROBE_RAYS_PER_TEXEL_MIN`), every period rather than every eighth at R, so that a
+ *   probe inside a solid notices when the scene changes sooner, for fewer rays (Enshrouded's dead probes
+ *   trace 16 a frame).
+ *
+ * Wanted since its last update, not this frame: a hit wants a probe the frame after its own probe's
+ * update, so a probe that only hits keep is wanted on few of its turns. Measured on Sponza with the
+ * point's bit as the test, the hits' probes were updated 0.8 times a second at p10 against the screen's
+ * 6.6 at the least, and 6 s had passed since the last update at p99 (§8.3). A want an update served
+ * waits on nothing: the update comes after admit in its frame, so its traced time is the want's or later.
  *
  * The due go on the trace list, which holds the frame's updates, at most U: past it the count still
- * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ the
- * expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
+ * rises and nothing is written, and a probe not listed waits its next turn. With T = ⌈P_w / U⌉ over the
+ * probes waiting, the expected count a frame is under U, so only NEW probes past U, a camera cut, wait.
  *
  * @type {ComputeShader}
  */
@@ -80,22 +85,16 @@ fn main(
 
         let kind = probe_state_kind(probe_states[slot].x);
 
-        // wanted this frame: its point's bit
-        let resolution = settings.resolution;
-        let storage = vec3<u32>(probe_records[slot].cell) & vec3<u32>(resolution - 1u);
-        let key = probe_clipmap_key(probe_records[slot].cascade, storage, resolution);
-        let wanted = (probe_wanted_bits[key >> 5u] & (1u << (key & 31u))) != 0u;
+        // wanted since its last update
+        let waiting = probe_records[slot].wanted_frame > probe_records[slot].traced_frame;
 
         let period = max(probe_counters[PROBE_COUNTER_PERIOD], 1u);
         let turn = settings.frame + hash_lowbias32(slot);
 
         if (settings.new_only != 0u) {
-            due = wanted && kind == PROBE_STATE_NEW;
+            due = kind == PROBE_STATE_NEW;
         } else {
-            due = wanted && (
-                (kind == PROBE_STATE_ALIVE && turn % period == 0u)
-                || (kind == PROBE_STATE_DEAD && turn % (${PROBE_DEAD_PERIODS}u * period) == 0u)
-            );
+            due = waiting && (kind == PROBE_STATE_ALIVE || kind == PROBE_STATE_DEAD) && turn % period == 0u;
         }
     }
 

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

@@ -0,0 +1,36 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_GUIDE_SETTINGS: WebGPUStruct;
+/**
+ * The guide, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a row of each listed probe's
+ * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the luminance of the row's history
+ * texels, which the weights' pass totals.
+ *
+ * The guide is built for every update. A guided update's trace casts its rays by it, and accumulation
+ * takes each texel's share of the guided updates' rays from it, uniform update or not.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_rows: ComputeShader;
+/**
+ * The guide, weights (§8.6): a thread a row of each listed probe's radiance map, dispatched through
+ * `PROBE_DISPATCH_ROWS`. It totals the rows' luminance, then weighs each of the row's texels by its share
+ * (`probe_clipmap_guide_weight`) and sums the row's weights, which the starts' pass totals.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_weights: ComputeShader;
+/**
+ * The guide, starts (§8.6): a thread a row of the walk of each listed probe's radiance map, dispatched
+ * through `PROBE_DISPATCH_ROWS`. It totals the weights and spreads what they leave of
+ * `PROBE_GUIDE_SCALE` evenly. It takes the weight the walk covers before its row from the row weights,
+ * then writes the first ray of each of its walk positions. The walk's first row writes the total and the
+ * even share as well.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_starts: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_guide.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_guide.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_guide.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,mCAFU,YAAY,CAWG;AAkEzB;;;;;;;;;GASG;AACH,8CAFU,aAAa,CAgCpB;AAEH;;;;;;GAMG;AACH,iDAFU,aAAa,CA4CpB;AAEH;;;;;;;;GAQG;AACH,gDAFU,aAAa,CA2DpB;6BA1P0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -0,0 +1,257 @@
+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 { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_ray_layout,
+    PROBE_GUIDE_WRITE_RESOURCE,
+    PROBE_RADIANCE_HISTORY_RESOURCE,
+    PROBE_RAY_SUMS_READ_RESOURCE,
+    PROBE_STATES_READ_RESOURCE,
+    PROBE_TRACE_READ_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_GUIDE_SETTINGS = WebGPUStruct.from({
+    /** probes a frame updates at most: the trace list's bound */
+    trace_capacity: u32,
+    /** rays a uniform update casts, R; the guide walks its probe's own (`probe_ray_sums`) */
+    rays_per_probe: u32,
+    /** octahedral radiance texels a side, n_r */
+    radiance_resolution: u32,
+    /** tiles a row of the radiance atlas */
+    radiance_tiles_per_row: u32,
+}, "ProbeGuideSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_GUIDE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_TRACE_READ_RESOURCE)
+    .add(PROBE_STATES_READ_RESOURCE)
+    .add(PROBE_RADIANCE_HISTORY_RESOURCE)
+    .add(PROBE_RAY_SUMS_READ_RESOURCE)
+    .add(PROBE_GUIDE_WRITE_RESOURCE);
+
+/**
+ * What every guide pass opens with: the thread's listed probe `k` and row, the rays its update casts,
+ * and where the probe's guide and history tile start. A thread past the list returns.
+ */
+const chunk_probe_clipmap_guide_thread = CodeChunk.from(
+    //language=WGSL
+    `
+struct ProbeGuideThread {
+    valid: bool,
+    k: u32,
+    row: u32,
+    rays: u32,
+    slot: u32,
+    updates: u32,
+    base: u32,
+    tile: vec2<u32>,
+}
+
+fn probe_guide_thread(workgroup_id: vec3<u32>, lane: u32) -> ProbeGuideThread {
+    var out: ProbeGuideThread;
+
+    let thread = folded_workgroup_index(workgroup_id) * PROBE_THREAD_WORKGROUP_SIZE + lane;
+    let n = settings.radiance_resolution;
+
+    out.valid = thread < min(probe_trace.count, settings.trace_capacity) * n;
+
+    if (!out.valid) {
+        return out;
+    }
+
+    out.k = thread / n;
+    out.row = thread % n;
+    out.rays = probe_clipmap_probe_rays(out.k).y;
+    out.slot = probe_trace.elements[out.k];
+    out.updates = probe_state_updates(probe_states[out.slot].x);
+    out.base = out.k * probe_clipmap_guide_words(n);
+    out.tile = index_to_grid2d(out.slot, settings.radiance_tiles_per_row) * (n + 2u) + 1u;
+
+    return out;
+}
+
+// the luminance of the history's texel (x, y) in the thread's tile
+fn probe_guide_texel_luminance(thread: ProbeGuideThread, x: u32, y: u32) -> f32 {
+    return probe_clipmap_guide_luminance(textureLoad(probe_radiance, thread.tile + vec2<u32>(x, y), 0).rgb);
+}
+`, [
+    chunk_probe_clipmap,
+    chunk_probe_clipmap_guide,
+    chunk_probe_clipmap_ray_layout,
+    chunk_folded_workgroup_index,
+    chunk_index_to_grid2d,
+]);
+
+/**
+ * The guide, rows (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.6): a thread a row of each listed probe's
+ * radiance map, dispatched through `PROBE_DISPATCH_ROWS`. It sums the luminance of the row's history
+ * texels, which the weights' pass totals.
+ *
+ * The guide is built for every update. A guided update's trace casts its rays by it, and accumulation
+ * takes each texel's share of the guided updates' rays from it, uniform update or not.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_rows = ComputeShader.from({
+    label: "Probe Clipmap Guide Rows",
+    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 = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+
+    var sum = 0.0;
+
+    for (var x = 0u; x < n; x++) {
+        sum += probe_guide_texel_luminance(thread, x, thread.row);
+    }
+
+    probe_guide[thread.base + 2u * n * n + thread.row] = bitcast<u32>(sum);
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});
+
+/**
+ * The guide, weights (§8.6): a thread a row of each listed probe's radiance map, dispatched through
+ * `PROBE_DISPATCH_ROWS`. It totals the rows' luminance, then weighs each of the row's texels by its share
+ * (`probe_clipmap_guide_weight`) and sums the row's weights, which the starts' pass totals.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_weights = ComputeShader.from({
+    label: "Probe Clipmap Guide Weights",
+    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 = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+    let texels = n * n;
+    let rows = thread.base + 2u * texels;
+
+    var total = 0.0;
+
+    for (var y = 0u; y < n; y++) {
+        total += bitcast<f32>(probe_guide[rows + y]);
+    }
+
+    var row_weight = 0u;
+
+    for (var x = 0u; x < n; x++) {
+        let texel = thread.row * n + x;
+        let weight = probe_clipmap_guide_weight(probe_guide_texel_luminance(thread, x, thread.row), total, thread.rays, texels);
+
+        probe_guide[thread.base + texels + texel] = weight;
+        row_weight += weight;
+    }
+
+    probe_guide[rows + n + thread.row] = row_weight;
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});
+
+/**
+ * The guide, starts (§8.6): a thread a row of the walk of each listed probe's radiance map, dispatched
+ * through `PROBE_DISPATCH_ROWS`. It totals the weights and spreads what they leave of
+ * `PROBE_GUIDE_SCALE` evenly. It takes the weight the walk covers before its row from the row weights,
+ * then writes the first ray of each of its walk positions. The walk's first row writes the total and the
+ * even share as well.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_guide_starts = ComputeShader.from({
+    label: "Probe Clipmap Guide Starts",
+    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 = probe_guide_thread(workgroup_id, lane);
+
+    if (!thread.valid) {
+        return;
+    }
+
+    let n = settings.radiance_resolution;
+    let texels = n * n;
+    let rays = thread.rays;
+    let row_weights = thread.base + 2u * texels + n;
+
+    var weights = 0u;
+
+    for (var y = 0u; y < n; y++) {
+        weights += probe_guide[row_weights + y];
+    }
+
+    // the shares, each rounded to f32, may sum a few units past the scale
+    let share = select(0u, (PROBE_GUIDE_SCALE - weights) / texels, weights < PROBE_GUIDE_SCALE);
+    let total = weights + share * texels;
+
+    // the walk's rows before this one, each a row of the map
+    var before = 0u;
+
+    for (var r = 0u; r < thread.row; r++) {
+        before += probe_guide[row_weights + probe_clipmap_guide_texel(r * n, thread.updates, n) / n] + share * n;
+    }
+
+    let phase = probe_clipmap_guide_phase(thread.slot, thread.updates);
+
+    for (var c = 0u; c < n; c++) {
+        let position = thread.row * n + c;
+
+        probe_guide[thread.base + position] = probe_clipmap_guide_start(before, total, rays, phase);
+
+        before += probe_guide[thread.base + texels + probe_clipmap_guide_texel(position, thread.updates, n)] + share;
+    }
+
+    if (thread.row == 0u) {
+        probe_guide[row_weights + n] = total;
+        probe_guide[row_weights + n + 1u] = share;
+    }
+}
+`, [
+            chunk_probe_clipmap_guide_thread,
+        ]),
+});

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

@@ -1,13 +1,24 @@
 /**
  * The light a front-face hit takes from beyond the trace (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.7): a
- * thread a ray, after shade through the same launch, `PROBE_DISPATCH_RAYS`. It adds ρ_d·(E_loc + E_ind)/π
- * to the radiance shade left, ρ_d being the albedo shade left in the ray's \`row\`.
+ * thread a ray, after shade through the same launch, `PROBE_DISPATCH_RAYS`, its probe the one trace wrote
+ * into its flags. It adds ρ_d·(E_loc + E_ind)/π to the radiance shade left, ρ_d being the albedo shade
+ * left in the ray's \`row\`.
  *
- * - **E_loc, the local lights**: the point and spot lights of the hit's cell of the world light clusters,
- *   built over the bricks' cascades so that every hit has one, at most `IRRADIANCE_CLIPMAP_LIGHT_BUDGET` of
- *   each; past them lights are dropped. Each is the irradiance clipmap's, at the footprint of a voxel of
- *   the hit's cascade, its cosine at the hit's normal, and its shadow map's nearest texel from a voxel off
- *   the surface, past the field's half-voxel expand. A light whose map is cleared lights hits unshadowed.
+ * - **E_loc, the local lights**: one of the point and spot lights of the hit's cell of the world light
+ *   clusters, built over the bricks' cascades so that every hit has one, at most
+ *   `IRRADIANCE_CLIPMAP_LIGHT_BUDGET` of each; past them lights are dropped. Each light's unshadowed
+ *   irradiance is the irradiance clipmap's, at the footprint of a voxel of the hit's cascade, by its
+ *   cosine at the hit's normal.
+ *   - One is picked by weighted reservoir sampling over the cell's lights, its weight the luminance of
+ *     that irradiance, with one number stretched over the candidates as `sample_discrete_wrs` does; it
+ *     lights the hit by its irradiance over the chance of its pick, w/W. The probe's blend of its rays
+ *     averages the picks to the cell's sum.
+ *   - The picked light's shadow is a ray traced through the brick clipmap, as the hit's own ray was:
+ *     from a voxel off the surface, past the field's half-voxel expand, toward a point of the light's
+ *     sphere drawn as the path tracer draws it, stopping short of that point by the light's near clip or
+ *     a voxel, whichever is more, for the expand at that end. It sees the light if it misses; a hit, or a
+ *     march that spends its steps, is no light. A light that casts no shadow traces none.
+ *   - The pick and the point are drawn from the ray's slot and direction, fresh every update.
  * - **E_ind, the next bounce**: this mode's own diffuse at the hit, `probe_clipmap_sample_sh` from the
  *   hit along its normal, the view back along the ray, with the ray's own jitter as the pick's noise.
  *   The projection writes the records later in the frame, so they hold last frame's SH: each frame takes

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

@@ -1 +1 @@
-{"version":3,"file":"shader_probe_clipmap_light.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAFU,aAAa,CAmHpB;8BAlM2B,kCAAkC"}
+{"version":3,"file":"shader_probe_clipmap_light.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_light.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,yCAFU,aAAa,CA6LpB;8BApS2B,kCAAkC"}