@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -4,14 +4,17 @@ import {
     PARTICLE_DATABASE_INITIAL_SIZE,
     PARTICLE_DATABASE_SPEC,
     PARTICLE_EMITTER_STATE_TABLE,
-    PARTICLE_EMITTER_TABLE
+    PARTICLE_EMITTER_TABLE,
+    PARTICLE_FIELD_BINDING_TABLE,
 } from "../data/PARTICLE_DATABASE_SPEC.js";
 import { PARTICLE_EMITTER_STATE_EMPTY } from "../data/PARTICLE_EMITTER_STATE.js";
+import { PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS } from "../data/PARTICLE_FIELD_BINDING.js";
 import { create_emitter_record, write_emitter_record } from "../data/particle_emitter_record.js";
 import { PARTICLE_GENERATION_FIRST, particle_generation_next } from "../data/particle_header.js";
 import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
 import { ProgramHeap } from "./ProgramHeap.js";
+import { warn_limited } from "../../../util/warn_limited.js";
 
 /**
  * @typedef {import("../../buffer/table/GPUTypedTable.js").GPUTypedTable} GPUTypedTable
@@ -40,17 +43,21 @@ const RECORD = create_emitter_record();
  *
  * **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.
  */
@@ -62,7 +69,7 @@ export class EmitterRegistry {
     database;
 
     /**
-     * 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 = new ProgramHeap();
@@ -91,7 +98,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.
@@ -132,6 +140,12 @@ export class EmitterRegistry {
      */
     #generation = PARTICLE_GENERATION_FIRST;
 
+    /**
+     * Global field transform bindings, by global field name.
+     * @type {Map<string, {row: number, transform_row: number, channel: number}>}
+     */
+    #global_bindings = new Map();
+
     /**
      * @param {GPUDevice} device
      */
@@ -163,6 +177,14 @@ export class EmitterRegistry {
         return this.database.get(PARTICLE_EMITTER_STATE_TABLE);
     }
 
+    /**
+     * The transform binding table: one row per transform bound to a field.
+     * @returns {GPUTypedTable}
+     */
+    get binding_table() {
+        return this.database.get(PARTICLE_FIELD_BINDING_TABLE);
+    }
+
     /**
      * @returns {number} number of live emitters
      */
@@ -201,8 +223,8 @@ export class EmitterRegistry {
     }
 
     /**
-     * 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.
@@ -223,6 +245,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, transform_row = 0) {
         const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
@@ -239,6 +263,11 @@ export class EmitterRegistry {
 
         context.transform_row = transform_row;
 
+        // before the record: the record carries the block's offset
+        context.emitter_layout = emitter.emitter_layout;
+        context.field_block = this.programs.acquire_fields(emitter_field_word_count(context.emitter_layout));
+        this.programs.write_fields(context.field_block, emitter.emitter_fields);
+
         // The table picks the slot — the lowest free one, so a removed emitter's row is reused
         // rather than the id space growing without bound.
         context.row = this.table.add(write_emitter_record(RECORD, emitter, context));
@@ -264,8 +293,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
      */
@@ -290,10 +320,19 @@ export class EmitterRegistry {
         this.table.remove(context.row);
         this.state_table.remove(context.row);
 
+        for (const binding of context.bindings.values()) {
+            this.binding_table.remove(binding.row);
+        }
+
+        context.bindings.clear();
+
         this.programs.release(context.placement);
+        this.programs.release_fields(context.field_block);
 
         context.placement = null;
         context.program = null;
+        context.field_block = null;
+        context.emitter_layout = null;
 
         this.#contexts.delete(emitter);
     }
@@ -302,17 +341,19 @@ 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, program) {
         assert.defined(program, 'program');
@@ -340,6 +381,188 @@ export class EmitterRegistry {
         context.invalidate();
     }
 
+    /**
+     * 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, name, transform_row, channel) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        const layout = binding_layout(emitter, context);
+
+        if (layout === null || !layout.has(name)) {
+            throw new Error(`The emitter has no emitter field '${name}' to bind`);
+        }
+
+        check_binding_width(name, layout.componentsOf(name), channel);
+
+        let binding = context.bindings.get(name);
+
+        if (binding === undefined) {
+            binding = { row: -1, transform_row, channel };
+            context.bindings.set(name, binding);
+        }
+
+        binding.transform_row = transform_row;
+        binding.channel = channel;
+
+        this.#stage_binding(binding, context.field_block.offset + layout.offsetOf(name));
+    }
+
+    /**
+     * 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) {
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        return binding_layout(emitter, context);
+    }
+
+    /**
+     * 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, name) {
+        const context = this.#contexts.get(emitter);
+
+        assert.defined(context, 'emitter is not registered here');
+
+        const binding = context.bindings.get(name);
+
+        if (binding === undefined) {
+            return false;
+        }
+
+        this.binding_table.remove(binding.row);
+        context.bindings.delete(name);
+        context.invalidate();
+
+        return true;
+    }
+
+    /**
+     * 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, transform_row, channel) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        const components = PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS[channel];
+        const globals = this.programs.global_fields;
+
+        // the channel first: an unknown one has no width, and must not reach the layout
+        check_binding_width(name, globals.has(name) ? globals.get(name).components : components, channel);
+
+        const offset = globals.declare(name, components);
+
+        let binding = this.#global_bindings.get(name);
+
+        if (binding === undefined) {
+            binding = { row: -1, transform_row, channel };
+            this.#global_bindings.set(name, binding);
+        }
+
+        binding.transform_row = transform_row;
+        binding.channel = channel;
+
+        this.#stage_binding(binding, offset);
+    }
+
+    /**
+     * 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) {
+        const binding = this.#global_bindings.get(name);
+
+        if (binding === undefined) {
+            return false;
+        }
+
+        this.binding_table.remove(binding.row);
+        this.#global_bindings.delete(name);
+
+        const field = this.programs.global_fields.get(name);
+
+        this.programs.resend_fields(field.offset, field.offset + field.components);
+
+        return true;
+    }
+
+    /**
+     * @param {{row: number, transform_row: number, channel: number}} binding
+     * @param {number} word where it writes, from the field section's base
+     */
+    #stage_binding(binding, word) {
+        BINDING_RECORD.source = binding.transform_row;
+        BINDING_RECORD.word = word;
+        BINDING_RECORD.channel = binding.channel;
+
+        if (binding.row === -1) {
+            binding.row = this.binding_table.add(BINDING_RECORD);
+        } else {
+            this.binding_table.set(binding.row, BINDING_RECORD);
+        }
+    }
+
+    /**
+     * Restage an emitter's bindings at where its fields now are, dropping any whose field the
+     * running program's layout no longer has at that width.
+     *
+     * @param {GPUParticleEmitterContext} context
+     */
+    #restage_bindings(context) {
+        if (context.bindings.size === 0) {
+            return;
+        }
+
+        const layout = context.emitter_layout;
+
+        for (const [name, binding] of context.bindings) {
+            if (
+                layout === null || !layout.has(name)
+                || layout.componentsOf(name) !== PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS[binding.channel]
+            ) {
+                this.binding_table.remove(binding.row);
+                context.bindings.delete(name);
+                continue;
+            }
+
+            this.#stage_binding(binding, context.field_block.offset + layout.offsetOf(name));
+        }
+    }
+
     /**
      * Look up a live emitter by its table row.
      *
@@ -403,13 +626,19 @@ export class EmitterRegistry {
     }
 
     /**
-     * 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.
@@ -419,18 +648,40 @@ export class EmitterRegistry {
     flush() {
         const table = this.table;
 
-        // Reconcile plain-field edits before checking relocation: an acquire can repack the heap
-        // and move placements of rows we would otherwise have already staged.
+        // Reconcile program and emitter-layout edits before checking relocation: acquiring a program
+        // or a resized field block can repack the heap and move rows we would otherwise have
+        // already staged.
         for (const [emitter, context] of this.#contexts) {
-            if (emitter.program !== context.program) {
-                this.set_program(emitter, emitter.program);
+            if (emitter.program !== context.program && emitter.program !== context.refused_program) {
+                try {
+                    this.set_program(emitter, emitter.program);
+                    context.refused_program = null;
+                } catch (e) {
+                    // one effect the global layout cannot take must not stop every other emitter's frame
+                    context.refused_program = emitter.program;
+                    warn_limited(`EmitterRegistry: a program was refused and the emitter keeps its old one: ${e.message}`);
+                }
+            }
+
+            // the emitter's layout is its program's: while that program is refused, the layout stays
+            // the one the running program reads
+            if (emitter.program === context.program) {
+                context.emitter_layout = emitter.emitter_layout;
+            }
+
+            const word_count = emitter_field_word_count(context.emitter_layout);
+
+            if (context.field_block.word_count !== word_count) {
+                this.programs.release_fields(context.field_block);
+                context.field_block = this.programs.acquire_fields(word_count);
+                context.invalidate();
             }
         }
 
         const placement_version = this.programs.placement_version;
 
-        // A repack moved every program that was already placed, so every row holds offsets into
-        // where its code used to be. That is the one change no emitter announces — it is not an edit
+        // A repack moved every program or field block that was already placed, so every row holds
+        // offsets into where they used to be. That is the one change no emitter announces — it is not an edit
         // to any of them — so it is asked of the heap once here rather than pushed onto each context.
         const relocated = placement_version !== this.#staged_placement_version;
 
@@ -442,17 +693,30 @@ export class EmitterRegistry {
             }
 
             table.set(context.row, write_emitter_record(RECORD, emitter, context));
+
+            // Written on every restage, as the record is; after a relocation alone the repack has
+            // already moved them, and this writes the same words again. Values laid out for a
+            // refused program's layout are not the running program's, and the block keeps the
+            // last ones that were.
+            if (context.emitter_layout === emitter.emitter_layout) {
+                this.programs.write_fields(context.field_block, emitter.emitter_fields);
+            }
+
+            // a binding writes at the block's offset, which may have moved
+            this.#restage_bindings(context);
+
             context.staged(emitter);
         }
     }
 
     /**
-     * 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}
      */
