@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/particles/isa/InstructionStream.js

@@ -21,7 +21,7 @@ import {
 } from "./ParticleVMISA.js";
 
 /**
- * The attribute ops take their width from their component count, so a nonsensical count would
+ * The particle field ops take their width from their component count, so a nonsensical count would
  * otherwise surface as a nonsensical width. Fail where the mistake was written instead.
  *
  * @param {number} component_count
@@ -71,8 +71,8 @@ export class InstructionStream {
      *
      * A source is what its slot's role in the ISA says: for a register-role slot, a register operand
      * word — a slot index, or `vm_register(slot, pattern)` to read it through a swizzle — or a
-     * literal from `vm_immediate(value)`; for any other role, the raw value (an attribute offset, a
-     * component count, a builtin id, a pool index). The kinds word 0 carries follow
+     * literal from `vm_immediate(value)`; for any other role, the raw value (a particle field
+     * offset, a component count, a builtin id, a pool index). The kinds word 0 carries follow
      * from that, and register operands are stored in their canonical spelling.
      *
      * `width` is the lane count the operation spans. Left out, it is the opcode's natural width —
@@ -112,13 +112,13 @@ export class InstructionStream {
 
         let requested = width === undefined ? meta.default_width : width;
 
-        // The attribute ops measure themselves in components. A store's width IS its component
+        // The particle field ops measure themselves in components. A store's width IS its component
         // count — it writes one record word per lane — so it is taken, not asked for, however the
         // instruction was built; a load merely defaults to it, since widening a load is how a narrow
-        // attribute reaches a wider operation.
-        if (op === VM_OP.STORE_ATTR) {
+        // particle field reaches a wider operation.
+        if (op === VM_OP.STORE_PARTICLE_FIELD) {
             requested = sources[2];
-        } else if (op === VM_OP.LOAD_ATTR && width === undefined) {
+        } else if (op === VM_OP.LOAD_PARTICLE_FIELD && width === undefined) {
             requested = sources[1];
         }
 
@@ -132,7 +132,7 @@ export class InstructionStream {
             assert.lessThanOrEqual(dst, VM_DST_MASK, `${meta.name} destination`);
         } else {
             // Nothing writes here, so a destination can only be a source that was put in the wrong
-            // slot — `KILL` and `STORE_ATTR` take theirs in s0.
+            // slot — `KILL` and `STORE_PARTICLE_FIELD` take theirs in s0.
             assert.equal(dst, 0, `${meta.name} writes no destination; its source goes in s0`);
         }
 
@@ -200,7 +200,7 @@ export class InstructionStream {
     }
 
     /**
-     * Lanes past `component_count` read as zero, which is how a narrow attribute widens into a
+     * Lanes past `component_count` read as zero, which is how a narrow particle field widens into a
      * wider operation without a second instruction.
      *
      * @param {number} dst
@@ -209,9 +209,9 @@ export class InstructionStream {
      * @param {number} [width] defaults to the component count
      * @returns {InstructionStream}
      */
