@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/scene/rows/GPUSceneRows.js

@@ -0,0 +1,1158 @@
+import { assert } from "../../../../core/assert.js";
+import { BitSet } from "../../../../core/binary/BitSet.js";
+import { GPUStateAuthority } from "../../../../engine/ecs/gpu/GPUStateAuthority.js";
+import { GPUStateAuthorityFlags } from "../../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
+import { TransformAttachment } from "../../../../engine/ecs/transform-attachment/TransformAttachment.js";
+import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { Transform64 } from "../../../../engine/ecs/transform/Transform64.js";
+import { generate_record_writer } from "../../buffer/table/serde/generate_record_writer.js";
+import { MESH_INSTANCE_METADATA_STRUCT } from "../MESH_INSTANCE_METADATA_STRUCT.js";
+import { NODE3D_SCENE_ID, NODE3D_STRUCT } from "../NODE3D_STRUCT.js";
+import { TransparencyMode } from "../../material/TransparencyMode.js";
+
+/**
+ * @typedef {import("../../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} EntityComponentDataset
+ * @typedef {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
+ * @typedef {import("../../geometry/GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ * @typedef {import("../../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
+ * @typedef {import("../GPUInstancesAccelerationStructure.js").GPUInstancesAccelerationStructure} GPUInstancesAccelerationStructure
+ * @typedef {import("../../animation/skinning/GPUMeshSkinningContext.js").GPUMeshSkinningContext} GPUMeshSkinningContext
+ * @typedef {import("../../geometry/MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
+ * @typedef {import("../../../../core/geom/3d/aabb/AABB3.js").AABB3} AABB3
+ */
+
+/**
+ * The row an entity occupies in both scene tables.
+ *
+ * Row 0 is the scene root — the hierarchy walk's terminator and the natural value of a
+ * zero-initialised buffer — so entity 0 lands at row 1 and every entity after it one row on. There
+ * is no mapping to consult and nothing to keep in step: the identity is the arithmetic.
+ *
+ * @param {number} entity
+ * @returns {number}
+ */
+export function row_of_entity(entity) {
+    return entity + 1;
+}
+
+/**
+ * The inverse of {@link row_of_entity}, for a row the renderer produced — a visibility-buffer
+ * pixel, a ray hit.
+ *
+ * @param {number} row
+ * @returns {number} the entity, or -1 for row 0
+ */
+export function entity_of_row(row) {
+    return row - 1;
+}
+
+/**
+ * Why an entity is on the dirty list. Carried as bits, because one frame can bring several
+ * reasons and the flush wants the union.
+ */
+const MARK_LOCAL = 1;
+const MARK_WORLD = 2;
+const MARK_MESH = 4;
+
+/**
+ * Staging for one `transforms` row, reused across every write. `global` and `prev_global` are read
+ * only on a row's first write.
+ */
+const TRANSFORM_RECORD = {
+    local_translation: new Float32Array(3),
+    local_rotation: new Float32Array(4),
+    local_scale: new Float32Array(3),
+    global: new Float32Array(16),
+    prev_global: new Float32Array(16),
+    parent: NODE3D_SCENE_ID,
+};
+
+/**
+ * What a `meshes` row's bounds hold until the bounds pass has derived them, which it does every
+ * tick for every occupied row, under the `global` the hierarchy pass composed — before anything
+ * culls, traces or reads them back. This side never computes a render box: for a subtree the GPU
+ * drives it does not hold the matrix the box needs, and a box it could compute would be one the
+ * pass overwrites within the frame.
+ *
+ * @type {Float32Array}
+ */
+const UNDERIVED_BOUNDING_BOX = new Float32Array(6);
+
+/**
+ * @type {Float32Array}
+ */
+const UNDERIVED_BOUNDING_SPHERE = new Float32Array(4);
+
+/**
+ * One mesh entry's geometry box under its entity's world matrix, for
+ * {@link GPUSceneRows.compute_world_bounds}.
+ *
+ * @type {Float64Array}
+ */
+const SCRATCH_WORLD_BOX = new Float64Array(6);
+
+/**
+ * Staging for one `meshes` row.
+ */
+const MESH_RECORD = {
+    geometry: 0,
+    material: 0,
+    node: NODE3D_SCENE_ID,
+    bounding_box: UNDERIVED_BOUNDING_BOX,
+    bounding_sphere: UNDERIVED_BOUNDING_SPHERE,
+};
+
+/**
+ * The fields of a row this side owns: its local TRS and the row of its parent. `global` and
+ * `prev_global` are composed by the hierarchy pass every frame for every row, whoever owns the TRS
+ * — see `GPUSceneContext` for why writing them here would be wrong as well as wasteful.
+ *
+ * @type {GPURecordWriter}
+ */
+const TRANSFORM_LOCAL_WRITER = generate_record_writer(NODE3D_STRUCT, [
+    'local_translation',
+    'local_rotation',
+    'local_scale',
+    'parent',
+]);
+
+/**
+ * Only the parent row: what changes when a parent gains or loses a row of its own while the
+ * entity's local offset is somebody else's to write.
+ *
+ * @type {GPURecordWriter}
+ */
+const TRANSFORM_PARENT_WRITER = generate_record_writer(NODE3D_STRUCT, ['parent']);
+
+/**
+ * The whole row, for its first write: `global` and `prev_global` are seeded to the entity's world
+ * matrix so its first frame reports no motion instead of a jump from the origin.
+ *
+ * @type {GPURecordWriter}
+ */
+const TRANSFORM_RECORD_WRITER = generate_record_writer(NODE3D_STRUCT);
+
+/**
+ * @type {GPURecordWriter}
+ */
+const MESH_RECORD_WRITER = generate_record_writer(MESH_INSTANCE_METADATA_STRUCT);
+
+/**
+ * What one entity has in the `meshes` table.
+ */
+class MeshEntry {
+    /**
+     * @type {MeshletGeometry}
+     */
+    geometry = null;
+
+    /**
+     * @type {ShadeMaterial}
+     */
+    material = null;
+
+    /**
+     * Whether the row draws a per-instance clone the skinning pass deforms, rather than the
+     * shared source. The clone is the skinning context's, made when the row is first written.
+     *
+     * @type {boolean}
+     */
+    skinned = false;
+
+    /**
+     * Whether the row has been written — and therefore whether the TLAS knows the row.
+     *
+     * @type {boolean}
+     */
+    written = false;
+
+    /**
+     * The material the written row draws with — the one its hold in the rows' material list is
+     * on. `null` until the row is written, and again once it is given back.
+     *
+     * @type {ShadeMaterial|null}
+     */
+    held = null;
+}
+
+/**
+ * Entities as rows of the scene database.
+ *
+ * **The entity is the row**, at {@link row_of_entity}. An entity that something in the renderer
+ * needs — a primitive, a joint, a parent of either — is {@link acquire}d, and from then until
+ * {@link release} its `transforms` row is written from its own components: `TransformAttachment`
+ * when it has one and its parent has a row, in which case the row holds the local offset and the
+ * parent's row and the GPU composes the world; the world `Transform64` otherwise, under the scene
+ * root, which is exact because the ECS composes every chain on the CPU regardless. A primitive
+ * {@link attach_mesh}es and takes the `meshes` row of the same index.
+ *
+ * **Change flow is mark, then flush.** The systems that place entities listen to the dataset's
+ * change events and {@link mark_local} or {@link mark_world}; nothing is read at mark time. The
+ * flush, in `GPUSceneContext.build`, reads each marked entity's components once, consults
+ * `GPUStateAuthority` then, writes the ranges the CPU owns, and clears the list. A world mark on
+ * an attached entity whose parent has a row writes nothing: its local offset and its parent are
+ * unchanged, and the GPU composes the rest. That is what stops a root's move from costing a row
+ * per descendant.
+ *
+ * **Render bounds are never written from this side.** They are derived on the GPU every tick from
+ * the composed world matrix, because the CPU does not hold that matrix for a subtree the GPU
+ * drives; a row is written with them underived, and the bounds pass has filled them in before
+ * anything reads them. What a consumer on this side wants is the readback (`GPUSceneContext.bounds`).
+ */
+export class GPUSceneRows {
+
+    /**
+     * @type {EntityComponentDataset}
+     */
+    #dataset;
+
+    /**
+     * @type {GPUTypedTable}
+     */
+    #transforms;
+
+    /**
+     * @type {GPUTypedTable}
+     */
+    #meshes;
+
+    /**
+     * @type {GPUGeometryManager}
+     */
+    #geometries;
+
+    /**
+     * @type {GPUMaterialManager}
+     */
+    #materials;
+
+    /**
+     * How many written mesh rows draw with each material. A material is listed while the count is
+     * above zero — what the rasterizers iterate to decide which buckets and pipelines a frame needs.
+     *
+     * @type {Map<ShadeMaterial, number>}
+     */
+    #material_holds = new Map();
+
+    /**
+     * Moves when a material enters or leaves {@link #material_holds}; not when a count changes
+     * between two positive values.
+     *
+     * @type {number}
+     */
+    #materials_version = 0;
+
+    /**
+     * @type {ShadeMaterial[]}
+     */
+    #cached_materials = [];
+
+    /**
+     * @type {number}
+     */
+    #cached_materials_version = -1;
+
+    /**
+     * @type {GPUInstancesAccelerationStructure}
+     */
+    #tlas;
+
+    /**
+     * The scene's skinning context, asked for when a skinned row is written — a function, because
+     * the context is built on first use and the rows may be here first.
+     *
+     * @type {function(): GPUMeshSkinningContext}
+     */
+    #skinning;
+
+    /**
+     * Entities holding a `transforms` row, from the first {@link acquire} to the last
+     * {@link release}.
+     *
+     * @type {BitSet}
+     */
+    #acquired = new BitSet();
+
+    /**
+     * How many holders each acquired entity has. A model holds every one of its entities' rows and
+     * a primitive holds its own, and the row goes when the last of them lets go. Indexed by entity.
+     *
+     * @type {Uint16Array}
+     */
+    #holds = new Uint16Array(256);
+
+    /**
+     * Entities whose row has been written at least once — whose next write is a patch rather than
+     * the seeding write.
+     *
+     * @type {BitSet}
+     */
+    #written = new BitSet();
+
+    /**
+     * Why each marked entity is marked, or zero. Indexed by entity.
+     *
+     * @type {Uint8Array}
+     */
+    #reason = new Uint8Array(256);
+
+    /**
+     * The marked entities, in the order they were first marked this frame.
+     *
+     * @type {number[]}
+     */
+    #marked = [];
+
+    /**
+     * The `parent` field each written row currently holds. Indexed by entity, meaningful for
+     * written rows only. Lets the flush notice a parent that gained or lost its row, which is a
+     * change to the child's row that no component write announces.
+     *
+     * @type {Uint32Array}
+     */
+    #parent_row = new Uint32Array(256);
+
+    /**
+     * Which entity each row's attachment named when it was last flushed, or -1. Indexed by entity.
+     * Maintains {@link #children}.
+     *
+     * @type {Int32Array}
+     */
+    #parent_entity = new Int32Array(256).fill(-1);
+
+    /**
+     * Acquired entities by the entity their attachment names, whether or not that entity has a row
+     * itself. When it acquires or releases one, these are the rows that have to change shape.
+     *
+     * @type {Map<number, Set<number>>}
+     */
+    #children = new Map();
+
+    /**
+     * @type {Map<number, MeshEntry>}
+     */
+    #mesh_entries = new Map();
+
+    /**
+     * @type {number}
+     */
+    #mesh_rows_version = 0;
+
+    /**
+     * @param {object} options
+     * @param {EntityComponentDataset} options.dataset
+     * @param {GPUTypedTable} options.transforms
+     * @param {GPUTypedTable} options.meshes
+     * @param {GPUGeometryManager} options.geometries
+     * @param {GPUMaterialManager} options.materials
+     * @param {GPUInstancesAccelerationStructure} options.tlas
+     * @param {function(): GPUMeshSkinningContext} options.skinning
+     */
+    constructor({ dataset, transforms, meshes, geometries, materials, tlas, skinning }) {
+        assert.defined(dataset, 'dataset');
+        assert.equal(dataset.isEntityComponentDataset, true, 'dataset.isEntityComponentDataset !== true');
+        assert.defined(transforms, 'transforms');
+        assert.defined(meshes, 'meshes');
+        assert.defined(geometries, 'geometries');
+        assert.defined(materials, 'materials');
+        assert.defined(tlas, 'tlas');
+        assert.typeOf(skinning, 'function', 'skinning');
+
+        this.#dataset = dataset;
+        this.#transforms = transforms;
+        this.#meshes = meshes;
+        this.#geometries = geometries;
+        this.#materials = materials;
+        this.#tlas = tlas;
+        this.#skinning = skinning;
+    }
+
+    /**
+     * @returns {EntityComponentDataset}
+     */
+    get dataset() {
+        return this.#dataset;
+    }
+
+    /**
+     * Bumped every time the `meshes` table gains or loses an entity's row. A row read and kept is
+     * only as valid as this number.
+     *
+     * @returns {number}
+     */
+    get mesh_rows_version() {
+        return this.#mesh_rows_version;
+    }
+
+    /**
+     * Whether the entity holds a `transforms` row — acquired and not yet released, written or not.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has(entity) {
+        return this.#acquired.get(entity);
+    }
+
+    /**
+     * Whether the entity holds a `meshes` row.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has_mesh(entity) {
+        return this.#mesh_entries.has(entity);
+    }
+
+    /**
+     * Every entity holding a `meshes` row, with what the row draws — what a tool that walks the
+     * scene's primitives on this side (a CPU bake, a verifier) iterates. The order is the order
+     * the meshes were attached in.
+     *
+     * @param {function(number, MeshletGeometry, ShadeMaterial, boolean): void} visitor entity,
+     *        geometry, material, whether the row draws a skinned clone
+     */
+    for_each_mesh(visitor) {
+        assert.isFunction(visitor, 'visitor');
+
+        for (const [entity, entry] of this.#mesh_entries) {
+            visitor(entity, entry.geometry, entry.material, entry.skinned);
+        }
+    }
+
+    /**
+     * The box around everything the rows draw, as this side can compose it: each mesh entry's
+     * geometry box projected under its entity's own `Transform64` — the ECS's world pose, exact
+     * for what the CPU placed and a frame behind for a subtree the GPU drives — and the union of
+     * them. What a consumer that sizes a volume once asks for; the box that is drawn is the GPU's,
+     * read back through `GPUSceneContext.bounds`.
+     *
+     * @param {AABB3} target set to the union, or to the empty box when nothing draws
+     * @returns {boolean} whether anything draws
+     */
+    compute_world_bounds(target) {
+        assert.defined(target, 'target');
+
+        target.setNegativelyInfiniteBounds();
+
+        let any = false;
+
+        for (const [entity, entry] of this.#mesh_entries) {
+            const world = this.#dataset.getComponent(entity, Transform64);
+
+            assert.defined(world, `entity ${entity} holds a mesh row and carries no Transform64`);
+
+            aabb3_matrix4_project(SCRATCH_WORLD_BOX, entry.geometry.bounding_box, world.matrix);
+
+            target._expandToFit(
+                SCRATCH_WORLD_BOX[0], SCRATCH_WORLD_BOX[1], SCRATCH_WORLD_BOX[2],
+                SCRATCH_WORLD_BOX[3], SCRATCH_WORLD_BOX[4], SCRATCH_WORLD_BOX[5],
+            );
+
+            any = true;
+        }
+
+        return any;
+    }
+
+    /**
+     * Hold the entity's `transforms` row. The first hold takes the row: it is written at the next
+     * flush, from the entity's components as they are then, and the entity must carry a
+     * `Transform64` by then. Every hold is matched by a {@link release}, and the row goes with the
+     * last one.
+     *
+     * Children already holding rows are re-marked on the first hold, so that they point at this
+     * one from the next flush instead of carrying their world pose under the scene root.
+     *
+     * @param {number} entity
+     */
+    acquire(entity) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        this.#ensure_capacity(entity);
+
+        if (this.#acquired.get(entity)) {
+            this.#holds[entity]++;
+
+            return;
+        }
+
+        this.#acquired.set(entity, true);
+        this.#written.set(entity, false);
+        this.#holds[entity] = 1;
+
+        this.#parent_entity[entity] = -1;
+
+        /*
+         Indexed under its attachment's parent from the start rather than at the first flush: the
+         animation manager walks the rows below a joint the moment a clip binds to it, which is
+         the same update the rows were acquired in. The flush re-registers, so a parent that
+         changes later is still followed.
+        */
+        const dataset = this.#dataset;
+        const attachment_index = dataset.computeComponentTypeIndex(TransformAttachment);
+
+        if (attachment_index !== -1) {
+            const attachment = dataset.getComponentByIndex(entity, attachment_index);
+
+            if (attachment !== undefined && attachment !== null) {
+                this.#register_child(entity, attachment.parent);
+            }
+        }
+
+        this.#mark(entity, MARK_LOCAL);
+
+        this.#mark_children(entity);
+    }
+
+    /**
+     * Let go of the entity's `transforms` row. The last holder to let go takes it back — and its
+     * `meshes` row with it, if it had one. Children keep theirs and are re-marked, to be written
+     * under the scene root from their world pose.
+     *
+     * Safe on an entity that holds nothing.
+     *
+     * @param {number} entity
+     */
+    release(entity) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        if (!this.#acquired.get(entity)) {
+            return;
+        }
+
+        if (--this.#holds[entity] > 0) {
+            return;
+        }
+
+        this.#free_mesh(entity);
+
+        if (this.#written.get(entity)) {
+            this.#transforms.remove(row_of_entity(entity));
+        }
+
+        this.#acquired.set(entity, false);
+        this.#written.set(entity, false);
+        this.#reason[entity] = 0;
+
+        this.#unregister_child(entity);
+
+        this.#mark_children(entity);
+    }
+
+    /**
+     * The entity's local offset or its attachment changed — what its own row holds.
+     *
+     * @param {number} entity
+     */
+    mark_local(entity) {
+        this.#mark(entity, MARK_LOCAL);
+    }
+
+    /**
+     * The entity's world transform changed. For an entity the GPU composes under a parent row this
+     * is nothing to write; for one carrying its world pose it is the row's contents.
+     *
+     * @param {number} entity
+     */
+    mark_world(entity) {
+        this.#mark(entity, MARK_WORLD);
+    }
+
+    /**
+     * Every material some written mesh row draws with, each once. The array is reused until the set
+     * changes — compare {@link materials_version} to know whether it did.
+     *
+     * @returns {ShadeMaterial[]}
+     */
+    get materials() {
+        if (this.#cached_materials_version !== this.#materials_version) {
+            this.#cached_materials = Array.from(this.#material_holds.keys());
+            this.#cached_materials_version = this.#materials_version;
+        }
+
+        return this.#cached_materials;
+    }
+
+    /**
+     * Moves when a material enters or leaves {@link materials}.
+     *
+     * @returns {number}
+     */
+    get materials_version() {
+        return this.#materials_version;
+    }
+
+    /**
+     * @param {ShadeMaterial} material
+     */
+    #hold_material(material) {
+        const holds = this.#material_holds;
+        const count = holds.get(material);
+
+        if (count === undefined) {
+            holds.set(material, 1);
+
+            this.#materials_version++;
+        } else {
+            holds.set(material, count + 1);
+        }
+    }
+
+    /**
+     * @param {ShadeMaterial} material
+     */
+    #release_material(material) {
+        const holds = this.#material_holds;
+        const count = holds.get(material);
+
+        assert.isNonNegativeInteger(count, 'count');
+        assert.greaterThan(count, 0, 'count');
+
+        if (count === 1) {
+            holds.delete(material);
+
+            this.#materials_version++;
+        } else {
+            holds.set(material, count - 1);
+        }
+    }
+
+    /**
+     * Give the entity a `meshes` row for one primitive, at the same index as its `transforms` row,
+     * which it takes as well if it does not have it yet. Replacing what it draws is the same call.
+     *
+     * A skinned primitive draws a per-instance clone of `geometry`, deformed by the skinning pass
+     * against whatever skin the entity is bound to; the clone is made when the row is written and
+     * given back with the row.
+     *
+     * The mesh is one hold on the `transforms` row, released by {@link detach_mesh}.
+     *
+     * @param {number} entity
+     * @param {MeshletGeometry} geometry
+     * @param {ShadeMaterial} material
+     * @param {boolean} [skinned]
+     */
+    attach_mesh(entity, geometry, material, skinned = false) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.defined(geometry, 'geometry');
+        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
+        assert.defined(material, 'material');
+        assert.isBoolean(skinned, 'skinned');
+
+        if (geometry.isVirtualGeometry === true
+            && material.transparency_mode !== TransparencyMode.Opaque) {
+            /*
+             It would draw nothing at all, silently. A virtual geometry expands to zero static
+             meshlets by construction, and the cut that fills that gap runs only in the opaque
+             rasterization paths — `prepare_meshlet_draw_commands_by_material`, which serves the
+             transparent and alpha-tested buckets, has no seam. VIRTUAL_GEOMETRY_DESIGN §9 scopes
+             v1 that way; what it did not do until now was say so, and the code cited it anyway
+             (REVIEW_LEDGER M14).
+
+             A warning rather than a refusal, because the attachment is otherwise legal and the
+             asset is fine — what is missing is a path, and the next campaign may add one.
+             */
+            console.warn(
+                `virtual geometry: entity ${entity} carries a ${
+                    geometry.name ?? 'virtual'
+                } geometry with a non-opaque material, and will draw nothing.`
+                + ` The cut runs only in the opaque paths (DESIGN §9).`
+            );
+        }
+
+        let entry = this.#mesh_entries.get(entity);
+
+        if (entry === undefined) {
+            this.acquire(entity);
+
+            entry = new MeshEntry();
+
+            this.#mesh_entries.set(entity, entry);
+        } else if (entry.written && (entry.skinned !== skinned || (skinned && entry.geometry !== geometry))) {
+            // a different clone, or none: the one the row draws goes back with the next write
+            this.#skinning().release_clone(entity);
+        }
+
+        entry.geometry = geometry;
+        entry.material = material;
+        entry.skinned = skinned;
+
+        this.#mark(entity, MARK_MESH);
+    }
+
+    /**
+     * Take the entity's `meshes` row back, and let go of the hold the mesh had on its
+     * `transforms` row — which stays if anything else holds it. Safe on an entity that has none.
+     *
+     * @param {number} entity
+     */
+    detach_mesh(entity) {
+        if (!this.#mesh_entries.has(entity)) {
+            return;
+        }
+
+        this.#free_mesh(entity);
+
+        this.release(entity);
+    }
+
+    /**
+     * Give a `meshes` row back without touching the holds on the entity's `transforms` row.
+     *
+     * @param {number} entity
+     */
+    #free_mesh(entity) {
+        const entry = this.#mesh_entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#mesh_entries.delete(entity);
+
+        if (!entry.written) {
+            return;
+        }
+
+        const row = row_of_entity(entity);
+
+        this.#meshes.remove(row);
+        this.#tlas.instance_remove(row);
+
+        this.#release_material(entry.held);
+
+        entry.held = null;
+
+        if (entry.skinned) {
+            // the row was the only thing naming the clone; its skin binding is kept, so a row
+            // that comes back is deformed again
+            this.#skinning().release_clone(entity);
+        }
+
+        this.#mesh_rows_version++;
+    }
+
+    /**
+     * Write every marked entity's rows from its components, and clear the list.
+     *
+     * @returns {number} rows written
+     */
+    flush() {
+        const marked = this.#marked;
+        const count = marked.length;
+
+        if (count === 0) {
+            return 0;
+        }
+
+        const dataset = this.#dataset;
+        const reason = this.#reason;
+
+        const transform_index = dataset.computeComponentTypeIndex(Transform64);
+        const attachment_index = dataset.computeComponentTypeIndex(TransformAttachment);
+        const authority_index = dataset.computeComponentTypeIndex(GPUStateAuthority);
+
+        let written = 0;
+
+        for (let i = 0; i < count; i++) {
+            const entity = marked[i];
+            const why = reason[entity];
+
+            reason[entity] = 0;
+
+            if (why === 0 || !this.#acquired.get(entity)) {
+                // released since it was marked
+                continue;
+            }
+
+            assert.ok(dataset.entityExists(entity), `entity ${entity} holds a row but is not in the dataset — release its row before removing it`);
+            assert.notEqual(transform_index, -1, 'Transform64 is not a registered component type of the dataset');
+
+            const world = dataset.getComponentByIndex(entity, transform_index);
+
+            assert.defined(world, `entity ${entity} holds a row and no Transform64`);
+
+            const attachment = attachment_index === -1
+                ? undefined
+                : dataset.getComponentByIndex(entity, attachment_index);
+
+            const authority = authority_index === -1
+                ? undefined
+                : dataset.getComponentByIndex(entity, authority_index);
+
+            const flags = authority === undefined ? 0 : authority.flags;
+
+            written += this.#flush_transform(entity, why, world, attachment, flags);
+            written += this.#flush_mesh(entity, why);
+        }
+
+        marked.length = 0;
+
+        return written;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} why
+     * @param {Transform64} world
+     * @param {TransformAttachment|undefined} attachment
+     * @param {number} flags
+     * @returns {number} rows written
+     */
+    #flush_transform(entity, why, world, attachment, flags) {
+        const row = row_of_entity(entity);
+
+        const parent = attachment === undefined ? -1 : attachment.parent;
+
+        this.#register_child(entity, parent);
+
+        const parent_has_row = parent >= 0 && this.#acquired.get(parent);
+
+        const parent_row = parent_has_row ? row_of_entity(parent) : NODE3D_SCENE_ID;
+
+        // What the row's local TRS is: the offset from the parent row when there is one, the world
+        // pose under the scene root when there is not. The second is exact — the ECS composed it.
+        const local = parent_has_row ? attachment.transform : world;
+
+        const first = !this.#written.get(entity);
+
+        if (first) {
+            this.#transforms.set_record(row, this.#seed_record(local, parent_row, world), TRANSFORM_RECORD_WRITER);
+
+            this.#written.set(entity, true);
+            this.#parent_row[entity] = parent_row;
+
+            return 1;
+        }
+
+        const parent_changed = this.#parent_row[entity] !== parent_row;
+
+        if ((flags & GPUStateAuthorityFlags.TransformAttachment) !== 0) {
+            // The GPU writes this row's TRS — a clip, a pose the CPU never sees — and a CPU that
+            // wrote it too would race what the animation just resolved. The parent row is still
+            // this side's, and changes only when the parent's own row comes or goes.
+            if (!parent_changed) {
+                return 0;
+            }
+
+            TRANSFORM_RECORD.parent = parent_row;
+
+            this.#transforms.set_fields(row, TRANSFORM_RECORD, TRANSFORM_PARENT_WRITER);
+
+            this.#parent_row[entity] = parent_row;
+
+            return 1;
+        }
+
+        const moved = parent_has_row
+            ? (why & MARK_LOCAL) !== 0
+            : (why & (MARK_LOCAL | MARK_WORLD)) !== 0;
+
+        if (!moved && !parent_changed) {
+            return 0;
+        }
+
+        this.#transforms.set_fields(row, this.#local_record(local, parent_row), TRANSFORM_LOCAL_WRITER);
+
+        this.#parent_row[entity] = parent_row;
+
+        return 1;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} why
+     * @returns {number} rows written
+     */
+    #flush_mesh(entity, why) {
+        const entry = this.#mesh_entries.get(entity);
+
+        if (entry === undefined) {
+            return 0;
+        }
+
+        const row = row_of_entity(entity);
+
+        if (entry.written && (why & MARK_MESH) === 0) {
+            if ((why & (MARK_WORLD | MARK_LOCAL)) !== 0) {
+                // The row's bounds are the GPU's — the bounds pass derives them under the composed
+                // global — and nothing on this side keeps a copy; what moved is the tree, which is
+                // rebuilt over them.
+                this.#tlas.instance_update(row);
+            }
+
+            return 0;
+        }
+
+        const geometry = entry.geometry;
+
+        this.#geometries.add(geometry);
+        this.#materials.obtain(entry.material);
+
+        if (entry.held !== entry.material) {
+            if (entry.held !== null) {
+                this.#release_material(entry.held);
+            }
+
+            this.#hold_material(entry.material);
+
+            entry.held = entry.material;
+        }
+
+        MESH_RECORD.geometry = entry.skinned
+            ? this.#skinning().obtain_clone(entity, geometry).index
+            : this.#geometries.getAddress(geometry);
+        MESH_RECORD.material = entry.material.id;
+        MESH_RECORD.node = row;
+
+        this.#meshes.set_record(row, MESH_RECORD, MESH_RECORD_WRITER);
+
+        if (entry.written) {
+            this.#tlas.instance_update(row);
+        } else {
+            entry.written = true;
+
+            this.#tlas.instance_add(row);
+
+            this.#mesh_rows_version++;
+        }
+
+        return 1;
+    }
+
+    /**
+     * @param {Transform64} local
+     * @param {number} parent_row
+     * @returns {object} the module-static record, valid until the next call
+     */
+    #local_record(local, parent_row) {
+        // through the scalar accessors: the vector properties are live views, freshly allocated
+        // on every access, and this runs once per changed row per frame
+        TRANSFORM_RECORD.local_translation[0] = local.translation_x;
+        TRANSFORM_RECORD.local_translation[1] = local.translation_y;
+        TRANSFORM_RECORD.local_translation[2] = local.translation_z;
+
+        TRANSFORM_RECORD.local_rotation[0] = local.rotation_x;
+        TRANSFORM_RECORD.local_rotation[1] = local.rotation_y;
+        TRANSFORM_RECORD.local_rotation[2] = local.rotation_z;
+        TRANSFORM_RECORD.local_rotation[3] = local.rotation_w;
+
+        TRANSFORM_RECORD.local_scale[0] = local.scale_x;
+        TRANSFORM_RECORD.local_scale[1] = local.scale_y;
+        TRANSFORM_RECORD.local_scale[2] = local.scale_z;
+
+        TRANSFORM_RECORD.parent = parent_row;
+
+        return TRANSFORM_RECORD;
+    }
+
+    /**
+     * @param {Transform64} local
+     * @param {number} parent_row
+     * @param {Transform64} world
+     * @returns {object} the module-static record, valid until the next call
+     */
+    #seed_record(local, parent_row, world) {
+        this.#local_record(local, parent_row);
+
+        for (let i = 0; i < 16; i++) {
+            TRANSFORM_RECORD.global[i] = world[i];
+            TRANSFORM_RECORD.prev_global[i] = world[i];
+        }
+
+        return TRANSFORM_RECORD;
+    }
+
+    /**
+     * @param {number} entity
+     * @param {number} why
+     */
+    #mark(entity, why) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        if (!this.#acquired.get(entity)) {
+            // nothing to write for an entity holding no row; a mark is not an acquire
+            return;
+        }
+
+        const reason = this.#reason;
+
+        if (reason[entity] === 0) {
+            this.#marked.push(entity);
+        }
+
+        reason[entity] |= why;
+    }
+
+    /**
+     * Re-mark every acquired entity whose attachment names `parent`.
+     *
+     * @param {number} parent
+     */
+    /**
+     * Visit every entity holding a row below `entity`, parents before their children.
+     *
+     * The index behind this is the one the rows keep for re-marking a subtree when its parent's
+     * row appears or goes; an entity with no row is not in it, and neither are its children.
+     *
+     * @param {number} entity
+     * @param {function(number): void} visitor
+     */
+    for_each_descendant(entity, visitor) {
+        assert.isNonNegativeInteger(entity, 'entity');
+        assert.typeOf(visitor, 'function', 'visitor');
+
+        const children = this.#children.get(entity);
+
+        if (children === undefined) {
+            return;
+        }
+
+        for (const child of children) {
+            visitor(child);
+
+            this.for_each_descendant(child, visitor);
+        }
+    }
+
+    #mark_children(parent) {
+        const children = this.#children.get(parent);
+
+        if (children === undefined) {
+            return;
+        }
+
+        for (const child of children) {
+            this.#mark(child, MARK_LOCAL);
+        }
+    }
+
+    /**
+     * Keep {@link #children} in step with what the entity's attachment names.
+     *
+     * @param {number} entity
+     * @param {number} parent the entity its attachment names, or -1
+     */
+    #register_child(entity, parent) {
+        const previous = this.#parent_entity[entity];
+
+        if (previous === parent) {
+            return;
+        }
+
+        this.#unregister_child(entity);
+
+        if (parent < 0) {
+            return;
+        }
+
+        let children = this.#children.get(parent);
+
+        if (children === undefined) {
+            children = new Set();
+
+            this.#children.set(parent, children);
+        }
+
+        children.add(entity);
+
+        this.#parent_entity[entity] = parent;
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #unregister_child(entity) {
+        const previous = this.#parent_entity[entity];
+
+        if (previous < 0) {
+            return;
+        }
+
+        const children = this.#children.get(previous);
+
+        if (children !== undefined) {
+            children.delete(entity);
+
+            if (children.size === 0) {
+                this.#children.delete(previous);
+            }
+        }
+
+        this.#parent_entity[entity] = -1;
+    }
+
+    /**
+     * Grow the per-entity arrays to cover `entity`. Doubling, so a dataset that grows steadily
+     * pays for this a logarithmic number of times.
+     *
+     * @param {number} entity
+     */
+    #ensure_capacity(entity) {
+        const length = this.#reason.length;
+
+        if (entity < length) {
+            return;
+        }
+
+        let size = length;
+
+        while (size <= entity) {
+            size *= 2;
+        }
+
+        const reason = new Uint8Array(size);
+        reason.set(this.#reason);
+        this.#reason = reason;
+
+        const holds = new Uint16Array(size);
+        holds.set(this.#holds);
+        this.#holds = holds;
+
+        const parent_row = new Uint32Array(size);
+        parent_row.set(this.#parent_row);
+        this.#parent_row = parent_row;
+
+        const parent_entity = new Int32Array(size).fill(-1);
+        parent_entity.set(this.#parent_entity);
+        this.#parent_entity = parent_entity;
+    }
+
+    /**
+     * Forget everything, freeing every row. For the context's own teardown.
+     */
+    destroy() {
+        for (const [entity, entry] of this.#mesh_entries) {
+            if (entry.written) {
+                const row = row_of_entity(entity);
+
+                this.#meshes.remove(row);
+                this.#tlas.instance_remove(row);
+
+                if (entry.skinned) {
+                    this.#skinning().release_clone(entity);
+                }
+            }
+        }
+
+        this.#mesh_entries.clear();
+
+        const acquired = this.#acquired;
+
+        for (let entity = acquired.nextSetBit(0); entity !== -1; entity = acquired.nextSetBit(entity + 1)) {
+            if (this.#written.get(entity)) {
+                this.#transforms.remove(row_of_entity(entity));
+            }
+        }
+
+        acquired.reset();
+        this.#written.reset();
+        this.#reason.fill(0);
+        this.#holds.fill(0);
+        this.#marked.length = 0;
+        this.#children.clear();
+        this.#parent_entity.fill(-1);
+    }
+}