@@ -462,3 +726,46 @@ export class EmitterRegistry {
         return this.programs.build_buffer();
     }
 }
+
+/**
+ * The one record every binding row is staged through; the table serializes it synchronously.
+ */
+const BINDING_RECORD = { source: 0, word: 0, channel: 0 };
+
+/**
+ * @param {string} name
+ * @param {number} components the field's
+ * @param {number} channel
+ * @throws if the channel does not write exactly as many words as the field has
+ */
+function check_binding_width(name, components, channel) {
+    const words = PARTICLE_FIELD_BINDING_CHANNEL_COMPONENTS[channel];
+
+    if (words === undefined) {
+        throw new Error(`Unknown transform binding channel ${channel}`);
+    }
+
+    if (components !== words) {
+        throw new Error(`Field '${name}' has ${components} components and the channel writes ${words}`);
+    }
+}
+
+/**
+ * @param {ParticleEmitter} emitter
+ * @param {GPUParticleEmitterContext} context its context
+ * @returns {import("../layout/ParticleLayout.js").ParticleLayout|null} see {@link EmitterRegistry#binding_layout}
+ */
+function binding_layout(emitter, context) {
+    return emitter.program === context.refused_program ? context.emitter_layout : emitter.emitter_layout;
+}
+
+/**
+ * How many words of emitter fields a block laid out by `layout` has to hold, and nothing for an
+ * effect that declares none.
+ *
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} layout
+ * @returns {number}
+ */
+function emitter_field_word_count(layout) {
+    return layout === null ? 0 : layout.word_count;
+}

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

