@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -0,0 +1,144 @@
+import { assert } from "../../../../core/assert.js";
+import { MESH_INSTANCE_METADATA_STRUCT } from "../MESH_INSTANCE_METADATA_STRUCT.js";
+import { row_of_entity } from "./GPUSceneRows.js";
+
+/**
+ * Bytes of a row's world box: six f32.
+ *
+ * @type {number}
+ */
+const BOX_BYTES = 6 * 4;
+
+/**
+ * An entity's world bounds as the GPU holds them, read back.
+ *
+ * The box the renderer culls a primitive by is derived on the GPU from its geometry under the
+ * `global` the hierarchy pass composed — which for a subtree the GPU drives is a matrix the CPU
+ * never sees, and for a skinned primitive is the deformed clone's box rather than the rest pose's.
+ * A consumer that wants the box that is drawn — an editor's selection outline, a framing camera —
+ * asks here: {@link request} once a frame for each entity it cares about, and {@link get} for the
+ * last box that landed. A box lands a frame or two after it was asked for, at the head of a frame,
+ * never mid-update; until the first lands there is no answer, and a request that was dropped —
+ * the row changed hands — leaves the last answer standing.
+ *
+ * One request per entity per frame is the intended use; the readback service batches a frame's
+ * requests into one copy, or one gather dispatch past its threshold.
+ */
+export class GPUEntityBoundsReadback {
+    /**
+     * @type {import("../../buffer/table/GPUDatabaseReadback.js").GPUDatabaseReadback}
+     */
+    #readback;
+
+    /**
+     * @type {import("./GPUSceneRows.js").GPUSceneRows}
+     */
+    #rows;
+
+    /**
+     * The readback's handle for the `meshes` table.
+     * @type {number}
+     */
+    #table;
+
+    /**
+     * Byte offset of `bounding_box` in a `meshes` record.
+     * @type {number}
+     */
+    #offset;
+
+    /**
+     * Entity -> the memory its box lands in. `box` is a view over `bytes`; NaN until a delivery.
+     *
+     * @type {Map<number, {bytes: Uint8Array, box: Float32Array}>}
+     */
+    #slots = new Map();
+
+    /**
+     * @param {import("../../buffer/table/GPUDatabaseReadback.js").GPUDatabaseReadback} readback the
+     *        scene database's
+     * @param {import("./GPUSceneRows.js").GPUSceneRows} rows
+     */
+    constructor(readback, rows) {
+        assert.defined(readback, 'readback');
+        assert.defined(rows, 'rows');
+
+        this.#readback = readback;
+        this.#rows = rows;
+        this.#table = readback.table('meshes');
+        this.#offset = MESH_INSTANCE_METADATA_STRUCT.get('bounding_box').offset;
+    }
+
+    /**
+     * How many entities have a box here, delivered or awaited.
+     *
+     * @returns {number}
+     */
+    get tracked_count() {
+        return this.#slots.size;
+    }
+
+    /**
+     * Ask for an entity's box as the GPU holds it this frame. Nothing is asked for an entity with
+     * no mesh row — no primitive is drawn for it, so there is no box to read.
+     *
+     * @param {number} entity
+     * @returns {boolean} whether a row was asked for
+     */
+    request(entity) {
+        assert.isNonNegativeInteger(entity, 'entity');
+
+        if (!this.#rows.has_mesh(entity)) {
+            return false;
+        }
+
+        let slot = this.#slots.get(entity);
+
+        if (slot === undefined) {
+            const bytes = new Uint8Array(BOX_BYTES);
+            const box = new Float32Array(bytes.buffer);
+
+            box.fill(NaN);
+
+            slot = { bytes, box };
+
+            this.#slots.set(entity, slot);
+        }
+
+        this.#readback.request(this.#table, row_of_entity(entity), this.#offset, BOX_BYTES, slot.bytes);
+
+        return true;
+    }
+
+    /**
+     * The last box that landed for an entity.
+     *
+     * @param {number} entity
+     * @param {ArrayLike<number>|Float32Array|Float64Array|number[]} target aabb3, `x0,y0,z0,x1,y1,z1`
+     * @returns {boolean} whether one has; `false` leaves `target` alone
+     */
+    get(entity, target) {
+        const slot = this.#slots.get(entity);
+
+        if (slot === undefined || Number.isNaN(slot.box[0])) {
+            return false;
+        }
+
+        const box = slot.box;
+
+        for (let i = 0; i < 6; i++) {
+            target[i] = box[i];
+        }
+
+        return true;
+    }
+
+    /**
+     * Stop keeping an entity's box. A request already on the device lands in memory nothing reads.
+     *
+     * @param {number} entity
+     */
+    forget(entity) {
+        this.#slots.delete(entity);
+    }
+}

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @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: number): number;
+/**
+ * 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: number): number;
+/**
+ * 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 {
+    /**
+     * @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 }: {
+        dataset: EntityComponentDataset;
+        transforms: import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+        meshes: import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+        geometries: GPUGeometryManager;
+        materials: GPUMaterialManager;
+        tlas: GPUInstancesAccelerationStructure;
+        skinning: () => GPUMeshSkinningContext;
+    });
+    /**
+     * @returns {EntityComponentDataset}
+     */
+    get dataset(): import("../../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset;
+    /**
+     * 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(): number;
+    /**
+     * Whether the entity holds a `transforms` row — acquired and not yet released, written or not.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has(entity: number): boolean;
+    /**
+     * Whether the entity holds a `meshes` row.
+     *
+     * @param {number} entity
+     * @returns {boolean}
+     */
+    has_mesh(entity: number): boolean;
+    /**
+     * 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: (arg0: number, arg1: MeshletGeometry, arg2: ShadeMaterial, arg3: boolean) => void): void;
+    /**
+     * 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: AABB3): boolean;
+    /**
+     * 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: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * The entity's local offset or its attachment changed — what its own row holds.
+     *
+     * @param {number} entity
+     */
+    mark_local(entity: number): void;
+    /**
+     * 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: number): void;
+    /**
+     * 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(): import("../../material/ShadeMaterial.js").ShadeMaterial[];
+    /**
+     * Moves when a material enters or leaves {@link materials}.
+     *
+     * @returns {number}
+     */
+    get materials_version(): number;
+    /**
+     * 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: number, geometry: MeshletGeometry, material: ShadeMaterial, skinned?: boolean): void;
+    /**
+     * 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: number): void;
+    /**
+     * Write every marked entity's rows from its components, and clear the list.
+     *
+     * @returns {number} rows written
+     */
+    flush(): number;
+    /**
+     * 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: number, visitor: (arg0: number) => void): void;
+    /**
+     * Forget everything, freeing every row. For the context's own teardown.
+     */
+    destroy(): void;
+    #private;
+}
+export type EntityComponentDataset = import("../../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset;
+export type GPUTypedTable = import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+export type GPUGeometryManager = import("../../geometry/GPUGeometryManager.js").GPUGeometryManager;
+export type GPUMaterialManager = import("../../material/GPUMaterialManager.js").GPUMaterialManager;
+export type GPUInstancesAccelerationStructure = import("../GPUInstancesAccelerationStructure.js").GPUInstancesAccelerationStructure;
+export type GPUMeshSkinningContext = import("../../animation/skinning/GPUMeshSkinningContext.js").GPUMeshSkinningContext;
+export type MeshletGeometry = import("../../geometry/MeshletGeometry.js").MeshletGeometry;
+export type ShadeMaterial = import("../../material/ShadeMaterial.js").ShadeMaterial;
+export type AABB3 = import("../../../../core/geom/3d/aabb/AABB3.js").AABB3;
+//# sourceMappingURL=GPUSceneRows.d.ts.map

package/src/shade/renderer/scene/rows/GPUSceneRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUSceneRows.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/scene/rows/GPUSceneRows.js"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,sCAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,mCAHW,MAAM,GACJ,MAAM,CAIlB;AAmID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2II;;;;;;;;;OASG;IACH;QAR2C,OAAO,EAAvC,sBAAsB;QACC,UAAU;QACV,MAAM;QACD,UAAU,EAAtC,kBAAkB;QACU,SAAS,EAArC,kBAAkB;QACyB,IAAI,EAA/C,iCAAiC;QACW,QAAQ,QAAxC,sBAAsB;OAmB5C;IAED;;OAEG;IACH,iGAEC;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;OAOG;IACH,8BAHoB,MAAM,QAAE,eAAe,QAAE,aAAa,QAAE,OAAO,KAAG,IAAI,QASzE;IAED;;;;;;;;;OASG;IACH,6BAHW,KAAK,GACH,OAAO,CAyBnB;IAED;;;;;;;;;;OAUG;IACH,gBAFW,MAAM,QAuChB;IAED;;;;;;;;OAQG;IACH,gBAFW,MAAM,QA0BhB;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,mBAFW,MAAM,QAIhB;IAED;;;;;OAKG;IACH,2EAOC;IAED;;;;OAIG;IACH,gCAEC;IAqCD;;;;;;;;;;;;;;OAcG;IACH,oBALW,MAAM,YACN,eAAe,YACf,aAAa,YACb,OAAO,QA2BjB;IAED;;;;;OAKG;IACH,oBAFW,MAAM,QAUhB;IAsCD;;;;OAIG;IACH,SAFa,MAAM,CAsDlB;IAmMD;;;;OAIG;IACH;;;;;;;;OAQG;IACH,4BAHW,MAAM,kBACG,MAAM,KAAG,IAAI,QAiBhC;IAyGD;;OAEG;IACH,gBA+BC;;CACJ;qCAnmCY,OAAO,kDAAkD,EAAE,sBAAsB;;iCAEjF,OAAO,sCAAsC,EAAE,kBAAkB;iCACjE,OAAO,sCAAsC,EAAE,kBAAkB;gDACjE,OAAO,yCAAyC,EAAE,iCAAiC;qCACnF,OAAO,oDAAoD,EAAE,sBAAsB;8BACnF,OAAO,mCAAmC,EAAE,eAAe;4BAC3D,OAAO,iCAAiC,EAAE,aAAa;oBACvD,OAAO,wCAAwC,EAAE,KAAK"}