@woosh/meep-engine 3.64.1 → 3.65.0

package/src/engine/graphics3/GrassSurfaceSystem.js

@@ -0,0 +1,1076 @@
+import { assert } from "../../core/assert.js";
+import { m4_from_rotation_translation_scale_array } from "../../core/geom/3d/mat4/m4_from_rotation_translation_scale_array.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { GPUGrassBlades } from "../../shade/renderer/grass/blade/GPUGrassBlades.js";
+import { GPUGrassSurfaces } from "../../shade/renderer/grass/surface/GPUGrassSurfaces.js";
+import { grass_surface_lattice_bits } from "../../shade/renderer/scene/GRASS_SURFACE_PARAMS_STRUCT.js";
+import {
+    MESH_GROUND_COVER_FLAG_GROWS,
+    MESH_GROUND_COVER_FLAG_MEMBER
+} from "../../shade/renderer/scene/MESH_GROUND_COVER_STRUCT.js";
+import { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
+import { EventType } from "../ecs/EventType.js";
+import { System } from "../ecs/System.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { TransformAttachment } from "../ecs/transform-attachment/TransformAttachment.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import {
+    Transform64,
+    TRANSFORM64_ROTATION_OFFSET,
+    TRANSFORM64_SCALE_OFFSET,
+    TRANSFORM64_TRANSLATION_OFFSET
+} from "../ecs/transform/Transform64.js";
+import { GrassSurface } from "../graphics/ecs/grass/GrassSurface.js";
+import { GPUFluidSystem } from "./GPUFluidSystem.js";
+import { SHADED_GEOMETRY_EVENT_CHANGE } from "../graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.js";
+
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../shade/renderer/scene/Scene.js").Scene} Scene
+ * @typedef {import("../graphics/ecs/grass/GrassSpecies.js").GrassSpecies} GrassSpecies
+ * @typedef {import("../graphics/ecs/grass/GroundCover.js").GroundCover} GroundCover
+ * @typedef {import("../graphics/ecs/mesh-v2/ShadedGeometry.js").ShadedGeometry} ShadedGeometry
+ * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
+ */
+
+/**
+ * A grass surface's entity, and what is held on its behalf.
+ */
+class SurfaceEntry {
+    /** @type {number} */
+    entity = -1;
+
+    /** @type {Transform64} */
+    transform = null;
+
+    /**
+     * Whether the entity's `transforms` row is held in the current context.
+     * @type {boolean}
+     */
+    held = false;
+
+    /** @type {function(): void} */
+    on_world = null;
+
+    /** @type {function(): void} */
+    on_local = null;
+
+    /** @type {function({klass: Function}): void} */
+    on_components = null;
+}
+
+/**
+ * A mesh entity that is ground of a surface.
+ */
+class MemberEntry {
+    /** @type {number} */
+    entity = -1;
+
+    /** @type {GroundCover} */
+    cover = null;
+
+    /** @type {ShadedGeometry} */
+    shaded = null;
+
+    /** @type {Transform64} */
+    transform = null;
+
+    /**
+     * The species the entry is counted under, which is the cover's as of the last write.
+     * @type {GrassSpecies|null}
+     */
+    species = null;
+
+    /**
+     * Whether the entity's `mesh_ground_covers` row is written in the current context.
+     * @type {boolean}
+     */
+    written = false;
+
+    /**
+     * The geometry the row was last written for; null before the first write. The geometry itself and not
+     * its address on the device, which a geometry that replaces another can be given.
+     * @type {object|null}
+     */
+    geometry = null;
+
+    /**
+     * Whether the member's ground is marked on the device where {@link corners} say it is.
+     * @type {boolean}
+     */
+    placed = false;
+
+    /**
+     * The eight corners of the member's geometry box in its surface's frame, as last marked.
+     * @type {Float64Array}
+     */
+    corners = new Float64Array(24);
+
+    /**
+     * The rectangle of {@link corners} on the frame's x and z: low x, low z, high x, high z.
+     * @type {Float64Array}
+     */
+    rectangle = new Float64Array(4);
+
+    /** @type {function(): void} */
+    on_changed = null;
+
+    /** @type {function(): void} */
+    on_world = null;
+}
+
+/**
+ * How far a corner of a member's box may be from where it was, in its surface's frame, before the member
+ * counts as moved and the ground under it is baked again: a micron. A surface that moves as one moves its
+ * members by the arithmetic's noise and no more, which for a world kilometres across is a ten-thousandth
+ * of this; nothing a surfel holds can show a move this small.
+ *
+ * @type {number}
+ */
+export const GRASS_MEMBER_MOVE_TOLERANCE = 1e-6;
+
+const ONES = Float64Array.of(1, 1, 1);
+
+const scratch_frame = new Float64Array(16);
+const scratch_member = new Float64Array(16);
+const scratch_low = new Float64Array(3);
+const scratch_high = new Float64Array(3);
+const scratch_corners = new Float64Array(24);
+
+/**
+ * The corners of a member's geometry box, placed by the member's transform and read in its surface's frame.
+ *
+ * @param {Float64Array} corners the eight corners, written here
+ * @param {Float64Array} frame the surface's frame, frame to world: a rotation and a translation
+ * @param {MemberEntry} member
+ */
+function member_corners(corners, frame, member) {
+    const box = member.shaded.geometry.bounding_box;
+    const t = member.transform;
+
+    const m = scratch_member;
+
+    m4_from_rotation_translation_scale_array(
+        m,
+        t, TRANSFORM64_ROTATION_OFFSET,
+        t, TRANSFORM64_TRANSLATION_OFFSET,
+        t, TRANSFORM64_SCALE_OFFSET
+    );
+
+    for (let corner = 0; corner < 8; corner++) {
+        const x = box[(corner & 1) === 0 ? 0 : 3];
+        const y = box[(corner & 2) === 0 ? 1 : 4];
+        const z = box[(corner & 4) === 0 ? 2 : 5];
+
+        // into the world, and from the frame's origin
+        const wx = m[0] * x + m[4] * y + m[8] * z + m[12] - frame[12];
+        const wy = m[1] * x + m[5] * y + m[9] * z + m[13] - frame[13];
+        const wz = m[2] * x + m[6] * y + m[10] * z + m[14] - frame[14];
+
+        // onto the frame's axes
+        for (let axis = 0; axis < 3; axis++) {
+            corners[corner * 3 + axis] = frame[axis * 4] * wx + frame[axis * 4 + 1] * wy + frame[axis * 4 + 2] * wz;
+        }
+    }
+}
+
+/**
+ * Keeps the scene's grass surfaces on the device: which entities are surfaces, which mesh rows are ground
+ * of which, and a box and a tallest blade for each surface, so that views can ask for its tiles.
+ *
+ * A surface is an entity with [{@link GrassSurface}, {@link Transform64}]; this system links those. Its
+ * members are the mesh entities whose {@link GroundCover} names it, which {@link GroundCoverSystem} links
+ * and hands over through {@link add_member}. A member may arrive before its surface, and waits.
+ *
+ * **What is written, and when.** Nothing per frame: a link, an unlink, an edit announced by a component's
+ * `onChanged`, and a move announced by the dataset queue the surface or member they touch, and
+ * {@link update} writes what is queued.
+ *
+ * - A member's `mesh_ground_covers` row, at the entity's own row: its surface's `transforms` row, the
+ *   geometry a column traces for it, its species and density. Written once the mesh row itself exists.
+ * - A surface's record in {@link GPUGrassSurfaces}: a box, in the surface's frame, that holds every member
+ *   whose row is written, as placed, and the tallest blade of any of their species. A surface with no such
+ *   member has no record.
+ * - The ground that changed ({@link GPUGrassSurfaces#invalidate}): the rectangle of a member that has come,
+ *   gone, changed geometry, or moved in its surface's frame by more than
+ *   {@link GRASS_MEMBER_MOVE_TOLERANCE}. A surface that moves as one marks nothing.
+ * - A surface's `transforms` row is held, so that a surface entity with no mesh of its own has a frame on
+ *   the device.
+ *
+ * **Rows need a device.** While the scene has no GPU context nothing is written, and when one arrives or
+ * is replaced everything is queued again.
+ */
+export class GrassSurfaceSystem extends System {
+    dependencies = [GrassSurface, Transform64];
+
+    /** @type {GraphicsEngine} */
+    #graphics;
+
+    /** @type {Scene} */
+    #scene;
+
+    /** @type {GPUSceneContext|null} */
+    #context = null;
+
+    /** @type {GPUGrassSurfaces|null} */
+    #gpu = null;
+
+    /** @type {GPUGrassBlades|null} */
+    #blades = null;
+
+    /** @type {GrassSurfaceExtension|null} */
+    #extension = null;
+
+    /** @type {GrassBladeExtension|null} */
+    #draw_extension = null;
+
+    /**
+     * The finest spacing the surfaces' `grass_surface_params` rows were written for.
+     * @type {number}
+     */
+    #params_spacing = 0;
+
+    /** @type {Map<number, SurfaceEntry>} */
+    #surfaces = new Map();
+
+    /** @type {Map<number, MemberEntry>} */
+    #members = new Map();
+
+    /**
+     * Members by the surface entity their cover names, whether or not that entity is a surface yet.
+     * @type {Map<number, Set<MemberEntry>>}
+     */
+    #members_of = new Map();
+
+    /**
+     * Surface entities whose record is to be written, or taken away if they are surfaces no longer.
+     * @type {Set<number>}
+     */
+    #dirty_surfaces = new Set();
+
+    /**
+     * Members whose row is to be written.
+     * @type {Set<MemberEntry>}
+     */
+    #dirty_members = new Set();
+
+    /**
+     * Each species in use: its index, how many members grow it, and the listener on its `onChanged`.
+     * @type {Map<GrassSpecies, {index: number, uses: number, on_changed: function(): void}>}
+     */
+    #species = new Map();
+
+    /** @type {number[]} species indices given back */
+    #species_free = [];
+
+    /** @type {number} */
+    #species_next = 0;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    /**
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * The surfaces on the device, or null while the scene has no GPU context.
+     *
+     * @returns {GPUGrassSurfaces|null}
+     */
+    get surfaces() {
+        return this.#gpu;
+    }
+
+    /**
+     * The blades on the device, or null while the scene has no GPU context.
+     *
+     * @returns {GPUGrassBlades|null}
+     */
+    get blades() {
+        return this.#blades;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new GrassSurfaceExtension(this));
+        this.#draw_extension = this.#graphics.add_extension(new GrassBladeExtension(this));
+    }
+
+    async shutdown(entityManager) {
+        for (const entry of Array.from(this.#surfaces.values())) {
+            this.unlink(null, entry.transform, entry.entity);
+        }
+
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+            this.#extension = null;
+        }
+
+        if (this.#draw_extension !== null) {
+            this.#graphics.remove_extension(this.#draw_extension);
+            this.#draw_extension = null;
+        }
+
+        this.#drop_context();
+    }
+
+    /** The scene's rows are this dataset's entities; the first system to place one says so. */
+    handleDatasetAttached(dataset) {
+        assert.ok(this.#scene.dataset == null || this.#scene.dataset === dataset, 'scene belongs to another dataset');
+
+        this.#scene.dataset = dataset;
+    }
+
+    handleDatasetDetached(dataset) {
+        if (this.#scene.dataset === dataset) {
+            this.#scene.dataset = null;
+        }
+    }
+
+    /**
+     * @param {GrassSurface} surface
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(surface, transform, entity) {
+        const entry = new SurfaceEntry();
+
+        entry.entity = entity;
+        entry.transform = transform;
+
+        entry.on_world = () => {
+            if (entry.held) {
+                this.#context.rows.mark_world(entity);
+            }
+
+            // the members are where they were; what they are in the frame is not
+            this.#dirty_surfaces.add(entity);
+        };
+
+        entry.on_local = () => {
+            if (entry.held) {
+                this.#context.rows.mark_local(entity);
+            }
+        };
+
+        entry.on_components = ({ klass }) => {
+            if (klass === TransformAttachment) {
+                entry.on_local();
+            }
+        };
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world);
+        dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.on_local);
+        dataset.addEntityEventListener(entity, EventType.ComponentAdded, entry.on_components);
+        dataset.addEntityEventListener(entity, EventType.ComponentRemoved, entry.on_components);
+
+        this.#surfaces.set(entity, entry);
+        this.#dirty_surfaces.add(entity);
+
+        // members that came first can be written now
+        this.#queue_members_of(entity);
+    }
+
+    /**
+     * @param {GrassSurface} surface
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(surface, transform, entity) {
+        const entry = this.#surfaces.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world);
+        dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.on_local);
+        dataset.removeEntityEventListener(entity, EventType.ComponentAdded, entry.on_components);
+        dataset.removeEntityEventListener(entity, EventType.ComponentRemoved, entry.on_components);
+
+        this.#surfaces.delete(entity);
+
+        // a context that has been replaced took its rows with it; only the one that is running is handed anything back
+        if (this.#context !== null && this.#context === this.#graphics.scene_context(this.#scene)) {
+            if (entry.held) {
+                this.#context.rows.release(entity);
+            }
+
+            this.#gpu.remove(row_of_entity(entity));
+            this.#clear_params(row_of_entity(entity), this.#context);
+        }
+
+        entry.held = false;
+
+        this.#dirty_surfaces.delete(entity);
+
+        // its members are ground of nothing until it is a surface again
+        this.#queue_members_of(entity);
+    }
+
+    /**
+     * A mesh entity becomes ground of the surface its cover names.
+     *
+     * @param {number} entity
+     * @param {GroundCover} cover
+     * @param {ShadedGeometry} shaded
+     * @param {Transform64} transform
+     */
+    add_member(entity, cover, shaded, transform) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.equal(this.#members.has(entity), false, 'entity is a member already');
+
+        const member = new MemberEntry();
+
+        member.entity = entity;
+        member.cover = cover;
+        member.shaded = shaded;
+        member.transform = transform;
+
+        member.on_changed = () => {
+            this.#dirty_members.add(member);
+            this.#dirty_surfaces.add(cover.surface);
+        };
+
+        member.on_world = () => {
+            this.#dirty_surfaces.add(cover.surface);
+        };
+
+        cover.onChanged.add(member.on_changed);
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, member.on_world);
+        dataset.addEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, member.on_changed);
+
+        this.#members.set(entity, member);
+
+        let set = this.#members_of.get(cover.surface);
+
+        if (set === undefined) {
+            set = new Set();
+
+            this.#members_of.set(cover.surface, set);
+        }
+
+        set.add(member);
+
+        this.#species_take(member);
+
+        member.on_changed();
+    }
+
+    /**
+     * A mesh entity stops being ground.
+     *
+     * @param {number} entity one that is no member is left alone
+     */
+    remove_member(entity) {
+        const member = this.#members.get(entity);
+
+        if (member === undefined) {
+            return;
+        }
+
+        const cover = member.cover;
+
+        cover.onChanged.remove(member.on_changed);
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, member.on_world);
+        dataset.removeEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, member.on_changed);
+
+        this.#members.delete(entity);
+        this.#dirty_members.delete(member);
+
+        const set = this.#members_of.get(cover.surface);
+
+        set.delete(member);
+
+        if (set.size === 0) {
+            this.#members_of.delete(cover.surface);
+        }
+
+        this.#species_give(member);
+
+        if (member.written && this.#context !== null && this.#context === this.#graphics.scene_context(this.#scene)) {
+            this.#context.scene_database.get('mesh_ground_covers').remove(row_of_entity(entity));
+
+            this.#unplace(member);
+        }
+
+        member.written = false;
+        member.placed = false;
+
+        this.#dirty_surfaces.add(cover.surface);
+    }
+
+    /**
+     * @param {number} surface a surface entity
+     */
+    #queue_members_of(surface) {
+        const set = this.#members_of.get(surface);
+
+        if (set === undefined) {
+            return;
+        }
+
+        for (const member of set) {
+            this.#dirty_members.add(member);
+        }
+    }
+
+    /**
+     * Count a member under its cover's species, which gets an index when it is first used.
+     *
+     * @param {MemberEntry} member
+     */
+    #species_take(member) {
+        const species = member.cover.species;
+
+        member.species = species;
+
+        if (species === null) {
+            return;
+        }
+
+        let record = this.#species.get(species);
+
+        if (record === undefined) {
+            const index = this.#species_free.length > 0 ? this.#species_free.pop() : this.#species_next++;
+
+            record = {
+                index,
+                uses: 0,
+                // a blade's length reaches every surface it grows on
+                on_changed: () => {
+                    this.#push_species(species, index);
+
+                    for (const other of this.#members.values()) {
+                        if (other.species === species) {
+                            other.on_changed();
+                        }
+                    }
+                },
+            };
+
+            species.onChanged.add(record.on_changed);
+
+            this.#species.set(species, record);
+
+            this.#push_species(species, index);
+        }
+
+        record.uses++;
+    }
+
+    /**
+     * Write a species' record on the device, if there is a device.
+     *
+     * @param {GrassSpecies} species
+     * @param {number} index
+     */
+    #push_species(species, index) {
+        if (this.#blades !== null) {
+            this.#blades.set_species(index, species);
+        }
+    }
+
+    /**
+     * Take a surface's `grass_surface_params` row away, if it has one.
+     *
+     * @param {number} row
+     * @param {GPUSceneContext} context
+     */
+    #clear_params(row, context) {
+        const table = context.scene_database.get('grass_surface_params');
+
+        if (table.occupancy.get(row)) {
+            table.remove(row);
+        }
+    }
+
+    /**
+     * @param {MemberEntry} member
+     */
+    #species_give(member) {
+        const species = member.species;
+
+        member.species = null;
+
+        if (species === null) {
+            return;
+        }
+
+        const record = this.#species.get(species);
+
+        if (--record.uses === 0) {
+            species.onChanged.remove(record.on_changed);
+
+            this.#species.delete(species);
+            this.#species_free.push(record.index);
+        }
+    }
+
+    /**
+     * The index a species in use is known by on the device.
+     *
+     * @param {GrassSpecies} species
+     * @returns {number} -1 for a species no member grows
+     */
+    species_index(species) {
+        const record = this.#species.get(species);
+
+        return record === undefined ? -1 : record.index;
+    }
+
+    #drop_context() {
+        if (this.#blades !== null) {
+            this.#blades.destroy();
+            this.#blades = null;
+        }
+
+        if (this.#gpu !== null) {
+            this.#gpu.destroy();
+            this.#gpu = null;
+        }
+
+        this.#context = null;
+
+        for (const entry of this.#surfaces.values()) {
+            entry.held = false;
+        }
+
+        for (const member of this.#members.values()) {
+            member.written = false;
+            member.placed = false;
+        }
+    }
+
+    /**
+     * A member's ground is no longer where it was marked: the tiles under it are to be baked again.
+     *
+     * @param {MemberEntry} member
+     */
+    #unplace(member) {
+        if (!member.placed) {
+            return;
+        }
+
+        member.placed = false;
+
+        if (this.#surfaces.has(member.cover.surface)) {
+            const r = member.rectangle;
+
+            this.#gpu.invalidate(row_of_entity(member.cover.surface), r[0], r[1], r[2], r[3]);
+        }
+    }
+
+    update(time_delta_seconds) {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            // no device: before the first start, or after a stop
+            if (this.#context !== null) {
+                this.#drop_context();
+            }
+
+            return;
+        }
+
+        if (context !== this.#context) {
+            // a new device took every row and buffer with the old one: everything is written again
+            const settings = this.#gpu?.settings;
+            const press = this.#blades?.press;
+
+            this.#drop_context();
+
+            this.#context = context;
+            this.#gpu = new GPUGrassSurfaces(context.graphics);
+
+            if (settings !== undefined) {
+                this.#gpu.settings = settings;
+            }
+
+            this.#blades = new GPUGrassBlades(context.graphics, this.#gpu);
+
+            if (press !== undefined) {
+                this.#blades.press.enabled = press.enabled;
+                this.#blades.press.spacing = press.spacing;
+            }
+
+            for (const [species, record] of this.#species) {
+                this.#push_species(species, record.index);
+            }
+
+            for (const entity of this.#surfaces.keys()) {
+                this.#dirty_surfaces.add(entity);
+            }
+
+            for (const member of this.#members.values()) {
+                this.#dirty_members.add(member);
+            }
+        }
+
+        if (this.#params_spacing !== this.#gpu.settings.finest_spacing) {
+            // the lattices are cut from the surfels' spacing: every surface's row is written again
+            this.#params_spacing = this.#gpu.settings.finest_spacing;
+
+            for (const entity of this.#surfaces.keys()) {
+                this.#dirty_surfaces.add(entity);
+            }
+        }
+
+        for (const member of this.#dirty_members) {
+            if (this.#write_member(member, context)) {
+                this.#dirty_members.delete(member);
+            }
+        }
+
+        for (const entity of this.#dirty_surfaces) {
+            this.#write_surface(entity, context);
+        }
+
+        this.#dirty_surfaces.clear();
+
+        this.#gpu.update();
+        this.#blades.update(time_delta_seconds);
+    }
+
+    /**
+     * Bring a member's `mesh_ground_covers` row up to date.
+     *
+     * @param {MemberEntry} member
+     * @param {GPUSceneContext} context
+     * @returns {boolean} false when the row has to wait for the entity's mesh row
+     */
+    #write_member(member, context) {
+        const covers = context.scene_database.get('mesh_ground_covers');
+        const row = row_of_entity(member.entity);
+        const cover = member.cover;
+
+        if (member.species !== cover.species) {
+            this.#species_give(member);
+            this.#species_take(member);
+        }
+
+        if (!this.#surfaces.has(cover.surface)) {
+            // ground of nothing, for now
+            if (member.written) {
+                covers.remove(row);
+
+                member.written = false;
+                member.placed = false;
+            }
+
+            return true;
+        }
+
+        const geometry = member.shaded.geometry;
+
+        if (!context.rows.has_mesh(member.entity) || !context.geometries.has(geometry)) {
+            return false;
+        }
+
+        const species = cover.species;
+        const address = context.geometries.getAddress(geometry);
+
+        if (member.written && member.geometry !== geometry) {
+            // other ground, in the same place
+            this.#unplace(member);
+        }
+
+        covers.set(row, {
+            flags: MESH_GROUND_COVER_FLAG_MEMBER | (species !== null ? MESH_GROUND_COVER_FLAG_GROWS : 0),
+            surface: row_of_entity(cover.surface),
+            geometry: address,
+            species: species !== null ? this.#species.get(species).index : 0,
+            density: Math.min(1, Math.max(0, cover.density)),
+        });
+
+        member.written = true;
+        member.geometry = geometry;
+
+        // its surface's box holds it from now, and the ground under it is marked
+        this.#dirty_surfaces.add(cover.surface);
+
+        return true;
+    }
+
+    /**
+     * Bring a surface's record up to date, or take it away when the entity is a surface no longer or has no member.
+     *
+     * @param {number} entity
+     * @param {GPUSceneContext} context
+     */
+    #write_surface(entity, context) {
+        const entry = this.#surfaces.get(entity);
+        const row = row_of_entity(entity);
+
+        if (entry === undefined) {
+            // unlinked since it was queued, and taken away there
+            return;
+        }
+
+        if (!entry.held) {
+            context.rows.acquire(entity);
+
+            entry.held = true;
+        }
+
+        const members = this.#members_of.get(entity);
+
+        if (members === undefined) {
+            this.#gpu.remove(row);
+            this.#clear_params(row, context);
+
+            return;
+        }
+
+        const t = entry.transform;
+        const frame = scratch_frame;
+
+        // where the entity is and how it is turned; its scale is no part of the frame
+        m4_from_rotation_translation_scale_array(
+            frame,
+            t, TRANSFORM64_ROTATION_OFFSET,
+            t, TRANSFORM64_TRANSLATION_OFFSET,
+            ONES, 0
+        );
+
+        const low = scratch_low.fill(Infinity);
+        const high = scratch_high.fill(-Infinity);
+
+        const corners = scratch_corners;
+
+        let blade_length = 0;
+        let blade_length_min = Infinity;
+        let blade_width_min = Infinity;
+        let density = 0;
+        let cover = 0;
+        let held = 0;
+
+        for (const member of members) {
+            if (!member.written) {
+                // no column can find it yet
+                continue;
+            }
+
+            member_corners(corners, frame, member);
+
+            for (let i = 0; i < 24; i++) {
+                const axis = i % 3;
+                const v = corners[i];
+
+                if (v < low[axis]) {
+                    low[axis] = v;
+                }
+
+                if (v > high[axis]) {
+                    high[axis] = v;
+                }
+            }
+
+            this.#place(row, member, corners);
+
+            const species = member.cover.species;
+
+            if (species !== null) {
+                blade_length = Math.max(blade_length, species.blade_length);
+                blade_length_min = Math.min(blade_length_min, species.blade_length);
+                blade_width_min = Math.min(blade_width_min, species.blade_width);
+                density = Math.max(density, species.density);
+                cover = Math.max(cover, species.density * species.blade_width);
+            }
+
+            held++;
+        }
+
+        if (held === 0) {
+            this.#gpu.remove(row);
+            this.#clear_params(row, context);
+
+            return;
+        }
+
+        this.#gpu.set(row, low, high, blade_length);
+
+        if (density > 0) {
+            context.scene_database.get('grass_surface_params').set(row, {
+                lattice_bits: grass_surface_lattice_bits(density, this.#gpu.settings.finest_spacing),
+                density,
+                blade_length,
+                blade_length_min,
+                blade_width_min,
+                cover,
+            });
+        } else {
+            this.#clear_params(row, context);
+        }
+    }
+
+    /**
+     * Mark a member's ground where it is, if that is not where it was marked: the tiles under where it was
+     * and under where it is are baked again. A member that has moved with its surface is where it was.
+     *
+     * @param {number} surface the surface's `transforms` row
+     * @param {MemberEntry} member
+     * @param {Float64Array} corners the member's corners in the surface's frame
+     */
+    #place(surface, member, corners) {
+        const was = member.corners;
+
+        if (member.placed) {
+            let moved = false;
+
+            for (let i = 0; i < 24; i++) {
+                if (Math.abs(corners[i] - was[i]) > GRASS_MEMBER_MOVE_TOLERANCE) {
+                    moved = true;
+
+                    break;
+                }
+            }
+
+            if (!moved) {
+                return;
+            }
+
+            this.#unplace(member);
+        }
+
+        was.set(corners);
+
+        const r = member.rectangle;
+
+        r[0] = Infinity;
+        r[1] = Infinity;
+        r[2] = -Infinity;
+        r[3] = -Infinity;
+
+        for (let corner = 0; corner < 8; corner++) {
+            const x = corners[corner * 3];
+            const z = corners[corner * 3 + 2];
+
+            r[0] = Math.min(r[0], x);
+            r[1] = Math.min(r[1], z);
+            r[2] = Math.max(r[2], x);
+            r[3] = Math.max(r[3], z);
+        }
+
+        member.placed = true;
+
+        this.#gpu.invalidate(surface, r[0], r[1], r[2], r[3]);
+    }
+
+    /**
+     * Record the frame's asks and bakes for one view.
+     *
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    record(frame) {
+        if (this.#gpu === null || frame.view.scene !== this.#context) {
+            return;
+        }
+
+        this.#gpu.graph_update({ graph: frame.graph, view: frame.view });
+    }
+
+    /**
+     * Record a view's blades, made and drawn into the frame's G-buffer. The blades are made here and not
+     * at the frame's start because they are bent by the scene's wind, which its producer publishes at the
+     * frame's start.
+     *
+     * The blades are pressed by the obstacles of the entity manager's {@link GPUFluidSystem}, when it has
+     * one for this scene.
+     *
+     * @param {FrameContext} frame
+     */
+    draw(frame) {
+        if (this.#blades === null || frame.view.scene !== this.#context) {
+            return;
+        }
+
+        const fluid = this.entityManager?.getSystem(GPUFluidSystem) ?? null;
+        const forcing = fluid !== null && fluid.scene === this.#scene ? fluid.forcing : null;
+
+        this.#blades.graph_generate({ graph: frame.graph, view: frame.view, forcing });
+        this.#blades.graph_draw(frame);
+    }
+}
+
+/**
+ * The blades' seat in the frame: where the G-buffer is written into, ahead of what is laid over surfaces.
+ */
+export class GrassBladeExtension extends RenderExtension {
+    name = "grass blades";
+
+    phase = FramePhase.AfterGBuffer;
+
+    /** @type {GrassSurfaceSystem} */
+    #system;
+
+    /**
+     * @param {GrassSurfaceSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.draw(frame);
+    }
+}
+
+/**
+ * The grass surfaces' seat in the frame: at its start, where the compute that later phases read belongs.
+ */
+export class GrassSurfaceExtension extends RenderExtension {
+    name = "grass surfaces";
+
+    phase = FramePhase.FrameStart;
+
+    /** @type {GrassSurfaceSystem} */
+    #system;
+
+    /**
+     * @param {GrassSurfaceSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+
+    enquirePipelines(enquiry) {
+        GPUGrassSurfaces.enquirePipelines(enquiry);
+        GPUGrassBlades.enquirePipelines(enquiry);
+    }
+}