@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/graph_particles_billboard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Loads the colour target, depth-tests read-only against the scene, and draws
+ * `drawIndirect(draw_args)` instances over `draw_list`.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.camera graph handle of the camera uniform buffer
+ * @param {number} params.color graph handle of the colour target the billboards draw over
+ * @param {number} params.depth graph handle of the scene depth, tested against and never written
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.draw_list graph handle of the slot list to draw, in draw order
+ * @param {number} params.emitter_database graph handle
+ * @param {number} params.draw_args graph handle of the indirect draw args: six vertices, one
+ *   instance per live particle, written on-GPU by this frame's build-indirect pass
+ * @param {object} params.render
+ * @param {GPUTextureView} params.render.atlas sprite atlas
+ * @param {GPUSampler} params.render.atlas_sampler
+ * @param {(color_format: string, depth_format: string) => object} params.render.obtain_pipeline
+ *   the billboard pipeline for the frame's attachment formats
+ * @returns {number} the colour handle after the draw
+ */
+export function graph_particles_billboard({ graph, camera, color, depth, pool, draw_list, emitter_database, draw_args, render }: {
+    graph: import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    camera: number;
+    color: number;
+    depth: number;
+    pool: number;
+    draw_list: number;
+    emitter_database: number;
+    draw_args: number;
+    render: {
+        atlas: GPUTextureView;
+        atlas_sampler: GPUSampler;
+        obtain_pipeline: (color_format: string, depth_format: string) => object;
+    };
+}): number;
+//# sourceMappingURL=graph_particles_billboard.d.ts.map

package/src/shade/renderer/particles/graph_particles_billboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph_particles_billboard.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/graph_particles_billboard.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;WAhBW,OAAO,2DAA2D,EAAE,UAAU;YAC9E,MAAM;WACN,MAAM;WACN,MAAM;UACN,MAAM;eACN,MAAM;sBACN,MAAM;eACN,MAAM;;;;wCAKS,MAAM,gBAAgB,MAAM,KAAK,MAAM;;IAEpD,MAAM,CAuDlB"}

package/src/shade/renderer/particles/graph_particles_billboard.js

