@woosh/meep-engine 3.42.0 → 3.44.0

package/src/engine/graphics3/ShadedGeometrySystem.js

@@ -1,309 +1,329 @@
-import { assert } from "../../core/assert.js";
-import { System } from "../ecs/System.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
-import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
-import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
-import { SHADED_GEOMETRY_EVENT_CHANGE } from "../graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.js";
-import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
-import { ShadedGeometryFlags } from "../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
-
-/**
- * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
- * @typedef {import("../../shade/renderer/scene/Scene.js").Scene} Scene
- */
-
-/**
- * One primitive's place in the scene database, and what is listening on its behalf.
- */
-class Entry {
-    /**
-     * @type {number}
-     */
-    entity = -1;
-
-    /**
-     * @type {ShadedGeometry}
-     */
-    geometry = null;
-
-    /**
-     * The GPU context the entity's rows are held in, or null while there is no device — before
-     * the first start, and again after a stop.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    context = null;
-
-    /**
-     * @type {function(): void}
-     */
-    on_world_changed = null;
-
-    /**
-     * @type {function(): void}
-     */
-    on_local_changed = null;
-}
-
-/**
- * Gives one primitive its rows in the scene database, and keeps them where the entity says.
- *
- * **The component and the row are the same shape, which is the whole reason this system is short.**
- * `ShadedGeometry` is a geometry, a material and a flat transform — *"not a hierarchical data
- * structure"*, in its own docblock — and a `meshes` row is a geometry, a material and the
- * `transforms` row it draws under. The entity is both rows, at `entity + 1`: the system
- * `attach_mesh`es it and marks it when the entity moves, and the scene database's flush writes what
- * the CPU owns.
- *
- * **What it is not is a model.** A model file is many primitives arranged in a hierarchy, and in an
- * ECS a hierarchy is entities — one per node, attached to their parents, each carrying its own
- * `ShadedGeometry` where it draws. `MeshSystem` is the layer that spawns a loaded file as those
- * entities (a prefab); this system never sees the file, only the primitives that came out of it,
- * and cannot tell them from primitives some tool built by hand. A primitive a skin deforms says so
- * on its component ({@link ShadedGeometryFlags.Skinned}) and draws a per-instance clone the
- * skinning pass writes; the skin itself is the model's business.
- *
- * **Rows need a device.** A primitive linked before the renderer has started, or after it has been
- * replaced, waits: {@link update} notices the scene's GPU context arriving or changing and attaches
- * everything it holds to it. Nothing about the entity is lost meanwhile — the component and the
- * transform are the truth, and the rows are written from them.
- */
-export class ShadedGeometrySystem extends System {
-    /**
-     * @type {GraphicsEngine}
-     */
-    #graphics;
-
-    /**
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * @type {Map<number, Entry>}
-     */
-    #entries = new Map();
-
-    /**
-     * Shade's GPU state for {@link scene}, as of the last {@link update}. A change means every
-     * row this system held is void and every primitive is attached again.
-     *
-     * @type {GPUSceneContext|null}
-     */
-    #context = null;
-
-    /**
-     * Entries not yet attached to {@link #context} — linked while there was no device, or since a
-     * restart. A queue rather than a scan, because the answer is almost always "nothing to do".
-     *
-     * @type {Entry[]}
-     */
-    #unattached = [];
-
-    /**
-     * @param {GraphicsEngine} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics, scene) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene, 'scene');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
-
-        this.dependencies = [ShadedGeometry, Transform64];
-    }
-
-    /**
-     * @returns {Scene}
-     */
-    get scene() {
-        return this.#scene;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        // the scene's rows are this dataset's entities; the first system to place one says so
-        const dataset = entityManager.dataset;
-        const scene = this.#scene;
-
-        assert.ok(
-            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
-            'the scene is bound to another dataset'
-        );
-
-        scene.dataset = dataset;
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-
-        this.#context = null;
-        this.#unattached.length = 0;
-    }
-
-    /**
-     * Attach what arrived since the last frame, and everything again after a renderer restart.
-     *
-     * @param {number} time_delta_seconds
-     */
-    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. Nothing holds rows while this
-            // holds, and the next context to arrive is a change like any other.
-            return;
-        }
-
-        if (context !== this.#context) {
-            this.#context = context;
-
-            const waiting = this.#unattached;
-
-            waiting.length = 0;
-
-            for (const entry of this.#entries.values()) {
-                entry.context = null;
-
-                waiting.push(entry);
-            }
-        }
-
-        const waiting = this.#unattached;
-
-        for (let i = 0; i < waiting.length; i++) {
-            this.#attach(waiting[i], context);
-        }
-
-        waiting.length = 0;
-    }
-
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    link(geometry, transform, entity) {
-        // the component's own bounds query reads the transform through this
-        geometry.__c_transform = transform;
-        geometry.__entity = entity;
-
-        const entry = new Entry();
-
-        entry.entity = entity;
-        entry.geometry = geometry;
-
-        // Marked when the entity moves rather than placed on a poll: an entity that has not moved
-        // costs nothing, which is the same bargain the scene database makes downstream. A
-        // Transform64 has no signals of its own, so the announcement comes from the dataset. The
-        // world event says the entity's pose moved; the attachment event says its offset from its
-        // parent did — which is what its row holds when the parent has a row of its own.
-        entry.on_world_changed = () => {
-            if (entry.context !== null) {
-                entry.context.rows.mark_world(entity);
-            }
-        };
-
-        entry.on_local_changed = () => {
-            if (entry.context !== null) {
-                entry.context.rows.mark_local(entity);
-            }
-        };
-
-        // The component changed in place — a material swapped, most often — and the row is
-        // rewritten from it. Same geometry, same clone: a skinned primitive fading out keeps the
-        // vertex region the skinning pass is deforming.
-        entry.on_changed = () => {
-            if (entry.context !== null) {
-                this.#attach(entry, entry.context);
-            }
-        };
-
-        const dataset = this.entityManager.dataset;
-
-        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world_changed);
-        dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.on_local_changed);
-        dataset.addEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, entry.on_changed);
-
-        this.#entries.set(entity, entry);
-
-        const context = this.#context;
-
-        if (context !== null && context === this.#graphics.scene_context(this.#scene)) {
-            this.#attach(entry, context);
-        } else {
-            this.#unattached.push(entry);
-        }
-    }
-
-    /**
-     * @param {ShadedGeometry} geometry
-     * @param {Transform64} transform
-     * @param {number} entity
-     */
-    unlink(geometry, transform, entity) {
-        geometry.__c_transform = null;
-        geometry.__entity = -1;
-
-        this.#drop(entity);
-    }
-
-    /**
-     * Give the primitive its rows in a context.
-     *
-     * @param {Entry} entry
-     * @param {GPUSceneContext} context
-     */
-    #attach(entry, context) {
-        const geometry = entry.geometry;
-
-        context.rows.attach_mesh(
-            entry.entity,
-            geometry.geometry,
-            geometry.material,
-            geometry.getFlag(ShadedGeometryFlags.Skinned)
-        );
-
-        entry.context = context;
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        this.#entries.delete(entity);
-
-        const dataset = this.entityManager.dataset;
-
-        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world_changed);
-        dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.on_local_changed);
-        dataset.removeEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, entry.on_changed);
-
-        const waiting = this.#unattached.indexOf(entry);
-
-        if (waiting !== -1) {
-            this.#unattached.splice(waiting, 1);
-        }
-
-        // A context that has been replaced took its rows with it; only the one that is running
-        // is handed anything back.
-        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
-            entry.context.rows.detach_mesh(entity);
-        }
-
-        entry.context = null;
-    }
-}
+import { assert } from "../../core/assert.js";
+import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { SHADED_GEOMETRY_EVENT_CHANGE } from "../graphics/ecs/mesh-v2/SHADED_GEOMETRY_EVENT_CHANGE.js";
+import { ShadedGeometry } from "../graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../graphics/ecs/mesh-v2/ShadedGeometryFlags.js";
+import { RowChains } from "./RowChains.js";
+
+/**
+ * @typedef {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("./GraphicsEngine.js").GraphicsEngine} GraphicsEngine
+ * @typedef {import("../../shade/renderer/scene/Scene.js").Scene} Scene
+ */
+
+/**
+ * One primitive's place in the scene database, and what is listening on its behalf.
+ */
+class Entry {
+    /**
+     * @type {number}
+     */
+    entity = -1;
+
+    /**
+     * @type {ShadedGeometry}
+     */
+    geometry = null;
+
+    /**
+     * The GPU context the entity's rows are held in, or null while there is no device — before
+     * the first start, and again after a stop.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    context = null;
+
+    /**
+     * @type {function(): void}
+     */
+    on_world_changed = null;
+
+    /**
+     * @type {function(): void}
+     */
+    on_changed = null;
+}
+
+/**
+ * Gives one primitive its rows in the scene database, and keeps them where the entity says.
+ *
+ * **The component and the row are the same shape, which is the whole reason this system is short.**
+ * `ShadedGeometry` is a geometry, a material and a flat transform — *"not a hierarchical data
+ * structure"*, in its own docblock — and a `meshes` row is a geometry, a material and the
+ * `transforms` row it draws under. The entity is both rows, at `entity + 1`: the system
+ * `attach_mesh`es it and marks it when the entity moves, and the scene database's flush writes what
+ * the CPU owns.
+ *
+ * **What it is not is a model.** A model file is many primitives arranged in a hierarchy, and in an
+ * ECS a hierarchy is entities — one per node, attached to their parents, each carrying its own
+ * `ShadedGeometry` where it draws. `MeshSystem` is the layer that spawns a loaded file as those
+ * entities (a prefab); this system never sees the file, only the primitives that came out of it,
+ * and cannot tell them from primitives some tool built by hand. A primitive a skin deforms says so
+ * on its component ({@link ShadedGeometryFlags.Skinned}) and draws a per-instance clone the
+ * skinning pass writes; the skin itself is the model's business.
+ *
+ * **A primitive holds the rows of everything it hangs from** ({@link RowChains}). Under a parent
+ * with no row it would carry its CPU world under the scene root, which stops moving the moment a
+ * clip drives a node above it — a rigid head under an animated tag is the common case. Holding the
+ * chain lets the GPU compose it from the top, and holds the tag's row, without which the clip never
+ * binds.
+ *
+ * **Rows need a device.** A primitive linked before the renderer has started, or after it has been
+ * replaced, waits: {@link update} notices the scene's GPU context arriving or changing and attaches
+ * everything it holds to it. Nothing about the entity is lost meanwhile — the component and the
+ * transform are the truth, and the rows are written from them.
+ */
+export class ShadedGeometrySystem extends System {
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {Map<number, Entry>}
+     */
+    #entries = new Map();
+
+    /**
+     * Shade's GPU state for {@link scene}, as of the last {@link update}. A change means every
+     * row this system held is void and every primitive is attached again.
+     *
+     * @type {GPUSceneContext|null}
+     */
+    #context = null;
+
+    /**
+     * Entries not yet attached to {@link #context} — linked while there was no device, or since a
+     * restart. A queue rather than a scan, because the answer is almost always "nothing to do".
+     *
+     * @type {Entry[]}
+     */
+    #unattached = [];
+
+    /**
+     * Each primitive's chain: its own row and the rows of the entities above it, followed as they
+     * move. Null until the system has a dataset.
+     *
+     * @type {RowChains|null}
+     */
+    #chains = null;
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+
+        this.dependencies = [ShadedGeometry, Transform64];
+    }
+
+    /**
+     * @returns {Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        this.#chains = new RowChains(dataset);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+
+        this.#chains.destroy();
+        this.#chains = null;
+
+        this.#context = null;
+        this.#unattached.length = 0;
+    }
+
+    /**
+     * Attach what arrived since the last frame, and everything again after a renderer restart.
+     *
+     * @param {number} time_delta_seconds
+     */
+    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. Nothing holds rows while this
+            // holds, and the next context to arrive is a change like any other.
+            this.#chains.bind(null);
+
+            return;
+        }
+
+        if (context !== this.#context) {
+            this.#context = context;
+
+            // the chains first, so that a primitive attached below finds its parents' rows there
+            this.#chains.bind(context.rows);
+
+            const waiting = this.#unattached;
+
+            waiting.length = 0;
+
+            for (const entry of this.#entries.values()) {
+                entry.context = null;
+
+                waiting.push(entry);
+            }
+        }
+
+        const waiting = this.#unattached;
+
+        for (let i = 0; i < waiting.length; i++) {
+            this.#attach(waiting[i], context);
+        }
+
+        waiting.length = 0;
+    }
+
+    /**
+     * @param {ShadedGeometry} geometry
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(geometry, transform, entity) {
+        // the component's own bounds query reads the transform through this
+        geometry.__c_transform = transform;
+        geometry.__entity = entity;
+
+        const entry = new Entry();
+
+        entry.entity = entity;
+        entry.geometry = geometry;
+
+        // Marked when the entity moves rather than placed on a poll: an entity that has not moved
+        // costs nothing, which is the same bargain the scene database makes downstream. A
+        // Transform64 has no signals of its own, so the announcement comes from the dataset. The
+        // world event says the entity's pose moved, which for a primitive composed under a parent's
+        // row is its place in the scene's tree; its offset from the parent is the chain's to follow.
+        entry.on_world_changed = () => {
+            if (entry.context !== null) {
+                entry.context.rows.mark_world(entity);
+            }
+        };
+
+        // The component changed in place — a material swapped, most often — and the row is
+        // rewritten from it. Same geometry, same clone: a skinned primitive fading out keeps the
+        // vertex region the skinning pass is deforming.
+        entry.on_changed = () => {
+            if (entry.context !== null) {
+                this.#attach(entry, entry.context);
+            }
+        };
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world_changed);
+        dataset.addEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, entry.on_changed);
+
+        this.#entries.set(entity, entry);
+
+        this.#chains.hold(entity);
+
+        const context = this.#context;
+
+        if (context !== null && context === this.#graphics.scene_context(this.#scene)) {
+            this.#attach(entry, context);
+        } else {
+            this.#unattached.push(entry);
+        }
+    }
+
+    /**
+     * @param {ShadedGeometry} geometry
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(geometry, transform, entity) {
+        geometry.__c_transform = null;
+        geometry.__entity = -1;
+
+        this.#drop(entity);
+    }
+
+    /**
+     * Give the primitive its rows in a context.
+     *
+     * @param {Entry} entry
+     * @param {GPUSceneContext} context
+     */
+    #attach(entry, context) {
+        const geometry = entry.geometry;
+
+        context.rows.attach_mesh(
+            entry.entity,
+            geometry.geometry,
+            geometry.material,
+            geometry.getFlag(ShadedGeometryFlags.Skinned)
+        );
+
+        entry.context = context;
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#entries.delete(entity);
+
+        const dataset = this.entityManager.dataset;
+
+        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.on_world_changed);
+        dataset.removeEntityEventListener(entity, SHADED_GEOMETRY_EVENT_CHANGE, entry.on_changed);
+
+        const waiting = this.#unattached.indexOf(entry);
+
+        if (waiting !== -1) {
+            this.#unattached.splice(waiting, 1);
+        }
+
+        // A context that has been replaced took its rows with it; only the one that is running
+        // is handed anything back.
+        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
+            entry.context.rows.detach_mesh(entity);
+        }
+
+        entry.context = null;
+
+        this.#chains.release(entity);
+    }
+}