@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -2,10 +2,14 @@ import { assert } from "../../../../core/assert.js";
 import { Allocation, ALLOCATOR_NO_SPACE, OffsetAllocator } from "../../../../core/binary/allocator/OffsetAllocator.js";
 import { HashMap } from "../../../../core/collection/map/HashMap.js";
 import {
+    PARTICLE_GLOBAL_FIELD_WORDS,
     PARTICLE_PROGRAM_CODE_BASE_WORD,
+    PARTICLE_PROGRAM_FIELD_BASE_WORD,
     PARTICLE_PROGRAM_HEADER_WORDS,
     PARTICLE_VM_INSTRUCTION_WORDS,
 } from "../ParticleConstants.js";
+import { particle_link_global_fields } from "../isa/particle_link_global_fields.js";
+import { ParticleGlobalFields } from "./ParticleGlobalFields.js";
 import { ProgramPlacement } from "./ProgramPlacement.js";
 
 /**
@@ -22,8 +26,15 @@ const INITIAL_CODE_CAPACITY = 128;
 const INITIAL_CONSTANT_CAPACITY = 128;
 
 /**
- * Ranges an allocator can describe at once, to begin with. Each live program costs one, plus one for
- * the free remainder, and this grows with the set — it is a floor, not a ceiling.
+ * Words the field section starts out able to hold: the global reservation, and as much again for
+ * emitter blocks.
+ * @type {number}
+ */
+const INITIAL_FIELD_CAPACITY = PARTICLE_GLOBAL_FIELD_WORDS * 2;
+
+/**
+ * Ranges an allocator can describe at once, to begin with. Each live program or field block costs
+ * one, plus one for the free remainder, and this grows with the set — it is a floor, not a ceiling.
  * @type {number}
  */
 const INITIAL_ALLOCATION_CAPACITY = 32;
