@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -14,17 +14,21 @@
  *
  * **None of that bookkeeping is on the emitter.** An emitter is a description of an effect, with
  * nothing in it that depends on a device; the row, the generation, the program placement, the
- * `transforms` row it is placed at and the atlas patch are a
+ * block of emitter fields, the transform bindings, the `transforms` row it is placed at 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.
+ * emitter's row and never written by the CPU otherwise. The third, `field_bindings`, holds one row
+ * per field bound to a transform, global fields' included.
  *
- * 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
+ * Programs and field values are NOT in the database: programs are variable-length and shared, so
+ * they go into a packed {@link ProgramHeap} buffer, followed by the field section — the global
+ * fields, then every emitter's block of emitter fields — 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.
  */
@@ -38,7 +42,7 @@ export class EmitterRegistry {
      */
     database: GPUDatabase;
     /**
-     * Packed instruction + constant buffers for every distinct program in the set.
+     * Constants and code for every distinct program in the set, and the field values.
      * @type {ProgramHeap}
      */
     programs: ProgramHeap;
@@ -63,7 +67,8 @@ export class EmitterRegistry {
      * 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.
+     * separate from the per-row dirtiness the table tracks. Field values are not counted: they go
+     * out by the heap's dirty span ({@link ProgramHeap#fields_dirty}).
      *
      * 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.
@@ -82,6 +87,11 @@ export class EmitterRegistry {
      * @returns {GPUTypedTable}
      */
     get state_table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
+    /**
+     * The transform binding table: one row per transform bound to a field.
+     * @returns {GPUTypedTable}
+     */
+    get binding_table(): import("../../buffer/table/GPUTypedTable.js").GPUTypedTable<any>;
     /**
      * @returns {number} number of live emitters
      */
@@ -108,8 +118,8 @@ export class EmitterRegistry {
      */
     get max_register_count(): number;
     /**
-     * What this registry assigned an emitter: its table row, generation, program placement, the
-     * `transforms` row it is placed at and its atlas patch.
+     * What this registry assigned an emitter: its table row, generation, program placement, block of
+     * emitter fields, transform bindings, the `transforms` row it is placed at 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.
@@ -127,6 +137,8 @@ export class EmitterRegistry {
      *        placed at — its entity's, one on — if already known; {@link set_transform_row} sets it
      *        later otherwise
      * @returns {ParticleEmitter}
+     * @throws what {@link ProgramHeap#acquire} throws for a program whose global imports are refused;
+     *         nothing is registered then
      */
     add(config: ParticleEmitter | object, transform_row?: number): ParticleEmitter;
     /**
@@ -138,8 +150,9 @@ export class EmitterRegistry {
      * 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.
+     * everything being registered gave it. Its program, its block of emitter fields and its
+     * transform bindings go with the context — the heap counts program references, so an effect is
+     * only unpacked when its last emitter leaves.
      *
      * @param {ParticleEmitter} emitter
      */
@@ -148,19 +161,70 @@ export class EmitterRegistry {
      * 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.
+     * This is the runtime edit an author reworking an effect in the editor makes: the program of an
+     * emitter that is already live changes, 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.
+     * The particle field {@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
+     * @throws what {@link ProgramHeap#acquire} throws for a program whose global imports are refused;
+     *         the emitter keeps the program it had
      */
     set_program(emitter: ParticleEmitter, program: import("../isa/ParticleProgram.js").ParticleProgram): void;
+    /**
+     * Write a row of the scene's `transforms` table into one of an emitter's emitter fields every
+     * frame, on the GPU: `channel` says which part of the row's composed `global`. Binding a field
+     * that is already bound rebinds it.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {string} name an emitter field of the program the emitter runs
+     * @param {number} transform_row the row to read — the bound entity's, held by the caller
+     * @param {number} channel a {@link ../data/PARTICLE_FIELD_BINDING.js PARTICLE_FIELD_BINDING_CHANNEL}
+     * @throws if the emitter has no such field, the channel is unknown, or the field is not exactly
+     *         as wide as the channel
+     */
+    bind_emitter_field(emitter: ParticleEmitter, name: string, transform_row: number, channel: number): void;
+    /**
+     * The emitter layout {@link bind_emitter_field} binds an emitter's fields against: the emitter's
+     * own, unless its program was refused, and then that of the program it still runs.
+     *
+     * @param {ParticleEmitter} emitter
+     * @returns {import("../layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    binding_layout(emitter: ParticleEmitter): import("../layout/ParticleLayout.js").ParticleLayout | null;
+    /**
+     * Stop writing a transform into an emitter field. The field holds the emitter's own value again
+     * from the next {@link EmitterRegistry#flush}, which restages the emitter.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {string} name
+     * @returns {boolean} false when the field was not bound
+     */
+    unbind_emitter_field(emitter: ParticleEmitter, name: string): boolean;
+    /**
+     * Write a row of the scene's `transforms` table into a global field every frame, on the GPU.
+     * The global field is declared at the channel's width if nothing has declared it yet.
+     *
+     * @param {string} name
+     * @param {number} transform_row the row to read — the bound entity's, held by the caller
+     * @param {number} channel a {@link ../data/PARTICLE_FIELD_BINDING.js PARTICLE_FIELD_BINDING_CHANNEL}
+     * @throws if the channel is unknown, the global field is declared with another width than the
+     *         channel's, or declaring it would run past the reserved words
+     */
+    bind_global_field(name: string, transform_row: number, channel: number): void;
+    /**
+     * Stop writing a transform into a global field. It reads its own value again — the last one set,
+     * or zero — which this marks to go out with the next field upload.
+     *
+     * @param {string} name
+     * @returns {boolean} false when the field was not bound
+     */
+    unbind_global_field(name: string): boolean;
     /**
      * Look up a live emitter by its table row.
      *
@@ -188,13 +252,19 @@ export class EmitterRegistry {
      */
     set_atlas_region(emitter: ParticleEmitter, region: ArrayLike<number>): void;
     /**
-     * Restage the table rows of every emitter whose fields have moved since the last flush.
+     * Restage the table rows of every emitter that has changed since the last flush, with its
+     * emitter field values and its transform bindings.
      *
-     * "Moved" is the emitter's own change counter: an emitter is restaged when its
+     * "Changed" is the emitter's own change counter: an emitter is restaged when its
      * {@link ./ParticleEmitter.js ParticleEmitter#version} is not the one its row was staged from,
      * or when something in its context changed. So an author marks an edited emitter with
      * `needsUpdate = true`, and there is no second flag to forget.
      *
+     * An emitter whose {@link ./ParticleEmitter.js ParticleEmitter#program} was replaced is moved to
+     * it here. A program the heap refuses is warned about and not tried again until the emitter's
+     * program changes; the emitter keeps running the one it had, and with it the block, values and
+     * bindings of that program's emitter layout. Does not throw for it.
+     *
      * 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.
@@ -203,12 +273,13 @@ export class EmitterRegistry {
      */
     flush(): void;
     /**
-     * The packed program buffer — header, constant pools, code — rebuilt whole.
+     * The packed program buffer — header, constant pools, code, fields — 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).
+     * seen is registered, or when a section is repacked to make room). Field value changes go by the
+     * heap's dirty span instead.
      *
      * @returns {Uint32Array}
      */

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":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;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;;;;;;;;;OASG;IACH,YAPW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAGJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;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,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BA9c2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAqFI;;OAEG;IACH,+BASC;IA/FD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;;OAWG;IACH,8BAEC;IAoDD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;IAED;;;OAGG;IACH,sFAEC;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;;;;;;;;;;;OAWG;IACH,YATW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAGJ,eAAe,CAsC3B;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAFW,eAAe,QAsCzB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,qBALW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA4B7D;IAED;;;;;;;;;;;OAWG;IACH,4BAPW,eAAe,QACf,MAAM,iBACN,MAAM,WACN,MAAM,QA8BhB;IAED;;;;;;OAMG;IACH,wBAHW,eAAe,GACb,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI,CAQrE;IAED;;;;;;;OAOG;IACH,8BAJW,eAAe,QACf,MAAM,GACJ,OAAO,CAkBnB;IAED;;;;;;;;;OASG;IACH,wBANW,MAAM,iBACN,MAAM,WACN,MAAM,QA0BhB;IAED;;;;;;OAMG;IACH,0BAHW,MAAM,GACJ,OAAO,CAiBnB;IA6CD;;;;;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;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cA8DC;IAED;;;;;;;;;;OAUG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BAttB2B,mCAAmC;4BAcnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}