-    loadAttr(dst, word_offset, component_count, width = undefined) {
-        assert_component_count(component_count, "LOAD_ATTR");
-        return this.emit(VM_OP.LOAD_ATTR, dst, word_offset, component_count, 0, width ?? component_count);
+    loadParticleField(dst, word_offset, component_count, width = undefined) {
+        assert_component_count(component_count, "LOAD_PARTICLE_FIELD");
+        return this.emit(VM_OP.LOAD_PARTICLE_FIELD, dst, word_offset, component_count, 0, width ?? component_count);
     }
 
     /**
@@ -223,14 +223,15 @@ export class InstructionStream {
      * @param {number} component_count
      * @returns {InstructionStream}
      */
-    storeAttr(source, word_offset, component_count) {
-        assert_component_count(component_count, "STORE_ATTR");
-        return this.emit(VM_OP.STORE_ATTR, 0, source, word_offset, component_count, component_count);
+    storeParticleField(source, word_offset, component_count) {
+        assert_component_count(component_count, "STORE_PARTICLE_FIELD");
+        return this.emit(VM_OP.STORE_PARTICLE_FIELD, 0, source, word_offset, component_count, component_count);
     }
 
     /**
      * @param {number} dst
-     * @param {number} builtin_id
+     * @param {number} builtin_id a `VM_BUILTIN`, or a field id from `vm_builtin_emitter_field` or
+     *   `vm_builtin_global_field`
      * @param {number} [width]
      * @returns {InstructionStream}
      */

package/src/shade/renderer/particles/isa/ParticleAssembler.d.ts

@@ -9,6 +9,23 @@ export class ParticleAssembler {
     update: InstructionStream;
     /** @type {number[]} flat constant pool, one float per word */
     constants: number[];
+    /**
+     * The global fields the program reads, in the order their `LOAD_BUILTIN` ids index them.
+     * @type {Array<{name: string, components: number}>}
+     */
+    global_imports: Array<{
+        name: string;
+        components: number;
+    }>;
+    /**
+     * The import index a global field is read through, importing it if this is its first read.
+     *
+     * @param {string} name
+     * @param {number} components
+     * @returns {number}
+     * @throws if the name is already imported at another width
+     */
+    global_import(name: string, components: number): number;
     /**
      * Intern a constant into the shared pool, as many words as it has components.
      *

package/src/shade/renderer/particles/isa/ParticleAssembler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleAssembler.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACI,gCAAgC;IAChC,MADW,iBAAiB,CACG;IAE/B,gCAAgC;IAChC,QADW,iBAAiB,CACK;IAEjC,8DAA8D;IAC9D,WADW,MAAM,EAAE,CACJ;IAEf;;;;;;;;;;;OAWG;IACH,oBAHc,MAAM,KACP,MAAM,CA0BlB;IAED;;OAEG;IACH,SAFa,eAAe,CAS3B;CACJ;kCAlEiC,wBAAwB;gCAC1B,sBAAsB"}
+{"version":3,"file":"ParticleAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleAssembler.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH;IACI,gCAAgC;IAChC,MADW,iBAAiB,CACG;IAE/B,gCAAgC;IAChC,QADW,iBAAiB,CACK;IAEjC,8DAA8D;IAC9D,WADW,MAAM,EAAE,CACJ;IAEf;;;OAGG;IACH,gBAFU,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAE/B;IAEpB;;;;;;;OAOG;IACH,oBALW,MAAM,cACN,MAAM,GACJ,MAAM,CAqBlB;IAED;;;;;;;;;;;OAWG;IACH,oBAHc,MAAM,KACP,MAAM,CA0BlB;IAED;;OAEG;IACH,SAFa,eAAe,CAU3B;CACJ;kCArGiC,wBAAwB;gCAC1B,sBAAsB"}

package/src/shade/renderer/particles/isa/ParticleAssembler.js

@@ -15,6 +15,40 @@ export class ParticleAssembler {
     /** @type {number[]} flat constant pool, one float per word */
     constants = [];
 
+    /**
+     * The global fields the program reads, in the order their `LOAD_BUILTIN` ids index them.
+     * @type {Array<{name: string, components: number}>}
+     */
+    global_imports = [];
+
+    /**
+     * The import index a global field is read through, importing it if this is its first read.
+     *
+     * @param {string} name
+     * @param {number} components
+     * @returns {number}
+     * @throws if the name is already imported at another width
+     */
+    global_import(name, components) {
+        const imports = this.global_imports;
+
+        for (let i = 0; i < imports.length; i++) {
+            if (imports[i].name !== name) {
+                continue;
+            }
+
+            if (imports[i].components !== components) {
+                throw new Error(`Global field '${name}' is imported with ${imports[i].components} components and ${components}`);
+            }
+
+            return i;
+        }
+
+        imports.push({ name, components });
+
+        return imports.length - 1;
+    }
+
     /**
      * Intern a constant into the shared pool, as many words as it has components.
      *
@@ -62,6 +96,7 @@ export class ParticleAssembler {
             update: this.update.toWords(),
             constants: new Float32Array(this.constants),
             register_count: Math.max(this.init.register_count, this.update.register_count),
+            global_imports: this.global_imports.map(entry => ({ ...entry })),
         });
     }
 }

package/src/shade/renderer/particles/isa/ParticleProgram.d.ts

@@ -1,6 +1,7 @@
 /**
- * A compiled particle program: two instruction streams (INIT and UPDATE) plus a shared constant
- * pool. This is the value the node compiler emits and the runtime packs into the program heap.
+ * A compiled particle program: two instruction streams (INIT and UPDATE), a shared constant pool,
+ * and the global fields it imports. This is the value the node compiler emits and the runtime
+ * packs into the program heap.
  *
  * Instruction streams are flat `Uint32Array`s, {@link PARTICLE_VM_INSTRUCTION_WORDS} words per
  * instruction. The constant pool is a flat `Float32Array`, one float per word.
@@ -12,12 +13,18 @@ export class ParticleProgram {
      * @param {Uint32Array} params.update instruction words for the UPDATE section
      * @param {Float32Array} params.constants constant pool, one float per word
      * @param {number} params.register_count register slots the program needs
+     * @param {ReadonlyArray<{name: string, components: number}>} [params.global_imports] the global
+     *   fields the program reads, in import order
      */
-    constructor({ init, update, constants, register_count }: {
+    constructor({ init, update, constants, register_count, global_imports }: {
         init: Uint32Array;
         update: Uint32Array;
         constants: Float32Array;
         register_count: number;
+        global_imports?: ReadonlyArray<{
+            name: string;
+            components: number;
+        }>;
     });
     /**
      * Instruction words for the INIT section.
@@ -39,6 +46,18 @@ export class ParticleProgram {
      * @type {number}
      */
     register_count: number;
+    /**
+     * The global fields the program reads, by name, in the order its `LOAD_BUILTIN` global ids
+     * index them. Programs are compiled with no scene present, so a global field is named here and
+     * found in the system's global layout when the program is placed — see
+     * {@link ../runtime/ProgramHeap.js}.
+     *
+     * @type {ReadonlyArray<{name: string, components: number}>}
+     */
+    global_imports: ReadonlyArray<{
+        name: string;
+        components: number;
+    }>;
     /** @returns {number} number of instructions in the INIT section */
     get init_instruction_count(): number;
     /** @returns {number} number of instructions in the UPDATE section */
@@ -61,8 +80,8 @@ export class ParticleProgram {
     get constant_words(): Uint32Array;
     /**
      * Structural equality: the same two instruction streams, the same constant pool bit for bit,
-     * and the same register budget. Two programs that compare equal are one program — the VM would
-     * execute them identically.
+     * the same register budget and the same global imports. Two programs that compare equal are one
+     * program — the VM would execute them identically.
      *
      * @param {ParticleProgram} other
      * @returns {boolean}
@@ -81,7 +100,8 @@ export class ParticleProgram {
      * The streams and the pool are duplicated rather than shared. A compiled program is treated as
      * immutable, but nothing here enforces that — the optimizer's passes read and rewrite these
      * arrays directly — so a copy that aliased the original would let a rewrite of one silently
-     * become a rewrite of both.
+     * become a rewrite of both. The imports are shared: they are read-only, and linking rewrites
+     * the placed code, not them.
      *
      * @param {ParticleProgram} other
      */

package/src/shade/renderer/particles/isa/ParticleProgram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleProgram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleProgram.js"],"names":[],"mappings":"AAUA;;;;;;GAMG;AACH;IA0BI;;;;;;OAMG;IACH;QAL+B,IAAI,EAAxB,WAAW;QACS,MAAM,EAA1B,WAAW;QACU,SAAS,EAA9B,YAAY;QACG,cAAc,EAA7B,MAAM;OAoBhB;IAjDD;;;OAGG;IACH,MAFU,WAAW,CAEhB;IAEL;;;OAGG;IACH,QAFU,WAAW,CAEd;IAEP;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,gBAFU,MAAM,CAED;IA6Bf,mEAAmE;IACnE,qCAEC;IAED,qEAAqE;IACrE,uCAEC;IAED,4FAA4F;IAC5F,kCAEC;IAED;;;;;;;;;;;;OAYG;IACH,kCAGC;IAED;;;;;;;OAOG;IACH,cAHW,eAAe,GACb,OAAO,CAWnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAalB;IAED;;;;;;;;;OASG;IACH,YAFW,eAAe,QAOzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAe3B;CACJ"}
+{"version":3,"file":"ParticleProgram.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleProgram.js"],"names":[],"mappings":"AAoCA;;;;;;;GAOG;AACH;IAoCI;;;;;;;;OAQG;IACH;QAP+B,IAAI,EAAxB,WAAW;QACS,MAAM,EAA1B,WAAW;QACU,SAAS,EAA9B,YAAY;QACG,cAAc,EAA7B,MAAM;QACqD,cAAc,GAAzE,cAAc;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAC,CAAC;OAsB3D;IA9DD;;;OAGG;IACH,MAFU,WAAW,CAEhB;IAEL;;;OAGG;IACH,QAFU,WAAW,CAEd;IAEP;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,gBAFU,MAAM,CAED;IAEf;;;;;;;OAOG;IACH,gBAFU,cAAc;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAE5C;IAgCf,mEAAmE;IACnE,qCAEC;IAED,qEAAqE;IACrE,uCAEC;IAED,4FAA4F;IAC5F,kCAEC;IAED;;;;;;;;;;;;OAYG;IACH,kCAGC;IAED;;;;;;;OAOG;IACH,cAHW,eAAe,GACb,OAAO,CAYnB;IAED;;;;;OAKG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;OAUG;IACH,YAFW,eAAe,QAQzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAe3B;CACJ"}

package/src/shade/renderer/particles/isa/ParticleProgram.js

@@ -3,14 +3,41 @@ import { is_typed_array_equals } from "../../../../core/collection/array/typed/i
 import { uint32_array_hash } from "../../../../core/collection/array/typed/uint32_array_hash.js";
 import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
 import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import {
     PARTICLE_VM_INSTRUCTION_WORDS,
     PARTICLE_VM_REGISTER_SLOTS,
 } from "../ParticleConstants.js";
 
 /**
- * A compiled particle program: two instruction streams (INIT and UPDATE) plus a shared constant
- * pool. This is the value the node compiler emits and the runtime packs into the program heap.
+ * The imports of a program that reads no global field.
+ * @type {ReadonlyArray<{name: string, components: number}>}
+ */
+const NO_IMPORTS = Object.freeze([]);
+
+/**
+ * @param {ReadonlyArray<{name: string, components: number}>} a
+ * @param {ReadonlyArray<{name: string, components: number}>} b
+ * @returns {boolean} whether both import the same fields, in the same order, at the same widths
+ */
+function imports_equal(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+
+    for (let i = 0; i < a.length; i++) {
+        if (a[i].name !== b[i].name || a[i].components !== b[i].components) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * A compiled particle program: two instruction streams (INIT and UPDATE), a shared constant pool,
+ * and the global fields it imports. This is the value the node compiler emits and the runtime
+ * packs into the program heap.
  *
  * Instruction streams are flat `Uint32Array`s, {@link PARTICLE_VM_INSTRUCTION_WORDS} words per
  * instruction. The constant pool is a flat `Float32Array`, one float per word.
@@ -41,14 +68,26 @@ export class ParticleProgram {
      */
     register_count;
 
+    /**
+     * The global fields the program reads, by name, in the order its `LOAD_BUILTIN` global ids
+     * index them. Programs are compiled with no scene present, so a global field is named here and
+     * found in the system's global layout when the program is placed — see
+     * {@link ../runtime/ProgramHeap.js}.
+     *
+     * @type {ReadonlyArray<{name: string, components: number}>}
+     */
+    global_imports;
+
     /**
      * @param {object} params
      * @param {Uint32Array} params.init instruction words for the INIT section
      * @param {Uint32Array} params.update instruction words for the UPDATE section
      * @param {Float32Array} params.constants constant pool, one float per word
      * @param {number} params.register_count register slots the program needs
+     * @param {ReadonlyArray<{name: string, components: number}>} [params.global_imports] the global
+     *   fields the program reads, in import order
      */
-    constructor({ init, update, constants, register_count }) {
+    constructor({ init, update, constants, register_count, global_imports = NO_IMPORTS }) {
         assert.ok(init instanceof Uint32Array, "init must be a Uint32Array");
         assert.ok(update instanceof Uint32Array, "update must be a Uint32Array");
         assert.ok(constants instanceof Float32Array, "constants must be a Float32Array");
@@ -66,6 +105,7 @@ export class ParticleProgram {
         this.update = update;
         this.constants = constants;
         this.register_count = register_count;
+        this.global_imports = global_imports;
     }
 
     /** @returns {number} number of instructions in the INIT section */
@@ -103,8 +143,8 @@ export class ParticleProgram {
 
     /**
      * Structural equality: the same two instruction streams, the same constant pool bit for bit,
-     * and the same register budget. Two programs that compare equal are one program — the VM would
-     * execute them identically.
+     * the same register budget and the same global imports. Two programs that compare equal are one
+     * program — the VM would execute them identically.
      *
      * @param {ParticleProgram} other
      * @returns {boolean}
@@ -117,7 +157,8 @@ export class ParticleProgram {
         return this.register_count === other.register_count
             && is_typed_array_equals(this.init, other.init)
             && is_typed_array_equals(this.update, other.update)
-            && is_typed_array_equals(this.constant_words, other.constant_words);
+            && is_typed_array_equals(this.constant_words, other.constant_words)
+            && imports_equal(this.global_imports, other.global_imports);
     }
 
     /**
@@ -129,13 +170,22 @@ export class ParticleProgram {
     hash() {
         const constant_words = this.constant_words;
 
-        return hash_mix2(
+        let imports = this.global_imports.length;
+
+        for (let i = 0; i < this.global_imports.length; i++) {
+            const entry = this.global_imports[i];
+
+            imports = hash_mix3(imports, computeStringHash(entry.name), entry.components);
+        }
+
+        return hash_mix3(
             hash_mix3(
                 uint32_array_hash(this.init, 0, this.init.length),
                 uint32_array_hash(this.update, 0, this.update.length),
                 uint32_array_hash(constant_words, 0, constant_words.length)
             ),
-            this.register_count
+            this.register_count,
+            imports
         );
     }
 
@@ -145,7 +195,8 @@ export class ParticleProgram {
      * The streams and the pool are duplicated rather than shared. A compiled program is treated as
      * immutable, but nothing here enforces that — the optimizer's passes read and rewrite these
      * arrays directly — so a copy that aliased the original would let a rewrite of one silently
-     * become a rewrite of both.
+     * become a rewrite of both. The imports are shared: they are read-only, and linking rewrites
+     * the placed code, not them.
      *
      * @param {ParticleProgram} other
      */
@@ -154,6 +205,7 @@ export class ParticleProgram {
         this.update = other.update.slice();
         this.constants = other.constants.slice();
         this.register_count = other.register_count;
+        this.global_imports = other.global_imports;
     }
 
     /**

package/src/shade/renderer/particles/isa/ParticleVMISA.d.ts

@@ -1,3 +1,23 @@
+/**
+ * @param {number} offset word offset into the emitter's block
+ * @returns {number} the `LOAD_BUILTIN` id that reads it
+ */
+export function vm_builtin_emitter_field(offset: number): number;
+/**
+ * @param {number} index an import index, or once linked a word offset into the global fields
+ * @returns {number} the `LOAD_BUILTIN` id that reads it
+ */
+export function vm_builtin_global_field(index: number): number;
+/**
+ * @param {number} id a `LOAD_BUILTIN` id
+ * @returns {boolean} whether it reads one of the emitter's fields
+ */
+export function vm_builtin_is_emitter_field(id: number): boolean;
+/**
+ * @param {number} id a `LOAD_BUILTIN` id
+ * @returns {boolean} whether it reads a global field
+ */
+export function vm_builtin_is_global_field(id: number): boolean;
 /**
  * Pack word 0.
  *
@@ -227,7 +247,7 @@ export function vm_register_kinds(op: number): number;
  * A source word means what its kind says — see {@link VM_KIND}:
  *
  * - `NONE`: not an operand the VM resolves — an unused slot, or a raw field the opcode reads for
- *   itself: an attribute offset, a component count, a builtin id, a pool index.
+ *   itself: a particle field offset, a component count, a builtin id, a pool index.
  * - `REG`: a register operand. Bits 0..7 are the first slot, bits 8..15 a swizzle — see below.
  * - `IMM`: the word IS the `f32` bit pattern of a literal, read in every lane. A scalar or a
  *   lane-uniform vector costs no register and no load; only a vector whose lanes differ still goes
@@ -273,7 +293,7 @@ export namespace VM_OPERAND {
     let NONE: string;
     let REG: string;
     let CONST: string;
-    let ATTR_OFFSET: string;
+    let PARTICLE_FIELD_OFFSET: string;
     let COMP: string;
     let BUILTIN: string;
 }
@@ -320,6 +340,37 @@ export const VM_BUILTIN_COMPONENTS: {
 export const VM_BUILTIN_PADDING: {
     [x: number]: number;
 };
+/**
+ * `LOAD_BUILTIN` ids from here up, below {@link VM_BUILTIN_GLOBAL_FIELD_BASE}, are emitter fields:
+ * the id less this is a word offset into the emitter's block. The engine's builtins are the
+ * emitter's members as the engine declares them; an effect's emitter fields are the members it
+ * declares, read the same way.
+ *
+ * A field read, emitter or global, takes the instruction's width in words, as `LOAD_CONST` does
+ * from the pool: the compiler emits a field at its own width, so no lane past it is read and none
+ * needs a padding.
+ *
+ * Wire format, like the opcode numbers.
+ *
+ * @type {number}
+ */
+export const VM_BUILTIN_EMITTER_FIELD_BASE: number;
+/**
+ * `LOAD_BUILTIN` ids from here up are global fields. In a compiled program the id less this is an
+ * index into the program's imports; once the program is placed, it is the field's word offset in
+ * the system's global layout — placing a program is what links it (see
+ * {@link ./particle_link_global_fields.js}).
+ *
+ * Wire format, like the opcode numbers.
+ *
+ * @type {number}
+ */
+export const VM_BUILTIN_GLOBAL_FIELD_BASE: number;
+/**
+ * The bits of a field id below its range, which carry the offset or the import index.
+ * @type {number}
+ */
+export const VM_BUILTIN_FIELD_INDEX_MASK: number;
 /**
  * Opcodes. Numbers are stable wire values — never renumber, only append. 19 was `SCALE` and 45 was
  * `SWIZZLE`; both are spelled by an operand swizzle now. 61 was the animation-table sampler.
@@ -331,8 +382,8 @@ export namespace VM_OP {
     let NOP: number;
     let MOV: number;
     let LOAD_CONST: number;
-    let LOAD_ATTR: number;
-    let STORE_ATTR: number;
+    let LOAD_PARTICLE_FIELD: number;
+    let STORE_PARTICLE_FIELD: number;
     let LOAD_BUILTIN: number;
     let KILL: number;
     let ADD: number;

package/src/shade/renderer/particles/isa/ParticleVMISA.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleVMISA.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleVMISA.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"ParticleVMISA.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/ParticleVMISA.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/particles/isa/ParticleVMISA.js

@@ -23,7 +23,7 @@
  * A source word means what its kind says — see {@link VM_KIND}:
  *
  * - `NONE`: not an operand the VM resolves — an unused slot, or a raw field the opcode reads for
- *   itself: an attribute offset, a component count, a builtin id, a pool index.
+ *   itself: a particle field offset, a component count, a builtin id, a pool index.
  * - `REG`: a register operand. Bits 0..7 are the first slot, bits 8..15 a swizzle — see below.
  * - `IMM`: the word IS the `f32` bit pattern of a literal, read in every lane. A scalar or a
  *   lane-uniform vector costs no register and no load; only a vector whose lanes differ still goes
@@ -74,11 +74,14 @@ export const VM_OPERAND = {
     REG: "reg",
     /** constant-pool word index */
     CONST: "const",
-    /** attribute word offset within the record */
-    ATTR_OFFSET: "attr_offset",
-    /** attribute component count `[1, 4]` */
+    /** particle field word offset within the record */
+    PARTICLE_FIELD_OFFSET: "particle_field_offset",
+    /** particle field component count `[1, 4]` */
     COMP: "comp",
-    /** builtin id (see {@link VM_BUILTIN}) */
+    /**
+     * builtin id: a {@link VM_BUILTIN}, or a field id from {@link VM_BUILTIN_EMITTER_FIELD_BASE} or
+     * {@link VM_BUILTIN_GLOBAL_FIELD_BASE} up
+     */
     BUILTIN: "builtin",
 };
 
@@ -153,6 +156,72 @@ export const VM_BUILTIN_PADDING = Object.freeze({
     [VM_BUILTIN.TIME]: 0,
 });
 
+/**
+ * `LOAD_BUILTIN` ids from here up, below {@link VM_BUILTIN_GLOBAL_FIELD_BASE}, are emitter fields:
+ * the id less this is a word offset into the emitter's block. The engine's builtins are the
+ * emitter's members as the engine declares them; an effect's emitter fields are the members it
+ * declares, read the same way.
+ *
+ * A field read, emitter or global, takes the instruction's width in words, as `LOAD_CONST` does
+ * from the pool: the compiler emits a field at its own width, so no lane past it is read and none
+ * needs a padding.
+ *
+ * Wire format, like the opcode numbers.
+ *
+ * @type {number}
+ */
+export const VM_BUILTIN_EMITTER_FIELD_BASE = 0x01000000;
+
+/**
+ * `LOAD_BUILTIN` ids from here up are global fields. In a compiled program the id less this is an
+ * index into the program's imports; once the program is placed, it is the field's word offset in
+ * the system's global layout — placing a program is what links it (see
+ * {@link ./particle_link_global_fields.js}).
+ *
+ * Wire format, like the opcode numbers.
+ *
+ * @type {number}
+ */
+export const VM_BUILTIN_GLOBAL_FIELD_BASE = 0x02000000;
+
+/**
+ * The bits of a field id below its range, which carry the offset or the import index.
+ * @type {number}
+ */
+export const VM_BUILTIN_FIELD_INDEX_MASK = 0x00ffffff;
+
+/**
+ * @param {number} offset word offset into the emitter's block
+ * @returns {number} the `LOAD_BUILTIN` id that reads it
+ */
+export function vm_builtin_emitter_field(offset) {
+    return (VM_BUILTIN_EMITTER_FIELD_BASE | (offset & VM_BUILTIN_FIELD_INDEX_MASK)) >>> 0;
+}
+
+/**
+ * @param {number} index an import index, or once linked a word offset into the global fields
+ * @returns {number} the `LOAD_BUILTIN` id that reads it
+ */
+export function vm_builtin_global_field(index) {
+    return (VM_BUILTIN_GLOBAL_FIELD_BASE | (index & VM_BUILTIN_FIELD_INDEX_MASK)) >>> 0;
+}
+
+/**
+ * @param {number} id a `LOAD_BUILTIN` id
+ * @returns {boolean} whether it reads one of the emitter's fields
+ */
+export function vm_builtin_is_emitter_field(id) {
+    return ((id & ~VM_BUILTIN_FIELD_INDEX_MASK) >>> 0) === VM_BUILTIN_EMITTER_FIELD_BASE;
+}
+
+/**
+ * @param {number} id a `LOAD_BUILTIN` id
+ * @returns {boolean} whether it reads a global field
+ */
+export function vm_builtin_is_global_field(id) {
+    return ((id & ~VM_BUILTIN_FIELD_INDEX_MASK) >>> 0) === VM_BUILTIN_GLOBAL_FIELD_BASE;
+}
+
 /**
  * Opcodes. Numbers are stable wire values — never renumber, only append. 19 was `SCALE` and 45 was
  * `SWIZZLE`; both are spelled by an operand swizzle now. 61 was the animation-table sampler.
@@ -164,8 +233,8 @@ export const VM_OP = {
     NOP: 1,
     MOV: 2,
     LOAD_CONST: 3,
-    LOAD_ATTR: 4,
-    STORE_ATTR: 5,
+    LOAD_PARTICLE_FIELD: 4,
+    STORE_PARTICLE_FIELD: 5,
     LOAD_BUILTIN: 6,
     KILL: 7,
 
@@ -234,7 +303,7 @@ export const VM_WIDTH = {
  * @enum {string}
  */
 export const VM_DEST = {
-    /** writes nothing (`HALT`, `NOP`, `STORE_ATTR`, `KILL`) */
+    /** writes nothing (`HALT`, `NOP`, `STORE_PARTICLE_FIELD`, `KILL`) */
     NONE: "none",
     /** writes as many lanes as the operation is wide */
     WIDTH: "width",
@@ -635,10 +704,10 @@ def(VM_OP.HALT, "HALT", false, _, _, _, { width: VM_WIDTH.NONE });
 def(VM_OP.NOP, "NOP", false, _, _, _, { width: VM_WIDTH.NONE });
 def(VM_OP.MOV, "MOV", true, R);
 def(VM_OP.LOAD_CONST, "LOAD_CONST", true, VM_OPERAND.CONST);
-def(VM_OP.LOAD_ATTR, "LOAD_ATTR", true, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
+def(VM_OP.LOAD_PARTICLE_FIELD, "LOAD_PARTICLE_FIELD", true, VM_OPERAND.PARTICLE_FIELD_OFFSET, VM_OPERAND.COMP);
 // The value to store is an ordinary source — a register run or a literal — and the width must equal
 // the component count, since a store cannot write lanes the value does not have.
-def(VM_OP.STORE_ATTR, "STORE_ATTR", false, R, VM_OPERAND.ATTR_OFFSET, VM_OPERAND.COMP);
+def(VM_OP.STORE_PARTICLE_FIELD, "STORE_PARTICLE_FIELD", false, R, VM_OPERAND.PARTICLE_FIELD_OFFSET, VM_OPERAND.COMP);
 def(VM_OP.LOAD_BUILTIN, "LOAD_BUILTIN", true, VM_OPERAND.BUILTIN);
 // The condition is one lane of an ordinary source.
 def(VM_OP.KILL, "KILL", false, R, _, _, { width: VM_WIDTH.ONE });