@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -1,74 +1,216 @@
 /**
- * CPU-side registry of emitters. Each emitter binds a compiled effect (from
- * {@link ./create_particle_effect.js}) to instance parameters — world transform, spawn rate, blend /
- * projection / feature flags, bounds, render-attribute binding, atlas region and flipbook grid.
+ * The emitter set: {@link ParticleEmitter} instances on the CPU, one GPU table row each.
  *
- * {@link build} produces the three upload-ready buffers the GPU passes consume: the packed emitter
- * records, the concatenated program instructions, and the constant pool. Emitters are few and
- * long-lived, so the whole set is repacked when it changes.
+ * Rows live in a {@link GPUDatabase} table ({@link ../data/PARTICLE_DATABASE_SPEC.js}), which is
+ * what makes the set editable at runtime. Adding an emitter stages one record; removing one frees
+ * its slot for the next add; changing one restages that record and nothing else. Rows are handed
+ * out by the table and are stable for an emitter's lifetime — they have to be, because every live
+ * particle's record header stores the row of the emitter that spawned it.
+ *
+ * Reuse of a freed row is made safe by the **generation**: every add takes the next value of one
+ * running counter, so no two emitters this registry has ever registered share one, and the
+ * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
+ * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
+ *
+ * **None of that bookkeeping is on the emitter.** An emitter is a scene node and a description of
+ * an effect, with nothing in it that depends on a device; the row, the generation, the program
+ * placement, the node's `transforms` row and the atlas patch are a
+ * {@link ./GPUParticleEmitterContext.js} this registry holds against the emitter and hands out
+ * through {@link EmitterRegistry#context}. Registering an emitter creates one, removing it destroys
+ * one, and an emitter with no context here is an emitter this registry does not have.
+ *
+ * The GPU-owned per-emitter state is the database's second table, claimed and released here at the
+ * emitter's row and never written by the CPU otherwise.
+ *
+ * Programs are the one thing NOT in the database: they are variable-length and shared, so they go
+ * into a packed {@link ProgramHeap} buffer and the emitter record carries offsets into it. The heap
+ * is content-deduplicated and reference-counted — two emitters compiled from the same graph land on
+ * one program id, which is what the simulation-order bucketing buckets on, and the last emitter of
+ * an effect is what releases it.
  */
 export class EmitterRegistry {
-    /** @type {object[]} */
-    emitters: object[];
-    /** @returns {number} number of registered emitters */
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * @type {GPUDatabase}
+     */
+    database: GPUDatabase;
+    /**
+     * Packed instruction + constant buffers for every distinct program in the set.
+     * @type {ProgramHeap}
+     */
+    programs: ProgramHeap;
+    /**
+     * The live emitters, in no particular order — the row in {@link context} is the identity.
+     * @type {ParticleEmitter[]}
+     */
+    emitters: ParticleEmitter[];
+    /**
+     * The live emitters by table row. Sparse: a freed row reads `undefined` until it is reused.
+     * Rows are small dense integers handed out lowest-free-first, so an array is the right index.
+     *
+     * @type {ParticleEmitter[]}
+     */
+    by_row: ParticleEmitter[];
+    /**
+     * Whether {@link programs} has changed since {@link build_program} last packed it. The buffer is
+     * monolithic (a program is variable-length, so there is no table to page it into), so any change
+     * means re-uploading it whole — which is why the heap dedupes by content, and why this is
+     * separate from the per-row dirtiness the table tracks.
+     *
+     * Read off the heap's own version rather than kept as a flag: there is then no path that changes
+     * the programs and forgets to say so.
+     *
+     * @returns {boolean}
+     */
+    get programs_dirty(): boolean;
+    /**
+     * The emitter table.
+     * @returns {GPUTypedTable}
+     */
+    get table(): GPUTypedTable;
+    /**
+     * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
+     * here and otherwise the GPU's.
+     * @returns {GPUTypedTable}
+     */
+    get state_table(): GPUTypedTable;
+    /**
+     * @returns {number} number of live emitters
+     */
     get count(): number;
     /**
-     * Register an emitter.
-     *
-     * @param {object} config
-     * @param {{layout: object, program: object}} config.effect compiled effect
-     * @param {number[]} [config.transform] 16-element column-major local-to-world matrix
-     * @param {number} [config.seed]
-     * @param {number} [config.spawn_rate] particles/second
-     * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {{center?: number[], radius?: number}} [config.bounds]
-     * @param {Object<string,string>} [config.render] map of render channel -> attribute name
-     * @param {number[]} [config.atlas_region] [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
-     * @param {number[]} [config.flipbook] [cols, rows]
-     * @param {number} [config.attach_row] scene transforms row for bone attachment
-     * @returns {number} the emitter index
-     */
-    add(config: {
-        effect: {
-            layout: object;
-            program: object;
-        };
-        transform?: number[];
-        seed?: number;
-        spawn_rate?: number;
-        flags?: object;
-        bounds?: {
-            center?: number[];
-            radius?: number;
-        };
-        render?: {
-            [x: string]: string;
-        };
-        atlas_region?: number[];
-        flipbook?: number[];
-        attach_row?: number;
-    }): number;
-    /**
-     * Pack all emitters + their programs into upload-ready buffers.
-     *
-     * `program_count` is the number of DISTINCT programs across the emitter set — the bucket count
-     * the simulation-order coherence pass histograms into. It is CPU-known and low-churn (it only
-     * changes when the emitter set does), which is why that pass can size its histogram, its cursor
-     * and its padding dispatch on the host without any of the per-frame counts ever leaving the GPU.
-     *
-     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array, program_count: number }}
-     */
-    build(): {
-        emitters: Uint32Array;
-        program: Uint32Array;
-        constants: Uint32Array;
-        program_count: number;
-    };
-    /**
-     * The scene-node row an emitter is attached to (for bone attachment), or the "none" sentinel.
-     * @param {number} index
+     * Number of distinct compiled programs registered.
      * @returns {number}
      */
-    attachRow(index: number): number;
+    get program_count(): number;
+    /**
+     * Number of buckets the simulation-order coherence pass histograms into: every live program id
+     * is below it. See {@link ProgramHeap#program_id_capacity}.
+     *
+     * @returns {number}
+     */
+    get program_id_capacity(): number;
+    /**
+     * Register slots the hungriest registered effect needs — a property of the whole set, since
+     * there is one simulate pipeline and it is chosen once. What a caller does with the number (pick
+     * a register backing, refuse the effect, warn an author) is the caller's; see
+     * {@link ProgramHeap#max_register_count}.
+     *
+     * @returns {number}
+     */
+    get max_register_count(): number;
+    /**
+     * What this registry assigned an emitter: its table row, generation, program placement, the
+     * `transforms` row of its node and its atlas patch.
+     *
+     * `undefined` for an emitter this registry does not hold — which is the way to ask whether one
+     * is live, there being no `-1` on the emitter to read instead.
+     *
+     * @param {ParticleEmitter} emitter
+     * @returns {GPUParticleEmitterContext|undefined}
+     */
+    context(emitter: ParticleEmitter): GPUParticleEmitterContext | undefined;
+    /**
+     * Register an emitter and give it a table row.
+     *
+     * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or a description
+     *        {@link ParticleEmitter.from} accepts
+     * @param {number} [transform_row] the emitter node's row in the scene's `transforms` table, if
+     *        already known; {@link set_transform_row} sets it later otherwise
+     * @returns {ParticleEmitter}
+     */
+    add(config: ParticleEmitter | object, transform_row?: number): ParticleEmitter;
+    /**
+     * Unregister an emitter and free its table row.
+     *
+     * Its particles are not touched here; they carry its generation, the row they will read is
+     * zero-filled (or a later tenant's, with a different generation), and the simulate pass frees
+     * them the next time it sees them. Retiring an emitter gently — spawn rate to zero, remove once
+     * its particles have died — remains available to an author who wants the tail to play out.
+     *
+     * The emitter itself comes out of this unchanged: what it loses is its context, which is
+     * everything being registered gave it. Its program goes with the context — the heap counts
+     * references, so an effect is only unpacked when its last emitter leaves.
+     *
+     * @param {ParticleEmitter} emitter
+     */
+    remove(emitter: ParticleEmitter): void;
+    /**
+     * Give a registered emitter different bytecode to run: its old program loses a reference, the new
+     * one gains one, and its row is restaged with the new placement.
+     *
+     * This is the runtime edit the emitter table has always allowed and the program buffer used not
+     * to — an author reworking an effect in the editor changes the program of an emitter that is
+     * already live, and the effect it used to run goes away with the last emitter that ran it.
+     *
+     * The attribute {@link ../layout/ParticleLayout.js layout} is NOT part of this and must not
+     * change with it: particles already in flight are laid out the old way, and new bytecode reading
+     * them at new offsets would read somebody else's field. Re-laying-out an effect means new
+     * emitters.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+     */
+    set_program(emitter: ParticleEmitter, program: import("../isa/ParticleProgram.js").ParticleProgram): void;
+    /**
+     * Look up a live emitter by its table row.
+     *
+     * @param {number} row
+     * @returns {ParticleEmitter|undefined}
+     */
+    get(row: number): ParticleEmitter | undefined;
+    /**
+     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
+     * restaged on the next flush.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    set_transform_row(emitter: ParticleEmitter, transform_row: number): void;
+    /**
+     * Point an emitter's record at the patch its texture was packed into: uv offset `.xy`, uv scale
+     * `.zw`. The row is restaged on the next flush.
+     *
+     * For whoever owns the atlas to call, on registration and again after every repack — a repack
+     * moves every patch, and an emitter left holding the old one draws the wrong image.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {ArrayLike<number>} region [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
+     */
+    set_atlas_region(emitter: ParticleEmitter, region: ArrayLike<number>): void;
+    /**
+     * Restage the table rows of every emitter whose fields have moved since the last flush.
+     *
+     * "Moved" is the node's own change counter: an emitter is restaged when its
+     * {@link ../../scene/Node3D.js Node3D#version} is not the one its row was staged from, or when
+     * something in its context changed. So an author marks an edited emitter the way they mark any
+     * edited node, with `needsUpdate = true`, and there is no second flag to forget.
+     *
+     * Cheap to call every frame: an emitter that has not changed costs one integer comparison, and
+     * the table coalesces repeated writes to one row within a frame anyway. Walks the context map
+     * rather than the emitter list so that a pass over the set is not also a lookup per emitter.
+     * Stages through the one module-static record, so a frame's restaging allocates nothing however
+     * many rows it touches.
+     */
+    flush(): void;
+    /**
+     * The packed program buffer — header, constant pools, code — rebuilt whole.
+     *
+     * Call when {@link programs_dirty}; it answers the flag. The buffer is monolithic (a program is
+     * variable-length, so there is no table to page it into), so this is a full rebuild — the heap's
+     * content deduplication is what keeps it rare (it changes only when an effect the set has never
+     * seen is registered, or when the sections are repacked to make room for one).
+     *
+     * @returns {Uint32Array}
+     */
+    build_program(): Uint32Array;
+    #private;
 }
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import { ProgramHeap } from "./ProgramHeap.js";
+import { ParticleEmitter } from "./ParticleEmitter.js";
+import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
 //# sourceMappingURL=EmitterRegistry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAYA;;;;;;;;GAQG;AACH;IAEQ,uBAAuB;IACvB,UADW,MAAM,EAAE,CACD;IAGtB,sDAAsD;IACtD,oBAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;QAZqD,MAAM,EAAhD;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QACf,SAAS,GAA3B,MAAM,EAAE;QACQ,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,KAAK,GAArB,MAAM;QACwC,MAAM,GAApD;YAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACL,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACF,YAAY,GAA9B,MAAM,EAAE;QACU,QAAQ,GAA1B,MAAM,EAAE;QACQ,UAAU,GAA1B,MAAM;QACJ,MAAM,CASlB;IAED;;;;;;;;;OASG;IACH;kBAFyB,WAAW;iBAAW,WAAW;mBAAa,WAAW;uBAAiB,MAAM;MAyCxG;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAwEI;;OAEG;IACH,+BASC;IAlFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA8B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA4BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QAqB7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAoBC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;4BApb2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}