@woosh/meep-engine 3.68.0 → 3.69.0

package/src/shade/renderer/trails/data/TRAIL_DATABASE_SPEC.d.ts

@@ -0,0 +1,14 @@
+export const TRAIL_PAGE_SIZE: number;
+export const TRAIL_DATABASE_INITIAL_SIZE: number;
+export const TRAIL_TABLE: "trails";
+export const TRAIL_STATE_TABLE: "trail_state";
+/**
+ * The trails a scene context draws: the records the CPU stages and the state the GPU integrates, two
+ * tables in one buffer, at the same row. Rows are handed out densely by the runtime, not keyed by
+ * entity, so a page holds trails rather than holes.
+ */
+export const TRAIL_DATABASE_SPEC: GPUDatabaseDefinition;
+export const TRAIL_DESCRIPTOR: import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor;
+export const TRAIL_STATE_DESCRIPTOR: import("../../buffer/table/GPUTypedTableDescriptor.js").GPUTypedTableDescriptor;
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+//# sourceMappingURL=TRAIL_DATABASE_SPEC.d.ts.map

package/src/shade/renderer/trails/data/TRAIL_DATABASE_SPEC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRAIL_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/data/TRAIL_DATABASE_SPEC.js"],"names":[],"mappings":"AAMA,qCAA6C;AAE7C,iDAAyD;AAEzD,mCAAoC;AAEpC,8CAA+C;AAE/C;;;;GAIG;AACH,wDAGoB;AAapB,+GAAqE;AAErE,qHAAiF;sCApC3C,6CAA6C"}

package/src/shade/renderer/trails/data/TRAIL_DATABASE_SPEC.js

@@ -0,0 +1,38 @@
+import { KILOBYTE } from "../../../../core/science/units/memory/KILOBYTE.js";
+import { GPUDatabaseDefinition } from "../../buffer/table/GPUDatabaseDefinition.js";
+import { SCENE_DATABASE_SPEC } from "../../scene/SCENE_DATABASE_SPEC.js";
+import { TRAIL_STRUCT } from "./TRAIL_RECORD.js";
+import { TRAIL_STATE_STRUCT } from "./TRAIL_STATE.js";
+
+export const TRAIL_PAGE_SIZE = 16 * KILOBYTE;
+
+export const TRAIL_DATABASE_INITIAL_SIZE = 64 * KILOBYTE;
+
+export const TRAIL_TABLE = "trails";
+
+export const TRAIL_STATE_TABLE = "trail_state";
+
+/**
+ * The trails a scene context draws: the records the CPU stages and the state the GPU integrates, two
+ * tables in one buffer, at the same row. Rows are handed out densely by the runtime, not keyed by
+ * entity, so a page holds trails rather than holes.
+ */
+export const TRAIL_DATABASE_SPEC = GPUDatabaseDefinition.from({
+    [TRAIL_TABLE]: TRAIL_STRUCT,
+    [TRAIL_STATE_TABLE]: TRAIL_STATE_STRUCT,
+}, TRAIL_PAGE_SIZE);
+
+// The transforms row of the trail's entity, where the update reads its world matrix. Held through the
+// scene's rows by the trail system; it is not this database's to free.
+TRAIL_DATABASE_SPEC.add_link({
+    table: TRAIL_TABLE,
+    field: 'node',
+    target_database: SCENE_DATABASE_SPEC,
+    target_table: 'transforms',
+    nullable: false,
+    owning: false,
+});
+
+export const TRAIL_DESCRIPTOR = TRAIL_DATABASE_SPEC.get(TRAIL_TABLE);
+
+export const TRAIL_STATE_DESCRIPTOR = TRAIL_DATABASE_SPEC.get(TRAIL_STATE_TABLE);