@@ -0,0 +1,93 @@
+import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
+import { DEFAULT_DEPTH_TEXTURE_VIEW } from "../depth/DEFAULT_DEPTH_TEXTURE_VIEW.js";
+import { PARTICLE_BILLBOARD_RESOURCES } from "./shaders/shader_particle_render.js";
+
+/**
+ * The particle system's standalone drawing: one instanced billboard draw over a colour target with
+ * fixed-function blending, for {@link ParticleRenderMode.BILLBOARD}. The renderer's own path draws
+ * through `graph_particles_avboit.js` instead; these two files are the alternatives
+ * {@link GPUParticleSystem#execute} picks between, and both read the handles the simulation left.
+ *
+ * The draw list is a parameter rather than a buffer this file names, because what it must be is a
+ * property of the caller's blend state: premultiplied over-blending is order-dependent, so the
+ * standalone path hands in the back-to-front list `sort/graph_particle_sort.js` produced.
+ */
+
+/** The colour attachment's view: one mip, the one the frame draws into. */
+const COLOR_VIEW = TextureViewDescriptor.from({ mipLevelCount: 1, baseMipLevel: 0 });
+
+/**
+ * Loads the colour target, depth-tests read-only against the scene, and draws
+ * `drawIndirect(draw_args)` instances over `draw_list`.
+ *
+ * @param {object} params
+ * @param {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
+ * @param {number} params.camera graph handle of the camera uniform buffer
+ * @param {number} params.color graph handle of the colour target the billboards draw over
+ * @param {number} params.depth graph handle of the scene depth, tested against and never written
+ * @param {number} params.pool graph handle of the particle pool
+ * @param {number} params.draw_list graph handle of the slot list to draw, in draw order
+ * @param {number} params.emitter_database graph handle
+ * @param {number} params.draw_args graph handle of the indirect draw args: six vertices, one
+ *   instance per live particle, written on-GPU by this frame's build-indirect pass
+ * @param {object} params.render
+ * @param {GPUTextureView} params.render.atlas sprite atlas
+ * @param {GPUSampler} params.render.atlas_sampler
+ * @param {(color_format: string, depth_format: string) => object} params.render.obtain_pipeline
+ *   the billboard pipeline for the frame's attachment formats
+ * @returns {number} the colour handle after the draw
+ */
+export function graph_particles_billboard({ graph, camera, color, depth, pool, draw_list, emitter_database, draw_args, render }) {
+    const data = {};
+
+    const pass = graph.add("Particle Billboard", data, (data, resources, context) => {
+        const encoder = context.encoder;
+
+        const color_texture = resources.get(data.color);
+        const depth_texture = resources.get(data.depth);
+
+        const pipeline = render.obtain_pipeline(color_texture.descriptor.format, depth_texture.descriptor.format);
+
+        // Read by the soft-depth fade and tested against by the pass: the same view, read-only in
+        // both roles.
+        const depth_view = depth_texture.obtainView(DEFAULT_DEPTH_TEXTURE_VIEW);
+
+        const bindings = PARTICLE_BILLBOARD_RESOURCES.generateBindings({
+            camera: resources.get(data.camera),
+            pool: resources.get(data.pool),
+            draw_list: resources.get(data.draw_list),
+            emitter_database: resources.get(data.emitter_database),
+            atlas: render.atlas,
+            atlas_sampler: render.atlas_sampler,
+            scene_depth: depth_view,
+        }, encoder);
+
+        const render_pass = encoder.constructRenderPass({
+            label: "Particle Billboard",
+            pipeline,
+            bindings,
+            colorAttachments: [{
+                view: color_texture.obtainView(COLOR_VIEW),
+                loadOp: "load",
+                storeOp: "store",
+            }],
+            depthStencilAttachment: {
+                view: depth_view,
+                depthReadOnly: true,
+            },
+        });
+
+        render_pass.drawIndirect(resources.get(data.draw_args), 0);
+        render_pass.end();
+    });
+
+    data.camera = pass.read(camera);
+    data.pool = pass.read(pool);
+    data.draw_list = pass.read(draw_list);
+    data.emitter_database = pass.read(emitter_database);
+    data.draw_args = pass.read(draw_args);
+    data.depth = pass.read(depth);
+    data.color = pass.write(pass.read(color));
+
+    return data.color;
+}

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

