@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -0,0 +1,115 @@
+/**
+ * Constant folding, lane by lane.
+ *
+ * Every source a literal and an opcode whose two executors are obliged to agree on the bits, and the
+ * node is a vector of literals instead. A lane whose result is not finite refuses the whole fold
+ * rather than half of it — a partly-folded vector would need a pool run to say, which is a trade this
+ * does not make on its own.
+ *
+ * @param {ParticleVectorRuleOptions} options
+ * @returns {import("./particle_vector_graph.js").ParticleVectorRule}
+ */
+export function rule_fold_constants(options: ParticleVectorRuleOptions): import("./particle_vector_graph.js").ParticleVectorRule;
+/**
+ * Zero as an absorbing element, for the one opcode `PARTICLE_ZERO_ABSORBING_OPS` names — and only
+ * where the other side is unknown, since a product of two knowns is the number it actually is.
+ *
+ * Not bit-identical, and deliberately so; the argument is in `../pass_fold_constants.js`.
+ *
+ * @param {ParticleVectorRuleOptions} options
+ * @returns {import("./particle_vector_graph.js").ParticleVectorRule}
+ */
+export function rule_absorb_zero(options: ParticleVectorRuleOptions): import("./particle_vector_graph.js").ParticleVectorRule;
+/**
+ * @param {Partial<ParticleVectorRuleOptions>} [options]
+ * @returns {{rules: import("./particle_vector_graph.js").ParticleVectorRule[]}}
+ */
+export function particle_vector_rules(options?: Partial<ParticleVectorRuleOptions>): {
+    rules: import("./particle_vector_graph.js").ParticleVectorRule[];
+};
+/**
+ * Whether every lane an operand reads holds a given literal — what an identity asks before it
+ * decides an instruction is a copy.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {{value: number, pattern: number}} operand
+ * @param {number} width lanes the instruction reads of it
+ * @param {number} expected
+ * @returns {boolean}
+ */
+export function operand_is(graph: import("./particle_vector_graph.js").ParticleVectorGraph, operand: {
+    value: number;
+    pattern: number;
+}, width: number, expected: number): boolean;
+/**
+ * The identities that hold for EVERY value a register can hold, as the operand each is a copy of.
+ *
+ * `x * 1`, `x / 1` and `x - (+0)` qualify. `x + 0` does not — `-0 + 0` is `+0` — and neither does
+ * `x * 0`. The line is `../pass_fold_constants.js`'s, and for its reason: the record is compared to
+ * the bit.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number} op
+ * @param {Array<{value: number, pattern: number}|null>} operands by source slot
+ * @param {number} width
+ * @returns {{value: number, pattern: number}|null} the operand the instruction merely copies
+ */
+export function identity_of(graph: import("./particle_vector_graph.js").ParticleVectorGraph, op: number, operands: Array<{
+    value: number;
+    pattern: number;
+} | null>, width: number): {
+    value: number;
+    pattern: number;
+} | null;
+/**
+ * Which lanes of an instruction merely copy an operand, when not all of them do.
+ *
+ * `colour * (1, 1, 1, 0.5)` is the shape a frontend emits for a fade, and three of its four lanes are
+ * `x * 1`. {@link identity_of} will not touch it, because the instruction as a whole is not a copy —
+ * but three quarters of it is, and those three lanes then store back to the very words they were
+ * loaded from, which is not a store at all. Peeling is what turns a four-lane multiply and a pool
+ * load into a one-lane multiply against an immediate.
+ *
+ * The identities are {@link identity_of}'s, asked one lane at a time; `SELECT` is here too, since a
+ * condition known in some lanes is a choice already made in those.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number} op
+ * @param {Array<{value: number, pattern: number}>} operands
+ * @param {number} width
+ * @returns {number[]|null} per lane, the operand it copies, or -1; null when no lane copies one
+ */
+export function identity_lanes(graph: import("./particle_vector_graph.js").ParticleVectorGraph, op: number, operands: Array<{
+    value: number;
+    pattern: number;
+}>, width: number): number[] | null;
+/**
+ * The rewrites, over vectors.
+ *
+ * Only the ones that produce a VALUE live here. An identity — `x * 1` — does not: it produces a
+ * VIEW, the operand read through the swizzle it was already read through, and a view is not a node
+ * in this graph. So identities are recognised in `./particle_vector_lift.js`, where a view is exactly
+ * what an instruction's result can be, the same way a `MOV` is. That split is the vector graph's
+ * only real awkwardness and it is worth the price: it is the same reason a copy costs nothing here.
+ *
+ * The relaxations are the pass pipeline's, spelled the same way and argued where it argues them:
+ * `fold_multiply_by_zero` on, `fold_inexact` off.
+ */
+/**
+ * @typedef {object} ParticleVectorRuleOptions
+ * @property {boolean} fold_inexact fold what the two executors may round apart
+ * @property {boolean} fold_multiply_by_zero a known zero on either side of a multiply gives `+0`
+ */
+/** @type {Readonly<ParticleVectorRuleOptions>} */
+export const PARTICLE_VECTOR_RULE_DEFAULTS: Readonly<ParticleVectorRuleOptions>;
+export type ParticleVectorRuleOptions = {
+    /**
+     * fold what the two executors may round apart
+     */
+    fold_inexact: boolean;
+    /**
+     * a known zero on either side of a multiply gives `+0`
+     */
+    fold_multiply_by_zero: boolean;
+};
+//# sourceMappingURL=particle_vector_rules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_vector_rules.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/optimizer/dag/particle_vector_rules.js"],"names":[],"mappings":"AA8BA;;;;;;;;;;GAUG;AACH,6CAHW,yBAAyB,GACvB,OAAO,4BAA4B,EAAE,kBAAkB,CAwCnE;AAED;;;;;;;;GAQG;AACH,0CAHW,yBAAyB,GACvB,OAAO,4BAA4B,EAAE,kBAAkB,CA6BnE;AAED;;;GAGG;AACH,gDAHW,QAAQ,yBAAyB,CAAC,GAChC;IAAC,KAAK,EAAE,OAAO,4BAA4B,EAAE,kBAAkB,EAAE,CAAA;CAAC,CAM9E;AAED;;;;;;;;;GASG;AACH,kCANW,OAAO,4BAA4B,EAAE,mBAAmB,WACxD;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,SAChC,MAAM,YACN,MAAM,GACJ,OAAO,CAiBnB;AAED;;;;;;;;;;;;GAYG;AACH,mCANW,OAAO,4BAA4B,EAAE,mBAAmB,MACxD,MAAM,YACN,MAAM;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAAC,SAC5C,MAAM,GACJ;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAuCjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,sCANW,OAAO,4BAA4B,EAAE,mBAAmB,MACxD,MAAM,YACN,MAAM;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC,SACvC,MAAM,GACJ,MAAM,EAAE,GAAC,IAAI,CAuCzB;AAlQD;;;;;;;;;;;GAWG;AAEH;;;;GAIG;AAEH,kDAAkD;AAClD,4CADW,SAAS,yBAAyB,CAAC,CAI3C;;;;;kBARW,OAAO;;;;2BACP,OAAO"}

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

