@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -0,0 +1,221 @@
+import { assert } from "../../../../core/assert.js";
+import { PARTICLE_GLOBAL_FIELD_WORDS } from "../ParticleConstants.js";
+
+// One word reinterpreted: a global field is stored as f32 bit patterns, as every field is.
+const FIELD_WORD = new Uint32Array(1);
+const FIELD_WORD_F32 = new Float32Array(FIELD_WORD.buffer);
+
+/**
+ * @param {string} name
+ * @param {number} components
+ * @throws unless `components` is a width a field can have
+ */
+function check_components(name, components) {
+    if (!Number.isInteger(components) || components < 1 || components > 4) {
+        throw new Error(`Global field '${name}' cannot have ${components} components`);
+    }
+}
+
+/**
+ * @param {{components: number}} declared
+ * @param {string} name
+ * @param {number} components
+ * @throws if `declared` is narrower than `components`
+ */
+function check_width(declared, name, components) {
+    if (declared.components < components) {
+        throw new Error(
+            `Global field '${name}' is declared with ${declared.components} components and read with ${components}`
+        );
+    }
+}
+
+/**
+ * @param {string} name
+ * @param {number} offset
+ * @param {number} components
+ * @throws if a field that wide does not fit at `offset`
+ */
+function check_fits(name, offset, components) {
+    if (offset + components > PARTICLE_GLOBAL_FIELD_WORDS) {
+        throw new Error(
+            `Global field '${name}' does not fit: ${offset} of ${PARTICLE_GLOBAL_FIELD_WORDS} words are declared`
+        );
+    }
+}
+
+/**
+ * The system's global fields: the static members every effect may read, by name.
+ *
+ * The layout is the union of what is loaded. A program names the globals it imports, and placing it
+ * declares any name the system does not have yet, zero-filled; game code may declare names up front
+ * and set their values whenever it likes. The layout is append-only — a field once declared keeps
+ * its offset — so linking a program never has to be redone because another one was placed.
+ *
+ * The words live at the top of the program heap's field section (see {@link ./ProgramHeap.js}), in
+ * the {@link PARTICLE_GLOBAL_FIELD_WORDS} reserved there, so a global field is addressed from zero.
+ * A global field nobody has set reads 0: missing data is zero, never a stand-in.
+ */
+export class ParticleGlobalFields {
+
+    /**
+     * @type {Map<string, {name: string, offset: number, components: number}>}
+     */
+    #fields = new Map();
+
+    /**
+     * First free word.
+     * @type {number}
+     */
+    #cursor = 0;
+
+    /**
+     * @type {function(number, number):void} writes one word of the global region and says it changed
+     */
+    #write_word;
+
+    /**
+     * @param {function(number, number):void} write_word `(index, bits)`: writes word `index` of the
+     *   global region and marks it for upload
+     */
+    constructor(write_word) {
+        this.#write_word = write_word;
+    }
+
+    /**
+     * Words the declared fields take.
+     * @returns {number}
+     */
+    get word_count() {
+        return this.#cursor;
+    }
+
+    /**
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this.#fields.has(name);
+    }
+
+    /**
+     * @param {string} name
+     * @returns {{name: string, offset: number, components: number}|undefined}
+     */
+    get(name) {
+        return this.#fields.get(name);
+    }
+
+    /**
+     * Whether a program importing these could be placed: every name either declared at least that
+     * wide, or new and fitting in what is left of the reservation — all of them together, as placing
+     * the program would declare them. Changes nothing, so a program that cannot be placed is
+     * refused before anything is claimed for it.
+     *
+     * @param {ReadonlyArray<{name: string, components: number}>} imports
+     * @throws exactly what {@link declare} would throw for the first import that cannot be declared
+     */
+    check(imports) {
+        let cursor = this.#cursor;
+
+        for (let i = 0; i < imports.length; i++) {
+            const { name, components } = imports[i];
+
+            check_components(name, components);
+
+            const existing = this.#fields.get(name);
+
+            if (existing !== undefined) {
+                check_width(existing, name, components);
+                continue;
+            }
+
+            // a name new to the layout and imported twice is declared once, at its first width
+            let earlier = -1;
+
+            for (let j = 0; j < i; j++) {
+                if (imports[j].name === name) {
+                    earlier = j;
+                    break;
+                }
+            }
+
+            if (earlier !== -1) {
+                check_width(imports[earlier], name, components);
+                continue;
+            }
+
+            check_fits(name, cursor, components);
+
+            cursor += components;
+        }
+    }
+
+    /**
+     * Declare a global field, or find the one already declared under that name.
+     *
+     * A name is one field however many programs import it, so a second declaration must not want
+     * more of it than the first gave it: reading three words of a one-word field would read the next
+     * field's words, which is somebody else's data and never the right answer.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @returns {number} the field's word offset
+     * @throws if `components` is not 1..4, the name is declared narrower, or the reserved words are
+     *   spent
+     */
+    declare(name, components) {
+        assert.isString(name, 'name');
+
+        // thrown rather than asserted: a width that is not one corrupts the cursor for every field
+        // declared after it, and asserts are stripped from a shipped build
+        check_components(name, components);
+
+        const existing = this.#fields.get(name);
+
+        if (existing !== undefined) {
+            check_width(existing, name, components);
+
+            return existing.offset;
+        }
+
+        const offset = this.#cursor;
+
+        check_fits(name, offset, components);
+
+        this.#fields.set(name, { name, offset, components });
+        this.#cursor = offset + components;
+
+        return offset;
+    }
+
+    /**
+     * Set a global field's value, declaring it at that width if nothing has yet. Fewer values than
+     * the field has components set the leading ones.
+     *
+     * @param {string} name
+     * @param {ArrayLike<number>} values one per component
+     * @throws what {@link ParticleGlobalFields#declare} throws for `values.length` components
+     */
+    set(name, values) {
+        const offset = this.declare(name, values.length);
+        const field = this.#fields.get(name);
+
+        assert.lessThanOrEqual(values.length, field.components, 'values.length');
+
+        for (let i = 0; i < values.length; i++) {
+            FIELD_WORD_F32[0] = values[i];
+            this.#write_word(offset + i, FIELD_WORD[0]);
+        }
+    }
+
+    /**
+     * Visit every declared field, in declaration order.
+     * @param {function({name: string, offset: number, components: number}):void} visitor
+     */
+    forEach(visitor) {
+        for (const field of this.#fields.values()) {
+            visitor(field);
+        }
+    }
+}

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

