@woosh/meep-engine 3.64.0 → 3.65.0

package/src/shade/renderer/grass/surface/GPUGrassSurfaces.js

@@ -0,0 +1,1253 @@
+import { assert } from "../../../../core/assert.js";
+import { graph_read_buffer } from "../../buffer/graph_read_buffer.js";
+import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
+import { HASH_TABLE_PROBE_LIMIT } from "../../gpu_primitive/hash_table/cpu_build_hash_table.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION
+} from "../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import {
+    shader_slot_stack_fill,
+    SLOT_STACK_FILL_WORKGROUP_SIZE
+} from "../../gpu_primitive/slot_stack/shader_slot_stack_fill.js";
+import {
+    shader_slot_stack_push_range,
+    SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE
+} from "../../gpu_primitive/slot_stack/shader_slot_stack_push_range.js";
+import { shader_prefix_sum_to_command } from "../../rasterize/expand/mesh/shader_prefix_sum_to_command.js";
+import { graph_create_buffer } from "../../shader/graph/graph_create_buffer.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
+import { GPUTileAtlas2D } from "../../texture/atlas/GPUTileAtlas2D.js";
+import { GRASS_SURFEL_FORMAT } from "./chunk_grass_surfel.js";
+import {
+    GRASS_POOL_FREE_COUNT,
+    GRASS_POOL_HEADER_WORDS,
+    GRASS_POOL_REMOVED,
+    GRASS_POOL_STARVED,
+    GRASS_SLOT_WORDS,
+    GRASS_TILE_COLUMNS
+} from "./GRASS_SURFACE.js";
+import {
+    grass_surface_level_count,
+    GRASS_SURFACE_RECORD_BLADE_LENGTH,
+    GRASS_SURFACE_RECORD_HIGH,
+    GRASS_SURFACE_RECORD_LOW,
+    GRASS_SURFACE_RECORD_NODE,
+    GRASS_SURFACE_RECORD_WORDS
+} from "./GRASS_SURFACE_VIEW.js";
+import { GRASS_DIRECTORY_FILL_WORKGROUP_SIZE, shader_grass_directory_fill } from "./shader_grass_directory_fill.js";
+import { shader_grass_surface_bake } from "./shader_grass_surface_bake.js";
+import { shader_grass_surface_bake_command } from "./shader_grass_surface_bake_command.js";
+import {
+    GRASS_INVALIDATION_WORDS,
+    GRASS_SURFACE_INVALIDATE_RUN,
+    GRASS_SURFACE_INVALIDATE_WORKGROUP_SIZE,
+    shader_grass_surface_invalidate
+} from "./shader_grass_surface_invalidate.js";
+import { GRASS_SURFACE_RETIRE_WORKGROUP_SIZE, shader_grass_surface_retire } from "./shader_grass_surface_retire.js";
+import { shader_grass_surface_schedule } from "./shader_grass_surface_schedule.js";
+import { shader_grass_surface_want } from "./shader_grass_surface_want.js";
+import {
+    GRASS_SURFACE_WINDOW_COUNT_WORKGROUP_SIZE,
+    shader_grass_surface_window_count
+} from "./shader_grass_surface_window_count.js";
+
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
+ * @typedef {import("../../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ */
+
+/**
+ * Bytes a `u32` collection's count takes ahead of its elements, which sit on a 16-byte boundary.
+ * @type {number}
+ */
+const COLLECTION_HEADER_BYTES = 16;
+
+/**
+ * Slots a pool is made with. A pool that turns asks away grows.
+ * @type {number}
+ */
+const INITIAL_SLOT_CAPACITY = 1024;
+
+/**
+ * Surface records the list is made with room for.
+ * @type {number}
+ */
+const INITIAL_SURFACE_CAPACITY = 16;
+
+/**
+ * Changes of ground one frame's marking reads: what its dispatch can count runs of. The rest wait a frame.
+ * @type {number}
+ */
+const INVALIDATIONS_PER_FRAME = WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION * GRASS_SURFACE_INVALIDATE_RUN;
+
+/**
+ * Numbers a queued change of ground takes: the surface's row, and a rectangle on its frame's x and z.
+ * @type {number}
+ */
+const INVALIDATION_QUEUE_STRIDE = 5;
+
+/**
+ * Bytes of a `u32` collection with room for `count` elements.
+ *
+ * @param {number} count
+ * @returns {number}
+ */
+function collection_size(count) {
+    return COLLECTION_HEADER_BYTES + Math.max(1, Math.ceil(count / 4)) * 16;
+}
+
+/**
+ * Records in the directory of a pool of `slot_capacity` slots: a power of two at least twice the slots,
+ * so the table is never more than half full, and no fewer than its probe limit.
+ *
+ * @param {number} slot_capacity
+ * @returns {number}
+ */
+export function grass_directory_table_size(slot_capacity) {
+    let size = HASH_TABLE_PROBE_LIMIT;
+
+    while (size < 2 * slot_capacity) {
+        size *= 2;
+    }
+
+    return size;
+}
+
+/**
+ * How finely a scene's grass surfaces are sampled, and how fast.
+ */
+export class GrassSurfaceSettings {
+    /**
+     * The distance between neighbouring columns of a surface's finest level, in world units: how exactly a
+     * blade's root follows the ground, against the rays that find it and the memory that keeps it.
+     *
+     * @type {number}
+     */
+    finest_spacing = 0.125;
+
+    /**
+     * The least width a blade is drawn at, in pixels of the view's render resolution. A surface's level
+     * serves the distances at which its spacing spans no more than this.
+     *
+     * @type {number}
+     */
+    narrowest_blade = 1.5;
+
+    /**
+     * The least length a blade is drawn at, in pixels of the view's render resolution. No tile is asked for
+     * past the distance where its surface's tallest blade spans less.
+     *
+     * @type {number}
+     */
+    shortest_blade = 2;
+
+    /**
+     * The most layers of tiles baked a view a frame, each a workgroup of {@link GRASS_TILE_SURFELS} columns:
+     * how fast ground a view turns towards gets its grass. A frame bakes what it was asked and no more, so
+     * this is the cost of the frame that asks most.
+     *
+     * @type {number}
+     */
+    bake_capacity = 64;
+
+    /**
+     * How many blades a view ray may cross before the grass behind them is left out: the grass's density
+     * where it is seen at a low angle. Lower lets more ground show through.
+     * @type {number}
+     */
+    canopy_opacity = 6;
+}
+
+/**
+ * The grass surfaces of one scene on the device: which surfaces there are, the pool their tiles' surfels
+ * are kept in, and the passes that ask for and bake the tiles a view wants (`GRASS_SURFACE.js`).
+ *
+ * A surface is named by its `transforms` row. Its members are the mesh rows whose `mesh_ground_covers`
+ * record names that row; this class is told only the surface's box and tallest blade.
+ *
+ * Each frame: {@link update} once, then {@link graph_update} for every view that draws grass.
+ */
+export class GPUGrassSurfaces {
+
+    /**
+     * Offer the pipelines the surfaces' passes run — see {@link PipelineEnquiry}.
+     *
+     * @param {PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        enquiry.compute.push(shader_slot_stack_fill.pipeline);
+        enquiry.compute.push(shader_slot_stack_push_range.pipeline);
+        enquiry.compute.push(shader_grass_directory_fill.pipeline);
+        enquiry.compute.push(shader_grass_surface_invalidate.pipeline);
+        enquiry.compute.push(shader_grass_surface_retire.pipeline);
+        enquiry.compute.push(shader_grass_surface_schedule.pipeline);
+        enquiry.compute.push(shader_grass_surface_window_count.pipeline);
+        enquiry.compute.push(shader_grass_surface_want.pipeline);
+        enquiry.compute.push(shader_grass_surface_bake_command.pipeline);
+        enquiry.compute.push(shader_grass_surface_bake.pipeline);
+        enquiry.compute.push(shader_prefix_sum_to_command.pipeline);
+    }
+
+    /**
+     * @type {GrassSurfaceSettings}
+     */
+    settings = new GrassSurfaceSettings();
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * Surface records, packed from 0, as words.
+     * @type {Uint32Array}
+     */
+    #records = new Uint32Array(INITIAL_SURFACE_CAPACITY * GRASS_SURFACE_RECORD_WORDS);
+
+    /**
+     * The same memory as floats.
+     * @type {Float32Array}
+     */
+    #records_f32 = new Float32Array(this.#records.buffer);
+
+    /**
+     * Each surface's place in {@link #records}, by its `transforms` row.
+     * @type {Map<number, number>}
+     */
+    #index_of = new Map();
+
+    /**
+     * @type {number}
+     */
+    #surface_count = 0;
+
+    /**
+     * The device's copy of {@link #records}; null until a surface is added.
+     * @type {GPUBuffer|null}
+     */
+    #surfaces_buffer = null;
+
+    /**
+     * The records the device's copy is behind on, as a range of records; empty when `from >= to`.
+     */
+    #dirty_from = Infinity;
+    #dirty_to = 0;
+
+    /**
+     * The tallest blade of any surface, kept as surfaces come, go and change.
+     * @type {number}
+     */
+    #blade_length_max = 0;
+    #blade_length_stale = false;
+
+    /**
+     * Slots the pool has; 0 until the pool is made.
+     * @type {number}
+     */
+    #slot_capacity = 0;
+
+    /**
+     * Slots the next pool is made with, when it replaces one that had grown; 0 for the least.
+     * @type {number}
+     */
+    #slot_capacity_wanted = 0;
+
+    /** @type {GPUBuffer|null} the pool's arena */
+    #pool = null;
+
+    /** @type {GPUBuffer|null} the free stack's slots */
+    #free = null;
+
+    /** @type {GPUBuffer|null} the directory's table */
+    #directory = null;
+
+    /** @type {GPUTileAtlas2D|null} the surfel atlas, a tile a slot */
+    #atlas = null;
+
+    /**
+     * Slots the pool has gained and the free stack does not hold yet: `[first, count]` each.
+     * @type {number[]}
+     */
+    #pushes = [];
+
+    /**
+     * The pool's count of starved asks, as last read off the device.
+     * @type {number}
+     */
+    #starved = 0;
+
+    /**
+     * Whether an ask has starved since the pool last grew.
+     * @type {boolean}
+     */
+    #grow_pending = false;
+
+    /**
+     * The frame the pool last grew in: a reading recorded before it says nothing of the pool as it is.
+     * @type {number}
+     */
+    #grown_frame = 0;
+
+    /**
+     * The pool's count of directory removals, as last read off the device, and as it stood when the
+     * directory was last made.
+     * @type {number}
+     */
+    #removed = 0;
+
+    /** @type {number} */
+    #removed_at_fill = 0;
+
+    /**
+     * Whether the directory is to be made again from the slots: it is empty, or holds too many removed records.
+     * @type {boolean}
+     */
+    #directory_stale = false;
+
+    /**
+     * The frame whose once-a-frame passes are recorded, and how many views it and the frame before recorded.
+     * @type {number}
+     */
+    #lifetime_frame = -1;
+
+    /** @type {number} */
+    #views = 0;
+
+    /** @type {number} */
+    #views_before = 1;
+
+    /**
+     * Raised when the pool is let go of: a reading of a pool that is gone is dropped.
+     * @type {number}
+     */
+    #generation = 0;
+
+    /**
+     * The finest spacing the pool's tiles are cut by: a tile of another spacing is another piece of ground.
+     * @type {number}
+     */
+    #pool_spacing = 0;
+
+    /**
+     * Whether the free stack is still to be filled: a fresh one holds zeros, which is one slot many times over.
+     * @type {boolean}
+     */
+    #fill_pending = false;
+
+    /**
+     * Frames {@link update} has begun.
+     * @type {number}
+     */
+    #frame = 0;
+
+    /**
+     * Changes of ground not yet marked on the device: `[node, low_x, low_z, high_x, high_z]` each.
+     * @type {number[]}
+     */
+    #invalidations = [];
+
+    /** @type {GPUBuffer|null} the frame's changes of ground */
+    #invalidation_buffer = null;
+
+    /**
+     * The frame's changes of ground as the device reads them, kept between frames.
+     * @type {Uint32Array}
+     */
+    #invalidation_words = new Uint32Array(64 * GRASS_INVALIDATION_WORDS);
+
+    /** @type {Float32Array} */
+    #invalidation_floats = new Float32Array(this.#invalidation_words.buffer);
+
+    /**
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        assert.defined(graphics, 'graphics');
+        assert.equal(graphics.isGraphicsContext, true, 'graphics.isGraphicsContext !== true');
+
+        this.#device = graphics.device;
+    }
+
+    /**
+     * @returns {number} how many surfaces there are
+     */
+    get surface_count() {
+        return this.#surface_count;
+    }
+
+    /**
+     * @returns {number} how many slots the pool has; 0 before the first surface
+     */
+    get slot_capacity() {
+        return this.#slot_capacity;
+    }
+
+    /**
+     * The pool's arena: its counters, then a record a slot (`GRASS_SURFACE.js`). Null before the first
+     * surface, and replaced when the pool grows: read it when a pass runs.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get pool_buffer() {
+        return this.#pool;
+    }
+
+    /**
+     * The pool's directory, a `chunk_hash_table_atomic` table. Null before the first surface, and replaced
+     * when the pool grows.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get directory_buffer() {
+        return this.#directory;
+    }
+
+    /**
+     * The surfel atlas, a texel a column of a slot (`chunk_grass_surfel`, `grass_slot_texel`). Null before
+     * the first surface, and replaced when the pool grows.
+     *
+     * @returns {GPUTexture|null}
+     */
+    get atlas() {
+        return this.#atlas === null ? null : this.#atlas.texture_at(0).gpu_texture;
+    }
+
+    /**
+     * A view of the surfel atlas for a pass to bind. Null before the first surface; ask again each frame.
+     *
+     * @returns {GPUTextureView|null}
+     */
+    get atlas_view() {
+        return this.#atlas === null ? null : this.#atlas.texture_at(0).obtainView();
+    }
+
+    /**
+     * The most slots the pool can grow to on this device: what the surfel atlas can hold. 0 before the
+     * first surface.
+     *
+     * @returns {number}
+     */
+    get slot_capacity_limit() {
+        return this.#atlas === null ? 0 : this.#atlas.capacity_limit;
+    }
+
+    /**
+     * The list of surface records (`GRASS_SURFACE_RECORD_STRUCT`), {@link surface_count} of them. Null
+     * before the first surface, and replaced when the list grows.
+     *
+     * @returns {GPUBuffer|null}
+     */
+    get surfaces_buffer() {
+        return this.#surfaces_buffer;
+    }
+
+    /**
+     * Whether `node` is a surface here.
+     *
+     * @param {number} node a `transforms` row
+     * @returns {boolean}
+     */
+    has(node) {
+        return this.#index_of.has(node);
+    }
+
+    /**
+     * Make a surface of a `transforms` row, or change the one it is.
+     *
+     * @param {number} node the surface's `transforms` row; not the scene's root
+     * @param {ArrayLike<number>} low the least corner of a box, in the surface's frame, that holds every member
+     * @param {ArrayLike<number>} high the box's greatest corner
+     * @param {number} blade_length the tallest blade that grows on any member, world units; 0 when none grows
+     */
+    set(node, low, high, blade_length) {
+        assert.isPositiveInteger(node, 'node');
+        assert.isFinite(blade_length, 'blade_length');
+        assert.greaterThanOrEqual(blade_length, 0, 'blade_length');
+
+        for (let axis = 0; axis < 3; axis++) {
+            assert.isFinite(low[axis], `low[${axis}]`);
+            assert.isFinite(high[axis], `high[${axis}]`);
+        }
+
+        let index = this.#index_of.get(node);
+
+        if (index === undefined) {
+            index = this.#surface_count++;
+
+            this.#index_of.set(node, index);
+
+            if (this.#records.length < this.#surface_count * GRASS_SURFACE_RECORD_WORDS) {
+                const grown = new Uint32Array(2 * this.#records.length);
+
+                grown.set(this.#records);
+
+                this.#records = grown;
+                this.#records_f32 = new Float32Array(grown.buffer);
+            }
+        }
+
+        const at = index * GRASS_SURFACE_RECORD_WORDS;
+        const words = this.#records;
+        const floats = this.#records_f32;
+
+        if (floats[at + GRASS_SURFACE_RECORD_BLADE_LENGTH] === this.#blade_length_max && blade_length < this.#blade_length_max) {
+            this.#blade_length_stale = true;
+        }
+
+        words[at + GRASS_SURFACE_RECORD_NODE] = node;
+        floats[at + GRASS_SURFACE_RECORD_BLADE_LENGTH] = blade_length;
+
+        for (let axis = 0; axis < 3; axis++) {
+            floats[at + GRASS_SURFACE_RECORD_LOW + axis] = low[axis];
+            floats[at + GRASS_SURFACE_RECORD_HIGH + axis] = high[axis];
+        }
+
+        this.#blade_length_max = Math.max(this.#blade_length_max, blade_length);
+
+        this.#mark(index);
+    }
+
+    /**
+     * A row stops being a surface. The slots that hold its tiles stay taken until the pool has need of them.
+     *
+     * @param {number} node a `transforms` row; one that is no surface is left alone
+     */
+    remove(node) {
+        const index = this.#index_of.get(node);
+
+        if (index === undefined) {
+            return;
+        }
+
+        this.#index_of.delete(node);
+
+        const last = --this.#surface_count;
+
+        const at = index * GRASS_SURFACE_RECORD_WORDS;
+        const words = this.#records;
+
+        if (this.#records_f32[at + GRASS_SURFACE_RECORD_BLADE_LENGTH] === this.#blade_length_max) {
+            this.#blade_length_stale = true;
+        }
+
+        if (index !== last) {
+            // the last record takes the place left
+            const from = last * GRASS_SURFACE_RECORD_WORDS;
+
+            words.copyWithin(at, from, from + GRASS_SURFACE_RECORD_WORDS);
+
+            this.#index_of.set(words[at + GRASS_SURFACE_RECORD_NODE], index);
+
+            this.#mark(index);
+        }
+    }
+
+    /**
+     * The ground of a surface has changed inside a rectangle: a member has come, gone or moved there. Every
+     * layer of every tile the rectangle touches, of every level, is baked again, where it is, when a view
+     * next asks for it. What it costs does not depend on the rectangle's size.
+     *
+     * @param {number} node the surface's `transforms` row
+     * @param {number} low_x the rectangle, in the surface's frame
+     * @param {number} low_z
+     * @param {number} high_x
+     * @param {number} high_z
+     */
+    invalidate(node, low_x, low_z, high_x, high_z) {
+        assert.isPositiveInteger(node, 'node');
+        assert.isFinite(low_x, 'low_x');
+        assert.isFinite(low_z, 'low_z');
+        assert.isFinite(high_x, 'high_x');
+        assert.isFinite(high_z, 'high_z');
+        assert.lessThanOrEqual(low_x, high_x, 'low_x');
+        assert.lessThanOrEqual(low_z, high_z, 'low_z');
+
+        this.#invalidations.push(node, low_x, low_z, high_x, high_z);
+    }
+
+    /**
+     * Record the pass that marks the queued changes of ground.
+     *
+     * @param {FrameGraph} graph
+     */
+    #graph_invalidate(graph) {
+        const queue = this.#invalidations;
+
+        if (queue.length === 0) {
+            return;
+        }
+
+        const record_count = Math.min(queue.length / INVALIDATION_QUEUE_STRIDE, INVALIDATIONS_PER_FRAME);
+        const word_count = record_count * GRASS_INVALIDATION_WORDS;
+
+        if (this.#invalidation_words.length < word_count) {
+            this.#invalidation_words = new Uint32Array(Math.max(word_count, this.#invalidation_words.length * 2));
+            this.#invalidation_floats = new Float32Array(this.#invalidation_words.buffer);
+        }
+
+        const words = this.#invalidation_words;
+        const floats = this.#invalidation_floats;
+
+        for (let i = 0; i < record_count; i++) {
+            const from = i * INVALIDATION_QUEUE_STRIDE;
+            const to = i * GRASS_INVALIDATION_WORDS;
+
+            words[to] = queue[from];
+            floats[to + 1] = queue[from + 1];
+            floats[to + 2] = queue[from + 2];
+            floats[to + 3] = queue[from + 3];
+            floats[to + 4] = queue[from + 4];
+        }
+
+        // what was not taken moves to the queue's front
+        const taken = record_count * INVALIDATION_QUEUE_STRIDE;
+
+        queue.copyWithin(0, taken);
+        queue.length -= taken;
+
+        const device = this.#device;
+        const bytes = word_count * 4;
+
+        if (this.#invalidation_buffer === null || this.#invalidation_buffer.size < bytes) {
+            this.#invalidation_buffer?.destroy();
+
+            this.#invalidation_buffer = device.createBuffer({
+                label: "grass / invalidations",
+                size: words.byteLength,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+        }
+
+        device.queue.writeBuffer(this.#invalidation_buffer, 0, words, 0, word_count);
+
+        const buffer = this.#invalidation_buffer;
+        const slot_capacity = this.#slot_capacity;
+        const finest_spacing = this.settings.finest_spacing;
+
+        const pass = graph.add("invalidate tiles", {}, (data, resources, context) => {
+            shader_grass_surface_invalidate.dispatch({
+                encoder: context.encoder,
+                group_count_x: Math.min(Math.ceil(slot_capacity / GRASS_SURFACE_INVALIDATE_WORKGROUP_SIZE), WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+                group_count_y: Math.ceil(record_count / GRASS_SURFACE_INVALIDATE_RUN),
+                bindings: {
+                    settings: { finest_spacing, record_count, slot_capacity },
+                    grass_invalidations: buffer,
+                    grass_pool: this.#pool,
+                },
+            });
+        });
+
+        // it writes the pool, which the graph does not hold
+        pass.make_side_effect();
+    }
+
+    /**
+     * @param {number} index a record the device's copy is now behind on
+     */
+    #mark(index) {
+        this.#dirty_from = Math.min(this.#dirty_from, index);
+        this.#dirty_to = Math.max(this.#dirty_to, index + 1);
+    }
+
+    /**
+     * @returns {number} the tallest blade of any surface
+     */
+    #tallest_blade() {
+        if (this.#blade_length_stale) {
+            this.#blade_length_stale = false;
+
+            let tallest = 0;
+
+            for (let i = 0; i < this.#surface_count; i++) {
+                tallest = Math.max(tallest, this.#records_f32[i * GRASS_SURFACE_RECORD_WORDS + GRASS_SURFACE_RECORD_BLADE_LENGTH]);
+            }
+
+            this.#blade_length_max = tallest;
+        }
+
+        return this.#blade_length_max;
+    }
+
+    /**
+     * Begin a frame: bring the device's list of surfaces up to date, and make the pool if there is a
+     * surface and no pool yet. Call once a frame, before any view's {@link graph_update}.
+     */
+    update() {
+        this.#frame++;
+
+        this.#views_before = Math.max(1, this.#views);
+        this.#views = 0;
+
+        if (this.#pool !== null && this.#pool_spacing !== this.settings.finest_spacing) {
+            // every tile it holds is of a lattice that is no more: a fresh pool of its size, when a surface next needs one
+            const slot_capacity = this.#slot_capacity;
+
+            this.#drop_pool();
+
+            this.#slot_capacity_wanted = slot_capacity;
+        }
+
+        if (this.#pool !== null) {
+            if (this.#grow_pending) {
+                this.#grow_pending = false;
+                this.#grown_frame = this.#frame;
+
+                this.#grow();
+            }
+
+            // a quarter of the table removed: with the half the slots can fill, a miss still ends within four probes or so
+            if (this.#removed - this.#removed_at_fill >= grass_directory_table_size(this.#slot_capacity) / 4) {
+                this.#directory_stale = true;
+            }
+        }
+
+        if (this.#surface_count === 0) {
+            return;
+        }
+
+        const device = this.#device;
+
+        const needed_bytes = this.#surface_count * GRASS_SURFACE_RECORD_WORDS * 4;
+
+        if (this.#surfaces_buffer === null || this.#surfaces_buffer.size < needed_bytes) {
+            this.#surfaces_buffer?.destroy();
+
+            this.#surfaces_buffer = device.createBuffer({
+                label: "grass / surfaces",
+                size: this.#records.byteLength,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+            });
+
+            this.#dirty_from = 0;
+            this.#dirty_to = this.#surface_count;
+        }
+
+        if (this.#dirty_from < this.#dirty_to) {
+            // a record that has since left the list's end needs no write
+            const to = Math.min(this.#dirty_to, this.#surface_count);
+            const from = Math.min(this.#dirty_from, to);
+
+            if (from < to) {
+                device.queue.writeBuffer(
+                    this.#surfaces_buffer,
+                    from * GRASS_SURFACE_RECORD_WORDS * 4,
+                    this.#records,
+                    from * GRASS_SURFACE_RECORD_WORDS,
+                    (to - from) * GRASS_SURFACE_RECORD_WORDS,
+                );
+            }
+
+            this.#dirty_from = Infinity;
+            this.#dirty_to = 0;
+        }
+
+        if (this.#pool === null) {
+            this.#make_pool(Math.max(INITIAL_SLOT_CAPACITY, this.#slot_capacity_wanted));
+        }
+    }
+
+    /**
+     * @param {number} slot_capacity
+     */
+    #make_pool(slot_capacity) {
+        const device = this.#device;
+
+        this.#slot_capacity = slot_capacity;
+        this.#pool_spacing = this.settings.finest_spacing;
+
+        this.#pool = device.createBuffer({
+            label: "grass / pool",
+            size: (GRASS_POOL_HEADER_WORDS + slot_capacity * GRASS_SLOT_WORDS) * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+
+        // every slot is free
+        const header = new Uint32Array(GRASS_POOL_HEADER_WORDS);
+
+        header[GRASS_POOL_FREE_COUNT] = slot_capacity;
+
+        device.queue.writeBuffer(this.#pool, 0, header);
+
+        this.#free = device.createBuffer({
+            label: "grass / free slots",
+            size: slot_capacity * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+
+        this.#fill_pending = true;
+
+        const table_size = grass_directory_table_size(slot_capacity);
+
+        this.#directory = device.createBuffer({
+            label: "grass / directory",
+            size: (2 + 2 * table_size) * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+
+        // [records held, table size]; the records themselves start empty
+        device.queue.writeBuffer(this.#directory, 0, Uint32Array.of(0, table_size));
+
+        this.#atlas = new GPUTileAtlas2D({
+            device,
+            formats: [GRASS_SURFEL_FORMAT],
+            tile_size: [GRASS_TILE_COLUMNS, GRASS_TILE_COLUMNS],
+            usage: GPUTextureUsage.STORAGE_BINDING | GPUTextureUsage.TEXTURE_BINDING,
+            label: "grass / surfels",
+            capacity: slot_capacity,
+        });
+    }
+
+    /**
+     * Double the pool: the atlas adds rows, the arena and the free stack grow with a copy, the new slots
+     * are pushed by the next frame, and the directory is made again in a table of the new size.
+     */
+    #grow() {
+        const old_capacity = this.#slot_capacity;
+        const capacity = Math.min(2 * old_capacity, this.#atlas.capacity_limit);
+
+        if (capacity <= old_capacity) {
+            return;
+        }
+
+        const device = this.#device;
+
+        this.#atlas.ensure_capacity(capacity);
+
+        this.#pool = this.#regrow(this.#pool, (GRASS_POOL_HEADER_WORDS + capacity * GRASS_SLOT_WORDS) * 4);
+        this.#free = this.#regrow(this.#free, capacity * 4);
+
+        const table_size = grass_directory_table_size(capacity);
+
+        this.#directory.destroy();
+
+        this.#directory = device.createBuffer({
+            label: "grass / directory",
+            size: (2 + 2 * table_size) * 4,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+
+        // [records held, table size]; the next frame lists the slots in it
+        device.queue.writeBuffer(this.#directory, 0, Uint32Array.of(0, table_size));
+
+        this.#directory_stale = true;
+
+        this.#slot_capacity = capacity;
+        this.#pushes.push(old_capacity, capacity - old_capacity);
+    }
+
+    /**
+     * A larger buffer with the old one's bytes, copied ahead of the frame's commands; the old one is
+     * destroyed after the copy is submitted.
+     *
+     * @param {GPUBuffer} old
+     * @param {number} size bytes
+     * @returns {GPUBuffer}
+     */
+    #regrow(old, size) {
+        const device = this.#device;
+
+        const buffer = device.createBuffer({ label: old.label, size, usage: old.usage });
+
+        const encoder = device.createCommandEncoder({ label: `${old.label} / growth` });
+
+        encoder.copyBufferToBuffer(old, 0, buffer, 0, old.size);
+        device.queue.submit([encoder.finish()]);
+
+        old.destroy();
+
+        return buffer;
+    }
+
+    /**
+     * Record the passes that run once a frame, ahead of any view's asks: the pool's new slots onto the
+     * free stack, the directory made again if it is due, the changes of ground, and the retire.
+     *
+     * @param {FrameGraph} graph
+     */
+    #graph_begin_frame(graph) {
+        const slot_capacity = this.#slot_capacity;
+        const frame = this.#frame;
+
+        const fill_stack = this.#fill_pending;
+
+        this.#fill_pending = false;
+
+        const pushes = this.#pushes.slice();
+
+        this.#pushes.length = 0;
+
+        const fill_directory = this.#directory_stale;
+
+        if (fill_directory) {
+            this.#directory_stale = false;
+            this.#removed_at_fill = this.#removed;
+        }
+
+        const table_size = grass_directory_table_size(slot_capacity);
+
+        const pass = graph.add("retire tiles", {}, (data, resources, context) => {
+            const encoder = context.encoder;
+
+            if (fill_stack) {
+                shader_slot_stack_fill.dispatch({
+                    encoder,
+                    group_count_x: Math.min(Math.ceil(slot_capacity / SLOT_STACK_FILL_WORKGROUP_SIZE), WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+                    bindings: { capacity: slot_capacity, slots: this.#free },
+                });
+            }
+
+            for (let i = 0; i < pushes.length; i += 2) {
+                shader_slot_stack_push_range.dispatch({
+                    encoder,
+                    group_count_x: Math.min(Math.ceil(pushes[i + 1] / SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE), WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+                    bindings: {
+                        settings: { first: pushes[i], count: pushes[i + 1], counter: GRASS_POOL_FREE_COUNT },
+                        counts: this.#pool,
+                        slots: this.#free,
+                    },
+                });
+            }
+
+            if (fill_directory) {
+                // no record, in a table of its size: the count, then every record
+                encoder.clearBuffer(this.#directory, 0, 4);
+                encoder.clearBuffer(this.#directory, 8, table_size * 8);
+
+                shader_grass_directory_fill.dispatch({
+                    encoder,
+                    group_count_x: Math.ceil(slot_capacity / GRASS_DIRECTORY_FILL_WORKGROUP_SIZE),
+                    bindings: { slot_capacity, grass_pool: this.#pool, grass_directory: this.#directory },
+                });
+            }
+
+            shader_grass_surface_retire.dispatch({
+                encoder,
+                group_count_x: Math.ceil(slot_capacity / GRASS_SURFACE_RETIRE_WORKGROUP_SIZE),
+                bindings: {
+                    settings: { frame, slot_capacity },
+                    grass_pool: this.#pool,
+                    grass_directory: this.#directory,
+                    grass_free: this.#free,
+                },
+            });
+        });
+
+        // it writes the pool, which the graph does not hold
+        pass.make_side_effect();
+
+        this.#graph_invalidate(graph);
+    }
+
+    /**
+     * Record the pass that plans the next frame's eviction, and the reading of the pool's counters that
+     * growth and the directory's upkeep follow.
+     *
+     * @param {FrameGraph} graph
+     */
+    #graph_end_frame(graph) {
+        const slack = this.settings.bake_capacity * this.#views_before;
+
+        const pass = graph.add("schedule eviction", {}, (data, resources, context) => {
+            shader_grass_surface_schedule.dispatch({
+                encoder: context.encoder,
+                bindings: { slack, grass_pool: this.#pool },
+            });
+        });
+
+        pass.make_side_effect();
+
+        const read_frame = this.#frame;
+        const generation = this.#generation;
+
+        graph_read_buffer({
+            graph,
+            buffer: graph_import_buffer(graph, this.#pool, "grass / pool"),
+            offset: 0,
+            size: 4 * (Math.max(GRASS_POOL_STARVED, GRASS_POOL_REMOVED) + 1),
+        })
+            .then(reference => {
+                try {
+                    if (generation !== this.#generation) {
+                        return;
+                    }
+
+                    const words = new Uint32Array(reference.getValue());
+
+                    if (words[GRASS_POOL_STARVED] !== this.#starved) {
+                        this.#starved = words[GRASS_POOL_STARVED];
+                        this.#grow_pending ||= read_frame >= this.#grown_frame;
+                    }
+
+                    this.#removed = words[GRASS_POOL_REMOVED];
+                } finally {
+                    reference.release();
+                }
+            })
+            .catch(() => {
+                // a reading lost to a timeout or a lost device: the counts run on, and a later reading carries them
+            });
+    }
+
+    /**
+     * What a view asks of the surfaces this frame, as the passes' immediate (`GRASS_SURFACE_VIEW_SETTINGS`):
+     * the settings, the view's focal length in pixels, the frame and the counts. `blade_capacity` is left
+     * at zero for whoever keeps a blade list.
+     *
+     * @param {GPUViewContext} view
+     * @returns {object|null} null while there is no pool, no surface, or nothing grows on any
+     */
+    view_settings(view) {
+        const tallest = this.#tallest_blade();
+
+        if (this.#pool === null || this.#surface_count === 0 || tallest <= 0) {
+            return null;
+        }
+
+        const settings = this.settings;
+
+        return {
+            finest_spacing: settings.finest_spacing,
+            // what a unit a unit away spans, in pixels: the projection's vertical scale over half the view's height
+            focal: view.camera.camera.projection_matrix[5] * view.resolution[1] * 0.5,
+            narrowest_blade: settings.narrowest_blade,
+            shortest_blade: settings.shortest_blade,
+            frame: this.#frame,
+            level_count: grass_surface_level_count(tallest, settings.finest_spacing, settings.narrowest_blade, settings.shortest_blade),
+            surface_count: this.#surface_count,
+            job_capacity: settings.bake_capacity,
+            slot_capacity: this.#slot_capacity,
+            canopy_opacity: settings.canopy_opacity,
+            blade_capacity: 0,
+        };
+    }
+
+    /**
+     * Record a view's asks for tiles, and the bake of those taken: the passes of `GRASS_SURFACE.js`'s
+     * lifetime, in the frame graph. Records nothing while there is no surface.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view the view; its scene is the surfaces' scene
+     */
+    graph_update({ graph, view }) {
+        assert.defined(graph, 'graph');
+        assert.defined(view, 'view');
+
+        if (this.#pool === null) {
+            // no pool holds a tile to mark
+            this.#invalidations.length = 0;
+
+            return;
+        }
+
+        graph.push_scope("grass surfaces");
+
+        // the first view a frame records carries the passes that run once a frame
+        const first_view = this.#lifetime_frame !== this.#frame;
+
+        this.#lifetime_frame = this.#frame;
+        this.#views++;
+
+        if (first_view) {
+            this.#graph_begin_frame(graph);
+        }
+
+        const settings = this.settings;
+
+        const tallest = this.#tallest_blade();
+
+        if (this.#surface_count === 0 || tallest <= 0) {
+            // no surface, or nothing grows on any: no view wants a tile
+            if (first_view) {
+                this.#graph_end_frame(graph);
+            }
+
+            graph.pop_scope();
+
+            return;
+        }
+
+        const view_settings = this.view_settings(view);
+
+        const level_count = view_settings.level_count;
+
+        const window_total = this.#surface_count * level_count;
+
+        const camera = view.camera;
+
+        const scene = view.scene;
+
+        const count_data = {};
+
+        const count_pass = graph.add("count windows", count_data, (data, resources, context) => {
+            shader_grass_surface_window_count.dispatch({
+                encoder: context.encoder,
+                group_count_x: Math.ceil(window_total / GRASS_SURFACE_WINDOW_COUNT_WORKGROUP_SIZE),
+                bindings: {
+                    settings: view_settings,
+                    camera: camera.gpu_buffer,
+                    scene_database: scene.scene_database_buffer,
+                    grass_surfaces: this.#surfaces_buffer,
+                    grass_window_counts: resources.get(data.counts),
+                },
+            });
+        });
+
+        count_data.counts = count_pass.create("window counts", BufferResourceDescriptor.from(
+            collection_size(window_total),
+            GPUBufferUsage.STORAGE,
+            // the count, which thread 0 writes
+            0, COLLECTION_HEADER_BYTES,
+        ));
+
+        const sums = graph_prefix_scan_csdldf({
+            graph,
+            input: count_data.counts,
+            output: graph_create_buffer(graph, "window offsets", prefix_scan_csdldf_output_descriptor(window_total)),
+            element_max_count: window_total,
+        });
+
+        const command_data = {};
+
+        const command_pass = graph.add("make want command", command_data, (data, resources, context) => {
+            shader_prefix_sum_to_command.dispatch({
+                encoder: context.encoder,
+                bindings: {
+                    prefix_sums: resources.get(data.prefix_sums),
+                    command: resources.get(data.command),
+                },
+            });
+        });
+
+        command_data.prefix_sums = command_pass.read(sums);
+        command_data.command = command_pass.create("want command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+
+        const want_data = {};
+
+        const want_pass = graph.add("want tiles", want_data, (data, resources, context) => {
+            shader_grass_surface_want.dispatchIndirect({
+                encoder: context.encoder,
+                command: resources.get(data.command),
+                bindings: {
+                    settings: view_settings,
+                    camera: camera.gpu_buffer,
+                    scene_database: scene.scene_database_buffer,
+                    grass_surfaces: this.#surfaces_buffer,
+                    prefix_sums: resources.get(data.prefix_sums),
+                    grass_pool: this.#pool,
+                    grass_directory: this.#directory,
+                    grass_free: this.#free,
+                    grass_jobs: resources.get(data.jobs),
+                },
+            });
+        });
+
+        want_data.command = want_pass.read(command_data.command);
+        want_data.prefix_sums = want_pass.read(sums);
+        want_data.jobs = want_pass.create("bake list", BufferResourceDescriptor.from(
+            collection_size(settings.bake_capacity),
+            GPUBufferUsage.STORAGE,
+            // the count, which the asks raise from zero
+            0, COLLECTION_HEADER_BYTES,
+        ));
+
+        const bake_command_data = {};
+
+        const bake_command_pass = graph.add("make bake command", bake_command_data, (data, resources, context) => {
+            shader_grass_surface_bake_command.dispatch({
+                encoder: context.encoder,
+                bindings: {
+                    job_capacity: settings.bake_capacity,
+                    grass_jobs: resources.get(data.jobs),
+                    command: resources.get(data.command),
+                },
+            });
+        });
+
+        bake_command_data.jobs = bake_command_pass.write(bake_command_pass.read(want_data.jobs));
+        bake_command_data.command = bake_command_pass.create("bake command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR);
+
+        const bake_data = {};
+
+        const bake_pass = graph.add("bake tiles", bake_data, (data, resources, context) => {
+            const geometries = scene.geometries;
+
+            shader_grass_surface_bake.dispatchIndirect({
+                encoder: context.encoder,
+                command: resources.get(data.command),
+                bindings: {
+                    settings: { finest_spacing: settings.finest_spacing },
+                    scene_database: scene.scene_database_buffer,
+                    tlas: scene.tlas.buffer,
+                    blas_lookup: geometries.blas.buffer_metadata,
+                    blas_data: geometries.blas.buffer_data,
+                    geometries: geometries.buffer_metadata,
+                    meshlet_metadata: geometries.meshlets.buffer_metadata,
+                    meshlet_data: geometries.meshlets.buffer_data,
+                    grass_jobs: resources.get(data.jobs),
+                    grass_pool: this.#pool,
+                    grass_surfels: this.#atlas.texture_at(0).obtainView(),
+                },
+            });
+        });
+
+        bake_data.command = bake_pass.read(bake_command_data.command);
+        bake_data.jobs = bake_pass.read(bake_command_data.jobs);
+
+        // the bake writes the pool and the atlas, which the graph does not hold
+        bake_pass.make_side_effect();
+
+        if (first_view) {
+            this.#graph_end_frame(graph);
+        }
+
+        graph.pop_scope();
+    }
+
+    /**
+     * Let go of everything on the device. The surfaces stay listed: the next {@link update} makes a fresh
+     * pool for them.
+     */
+    destroy() {
+        this.#surfaces_buffer?.destroy();
+        this.#invalidation_buffer?.destroy();
+
+        this.#surfaces_buffer = null;
+        this.#invalidation_buffer = null;
+
+        this.#drop_pool();
+    }
+
+    /**
+     * Let go of the pool and everything it holds.
+     */
+    #drop_pool() {
+        this.#pool?.destroy();
+        this.#free?.destroy();
+        this.#directory?.destroy();
+        this.#atlas?.destroy();
+
+        this.#pool = null;
+        this.#free = null;
+        this.#directory = null;
+        this.#atlas = null;
+        this.#invalidations.length = 0;
+        this.#slot_capacity = 0;
+        this.#slot_capacity_wanted = 0;
+        this.#fill_pending = false;
+        this.#pushes.length = 0;
+        this.#starved = 0;
+        this.#removed = 0;
+        this.#removed_at_fill = 0;
+        this.#grow_pending = false;
+        this.#directory_stale = false;
+        this.#generation++;
+    }
+}