@woosh/meep-engine 3.68.0 → 3.69.0

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

@@ -0,0 +1,164 @@
+/**
+ * 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: number;
+    /** @type {number} the `transforms` row the head follows */
+    node: number;
+    /** @type {import("../../../core/binary/allocator/OffsetAllocator.js").Allocation|null} the knot run */
+    knots: import("../../../core/binary/allocator/OffsetAllocator.js").Allocation | null;
+    /** @type {import("./runtime/TrailFadeCurves.js").TrailFadeCurve|null} */
+    fade: import("./runtime/TrailFadeCurves.js").TrailFadeCurve | null;
+    /** @type {number} index of the trail's radial class */
+    draw_class: number;
+    /** @type {number} what the record's `seed_epoch` says */
+    epoch: number;
+    /** @type {boolean} the pending seed is a `clear()`, which keeps the trail's birth and frames */
+    reseed: boolean;
+    /** @type {TrailParameters} what was last staged */
+    staged: 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: number;
+    /** @type {number} trails in the class */
+    references: number;
+    /** @type {number} the most segments the class's trails can show: their knots less one each */
+    segments: number;
+}
+/**
+ * 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 {
+    /**
+     * @param {import("../GraphicsContext.js").GraphicsContext} graphics
+     */
+    constructor(graphics: import("../GraphicsContext.js").GraphicsContext);
+    /** @returns {import("../GraphicsContext.js").GraphicsContext} */
+    get graphics(): import("../GraphicsContext.js").GraphicsContext;
+    /** @returns {GPUBuffer} the clock as the vertex stage reads it */
+    get frame_uniform(): GPUBuffer;
+    /**
+     * The draw classes by index, a hole where no trail uses one.
+     * @returns {(TrailDrawClass|undefined)[]}
+     */
+    get draw_classes(): TrailDrawClass[];
+    /**
+     * 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: number): GPUBuffer;
+    /** @returns {GPUDatabase} the trail and state tables */
+    get database(): GPUDatabase;
+    /** @returns {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    get table(): import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+    /** @returns {import("../buffer/table/GPUTypedTable.js").GPUTypedTable} */
+    get state_table(): import("../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+    /** @returns {TrailKnotPool} */
+    get knots(): TrailKnotPool;
+    /** @returns {TrailFadeCurves} */
+    get fades(): TrailFadeCurves;
+    /** @returns {number} trails registered */
+    get count(): number;
+    /**
+     * @returns {number} the clock, in ticks, wrapped to a u32
+     */
+    get now(): number;
+    /**
+     * Radial counts by class index, a hole where no trail uses one.
+     * @returns {(number|undefined)[]}
+     */
+    get class_radials(): number[];
+    /**
+     * @returns {GPUTrailContext[]} trails waiting for the GPU to seed them; taken by the frame that seeds them
+     */
+    get pending_seeds(): GPUTrailContext[];
+    /**
+     * Move the clock on.
+     *
+     * @param {number} seconds simulation time since the last call
+     */
+    advance(seconds: number): void;
+    /**
+     * 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: TrailParameters, node: number): GPUTrailContext | null;
+    /**
+     * 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: GPUTrailContext, parameters: TrailParameters): boolean;
+    /**
+     * Point a trail at another `transforms` row.
+     *
+     * @param {GPUTrailContext} context
+     * @param {number} node
+     */
+    set_node(context: GPUTrailContext, node: number): void;
+    /**
+     * 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: GPUTrailContext): void;
+    /**
+     * @param {GPUTrailContext} context
+     */
+    remove(context: GPUTrailContext): void;
+    /**
+     * 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(): GPUBuffer;
+    /**
+     * Take the trails waiting for the GPU to seed them, as rows.
+     *
+     * @returns {Uint32Array}
+     */
+    take_seeds(): Uint32Array;
+    /**
+     * 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: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph, scene_database: number): import("./graph_trails.js").TrailSimulationHandles;
+    destroy(): void;
+    #private;
+}
+import { TrailParameters } from "./runtime/TrailParameters.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { TrailKnotPool } from "./runtime/TrailKnotPool.js";
+import { TrailFadeCurves } from "./runtime/TrailFadeCurves.js";
+//# sourceMappingURL=GPUTrailSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUTrailSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/trails/GPUTrailSystem.js"],"names":[],"mappings":"AA4BA;;;GAGG;AACH;IACI,uDAAuD;IACvD,KADW,MAAM,CACR;IAET,2DAA2D;IAC3D,MADW,MAAM,CACR;IAET,uGAAuG;IACvG,OADW,OAAO,mDAAmD,EAAE,UAAU,GAAC,IAAI,CACzE;IAEb,yEAAyE;IACzE,MADW,OAAO,8BAA8B,EAAE,cAAc,GAAC,IAAI,CACzD;IAEZ,uDAAuD;IACvD,YADW,MAAM,CACD;IAEhB,yDAAyD;IACzD,OADW,MAAM,CACP;IAEV,gGAAgG;IAChG,QADW,OAAO,CACH;IAEf,mDAAmD;IACnD,QADW,eAAe,CACK;CAClC;AAED;;GAEG;AACH;IACI,qBAAqB;IACrB,QADW,MAAM,CACN;IAEX,yCAAyC;IACzC,YADW,MAAM,CACF;IAEf,8FAA8F;IAC9F,UADW,MAAM,CACJ;CAChB;AAQD;;;;;;;;;;;;GAYG;AACH;IA2FI;;OAEG;IACH,sBAFW,OAAO,uBAAuB,EAAE,eAAe,EAqBzD;IAED,iEAAiE;IACjE,gEAEC;IAED,kEAAkE;IAClE,+BAEC;IAED;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,aAmChB;IAED,wDAAwD;IACxD,4BAEC;IAED,0EAA0E;IAC1E,2EAEC;IAED,0EAA0E;IAC1E,iFAEC;IAED,+BAA+B;IAC/B,2BAEC;IAED,iCAAiC;IACjC,6BAEC;IAED,0CAA0C;IAC1C,oBAEC;IAED;;OAEG;IACH,kBAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;OAEG;IACH,uCAEC;IAED;;;;OAIG;IACH,iBAFW,MAAM,QAMhB;IAED;;;;;;OAMG;IACH,gBAJW,eAAe,QACf,MAAM,GACJ,eAAe,GAAC,IAAI,CA2BhC;IAED;;;;;;;OAOG;IACH,eAJW,eAAe,cACf,eAAe,GACb,OAAO,CA+CnB;IAED;;;;;OAKG;IACH,kBAHW,eAAe,QACf,MAAM,QAYhB;IAED;;;;;OAKG;IACH,eAFW,eAAe,QAWzB;IAED;;OAEG;IACH,gBAFW,eAAe,QAwBzB;IAED;;;;OAIG;IACH,oBAYC;IAED;;;;OAIG;IACH,cAFa,WAAW,CAavB;IAED;;;;;;;;OAQG;IACH,yBAJW,OAAO,2DAA2D,EAAE,UAAU,kBAC9E,MAAM,GACJ,OAAO,mBAAmB,EAAE,sBAAsB,CAgB9D;IAED,gBAaC;;CA0KJ;gCA1sB+B,8BAA8B;4BARlC,gCAAgC;8BAO9B,4BAA4B;gCAD1B,8BAA8B"}