@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -6,40 +6,6 @@
  * @returns {ParticleOpSemantics}
  */
 export function vm_semantics_of(op: number): ParticleOpSemantics;
-/**
- * Which lane of a source operand feeds a given output lane.
- *
- * A scalar operand feeds every output lane from lane 0, a `SWIZZLE` reads the lane its pattern
- * names, and everything lanewise reads straight across.
- *
- * @param {number} op
- * @param {number} lane output lane
- * @param {boolean} is_scalar whether the ISA marks this source slot scalar
- * @param {number} pattern packed swizzle pattern, read only for `SWIZZLE`
- * @returns {number} lane of the source operand read into `lane`
- */
-export function vm_source_lane(op: number, lane: number, is_scalar: boolean, pattern: number): number;
-/**
- * Rewrite a swizzle pattern so its lanes past `width` name nothing new.
- *
- * A pattern's four selectors are read whatever the instruction's width, so a narrowed broadcast
- * still reaches as far as its widest selector — {@link swizzle_span} counts all four. Pointing the
- * unused ones at lane 0's selector shrinks the source run to what the live lanes actually read,
- * which is what frees the slots above it.
- *
- * @param {number} pattern
- * @param {number} width lanes the instruction still writes
- * @returns {number} a pattern equivalent at that width
- */
-export function vm_trim_swizzle(pattern: number, width: number): number;
-/**
- * How far into its source a swizzle reaches once trimmed to `width`.
- *
- * @param {number} pattern
- * @param {number} width
- * @returns {number}
- */
-export function vm_trimmed_swizzle_span(pattern: number, width: number): number;
 /**
  * What the optimizer is allowed to assume about each opcode.
  *
@@ -52,6 +18,11 @@ export function vm_trimmed_swizzle_span(pattern: number, width: number): number;
  * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
  * default for a new one is "assume nothing", and a table that silently omitted it would instead have
  * the optimizer assume everything.
+ *
+ * Which lane of a source feeds which lane of the result is not a property of the opcode any more:
+ * every register operand carries a swizzle, and `vm_operand_slot` in the ISA answers it per operand.
+ * What is left here is per-opcode: whether lane `i` of the result depends on lane `i` of the
+ * sources alone (`lanewise`), and whether every lane of the result is the same value (`broadcasts`).
  */
 /**
  * @typedef {object} ParticleOpSemantics
@@ -59,8 +30,7 @@ export function vm_trimmed_swizzle_span(pattern: number, width: number): number;
  *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
  *   duplicated, never widened or narrowed.
  * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
- *   (and of the whole of a scalar one). The reductions and `CROSS` are not; `SWIZZLE` is lane-mapped
- *   rather than lanewise and is handled by {@link vm_source_lane}.
+ *   (and of the whole of a scalar one). The reductions and `CROSS` are not.
  * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
  *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
  *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
@@ -75,6 +45,13 @@ export function vm_trimmed_swizzle_span(pattern: number, width: number): number;
  *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
  *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
  *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+ * @property {boolean} foldable_inexact the operation has a value at compile time and it is the right
+ *   one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+ *   the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+ *   the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+ *   or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+ *   Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+ *   and has no model for a reduction.
  */
 /** @type {Map<number, ParticleOpSemantics>} */
 export const VM_SEMANTICS: Map<number, ParticleOpSemantics>;