@@ -6,43 +6,63 @@
  * registers the program touches without a separate pass.
  */
 export class InstructionStream {
-    /** @type {number[][]} */
+    /** @type {number[][]} four words each */
     instructions: number[][];
     /** @type {number} highest register index referenced, plus one */
     register_count: number;
     /**
-     * Emit a raw instruction. Validates the opcode and tracks register usage. Prefer the typed
-     * helpers below where they exist — they document the non-obvious operand packing.
+     * Emit an instruction. Validates the opcode and tracks register usage. Prefer the typed helpers
+     * below where they exist — they document the non-obvious operand packing.
+     *
+     * 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 curve handle, 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 —
      * four for the element-wise ops, three for the ones that used to be spelled `.xyz`. Opcodes
      * whose lane count is fixed ignore it.
      *
      * @param {number} op
-     * @param {number} [dst]
-     * @param {number} [s0]
-     * @param {number} [s1]
-     * @param {number} [s2]
+     * @param {number} [dst] destination register; `0` for an opcode that writes none
+     * @param {number|{kind: number, word: number}} [s0]
+     * @param {number|{kind: number, word: number}} [s1]
+     * @param {number|{kind: number, word: number}} [s2]
      * @param {number} [width]
      * @returns {InstructionStream} this, for chaining
      */
-    emit(op: number, dst?: number, s0?: number, s1?: number, s2?: number, width?: number): InstructionStream;
+    emit(op: number, dst?: number, s0?: number | {
+        kind: number;
+        word: number;
+    }, s1?: number | {
+        kind: number;
+        word: number;
+    }, s2?: number | {
+        kind: number;
+        word: number;
+    }, width?: number): InstructionStream;
+    /**
+     * Emit an instruction that is already encoded — the optimizer's way back into a stream, where the
+     * words are re-validated and the register count re-derived from what they touch.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction
+     * @returns {InstructionStream} this, for chaining
+     */
+    emitWords(words: ArrayLike<number>): InstructionStream;
     /**
      * @param {number} dst
-     * @param {number} src
+     * @param {number} src a register operand word
      * @param {number} [width]
      * @returns {InstructionStream}
      */
     mov(dst: number, src: number, width?: number): InstructionStream;
     /**
-     * Widen a single-lane value into `width` lanes.
-     *
-     * A `SWIZZLE` whose every selector names lane 0 — no opcode of its own, because that is exactly
-     * what one is. The compiler emits these where a narrow value meets a wider operation, which is
-     * the broadcast the reductions and `CURVE` used to do implicitly by filling all four lanes.
+     * Widen a single-lane value into `width` lanes: a copy through the `.xxxx` swizzle. The compiler
+     * emits these where a narrow value meets a wider operation.
      *
      * @param {number} dst
-     * @param {number} src
+     * @param {number} src register slot
      * @param {number} width
      * @returns {InstructionStream}
      */
@@ -67,14 +87,17 @@ export class InstructionStream {
     loadAttr(dst: number, word_offset: number, component_count: number, width?: number): InstructionStream;
     /**
      * The width is the component count and cannot differ from it: a store writes exactly the lanes
-     * the register holds.
+     * the value holds.
      *
-     * @param {number} src_register
+     * @param {number|{kind: number, word: number}} source a register operand word or a literal
      * @param {number} word_offset
      * @param {number} component_count
      * @returns {InstructionStream}
      */
-    storeAttr(src_register: number, word_offset: number, component_count: number): InstructionStream;
+    storeAttr(source: number | {
+        kind: number;
+        word: number;
+    }, word_offset: number, component_count: number): InstructionStream;
     /**
      * @param {number} dst
      * @param {number} builtin_id
@@ -83,10 +106,13 @@ export class InstructionStream {
      */
     loadBuiltin(dst: number, builtin_id: number, width?: number): InstructionStream;
     /**
-     * @param {number} condition_register
+     * @param {number|{kind: number, word: number}} condition a register operand word or a literal, read one lane
      * @returns {InstructionStream}
      */
-    kill(condition_register: number): InstructionStream;
+    kill(condition: number | {
+        kind: number;
+        word: number;
+    }): InstructionStream;
     /**
      * One independent uniform draw in `[0, 1)` per lane — so `width` draws off the shared RNG.
      * Anything shaped (signed, a disk, a sphere) is arithmetic over these; see
@@ -100,11 +126,14 @@ export class InstructionStream {
     /**
      * @param {number} dst
      * @param {number} curve_handle
-     * @param {number} t_register
+     * @param {number|{kind: number, word: number}} t a register operand word or a literal, read one lane
      * @param {number} [width]
      * @returns {InstructionStream}
      */
-    curve(dst: number, curve_handle: number, t_register: number, width?: number): InstructionStream;
+    curve(dst: number, curve_handle: number, t: number | {
+        kind: number;
+        word: number;
+    }, width?: number): InstructionStream;
     /**
      * @returns {InstructionStream}
      */

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

@@ -1 +1 @@
-{"version":3,"file":"InstructionStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/InstructionStream.js"],"names":[],"mappings":"AAwBA;;;;;;GAMG;AACH;IACI,yBAAyB;IACzB,cADW,MAAM,EAAE,EAAE,CACH;IAClB,iEAAiE;IACjE,gBADW,MAAM,CACE;IAqBnB;;;;;;;;;;;;;;;OAeG;IACH,SARW,MAAM,QACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CA+B7B;IAID;;;;;OAKG;IACH,SALW,MAAM,OACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;;;;OAWG;IACH,eALW,MAAM,OACN,MAAM,SACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,eALW,MAAM,kBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;;OASG;IACH,cANW,MAAM,eACN,MAAM,mBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;;;;OAQG;IACH,wBALW,MAAM,eACN,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;OAKG;IACH,iBALW,MAAM,cACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;OAGG;IACH,yBAHW,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,YAJW,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;OAMG;IACH,WANW,MAAM,gBACN,MAAM,cACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;OAEG;IACH,QAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,WAFa,WAAW,CAWvB;;CACJ"}
+{"version":3,"file":"InstructionStream.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/isa/InstructionStream.js"],"names":[],"mappings":"AAkCA;;;;;;GAMG;AACH;IACI,yCAAyC;IACzC,cADW,MAAM,EAAE,EAAE,CACH;IAClB,iEAAiE;IACjE,gBADW,MAAM,CACE;IAsBnB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SARW,MAAM,QACN,MAAM,OACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,OACnC,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CA6D7B;IAED;;;;;;OAMG;IACH,iBAHW,UAAU,MAAM,CAAC,GACf,iBAAiB,CAS7B;IAID;;;;;OAKG;IACH,SALW,MAAM,OACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,eALW,MAAM,OACN,MAAM,SACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;OAKG;IACH,eALW,MAAM,kBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;;;;OASG;IACH,cANW,MAAM,eACN,MAAM,mBACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;;;;OAQG;IACH,kBALW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,eACnC,MAAM,mBACN,MAAM,GACJ,iBAAiB,CAK7B;IAED;;;;;OAKG;IACH,iBALW,MAAM,cACN,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;OAGG;IACH,gBAHW,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GACjC,iBAAiB,CAI7B;IAED;;;;;;;;OAQG;IACH,YAJW,MAAM,UACN,MAAM,GACJ,iBAAiB,CAI7B;IAED;;;;;;OAMG;IACH,WANW,MAAM,gBACN,MAAM,KACN,MAAM,GAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,UACnC,MAAM,GACJ,iBAAiB,CAI7B;IAED;;OAEG;IACH,QAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,WAFa,WAAW,CAWvB;;CACJ"}

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