@@ -0,0 +1,264 @@
+import { VM_OP, swizzle_selector } from "../../isa/ParticleVMISA.js";
+import { evaluate_particle_operation, PARTICLE_ZERO_ABSORBING_OPS } from "../pass_fold_constants.js";
+import { vm_semantics_of } from "../particle_vm_semantics.js";
+import { PV } from "./particle_vector_graph.js";
+
+/**
+ * The rewrites, over vectors.
+ *
+ * Only the ones that produce a VALUE live here. An identity — `x * 1` — does not: it produces a
+ * VIEW, the operand read through the swizzle it was already read through, and a view is not a node
+ * in this graph. So identities are recognised in `./particle_vector_lift.js`, where a view is exactly
+ * what an instruction's result can be, the same way a `MOV` is. That split is the vector graph's
+ * only real awkwardness and it is worth the price: it is the same reason a copy costs nothing here.
+ *
+ * The relaxations are the pass pipeline's, spelled the same way and argued where it argues them:
+ * `fold_multiply_by_zero` on, `fold_inexact` off.
+ */
+
+/**
+ * @typedef {object} ParticleVectorRuleOptions
+ * @property {boolean} fold_inexact fold what the two executors may round apart
+ * @property {boolean} fold_multiply_by_zero a known zero on either side of a multiply gives `+0`
+ */
+
+/** @type {Readonly<ParticleVectorRuleOptions>} */
+export const PARTICLE_VECTOR_RULE_DEFAULTS = Object.freeze({
+    fold_inexact: false,
+    fold_multiply_by_zero: true,
+});
+
+/**
+ * Constant folding, lane by lane.
+ *
+ * Every source a literal and an opcode whose two executors are obliged to agree on the bits, and the
+ * node is a vector of literals instead. A lane whose result is not finite refuses the whole fold
+ * rather than half of it — a partly-folded vector would need a pool run to say, which is a trade this
+ * does not make on its own.
+ *
+ * @param {ParticleVectorRuleOptions} options
+ * @returns {import("./particle_vector_graph.js").ParticleVectorRule}
+ */
+export function rule_fold_constants(options) {
+    return (graph, node) => {
+        const semantics = vm_semantics_of(node.op);
+
+        if (!(semantics.foldable || (options.fold_inexact && semantics.foldable_inexact))) {
+            return -1;
+        }
+
+        if (node.children.length === 0 || node.children.length > 3) {
+            return -1;
+        }
+
+        const sources = node.children.map(child => graph.constants_of(child));
+
+        if (sources.some(source => source === null)) {
+            return -1;
+        }
+
+        const folded = [];
+
+        for (let lane = 0; lane < node.width; lane++) {
+            const inputs = sources.map((source, index) => source[swizzle_selector(node.patterns[index], lane)]);
+
+            if (inputs.some(input => input === undefined)) {
+                return -1;
+            }
+
+            const value = evaluate_particle_operation(node.op, inputs[0], inputs[1], inputs[2]);
+
+            if (!Number.isFinite(value)) {
+                return -1;
+            }
+
+            folded.push(Math.fround(value));
+        }
+
+        return graph.constant(...folded);
+    };
+}
+
+/**
+ * Zero as an absorbing element, for the one opcode `PARTICLE_ZERO_ABSORBING_OPS` names — and only
+ * where the other side is unknown, since a product of two knowns is the number it actually is.
+ *
+ * Not bit-identical, and deliberately so; the argument is in `../pass_fold_constants.js`.
+ *
+ * @param {ParticleVectorRuleOptions} options
+ * @returns {import("./particle_vector_graph.js").ParticleVectorRule}
+ */
+export function rule_absorb_zero(options) {
+    return (graph, node) => {
+        if (!options.fold_multiply_by_zero || !PARTICLE_ZERO_ABSORBING_OPS.has(node.op)) {
+            return -1;
+        }
+
+        const sources = node.children.map(child => graph.constants_of(child));
+
+        if (sources.every(source => source !== null)) {
+            return -1;
+        }
+
+        const zeroed = [];
+
+        for (let lane = 0; lane < node.width; lane++) {
+            const absorbing = sources.some((source, index) => source !== null
+                && source[swizzle_selector(node.patterns[index], lane)] === 0);
+
+            if (!absorbing) {
+                return -1;
+            }
+
+            zeroed.push(0);
+        }
+
+        return graph.constant(...zeroed);
+    };
+}
+
+/**
+ * @param {Partial<ParticleVectorRuleOptions>} [options]
+ * @returns {{rules: import("./particle_vector_graph.js").ParticleVectorRule[]}}
+ */
+export function particle_vector_rules(options = {}) {
+    const settings = { ...PARTICLE_VECTOR_RULE_DEFAULTS, ...options };
+
+    return { rules: [rule_fold_constants(settings), rule_absorb_zero(settings)] };
+}
+
+/**
+ * Whether every lane an operand reads holds a given literal — what an identity asks before it
+ * decides an instruction is a copy.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {{value: number, pattern: number}} operand
+ * @param {number} width lanes the instruction reads of it
+ * @param {number} expected
+ * @returns {boolean}
+ */
+export function operand_is(graph, operand, width, expected) {
+    const values = graph.constants_of(operand.value);
+
+    if (values === null) {
+        return false;
+    }
+
+    for (let lane = 0; lane < width; lane++) {
+        // `Object.is`, so a `-0` never passes for the `+0` an identity actually needs.
+        if (!Object.is(values[swizzle_selector(operand.pattern, lane)], expected)) {
+            return false;
+        }
+    }
+
+    return true;
+}
+
+/**
+ * The identities that hold for EVERY value a register can hold, as the operand each is a copy of.
+ *
+ * `x * 1`, `x / 1` and `x - (+0)` qualify. `x + 0` does not — `-0 + 0` is `+0` — and neither does
+ * `x * 0`. The line is `../pass_fold_constants.js`'s, and for its reason: the record is compared to
+ * the bit.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number} op
+ * @param {Array<{value: number, pattern: number}|null>} operands by source slot
+ * @param {number} width
+ * @returns {{value: number, pattern: number}|null} the operand the instruction merely copies
+ */
+export function identity_of(graph, op, operands, width) {
+    const is = (slot, expected) => operands[slot] !== undefined && operand_is(graph, operands[slot], width, expected);
+
+    switch (op) {
+        case VM_OP.MUL:
+            if (is(1, 1)) return operands[0];
+            if (is(0, 1)) return operands[1];
+            return null;
+
+        case VM_OP.DIV:
+            return is(1, 1) ? operands[0] : null;
+
+        // Positive zero only: `x - (-0)` is `x + 0`, and that turns a `-0` into a `+0`.
+        case VM_OP.SUB:
+            return is(1, 0) ? operands[0] : null;
+
+        // A condition that is known is a choice already made — but only when it is the same choice in
+        // every lane, since one instruction cannot be two copies.
+        case VM_OP.SELECT: {
+            const values = operands[2] === undefined ? null : graph.constants_of(operands[2].value);
+
+            if (values === null) {
+                return null;
+            }
+
+            const picks = [];
+
+            for (let lane = 0; lane < width; lane++) {
+                picks.push(values[swizzle_selector(operands[2].pattern, lane)] > 0.5 ? 1 : 0);
+            }
+
+            return picks.every(pick => pick === picks[0]) ? operands[picks[0]] : null;
+        }
+
+        default:
+            return null;
+    }
+}
+
+/**
+ * Which lanes of an instruction merely copy an operand, when not all of them do.
+ *
+ * `colour * (1, 1, 1, 0.5)` is the shape a frontend emits for a fade, and three of its four lanes are
+ * `x * 1`. {@link identity_of} will not touch it, because the instruction as a whole is not a copy —
+ * but three quarters of it is, and those three lanes then store back to the very words they were
+ * loaded from, which is not a store at all. Peeling is what turns a four-lane multiply and a pool
+ * load into a one-lane multiply against an immediate.
+ *
+ * The identities are {@link identity_of}'s, asked one lane at a time; `SELECT` is here too, since a
+ * condition known in some lanes is a choice already made in those.
+ *
+ * @param {import("./particle_vector_graph.js").ParticleVectorGraph} graph
+ * @param {number} op
+ * @param {Array<{value: number, pattern: number}>} operands
+ * @param {number} width
+ * @returns {number[]|null} per lane, the operand it copies, or -1; null when no lane copies one
+ */
+export function identity_lanes(graph, op, operands, width) {
+    const at = (slot, lane) => {
+        const values = operands[slot] === undefined ? null : graph.constants_of(operands[slot].value);
+
+        return values === null ? undefined : values[swizzle_selector(operands[slot].pattern, lane)];
+    };
+    /** @type {number[]} */
+    const from = [];
+
+    for (let lane = 0; lane < width; lane++) {
+        switch (op) {
+            case VM_OP.MUL:
+                from.push(Object.is(at(1, lane), 1) ? 0 : Object.is(at(0, lane), 1) ? 1 : -1);
+                break;
+
+            case VM_OP.DIV:
+                from.push(Object.is(at(1, lane), 1) ? 0 : -1);
+                break;
+
+            // Positive zero only, for {@link identity_of}'s reason.
+            case VM_OP.SUB:
+                from.push(Object.is(at(1, lane), 0) ? 0 : -1);
+                break;
+
+            case VM_OP.SELECT: {
+                const condition = at(2, lane);
+
+                from.push(condition === undefined ? -1 : (condition > 0.5 ? 1 : 0));
+                break;
+            }
+
+            default:
+                return null;
+        }
+    }
+
+    return from.some(one => one >= 0) ? from : null;
+}

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

