@woosh/meep-engine 3.68.0 → 3.69.0

package/src/shade/renderer/trails/GPUTrailSystem.js

@@ -0,0 +1,725 @@
+import { assert } from "../../../core/assert.js";
+import { ALLOCATOR_NO_SPACE } from "../../../core/binary/allocator/OffsetAllocator.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { TRAIL_KNOT_WORDS, TRAIL_TICKS_PER_SECOND, trail_knot_write } from "./data/TRAIL_KNOT.js";
+import { TRAIL_DATABASE_INITIAL_SIZE, TRAIL_DATABASE_SPEC, TRAIL_STATE_TABLE, TRAIL_TABLE } from "./data/TRAIL_DATABASE_SPEC.js";
+import { TRAIL_FLAG } from "./data/TRAIL_RECORD.js";
+import { TRAIL_STATE_UNSEEDED } from "./data/TRAIL_STATE.js";
+import { TrailFadeCurves } from "./runtime/TrailFadeCurves.js";
+import { TrailKnotPool } from "./runtime/TrailKnotPool.js";
+import { TrailParameters } from "./runtime/TrailParameters.js";
+import { graph_trails_simulate } from "./graph_trails.js";
+import { TRAIL_FRAME_STRUCT } from "./shaders/chunk_trail_vertex.js";
+
+/**
+ * Ticks past which an age is no longer exact: half the u32 range, so `max_age + a frame` stays under the
+ * wrap with room for the frame.
+ * @type {number}
+ */
+const TICK_AGE_LIMIT = 2 ** 31;
+
+/**
+ * Scratch for an authored knot's frame and position.
+ * @type {Float64Array}
+ */
+const scratch_frame = new Float64Array(6);
+const scratch_position = new Float64Array(3);
+
+/**
+ * Everything the runtime holds for one trail. Plain bookkeeping: the trail's look is its
+ * {@link TrailParameters}, which the owner keeps.
+ */
+export class GPUTrailContext {
+    /** @type {number} row in the trail and state tables */
+    row = -1;
+
+    /** @type {number} the `transforms` row the head follows */
+    node = 0;
+
+    /** @type {import("../../../core/binary/allocator/OffsetAllocator.js").Allocation|null} the knot run */
+    knots = null;
+
+    /** @type {import("./runtime/TrailFadeCurves.js").TrailFadeCurve|null} */
+    fade = null;
+
+    /** @type {number} index of the trail's radial class */
+    draw_class = -1;
+
+    /** @type {number} what the record's `seed_epoch` says */
+    epoch = 1;
+
+    /** @type {boolean} the pending seed is a `clear()`, which keeps the trail's birth and frames */
+    reseed = false;
+
+    /** @type {TrailParameters} what was last staged */
+    staged = new TrailParameters();
+}
+
+/**
+ * A radial count in use, and the trails using it: a draw class, one indexed draw per pass.
+ */
+export class TrailDrawClass {
+    /** @type {number} */
+    radial = 0;
+
+    /** @type {number} trails in the class */
+    references = 0;
+
+    /** @type {number} the most segments the class's trails can show: their knots less one each */
+    segments = 0;
+}
+
+/**
+ * The frame uniform the trails' vertex stage reads: the clock, in ticks.
+ * @type {number}
+ */
+const FRAME_UNIFORM_BYTES = TRAIL_FRAME_STRUCT.size;
+
+/**
+ * The GPU trails of one scene context: the trail and state tables, the knot pool, the fade curves, and
+ * the clock the knots are aged by.
+ *
+ * **The CPU registers and stages; the GPU simulates.** {@link add} claims a row, a run of knots and the
+ * trail's fade curve and radial class, and asks for a seed; {@link stage} writes the record when the
+ * trail's parameters change; {@link remove} lets everything go. No knot is written on the CPU, except
+ * the knots of an authored trail, which are uploaded once when it is added. Everything per frame — the
+ * head, commits, aging — is the GPU's.
+ *
+ * **Time is the owner's.** {@link advance} moves the clock by the simulation time the owner was given,
+ * so a paused game holds its trails still, and the knots age by ticks of it (`TRAIL_TICKS_PER_SECOND`).
+ */
+export class GPUTrailSystem {
+    /**
+     * @type {import("../GraphicsContext.js").GraphicsContext}
+     */
+    #graphics;
+
+    /**
+     * @type {GPUDatabase}
+     */
+    #database;
+
+    /**
+     * @type {TrailKnotPool}
+     */
+    #knots;
+
+    /**
+     * @type {TrailFadeCurves}
+     */
+    #fades;
+
+    /**
+     * @type {Map<number, GPUTrailContext>} by row
+     */
+    #trails = new Map();
+
+    /**
+     * Radial classes by radial count.
+     * @type {Map<number, TrailDrawClass>}
+     */
+    #classes_by_radial = new Map();
+
+    /**
+     * Radial classes by index; a hole is a class no trail uses, free to be handed out again.
+     * @type {(TrailDrawClass|undefined)[]}
+     */
+    #classes = [];
+
+    /**
+     * Trails the GPU is to seed in the next frame recorded.
+     * @type {GPUTrailContext[]}
+     */
+    #seeds = [];
+
+    /**
+     * A static index buffer per radial count: the triangles of one segment, two rings of `radial + 1`
+     * vertices.
+     * @type {Map<number, GPUBuffer>}
+     */
+    #index_buffers = new Map();
+
+    /**
+     * The clock as the vertex stage reads it, written once a frame.
+     * @type {GPUBuffer}
+     */
+    #frame_uniform;
+
+    /**
+     * @type {Uint32Array}
+     */
+    #frame_words = new Uint32Array(FRAME_UNIFORM_BYTES / 4);
+
+    /**
+     * Seconds of simulation time the clock has been advanced by. A double, so the tick count taken from
+     * it does not drift however long the game runs.
+     * @type {number}
+     */
+    #time = 0;
+
+    /**
+     * @type {Object}
+     */
+    #record = {
+        node: 0,
+        knot_base: 0,
+        knot_count: 0,
+        radial: 0,
+        flags: 0,
+        seed_epoch: 0,
+        commit_ticks: 0,
+        max_age_ticks: 0,
+        max_age: 0,
+        width: 0,
+        spawn_distance: 0,
+        fade_first: 0,
+        fade_count: 0,
+        draw_class: 0,
+        offset: new Float32Array(3),
+        color: new Float32Array(4),
+    };
+
+    /**
+     * @param {import("../GraphicsContext.js").GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        assert.defined(graphics, 'graphics');
+
+        const device = graphics.device;
+
+        this.#graphics = graphics;
+        this.#database = new GPUDatabase({
+            device,
+            definition: TRAIL_DATABASE_SPEC,
+            label: "Trails",
+            initial_data_size_bytes: TRAIL_DATABASE_INITIAL_SIZE,
+        });
+        this.#knots = new TrailKnotPool(device);
+        this.#fades = new TrailFadeCurves(device);
+        this.#frame_uniform = device.createBuffer({
+            label: "Trails / frame",
+            size: FRAME_UNIFORM_BYTES,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /** @returns {import("../GraphicsContext.js").GraphicsContext} */
+    get graphics() {
+        return this.#graphics;
+    }
+
+    /** @returns {GPUBuffer} the clock as the vertex stage reads it */
+    get frame_uniform() {
+        return this.#frame_uniform;
+    }
+
+    /**
+     * The draw classes by index, a hole where no trail uses one.
+     * @returns {(TrailDrawClass|undefined)[]}
+     */
+    get draw_classes() {
+        return this.#classes;
+    }
+
+    /**
+     * The triangles of one segment of a tube of `radial` segments: two rings of `radial + 1` vertices,
+     * the head-ward ring first. Both faces are drawn, so the winding carries nothing.
+     *
+     * @param {number} radial
+     * @returns {GPUBuffer} `uint32` indices, `6 × radial` of them
+     */
+    index_buffer(radial) {
+        let buffer = this.#index_buffers.get(radial);
+
+        if (buffer !== undefined) {
+            return buffer;
+        }
+
+        const indices = new Uint32Array(radial * 6);
+        const ring = radial + 1;
+
+        for (let r = 0; r < radial; r++) {
+            const a = r;
+            const b = ring + r;
+            const c = ring + r + 1;
+            const d = r + 1;
+
+            indices.set([a, b, d, b, c, d], r * 6);
+        }
+
+        const device = this.#graphics.device;
+
+        buffer = device.createBuffer({
+            label: `Trails / indices / ${radial}`,
+            size: indices.byteLength,
+            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
+        });
+
+        device.queue.writeBuffer(buffer, 0, indices.buffer, 0, indices.byteLength);
+
+        this.#index_buffers.set(radial, buffer);
+
+        return buffer;
+    }
+
+    /** @returns {GPUDatabase} the trail and state tables */
+    get database() {
+        return this.#database;
+    }
+
+    /** @returns {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    get table() {
+        return this.#database.get(TRAIL_TABLE);
+    }
+
+    /** @returns {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    get state_table() {
+        return this.#database.get(TRAIL_STATE_TABLE);
+    }
+
+    /** @returns {TrailKnotPool} */
+    get knots() {
+        return this.#knots;
+    }
+
+    /** @returns {TrailFadeCurves} */
+    get fades() {
+        return this.#fades;
+    }
+
+    /** @returns {number} trails registered */
+    get count() {
+        return this.#trails.size;
+    }
+
+    /**
+     * @returns {number} the clock, in ticks, wrapped to a u32
+     */
+    get now() {
+        return Math.floor(this.#time * TRAIL_TICKS_PER_SECOND) >>> 0;
+    }
+
+    /**
+     * Radial counts by class index, a hole where no trail uses one.
+     * @returns {(number|undefined)[]}
+     */
+    get class_radials() {
+        return this.#classes.map(c => c === undefined ? undefined : c.radial);
+    }
+
+    /**
+     * @returns {GPUTrailContext[]} trails waiting for the GPU to seed them; taken by the frame that seeds them
+     */
+    get pending_seeds() {
+        return this.#seeds;
+    }
+
+    /**
+     * Move the clock on.
+     *
+     * @param {number} seconds simulation time since the last call
+     */
+    advance(seconds) {
+        assert.greaterThanOrEqual(seconds, 0, 'seconds');
+
+        this.#time += seconds;
+    }
+
+    /**
+     * Register a trail whose head follows `node`.
+     *
+     * @param {TrailParameters} parameters
+     * @param {number} node the `transforms` row of the trail's entity
+     * @returns {GPUTrailContext|null} null when the knot pool cannot house the trail on this device
+     */
+    add(parameters, node) {
+        assert.isNonNegativeInteger(node, 'node');
+        assert.notNull(parameters.fade, 'parameters.fade');
+
+        const knots = this.#knots.allocate(parameters.knot_count);
+
+        if (knots.offset === ALLOCATOR_NO_SPACE) {
+            return null;
+        }
+
+        const context = new GPUTrailContext();
+
+        context.node = node;
+        context.knots = knots;
+        context.fade = this.#fades.acquire(parameters.fade);
+        context.draw_class = this.#acquire_class(parameters.radial, parameters.knot_count - 1);
+        context.staged.copy(parameters);
+
+        context.row = this.table.add(this.#write_record(context, parameters));
+
+        this.#trails.set(context.row, context);
+
+        this.#seed(context);
+
+        return context;
+    }
+
+    /**
+     * Bring a trail's record up to date with `parameters`. A change to a build-time parameter rebuilds
+     * the trail: a new knot run, and a seed.
+     *
+     * @param {GPUTrailContext} context
+     * @param {TrailParameters} parameters
+     * @returns {boolean} false when a rebuild could not be housed; the trail keeps its old build
+     */
+    stage(context, parameters) {
+        assert.equal(this.#trails.get(context.row), context, 'the trail is not registered here');
+
+        const staged = context.staged;
+
+        if (!staged.same_build(parameters)) {
+            if (staged.knot_count !== parameters.knot_count) {
+                const knots = this.#knots.allocate(parameters.knot_count);
+
+                if (knots.offset === ALLOCATOR_NO_SPACE) {
+                    return false;
+                }
+
+                this.#knots.free(context.knots);
+                context.knots = knots;
+            }
+
+            // acquired before the old is released, so a class the trail stays in is never let go
+            const draw_class = this.#acquire_class(parameters.radial, parameters.knot_count - 1);
+
+            this.#release_class(context.draw_class, staged.knot_count - 1);
+            context.draw_class = draw_class;
+
+            context.reseed = false;
+            context.epoch++;
+        }
+
+        if (!context.fade.curve.equals(parameters.fade)) {
+            const fade = this.#fades.acquire(parameters.fade);
+
+            this.#fades.release(context.fade);
+            context.fade = fade;
+        }
+
+        const rebuild = !staged.same_build(parameters);
+
+        staged.copy(parameters);
+
+        this.table.set(context.row, this.#write_record(context, parameters));
+
+        if (rebuild) {
+            this.#seed(context);
+        }
+
+        return true;
+    }
+
+    /**
+     * Point a trail at another `transforms` row.
+     *
+     * @param {GPUTrailContext} context
+     * @param {number} node
+     */
+    set_node(context, node) {
+        assert.isNonNegativeInteger(node, 'node');
+
+        if (context.node === node) {
+            return;
+        }
+
+        context.node = node;
+
+        this.table.set(context.row, this.#write_record(context, context.staged));
+    }
+
+    /**
+     * Expire every knot and collapse the tube onto the head at the next frame, keeping the trail's birth
+     * and its knots' frames: `Trail3D.clear()`.
+     *
+     * @param {GPUTrailContext} context
+     */
+    clear(context) {
+        context.epoch++;
+        context.reseed = true;
+
+        this.table.set(context.row, this.#write_record(context, context.staged));
+
+        if (!this.#seeds.includes(context)) {
+            this.#seeds.push(context);
+        }
+    }
+
+    /**
+     * @param {GPUTrailContext} context
+     */
+    remove(context) {
+        assert.equal(this.#trails.get(context.row), context, 'the trail is not registered here');
+
+        this.table.remove(context.row);
+        this.state_table.remove(context.row);
+
+        this.#knots.free(context.knots);
+        this.#fades.release(context.fade);
+        this.#release_class(context.draw_class, context.staged.knot_count - 1);
+
+        const pending = this.#seeds.indexOf(context);
+
+        if (pending !== -1) {
+            this.#seeds.splice(pending, 1);
+        }
+
+        this.#trails.delete(context.row);
+
+        context.row = -1;
+        context.knots = null;
+        context.fade = null;
+        context.draw_class = -1;
+    }
+
+    /**
+     * Send what changed since the last frame: the records and states staged, the fade curves.
+     *
+     * @returns {GPUBuffer} the fade key buffer, as it now is on the device
+     */
+    upload() {
+        const database = this.#database;
+
+        if (database.has_pending_upload) {
+            const cmd = ShadeGPUCommandContext.create(this.#graphics, "trails/upload");
+
+            database.update(cmd);
+
+            cmd.finish();
+        }
+
+        return this.#fades.flush();
+    }
+
+    /**
+     * Take the trails waiting for the GPU to seed them, as rows.
+     *
+     * @returns {Uint32Array}
+     */
+    take_seeds() {
+        const seeds = this.#seeds;
+        const rows = new Uint32Array(seeds.length);
+
+        for (let i = 0; i < seeds.length; i++) {
+            rows[i] = seeds[i].row;
+        }
+
+        seeds.length = 0;
+
+        return rows;
+    }
+
+    /**
+     * Upload what changed and record one frame of the trails into `graph`: the seeds asked for, the
+     * update, and the scan of live segments the per-view passes dispatch from. Once per frame, after
+     * the hierarchy has composed this frame's matrices.
+     *
+     * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @param {number} scene_database graph handle of the scene database
+     * @returns {import("./graph_trails.js").TrailSimulationHandles}
+     */
+    record_simulation(graph, scene_database) {
+        const fade_keys = this.upload();
+
+        // a persistent buffer: written ahead of the frame's commands, read by its draws
+        this.#frame_words[0] = this.now;
+        this.#graphics.device.queue.writeBuffer(this.#frame_uniform, 0, this.#frame_words.buffer, 0, FRAME_UNIFORM_BYTES);
+
+        return graph_trails_simulate({
+            graph,
+            scene_database,
+            runtime: this,
+            fade_keys,
+            seeds: this.take_seeds(),
+        });
+    }
+
+    destroy() {
+        this.#database.destroy();
+        this.#knots.destroy();
+        this.#fades.destroy();
+        this.#frame_uniform.destroy();
+
+        for (const buffer of this.#index_buffers.values()) {
+            buffer.destroy();
+        }
+
+        this.#index_buffers.clear();
+        this.#trails.clear();
+        this.#seeds.length = 0;
+    }
+
+    /**
+     * Queue a GPU seed, or for an authored trail lay its knots down now.
+     *
+     * @param {GPUTrailContext} context
+     */
+    #seed(context) {
+        const parameters = context.staged;
+
+        if (parameters.authored === null) {
+            this.state_table.set(context.row, TRAIL_STATE_UNSEEDED);
+
+            if (!this.#seeds.includes(context)) {
+                this.#seeds.push(context);
+            }
+
+            return;
+        }
+
+        const authored = parameters.authored;
+        const count = authored.count;
+        const now = this.now;
+
+        assert.equal(count, parameters.knot_count, 'an authored trail has as many knots as its layout');
+
+        const words = new Uint32Array(count * TRAIL_KNOT_WORDS);
+        const floats = new Float32Array(words.buffer);
+
+        for (let i = 0; i < count; i++) {
+            authored.getPosition(scratch_position, i);
+            authored.getFrame(scratch_frame, i);
+
+            const age_ticks = Math.round(authored.getAge(i) * TRAIL_TICKS_PER_SECOND);
+
+            trail_knot_write(
+                words, floats, i,
+                scratch_position[0], scratch_position[1], scratch_position[2],
+                (now - age_ticks) >>> 0,
+                scratch_frame,
+                authored.getThickness(i),
+                context.row
+            );
+        }
+
+        this.#knots.write(context.knots.offset, words);
+
+        // laid down here, so seeded already: every knot is a candidate, the head is the first
+        this.state_table.set(context.row, {
+            head: 0,
+            live: count,
+            last_commit: now,
+            birth: now,
+            seeded_epoch: context.epoch,
+            distance: 0,
+        });
+
+        const pending = this.#seeds.indexOf(context);
+
+        if (pending !== -1) {
+            this.#seeds.splice(pending, 1);
+        }
+    }
+
+    /**
+     * @param {GPUTrailContext} context
+     * @param {TrailParameters} parameters
+     * @returns {Object} the record, for the table to copy
+     */
+    #write_record(context, parameters) {
+        const record = this.#record;
+
+        const max_age_ticks = Math.floor(parameters.max_age * TRAIL_TICKS_PER_SECOND);
+
+        assert.lessThan(max_age_ticks, TICK_AGE_LIMIT, 'maxAge past what a u32 tick count ages exactly');
+
+        let flags = 0;
+
+        if (parameters.spawning) {
+            flags |= TRAIL_FLAG.SPAWNING;
+        }
+
+        if (parameters.distance_mode) {
+            flags |= TRAIL_FLAG.DISTANCE;
+        }
+
+        if (parameters.authored !== null) {
+            flags |= TRAIL_FLAG.AUTHORED;
+        }
+
+        if (parameters.warmup) {
+            flags |= TRAIL_FLAG.WARMUP;
+        }
+
+        if (parameters.fade.evaluate(1) * parameters.color[3] > 0) {
+            flags |= TRAIL_FLAG.TAIL_VISIBLE;
+        }
+
+        if (context.reseed) {
+            flags |= TRAIL_FLAG.RESEED;
+        }
+
+        record.node = context.node;
+        record.knot_base = context.knots.offset;
+        record.knot_count = parameters.knot_count;
+        record.radial = parameters.radial;
+        record.flags = flags;
+        record.seed_epoch = context.epoch;
+        record.commit_ticks = Math.floor(parameters.max_age / parameters.knot_count * TRAIL_TICKS_PER_SECOND);
+        record.max_age_ticks = max_age_ticks;
+        record.max_age = parameters.max_age;
+        record.width = parameters.width;
+        record.spawn_distance = parameters.spawn_distance;
+        record.fade_first = context.fade.first;
+        record.fade_count = context.fade.count;
+        record.draw_class = context.draw_class;
+        record.offset.set(parameters.offset);
+        record.color.set(parameters.color);
+
+        return record;
+    }
+
+    /**
+     * @param {number} radial
+     * @param {number} segments the trail's knots less one
+     * @returns {number} the class index
+     */
+    #acquire_class(radial, segments) {
+        assert.greaterThanOrEqual(radial, 3, 'a tube ring needs at least 3 radial segments');
+
+        let draw_class = this.#classes_by_radial.get(radial);
+
+        if (draw_class === undefined) {
+            draw_class = new TrailDrawClass();
+            draw_class.radial = radial;
+
+            this.#classes_by_radial.set(radial, draw_class);
+
+            let index = this.#classes.indexOf(undefined);
+
+            if (index === -1) {
+                index = this.#classes.length;
+            }
+
+            this.#classes[index] = draw_class;
+        }
+
+        draw_class.references++;
+        draw_class.segments += segments;
+
+        return this.#classes.indexOf(draw_class);
+    }
+
+    /**
+     * @param {number} index
+     * @param {number} segments the trail's knots less one, as it was acquired with
+     */
+    #release_class(index, segments) {
+        const draw_class = this.#classes[index];
+
+        draw_class.references--;
+        draw_class.segments -= segments;
+
+        if (draw_class.references > 0) {
+            return;
+        }
+
+        this.#classes_by_radial.delete(draw_class.radial);
+        this.#classes[index] = undefined;
+    }
+}