@@ -2,10 +2,11 @@
  * Everything the GPU side knows about one {@link ./ParticleEmitter.js} that the emitter itself has
  * no business knowing.
  *
- * An emitter is a description of an effect: what to run, how fast, how big, which attribute is
+ * An emitter is a description of an effect: what to run, how fast, how big, which particle field 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 it was registered at, where its texture was packed into the atlas —
+ * given, which tenancy of that row it is, where its program and its emitter fields were placed in
+ * the program heap, which transforms are bound to those fields, which `transforms` row it was
+ * registered at, 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.
@@ -55,6 +56,45 @@ export class GPUParticleEmitterContext {
      * @type {import("./ProgramPlacement.js").ProgramPlacement|null}
      */
     placement: import("./ProgramPlacement.js").ProgramPlacement | null;
+    /**
+     * Where this emitter's own emitter fields sit in the field section of the {@link ./ProgramHeap.js}:
+     * the instance's data, beside the class's code and constants but never shared with another
+     * emitter of the same program. Held rather than copied out for the same reason as
+     * {@link placement} — a repack rewrites its offset in place. A zero-word block for an emitter
+     * whose effect declares no emitter fields; `null` only outside registration.
+     *
+     * @type {import("./ProgramHeap.js").FieldBlock|null}
+     */
+    field_block: import("./ProgramHeap.js").FieldBlock | null;
+    /**
+     * The emitter layout {@link program} was compiled against: what sizes {@link field_block} and
+     * places the values and bindings in it. The emitter's own `emitter_layout`, except while a
+     * program change is refused ({@link refused_program}) — the emitter's layout is then the refused
+     * program's, and this stays with the program that runs.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    /**
+     * This emitter's transform bindings, by emitter field name: the `field_bindings` row each one
+     * occupies, the `transforms` row it reads and the channel it writes. Restaged with the emitter,
+     * because the word a binding writes is the block's offset plus the field's, and the block moves.
+     *
+     * @type {Map<string, {row: number, transform_row: number, channel: number}>}
+     */
+    bindings: Map<string, {
+        row: number;
+        transform_row: number;
+        channel: number;
+    }>;
+    /**
+     * A program {@link ./EmitterRegistry.js EmitterRegistry#flush} could not give this emitter —
+     * one whose global imports the system's layout refuses — so that it is not tried again every
+     * frame. The emitter keeps running the program it had.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    refused_program: import("../isa/ParticleProgram.js").ParticleProgram | null;
     /** Author's immutable program reference, distinct from the heap's owned copy.
      * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleEmitterContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAEI;;;;;;;;OAQG;IACH,KAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;OAOG;IACH,WAFU,OAAO,uBAAuB,EAAE,gBAAgB,GAAC,IAAI,CAE9C;IAEjB;;OAEG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,GAAC,IAAI,CAEnD;IAEf;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEwB;IAE9C;;;;;;;;;;;;;;OAcG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,OAAO,CAInB;IAED;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAFW,OAAO,sBAAsB,EAAE,eAAe,QAMxD;CACJ"}
+{"version":3,"file":"GPUParticleEmitterContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/GPUParticleEmitterContext.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;;;;;;;OAQG;IACH,KAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;;;;OAOG;IACH,WAFU,OAAO,uBAAuB,EAAE,gBAAgB,GAAC,IAAI,CAE9C;IAEjB;;;;;;;;OAQG;IACH,aAFU,OAAO,kBAAkB,EAAE,UAAU,GAAC,IAAI,CAEjC;IAEnB;;;;;;;OAOG;IACH,gBAFU,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI,CAE7C;IAEtB;;;;;;OAMG;IACH,UAFU,IAAI,MAAM,EAAE;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,CAAC,CAEvD;IAErB;;;;;;OAMG;IACH,iBAFU,OAAO,2BAA2B,EAAE,eAAe,GAAC,IAAI,CAE3C;IAEvB;;OAEG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,GAAC,IAAI,CAEnD;IAEf;;;;;;;;;;OAUG;IACH,cAFU,YAAY,CAEwB;IAE9C;;;;;;;;;;;;;;OAcG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,kBAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,OAAO,CAInB;IAED;;;OAGG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAFW,OAAO,sBAAsB,EAAE,eAAe,QAMxD;CACJ"}

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

@@ -4,10 +4,11 @@ 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 description of an effect: what to run, how fast, how big, which attribute is
+ * An emitter is a description of an effect: what to run, how fast, how big, which particle field 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 it was registered at, where its texture was packed into the atlas —
+ * given, which tenancy of that row it is, where its program and its emitter fields were placed in
+ * the program heap, which transforms are bound to those fields, which `transforms` row it was
+ * registered at, 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.
@@ -62,6 +63,45 @@ export class GPUParticleEmitterContext {
      */
     placement = null;
 
+    /**
+     * Where this emitter's own emitter fields sit in the field section of the {@link ./ProgramHeap.js}:
+     * the instance's data, beside the class's code and constants but never shared with another
+     * emitter of the same program. Held rather than copied out for the same reason as
+     * {@link placement} — a repack rewrites its offset in place. A zero-word block for an emitter
+     * whose effect declares no emitter fields; `null` only outside registration.
+     *
+     * @type {import("./ProgramHeap.js").FieldBlock|null}
+     */
+    field_block = null;
+
+    /**
+     * The emitter layout {@link program} was compiled against: what sizes {@link field_block} and
+     * places the values and bindings in it. The emitter's own `emitter_layout`, except while a
+     * program change is refused ({@link refused_program}) — the emitter's layout is then the refused
+     * program's, and this stays with the program that runs.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    emitter_layout = null;
+
+    /**
+     * This emitter's transform bindings, by emitter field name: the `field_bindings` row each one
+     * occupies, the `transforms` row it reads and the channel it writes. Restaged with the emitter,
+     * because the word a binding writes is the block's offset plus the field's, and the block moves.
+     *
+     * @type {Map<string, {row: number, transform_row: number, channel: number}>}
+     */
+    bindings = new Map();
+
+    /**
+     * A program {@link ./EmitterRegistry.js EmitterRegistry#flush} could not give this emitter —
+     * one whose global imports the system's layout refuses — so that it is not tried again every
+     * frame. The emitter keeps running the program it had.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    refused_program = null;
+
     /** Author's immutable program reference, distinct from the heap's owned copy.
      * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
      */