@@ -45,17 +56,18 @@ const EMPTY_WORDS = new Uint32Array(0);
 const EMPTY_ALLOCATION = Object.freeze(Allocation.from(0, ALLOCATOR_NO_SPACE));
 
 /**
- * One of the two sections of the packed buffer: a flat word array, and the
+ * One section of the packed buffer — constants, code or fields: a flat word array, and the
  * {@link ../../../../core/binary/allocator/OffsetAllocator.js OffsetAllocator} that says which parts
  * of it are in use.
  *
  * The unit is the ELEMENT, not the word — instructions for the code section, words for the constant
- * pool — because that is the unit the emitter record's offsets are in. `stride` is what converts.
+ * pool and the field section — because that is the unit the emitter record's offsets are in.
+ * `stride` is what converts.
  */
 class ProgramRegion {
 
     /**
-     * Words per element: {@link PARTICLE_VM_INSTRUCTION_WORDS} for code, 1 for constants.
+     * Words per element: {@link PARTICLE_VM_INSTRUCTION_WORDS} for code, 1 for constants and fields.
      * @type {number}
      */
     stride;
@@ -67,7 +79,7 @@ class ProgramRegion {
 
     /**
      * The section's words, `capacity * stride` of them. Words outside a live allocation hold
-     * whatever the program that used to be there left — nothing addresses them.
+     * whatever their last tenant left — nothing addresses them.
      * @type {Uint32Array}
      */
     words = EMPTY_WORDS;
@@ -89,7 +101,7 @@ class ProgramRegion {
 
     /**
      * Throw away every allocation and start again at `capacity` elements. The words go with them —
-     * the caller is expected to write each surviving program back into its new range.
+     * the caller is expected to write each survivor back into its new range.
      *
      * @param {number} capacity elements
      * @param {number} max_allocations ranges the allocator can describe at once
@@ -145,21 +157,49 @@ class ProgramRegion {
     }
 }
 
+/**
+ * One emitter's block of emitter fields in the heap's field section: an instance's own data, laid
+ * out by its effect's {@link ../layout/ParticleLayout.js ParticleLayout.emitter}.
+ *
+ * Held by the emitter's context and mutated in place by the heap when a repack moves it, as a
+ * {@link ./ProgramPlacement.js ProgramPlacement} is — a copy of {@link FieldBlock#offset} would go
+ * stale.
+ */
+export class FieldBlock {
+    /**
+     * First word of the block, counted from the field section's base — what the emitter record's
+     * `field_offset` carries.
+     * @type {number}
+     */
+    offset = 0;
+
+    /**
+     * @type {number}
+     */
+    word_count = 0;
+
+    /**
+     * The range the field section's allocator gave it; `null` for an empty or released block.
+     * @type {Allocation|null}
+     */
+    allocation = null;
+}
+
 /**
  * Holds every distinct compiled {@link ../isa/ParticleProgram.js ParticleProgram} the emitter set
- * runs, packs them into one buffer — a header, every constant pool, then every instruction stream —
- * and hands back the {@link ./ProgramPlacement.js placement} each emitter records.
+ * runs, packs them into one buffer — a header, every constant pool, every instruction stream, then
+ * the field values — and hands back the {@link ./ProgramPlacement.js placement} each emitter records.
  *
  * Data before code, behind a four-word header whose first word says where the code starts: the VM
- * reads both sections through one binding (a storage buffer per stage is not free, and code and
+ * reads every section through one binding (a storage buffer per stage is not free, and code and
  * constants are read together), and an emitter's constant pool sits next to the pools of the
  * programs it shares a wave with.
  *
  * **Programs are placed, not appended.** Each section is a range allocator
  * ({@link ../../../../core/binary/allocator/OffsetAllocator.js}) over a flat word array, so a
- * program that is no longer wanted gives its space back and the next one takes it. This is what the
- * emitter table has always been able to do, and what the packed buffer could not: an authoring
- * session that adds, edits and drops effects for an hour no longer grows the buffer for an hour.
+ * program that is no longer wanted gives its space back and the next one takes it, as a row of the
+ * emitter table does: an authoring session that adds, edits and drops effects for an hour does not
+ * grow the buffer for an hour.
  *
  * Because VM instructions carry no absolute code addresses (control flow is branchless) and constant
  * references are program-local (the VM adds the emitter's `constant_offset`), a program is
@@ -177,25 +217,40 @@ class ProgramRegion {
  *
  * **Sharing is what makes {@link ProgramHeap#release} a reference count** rather than a delete: the
  * last emitter of an effect frees it, and the ones before it do not.
+ *
+ * **Fields come after the code**: `[header][constants][code][fields]`. A program is a class and an
+ * emitter an instance of it, so the code and constants are shared and the fields are not — every
+ * emitter whose effect declares emitter fields has a {@link FieldBlock} of its own, allocated by the
+ * same kind of range allocator and repacked the same way. The section opens with
+ * {@link ../ParticleConstants.js PARTICLE_GLOBAL_FIELD_WORDS} reserved for global fields, so those
+ * are addressed from zero and never move. Header word
+ * {@link ../ParticleConstants.js PARTICLE_PROGRAM_FIELD_BASE_WORD} says where the section starts.
+ *
+ * Field values change with gameplay where code changes with authoring, so a value change does not
+ * move {@link ProgramHeap#version}: the section is written back by span instead, and
+ * {@link ProgramHeap#fields_dirty_begin} and {@link ProgramHeap#fields_dirty_end} bound what changed
+ * since the buffer was last built or the span last cleared.
  */
 export class ProgramHeap {
 
     /**
      * Bumped whenever the packed buffer would come out different from the last one
-     * {@link ProgramHeap#build_buffer} produced — a program was placed, or the sections were
-     * repacked. A holder that uploads the buffer re-uploads when this moves.
+     * {@link ProgramHeap#build_buffer} produced — a program was placed, or a section was repacked.
+     * A holder that uploads the buffer re-uploads when this moves.
      *
-     * Releasing a program does NOT move it. The words it occupied are dead rather than changed, and
-     * re-uploading the buffer to remove bytes nothing addresses would be a rebuild for nothing; the
-     * next program placed there is what makes the buffer differ, and that bumps this.
+     * Placing a field block or writing field values does NOT move it: those words go out by the
+     * dirty span ({@link ProgramHeap#fields_dirty}). Nor does releasing a program or a block. The
+     * words it occupied are dead rather than changed, and re-uploading the buffer to remove bytes
+     * nothing addresses would be a rebuild for nothing; whatever is placed there next sends them.
      *
      * @type {number}
      */
     version = 0;
 
     /**
-     * Bumped when a repack moved programs that were already placed — every existing placement now
-     * holds different offsets, so every emitter record built from one is out of date.
+     * Bumped when a repack moved programs or field blocks that were already placed — every existing
+     * placement or block now holds different offsets, so every emitter record built from one is out
+     * of date.
      *
      * Separate from {@link ProgramHeap#version} because the two ask for different work: that one
      * says "upload the buffer again", this one says "restage every row". A repack moves both; an
@@ -223,6 +278,42 @@ export class ProgramHeap {
      */
     #constants = new ProgramRegion(1);
 
+    /**
+     * Global fields, then every emitter's block.
+     * @type {ProgramRegion}
+     */
+    #fields = new ProgramRegion(1);
+
+    /**
+     * Every live non-empty block, so a repack can move them.
+     * @type {Set<FieldBlock>}
+     */
+    #field_blocks = new Set();
+
+    /**
+     * First word of the field section changed since the buffer was built or the span cleared; with
+     * {@link ProgramHeap#fields_dirty_end}, an empty range when nothing did.
+     * @type {number}
+     */
+    fields_dirty_begin = 0;
+
+    /**
+     * One past the last word of the field section changed.
+     * @type {number}
+     */
+    fields_dirty_end = 0;
+
+    /**
+     * The system's global fields: the layout programs are linked against as they are placed, and
+     * the values, in the words reserved at the start of the field section.
+     *
+     * @type {ParticleGlobalFields}
+     */
+    global_fields = new ParticleGlobalFields((index, bits) => {
+        this.#fields.words[index] = bits;
+        this.#mark_fields_dirty(index, index + 1);
+    });
+
     /**
      * Id the next program gets when {@link ProgramHeap##free_program_ids} is empty. Also the number
      * of id slots that have ever been in use at once, which is what
@@ -249,6 +340,227 @@ export class ProgramHeap {
     constructor() {
         this.#code.reset(INITIAL_CODE_CAPACITY, INITIAL_ALLOCATION_CAPACITY);
         this.#constants.reset(INITIAL_CONSTANT_CAPACITY, INITIAL_ALLOCATION_CAPACITY);
+        this.#reset_fields(INITIAL_FIELD_CAPACITY, INITIAL_ALLOCATION_CAPACITY);
+    }
+
+    /**
+     * The field section's words, global fields first. What {@link ProgramHeap#fields_dirty_begin}
+     * and {@link ProgramHeap#fields_dirty_end} index.
+     *
+     * A repack replaces the array, so read it again after any {@link ProgramHeap#acquire_fields}.
+     *
+     * @returns {Uint32Array}
+     */
+    get field_words() {
+        return this.#fields.words;
+    }
+
+    /**
+     * The word of the packed buffer the field section starts at — what header word
+     * {@link ../ParticleConstants.js PARTICLE_PROGRAM_FIELD_BASE_WORD} holds.
+     * @returns {number}
+     */
+    get field_base_word() {
+        return PARTICLE_PROGRAM_HEADER_WORDS + this.#constants.words.length + this.#code.words.length;
+    }
+
+    /**
+     * @returns {boolean} whether any field words changed since the buffer was built or the span cleared
+     */
+    get fields_dirty() {
+        return this.fields_dirty_end > this.fields_dirty_begin;
+    }
+
+    /**
+     * Mark words of the field section for upload as they stand on the CPU, without changing them —
+     * for a word a transform binding was writing on the GPU, whose CPU value holds again once the
+     * binding is gone.
+     *
+     * @param {number} begin
+     * @param {number} end
+     */
+    resend_fields(begin, end) {
+        this.#mark_fields_dirty(begin, end);
+    }
+
+    /**
+     * Say the changed span has been written to the device.
+     */
+    clear_fields_dirty() {
+        this.fields_dirty_begin = 0;
+        this.fields_dirty_end = 0;
+    }
+
+    /**
+     * A block of `word_count` words for one emitter's emitter fields. Its contents are undefined
+     * until {@link ProgramHeap#write_fields}.
+     *
+     * Placing it may repack the field section, which moves every block and so moves
+     * {@link ProgramHeap#placement_version} (every emitter record carries its block's offset) and
+     * {@link ProgramHeap#version}.
+     *
+     * @param {number} word_count
+     * @returns {FieldBlock} never `null`; a zero-word block holds no allocation
+     */
+    acquire_fields(word_count) {
+        assert.isNonNegativeInteger(word_count, 'word_count');
+
+        const block = new FieldBlock();
+
+        block.word_count = word_count;
+
+        if (word_count === 0) {
+            return block;
+        }
+
+        if (!this.#try_place_fields(block)) {
+            this.#repack_fields(word_count);
+
+            const placed = this.#try_place_fields(block);
+
+            assert.ok(placed, 'a repacked field section had no room for the block it was repacked for');
+        }
+
+        this.#field_blocks.add(block);
+
+        return block;
+    }
+
+    /**
+     * Give a block back. Releasing one twice, or an empty one, does nothing.
+     * @param {FieldBlock} block
+     */
+    release_fields(block) {
+        assert.defined(block, 'block');
+
+        if (block.allocation === null) {
+            return;
+        }
+
+        this.#fields.free(block.allocation);
+        this.#field_blocks.delete(block);
+
+        block.allocation = null;
+    }
+
+    /**
+     * Write an emitter's field values into its block — `words` from the start, and zero for the rest
+     * of the block, so a block that held a previous tenant's values never shows them — and mark the
+     * block for upload.
+     *
+     * @param {FieldBlock} block
+     * @param {Uint32Array} words f32 bit patterns, at most {@link FieldBlock#word_count} of them
+     */
+    write_fields(block, words) {
+        assert.lessThanOrEqual(words.length, block.word_count, 'words.length');
+
+        if (block.word_count === 0) {
+            return;
+        }
+
+        const target = this.#fields.words;
+        const begin = block.offset;
+        const end = begin + block.word_count;
+
+        // Never past the block, whatever the caller handed over: the next block is somebody
+        // else's, and the assert above is stripped from a shipped build.
+        const count = Math.min(words.length, block.word_count);
+
+        for (let i = 0; i < count; i++) {
+            target[begin + i] = words[i];
+        }
+
+        target.fill(0, begin + count, end);
+
+        this.#mark_fields_dirty(begin, end);
+    }
+
+    /**
+     * @param {number} begin
+     * @param {number} end
+     */
+    #mark_fields_dirty(begin, end) {
+        if (!this.fields_dirty) {
+            this.fields_dirty_begin = begin;
+            this.fields_dirty_end = end;
+            return;
+        }
+
+        this.fields_dirty_begin = Math.min(this.fields_dirty_begin, begin);
+        this.fields_dirty_end = Math.max(this.fields_dirty_end, end);
+    }
+
+    /**
+     * Start the field section over at `capacity` words with nothing in it but the global
+     * reservation, which the first allocation of a fresh allocator puts at offset zero.
+     *
+     * @param {number} capacity
+     * @param {number} max_allocations
+     */
+    #reset_fields(capacity, max_allocations) {
+        this.#fields.reset(capacity, max_allocations);
+
+        const globals = this.#fields.allocate(PARTICLE_GLOBAL_FIELD_WORDS);
+
+        assert.ok(globals !== null && globals.offset === 0, 'the global field reservation must open the field section');
+    }
+
+    /**
+     * @param {FieldBlock} block
+     * @returns {boolean} whether it fit
+     */
+    #try_place_fields(block) {
+        const allocation = this.#fields.allocate(block.word_count);
+
+        if (allocation === null) {
+            return false;
+        }
+
+        block.allocation = allocation;
+        block.offset = allocation.offset;
+
+        return true;
+    }
+
+    /**
+     * Lay the field section out again with room for the blocks it holds plus one of
+     * `extra_words`, keeping every word: the global fields where they were, and each block's values
+     * moved with it.
+     *
+     * @param {number} extra_words
+     */
+    #repack_fields(extra_words) {
+        const previous = this.#fields.words;
+
+        let required = PARTICLE_GLOBAL_FIELD_WORDS + extra_words;
+
+        for (const block of this.#field_blocks) {
+            required += block.word_count;
+        }
+
+        const max_allocations = Math.max(INITIAL_ALLOCATION_CAPACITY, (this.#field_blocks.size + 3) * 2);
+
+        this.#reset_fields(
+            grown_capacity(this.#fields.capacity, required, INITIAL_FIELD_CAPACITY),
+            max_allocations
+        );
+
+        const words = this.#fields.words;
+
+        words.set(previous.subarray(0, PARTICLE_GLOBAL_FIELD_WORDS), 0);
+
+        for (const block of this.#field_blocks) {
+            const from = block.offset;
+
+            const placed = this.#try_place_fields(block);
+
+            assert.ok(placed, 'a freshly reset field section had no room for a block it already held');
+
+            words.set(previous.subarray(from, from + block.word_count), block.offset);
+        }
+
+        this.placement_version++;
+        this.version++;
     }
 
     /**
@@ -303,8 +615,12 @@ export class ProgramHeap {
      * in place when it repacks, so a caller keeps the object rather than copying its fields —
      * copies go stale, the object does not.
      *
+     * Placing a program declares the global fields it imports. A program whose imports the global
+     * layout cannot take is refused before anything is claimed for it.
+     *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
      * @returns {ProgramPlacement}
+     * @throws what {@link ./ParticleGlobalFields.js ParticleGlobalFields#check} throws for its imports
      */
     acquire(program) {
         assert.defined(program, 'program');
@@ -317,6 +633,9 @@ export class ProgramHeap {
             return existing;
         }
 
+        // asked first, so a refused program leaves no id, no range and no declaration behind
+        this.global_fields.check(program.global_imports);
+
         // The heap keeps its own copy, because this is about to become a hash table key and hash
         // table keys have to be immutable. A compiled program is treated as immutable everywhere,
         // but nothing enforces it — the optimizer's passes rewrite these arrays in place — and a
@@ -386,28 +705,37 @@ export class ProgramHeap {
     }
 
     /**
-     * The packed buffer: `[header][constants][code]`. Word
-     * {@link ../ParticleConstants.js PARTICLE_PROGRAM_CODE_BASE_WORD} of the header is the word index
-     * the code starts at — the only absolute address in the buffer, and the reason a placement can
-     * hold section-relative offsets and survive the sections being resized.
+     * The packed buffer: `[header][constants][code][fields]`. Header words
+     * {@link ../ParticleConstants.js PARTICLE_PROGRAM_CODE_BASE_WORD} and
+     * {@link ../ParticleConstants.js PARTICLE_PROGRAM_FIELD_BASE_WORD} are the word indices the code
+     * and the field section start at — the only absolute addresses in the buffer, and the reason a
+     * placement or a block can hold section-relative offsets and survive the sections being resized.
      *
-     * Both sections come out at their full capacity rather than trimmed to what is live: the offsets
+     * Every section comes out at its full capacity rather than trimmed to what is live: the offsets
      * a placement holds are offsets into the capacity, and trimming would mean moving programs to
      * close the holes, which is what a repack is for and what a buffer rebuild should not silently
      * become.
      *
+     * Clears the dirty field span: the whole section goes out with the buffer.
+     *
      * @returns {Uint32Array}
      */
     build_buffer() {
         const constants = this.#constants.words;
         const code = this.#code.words;
+        const fields = this.#fields.words;
 
         const code_base = PARTICLE_PROGRAM_HEADER_WORDS + constants.length;
-        const buffer = new Uint32Array(code_base + code.length);
+        const field_base = code_base + code.length;
+        const buffer = new Uint32Array(field_base + fields.length);
 
         buffer[PARTICLE_PROGRAM_CODE_BASE_WORD] = code_base;
+        buffer[PARTICLE_PROGRAM_FIELD_BASE_WORD] = field_base;
         buffer.set(constants, PARTICLE_PROGRAM_HEADER_WORDS);
         buffer.set(code, code_base);
+        buffer.set(fields, field_base);
+
+        this.clear_fields_dirty();
 
         return buffer;
     }
@@ -503,12 +831,34 @@ export class ProgramHeap {
         this.#code.write(placement.update_offset, program.update);
         this.#constants.write(placement.constant_offset, program.constant_words);
 
+        // Placing a program is what links it: its global reads name imports, and the system's
+        // layout says where each one is. The layout is append-only, so a link made here stays
+        // right for as long as the program is placed, and a repack makes the same one again.
+        const imports = program.global_imports;
+
+        if (imports.length > 0) {
+            const offsets = new Array(imports.length);
+
+            for (let i = 0; i < imports.length; i++) {
+                offsets[i] = this.global_fields.declare(imports[i].name, imports[i].components);
+            }
+
+            const begin = placement.init_offset * PARTICLE_VM_INSTRUCTION_WORDS;
+
+            particle_link_global_fields(
+                this.#code.words,
+                begin,
+                begin + placement.instruction_count * PARTICLE_VM_INSTRUCTION_WORDS,
+                offsets
+            );
+        }
+
         return true;
     }
 
     /**
-     * Lay both sections out again from scratch, with room for the programs already held plus one
-     * more of the given size.
+     * Lay the code and constant sections out again from scratch, with room for the programs already
+     * held plus one more of the given size.
      *
      * This is the only thing that moves a program, and it happens for one of two reasons: a section
      * has no contiguous run long enough (its free space is there but scattered), or its allocator has

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

@@ -1,25 +1,37 @@
 /**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
+ * Compile a particle effect: a particle field {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
- * The two halves come back together because they are compiled together, and an emitter takes both:
- * the layout is what a render binding resolves a name against, the program is what the heap packs.
- * They are not a value in their own right, so they go into an emitter by being spread —
+ * The parts come back together because they are compiled together, and an emitter takes all of
+ * them: the layout is what a render binding resolves a name against, the program is what the heap
+ * packs, and the emitter layout and values are the instance data the program reads. They are not a
+ * value in their own right, so they go into an emitter by being spread —
  * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
- * the emitter keeps them as two fields rather than as one bag.
+ * the emitter keeps them as separate fields rather than as one bag.
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
  * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [params.emitter_layout] the
+ *   emitter fields every emitter of the effect carries, from {@link ../layout/ParticleLayout.js ParticleLayout.emitter}
+ * @param {ArrayLike<number>} [params.emitter_fields] their values, as f32 bit patterns laid out by
+ *   `emitter_layout` — the defaults each emitter starts from
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [params.global_layout] the
+ *   global fields the effect may read, by name; what it does read becomes the program's imports
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram, emitter_layout: import("../layout/ParticleLayout.js").ParticleLayout|null, emitter_fields: Uint32Array }}
  */
-export function create_particle_effect({ layout, init, update }: {
+export function create_particle_effect({ layout, init, update, emitter_layout, emitter_fields, global_layout }: {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
     init?: NodeGraph;
     update?: NodeGraph;
+    emitter_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    emitter_fields?: ArrayLike<number>;
+    global_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
 }): {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
     program: import("../isa/ParticleProgram.js").ParticleProgram;
+    emitter_layout: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    emitter_fields: Uint32Array;
 };
 //# sourceMappingURL=create_particle_effect.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;IACvB;IAAE,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,2BAA2B,EAAE,eAAe,CAAA;CAAE,CAK1I"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAXwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;IAC0C,cAAc,GAAjF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAE9B,cAAc,GAAzC,UAAU,MAAM,CAAC;IAEkD,aAAa,GAAhF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEvD;IAAE,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,2BAA2B,EAAE,eAAe,CAAC;IAAC,cAAc,EAAE,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI,CAAC;IAAC,cAAc,EAAE,WAAW,CAAA;CAAE,CAWlP"}

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

@@ -1,22 +1,35 @@
 import { compile_particle_effect } from "../graph/compile_particle_graph.js";
 
 /**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
+ * Compile a particle effect: a particle field {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
- * The two halves come back together because they are compiled together, and an emitter takes both:
- * the layout is what a render binding resolves a name against, the program is what the heap packs.
- * They are not a value in their own right, so they go into an emitter by being spread —
+ * The parts come back together because they are compiled together, and an emitter takes all of
+ * them: the layout is what a render binding resolves a name against, the program is what the heap
+ * packs, and the emitter layout and values are the instance data the program reads. They are not a
+ * value in their own right, so they go into an emitter by being spread —
  * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
- * the emitter keeps them as two fields rather than as one bag.
+ * the emitter keeps them as separate fields rather than as one bag.
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
  * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [params.emitter_layout] the
+ *   emitter fields every emitter of the effect carries, from {@link ../layout/ParticleLayout.js ParticleLayout.emitter}
+ * @param {ArrayLike<number>} [params.emitter_fields] their values, as f32 bit patterns laid out by
+ *   `emitter_layout` — the defaults each emitter starts from
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [params.global_layout] the
+ *   global fields the effect may read, by name; what it does read becomes the program's imports
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram, emitter_layout: import("../layout/ParticleLayout.js").ParticleLayout|null, emitter_fields: Uint32Array }}
  */
-export function create_particle_effect({ layout, init, update }) {
-    const program = compile_particle_effect({ init, update, layout });
-    return { layout, program };
+export function create_particle_effect({ layout, init, update, emitter_layout = null, emitter_fields = [], global_layout = null }) {
+    const program = compile_particle_effect({
+        init,
+        update,
+        layout,
+        emitter_layout: emitter_layout ?? undefined,
+        global_layout: global_layout ?? undefined,
+    });
+    return { layout, program, emitter_layout, emitter_fields: Uint32Array.from(emitter_fields) };
 }