package/src/shade/renderer/trails/data/TRAIL_KNOT.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Write one knot into `words` (a `Uint32Array` over the pool's words) at knot index `knot`, through
+ * `floats`, a `Float32Array` over the same bytes. The frame goes through the CPU encoder that matches
+ * `decode_vertex_normal`.
+ *
+ * @param {Uint32Array} words
+ * @param {Float32Array} floats
+ * @param {number} knot
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} birth tick
+ * @param {ArrayLike<number>} frame `[nx, ny, nz, bx, by, bz]`, unit and orthogonal
+ * @param {number} thickness
+ * @param {number} trail row
+ */
+export function trail_knot_write(words: Uint32Array, floats: Float32Array, knot: number, x: number, y: number, z: number, birth: number, frame: ArrayLike<number>, thickness: number, trail: number): void;
+/**
+ * Words of one knot in the knot pool:
+ *
+ *   [0..2] position   f32 × 3, world space
+ *   [3]    birth      u32, the tick the knot was committed at (`TRAIL_TICKS_PER_SECOND`)
+ *   [4]    normal     the ring frame's first axis, through `encode_vertex_normal`
+ *   [5]    binormal   the second axis, the same way
+ *   [6]    thickness  f32, the tube's diameter at this knot
+ *   [7]    trail      u32, the row of the trail the knot belongs to
+ *
+ * A knot stores when it was committed, not how old it is, so nothing writes it as it ages.
+ *
+ * @type {number}
+ */
+export const TRAIL_KNOT_WORDS: number;
+export const TRAIL_KNOT_BYTES: number;
+export const TRAIL_KNOT_POSITION: 0;
+export const TRAIL_KNOT_BIRTH: 3;
+export const TRAIL_KNOT_NORMAL: 4;
+export const TRAIL_KNOT_BINORMAL: 5;
+export const TRAIL_KNOT_THICKNESS: 6;
+export const TRAIL_KNOT_TRAIL: 7;
+/**
+ * Trail time is counted in ticks of 2⁻¹⁶ s (about 15 µs) in a u32, which wraps every 65,536 s (18.2 h).
+ * An age is `(now - birth) mod 2³²`, exact while it is under the wrap; a trail never asks the age of a
+ * knot it has already seen fade out, so an age is only ever read while it is under `maxAge` plus one
+ * frame.
+ *
+ * @type {number}
+ */
+export const TRAIL_TICKS_PER_SECOND: number;
+/**
+ * Reading and writing knots of the pool the enclosing shader binds as `knots` (`array<u32>`, read or
+ * read-write) by knot address — the index of the knot in the pool, not of its first word.
+ *
+ * - `trail_knot_read(address) -> TrailKnot`
+ * - `trail_knot_write(address, knot)` (the binding must be read-write)
+ * - `trail_knot_position(address) -> vec3<f32>`, `trail_knot_birth(address) -> u32`
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_trail_knot_read: CodeChunk;
+/**
+ * @see chunk_trail_knot_read
+ * @type {CodeChunk}
+ */
+export const chunk_trail_knot_write: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=TRAIL_KNOT.d.ts.map

package/src/shade/renderer/trails/data/TRAIL_KNOT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRAIL_KNOT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/data/TRAIL_KNOT.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;GAeG;AACH,wCAXW,WAAW,UACX,YAAY,QACZ,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,SACN,MAAM,SACN,UAAU,MAAM,CAAC,aACjB,MAAM,SACN,MAAM,QAiBhB;AAlED;;;;;;;;;;;;;GAaG;AACH,+BAFU,MAAM,CAEkB;AAElC,sCAAqD;AAErD,oCAAqC;AACrC,iCAAkC;AAClC,kCAAmC;AACnC,oCAAqC;AACrC,qCAAsC;AACtC,iCAAkC;AAElC;;;;;;;GAOG;AACH,qCAFU,MAAM,CAE4B;AAmC5C;;;;;;;;;GASG;AACH,oCAFU,SAAS,CA+CjB;AAEF;;;GAGG;AACH,qCAFU,SAAS,CAqBjB;0BAtJwB,oCAAoC"}