@@ -87,8 +64,7 @@ export type ParticleOpSemantics = {
     side_effects: boolean;
     /**
      * output lane `i` is a function of lane `i` of every non-scalar source
-     * (and of the whole of a scalar one). The reductions and `CROSS` are not; `SWIZZLE` is lane-mapped
-     * rather than lanewise and is handled by {@link vm_source_lane }.
+     * (and of the whole of a scalar one). The reductions and `CROSS` are not.
      */
     lanewise: boolean;
     /**
@@ -117,5 +93,15 @@ export type ParticleOpSemantics = {
      * tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
      */
     foldable: boolean;
+    /**
+     * the operation has a value at compile time and it is the right
+     * one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+     * the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+     * the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+     * or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+     * Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+     * and has no model for a reduction.
+     */
+    foldable_inexact: boolean;
 };
 //# sourceMappingURL=particle_vm_semantics.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"particle_vm_semantics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_vm_semantics.js"],"names":[],"mappings":"AAgIA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAW/B;AAED;;;;;;;;;;;GAWG;AACH,mCANW,MAAM,QACN,MAAM,aACN,OAAO,WACP,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;;;;GAWG;AACH,yCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAclB;AAED;;;;;;GAMG;AACH,iDAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AA3MD;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBAvBxB,OAAO;;;;;;cAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;eAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;;;cAGP,OAAO"}
+{"version":3,"file":"particle_vm_semantics.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_vm_semantics.js"],"names":[],"mappings":"AAoJA;;;;;;GAMG;AACH,oCAHW,MAAM,GACJ,mBAAmB,CAY/B;AAnKD;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,+CAA+C;AAC/C,2BADW,IAAI,MAAM,EAAE,mBAAmB,CAAC,CACL;;;;;;;kBA7BxB,OAAO;;;;;cAGP,OAAO;;;;;;gBAEP,OAAO;;;;;;eAGP,OAAO;;;;;;gBAGP,OAAO;;;;;;;;cAGP,OAAO;;;;;;;;;;sBAKP,OAAO"}

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