@@ -1,62 +1,90 @@
 /**
  * Optimize one section of a particle program.
  *
+ * The options are flat, and the ones that are not about the pipeline itself are handed to every pass
+ * — each takes the ones it knows and ignores the rest, which is why a rewrite like
+ * `fold_multiply_by_zero` is named here rather than buried under the pass that happens to implement
+ * it. A caller asking for exact arithmetic should not have to know which pass would otherwise round.
+ *
  * @param {InstructionStream} stream
  * @param {object} [options]
  * @param {ArrayLike<number>} [options.constants] the shared constant pool; without it the passes
  *   that reason about literal values do nothing
  * @param {function(number[]): number} [options.intern_constant] adds a run to that pool
- * @param {Object<string, boolean|object>} [options.passes] per-pass switches, overriding
- *   {@link PARTICLE_OPTIMIZER_DEFAULT_PASSES}; an object value also carries that pass's options
+ * @param {ReadonlyArray<string>} [options.passes] the passes to run, defaulting to
+ *   {@link PARTICLE_OPTIMIZER_DEFAULT_PASSES}; see {@link particle_passes_except}
  * @param {number} [options.max_iterations] sweeps of the whole pass list
  * @param {boolean} [options.speculate] whether to try lane peeling both ways and keep the better
  *   program; on unless told otherwise. Off makes the pipeline a straight run of its passes, which is
  *   what a caller measuring one pass in isolation wants.
  * @param {number} [options.register_slots]
+ * @param {boolean} [options.fold_multiply_by_zero] a known zero absorbs a multiply
+ * @param {boolean} [options.fold_inexact] fold what the two executors may round apart
+ * @param {boolean} [options.peel_constant_lanes] split a lane whose value is known off its
+ *   instruction
+ * @param {number} [options.max_select_moves] how many copies folding a `SELECT` may cost
+ * @param {boolean} [options.fuse_multiply_add] fuse where the rounding may differ
+ * @param {boolean} [options.fuse_exact_multiply_add] fuse where it cannot
+ * @param {boolean} [options.merge_constant_loads] join adjacent pool loads into one run
+ * @param {boolean} [options.merge_moves] join adjacent copies into one
  * @returns {InstructionStream} a fresh stream, whose `register_count` is re-derived from what the
  *   optimized instructions actually touch
  */