@@ -1,13 +1,23 @@
 import { assert } from "../../../../core/assert.js";
-import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
 import {
-    pack_swizzle,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+    VM_DST_MASK,
     VM_ISA,
+    VM_KIND,
     VM_MAX_WIDTH,
     VM_OP,
+    VM_OPERAND,
+    VM_SWIZZLE_BROADCAST,
     VM_WIDTH,
-    vm_encode_word0,
-    vm_visit_register_operands,
+    vm_decode_dst,
+    vm_decode_kind,
+    vm_decode_op,
+    vm_decode_width,
+    vm_kinds_problem,
+    vm_pack_instruction,
+    vm_register,
+    vm_visit_register_runs,
 } from "./ParticleVMISA.js";
 
 /**
@@ -30,7 +40,7 @@ function assert_component_count(component_count, mnemonic) {
  * registers the program touches without a separate pass.
  */
 export class InstructionStream {
-    /** @type {number[][]} */
+    /** @type {number[][]} four words each */
     instructions = [];
     /** @type {number} highest register index referenced, plus one */
     register_count = 0;
@@ -47,7 +57,8 @@ export class InstructionStream {
         assert.lessThanOrEqual(
             base + span,
             PARTICLE_VM_REGISTER_SLOTS,
-            `register range [${base}, ${base + span}) exceeds the ${PARTICLE_VM_REGISTER_SLOTS}-slot VM register file`
+            `register range [${base}, ${base + span}) exceeds the ${PARTICLE_VM_REGISTER_SLOTS} slots a VM `
+            + `instruction can address`
         );
         if (base + span > this.register_count) {
             this.register_count = base + span;
@@ -55,18 +66,24 @@ export class InstructionStream {
     }
 
     /**
-     * Emit a raw instruction. Validates the opcode and tracks register usage. Prefer the typed
-     * helpers below where they exist — they document the non-obvious operand packing.
+     * Emit an instruction. Validates the opcode and tracks register usage. Prefer the typed helpers
+     * below where they exist — they document the non-obvious operand packing.
+     *
+     * 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 curve handle, 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 —
      * four for the element-wise ops, three for the ones that used to be spelled `.xyz`. Opcodes
      * whose lane count is fixed ignore it.
      *
      * @param {number} op
-     * @param {number} [dst]
-     * @param {number} [s0]
-     * @param {number} [s1]
-     * @param {number} [s2]
+     * @param {number} [dst] destination register; `0` for an opcode that writes none
+     * @param {number|{kind: number, word: number}} [s0]
+     * @param {number|{kind: number, word: number}} [s1]
+     * @param {number|{kind: number, word: number}} [s2]
      * @param {number} [width]
      * @returns {InstructionStream} this, for chaining
      */
@@ -74,6 +91,25 @@ export class InstructionStream {
         const meta = VM_ISA.get(op);
         assert.defined(meta, `unknown opcode ${op}`);
 
+        const kinds = [VM_KIND.NONE, VM_KIND.NONE, VM_KIND.NONE];
+        const sources = [0, 0, 0];
+
+        [s0, s1, s2].forEach((source, slot) => {
+            const role = meta.operands[slot];
+
+            if (typeof source === "object" && source !== null) {
+                assert.equal(source.kind, VM_KIND.IMM, `${meta.name} s${slot}: an operand object must be a literal`);
+                assert.equal(role, VM_OPERAND.REG, `${meta.name} s${slot} is ${role} and cannot take a literal`);
+                kinds[slot] = VM_KIND.IMM;
+                sources[slot] = source.word >>> 0;
+                return;
+            }
+
+            assert.isNonNegativeInteger(source, `${meta.name} s${slot}`);
+            kinds[slot] = role === VM_OPERAND.REG ? VM_KIND.REG : VM_KIND.NONE;
+            sources[slot] = source >>> 0;
+        });
+
         let requested = width === undefined ? meta.default_width : width;
 
         // The attribute ops measure themselves in components. A store's width IS its component
@@ -81,9 +117,9 @@ export class InstructionStream {
         // 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) {
-            requested = s1;
+            requested = sources[2];
         } else if (op === VM_OP.LOAD_ATTR && width === undefined) {
-            requested = s1;
+            requested = sources[1];
         }
 
         if (meta.width !== VM_WIDTH.NONE) {
@@ -91,21 +127,48 @@ export class InstructionStream {
             assert.lessThanOrEqual(requested, VM_MAX_WIDTH, `${meta.name} width`);
         }
 
-        const word0 = vm_encode_word0(op, requested);
+        if (meta.dst) {
+            assert.isNonNegativeInteger(dst, `${meta.name} destination`);
+            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.
+            assert.equal(dst, 0, `${meta.name} writes no destination; its source goes in s0`);
+        }
+
+        const words = vm_pack_instruction(op, requested, dst, kinds, sources);
 
-        // Walked before the operands are narrowed to u32, so a nonsense index still trips the assert
-        // that names it rather than wrapping into a plausible-looking slot.
-        vm_visit_register_operands([word0, dst, s0, s1, s2], 0, (slot, span) => this.#use_register(slot, span));
+        const kinds_problem = vm_kinds_problem(words, 0);
+        assert.ok(kinds_problem === null, `${meta.name}: ${kinds_problem}`);
 
-        this.instructions.push([word0, dst >>> 0, s0 >>> 0, s1 >>> 0, s2 >>> 0]);
+        // A nonsense index trips the assert that names it rather than wrapping into a plausible slot.
+        vm_visit_register_runs(words, 0, (slot, span) => this.#use_register(slot, span));
+
+        this.instructions.push(words);
         return this;
     }
 
+    /**
+     * Emit an instruction that is already encoded — the optimizer's way back into a stream, where the
+     * words are re-validated and the register count re-derived from what they touch.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction
+     * @returns {InstructionStream} this, for chaining
+     */
+    emitWords(words) {
+        const word0 = words[0];
+        const source = (slot) => (vm_decode_kind(word0, slot) === VM_KIND.IMM
+            ? { kind: VM_KIND.IMM, word: words[1 + slot] }
+            : words[1 + slot]);
+
+        return this.emit(vm_decode_op(word0), vm_decode_dst(word0), source(0), source(1), source(2), vm_decode_width(word0));
+    }
+
     // --- typed helpers (packing that isn't obvious from `emit`) ---
 
     /**
      * @param {number} dst
-     * @param {number} src
+     * @param {number} src a register operand word
      * @param {number} [width]
      * @returns {InstructionStream}
      */
@@ -114,19 +177,16 @@ export class InstructionStream {
     }
 
     /**
-     * Widen a single-lane value into `width` lanes.
-     *
-     * A `SWIZZLE` whose every selector names lane 0 — no opcode of its own, because that is exactly
-     * what one is. The compiler emits these where a narrow value meets a wider operation, which is
-     * the broadcast the reductions and `CURVE` used to do implicitly by filling all four lanes.
+     * Widen a single-lane value into `width` lanes: a copy through the `.xxxx` swizzle. The compiler
+     * emits these where a narrow value meets a wider operation.
      *
      * @param {number} dst
-     * @param {number} src
+     * @param {number} src register slot
      * @param {number} width
      * @returns {InstructionStream}
      */
     broadcast(dst, src, width) {
-        return this.emit(VM_OP.SWIZZLE, dst, src, pack_swizzle(0, 0, 0, 0), 0, width);
+        return this.emit(VM_OP.MOV, dst, vm_register(src, VM_SWIZZLE_BROADCAST), 0, 0, width);
     }
 
     /**
@@ -156,16 +216,16 @@ export class InstructionStream {
 
     /**
      * The width is the component count and cannot differ from it: a store writes exactly the lanes
-     * the register holds.
+     * the value holds.
      *
-     * @param {number} src_register
+     * @param {number|{kind: number, word: number}} source a register operand word or a literal
      * @param {number} word_offset
      * @param {number} component_count
      * @returns {InstructionStream}
      */
-    storeAttr(src_register, word_offset, component_count) {
+    storeAttr(source, word_offset, component_count) {
         assert_component_count(component_count, "STORE_ATTR");
-        return this.emit(VM_OP.STORE_ATTR, src_register, word_offset, component_count, 0, component_count);
+        return this.emit(VM_OP.STORE_ATTR, 0, source, word_offset, component_count, component_count);
     }
 
     /**
@@ -179,11 +239,11 @@ export class InstructionStream {
     }
 
     /**
-     * @param {number} condition_register
+     * @param {number|{kind: number, word: number}} condition a register operand word or a literal, read one lane
      * @returns {InstructionStream}
      */
-    kill(condition_register) {
-        return this.emit(VM_OP.KILL, condition_register);
+    kill(condition) {
+        return this.emit(VM_OP.KILL, 0, condition);
     }
 
     /**
@@ -202,12 +262,12 @@ export class InstructionStream {
     /**
      * @param {number} dst
      * @param {number} curve_handle
-     * @param {number} t_register
+     * @param {number|{kind: number, word: number}} t a register operand word or a literal, read one lane
      * @param {number} [width]
      * @returns {InstructionStream}
      */
-    curve(dst, curve_handle, t_register, width = undefined) {
-        return this.emit(VM_OP.CURVE, dst, curve_handle, t_register, 0, width);
+    curve(dst, curve_handle, t, width = undefined) {
+        return this.emit(VM_OP.CURVE, dst, curve_handle, t, 0, width);
     }
 
     /**
@@ -237,4 +297,4 @@ export class InstructionStream {
 
         return words;
     }
-}
+}

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

@@ -1,9 +1,9 @@
 /**
  * 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 arena.
+ * pool. 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`, 4 floats (one `vec4f`) per constant.
+ * instruction. The constant pool is a flat `Float32Array`, one float per word.
  */
 export class ParticleProgram {
     /**
@@ -30,12 +30,12 @@ export class ParticleProgram {
      */
     update: Uint32Array;
     /**
-     * Constant pool, 4 floats (one `vec4f`) per entry.
+     * Constant pool, one float per word.
      * @type {Float32Array}
      */
     constants: Float32Array;
     /**
-     * Number of vec4 registers the program needs.
+     * Register slots the program needs.
      * @type {number}
      */
     register_count: number;
@@ -46,10 +46,51 @@ export class ParticleProgram {
     /** @returns {number} words in the constant pool — it is addressed by word, not by `vec4` */
     get constant_word_count(): number;
     /**
-     * Validate structural invariants (opcodes known, register indices in range, instruction budget,
-     * constant references in range). Throws on the first problem. Intended for tests and asset
-     * ingestion, not the hot path.
+     * The constant pool as the raw IEEE-754 words it is made of, without copying — a view of the
+     * same bytes, so writing through it writes the pool.
+     *
+     * This is the form the pool is compared, hashed and packed in, because it holds constants, not
+     * measurements. `-0` and `+0` are the same number and different constants — a `DIV` by each
+     * disagrees about the sign of the infinity it produces — and the assembler already keeps them
+     * apart, interning with `Object.is`; equality that read the pool as floats would put back
+     * together what interning took care to separate. Reading bits also keeps
+     * {@link ParticleProgram#equals} reflexive over a pool holding a NaN.
+     *
+     * @returns {Uint32Array}
      */
-    validate(): void;
+    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.
+     *
+     * @param {ParticleProgram} other
+     * @returns {boolean}
+     */
+    equals(other: ParticleProgram): boolean;
+    /**
+     * Hash over everything {@link ParticleProgram#equals} compares, and in the same terms — the pool
+     * goes through the same bit view, so equal programs hash equally.
+     *
+     * @returns {number} int32
+     */
+    hash(): number;
+    /**
+     * Take on another program's code, becoming equal to it.
+     *
+     * 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.
+     *
+     * @param {ParticleProgram} other
+     */
+    copy(other: ParticleProgram): void;
+    /**
+     * A second program equal to this one and sharing none of its storage.
+     *
+     * @returns {ParticleProgram}
+     */
+    clone(): ParticleProgram;
 }
 //# sourceMappingURL=ParticleProgram.d.ts.map

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":"AAqBA;;;;;;GAMG;AACH;IA0BI;;;;;;OAMG;IACH;QAL+B,IAAI,EAAxB,WAAW;QACS,MAAM,EAA1B,WAAW;QACU,SAAS,EAA9B,YAAY;QACG,cAAc,EAA7B,MAAM;OAgBhB;IA7CD;;;OAGG;IACH,MAFU,WAAW,CAEhB;IAEL;;;OAGG;IACH,QAFU,WAAW,CAEd;IAEP;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,gBAFU,MAAM,CAED;IAyBf,mEAAmE;IACnE,qCAEC;IAED,qEAAqE;IACrE,uCAEC;IAED,4FAA4F;IAC5F,kCAEC;IAED;;;;OAIG;IACH,iBAKC;CACJ"}
+{"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"}