@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts

@@ -1,21 +1,22 @@
 /**
- * The per-particle state schema — a user-defined set of named attributes mapped to word offsets
- * inside the shared pool record.
+ * A field schema — a user-defined set of named fields mapped to word offsets. An effect's particle
+ * fields are laid out by one inside the shared pool record, and its emitter fields by another inside
+ * each emitter's block ({@link ParticleLayout.emitter}).
  *
  * This is the crux of the "no default state" requirement: the engine imposes no age/position/colour.
- * The effect author declares exactly the attributes their simulation needs, the VM reads/writes them
- * by the offsets this layout assigns, and the renderer is bound to specific attributes (position,
- * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
- * emitter index; user attributes are packed sequentially from
+ * The effect author declares exactly the particle fields their simulation needs, the VM
+ * reads/writes them by the offsets this layout assigns, and the renderer is bound to specific
+ * particle fields (position, size, colour, …) via a separate render binding. Word 0 of every record
+ * is reserved for the owning emitter index; particle fields are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
  *
  * ## The `type` tag
  *
- * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
- * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
- * and every instruction that touches the attribute are exactly what they were without it — and is
- * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
- * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ * A field may also say what its words are *for*: four of them tagged `color` are a colour rather
+ * than four numbers that happen to be four. It changes nothing here — the offset, the width and
+ * every instruction that touches the field are exactly what they were without it — and is read by
+ * the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type} turns the
+ * tag into a type that an editor can offer a swatch for and colour a wire by.
  *
  * A plain string rather than a type object, because the runtime schema has no business importing a
  * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
@@ -23,30 +24,63 @@
  */
 export class ParticleLayout {
     /**
-     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
-     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
-     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
+     * A layout for an emitter's block of emitter fields: packed from word zero, with no fixed size.
+     * The block is allocated to fit it (see {@link ../runtime/ProgramHeap.js}), so there is no record
+     * width for it to outgrow.
+     *
+     * @param {Array<{name: string, components: number, type?: string}>} fields ordered field
+     *   declarations
+     * @returns {ParticleLayout}
+     */
+    static emitter(fields: Array<{
+        name: string;
+        components: number;
+        type?: string;
+    }>): ParticleLayout;
+    /**
+     * @param {Array<{name: string, components: number, type?: string}>} fields ordered field
+     *   declarations. `type` optionally says what the words are *for* — see the class note on the
+     *   `type` tag — and never what shape they are, which is `components` and only that.
+     * @param {object} [options]
+     * @param {number} [options.first_word] the word the first field is packed at: past the particle
+     *   record's header by default
+     * @param {number} [options.word_capacity] the word the fields may not extend past: the particle
+     *   record's width by default
+     * @throws on a duplicate name, or fields that extend past `word_capacity`
      */
-    constructor(attributes: Array<{
+    constructor(fields: Array<{
         name: string;
         components: number;
         type?: string;
-    }>);
+    }>, { first_word, word_capacity, }?: {
+        first_word?: number;
+        word_capacity?: number;
+    });
     /**
-     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * Field name -> where it sits in the record or block, how wide it is, and what it is for.
      * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
      */
-    attributes: Map<string, {
+    fields: Map<string, {
         name: string;
         offset: number;
         components: number;
         type: string | undefined;
     }>;
     /**
-     * First free word after all attributes.
+     * Word the first field is packed at.
+     * @type {number}
+     */
+    first_word: number;
+    /**
+     * First free word after all fields.
      * @type {number}
      */
     word_cursor: number;
+    /**
+     * How many words the fields take, from {@link first_word} to {@link word_cursor}.
+     * @returns {number}
+     */
+    get word_count(): number;
     /**
      * @param {string} name
      * @returns {boolean}
@@ -63,21 +97,21 @@ export class ParticleLayout {
     };
     /**
      * @param {string} name
-     * @returns {number} word offset of the attribute within a record
+     * @returns {number} word offset of the field within the record or block
      */
     offsetOf(name: string): number;
     /**
      * @param {string} name
-     * @returns {number} component count of the attribute
+     * @returns {number} component count of the field
      */
     componentsOf(name: string): number;
     /**
-     * Structural equality: the same attributes, by name, at the same offsets, the same width, and
-     * tagged the same. Two layouts that compare equal describe one particle record — a program
-     * compiled against either reads and writes the same words.
+     * Structural equality: the same fields, by name, at the same offsets, the same width, and
+     * tagged the same. A program compiled against either of two equal layouts reads and writes the
+     * same words.
      *
      * Declaration order is not compared separately because it cannot differ without an offset
-     * differing: attributes are packed sequentially in the order they were declared.
+     * differing: fields are packed sequentially in the order they were declared.
      *
      * @param {ParticleLayout} other
      * @returns {boolean}
@@ -86,10 +120,10 @@ export class ParticleLayout {
     /**
      * Hash over everything {@link ParticleLayout#equals} compares.
      *
-     * Per-attribute hashes are summed rather than folded in iteration order. A `Map` iterates in
+     * Per-field hashes are summed rather than folded in iteration order. A `Map` iterates in
      * insertion order and equal layouts are built in the same order, so a fold would agree — but a
-     * commutative combine says outright that the hash is of a set of attributes, and holds even if
-     * a layout is ever built by some other route.
+     * commutative combine says outright that the hash is of a set of fields, and holds even if a
+     * layout is ever built by some other route.
      *
      * @returns {number} int32
      */

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAcI;;;;OAIG;IACH,wBAJW,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,EAyClE;IAtDD;;;OAGG;IACH,YAFU,IAAI,MAAM,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAA;KAAC,CAAC,CAE1E;IAEvB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IA8C9C;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,cAHW,cAAc,GACZ,OAAO,CA8BnB;IAED;;;;;;;;;OASG;IACH,QAFa,MAAM,CAclB;CACJ"}
+{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA4EI;;;;;;;;OAQG;IACH,uBAJW,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,GAEtD,cAAc,CAI1B;IAnED;;;;;;;;;;OAUG;IACH,oBAVW,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;QAIvC,UAAU,GAA3B,MAAM;QAEW,aAAa,GAA9B,MAAM;OA+ChB;IAxED;;;OAGG;IACH,QAFU,IAAI,MAAM,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAA;KAAC,CAAC,CAE9E;IAEnB;;;OAGG;IACH,YAFU,MAAM,CAE6B;IAE7C;;;OAGG;IACH,aAFU,MAAM,CAE8B;IAuE9C;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;OAUG;IACH,cAHW,cAAc,GACZ,OAAO,CA8BnB;IAED;;;;;;;;;OASG;IACH,QAFa,MAAM,CAclB;CACJ"}

package/src/shade/renderer/particles/layout/ParticleLayout.js

@@ -8,23 +8,24 @@ import {
 } from "../ParticleConstants.js";
 
 /**
- * The per-particle state schema — a user-defined set of named attributes mapped to word offsets
- * inside the shared pool record.
+ * A field schema — a user-defined set of named fields mapped to word offsets. An effect's particle
+ * fields are laid out by one inside the shared pool record, and its emitter fields by another inside
+ * each emitter's block ({@link ParticleLayout.emitter}).
  *
  * This is the crux of the "no default state" requirement: the engine imposes no age/position/colour.
- * The effect author declares exactly the attributes their simulation needs, the VM reads/writes them
- * by the offsets this layout assigns, and the renderer is bound to specific attributes (position,
- * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
- * emitter index; user attributes are packed sequentially from
+ * The effect author declares exactly the particle fields their simulation needs, the VM
+ * reads/writes them by the offsets this layout assigns, and the renderer is bound to specific
+ * particle fields (position, size, colour, …) via a separate render binding. Word 0 of every record
+ * is reserved for the owning emitter index; particle fields are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
  *
  * ## The `type` tag
  *
- * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
- * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
- * and every instruction that touches the attribute are exactly what they were without it — and is
- * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
- * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ * A field may also say what its words are *for*: four of them tagged `color` are a colour rather
+ * than four numbers that happen to be four. It changes nothing here — the offset, the width and
+ * every instruction that touches the field are exactly what they were without it — and is read by
+ * the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type} turns the
+ * tag into a type that an editor can offer a swatch for and colour a wire by.
  *
  * A plain string rather than a type object, because the runtime schema has no business importing a
  * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
@@ -33,67 +34,106 @@ import {
 export class ParticleLayout {
 
     /**
-     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * Field name -> where it sits in the record or block, how wide it is, and what it is for.
      * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
      */
-    attributes = new Map();
+    fields = new Map();
 
     /**
-     * First free word after all attributes.
+     * Word the first field is packed at.
+     * @type {number}
+     */
+    first_word = PARTICLE_RECORD_USER_WORD_START;
+
+    /**
+     * First free word after all fields.
      * @type {number}
      */
     word_cursor = PARTICLE_RECORD_USER_WORD_START;
 
     /**
-     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
-     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
-     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
+     * @param {Array<{name: string, components: number, type?: string}>} fields ordered field
+     *   declarations. `type` optionally says what the words are *for* — see the class note on the
+     *   `type` tag — and never what shape they are, which is `components` and only that.
+     * @param {object} [options]
+     * @param {number} [options.first_word] the word the first field is packed at: past the particle
+     *   record's header by default
+     * @param {number} [options.word_capacity] the word the fields may not extend past: the particle
+     *   record's width by default
+     * @throws on a duplicate name, or fields that extend past `word_capacity`
      */
-    constructor(attributes) {
-        assert.isArray(attributes, "attributes");
+    constructor(fields, {
+        first_word = PARTICLE_RECORD_USER_WORD_START,
+        word_capacity = PARTICLE_RECORD_WORD_COUNT,
+    } = {}) {
+        assert.isArray(fields, "fields");
+        assert.isNonNegativeInteger(first_word, "first_word");
 
-        let cursor = PARTICLE_RECORD_USER_WORD_START;
+        this.first_word = first_word;
 
-        for (const attribute of attributes) {
-            assert.isString(attribute.name, "attribute.name");
-            assert.isNonNegativeInteger(attribute.components, "attribute.components");
-            assert.greaterThanOrEqual(attribute.components, 1, "attribute.components must be >= 1");
-            assert.lessThanOrEqual(attribute.components, 4, "attribute.components must be <= 4");
+        let cursor = first_word;
 
-            if (attribute.type !== undefined) {
-                assert.isString(attribute.type, "attribute.type");
+        for (const field of fields) {
+            assert.isString(field.name, "field.name");
+            assert.isNonNegativeInteger(field.components, "field.components");
+            assert.greaterThanOrEqual(field.components, 1, "field.components must be >= 1");
+            assert.lessThanOrEqual(field.components, 4, "field.components must be <= 4");
+
+            if (field.type !== undefined) {
+                assert.isString(field.type, "field.type");
             }
 
-            if (this.attributes.has(attribute.name)) {
-                throw new Error(`Duplicate particle attribute '${attribute.name}'`);
+            if (this.fields.has(field.name)) {
+                throw new Error(`Duplicate field '${field.name}'`);
             }
 
-            this.attributes.set(attribute.name, {
-                name: attribute.name,
+            this.fields.set(field.name, {
+                name: field.name,
                 offset: cursor,
-                components: attribute.components,
-                type: attribute.type,
+                components: field.components,
+                type: field.type,
             });
 
-            cursor += attribute.components;
+            cursor += field.components;
         }
 
         this.word_cursor = cursor;
 
-        if (cursor > PARTICLE_RECORD_WORD_COUNT) {
+        if (cursor > word_capacity) {
             throw new Error(
-                `Particle layout needs ${cursor} words but the record holds only ${PARTICLE_RECORD_WORD_COUNT}. ` +
-                `Reduce attributes or raise PARTICLE_RECORD_WORD_COUNT.`
+                `Particle layout needs ${cursor} words but the record holds only ${word_capacity}. ` +
+                `Reduce fields or raise PARTICLE_RECORD_WORD_COUNT.`
             );
         }
     }
 
+    /**
+     * A layout for an emitter's block of emitter fields: packed from word zero, with no fixed size.
+     * The block is allocated to fit it (see {@link ../runtime/ProgramHeap.js}), so there is no record
+     * width for it to outgrow.
+     *
+     * @param {Array<{name: string, components: number, type?: string}>} fields ordered field
+     *   declarations
+     * @returns {ParticleLayout}
+     */
+    static emitter(fields) {
+        return new ParticleLayout(fields, { first_word: 0, word_capacity: Infinity });
+    }
+
+    /**
+     * How many words the fields take, from {@link first_word} to {@link word_cursor}.
+     * @returns {number}
+     */
+    get word_count() {
+        return this.word_cursor - this.first_word;
+    }
+
     /**
      * @param {string} name
      * @returns {boolean}
      */
     has(name) {
-        return this.attributes.has(name);
+        return this.fields.has(name);
     }
 
     /**
@@ -101,16 +141,16 @@ export class ParticleLayout {
      * @returns {{name: string, offset: number, components: number}}
      */
     get(name) {
-        const attribute = this.attributes.get(name);
-        if (attribute === undefined) {
-            throw new Error(`Unknown particle attribute '${name}'`);
+        const field = this.fields.get(name);
+        if (field === undefined) {
+            throw new Error(`Unknown field '${name}'`);
         }
-        return attribute;
+        return field;
     }
 
     /**
      * @param {string} name
-     * @returns {number} word offset of the attribute within a record
+     * @returns {number} word offset of the field within the record or block
      */
     offsetOf(name) {
         return this.get(name).offset;
@@ -118,19 +158,19 @@ export class ParticleLayout {
 
     /**
      * @param {string} name
-     * @returns {number} component count of the attribute
+     * @returns {number} component count of the field
      */
     componentsOf(name) {
         return this.get(name).components;
     }
 
     /**
-     * Structural equality: the same attributes, by name, at the same offsets, the same width, and
-     * tagged the same. Two layouts that compare equal describe one particle record — a program
-     * compiled against either reads and writes the same words.
+     * Structural equality: the same fields, by name, at the same offsets, the same width, and
+     * tagged the same. A program compiled against either of two equal layouts reads and writes the
+     * same words.
      *
      * Declaration order is not compared separately because it cannot differ without an offset
-     * differing: attributes are packed sequentially in the order they were declared.
+     * differing: fields are packed sequentially in the order they were declared.
      *
      * @param {ParticleLayout} other
      * @returns {boolean}
@@ -140,23 +180,23 @@ export class ParticleLayout {
             return true;
         }
 
-        const attributes = this.attributes;
+        const fields = this.fields;
 
-        if (attributes.size !== other.attributes.size) {
+        if (fields.size !== other.fields.size) {
             return false;
         }
 
-        for (const [name, attribute] of attributes) {
-            const candidate = other.attributes.get(name);
+        for (const [name, field] of fields) {
+            const candidate = other.fields.get(name);
 
             if (candidate === undefined) {
                 return false;
             }
 
             if (
-                candidate.offset !== attribute.offset
-                || candidate.components !== attribute.components
-                || candidate.type !== attribute.type
+                candidate.offset !== field.offset
+                || candidate.components !== field.components
+                || candidate.type !== field.type
             ) {
                 return false;
             }
@@ -168,21 +208,21 @@ export class ParticleLayout {
     /**
      * Hash over everything {@link ParticleLayout#equals} compares.
      *
-     * Per-attribute hashes are summed rather than folded in iteration order. A `Map` iterates in
+     * Per-field hashes are summed rather than folded in iteration order. A `Map` iterates in
      * insertion order and equal layouts are built in the same order, so a fold would agree — but a
-     * commutative combine says outright that the hash is of a set of attributes, and holds even if
-     * a layout is ever built by some other route.
+     * commutative combine says outright that the hash is of a set of fields, and holds even if a
+     * layout is ever built by some other route.
      *
      * @returns {number} int32
      */
     hash() {
-        let hash = this.attributes.size;
+        let hash = this.fields.size;
 
-        for (const [name, attribute] of this.attributes) {
+        for (const [name, field] of this.fields) {
             hash = (hash + hash_mix3(
                 computeStringHash(name),
-                hash_mix2(attribute.offset, attribute.components),
-                computeStringHash(attribute.type)
+                hash_mix2(field.offset, field.components),
+                computeStringHash(field.type)
             )) | 0;
         }
 

package/src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimize_particle_program_vector.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AAEH;;;;GAIG;AACH,0DAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAI3B;AAED;;;;;;;;;;GAUG;AACH,iEAVW,eAAe;IAEE,cAAc,GAA/B,MAAM;IACY,YAAY,GAA9B,OAAO;IACW,qBAAqB,GAAvC,OAAO;IACW,iBAAiB,GAAnC,OAAO;IACW,WAAW,GAA7B,OAAO;IACY,aAAa,GAAhC,MAAM,EAAE;IACN,6BAA6B,CAwCzC;AAhGD;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,4CAFU,MAAM,EAAE,CAEqE;;aAIzE,eAAe;;;;eACf,OAAO;;;;kBACP,MAAM;;;;eACN,MAAM;;gCA9CY,8BAA8B"}
+{"version":3,"file":"optimize_particle_program_vector.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js"],"names":[],"mappings":"AA4CA;;;;;;GAMG;AAEH;;;;GAIG;AACH,0DAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAI3B;AAED;;;;;;;;;;GAUG;AACH,iEAVW,eAAe;IAEE,cAAc,GAA/B,MAAM;IACY,YAAY,GAA9B,OAAO;IACW,qBAAqB,GAAvC,OAAO;IACW,iBAAiB,GAAnC,OAAO;IACW,WAAW,GAA7B,OAAO;IACY,aAAa,GAAhC,MAAM,EAAE;IACN,6BAA6B,CAyCzC;AAjGD;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,4CAFU,MAAM,EAAE,CAEqE;;aAIzE,eAAe;;;;eACf,OAAO;;;;kBACP,MAAM;;;;eACN,MAAM;;gCA9CY,8BAA8B"}

package/src/shade/renderer/particles/optimizer/dag/optimize_particle_program_vector.js

@@ -98,6 +98,7 @@ export function optimize_particle_program_vector_result(program, {
         update: update.toWords(),
         constants: new Float32Array(assembler.constants),
         register_count: Math.max(init.register_count, update.register_count),
+        global_imports: program.global_imports,
     });
 
     const finished = compact_registers ? compact(rebuilt, register_slots) : rebuilt;
@@ -204,6 +205,7 @@ function compact(program, register_slots) {
         update: update.toWords(),
         constants: program.constants,
         register_count: Math.max(init.register_count, update.register_count),
+        global_imports: program.global_imports,
     });
 }
 

package/src/shade/renderer/particles/optimizer/dag/particle_vector_groups.js

@@ -22,7 +22,7 @@ export const PV_GROUP = {
     CONSTANT: "constant",
     /** a run assembled one lane at a time, one `MOV` per entry of `gather` */
     GATHER: "gather",
-    /** a `STORE_ATTR`; writes no run */
+    /** a `STORE_PARTICLE_FIELD`; writes no run */
     STORE: "store",
     /** a `KILL`; writes no run */
     KILL: "kill",

package/src/shade/renderer/particles/optimizer/dag/particle_vector_lift.js

@@ -314,7 +314,7 @@ function evaluate(graph, instruction, operands, state) {
             return lanes_of(graph, graph.constant(...values), dest);
         }
 
-        case VM_OP.LOAD_ATTR: {
+        case VM_OP.LOAD_PARTICLE_FIELD: {
             if (words[1] + Math.min(dest, words[2]) > PARTICLE_RECORD_WORD_COUNT) {
                 return null;
             }
@@ -331,7 +331,7 @@ function evaluate(graph, instruction, operands, state) {
             return places;
         }
 
-        case VM_OP.STORE_ATTR: {
+        case VM_OP.STORE_PARTICLE_FIELD: {
             if (words[2] + words[3] > PARTICLE_RECORD_WORD_COUNT) {
                 return null;
             }
@@ -350,7 +350,8 @@ function evaluate(graph, instruction, operands, state) {
         }
 
         // Never folded past the builtin's component count: `EMITTER_POSITION` reads `1.0` in its
-        // fourth lane on both executors.
+        // fourth lane on both executors, and an emitter or global field's lanes past its width are
+        // not the field's: the WGSL reads the words after it, the reference VM zero.
         case VM_OP.LOAD_BUILTIN:
             return node({ op, width: dest, imm: [words[1]] });
 

package/src/shade/renderer/particles/optimizer/dag/particle_vector_lower.js

@@ -81,7 +81,7 @@ export function lower_particle_values(packing, { register_slots, intern_constant
  */
 export function build_group_dependencies(groups) {
     const predecessors = groups.map(() => new Set());
-    const loads = groups.filter(group => group.op === VM_OP.LOAD_ATTR);
+    const loads = groups.filter(group => group.op === VM_OP.LOAD_PARTICLE_FIELD);
 
     for (const group of groups) {
         for (const operand of group.operands) {
@@ -100,7 +100,7 @@ export function build_group_dependencies(groups) {
         // a word that had been stored, so what is left is loads of the word AS THE SECTION FOUND IT —
         // and those are only true until something stores over that word. The value is a fact about
         // the record before the section ran; the INSTRUCTION that fetches it is not.
-        if (group.op === VM_OP.STORE_ATTR) {
+        if (group.op === VM_OP.STORE_PARTICLE_FIELD) {
             for (const load of loads) {
                 if (words_overlap(load.raw[0], load.raw[1], group.raw[1], group.raw[2])) {
                     predecessors[group.index].add(load.index);

package/src/shade/renderer/particles/optimizer/dag/particle_vector_pack.d.ts

@@ -21,9 +21,9 @@
  */
 export function pack_particle_vectors(graph: import("./particle_vector_graph.js").ParticleVectorGraph, section: import("./particle_vector_lift.js").ParticleLiftedVectorSection, extraction: import("./particle_vector_extract.js").ParticleValueExtraction): import("./particle_vector_groups.js").ParticleValuePacking;
 /**
- * Which record words go in one `STORE_ATTR`: consecutive words, taken from one value, no more than
- * the four an operand spans — and cut where the original stores cut, so that a `vec3` position and a
- * `vec4` colour in adjacent words stay two stores.
+ * Which record words go in one `STORE_PARTICLE_FIELD`: consecutive words, taken from one value, no
+ * more than the four an operand spans — and cut where the original stores cut, so that a `vec3`
+ * position and a `vec4` colour in adjacent words stay two stores.
  *
  * @param {Array<{word: number, place: {value: number, lane: number}, origin: number}>} stores
  * @returns {Array<Array<{word: number, place: {value: number, lane: number}, origin: number}>>}

package/src/shade/renderer/particles/optimizer/dag/particle_vector_pack.js

@@ -151,7 +151,7 @@ export function pack_particle_vectors(graph, section, extraction) {
 
         if (node.op === PV.ATTR) {
             const group = add({
-                op: VM_OP.LOAD_ATTR,
+                op: VM_OP.LOAD_PARTICLE_FIELD,
                 width,
                 span: width,
                 raw: [node.imm[0], width, -1],
@@ -204,10 +204,10 @@ export function pack_particle_vectors(graph, section, extraction) {
 
         for (let source = 0; source < node.children.length; source++) {
             group.operands.push(operand(
-                source,
+                source,
                 node.children[source],
                 node.patterns[source],
-                group.width,
+                group.width,
                 sequence
             ));
         }
@@ -224,7 +224,7 @@ export function pack_particle_vectors(graph, section, extraction) {
     for (const chunk of chunk_stores(section.stores)) {
         const group = add({
             kind: PV_GROUP.STORE,
-            op: VM_OP.STORE_ATTR,
+            op: VM_OP.STORE_PARTICLE_FIELD,
             width: chunk.length,
             span: 0,
             raw: [-1, chunk[0].word, chunk.length],
@@ -436,9 +436,9 @@ function dissolve_builds(packing, add) {
             operand.group = gone.anchor;
         }
 
-        // A build may read a build — a four-wide load of a three-component attribute is a build, and
-        // anything assembled from it reads one. Those lanes are copies still to be made, so they take
-        // the run each lane ended up in rather than a window into it.
+        // A build may read a build — a four-wide load of a three-component particle field is a
+        // build, and anything assembled from it reads one. Those lanes are copies still to be made,
+        // so they take the run each lane ended up in rather than a window into it.
         group.gather = group.gather.map(source => {
             const gone = dissolved.get(source.group);
 
@@ -659,9 +659,9 @@ function store_operand(graph, of, groups, chunk, add, where) {
 }
 
 /**
- * Which record words go in one `STORE_ATTR`: consecutive words, taken from one value, no more than
- * the four an operand spans — and cut where the original stores cut, so that a `vec3` position and a
- * `vec4` colour in adjacent words stay two stores.
+ * Which record words go in one `STORE_PARTICLE_FIELD`: consecutive words, taken from one value, no
+ * more than the four an operand spans — and cut where the original stores cut, so that a `vec3`
+ * position and a `vec4` colour in adjacent words stay two stores.
  *
  * @param {Array<{word: number, place: {value: number, lane: number}, origin: number}>} stores
  * @returns {Array<Array<{word: number, place: {value: number, lane: number}, origin: number}>>}
@@ -760,7 +760,7 @@ function measure_demand(graph, section, extraction) {
             continue;
         }
 
-        const reads = Math.max(narrowable(node) ? width : node.operand_width, VM_ISA.get(node.op)?.min_width ?? 1);
+        const reads = Math.max(narrowable(node) ? width : node.operand_width, VM_ISA.get(node.op)?.min_width ?? 1);
 
         for (let source = 0; source < node.children.length; source++) {
             let highest = 0;

package/src/shade/renderer/particles/optimizer/optimize_particle_program.d.ts

@@ -96,10 +96,10 @@ export function stream_from_words(words: Uint32Array): InstructionStream;
  *
  * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
  * nothing". All but one never reorder: every pass rewrites an instruction in place or drops it,
- * which is what makes the ordering constraints — `RANDOM`'s draw sequence, `STORE_ATTR`/`LOAD_ATTR`
- * aliasing — hold structurally rather than by each pass remembering them. The one that does,
- * `pass_schedule`, moves nothing across an instruction with side effects, which keeps the same
- * constraints structural for it.
+ * which is what makes the ordering constraints — `RANDOM`'s draw sequence,
+ * `STORE_PARTICLE_FIELD`/`LOAD_PARTICLE_FIELD` aliasing — hold structurally rather than by each
+ * pass remembering them. The one that does, `pass_schedule`, moves nothing across an instruction
+ * with side effects, which keeps the same constraints structural for it.
  *
  * The pipeline sweeps the enabled passes in order until a whole sweep changes nothing or
  * `max_iterations` sweeps have run, then schedules, allocates and packs the register file — and

package/src/shade/renderer/particles/optimizer/optimize_particle_program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimize_particle_program.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js"],"names":[],"mappings":"AA+IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kDAxBW,iBAAiB;IAEW,SAAS,GAArC,UAAU,MAAM,CAAC;IAEoB,eAAe,UAA3C,MAAM,EAAE,KAAG,MAAM;IACM,MAAM,GAAtC,cAAc,MAAM,CAAC;IAEJ,cAAc,GAA/B,MAAM;IACY,SAAS,GAA3B,OAAO;IAGU,cAAc,GAA/B,MAAM;IACY,qBAAqB,GAAvC,OAAO;IACW,YAAY,GAA9B,OAAO;IACW,mBAAmB,GAArC,OAAO;IAEU,gBAAgB,GAAjC,MAAM;IACY,iBAAiB,GAAnC,OAAO;IACW,uBAAuB,GAAzC,OAAO;IACW,oBAAoB,GAAtC,OAAO;IACW,WAAW,GAA7B,OAAO;IACL,iBAAiB,CAqC7B;AAuFD;;;;;;GAMG;AACH,iDAHc,MAAM,KACP,MAAM,EAAE,CAIpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,mDAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAsC3B;AAsFD;;;GAGG;AACH,yCAHW,WAAW,GACT,iBAAiB,CAU7B;AAnbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,wCAFU,MAAM;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAC,CAAC,CAwBrH;AAEF;;;;;;;;GAQG;AACH,gDAFU,cAAc,MAAM,CAAC,CAI7B;AAEF;;;;;;;;GAQG;AACH,oDAFU,MAAM,CAEuC;mDAnE5C,MAAM,EAAE,EAAE,WACV,wBAAwB,KACtB,MAAM,EAAE,EAAE,GAAC,IAAI;;;;;eAKd,UAAU,MAAM,CAAC;;;;;;qBACjB,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,GAAC,IAAI;;;;oBAGnC,MAAM;;;;oBACN,MAAM;;kCApFc,6BAA6B;gCAE/B,2BAA2B"}
+{"version":3,"file":"optimize_particle_program.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js"],"names":[],"mappings":"AA+IA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kDAxBW,iBAAiB;IAEW,SAAS,GAArC,UAAU,MAAM,CAAC;IAEoB,eAAe,UAA3C,MAAM,EAAE,KAAG,MAAM;IACM,MAAM,GAAtC,cAAc,MAAM,CAAC;IAEJ,cAAc,GAA/B,MAAM;IACY,SAAS,GAA3B,OAAO;IAGU,cAAc,GAA/B,MAAM;IACY,qBAAqB,GAAvC,OAAO;IACW,YAAY,GAA9B,OAAO;IACW,mBAAmB,GAArC,OAAO;IAEU,gBAAgB,GAAjC,MAAM;IACY,iBAAiB,GAAnC,OAAO;IACW,uBAAuB,GAAzC,OAAO;IACW,oBAAoB,GAAtC,OAAO;IACW,WAAW,GAA7B,OAAO;IACL,iBAAiB,CAqC7B;AAuFD;;;;;;GAMG;AACH,iDAHc,MAAM,KACP,MAAM,EAAE,CAIpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,mDAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAuC3B;AAsFD;;;GAGG;AACH,yCAHW,WAAW,GACT,iBAAiB,CAU7B;AApbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,wCAFU,MAAM;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAC,CAAC,CAwBrH;AAEF;;;;;;;;GAQG;AACH,gDAFU,cAAc,MAAM,CAAC,CAI7B;AAEF;;;;;;;;GAQG;AACH,oDAFU,MAAM,CAEuC;mDAnE5C,MAAM,EAAE,EAAE,WACV,wBAAwB,KACtB,MAAM,EAAE,EAAE,GAAC,IAAI;;;;;eAKd,UAAU,MAAM,CAAC;;;;;;qBACjB,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC,GAAC,IAAI;;;;oBAGnC,MAAM;;;;oBACN,MAAM;;kCApFc,6BAA6B;gCAE/B,2BAA2B"}

package/src/shade/renderer/particles/optimizer/optimize_particle_program.js

@@ -40,10 +40,10 @@ import { PARTICLE_PASS_SCHEDULE, pass_schedule } from "./pass_schedule.js";
  *
  * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
  * nothing". All but one never reorder: every pass rewrites an instruction in place or drops it,
- * which is what makes the ordering constraints — `RANDOM`'s draw sequence, `STORE_ATTR`/`LOAD_ATTR`
- * aliasing — hold structurally rather than by each pass remembering them. The one that does,
- * `pass_schedule`, moves nothing across an instruction with side effects, which keeps the same
- * constraints structural for it.
+ * which is what makes the ordering constraints — `RANDOM`'s draw sequence,
+ * `STORE_PARTICLE_FIELD`/`LOAD_PARTICLE_FIELD` aliasing — hold structurally rather than by each
+ * pass remembering them. The one that does, `pass_schedule`, moves nothing across an instruction
+ * with side effects, which keeps the same constraints structural for it.
  *
  * The pipeline sweeps the enabled passes in order until a whole sweep changes nothing or
  * `max_iterations` sweeps have run, then schedules, allocates and packs the register file — and
@@ -356,6 +356,7 @@ export function optimize_particle_program(program, options = {}) {
         update: update_words,
         constants,
         register_count: Math.max(init.register_count, update.register_count),
+        global_imports: program.global_imports,
     });
 }