-export function optimize_particle_program(stream: InstructionStream, options?: {
+export function optimize_particle_section(stream: InstructionStream, { constants, intern_constant, register_slots, passes, max_iterations, speculate, ...settings }?: {
     constants?: ArrayLike<number>;
     intern_constant?: (arg0: number[]) => number;
-    passes?: {
-        [x: string]: boolean | object;
-    };
+    passes?: ReadonlyArray<string>;
     max_iterations?: number;
     speculate?: boolean;
     register_slots?: number;
+    fold_multiply_by_zero?: boolean;
+    fold_inexact?: boolean;
+    peel_constant_lanes?: boolean;
+    max_select_moves?: number;
+    fuse_multiply_add?: boolean;
+    fuse_exact_multiply_add?: boolean;
+    merge_constant_loads?: boolean;
+    merge_moves?: boolean;
 }): InstructionStream;
 /**
- * A `passes` setting enabling only the named passes.
- *
- * The plain object form is additive — anything it does not mention keeps its default — which is what
- * a caller turning one pass off wants and the opposite of what a caller measuring one pass wants.
+ * The default passes with these ones left out — what a caller turning ONE pass off wants, without
+ * having to write down the ten it is keeping.
  *
  * @param {...string} names
- * @returns {Object<string, boolean>}
+ * @returns {string[]}
  */
-export function only_particle_passes(...names: string[]): {
-    [x: string]: boolean;
-};
+export function particle_passes_except(...names: string[]): string[];
 /**
- * Optimize both sections of a compiled program against their shared constant pool.
+ * Optimize a compiled program: `ParticleProgram` in, `ParticleProgram` out.
+ *
+ * The entry point, and the same shape
+ * {@link ./dag/optimize_particle_program_vector.js the graph optimizer} has — one program in, one
+ * out, flat options — so that a caller can hold both and choose.
  *
- * The pool is shared and may grow — a folded expression needs somewhere to put its literal — so it
- * is interned through a {@link ParticleAssembler}, which is the code that already knows how to reuse
- * a run that is anywhere in the pool rather than only one on a boundary.
+ * Both sections are optimized against one constant pool, which is shared and may grow: a folded
+ * expression needs somewhere to put its literal. It is interned through a
+ * {@link ParticleAssembler}, which is the code that already knows how to reuse a run anywhere in the
+ * pool rather than only one on a boundary.
  *
  * @param {ParticleProgram} program
- * @param {object} [options] as {@link optimize_particle_program}, minus the pool it supplies itself
+ * @param {object} [options] as {@link optimize_particle_section}, minus the pool it supplies itself
  * @returns {ParticleProgram}
  */
-export function optimize_compiled_particle_program(program: ParticleProgram, options?: object): ParticleProgram;
+export function optimize_particle_program(program: ParticleProgram, options?: object): ParticleProgram;
 /**
  * @param {Uint32Array} words a packed instruction section
  * @returns {InstructionStream}
  */
 export function stream_from_words(words: Uint32Array): InstructionStream;
 /**
- * Binary-level optimizer for particle VM programs: instructions in, instructions out.
+ * Binary-level optimizer for particle VM programs: a {@link ParticleProgram} in, one out.
+ *
+ * {@link optimize_particle_program} is the entry point and its options are FLAT — the passes to run
+ * as a list of names, and every rewrite a caller might want to name as an option of its own. Which
+ * pass implements a rewrite is this file's business and not the caller's, so
+ * `{ fold_multiply_by_zero: false }` asks for exact arithmetic without naming the pass that would
+ * otherwise round. {@link ./dag/optimize_particle_program_vector.js the graph optimizer} has the
+ * same shape, so a caller can hold both and choose between them.
  *
  * It runs over a compiled {@link InstructionStream} rather than inside any one frontend, because
  * there is more than one frontend — the node-graph compiler, the assembly text pane in the editor,
@@ -67,24 +95,35 @@ export function stream_from_words(words: Uint32Array): InstructionStream;
  * ## Shape
  *
  * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
- * nothing". They 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.
+ * 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.
  *
  * The pipeline sweeps the enabled passes in order until a whole sweep changes nothing or
- * `max_iterations` sweeps have run, then packs the register file once. Passes that pay to repeat on
- * their own take their own `max_iterations`, so effort is the caller's to spend.
+ * `max_iterations` sweeps have run, then schedules, allocates and packs the register file — and
+ * sweeps again if that changed anything, since a reordered program is one the passes have not seen.
+ * Passes that pay to repeat on their own take their own `max_iterations`, so effort is the
+ * caller's to spend.
  *
  * ## What must not change
  *
  * A program's meaning is the record it leaves, the kill flag it sets, and the RNG state it ends on.
  * Every pass here preserves all three to the bit, with one deliberate exception: folding `x * 0` to
- * `+0` gives up the sign of that zero, and gives up `NaN` where something upstream overflowed. It is
- * on by default — see the argument in `pass_fold_constants.js` — and
- * `{ passes: { fold_constants: { fold_multiply_by_zero: false } } }` takes the optimizer back to
- * bit-identical. `optimize_particle_program.spec.js` and the differential harness beside it hold
- * both settings to their respective promises, over the real distribution compositions, the
- * hand-written spec programs and randomly generated ones.
+ * `+0` gives up the sign of that zero, and gives up `NaN` where something upstream overflowed. That
+ * substitution is made in a register, so what it does to the record is whatever the instructions
+ * below it do with a zero — which is not bounded, and is why the harness holds the fold to the
+ * record words a multiply can REACH rather than to a shape. It is on by default — see the argument
+ * in `pass_fold_constants.js` — and `{ fold_multiply_by_zero: false }`
+ * takes the optimizer back to bit-identical. `optimize_particle_program.spec.js` and the
+ * differential harness beside it hold both settings to their respective promises, over the real
+ * distribution compositions, the hand-written spec programs and randomly generated ones.
+ *
+ * Two further rewrites change the arithmetic and are off unless a caller names them:
+ * `fuse_multiply_add`, which is a rounding the reference can see, and `fold_inexact`, which is a
+ * rounding only a GPU can see — the fast-math fold of the transcendentals and `rsqrt`. Each is
+ * argued where it lives.
  */
 /**
  * @callback ParticleOptimizerPass
@@ -103,27 +142,27 @@ export function stream_from_words(words: Uint32Array): InstructionStream;
  */
 /**
  * The passes, in the order a sweep runs them. `final` passes run once, after the sweeps settle.
+ * A pass marked `enabled: false` runs only when a caller switches it on by name.
  *
- * @type {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number, final?: boolean}>}
+ * @type {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number, final?: boolean, enabled?: boolean}>}
  */
 export const PARTICLE_OPTIMIZER_PASSES: Array<{
     name: string;
     run: ParticleOptimizerPass;
     max_iterations: number;
     final?: boolean;
+    enabled?: boolean;
 }>;
 /**
- * Passes enabled unless the caller says otherwise. The switches are for bisecting and for measuring
- * what each pass is worth; the two rewrites that change the arithmetic rather than the program are
- * options of their passes rather than passes, so that the list stays a list of what to run and not a
- * list of what to trust. `fold_constants.fold_multiply_by_zero` is on, `peephole.fuse_multiply_add`
- * is off, and both are argued where they live.
+ * The passes that run unless the caller names a different set. For bisecting, and for measuring what
+ * each pass is worth; the rewrites that change the ARITHMETIC rather than the program are flat
+ * options instead of passes, so that this stays a list of what to run and not a list of what to
+ * trust. `fold_multiply_by_zero` is on, `fuse_multiply_add` and `fold_inexact` are off, and each is
+ * argued where it lives.
  *
- * @type {Readonly<Object<string, boolean>>}
+ * @type {ReadonlyArray<string>}
  */
-export const PARTICLE_OPTIMIZER_DEFAULT_PASSES: Readonly<{
-    [x: string]: boolean;
-}>;
+export const PARTICLE_OPTIMIZER_DEFAULT_PASSES: ReadonlyArray<string>;
 /**
  * How many times the whole pass list may sweep before the optimizer gives up on reaching a fixed
  * point. Passes feed each other — folding a `SELECT` makes a broadcast dead, deleting it lets the

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":"AA8GA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAfW,iBAAiB;IAEW,SAAS,GAArC,UAAU,MAAM,CAAC;IAEoB,eAAe,UAA3C,MAAM,EAAE,KAAG,MAAM;IACe,MAAM;YAAxC,MAAM,GAAE,OAAO,GAAC,MAAM;;IAEZ,cAAc,GAA/B,MAAM;IACY,SAAS,GAA3B,OAAO;IAGU,cAAc,GAA/B,MAAM;IACJ,iBAAiB,CAqC7B;AA6GD;;;;;;;;GAQG;AACH,+CAHc,MAAM;QACA,MAAM,GAAE,OAAO;EAUlC;AAED;;;;;;;;;;GAUG;AACH,4DAJW,eAAe,YACf,MAAM,GACJ,eAAe,CAmC3B;AAyGD;;;GAGG;AACH,yCAHW,WAAW,GACT,iBAAiB,CAiB7B;AAvbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,wCAFU,MAAM;IAAC,MAAM,MAAM,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAC,CAAC,CAalG;AAEF;;;;;;;;GAQG;AACH,gDAFU;QAAgB,MAAM,GAAE,OAAO;EAAE,CAIzC;AAEF;;;;;;;;GAQG;AACH,oDAFU,MAAM,CAEuC;mDAvD5C,MAAM,EAAE,EAAE,WACV,wBAAwB,KACtB,MAAM,EAAE,EAAE,GAAC,IAAI;;;;;eAKd,UAAU,MAAM,CAAC;;;;;;8BACP,MAAM,EAAE,KAAK,MAAM;;;;oBAG7B,MAAM;;;;oBACN,MAAM;;kCA/Dc,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,CAsC3B;AAsFD;;;GAGG;AACH,yCAHW,WAAW,GACT,iBAAiB,CAU7B;AAnbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,wCAFU,MAAM;IAAC,MAAM,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;;;;;;8BACP,MAAM,EAAE,KAAK,MAAM;;;;oBAG7B,MAAM;;;;oBACN,MAAM;;kCApFc,6BAA6B;gCAE/B,2BAA2B"}