@woosh/meep-engine 3.68.0 → 3.69.0

package/src/engine/graphics3/Trail3DSystem.js

@@ -1,118 +1,250 @@
 import { assert } from "../../core/assert.js";
-import { DynamicMeshAVBOITChannel } from "../../shade/renderer/dynamic/DynamicMeshAVBOITChannel.js";
 import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { Geometry } from "../../shade/renderer/geometry/Geometry.js";
-import { DynamicMesh } from "../../shade/renderer/scene/DynamicMesh.js";
-import { DynamicMeshBatch } from "../../shade/renderer/scene/DynamicMeshBatch.js";
+import { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
+import { graph_import_buffer } from "../../shade/renderer/shader/graph/graph_import_buffer.js";
+import { GPUTrailAVBOITChannel } from "../../shade/renderer/trails/GPUTrailAVBOITChannel.js";
+import { GPUTrailSystem } from "../../shade/renderer/trails/GPUTrailSystem.js";
+import { TrailParameters } from "../../shade/renderer/trails/runtime/TrailParameters.js";
 import { System } from "../ecs/System.js";
 import { Transform64 } from "../ecs/transform/Transform64.js";
-import { advance_trail } from "../graphics/ecs/trail3d/advance_trail.js";
-import { seed_trail_tube } from "../graphics/ecs/trail3d/seed_trail_tube.js";
+import { trail_knot_count } from "../graphics/ecs/trail3d/trail_knot_count.js";
 import Trail3D from "../graphics/ecs/trail3d/Trail3D.js";
 import { Trail3DFlags } from "../graphics/ecs/trail3d/Trail3DFlags.js";
-import {
-    TubeXFixedPhysicsSimulator
-} from "../graphics/trail/tube/simulator/TubeXFixedPhysicsSimulator.js";
-import { trail_tube_write_geometry } from "./trail/trail_tube_write_geometry.js";
+import { TrailSpawnMode } from "../graphics/trail/TrailSpawnMode.js";
+import { EntityRowHold } from "./EntityRowHold.js";
 
 /**
- * Draws {@link Trail3D}'s tubes under Shade, as dynamic geometry inside the transparency pipeline.
+ * @typedef {Object} Trail3DEntry
+ * @property {number} entity
+ * @property {Trail3D} trail
+ * @property {EntityRowHold} hold the entity's row, kept current as it moves
+ * @property {import("../../shade/renderer/trails/GPUTrailSystem.js").GPUTrailContext|null} context the
+ *   trail in the runtime, or null while it is not registered
+ * @property {number} knot_count knots of the trail's ring, fixed when it is built
+ * @property {number} radial radial segments, fixed when it is built
+ * @property {number} clears the component's `clearCount` as last seen
+ */
+
+/**
+ * Knots a trail is built with: its authored layout's, or as many as its maxAge lays down.
  *
- * **A trail is dynamic content by definition** — every knot of it is rewritten as the entity moves
- * and every knot's opacity as it ages — so its geometry is a {@link DynamicMesh} (D5/I-10), not a
- * meshlet build, the same as paths and debug shapes.
+ * @param {Trail3D} trail
+ * @returns {number}
+ */
+function knot_count_of(trail) {
+    return trail.knots !== null ? trail.knots.count : trail_knot_count(trail.maxAge);
+}
+
+/**
+ * Copy a component onto runtime parameters.
  *
- * **It is drawn through AVBOIT, not over it.** The batch is a transparency channel
- * ({@link DynamicMeshAVBOITChannel}, registered with the facade): its fragments go into the same
- * extinction volume and accumulators as the transparent meshes and the GPU particles, so a trail
- * behind glass is seen through the glass, a trail inside smoke is hidden by the smoke in front of it
- * and hides the smoke behind it, and two trails crossing composite by depth, not by the order they
- * were linked in. Everything drawn at `AfterTransparency` runs after the transparency resolve they
- * are part of, so path display and the selection highlight land over a trail rather than under it.
- * Under MBOIT, the legacy transparency mode, trails are not drawn — as the particles are not.
+ * @param {TrailParameters} parameters
+ * @param {Trail3D} trail
+ * @param {Trail3DEntry} entry
+ */
+export function apply_trail3d(parameters, trail, entry) {
+    const knots = trail.knots;
+
+    parameters.knot_count = entry.knot_count;
+    parameters.radial = entry.radial;
+    parameters.max_age = trail.maxAge;
+    parameters.width = trail.width;
+    parameters.distance_mode = trail.spawnMode === TrailSpawnMode.Distance;
+    parameters.spawn_distance = trail.spawnDistance;
+    parameters.spawning = trail.getFlag(Trail3DFlags.Spawning);
+    parameters.warmup = trail.warmup;
+
+    const color = trail.color;
+
+    parameters.color[0] = color.x;
+    parameters.color[1] = color.y;
+    parameters.color[2] = color.z;
+    parameters.color[3] = color.w;
+
+    const offset = trail.offset;
+
+    parameters.offset[0] = offset.x;
+    parameters.offset[1] = offset.y;
+    parameters.offset[2] = offset.z;
+
+    parameters.fade = trail.fade;
+    parameters.authored = knots;
+    parameters.authored_version = knots === null ? -1 : knots.version;
+}
+
+/**
+ * Records the trails' simulation into the frame, once the hierarchy has composed this frame's matrices
+ * and before the transparency pipeline draws.
+ */
+class Trail3DFrameExtension extends RenderExtension {
+    name = "trails";
+
+    phase = FramePhase.AfterLighting;
+
+    /**
+     * @type {Trail3DSystem}
+     */
+    #system;
+
+    /**
+     * @param {Trail3DSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}
+
+/**
+ * Draws every {@link Trail3D}: simulated on the GPU, its head following the entity's `transforms` row,
+ * its knots seeded and committed in compute and its tube extruded in the vertex stage, drawn inside the
+ * transparency pipeline (AVBOIT), so a trail behind glass or smoke composites with them by depth.
+ * Nothing per knot happens on the CPU.
  *
- * **The simulation is not this system's, and that is deliberate.** {@link seed_trail_tube} and
- * {@link advance_trail} are what the legacy `Trail3DSystem` runs too: the knots a trail lays down
- * are a property of the trail, not of the renderer drawing it, and two implementations of them
- * would be two trails that age differently. What is this system's is turning those knots into
- * vertices, once a frame, per trail.
+ * **What is the CPU's:** registering a trail with the scene context's {@link GPUTrailSystem} — a row, a
+ * knot run, the entity's transform row held through {@link EntityRowHold} — comparing each component's
+ * fields once a tick with what was staged and restaging what differs, and moving the clock by the
+ * simulation time it is given. A game writes `trail.color` or `trail.maxAge` from code that never heard
+ * of this system; there is no change signal to send.
  *
- * **Every trail is rewritten every frame it exists**, moving or not, because the simulator ages
- * every knot on every tick and the age is what the vertex opacity carries. There is no quiet trail
- * — a trail that has stopped is a trail fading out.
+ * **The head follows announced transforms.** A trail reads where its entity is from the GPU row, which a
+ * transform write reaches when it is announced (`TRANSFORM64_EVENT_CHANGE`), as meshes and particle
+ * emitters do.
  *
- * **What the tube material had and this does not**: a texture, lighting, and per-trail depth
- * writing. The dynamic path has one vertex layout — position and colour — and a trail is drawn as
- * unlit straight alpha, depth tested against the opaque scene and never written, which is what a
- * trail wants and what the game's trails are authored as. `Trail3D.textureURL` therefore draws
- * untinted here; nothing in the game's own effects sets it to anything a flat colour does not
- * carry.
+ * A trail's knot count (from its `maxAge`, or its authored layout's) and its `radialSegments` are fixed
+ * when it registers; a replaced authored layout brings its own count.
  */
 export class Trail3DSystem extends System {
     dependencies = [Trail3D, Transform64];
 
     /**
-     * @type {GraphicsEngine}
+     * @type {import("./GraphicsEngine.js").GraphicsEngine}
      */
     #graphics;
 
     /**
-     * @type {DynamicMeshBatch}
+     * @type {import("../../shade/renderer/scene/Scene.js").Scene}
      */
-    #batch = new DynamicMeshBatch();
+    #scene;
 
     /**
-     * The batch as the transparency pipeline sees it, and the owner of its GPU buffers.
-     *
-     * @type {DynamicMeshAVBOITChannel}
+     * @type {import("../ecs/EntityComponentDataset.js").EntityComponentDataset|null}
      */
-    #channel = new DynamicMeshAVBOITChannel(this.#batch);
+    #dataset = null;
 
     /**
-     * @type {Map<number, {trail: Trail3D, transform: Transform, mesh: DynamicMesh}>}
+     * @type {Map<number, Trail3DEntry>}
      */
     #entries = new Map();
 
     /**
-     * @type {TubeXFixedPhysicsSimulator}
+     * @type {GPUTrailSystem|null}
      */
-    #simulator = new TubeXFixedPhysicsSimulator();
+    #runtime = null;
 
     /**
-     * What the transparency channel draws. Read-only — the meshes follow the entities.
-     *
-     * @returns {DynamicMeshBatch}
+     * The scene context {@link #runtime} was made for.
+     * @type {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null}
      */
-    get batch() {
-        return this.#batch;
-    }
+    #runtime_context = null;
+
+    /**
+     * @type {Trail3DFrameExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * @type {TrailParameters}
+     */
+    #scratch = new TrailParameters();
 
     /**
-     * @param {GraphicsEngine} graphics
+     * What draws the trails, inside the transparency pipeline.
+     * @type {GPUTrailAVBOITChannel}
      */
-    constructor(graphics) {
+    #channel = new GPUTrailAVBOITChannel();
+
+    /**
+     * @type {function(): (import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null)}
+     */
+    #current_context = () => this.#graphics.scene_context(this.#scene);
+
+    /**
+     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene the scene the trails' entities are in
+     */
+    constructor(graphics, scene) {
         super();
 
         assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
 
         this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    /**
+     * The runtime the scene's trails are registered with, or null while there is no scene context.
+     *
+     * @returns {GPUTrailSystem|null}
+     */
+    get runtime() {
+        return this.#runtime;
     }
 
     async startup(entityManager) {
         this.entityManager = entityManager;
 
+        this.#extension = new Trail3DFrameExtension(this);
+
+        this.#graphics.add_extension(this.#extension);
         this.#graphics.add_transparency_channel(this.#channel);
     }
 
     async shutdown(entityManager) {
-        // says whether it was there, so a shutdown after a startup that never ran is harmless
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+            this.#extension = null;
+        }
+
         this.#graphics.remove_transparency_channel(this.#channel);
+        this.#channel.end_frame();
+
+        this.#detach_dataset();
+        this.#destroy_runtime();
+    }
+
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     */
+    handleDatasetAttached(dataset) {
+        this.#detach_dataset();
 
-        this.#channel.destroy();
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const scene = this.#scene;
 
-        this.#batch.clear();
-        this.#entries.clear();
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        this.#dataset = dataset;
+    }
+
+    /**
+     * @param {import("../ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+     */
+    handleDatasetDetached(dataset) {
+        this.#detach_dataset();
     }
 
     /**
@@ -121,56 +253,223 @@ export class Trail3DSystem extends System {
      * @param {number} entity
      */
     link(trail, transform, entity) {
-        if (!trail.getFlag(Trail3DFlags.Built)) {
-            seed_trail_tube(trail, transform);
+        /** @type {Trail3DEntry} */
+        const entry = {
+            entity,
+            trail,
+            hold: new EntityRowHold(this.#dataset, entity, this.#current_context),
+            context: null,
+            knot_count: 0,
+            radial: 0,
+            clears: trail.clearCount,
+        };
+
+        this.#entries.set(entity, entry);
+
+        // registered now when there is a context, so a trail added mid-level is seeded where its entity
+        // stands from its first frame
+        if (this.#ensure_runtime() !== null) {
+            this.#register(entry);
+        }
+    }
+
+    /**
+     * @param {Trail3D} trail
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(trail, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * Move the clock by the simulation time given, register what is waiting, and restage every trail
+     * whose component changed.
+     *
+     * @param {number} [time_delta_seconds]
+     */
+    update(time_delta_seconds = 0) {
+        const runtime = this.#ensure_runtime();
+
+        if (runtime === null) {
+            return;
+        }
+
+        runtime.advance(time_delta_seconds);
+
+        for (const entry of this.#entries.values()) {
+            this.#sync(runtime, entry);
+        }
+    }
+
+    /**
+     * Record the frame's trail work — called by the frame extension.
+     *
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     */
+    record(frame) {
+        // whatever the last frame left is not this frame's: a frame that records nothing draws nothing
+        this.#channel.end_frame();
+
+        if (frame.view.scene.scene !== this.#scene) {
+            return;
+        }
+
+        const runtime = this.#ensure_runtime();
+
+        if (runtime === null) {
+            return;
         }
 
-        // the extrusion produces world-space vertices, and what the draw applies is the mesh's own
-        // transform, identity until moved
-        const mesh = DynamicMesh.from(new Geometry());
+        for (const entry of this.#entries.values()) {
+            this.#sync(runtime, entry);
+        }
 
-        trail_tube_write_geometry(mesh.geometry, trail.tube);
+        // Read the way the velocity pass and the particles read it: the hierarchy is encoded ahead of
+        // the frame's graph, so the matrices in it are this frame's.
+        const scene_database = graph_import_buffer(frame.graph, frame.view.scene.scene_database_buffer, "scene_database/trails");
 
-        this.#batch.add(mesh);
+        const simulation = runtime.record_simulation(frame.graph, scene_database);
 
-        this.#entries.set(entity, { trail, transform, mesh });
+        this.#channel.begin_frame(frame.graph, frame.view, runtime, simulation);
+    }
+
+    /**
+     * @param {GPUTrailSystem} runtime
+     * @param {Trail3DEntry} entry
+     */
+    #sync(runtime, entry) {
+        const context = entry.context;
+
+        if (context === null) {
+            this.#register(entry);
+            return;
+        }
+
+        const trail = entry.trail;
+
+        // a build-time change: an authored layout replaced, or one added or taken away
+        const knots = trail.knots;
+
+        if (knots !== context.staged.authored
+            || (knots !== null && knots.version !== context.staged.authored_version)) {
+            entry.knot_count = knot_count_of(trail);
+        }
+
+        const scratch = this.#scratch;
+
+        apply_trail3d(scratch, trail, entry);
+
+        if (!scratch.equals(context.staged)) {
+            runtime.stage(context, scratch);
+        }
+
+        if (entry.clears !== trail.clearCount) {
+            entry.clears = trail.clearCount;
+            runtime.clear(context);
+        }
+    }
+
+    /**
+     * @param {Trail3DEntry} entry
+     */
+    #register(entry) {
+        const runtime = this.#runtime;
+        const trail = entry.trail;
+
+        entry.knot_count = knot_count_of(trail);
+        entry.radial = trail.radialSegments;
+        entry.clears = trail.clearCount;
+
+        entry.hold.acquire(this.#runtime_context);
+
+        const scratch = this.#scratch;
+
+        apply_trail3d(scratch, trail, entry);
+
+        const context = runtime.add(scratch, row_of_entity(entry.entity));
+
+        if (context === null) {
+            // the knot pool cannot grow to house it on this device
+            entry.hold.release();
+            return;
+        }
+
+        entry.context = context;
     }
 
     /**
-     * @param {Trail3D} trail
-     * @param {Transform64} transform
      * @param {number} entity
      */
-    unlink(trail, transform, entity) {
+    #drop(entity) {
         const entry = this.#entries.get(entity);
 
         if (entry === undefined) {
             return;
         }
 
-        this.#batch.remove(entry.mesh);
+        if (entry.context !== null && this.#runtime !== null) {
+            this.#runtime.remove(entry.context);
+        }
 
-        // residency deliberately survives leaving the batch, so nothing else would free it
-        this.#channel.release(entry.mesh.geometry);
+        entry.context = null;
+        entry.hold.dispose();
 
         this.#entries.delete(entity);
+    }
+
+    /**
+     * The runtime for the scene context the scene renders through now, made fresh when that context is
+     * new: a device restart builds a new one, and every trail registers again and is seeded anew.
+     *
+     * @returns {GPUTrailSystem|null}
+     */
+    #ensure_runtime() {
+        const context = this.#current_context();
+
+        if (context === this.#runtime_context) {
+            return this.#runtime;
+        }
+
+        this.#destroy_runtime();
+
+        if (context === null) {
+            return null;
+        }
+
+        this.#runtime = new GPUTrailSystem(context.graphics);
+        this.#runtime_context = context;
 
-        trail.dispose();
+        return this.#runtime;
     }
 
-    update(timeDelta) {
+    #destroy_runtime() {
         for (const entry of this.#entries.values()) {
-            const trail = entry.trail;
+            // the trails and rows went with the context that held them
+            entry.context = null;
+            entry.hold.release();
+        }
 
-            advance_trail(trail, entry.transform, timeDelta, this.#simulator);
+        if (this.#runtime !== null) {
+            this.#runtime.destroy();
+        }
 
-            // The component's own bounds serve CPU culling, which this path does not do (§4.5), and
-            // the depth range the transparency pipeline needs the channel reads off the written
-            // geometry — so the flag the head raises has nobody else to answer it.
-            trail.clearFlag(Trail3DFlags.BoundsNeedUpdate);
+        this.#runtime = null;
+        this.#runtime_context = null;
+    }
 
-            trail_tube_write_geometry(entry.mesh.geometry, trail.tube);
+    #detach_dataset() {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
         }
+
+        const dataset = this.#dataset;
+
+        if (dataset !== null && this.#scene.dataset === dataset) {
+            this.#scene.dataset = null;
+        }
+
+        this.#dataset = null;
     }
 }
 

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts

@@ -38,6 +38,22 @@ export class FluidObstacle {
      * @type {number}
      */
     inflation: number;
+    /**
+     * How the obstacle stops the wind, 1/m. `0` (default): it is **solid**, and the air takes its
+     * velocity wherever it is. Above `0`: it is **porous**, the air passes through it and is slowed
+     * toward its velocity by `drag · |u − v| · (u − v)` each second, `u` the air's velocity and `v`
+     * the obstacle's.
+     *
+     * For something made of leaves or blades it is their drag coefficient times their one-sided area
+     * per cubic metre of the volume: a canopy of grass, a crop, the crown of a tree, a hedge. Their drag
+     * is spread through the volume, which is what makes the wind slow inside and fast above, and the
+     * shear at its top roll up into the gusts that run over a field.
+     *
+     * Only the GPU fluid has porous obstacles; the CPU fluid leaves them out.
+     *
+     * @type {number}
+     */
+    drag: number;
     /**
      * True when the previous tick stamped a non-zero wall velocity. A body
      * that stops (or sleeps — the solver zeroes velocities on sleep) must
@@ -58,6 +74,7 @@ export class FluidObstacle {
     hash(): number;
     toJSON(): {
         inflation: number;
+        drag: number;
     };
     fromJSON(json: any): void;
     /**

package/src/engine/physics/fluid/ecs/FluidObstacle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidObstacle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacle.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAEI;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,aAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,cAHW,aAAa,GACZ,OAAO,CAUlB;IAED;;OAEG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED,0BAEC;IASL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CAZtC;;kBAIS,MAAM"}
+{"version":3,"file":"FluidObstacle.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidObstacle.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAEI;;;;;;;;;;;;OAYG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;OAcG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;OAOG;IACH,aAFU,OAAO,CAEG;IAEpB;;;OAGG;IACH,cAHW,aAAa,GACZ,OAAO,CAUlB;IAED;;OAEG;IACH,QAFY,MAAM,CAIjB;IAED;;;MAKC;IAED,0BAGC;IASL;;;OAGG;IACH,0BAFU,OAAO,CAEsB;CAZtC;;kBAIS,MAAM"}

package/src/engine/physics/fluid/ecs/FluidObstacle.js

@@ -1,3 +1,4 @@
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
 
 /**
@@ -42,6 +43,23 @@ export class FluidObstacle {
      */
     inflation = 0;
 
+    /**
+     * How the obstacle stops the wind, 1/m. `0` (default): it is **solid**, and the air takes its
+     * velocity wherever it is. Above `0`: it is **porous**, the air passes through it and is slowed
+     * toward its velocity by `drag · |u − v| · (u − v)` each second, `u` the air's velocity and `v`
+     * the obstacle's.
+     *
+     * For something made of leaves or blades it is their drag coefficient times their one-sided area
+     * per cubic metre of the volume: a canopy of grass, a crop, the crown of a tree, a hedge. Their drag
+     * is spread through the volume, which is what makes the wind slow inside and fast above, and the
+     * shear at its top roll up into the gusts that run over a field.
+     *
+     * Only the GPU fluid has porous obstacles; the CPU fluid leaves them out.
+     *
+     * @type {number}
+     */
+    drag = 0;
+
     /**
      * True when the previous tick stamped a non-zero wall velocity. A body
      * that stops (or sleeps — the solver zeroes velocities on sleep) must
@@ -63,24 +81,26 @@ export class FluidObstacle {
         if (other === null || other === undefined || other.isFluidObstacle !== true) {
             return false;
         }
-        return this.inflation === other.inflation;
+        return this.inflation === other.inflation && this.drag === other.drag;
     }
 
     /**
      * @return {number}
      */
     hash() {
-        return computeHashFloat(this.inflation);
+        return hash_mix2(computeHashFloat(this.inflation), computeHashFloat(this.drag));
     }
 
     toJSON() {
         return {
             inflation: this.inflation,
+            drag: this.drag,
         };
     }
 
     fromJSON(json) {
         if (json.inflation !== undefined) this.inflation = json.inflation;
+        this.drag = json.drag ?? 0;
     }
 }