@@ -1,206 +1,166 @@
-import { VM_MAX_WIDTH, VM_OP, swizzle_span } from "../isa/ParticleVMISA.js";
-
-/**
- * What the optimizer is allowed to assume about each opcode.
- *
- * {@link ../isa/ParticleVMISA.js} says what an instruction *does*; this says what may be done *to*
- * it — whether it can be deleted when its result is unread, narrowed when its high lanes are dead,
- * evaluated at compile time, or recognised as a recomputation of something already in a register.
- * Those are four different questions and an opcode can answer them differently: `LOAD_ATTR` is
- * removable but not shareable across a store, `RANDOM` is neither, and `CURVE` is both.
- *
- * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
- * default for a new one is "assume nothing", and a table that silently omitted it would instead have
- * the optimizer assume everything.
- */
-
-/**
- * @typedef {object} ParticleOpSemantics
- * @property {boolean} side_effects execution changes something other than the destination register:
- *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
- *   duplicated, never widened or narrowed.
- * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
- *   (and of the whole of a scalar one). The reductions and `CROSS` are not; `SWIZZLE` is lane-mapped
- *   rather than lanewise and is handled by {@link vm_source_lane}.
- * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
- *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
- *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
- * @property {boolean} shareable two executions with equal operand values produce equal results, so a
- *   second one can read the first one's register instead. False for anything reading the record or
- *   the RNG.
- * @property {boolean} broadcasts every lane of the destination holds the same value, by construction
- *   rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
- *   as one.
- * @property {boolean} foldable the JS reference and the WGSL interpreter are both obliged to produce
- *   the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
- *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
- *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
- *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
- */
-
-/** @type {Map<number, ParticleOpSemantics>} */
-export const VM_SEMANTICS = new Map();
-
-/**
- * @param {number} op
- * @param {Partial<ParticleOpSemantics>} flags
- */
-function semantics(op, flags) {
-    VM_SEMANTICS.set(op, {
-        side_effects: false,
-        lanewise: false,
-        narrowable: false,
-        shareable: false,
-        broadcasts: false,
-        foldable: false,
-        ...flags,
-    });
-}
-
-/** Pure element-wise arithmetic whose two executors are bit-for-bit obliged to agree. */
-const EXACT = { lanewise: true, narrowable: true, shareable: true, foldable: true };
-
-/** The same, minus the folding: correct to narrow and to share, but the executors may round apart. */
-const INEXACT = { lanewise: true, narrowable: true, shareable: true };
-
-semantics(VM_OP.HALT, { side_effects: true });
-semantics(VM_OP.NOP, {});
-semantics(VM_OP.MOV, EXACT);
-semantics(VM_OP.LOAD_CONST, EXACT);
-// Reads the record, so it is removable when dead but may not be shared across a store that could
-// touch the same words — which is why it is not `shareable` and the CSE pass never sees it.
-semantics(VM_OP.LOAD_ATTR, { lanewise: true, narrowable: true });
-semantics(VM_OP.STORE_ATTR, { side_effects: true });
-semantics(VM_OP.LOAD_BUILTIN, { lanewise: true, narrowable: true, shareable: true });
-semantics(VM_OP.KILL, { side_effects: true });
-
-semantics(VM_OP.ADD, EXACT);
-semantics(VM_OP.SUB, EXACT);
-semantics(VM_OP.MUL, EXACT);
-semantics(VM_OP.DIV, EXACT);
-// `a * b + c` is one rounding on hardware that contracts it into an FMA and two in the reference.
-semantics(VM_OP.MAD, INEXACT);
-semantics(VM_OP.MIN, EXACT);
-semantics(VM_OP.MAX, EXACT);
-// The reference spells it `a + (b - a) * t`; WGSL's `mix` is free to round it differently.
-semantics(VM_OP.MIX, INEXACT);
-semantics(VM_OP.CLAMP, EXACT);
-semantics(VM_OP.SCALE, EXACT);
-
-semantics(VM_OP.NEG, EXACT);
-semantics(VM_OP.ABS, EXACT);
-semantics(VM_OP.FLOOR, EXACT);
-semantics(VM_OP.FRACT, EXACT);
-semantics(VM_OP.SQRT, EXACT);
-semantics(VM_OP.SIN, INEXACT);
-semantics(VM_OP.COS, INEXACT);
-semantics(VM_OP.EXP, INEXACT);
-semantics(VM_OP.LOG, INEXACT);
-semantics(VM_OP.POW, INEXACT);
-semantics(VM_OP.STEP, EXACT);
-semantics(VM_OP.SMOOTHSTEP, INEXACT);
-
-// The reductions read every lane to write one, so there are no trailing lanes to drop.
-semantics(VM_OP.DOT, { shareable: true });
-// Three lanes of cross product plus, optionally, the zero `w`. Dropping that `w` is the one
-// narrowing available, and `min_width` already floors it at three.
-semantics(VM_OP.CROSS, { narrowable: true, shareable: true });
-semantics(VM_OP.LENGTH, { shareable: true });
-semantics(VM_OP.NORMALIZE, { shareable: true });
-semantics(VM_OP.DISTANCE, { shareable: true });
-// Lane-MAPPED rather than lanewise: output lane `i` is source lane `pattern[i]`.
-semantics(VM_OP.SWIZZLE, { narrowable: true, shareable: true, foldable: true });
-
-semantics(VM_OP.CMP_LT, EXACT);
-semantics(VM_OP.CMP_LE, EXACT);
-semantics(VM_OP.CMP_GT, EXACT);
-semantics(VM_OP.CMP_GE, EXACT);
-semantics(VM_OP.CMP_EQ, EXACT);
-semantics(VM_OP.SELECT, EXACT);
-
-// Ordered and side-effecting: it advances the shared RNG, and its width IS the number of draws it
-// takes. Removing, duplicating, reordering or narrowing one moves every value drawn after it.
-semantics(VM_OP.RANDOM, { side_effects: true });
-// An external WGSL symbol, but a pure function of (handle, t) — so a dead one goes and a repeated
-// one is shared. Every lane of the result is the same sample, which is what makes it narrowable —
-// and what makes it a broadcast, so a consumer reading it wide is a consumer that wants `SCALE`.
-semantics(VM_OP.CURVE, { lanewise: true, narrowable: true, shareable: true, broadcasts: true });
-
-/**
- * What may be assumed about an opcode. An unknown one is assumed to do everything, so a new opcode
- * is inert to the optimizer until somebody adds it to the table above.
- *
- * @param {number} op
- * @returns {ParticleOpSemantics}
- */
-export function vm_semantics_of(op) {
-    return VM_SEMANTICS.get(op) ?? {
-        side_effects: true,
-        lanewise: false,
-        narrowable: false,
-        shareable: false,
-        broadcasts: false,
-        foldable: false,
-    };
-}
-
-/**
- * Which lane of a source operand feeds a given output lane.
- *
- * A scalar operand feeds every output lane from lane 0, a `SWIZZLE` reads the lane its pattern
- * names, and everything lanewise reads straight across.
- *
- * @param {number} op
- * @param {number} lane output lane
- * @param {boolean} is_scalar whether the ISA marks this source slot scalar
- * @param {number} pattern packed swizzle pattern, read only for `SWIZZLE`
- * @returns {number} lane of the source operand read into `lane`
- */
-export function vm_source_lane(op, lane, is_scalar, pattern) {
-    if (is_scalar) {
-        return 0;
-    }
-
-    if (op === VM_OP.SWIZZLE) {
-        return (pattern >> (2 * lane)) & 3;
-    }
-
-    return lane;
-}
-
-/**
- * Rewrite a swizzle pattern so its lanes past `width` name nothing new.
- *
- * A pattern's four selectors are read whatever the instruction's width, so a narrowed broadcast
- * still reaches as far as its widest selector — {@link swizzle_span} counts all four. Pointing the
- * unused ones at lane 0's selector shrinks the source run to what the live lanes actually read,
- * which is what frees the slots above it.
- *
- * @param {number} pattern
- * @param {number} width lanes the instruction still writes
- * @returns {number} a pattern equivalent at that width
- */
-export function vm_trim_swizzle(pattern, width) {
-    const first = pattern & 3;
-
-    let out = 0;
-
-    for (let lane = 0; lane < VM_MAX_WIDTH; lane++) {
-        const selector = lane < width ? (pattern >> (2 * lane)) & 3 : first;
-
-        out |= selector << (2 * lane);
-    }
-
-    return out >>> 0;
-}
-
-/**
- * How far into its source a swizzle reaches once trimmed to `width`.
- *
- * @param {number} pattern
- * @param {number} width
- * @returns {number}
- */
-export function vm_trimmed_swizzle_span(pattern, width) {
-    return swizzle_span(vm_trim_swizzle(pattern, width));
-}
+import { VM_OP } from "../isa/ParticleVMISA.js";
+
+/**
+ * What the optimizer is allowed to assume about each opcode.
+ *
+ * {@link ../isa/ParticleVMISA.js} says what an instruction *does*; this says what may be done *to*
+ * it — whether it can be deleted when its result is unread, narrowed when its high lanes are dead,
+ * evaluated at compile time, or recognised as a recomputation of something already in a register.
+ * Those are four different questions and an opcode can answer them differently: `LOAD_ATTR` is
+ * removable but not shareable across a store, `RANDOM` is neither, and `CURVE` is both.
+ *
+ * Every opcode has to appear in {@link VM_SEMANTICS} — the spec asserts it — because the safe
+ * default for a new one is "assume nothing", and a table that silently omitted it would instead have
+ * the optimizer assume everything.
+ *
+ * Which lane of a source feeds which lane of the result is not a property of the opcode any more:
+ * every register operand carries a swizzle, and `vm_operand_slot` in the ISA answers it per operand.
+ * What is left here is per-opcode: whether lane `i` of the result depends on lane `i` of the
+ * sources alone (`lanewise`), and whether every lane of the result is the same value (`broadcasts`).
+ */
+
+/**
+ * @typedef {object} ParticleOpSemantics
+ * @property {boolean} side_effects execution changes something other than the destination register:
+ *   the RNG stream, the record, the kill flag, or where the section stops. Never removable, never
+ *   duplicated, never widened or narrowed.
+ * @property {boolean} lanewise output lane `i` is a function of lane `i` of every non-scalar source
+ *   (and of the whole of a scalar one). The reductions and `CROSS` are not.
+ * @property {boolean} narrowable dropping trailing output lanes leaves the remaining ones unchanged.
+ *   Weaker than `lanewise` — `CROSS` writes a fourth lane nothing else depends on — and not implied
+ *   by it for `RANDOM`, whose lanes are independent but whose count is the draw count.
+ * @property {boolean} shareable two executions with equal operand values produce equal results, so a
+ *   second one can read the first one's register instead. False for anything reading the record or
+ *   the RNG.
+ * @property {boolean} broadcasts every lane of the destination holds the same value, by construction
+ *   rather than by what the operands happen to be. Lane `i` is then a copy of lane 0 and may be read
+ *   as one.
+ * @property {boolean} foldable the JS reference and the WGSL interpreter are both obliged to produce
+ *   the *same bits* for this operation, so evaluating it here and baking a constant changes nothing
+ *   on either. Correctly-rounded IEEE arithmetic qualifies; a transcendental does not — JS
+ *   `Math.sin` and a GPU's `sin` agree to about a part in 10^7, which is what the parity spec's
+ *   tolerance is for, and folding would quietly pick the CPU's answer for the GPU.
+ * @property {boolean} foldable_inexact the operation has a value at compile time and it is the right
+ *   one, but only to within the rounding the two executors are allowed to differ by. Folding it is
+ *   the fast-math trade every shading compiler offers: a constant instead of a transcendental, at
+ *   the price of the GPU's own last bits. Never true alongside `foldable` — an operation is exact
+ *   or it is not — and read only by `pass_fold_constants.fold_inexact`, which is off by default.
+ *   Only lanewise operations may carry it: the fold evaluates lane `i` from lane `i` of the sources
+ *   and has no model for a reduction.
+ */
+
+/** @type {Map<number, ParticleOpSemantics>} */
+export const VM_SEMANTICS = new Map();
+
+/**
+ * @param {number} op
+ * @param {Partial<ParticleOpSemantics>} flags
+ */
+function semantics(op, flags) {
+    VM_SEMANTICS.set(op, {
+        side_effects: false,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+        foldable_inexact: false,
+        ...flags,
+    });
+}
+
+/** Pure element-wise arithmetic whose two executors are bit-for-bit obliged to agree. */
+const EXACT = { lanewise: true, narrowable: true, shareable: true, foldable: true };
+
+/**
+ * The same, except that the two executors may round apart: correct to narrow and to share, and
+ * foldable only under the named relaxation — see `foldable_inexact` above.
+ */
+const INEXACT = { lanewise: true, narrowable: true, shareable: true, foldable_inexact: true };
+
+semantics(VM_OP.HALT, { side_effects: true });
+semantics(VM_OP.NOP, {});
+semantics(VM_OP.MOV, EXACT);
+semantics(VM_OP.LOAD_CONST, EXACT);
+// Reads the record, so it is removable when dead but may not be shared across a store that could
+// touch the same words — which is why it is not `shareable` and the CSE pass never sees it.
+semantics(VM_OP.LOAD_ATTR, { lanewise: true, narrowable: true });
+semantics(VM_OP.STORE_ATTR, { side_effects: true });
+semantics(VM_OP.LOAD_BUILTIN, { lanewise: true, narrowable: true, shareable: true });
+semantics(VM_OP.KILL, { side_effects: true });
+
+semantics(VM_OP.ADD, EXACT);
+semantics(VM_OP.SUB, EXACT);
+semantics(VM_OP.MUL, EXACT);
+semantics(VM_OP.DIV, EXACT);
+// `a * b + c` is one rounding on hardware that contracts it into an FMA and two in the reference.
+semantics(VM_OP.MAD, INEXACT);
+semantics(VM_OP.MIN, EXACT);
+semantics(VM_OP.MAX, EXACT);
+// The reference spells it `a + (b - a) * t`; WGSL's `mix` is free to round it differently.
+semantics(VM_OP.MIX, INEXACT);
+semantics(VM_OP.CLAMP, EXACT);
+
+semantics(VM_OP.NEG, EXACT);
+semantics(VM_OP.ABS, EXACT);
+semantics(VM_OP.FLOOR, EXACT);
+semantics(VM_OP.FRACT, EXACT);
+semantics(VM_OP.SQRT, EXACT);
+semantics(VM_OP.SIN, INEXACT);
+semantics(VM_OP.COS, INEXACT);
+semantics(VM_OP.EXP, INEXACT);
+semantics(VM_OP.LOG, INEXACT);
+semantics(VM_OP.POW, INEXACT);
+semantics(VM_OP.STEP, EXACT);
+semantics(VM_OP.SMOOTHSTEP, INEXACT);
+// `inverseSqrt` is a hardware estimate with ULPs of slack to it, and the reference divides one by
+// a square root — a different computation rather than a different rounding of the same one. So it
+// folds where a transcendental folds: under `fold_inexact`, and not before.
+semantics(VM_OP.RSQRT, INEXACT);
+semantics(VM_OP.TAN, INEXACT);
+semantics(VM_OP.ASIN, INEXACT);
+semantics(VM_OP.ACOS, INEXACT);
+semantics(VM_OP.ATAN2, INEXACT);
+
+// The reductions read every lane to write one, so there are no trailing lanes to drop.
+semantics(VM_OP.DOT, { shareable: true });
+// Three lanes of cross product plus, optionally, the zero `w`. Dropping that `w` is the one
+// narrowing available, and `min_width` already floors it at three.
+semantics(VM_OP.CROSS, { narrowable: true, shareable: true });
+semantics(VM_OP.LENGTH, { shareable: true });
+semantics(VM_OP.NORMALIZE, { shareable: true });
+semantics(VM_OP.DISTANCE, { shareable: true });
+
+semantics(VM_OP.CMP_LT, EXACT);
+semantics(VM_OP.CMP_LE, EXACT);
+semantics(VM_OP.CMP_GT, EXACT);
+semantics(VM_OP.CMP_GE, EXACT);
+semantics(VM_OP.CMP_EQ, EXACT);
+semantics(VM_OP.SELECT, EXACT);
+
+// Ordered and side-effecting: it advances the shared RNG, and its width IS the number of draws it
+// takes. Removing, duplicating, reordering or narrowing one moves every value drawn after it.
+semantics(VM_OP.RANDOM, { side_effects: true });
+// An external WGSL symbol, but a pure function of (handle, t) — so a dead one goes and a repeated
+// one is shared. Every lane of the result is the same sample, which is what makes it narrowable —
+// and what makes it a broadcast, so a consumer reading it wide is a consumer that wants `.xxxx`.
+semantics(VM_OP.CURVE, { lanewise: true, narrowable: true, shareable: true, broadcasts: true });
+
+/**
+ * What may be assumed about an opcode. An unknown one is assumed to do everything, so a new opcode
+ * is inert to the optimizer until somebody adds it to the table above.
+ *
+ * @param {number} op
+ * @returns {ParticleOpSemantics}
+ */
+export function vm_semantics_of(op) {
+    return VM_SEMANTICS.get(op) ?? {
+        side_effects: true,
+        lanewise: false,
+        narrowable: false,
+        shareable: false,
+        broadcasts: false,
+        foldable: false,
+        foldable_inexact: false,
+    };
+}

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