package/src/shade/renderer/trails/data/TRAIL_KNOT.js

@@ -0,0 +1,154 @@
+import { encode_normals_to_octahedral_u32 } from "../../geometry/normals/encode_normals_to_octahedral_u32.js";
+import { chunk_decode_vertex_normal } from "../../shader/chunk/geometry/normal/chunk_decode_vertex_normal.js";
+import { chunk_encode_vertex_normal } from "../../shader/chunk/geometry/normal/chunk_encode_vertex_normal.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Words of one knot in the knot pool:
+ *
+ *   [0..2] position   f32 × 3, world space
+ *   [3]    birth      u32, the tick the knot was committed at (`TRAIL_TICKS_PER_SECOND`)
+ *   [4]    normal     the ring frame's first axis, through `encode_vertex_normal`
+ *   [5]    binormal   the second axis, the same way
+ *   [6]    thickness  f32, the tube's diameter at this knot
+ *   [7]    trail      u32, the row of the trail the knot belongs to
+ *
+ * A knot stores when it was committed, not how old it is, so nothing writes it as it ages.
+ *
+ * @type {number}
+ */
+export const TRAIL_KNOT_WORDS = 8;
+
+export const TRAIL_KNOT_BYTES = TRAIL_KNOT_WORDS * 4;
+
+export const TRAIL_KNOT_POSITION = 0;
+export const TRAIL_KNOT_BIRTH = 3;
+export const TRAIL_KNOT_NORMAL = 4;
+export const TRAIL_KNOT_BINORMAL = 5;
+export const TRAIL_KNOT_THICKNESS = 6;
+export const TRAIL_KNOT_TRAIL = 7;
+
+/**
+ * Trail time is counted in ticks of 2⁻¹⁶ s (about 15 µs) in a u32, which wraps every 65,536 s (18.2 h).
+ * An age is `(now - birth) mod 2³²`, exact while it is under the wrap; a trail never asks the age of a
+ * knot it has already seen fade out, so an age is only ever read while it is under `maxAge` plus one
+ * frame.
+ *
+ * @type {number}
+ */
+export const TRAIL_TICKS_PER_SECOND = 65536;
+
+/**
+ * Write one knot into `words` (a `Uint32Array` over the pool's words) at knot index `knot`, through
+ * `floats`, a `Float32Array` over the same bytes. The frame goes through the CPU encoder that matches
+ * `decode_vertex_normal`.
+ *
+ * @param {Uint32Array} words
+ * @param {Float32Array} floats
+ * @param {number} knot
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} birth tick
+ * @param {ArrayLike<number>} frame `[nx, ny, nz, bx, by, bz]`, unit and orthogonal
+ * @param {number} thickness
+ * @param {number} trail row
+ */
+export function trail_knot_write(words, floats, knot, x, y, z, birth, frame, thickness, trail) {
+    const base = knot * TRAIL_KNOT_WORDS;
+
+    floats[base + TRAIL_KNOT_POSITION] = x;
+    floats[base + TRAIL_KNOT_POSITION + 1] = y;
+    floats[base + TRAIL_KNOT_POSITION + 2] = z;
+
+    words[base + TRAIL_KNOT_BIRTH] = birth >>> 0;
+
+    // normal and binormal are adjacent words, so the encoder writes both in one call
+    encode_normals_to_octahedral_u32(words, base + TRAIL_KNOT_NORMAL, 2, frame);
+
+    floats[base + TRAIL_KNOT_THICKNESS] = thickness;
+
+    words[base + TRAIL_KNOT_TRAIL] = trail >>> 0;
+}
+
+/**
+ * Reading and writing knots of the pool the enclosing shader binds as `knots` (`array<u32>`, read or
+ * read-write) by knot address — the index of the knot in the pool, not of its first word.
+ *
+ * - `trail_knot_read(address) -> TrailKnot`
+ * - `trail_knot_write(address, knot)` (the binding must be read-write)
+ * - `trail_knot_position(address) -> vec3<f32>`, `trail_knot_birth(address) -> u32`
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_trail_knot_read = CodeChunk.from(
+    //language=WGSL
+    `
+const TRAIL_KNOT_WORDS : u32 = ${TRAIL_KNOT_WORDS}u;
+
+struct TrailKnot {
+    position : vec3<f32>,
+    birth : u32,
+    normal : vec3<f32>,
+    binormal : vec3<f32>,
+    thickness : f32,
+    trail : u32,
+}
+
+fn trail_knot_position(address : u32) -> vec3<f32> {
+    let base = address * TRAIL_KNOT_WORDS;
+
+    return vec3<f32>(
+        bitcast<f32>(knots[base + ${TRAIL_KNOT_POSITION}u]),
+        bitcast<f32>(knots[base + ${TRAIL_KNOT_POSITION + 1}u]),
+        bitcast<f32>(knots[base + ${TRAIL_KNOT_POSITION + 2}u]),
+    );
+}
+
+fn trail_knot_birth(address : u32) -> u32 {
+    return knots[address * TRAIL_KNOT_WORDS + ${TRAIL_KNOT_BIRTH}u];
+}
+
+fn trail_knot_read(address : u32) -> TrailKnot {
+    let base = address * TRAIL_KNOT_WORDS;
+
+    var knot : TrailKnot;
+
+    knot.position = trail_knot_position(address);
+    knot.birth = knots[base + ${TRAIL_KNOT_BIRTH}u];
+    knot.normal = decode_vertex_normal(knots[base + ${TRAIL_KNOT_NORMAL}u]);
+    knot.binormal = decode_vertex_normal(knots[base + ${TRAIL_KNOT_BINORMAL}u]);
+    knot.thickness = bitcast<f32>(knots[base + ${TRAIL_KNOT_THICKNESS}u]);
+    knot.trail = knots[base + ${TRAIL_KNOT_TRAIL}u];
+
+    return knot;
+}
+`, [
+        chunk_decode_vertex_normal,
+    ]
+);
+
+/**
+ * @see chunk_trail_knot_read
+ * @type {CodeChunk}
+ */
+export const chunk_trail_knot_write = CodeChunk.from(
+    //language=WGSL
+    `
+fn trail_knot_write(address : u32, knot : TrailKnot) {
+    let base = address * TRAIL_KNOT_WORDS;
+
+    knots[base + ${TRAIL_KNOT_POSITION}u] = bitcast<u32>(knot.position.x);
+    knots[base + ${TRAIL_KNOT_POSITION + 1}u] = bitcast<u32>(knot.position.y);
+    knots[base + ${TRAIL_KNOT_POSITION + 2}u] = bitcast<u32>(knot.position.z);
+    knots[base + ${TRAIL_KNOT_BIRTH}u] = knot.birth;
+    knots[base + ${TRAIL_KNOT_NORMAL}u] = encode_vertex_normal(knot.normal);
+    knots[base + ${TRAIL_KNOT_BINORMAL}u] = encode_vertex_normal(knot.binormal);
+    knots[base + ${TRAIL_KNOT_THICKNESS}u] = bitcast<u32>(knot.thickness);
+    knots[base + ${TRAIL_KNOT_TRAIL}u] = knot.trail;
+}
+`, [
+        chunk_trail_knot_read,
+        chunk_encode_vertex_normal,
+    ]
+);

