@woosh/meep-engine 3.64.0 → 3.65.0

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

@@ -36,9 +36,26 @@ export const PROBE_WANT_SETTINGS = WebGPUStruct.from({
     select_half: f32,
 }, "ProbeWantSettings");
 
+/**
+ * {@link PROBE_WANT_SETTINGS} and how the surface's normals are read.
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_SURFACE_SETTINGS = WebGPUStruct.from({
+    cascade_count: u32,
+    resolution: u32,
+    frame: u32,
+    wanted_capacity: u32,
+    anchor: vec3f,
+    select_half: f32,
+    /** the channel of the normals' texel that holds the normal: 0 to 3 */
+    normal_channel: u32,
+    /** non-zero where a normal may face away from the eye and its reader turns it to face it */
+    two_sided: u32,
+}, "ProbeWantSurfaceSettings");
+
 const resources = new ShaderResourceSetDescriptor();
 
-resources.setImmediate("settings", PROBE_WANT_SETTINGS);
+resources.setImmediate("settings", PROBE_WANT_SURFACE_SETTINGS);
 
 resources.createGroup()
     .addTexture("gBufferDepth")
@@ -57,6 +74,12 @@ resources.createGroup()
  * that pixel's pick reads (§9.1), biased along `mix(n, v, 0.2)`, through `probe_clipmap_want`. A sky
  * pixel wants nothing.
  *
+ * The surface is any the frame holds a depth and a normal of, a pixel each: the G-buffer's, or one drawn
+ * apart from it whose reader picks its probes per pixel, the water's interface. `gBufferDepth` is its
+ * reverse-Z depth, zero where it has no surface; `gBufferNormals` its normals, octahedral in the channel
+ * `settings.normal_channel`, as the G-buffer packs its own in its first. Where `settings.two_sided` is set,
+ * a normal that faces away from the eye is turned to face it, as a reader of such a surface turns it.
+ *
  * At a cascade's outer edge a lattice cell is 58 pixels on a 1080p screen at a 60° field of view, and
  * 19 at 120°, so a tile of 8 samples every cell several times a frame, and a workgroup's 64 tiles want
  * a few cages between them, which its claims keep to one want each.
