@woosh/meep-engine 3.64.1 → 3.67.0

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);
+}
+`
+);

package/src/shade/renderer/grass/blade/GPUGrassBlades.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Grass blades on the device: the species list, and the passes that make a view's blades each frame and
+ * draw them (`GRASS_BLADE.js`).
+ *
+ * Blades stand on the surfels {@link GPUGrassSurfaces} keeps; nothing of a blade outlives its frame.
+ *
+ * Each frame: {@link update} once; then for every view that draws grass {@link graph_generate}, after the
+ * surfaces' own passes for the view, after whatever publishes the scene's wind for the frame (the blades
+ * are bent by it), and before anything reads the scene's depth for the frame's image; and
+ * {@link graph_draw} at the frame phase where the G-buffer is written into.
+ *
+ * The blades are pushed over by the scene's fluid obstacles through {@link press}, a field this owns and
+ * stamps as part of making a view's blades.
+ */
+export class GPUGrassBlades {
+    /**
+     * Offer the pipelines the blades' passes run — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry: PipelineEnquiry): void;
+    /**
+     * @param {GraphicsContext} graphics
+     * @param {GPUGrassSurfaces} surfaces whose surfels the blades stand on
+     */
+    constructor(graphics: GraphicsContext, surfaces: GPUGrassSurfaces);
+    /**
+     * Where obstacles have pressed the grass down, and its settings.
+     *
+     * @readonly
+     * @type {GPUGrassPress}
+     */
+    readonly press: GPUGrassPress;
+    /**
+     * @returns {number} blades a frame's list has room for
+     */
+    get blade_capacity(): number;
+    /**
+     * @returns {number} the most blades a view's list was asked to hold, as last read off the device
+     */
+    get blades_asked(): number;
+    /**
+     * The species list on the device. Null before the first {@link update}, and replaced when it grows.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get species_buffer(): any;
+    /**
+     * The blades' clock on the device (`GRASS_BLADE_CLOCK_STRUCT`). Null before the first {@link update}.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get clock_buffer(): any;
+    /**
+     * Set a species' record.
+     *
+     * @param {number} index the species' place in the list, as `mesh_ground_covers` rows name it
+     * @param {object} species
+     * @param {number} species.blade_length metres
+     * @param {number} species.blade_width metres
+     * @param {number} species.density blades a square metre
+     * @param {number} species.roughness
+     * @param {number[]} species.color_root linear rgb
+     * @param {number[]} species.color_tip linear rgb
+     * @param {number} species.length_variation how much of its length a blade can lack, 0 to 1
+     * @param {number} species.lean the most a blade leans from upright at its root, radians
+     * @param {number} species.curl the most a blade's tip turns further than its root leans, radians
+     * @param {number} species.tint how far a blade's colour strays from its species', as a share of it
+     * @param {number} species.roundness how far a blade's normal turns towards its edges
+     * @param {number} species.elastic_modulus of the blade's tissue in bending, Pa
+     * @param {number} species.blade_depth depth of the blade's section in bending, metres
+     * @param {number} species.turbulence how unsteady the wind a blade feels is, as a share of its speed
+     */
+    set_species(index: number, species: {
+        blade_length: number;
+        blade_width: number;
+        density: number;
+        roughness: number;
+        color_root: number[];
+        color_tip: number[];
+        length_variation: number;
+        lean: number;
+        curl: number;
+        tint: number;
+        roundness: number;
+        elastic_modulus: number;
+        blade_depth: number;
+        turbulence: number;
+    }): void;
+    /**
+     * Begin a frame: move the blades' clock and the press's on, bring the device's species list up to
+     * date, and make room for the blades the last frames' lists were asked to hold. Call once a frame,
+     * before any view's {@link graph_generate}.
+     *
+     * @param {number} time_delta_seconds how far the scene's clock has moved since the last call
+     */
+    update(time_delta_seconds: number): void;
+    /**
+     * Record the passes that make a view's blades: stamp the press field, count the cells, sum, and make
+     * the blades the counts allow. Records nothing while nothing grows.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view the view; its scene is the surfaces' scene
+     * @param {GPUFluidForcing|null} [options.forcing] the scene's GPU fluid forcing, whose obstacles press
+     *        the blades; none press without it
+     */
+    graph_generate({ graph, view, forcing }: {
+        graph: FrameGraph;
+        view: GPUViewContext;
+        forcing?: GPUFluidForcing | null;
+    }): void;
+    /**
+     * Record a view's blade draw: its blades into the blade id target under the scene's depth, then the
+     * G-buffer's surface, the visibility word and the velocity under every pixel a blade covers. Publishes
+     * the depth, the G-buffer targets, the visibility buffer and the velocity buffer it wrote. Records nothing for a view {@link graph_generate} made no blades for this frame.
+     *
+     * @param {FrameContext} frame at the phase where the G-buffer is written into
+     */
+    graph_draw(frame: FrameContext): void;
+    /**
+     * Let go of everything on the device. The species stay listed.
+     */
+    destroy(): void;
+    #private;
+}
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+export type FrameContext = import("../../extension/FrameContext.js").FrameContext;
+export type GPUFluidForcing = import("../../fluid/forcing/GPUFluidForcing.js").GPUFluidForcing;
+export type GraphicsContext = import("../../GraphicsContext.js").GraphicsContext;
+export type GPUViewContext = import("../../view/GPUViewContext.js").GPUViewContext;
+export type GPUGrassSurfaces = import("../surface/GPUGrassSurfaces.js").GPUGrassSurfaces;
+import { GPUGrassPress } from "../press/GPUGrassPress.js";
+//# sourceMappingURL=GPUGrassBlades.d.ts.map

package/src/shade/renderer/grass/blade/GPUGrassBlades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUGrassBlades.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/grass/blade/GPUGrassBlades.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;;;GAaG;AACH;IAEI;;;;OAIG;IACH,iCAFW,eAAe,QAWzB;IAmED;;;OAGG;IACH,sBAHW,eAAe,YACf,gBAAgB,EAW1B;IA9ED;;;;;OAKG;IACH,gBAFU,aAAa,CAEjB;IA0EN;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,2BAEC;IAED;;;;OAIG;IACH,0BAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBAjBW,MAAM;QAEU,YAAY,EAA5B,MAAM;QACU,WAAW,EAA3B,MAAM;QACU,OAAO,EAAvB,MAAM;QACU,SAAS,EAAzB,MAAM;QACY,UAAU,EAA5B,MAAM,EAAE;QACU,SAAS,EAA3B,MAAM,EAAE;QACQ,gBAAgB,EAAhC,MAAM;QACU,IAAI,EAApB,MAAM;QACU,IAAI,EAApB,MAAM;QACU,IAAI,EAApB,MAAM;QACU,SAAS,EAAzB,MAAM;QACU,eAAe,EAA/B,MAAM;QACU,WAAW,EAA3B,MAAM;QACU,UAAU,EAA1B,MAAM;aA0ChB;IAED;;;;;;OAMG;IACH,2BAFW,MAAM,QAyDhB;IAED;;;;;;;;;OASG;IACH;QAL+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACiB,OAAO,GAAtC,eAAe,GAAC,IAAI;aA8J9B;IAED;;;;;;OAMG;IACH,kBAFW,YAAY,QAqItB;IAED;;OAEG;IACH,gBAQC;;CACJ;yBA/nBY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,6CAA6C,EAAE,eAAe;2BACrE,OAAO,iCAAiC,EAAE,YAAY;8BACtD,OAAO,wCAAwC,EAAE,eAAe;8BAChE,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;+BACrD,OAAO,gCAAgC,EAAE,gBAAgB;8BA1BxC,2BAA2B"}