@@ -0,0 +1,99 @@
+export function pass_allocate_registers(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/**
+ * @typedef {object} ParticleRegisterSegment
+ * @property {number} slot the slot it occupies in the program as it stands
+ * @property {number} start the instruction that writes it, or `-1` for the reset
+ * @property {number} end the last instruction that reads it; `start` when nothing does
+ * @property {number} parent union-find link
+ * @property {number} placed the slot it is given, once the cluster is placed; `-1` until then
+ */
+/**
+ * @typedef {object} ParticleRegisterShape
+ * @property {number[]} members segment indices
+ * @property {number} origin the lowest slot among the members, which the others keep their distance from
+ * @property {number} extent slots from the origin to one past the highest member
+ * @property {number} start the earliest write among the members
+ */
+/**
+ * @typedef {object} ParticleRegisterSegments
+ * @property {ParticleRegisterSegment[]} segments
+ * @property {ParticleRegisterShape[]} shapes the clusters, in the order they are placed
+ * @property {Int32Array[]} read_segment per instruction, per source slot, the segment the operand's canonical base slot read
+ * @property {Uint32Array[]} read_word per instruction, per source slot, the operand in its canonical spelling
+ * @property {Int32Array} write_segment per instruction, the segment its destination base slot is written into
+ * @property {number} high_water one past the highest slot the program reaches
+ */
+/**
+ * Every stretch of every slot, and which of them have to keep their distance.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction[]} decoded
+ * @param {number} slots size of the register file
+ * @returns {ParticleRegisterSegments|null} `null` when an operand reaches outside the file
+ */
+export function analyze_particle_register_segments(decoded: import("./particle_program_analysis.js").ParticleDecodedInstruction[], slots: number): ParticleRegisterSegments | null;
+/** @type {string} */
+export const PARTICLE_PASS_ALLOCATE_REGISTERS: string;
+export type ParticleRegisterSegment = {
+    /**
+     * the slot it occupies in the program as it stands
+     */
+    slot: number;
+    /**
+     * the instruction that writes it, or `-1` for the reset
+     */
+    start: number;
+    /**
+     * the last instruction that reads it; `start` when nothing does
+     */
+    end: number;
+    /**
+     * union-find link
+     */
+    parent: number;
+    /**
+     * the slot it is given, once the cluster is placed; `-1` until then
+     */
+    placed: number;
+};
+export type ParticleRegisterShape = {
+    /**
+     * segment indices
+     */
+    members: number[];
+    /**
+     * the lowest slot among the members, which the others keep their distance from
+     */
+    origin: number;
+    /**
+     * slots from the origin to one past the highest member
+     */
+    extent: number;
+    /**
+     * the earliest write among the members
+     */
+    start: number;
+};
+export type ParticleRegisterSegments = {
+    segments: ParticleRegisterSegment[];
+    /**
+     * the clusters, in the order they are placed
+     */
+    shapes: ParticleRegisterShape[];
+    /**
+     * per instruction, per source slot, the segment the operand's canonical base slot read
+     */
+    read_segment: Int32Array[];
+    /**
+     * per instruction, per source slot, the operand in its canonical spelling
+     */
+    read_word: Uint32Array[];
+    /**
+     * per instruction, the segment its destination base slot is written into
+     */
+    write_segment: Int32Array;
+    /**
+     * one past the highest slot the program reaches
+     */
+    high_water: number;
+};
+//# sourceMappingURL=pass_allocate_registers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pass_allocate_registers.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/pass_allocate_registers.js"],"names":[],"mappings":"AA0FqC,0JAEqB;AAxB1D;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,4DAJW,OAAO,gCAAgC,EAAE,0BAA0B,EAAE,SACrE,MAAM,GACJ,wBAAwB,GAAC,IAAI,CAsHzC;AAlND,qBAAqB;AACrB,+CADW,MAAM,CACoD;;;;;UA6DvD,MAAM;;;;WACN,MAAM;;;;SACN,MAAM;;;;YACN,MAAM;;;;YACN,MAAM;;;;;;aAKN,MAAM,EAAE;;;;YACR,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;cAKN,uBAAuB,EAAE;;;;YACzB,qBAAqB,EAAE;;;;kBACvB,UAAU,EAAE;;;;eACZ,WAAW,EAAE;;;;mBACb,UAAU;;;;gBACV,MAAM"}