@@ -83,8 +106,12 @@ fn main(@builtin(global_invocation_id) id: vec3<u32>) {
 
     let uv = (vec2<f32>(pixel) + 0.5) / vec2<f32>(size);
     let position = project_position_from_depth(uv, depth, camera.view_projection_matrix_inverse);
-    let normal = decode_g_buffer_normal(textureLoad(gBufferNormals, pixel, 0).x);
+    let texel = textureLoad(gBufferNormals, pixel, 0);
+    // each channel by name: a dynamic index would put the texel in local memory
+    let encoded = select(select(texel.x, texel.y, settings.normal_channel == 1u), select(texel.z, texel.w, settings.normal_channel == 3u), settings.normal_channel >= 2u);
+    let stored = decode_g_buffer_normal(encoded);
     let view_direction = normalize(mat4_extract_position(camera.transform) - position);
+    let normal = select(stored, -stored, settings.two_sided != 0u && dot(stored, view_direction) < 0.0);
     let bias_direction = mix(normal, view_direction, ${PROBE_RECEIVER_BIAS_VIEW});
 
     probe_clipmap_want(on_screen && !is_background(depth), position, bias_direction, settings.cascade_count, settings.resolution, settings.anchor, settings.select_half, settings.wanted_capacity);

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

@@ -0,0 +1,40 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_LATE_SETTINGS: WebGPUStruct;
+/**
+ * The keys wanted since the last lifetime, each once, as the late wants listed them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_WANTED_READ_RESOURCE: ShaderResourceDescriptor;
+/**
+ * A bit a key of the late list, cleared as the key is taken.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_WANTED_BITS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The cage windows the late list's keys were written in: the levels of the frame before.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_LEVELS_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The late wants taken into the frame's (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a key of the late
+ * list, through a launch its count sizes.
+ *
+ * A reader whose surface is drawn after the frame's lifetime wants its probes into the late set, through
+ * `probe_clipmap_want` as any want does, and the next lifetime runs this between its own wants and admit. A key
+ * the frame's set lacks goes on its list; either way the key's late bit is cleared, which leaves the late bits
+ * empty, and the host empties the list.
+ *
+ * A key names a storage cell, and the lattice point it stands for is the one its writer's window held there. Where
+ * a window has moved since, the cell of a point it left stands for the point that came in across from it, which
+ * nothing wanted: a key is taken only where the present window's point is one the writer's window
+ * (`probe_late_levels`) held too.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_late: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_want_late.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_want_late.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_late.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,uCAFU,YAAY,CASM;AAE5B;;;GAGG;AACH,8CAFU,wBAAwB,CAEqG;AAEvI;;;GAGG;AACH,8CAFU,wBAAwB,CAEkH;AAEpJ;;;GAGG;AACH,yCAFU,wBAAwB,CAEmF;AAcrH;;;;;;;;;;;;;;;GAeG;AACH,6CAFU,aAAa,CAkDpB;6BAnH0B,sCAAsC;yCAJ1B,sDAAsD;8BADjE,kCAAkC"}

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

@@ -0,0 +1,126 @@
+import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { chunk_collection_u32_append } from "../../../gpu_primitive/chunk_collection_u32_append.js";
+import { chunk_clipmap_contains } from "../../../shader/chunk/clipmap/chunk_clipmap_contains.js";
+import { CLIPMAP_LEVEL_ARRAY, CLIPMAP_LEVEL_STRUCT } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceDescriptor } from "../../../shader/resource/ShaderResourceDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_WANTED_BITS_RESOURCE,
+    PROBE_WANTED_WRITE_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { PROBE_THREAD_WORKGROUP_SIZE } from "./PROBE_CLIPMAP.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const PROBE_WANT_LATE_SETTINGS = WebGPUStruct.from({
+    /** lattice points a cascade's window has a side */
+    resolution: u32,
+    /** what the frame's wanted list holds at most */
+    wanted_capacity: u32,
+    /** what the late list holds at most: every key */
+    late_capacity: u32,
+}, "ProbeWantLateSettings");
+
+/**
+ * The keys wanted since the last lifetime, each once, as the late wants listed them.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_WANTED_READ_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_late_wanted", COLLECTION_U32_STRUCT_READ);
+
+/**
+ * A bit a key of the late list, cleared as the key is taken.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_WANTED_BITS_RESOURCE = ShaderResourceDescriptor.storageBuffer("probe_late_wanted_bits", WebGPUArray.from(atomic_u32), true);
+
+/**
+ * The cage windows the late list's keys were written in: the levels of the frame before.
+ * @type {ShaderResourceDescriptor}
+ */
+export const PROBE_LATE_LEVELS_RESOURCE = ShaderResourceDescriptor.uniform("probe_late_levels", CLIPMAP_LEVEL_ARRAY);
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", PROBE_WANT_LATE_SETTINGS);
+
+resources.createGroup()
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_LATE_LEVELS_RESOURCE)
+    .add(PROBE_LATE_WANTED_READ_RESOURCE)
+    .add(PROBE_LATE_WANTED_BITS_RESOURCE)
+    .add(PROBE_WANTED_BITS_RESOURCE)
+    .add(PROBE_WANTED_WRITE_RESOURCE);
+
+/**
+ * The late wants taken into the frame's (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a key of the late
+ * list, through a launch its count sizes.
+ *
+ * A reader whose surface is drawn after the frame's lifetime wants its probes into the late set, through
+ * `probe_clipmap_want` as any want does, and the next lifetime runs this between its own wants and admit. A key
+ * the frame's set lacks goes on its list; either way the key's late bit is cleared, which leaves the late bits
+ * empty, and the host empties the list.
+ *
+ * A key names a storage cell, and the lattice point it stands for is the one its writer's window held there. Where
+ * a window has moved since, the cell of a point it left stands for the point that came in across from it, which
+ * nothing wanted: a key is taken only where the present window's point is one the writer's window
+ * (`probe_late_levels`) held too.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_late = ComputeShader.from({
+    label: "Probe Clipmap Want Late",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${PROBE_THREAD_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+    let index = id.x;
+    let listed = index < min(probe_late_wanted.count, settings.late_capacity);
+
+    var key = 0u;
+
+    if (listed) {
+        key = probe_late_wanted.elements[index];
+    }
+
+    let bit = 1u << (key & 31u);
+
+    var wants = false;
+
+    if (listed) {
+        atomicAnd(&probe_late_wanted_bits[key >> 5u], ~bit);
+
+        let cascade = probe_clipmap_key_cascade(key, settings.resolution);
+        let point = probe_clipmap_window_point(probe_clipmap_key_storage(key, settings.resolution), probe_levels[cascade].corner, settings.resolution);
+        let written = probe_late_levels[cascade];
+
+        // a lattice window is a point past its cage window along each axis
+        wants = clipmap_contains(point, written.corner, written.size + vec3<i32>(1));
+    }
+
+    var first = false;
+
+    if (wants) {
+        first = (atomicOr(&probe_wanted_bits[key >> 5u], bit) & bit) == 0u;
+    }
+
+    // every lane, so that the append stays in uniform control flow
+    collection_u32_append(&probe_wanted, first, key, settings.wanted_capacity);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_clipmap_contains,
+            chunk_collection_u32_append,
+            CLIPMAP_LEVEL_STRUCT.declaration_chunk,
+            COLLECTION_U32_STRUCT_READ.declaration_chunk,
+        ]),
+});

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

@@ -0,0 +1,36 @@
+/**
+ * The meshlets' wants, counted (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a listed meshlet, through
+ * the launch that walks the list, as `shader_avboit_occupancy` runs over it. `output` receives, for each, the
+ * cages a reader anywhere inside its world box can read (`probe_clipmap_box_cage_count`), and the list's count;
+ * their prefix sums launch `shader_probe_clipmap_want_meshlets`, a thread a cage.
+ *
+ * `output` is a count and its elements, cleared at its count for a list of no meshlet; it holds a count for each
+ * meshlet it has room for, and names that many.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_meshlet_count: ComputeShader;
+/**
+ * The meshlets' wants (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a cage a listed meshlet's readers
+ * can read, through the launch the prefix sums of `shader_probe_clipmap_want_meshlet_count` size
+ * (`shader_prefix_sum_to_command`). The wants of the probes a forward-shaded surface picks from, which no pixel
+ * of the G-buffer stands for: every fragment of a meshlet reads cages its box's blocks hold
+ * (`chunk_probe_clipmap_box_cages`), so wanting those leaves none of them without its probes.
+ *
+ * A thread finds its meshlet by its place in the sums, and its cage by its place among the meshlet's blocks,
+ * cascade by cascade. It wants the cage where a point near it can select its cascade
+ * (`probe_clipmap_cage_is_read`), the cage meets the meshlet's box as that lies in its own space
+ * (`probe_clipmap_cage_meets_box`), and it meets the view's frustum.
+ *
+ * What it wants is a superset of what the meshlet's surface crosses: a box holds cages the surface inside it
+ * does not reach, the more the larger and the less flat the meshlet is against its cascade's spacing. The
+ * threads a meshlet takes are its blocks' cages.
+ *
+ * The wanted list and bits it binds are whichever the pass is given: recorded after the frame's lifetime, the
+ * late ones (`GPUProbeClipmap.write_want_bindings`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_meshlets: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_probe_clipmap_want_meshlets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_probe_clipmap_want_meshlets.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/shader_probe_clipmap_want_meshlets.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;GAUG;AACH,sDAFU,aAAa,CAwCpB;AAgBH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iDAFU,aAAa,CAgGpB;8BA9M2B,kCAAkC"}

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

@@ -0,0 +1,221 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { MESHLET_COLLECTION_STRUCT } from "../../../rasterize/MESHLET_COLLECTION_STRUCT.js";
+import { chunk_scene_database_access } from "../../../scene/chunk_scene_database_access.js";
+import { CLIPMAP_LEVEL_LIMIT } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { AABB3_STRUCT } from "../../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
+import { chunk_aabb3_intersects_frustum } from "../../../shader/chunk/geometry/aabb3/chunk_aabb3_intersects_frustum.js";
+import { chunk_aabb3_project } from "../../../shader/chunk/geometry/aabb3/chunk_aabb3_project.js";
+import { chunk_array_to_aabb3 } from "../../../shader/chunk/geometry/aabb3/chunk_array_to_aabb3.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_lower_bound_branchless } from "../../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import {
+    chunk_probe_clipmap,
+    PROBE_LEVELS_RESOURCE,
+    PROBE_WANTED_BITS_RESOURCE,
+    PROBE_WANTED_WRITE_RESOURCE
+} from "./chunk_probe_clipmap.js";
+import { chunk_probe_clipmap_box_cages } from "./chunk_probe_clipmap_box_cages.js";
+import { chunk_probe_clipmap_want } from "./chunk_probe_clipmap_want.js";
+import { PROBE_RECEIVER_BIAS } from "./PROBE_CLIPMAP.js";
+import { PROBE_WANT_SETTINGS } from "./shader_probe_clipmap_want.js";
+
+const count_resources = new ShaderResourceSetDescriptor();
+
+count_resources.setImmediate("settings", PROBE_WANT_SETTINGS);
+
+count_resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer("input", MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer("output", COLLECTION_U32_STRUCT_READ, true)
+    .add(PROBE_LEVELS_RESOURCE);
+
+/**
+ * The meshlets' wants, counted (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a listed meshlet, through
+ * the launch that walks the list, as `shader_avboit_occupancy` runs over it. `output` receives, for each, the
+ * cages a reader anywhere inside its world box can read (`probe_clipmap_box_cage_count`), and the list's count;
+ * their prefix sums launch `shader_probe_clipmap_want_meshlets`, a thread a cage.
+ *
+ * `output` is a count and its elements, cleared at its count for a list of no meshlet; it holds a count for each
+ * meshlet it has room for, and names that many.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_meshlet_count = ComputeShader.from({
+    label: "Probe Clipmap Want Meshlets / count",
+    resources: count_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let index = folded_workgroup_index(workgroup_id) * ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u + lane;
+    let listed = min(input.count, arrayLength(&output.elements));
+
+    if (index >= listed) {
+        return;
+    }
+
+    if (index == 0u) {
+        output.count = listed;
+    }
+
+    let meshlet = input.elements[index];
+    let mesh = scene_read_mesh(&scene_database, meshlet.mesh);
+    let node = scene_read_node(&scene_database, mesh.node);
+    // its world box, as the occupancy and the HZB filter take it
+    let box = aabb3_project(array_to_aabb3(meshlet_metadata[meshlet.index].bounds_box), node.global);
+
+    output.elements[index] = probe_clipmap_box_cage_count(box.min, box.max, settings.cascade_count, settings.anchor, settings.select_half);
+}
+`, [
+            chunk_folded_workgroup_index,
+            AABB3_STRUCT.declaration_chunk,
+            chunk_array_to_aabb3,
+            chunk_aabb3_project,
+            chunk_scene_database_access,
+            chunk_probe_clipmap_box_cages,
+        ]),
+});
+
+const want_resources = new ShaderResourceSetDescriptor();
+
+want_resources.setImmediate("settings", PROBE_WANT_SETTINGS);
+
+want_resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer("input", MESHLET_COLLECTION_STRUCT)
+    .addStorageBuffer("prefix_sums", COLLECTION_U32_STRUCT_READ)
+    .add(PROBE_LEVELS_RESOURCE)
+    .add(PROBE_WANTED_BITS_RESOURCE)
+    .add(PROBE_WANTED_WRITE_RESOURCE);
+
+/**
+ * The meshlets' wants (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): a thread a cage a listed meshlet's readers
+ * can read, through the launch the prefix sums of `shader_probe_clipmap_want_meshlet_count` size
+ * (`shader_prefix_sum_to_command`). The wants of the probes a forward-shaded surface picks from, which no pixel
+ * of the G-buffer stands for: every fragment of a meshlet reads cages its box's blocks hold
+ * (`chunk_probe_clipmap_box_cages`), so wanting those leaves none of them without its probes.
+ *
+ * A thread finds its meshlet by its place in the sums, and its cage by its place among the meshlet's blocks,
+ * cascade by cascade. It wants the cage where a point near it can select its cascade
+ * (`probe_clipmap_cage_is_read`), the cage meets the meshlet's box as that lies in its own space
+ * (`probe_clipmap_cage_meets_box`), and it meets the view's frustum.
+ *
+ * What it wants is a superset of what the meshlet's surface crosses: a box holds cages the surface inside it
+ * does not reach, the more the larger and the less flat the meshlet is against its cascade's spacing. The
+ * threads a meshlet takes are its blocks' cages.
+ *
+ * The wanted list and bits it binds are whichever the pass is given: recorded after the frame's lifetime, the
+ * late ones (`GPUProbeClipmap.write_want_bindings`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_probe_clipmap_want_meshlets = ComputeShader.from({
+    label: "Probe Clipmap Want Meshlets",
+    resources: want_resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${COMPUTE_SHADER_DEFAULT_GROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    // the launch's workgroups are shader_prefix_sum_to_command's
+    let thread = folded_workgroup_index(workgroup_id) * ${COMPUTE_SHADER_DEFAULT_GROUP_SIZE}u + lane;
+    let listed = prefix_sums.count;
+
+    // the meshlet whose cages hold the thread: the first whose sum is past it
+    var meshlet_index = 0u;
+
+    if (listed > 0u) {
+        meshlet_index = lower_bound_branchless(&prefix_sums.elements, thread + 1u, listed);
+    }
+
+    var wants = meshlet_index < listed;
+    var local = thread;
+
+    if (wants && meshlet_index > 0u) {
+        local = thread - prefix_sums.elements[meshlet_index - 1u];
+    }
+
+    var cascade = 0u;
+    var cage = vec3<i32>(0);
+
+    if (wants) {
+        let meshlet = input.elements[meshlet_index];
+        let mesh = scene_read_mesh(&scene_database, meshlet.mesh);
+        let node = scene_read_node(&scene_database, mesh.node);
+        let local_box = array_to_aabb3(meshlet_metadata[meshlet.index].bounds_box);
+        let box = aabb3_project(local_box, node.global);
+
+        // its block, cascade by cascade, and its cage in the block
+        let cascades = probe_clipmap_box_cascades(box.min, box.max, settings.cascade_count, settings.anchor, settings.select_half);
+
+        var found = false;
+
+        for (var i = 0u; i < ${CLIPMAP_LEVEL_LIMIT}u; i++) {
+            let c = cascades.x + i;
+
+            if (c >= cascades.y) {
+                break;
+            }
+
+            let cages = probe_clipmap_box_cages(box.min, box.max, c, settings.anchor, settings.select_half);
+            let count = cages.dims.x * cages.dims.y * cages.dims.z;
+
+            if (local < count) {
+                cascade = c;
+                cage = cages.first + vec3<i32>(vec3<u32>(local % cages.dims.x, (local / cages.dims.x) % cages.dims.y, local / (cages.dims.x * cages.dims.y)));
+                found = true;
+
+                break;
+            }
+
+            local -= count;
+        }
+
+        wants = found
+            && probe_clipmap_cage_is_read(cascade, cage, settings.anchor, settings.select_half)
+            && probe_clipmap_cage_meets_box(cascade, cage, local_box.min, local_box.max, node.global);
+
+        if (wants) {
+            // grown by the bias, as the points that read it lie
+            let cell = probe_levels[cascade].cell_size;
+            let bias = ${PROBE_RECEIVER_BIAS} * cell;
+            let reach = ${AABB3_STRUCT.wgsl_ref}(vec3<f32>(cage) * cell - bias, vec3<f32>(cage + vec3<i32>(1)) * cell + bias);
+
+            wants = aabb3_intersects_frustum(reach, camera.frustum);
+        }
+    }
+
+    // every lane, so that the appends stay in uniform control flow
+    probe_clipmap_want_cage(wants, cascade, cage, settings.resolution, settings.wanted_capacity);
+}
+`, [
+            chunk_probe_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_lower_bound_branchless,
+            AABB3_STRUCT.declaration_chunk,
+            chunk_array_to_aabb3,
+            chunk_aabb3_project,
+            chunk_aabb3_intersects_frustum,
+            chunk_scene_database_access,
+            chunk_probe_clipmap_box_cages,
+            chunk_probe_clipmap_want,
+        ]),
+});

package/src/shade/renderer/gpu_primitive/age_eviction/chunk_age_eviction.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Buckets entries are sorted into by age. An age's bucket is its count of binary digits: 0 the first, 1 the
+ * second, 2 and 3 the third, and the last everything from `2^(AGE_EVICTION_BUCKETS − 2)` on.
+ *
+ * @type {number}
+ */
+export const AGE_EVICTION_BUCKETS: number;
+/**
+ * Eviction from a pool by pressure, oldest first, with no sort: the entries a pool could give up are
+ * counted into buckets by age, a plan asks for as many as the pool is short of, from the oldest bucket
+ * down, and the next pass over the entries takes what the plan asks for.
+ *
+ * ```wgsl
+ * const AGE_EVICTION_BUCKETS: u32
+ * fn age_eviction_bucket(age: u32) -> u32
+ * fn age_eviction_plan(counters: ptr<storage, array<atomic<u32>>, read_write>, ages: u32, lacking: u32) -> vec2<u32>
+ * fn age_eviction_whole(counted: u32, buckets: u32) -> bool
+ * fn age_eviction_partial(counted: u32, buckets: u32) -> bool
+ * ```
+ *
+ * - `age_eviction_bucket`: the bucket of an age ({@link AGE_EVICTION_BUCKETS}).
+ * - `age_eviction_plan`: reads the `AGE_EVICTION_BUCKETS` counts at `counters[ages]` on, how many entries
+ *   that could be evicted each bucket holds, and empties them. Returns the plan that frees `lacking`
+ *   entries, oldest first: `x` buckets whole, from the oldest, and `y` entries of the bucket below them. A
+ *   shortfall the counted entries cannot cover takes them all and no more: past the youngest bucket
+ *   anything was counted in, nothing is asked for.
+ * - `age_eviction_whole`: whether a plan of `buckets` whole buckets takes every entry counted in bucket
+ *   `counted`.
+ * - `age_eviction_partial`: whether bucket `counted` is the one the plan takes some of: the caller takes
+ *   entries of it while its own count of them is under the plan's `y`.
+ *
+ * The plan is made from one pass's counts and used by the next, so an entry's `counted` is the bucket it
+ * was in when counted, `age_eviction_bucket(age − 1)` a frame on: an entry that has aged into an asked
+ * bucket since, uncounted, is not taken for it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_age_eviction: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_age_eviction.d.ts.map

package/src/shade/renderer/gpu_primitive/age_eviction/chunk_age_eviction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_age_eviction.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/gpu_primitive/age_eviction/chunk_age_eviction.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,mCAFU,MAAM,CAEuB;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iCAFU,SAAS,CA+CjB;0BArFwB,oCAAoC"}

package/src/shade/renderer/gpu_primitive/age_eviction/chunk_age_eviction.js

@@ -0,0 +1,86 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Buckets entries are sorted into by age. An age's bucket is its count of binary digits: 0 the first, 1 the
+ * second, 2 and 3 the third, and the last everything from `2^(AGE_EVICTION_BUCKETS − 2)` on.
+ *
+ * @type {number}
+ */
+export const AGE_EVICTION_BUCKETS = 32;
+
+/**
+ * Eviction from a pool by pressure, oldest first, with no sort: the entries a pool could give up are
+ * counted into buckets by age, a plan asks for as many as the pool is short of, from the oldest bucket
+ * down, and the next pass over the entries takes what the plan asks for.
+ *
+ * ```wgsl
+ * const AGE_EVICTION_BUCKETS: u32
+ * fn age_eviction_bucket(age: u32) -> u32
+ * fn age_eviction_plan(counters: ptr<storage, array<atomic<u32>>, read_write>, ages: u32, lacking: u32) -> vec2<u32>
+ * fn age_eviction_whole(counted: u32, buckets: u32) -> bool
+ * fn age_eviction_partial(counted: u32, buckets: u32) -> bool
+ * ```
+ *
+ * - `age_eviction_bucket`: the bucket of an age ({@link AGE_EVICTION_BUCKETS}).
+ * - `age_eviction_plan`: reads the `AGE_EVICTION_BUCKETS` counts at `counters[ages]` on, how many entries
+ *   that could be evicted each bucket holds, and empties them. Returns the plan that frees `lacking`
+ *   entries, oldest first: `x` buckets whole, from the oldest, and `y` entries of the bucket below them. A
+ *   shortfall the counted entries cannot cover takes them all and no more: past the youngest bucket
+ *   anything was counted in, nothing is asked for.
+ * - `age_eviction_whole`: whether a plan of `buckets` whole buckets takes every entry counted in bucket
+ *   `counted`.
+ * - `age_eviction_partial`: whether bucket `counted` is the one the plan takes some of: the caller takes
+ *   entries of it while its own count of them is under the plan's `y`.
+ *
+ * The plan is made from one pass's counts and used by the next, so an entry's `counted` is the bucket it
+ * was in when counted, `age_eviction_bucket(age − 1)` a frame on: an entry that has aged into an asked
+ * bucket since, uncounted, is not taken for it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_age_eviction = CodeChunk.from(
+    //language=WGSL
+    `
+const AGE_EVICTION_BUCKETS: u32 = ${AGE_EVICTION_BUCKETS}u;
+
+fn age_eviction_bucket(age: u32) -> u32 {
+    return min(32u - countLeadingZeros(age), AGE_EVICTION_BUCKETS - 1u);
+}
+
+fn age_eviction_plan(counters: ptr<storage, array<atomic<u32>>, read_write>, ages: u32, lacking: u32) -> vec2<u32> {
+    var left = lacking;
+    var buckets = 0u;
+    var remaining = 0u;
+
+    for (var k = 0u; k < AGE_EVICTION_BUCKETS; k++) {
+        let at = ages + AGE_EVICTION_BUCKETS - 1u - k;
+        let aged = atomicLoad(&counters[at]);
+
+        atomicStore(&counters[at], 0u);
+
+        // a bucket nothing was counted in is taken only for an older one: what ages into a bucket below every
+        // entry counted is not asked for
+        if (left > 0u && aged > 0u) {
+            if (aged <= left) {
+                left -= aged;
+                buckets = k + 1u;
+            } else {
+                buckets = k;
+                remaining = left;
+                left = 0u;
+            }
+        }
+    }
+
+    return vec2<u32>(buckets, remaining);
+}
+
+fn age_eviction_whole(counted: u32, buckets: u32) -> bool {
+    return counted >= AGE_EVICTION_BUCKETS - min(buckets, AGE_EVICTION_BUCKETS);
+}
+
+fn age_eviction_partial(counted: u32, buckets: u32) -> bool {
+    return counted + 1u == AGE_EVICTION_BUCKETS - min(buckets, AGE_EVICTION_BUCKETS);
+}
+`
+);