package/src/shade/renderer/trails/data/TRAIL_RECORD.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bits of {@link TRAIL_STRUCT }`.flags`.
+ */
+export type TRAIL_FLAG = number;
+export namespace TRAIL_FLAG {
+    let SPAWNING: number;
+    let DISTANCE: number;
+    let AUTHORED: number;
+    let WARMUP: number;
+    let TAIL_VISIBLE: number;
+    let RESEED: number;
+}
+/**
+ * One trail, as the CPU stages it: where it is, how long its knot run is and what it looks like. The
+ * GPU never writes it; what the GPU integrates lives in `TRAIL_STATE_STRUCT`, at the same row.
+ */
+export const TRAIL_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=TRAIL_RECORD.d.ts.map

package/src/shade/renderer/trails/data/TRAIL_RECORD.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRAIL_RECORD.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/data/TRAIL_RECORD.js"],"names":[],"mappings":";;;yBAOU,MAAM;;;;;;;;;AAuBhB;;;GAGG;AACH,wCAiC2B;6BAlEE,mCAAmC"}

package/src/shade/renderer/trails/data/TRAIL_RECORD.js

@@ -0,0 +1,68 @@
+import { f32, u32, vec3f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * Bits of {@link TRAIL_STRUCT}`.flags`.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const TRAIL_FLAG = {
+    /** The head follows the entity and commits knots; clear for a trail that only ages where it lies. */
+    SPAWNING: 1,
+    /** Knots are committed by distance travelled (`spawn_distance`) rather than by time (`commit_ticks`). */
+    DISTANCE: 2,
+    /**
+     * The knots were laid down by the CPU (a stroke), with ages that need not grow away from the head,
+     * so every knot is a candidate for drawing rather than the run the live count covers.
+     */
+    AUTHORED: 4,
+    /** The head is born `maxAge - t` old during the trail's first `maxAge` seconds, so the trail fades in. */
+    WARMUP: 8,
+    /** The fade is above zero at the end of a knot's life, so a knot past `maxAge` is still drawn. */
+    TAIL_VISIBLE: 16,
+    /**
+     * The pending seed is a `clear()`: it expires every knot and collapses them onto the head, but keeps
+     * the trail's birth and the knots' frames. Without it a seed is a build: everything starts over.
+     */
+    RESEED: 32,
+};
+
+/**
+ * One trail, as the CPU stages it: where it is, how long its knot run is and what it looks like. The
+ * GPU never writes it; what the GPU integrates lives in `TRAIL_STATE_STRUCT`, at the same row.
+ */
+export const TRAIL_STRUCT = WebGPUStruct.from({
+    /** the `transforms` row of the trail's entity, whose world matrix the head follows */
+    node: u32,
+    /** the first knot of the trail's run in the knot pool */
+    knot_base: u32,
+    /** knots in the run: a ring, head to tail */
+    knot_count: u32,
+    /** radial segments around the tube; the trail's draw class is the one for this count */
+    radial: u32,
+    /** {@link TRAIL_FLAG} bits */
+    flags: u32,
+    /** moved by the CPU for every seed it asks for; a state that has not seen it is seeded */
+    seed_epoch: u32,
+    /** ticks between commits in time mode: `maxAge / knot_count`, rounded down */
+    commit_ticks: u32,
+    /** `maxAge` in ticks: an age at or past it has faded out */
+    max_age_ticks: u32,
+    /** `maxAge` in seconds, what the fade's time is a fraction of */
+    max_age: f32,
+    /** tube diameter, given to each knot the head writes */
+    width: f32,
+    /** distance the head travels between commits in distance mode */
+    spawn_distance: f32,
+    /** the first key of the trail's fade curve in the fade key buffer */
+    fade_first: u32,
+    /** keys in the fade curve */
+    fade_count: u32,
+    /** the index of the trail's radial class: which list a visible segment of it is drawn from */
+    draw_class: u32,
+    /** where the head sits in the entity's local frame */
+    offset: vec3f,
+    /** linear RGB, unbounded, and the trail's base opacity, which the fade scales */
+    color: vec4f,
+}, "Trail3DRecord").pack();

package/src/shade/renderer/trails/data/TRAIL_STATE.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What the GPU integrates for a trail, at the same row as its `TRAIL_STRUCT`.
+ *
+ * The CPU writes a state row twice: when it claims the row, and when it lets the row go. In between
+ * only the GPU writes it — the seed pass when the record's `seed_epoch` moves, the update pass every
+ * frame. A CPU-authored trail is the exception that proves it: its knots are laid down by the CPU, so
+ * the CPU writes its whole starting state at claim, seeded already.
+ */
+export const TRAIL_STATE_STRUCT: WebGPUStruct;
+/**
+ * The state of a row claimed for a trail the GPU seeds: an epoch no record carries, so the first frame
+ * that sees the row seeds it.
+ *
+ * @type {Object}
+ */
+export const TRAIL_STATE_UNSEEDED: any;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=TRAIL_STATE.d.ts.map

package/src/shade/renderer/trails/data/TRAIL_STATE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TRAIL_STATE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/trails/data/TRAIL_STATE.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,8CAgBmB;AAEnB;;;;;GAKG;AACH,uCAOG;6BAzC0B,mCAAmC"}

package/src/shade/renderer/trails/data/TRAIL_STATE.js

@@ -0,0 +1,43 @@
+import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * What the GPU integrates for a trail, at the same row as its `TRAIL_STRUCT`.
+ *
+ * The CPU writes a state row twice: when it claims the row, and when it lets the row go. In between
+ * only the GPU writes it — the seed pass when the record's `seed_epoch` moves, the update pass every
+ * frame. A CPU-authored trail is the exception that proves it: its knots are laid down by the CPU, so
+ * the CPU writes its whole starting state at claim, seeded already.
+ */
+export const TRAIL_STATE_STRUCT = WebGPUStruct.from({
+    /** the head's slot in the run; the predecessor, older by one knot, is the next slot round */
+    head: u32,
+    /**
+     * Knots from the head that can still be visible. Only these are ever asked their age, which is what
+     * keeps a wrapped tick count from reading as young.
+     */
+    live: u32,
+    /** tick of the last commit, or of the seed */
+    last_commit: u32,
+    /** tick the trail was built at: the warm-up runs on the time since */
+    birth: u32,
+    /** the `seed_epoch` this state was last seeded for */
+    seeded_epoch: u32,
+    /** distance the head has travelled since the last commit */
+    distance: f32,
+}, "Trail3DState");
+
+/**
+ * The state of a row claimed for a trail the GPU seeds: an epoch no record carries, so the first frame
+ * that sees the row seeds it.
+ *
+ * @type {Object}
+ */
+export const TRAIL_STATE_UNSEEDED = Object.freeze({
+    head: 0,
+    live: 0,
+    last_commit: 0,
+    birth: 0,
+    seeded_epoch: 0,
+    distance: 0,
+});

package/src/shade/renderer/trails/graph_trails.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @typedef {Object} TrailSimulationHandles
+ * @property {number} trail_database graph handle of the trail and state tables, after the update
+ * @property {number} knots graph handle of the knot pool, after the update
+ * @property {number} fade_keys graph handle of the fade key buffer
+ * @property {number} segment_sums graph handle of the inclusive sums of live segments over the trail rows
+ * @property {number} segments_command graph handle of the dispatch, a thread per live segment, folded
+ * @property {number} capacity rows the sums cover
+ */
+/**
+ * Record one frame of the trails, view-independent, once per frame: the seeds asked for, the update of
+ * every trail, the scan of their live segments and the dispatch the per-view passes take from it.
+ *
+ * Call after the hierarchy has composed this frame's matrices — the update reads them — and after the
+ * runtime's upload, so the records are on the device.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.scene_database graph handle of the scene database
+ * @param {import("./GPUTrailSystem.js").GPUTrailSystem} params.runtime
+ * @param {GPUBuffer} params.fade_keys the fade key buffer, as the upload left it
+ * @param {Uint32Array} params.seeds rows to seed this frame
+ * @returns {TrailSimulationHandles}
+ */
+export function graph_trails_simulate({ graph, scene_database, runtime, fade_keys, seeds }: {
+    graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    scene_database: number;
+    runtime: import("./GPUTrailSystem.js").GPUTrailSystem;
+    fade_keys: GPUBuffer;
+    seeds: Uint32Array;
+}): TrailSimulationHandles;
+export type TrailSimulationHandles = {
+    /**
+     * graph handle of the trail and state tables, after the update
+     */
+    trail_database: number;
+    /**
+     * graph handle of the knot pool, after the update
+     */
+    knots: number;
+    /**
+     * graph handle of the fade key buffer
+     */
+    fade_keys: number;
+    /**
+     * graph handle of the inclusive sums of live segments over the trail rows
+     */
+    segment_sums: number;
+    /**
+     * graph handle of the dispatch, a thread per live segment, folded
+     */
+    segments_command: number;
+    /**
+     * rows the sums cover
+     */
+    capacity: number;
+};
+//# sourceMappingURL=graph_trails.d.ts.map

package/src/shade/renderer/trails/graph_trails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_trails.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/trails/graph_trails.js"],"names":[],"mappings":"AAgBA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IAPkG,KAAK,EAA5F,OAAO,2DAA2D,EAAE,UAAU;IAC/D,cAAc,EAA7B,MAAM;IAC+C,OAAO,EAA5D,OAAO,qBAAqB,EAAE,cAAc;IAC1B,SAAS;IACP,KAAK,EAAzB,WAAW;IACT,sBAAsB,CAwElC;;;;;oBA7Fa,MAAM;;;;WACN,MAAM;;;;eACN,MAAM;;;;kBACN,MAAM;;;;sBACN,MAAM;;;;cACN,MAAM"}

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

@@ -0,0 +1,155 @@
+import { align_4 } from "../../../core/binary/align_4.js";
+import { assert } from "../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../device/graph/BufferResourceDescriptor.js";
+import { INDIRECT_COMPUTE_COMMAND_DESCRIPTOR } from "../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
+import { shader_prefix_sum_to_command } from "../rasterize/expand/mesh/shader_prefix_sum_to_command.js";
+import { graph_compute_pass } from "../shader/graph/compute/graph_compute_pass.js";
+import { graph_create_buffer } from "../shader/graph/graph_create_buffer.js";
+import { graph_import_buffer } from "../shader/graph/graph_import_buffer.js";
+import { shader_trail_seed } from "./shaders/shader_trail_seed.js";
+import { shader_trail_update, TRAIL_UPDATE_WORKGROUP_SIZE } from "./shaders/shader_trail_update.js";
+
+/**
+ * @typedef {Object} TrailSimulationHandles
+ * @property {number} trail_database graph handle of the trail and state tables, after the update
+ * @property {number} knots graph handle of the knot pool, after the update
+ * @property {number} fade_keys graph handle of the fade key buffer
+ * @property {number} segment_sums graph handle of the inclusive sums of live segments over the trail rows
+ * @property {number} segments_command graph handle of the dispatch, a thread per live segment, folded
+ * @property {number} capacity rows the sums cover
+ */
+
+/**
+ * Record one frame of the trails, view-independent, once per frame: the seeds asked for, the update of
+ * every trail, the scan of their live segments and the dispatch the per-view passes take from it.
+ *
+ * Call after the hierarchy has composed this frame's matrices — the update reads them — and after the
+ * runtime's upload, so the records are on the device.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.scene_database graph handle of the scene database
+ * @param {import("./GPUTrailSystem.js").GPUTrailSystem} params.runtime
+ * @param {GPUBuffer} params.fade_keys the fade key buffer, as the upload left it
+ * @param {Uint32Array} params.seeds rows to seed this frame
+ * @returns {TrailSimulationHandles}
+ */
+export function graph_trails_simulate({ graph, scene_database, runtime, fade_keys, seeds }) {
+    assert.isNonNegativeInteger(scene_database, "scene_database");
+
+    const now = runtime.now;
+    const table = runtime.table;
+
+    // Two tables in one buffer, and the knots; each pass that writes them renames the handle the next
+    // reader takes.
+    let trail_database = graph_import_buffer(graph, runtime.database.buffer, "trails/database");
+    let knots = graph_import_buffer(graph, runtime.knots.buffer, "trails/knots");
+    const gr_fade_keys = graph_import_buffer(graph, fade_keys, "trails/fade_keys");
+
+    if (seeds.length > 0) {
+        const out = graph_trail_seed({ graph, scene_database, trail_database, knots, seeds, now });
+
+        trail_database = out.trail_database;
+        knots = out.knots;
+    }
+
+    const capacity = Math.max(1, table.element_capacity);
+
+    // the counts are cleared whole: the update writes only the rows it visits
+    const count_bytes = (PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(capacity)) * Uint32Array.BYTES_PER_ELEMENT;
+
+    let live_segments = graph_create_buffer(graph, "trails/live_segments", BufferResourceDescriptor.from(
+        count_bytes,
+        GPUBufferUsage.STORAGE,
+        0, count_bytes,
+    ));
+
+    const group_count = table.dispatch_group_count(TRAIL_UPDATE_WORKGROUP_SIZE);
+
+    // a table with no pages has nothing to visit: the cleared counts scan to zero
+    if (group_count > 0) {
+        const out = graph_compute_pass({
+            graph,
+            shader: shader_trail_update,
+            bindings: {
+                trail_database,
+                scene_database,
+                knots,
+                live_segments,
+                settings: { now, capacity },
+            },
+            group_count: [group_count, 1, 1],
+        });
+
+        trail_database = out.trail_database;
+        knots = out.knots;
+        live_segments = out.live_segments;
+    }
+
+    const segment_sums = graph_prefix_scan_csdldf({
+        graph,
+        input: live_segments,
+        output: graph_create_buffer(graph, "trails/segment_sums", prefix_scan_csdldf_output_descriptor(capacity)),
+        element_max_count: capacity,
+    });
+
+    const segments_command = graph_compute_pass({
+        graph,
+        shader: shader_prefix_sum_to_command,
+        bindings: {
+            prefix_sums: segment_sums,
+            command: graph_create_buffer(graph, "trails/segments_command", INDIRECT_COMPUTE_COMMAND_DESCRIPTOR),
+        },
+        group_count: [1, 1, 1],
+    }).command;
+
+    return { trail_database, knots, fade_keys: gr_fade_keys, segment_sums, segments_command, capacity };
+}
+
+/**
+ * The seed pass: a workgroup per row of `seeds`, the list uploaded with the pass.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.scene_database
+ * @param {number} params.trail_database
+ * @param {number} params.knots
+ * @param {Uint32Array} params.seeds
+ * @param {number} params.now
+ * @returns {{trail_database: number, knots: number}}
+ */
+function graph_trail_seed({ graph, scene_database, trail_database, knots, seeds, now }) {
+    function execute(data, resources, context) {
+        const encoder = context.encoder;
+
+        shader_trail_seed.dispatch({
+            encoder,
+            bindings: {
+                trail_database: resources.get(data.trail_database),
+                scene_database: resources.get(data.scene_database),
+                knots: resources.get(data.knots),
+                seeds: encoder.allocateTransientBufferAndLoad(seeds.buffer, GPUBufferUsage.STORAGE, seeds.byteOffset, seeds.byteLength),
+                settings: { now },
+            },
+            group_count_x: seeds.length,
+            group_count_y: 1,
+            group_count_z: 1,
+        });
+    }
+
+    const pass_data = {};
+    const pass = graph.add("Trail Seed", pass_data, execute);
+
+    pass_data.scene_database = pass.read(scene_database);
+    pass.read(trail_database);
+    pass_data.trail_database = pass.write(trail_database);
+    pass.read(knots);
+    pass_data.knots = pass.write(knots);
+
+    return { trail_database: pass_data.trail_database, knots: pass_data.knots };
+}