@@ -1,18 +1,43 @@
+/**
+ * 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: number;
+    /**
+     * @type {number}
+     */
+    word_count: number;
+    /**
+     * The range the field section's allocator gave it; `null` for an empty or released block.
+     * @type {Allocation|null}
+     */
+    allocation: 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
@@ -30,23 +55,38 @@
  *
  * **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: number;
     /**
-     * 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
@@ -55,6 +95,82 @@ export class ProgramHeap {
      * @type {number}
      */
     placement_version: number;
+    /**
+     * 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: number;
+    /**
+     * One past the last word of the field section changed.
+     * @type {number}
+     */
+    fields_dirty_end: number;
+    /**
+     * 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: ParticleGlobalFields;
+    /**
+     * 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(): Uint32Array;
+    /**
+     * 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(): number;
+    /**
+     * @returns {boolean} whether any field words changed since the buffer was built or the span cleared
+     */
+    get fields_dirty(): boolean;
+    /**
+     * 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: number, end: number): void;
+    /**
+     * Say the changed span has been written to the device.
+     */
+    clear_fields_dirty(): void;
+    /**
+     * 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: number): FieldBlock;
+    /**
+     * Give a block back. Releasing one twice, or an empty one, does nothing.
+     * @param {FieldBlock} block
+     */
+    release_fields(block: FieldBlock): void;
+    /**
+     * 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: FieldBlock, words: Uint32Array): void;
     /**
      * Distinct programs currently held — and therefore effects, not emitters.
      * @returns {number}
@@ -98,8 +214,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: import("../isa/ParticleProgram.js").ParticleProgram): ProgramPlacement;
     /**
@@ -111,20 +231,25 @@ export class ProgramHeap {
      */
     release(placement: ProgramPlacement): boolean;
     /**
-     * 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(): Uint32Array;
     #private;
 }
+import { Allocation } from "../../../../core/binary/allocator/OffsetAllocator.js";
+import { ParticleGlobalFields } from "./ParticleGlobalFields.js";
 import { ProgramPlacement } from "./ProgramPlacement.js";
 //# sourceMappingURL=ProgramHeap.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ProgramHeap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramHeap.js"],"names":[],"mappings":"AAmJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAEI;;;;;;;;;;OAUG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAEM;IAgDtB;;;OAGG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,kCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAEC;IAED;;;;;;;;;;OAUG;IACH,iBAHW,OAAO,2BAA2B,EAAE,eAAe,GACjD,gBAAgB,CAuC5B;IAED;;;;;;OAMG;IACH,mBAHW,gBAAgB,GACd,OAAO,CAiCnB;IAED;;;;;;;;;;;;OAYG;IACH,gBAFa,WAAW,CAcvB;;CAwJJ;iCA5iBgC,uBAAuB"}
+{"version":3,"file":"ProgramHeap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramHeap.js"],"names":[],"mappings":"AA+JA;;;;;;;GAOG;AACH;IACI;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFU,UAAU,GAAC,IAAI,CAEP;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAEI;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;;;;;OAUG;IACH,mBAFU,MAAM,CAEM;IAgCtB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;OAKG;IACH,eAFU,oBAAoB,CAK3B;IA+BH;;;;;;;OAOG;IACH,+BAEC;IAED;;;;OAIG;IACH,8BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,qBAHW,MAAM,OACN,MAAM,QAIhB;IAED;;OAEG;IACH,2BAGC;IAED;;;;;;;;;;OAUG;IACH,2BAHW,MAAM,GACJ,UAAU,CAwBtB;IAED;;;OAGG;IACH,sBAFW,UAAU,QAapB;IAED;;;;;;;OAOG;IACH,oBAHW,UAAU,SACV,WAAW,QAwBrB;IA0FD;;;OAGG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,kCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAJW,OAAO,2BAA2B,EAAE,eAAe,GACjD,gBAAgB,CA2C5B;IAED;;;;;;OAMG;IACH,mBAHW,gBAAgB,GACd,OAAO,CAiCnB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAFa,WAAW,CAoBvB;;CA8KJ;2BAj5B+D,sDAAsD;qCAUjF,2BAA2B;iCAC/B,uBAAuB"}