@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js

@@ -0,0 +1,127 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Everything the GPU side knows about one {@link ./ParticleEmitter.js} that the emitter itself has
+ * no business knowing.
+ *
+ * An emitter is a scene node and a description of an effect: what to run, how fast, how big, which
+ * attribute is the colour. None of that depends on a device. The rest — which row of the emitter
+ * table it was given, which tenancy of that row it is, where its program was placed in the program
+ * heap, which `transforms` row its node ended up in, where its texture was packed into the atlas —
+ * is the particle system's bookkeeping, true only while the emitter is registered and only for the
+ * registry that registered it. Kept on the emitter it would travel with a saved effect, mean
+ * nothing when loaded, and be there for an author to set to a number the table has never heard of.
+ *
+ * So it lives here, in an object the registry owns and hands out ({@link ./EmitterRegistry.js#context}),
+ * and an emitter that no registry holds simply has none. That is also what makes "is this emitter
+ * live?" a question with one answer — the presence of a context — rather than a `row` of `-1` that
+ * anything could have written.
+ *
+ * Fields are set by the registry. Reading them is what a caller wants (the spawn ring addresses an
+ * emitter by row, a spec reads the generation a particle header should carry); writing them outside
+ * of {@link ./EmitterRegistry.js} desynchronises the context from the table it describes.
+ */
+export class GPUParticleEmitterContext {
+
+    /**
+     * Row this emitter occupies in the emitter table. Stable for as long as the emitter is
+     * registered — it is what every live particle's record header stores, so it cannot be
+     * renumbered while particles are in flight.
+     *
+     * Not to be confused with {@link ./ParticleEmitter.js Node3D#id}, which is the node's own
+     * identity and the key the scene context maps to a `transforms` row.
+     *
+     * @type {number}
+     */
+    row = -1;
+
+    /**
+     * Which tenancy of {@link row} this is. Distinct from every other the registry has ever handed
+     * out, and never zero. Stamped into every particle the emitter spawns, and what lets the
+     * simulate pass tell those particles from a later tenant's.
+     *
+     * @type {number}
+     */
+    generation = 0;
+
+    /**
+     * Row of the scene database's `transforms` table the emitter's node occupies, as the scene
+     * context reported it — what the record's `node` field carries. `0` (the scene root) until
+     * bound, so an emitter registered before its node is placed still reads a valid row.
+     *
+     * @type {number}
+     */
+    transform_row = 0;
+
+    /**
+     * Where this emitter's program sits in the shared {@link ./ProgramHeap.js}, and the program id
+     * the simulation-order bucketing keys on. Emitters compiled from the same graph hold the same
+     * object — which is also why it is held rather than copied out: the heap rewrites its offsets in
+     * place when it moves the program.
+     *
+     * @type {import("./ProgramPlacement.js").ProgramPlacement|null}
+     */
+    placement = null;
+
+    /**
+     * Where {@link ./ParticleEmitter.js#texture} landed in the particle system's atlas: uv offset
+     * `.xy`, uv scale `.zw`. Mirrors meep's `AtlasPatch`.
+     *
+     * Resolved, never authored. The emitter names an image; which sheet it is packed into and where
+     * is the system's answer, and it changes without the emitter changing — a repack moves every
+     * patch. `[0, 0, 1, 1]` is the whole sheet, which is what an emitter with no texture of its own
+     * gets: the default atlas is a single white texel.
+     *
+     * @type {Float32Array}
+     */
+    atlas_region = new Float32Array([0, 0, 1, 1]);
+
+    /**
+     * The emitter's {@link ../../scene/Node3D.js Node3D#version} as of the last time its row was
+     * staged, or `-1` for a row that must be restaged whatever the emitter says.
+     *
+     * This is the whole of the dirty tracking: {@link ./EmitterRegistry.js#flush} restages an
+     * emitter whose version has moved since. A node already counts its own changes for the
+     * renderer, and a second flag on the emitter saying the same thing would be one more thing to
+     * forget to set — so the emitter carries none, and an author who changes a field marks it the
+     * way they mark any node change, with `needsUpdate = true`.
+     *
+     * The version is the node's, so it also moves when the node merely moves, and the row is
+     * restaged for a change it does not hold. That costs one row: an emitter that moved is an
+     * emitter whose `transforms` row the scene context is uploading this frame anyway.
+     *
+     * A version of `-1` is unreachable for a node — the counter starts at 0 and only rises — so it
+     * is safe as the "not staged" sentinel, and it is what the fields above are set back to when
+     * one of *them* changes, since those move without the emitter moving.
+     *
+     * @type {number}
+     */
+    staged_version = -1;
+
+    /**
+     * @param {import("./ParticleEmitter.js").ParticleEmitter} emitter the emitter this describes
+     * @returns {boolean} whether the table row is out of step with `emitter`
+     */
+    is_stale(emitter) {
+        return this.staged_version !== emitter.version;
+    }
+
+    /**
+     * Mark the row as needing to be restaged on the next flush, for a change the emitter's version
+     * does not record — one of this context's own fields.
+     */
+    invalidate() {
+        this.staged_version = -1;
+    }
+
+    /**
+     * Record that the table row now holds `emitter` as it currently is.
+     *
+     * @param {import("./ParticleEmitter.js").ParticleEmitter} emitter
+     */
+    staged(emitter) {
+        assert.defined(emitter, 'emitter');
+
+        this.staged_version = emitter.version;
+    }
+}

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Render channels an emitter can bind to one of its effect's per-particle attributes. The names
+ * match the `render_*` fields of {@link ../data/PARTICLE_EMITTER_STRUCT.js}.
+ *
+ * @type {string[]}
+ */
+export const EMITTER_RENDER_CHANNELS: string[];
+/**
+ * How many record words the render pass reads for each channel.
+ *
+ * A channel is read at a fixed width — `chunk_particle_billboard_vertex.js` takes four words for
+ * colour and three for position, whatever the attribute behind the offset happens to be. Binding one
+ * to a narrower attribute is therefore not a smaller read but a read into whatever the layout put
+ * next, and nothing downstream objects: the particles simply come out wrong.
+ *
+ * Binding is deliberately not made to enforce this — the offsets are the record's, and an author who
+ * knows what is packed where may mean it — but an editor has this table so it can say so.
+ *
+ * @type {Object<string, number>}
+ */
+export const EMITTER_RENDER_CHANNEL_COMPONENTS: {
+    [x: string]: number;
+};
+/**
+ * One particle emitter: a scene node that runs a compiled effect.
+ *
+ * Being a {@link Node3D} is what places it. Add it to a scene and it gets a row in the scene
+ * database's `transforms` table like any other node; parent it to a joint and the GPU hierarchy
+ * pass composes its world matrix from the joint's every frame, animation included, with nothing
+ * copied through the CPU. Remove it from the scene and the row goes with it — and so do its
+ * particles, within a frame, because the emitter's table row is retired with it and its particles
+ * carry that row's generation. There is no transform of its own to keep in step with anything.
+ *
+ * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
+ * compiled {@link program}, the {@link texture} to draw with, spawn rate, blend / projection /
+ * feature flags, bounds sphere, render-attribute bindings and flipbook grid. Every one of those is
+ * the author's, means the same thing with no device present, and is what a saved effect is made of.
+ *
+ * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
+ * its program was placed in the program heap, which `transforms` row its node ended up in, where
+ * its texture was packed into the atlas — all of that is
+ * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
+ * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
+ * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
+ * "is this emitter live?" is asked. Nor is anything the GPU integrates per frame here — spawn
+ * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
+ *
+ * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
+ * node's own change counter, the same one the renderer reads to decide whether a transform needs
+ * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
+ * counter rather than a setter per field because a row is restaged whole either way: one changed
+ * field and ten cost the same upload.
+ */
+export class ParticleEmitter extends Node3D {
+    /**
+     * Build an emitter from a plain description. Every parameter is optional except the compiled
+     * effect — an emitter with no program has nothing to run.
+     *
+     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
+     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
+     *
+     * @param {object} config
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
+     *        attribute schema
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
+     *        UPDATE bytecode
+     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @param {string|null} [config.texture] image URL to draw with
+     * @param {number} [config.seed]
+     * @param {number} [config.spawn_rate] particles/second
+     * @param {object} [config.flags] passed to {@link make_emitter_flags}
+     * @param {{center?: ArrayLike<number>, radius?: number}} [config.bounds]
+     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
+     * @param {string} [config.name]
+     * @returns {ParticleEmitter}
+     */
+    static from(config: {
+        layout: import("../layout/ParticleLayout.js").ParticleLayout;
+        program: import("../isa/ParticleProgram.js").ParticleProgram;
+        position?: ArrayLike<number>;
+        texture?: string | null;
+        seed?: number;
+        spawn_rate?: number;
+        flags?: object;
+        bounds?: {
+            center?: ArrayLike<number>;
+            radius?: number;
+        };
+        render?: {
+            [x: string]: string;
+        };
+        flipbook?: ArrayLike<number>;
+        name?: string;
+    }): ParticleEmitter;
+    /**
+     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
+     * wide each is, and what word of the record it sits at.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout}
+     */
+    layout: import("../layout/ParticleLayout.js").ParticleLayout;
+    /**
+     * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram}
+     */
+    program: import("../isa/ParticleProgram.js").ParticleProgram;
+    /**
+     * Image to draw the particles with, by URL, or `null` to draw against the default atlas — a
+     * single white texel, so an untextured emitter is a flat quad of its colour.
+     *
+     * A URL rather than a texture, and no uv rect: the particle system packs every emitter's image
+     * into one sheet so that a hundred effects sharing a puff of smoke pay for one image, and where
+     * a given image lands in that sheet is the system's answer, not the author's — it changes on
+     * every repack, without the emitter changing. The resolved patch is
+     * {@link ./GPUParticleEmitterContext.js#atlas_region}.
+     *
+     * @type {string|null}
+     */
+    texture: string | null;
+    /**
+     * Base RNG seed.
+     *
+     * Two emitters running one program produce identical particles from identical seeds. `0` reads
+     * as "unset", and the row written for such an emitter takes its registration's generation
+     * instead, which no other emitter of that registry shares.
+     *
+     * @type {number}
+     */
+    seed: number;
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU by the emitter tick
+     * pass; the CPU never counts particles.
+     * @type {number}
+     */
+    spawn_rate: number;
+    /**
+     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * Bounding sphere in emitter-local space, scaled and placed by the node's world matrix.
+     *
+     * Two passes read it: the optional simulation culling (a culled emitter sleeps), and the AVBOIT
+     * occupancy, which marks the depth slices this emitter's particles may reach. The second gives
+     * it teeth even for an emitter that does not opt into culling — a particle outside the sphere
+     * still draws, but its extinction lands in whatever physical slice the warp put nearest, so it
+     * occludes at slightly the wrong depth. Size it to hold the effect.
+     *
+     * Hold the *quads*, not the centres. A camera-facing billboard has almost no depth extent, but
+     * an axis-locked, world-oriented or velocity-stretched one reaches a particle size — or, when
+     * stretched, several — in front of and behind the particle it belongs to.
+     *
+     * @type {Float32Array}
+     */
+    bounds_center: Float32Array;
+    /**
+     * @type {number}
+     */
+    bounds_radius: number;
+    /**
+     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
+     * is a single frame.
+     * @type {Float32Array}
+     */
+    flipbook: Float32Array;
+    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
+    render_position: number;
+    /** @type {number} record word offset of size */
+    render_size: number;
+    /** @type {number} record word offset of rgba colour */
+    render_color: number;
+    /** @type {number} record word offset of roll angle, radians */
+    render_rotation: number;
+    /** @type {number} record word offset of flipbook frame index */
+    render_frame: number;
+    /** @type {number} record word offset of velocity, read by the STRETCHED projection */
+    render_velocity: number;
+    get type(): string;
+    /**
+     * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
+     * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
+     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
+     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
+     * being at the origin.
+     *
+     * The record stores word offsets rather than names because that is what the render and sort
+     * passes index a particle record with; resolving here is the only place a name is involved.
+     *
+     * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
+     *        attribute name in the effect's layout
+     */
+    bind_render(channels: {
+        [x: string]: string;
+    }): void;
+    /**
+     * Structural equality over everything an emitter *is*: where it sits, what it runs, what it
+     * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
+     * effect in one place, and one row would serve both.
+     *
+     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
+     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
+     * be compared. {@link transform_global} is left out too, being derived from
+     * {@link transform_local} and the parent chain.
+     *
+     * @param {ParticleEmitter} other
+     * @returns {boolean}
+     */
+    equals(other: ParticleEmitter): boolean;
+    /**
+     * Hash over everything {@link equals} compares, in the same terms — the compiled program hashes
+     * by its own bytecode rather than by object identity, so two emitters separately compiled from
+     * one graph hash equally, as they compare equally.
+     *
+     * @returns {number} int32
+     */
+    hash(): number;
+    /**
+     * Make this emitter a copy of `other`: same effect, same settings, same placement.
+     *
+     * The layout and the compiled program are shared rather than duplicated — both are immutable
+     * once compiled, and sharing them is what puts two emitters of one effect on one program id in
+     * the program heap, hence in one simulation bucket.
+     *
+     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
+     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
+     * a second reference to the first one's table row.
+     *
+     * @param {ParticleEmitter} other
+     */
+    copy(other: ParticleEmitter): void;
+    /**
+     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
+     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
+     * `Node3D`, which would keep the transform and drop the effect.
+     *
+     * @returns {ParticleEmitter}
+     */
+    clone(): ParticleEmitter;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleEmitter: boolean;
+}
+import { Node3D } from "../../scene/Node3D.js";
+//# sourceMappingURL=ParticleEmitter.d.ts.map

package/src/shade/renderer/particles/runtime/ParticleEmitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA+QI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,KAAK,GAArB,MAAM;QACiD,MAAM,GAA7D;YAAC,MAAM,CAAC,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACd,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CAqD3B;IAvVD;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;OAIG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;OAcG;IACH,eAFU,YAAY,CAEc;IAEpC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;;;OAYG;IACH,cAHW,eAAe,GACb,OAAO,CAwBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CA0BlB;IAED;;;;;;;;;;;;OAYG;IACH,YAFW,eAAe,QAyBzB;IAED;;;;;;OAMG;IACH,SAFa,eAAe,CAgB3B;IA+EL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;uBA3ZsB,uBAAuB"}