@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,678 @@
+import {
+    VM_KIND,
+    VM_OP,
+    swizzle_selector,
+    vm_dest_width,
+    vm_f32_value,
+    vm_pack_instruction,
+    vm_register,
+    vm_with_width,
+} from "../isa/ParticleVMISA.js";
+import {
+    decode_particle_instructions,
+    particle_instruction_is_well_formed,
+    particle_read_slots,
+} from "./particle_program_analysis.js";
+
+/** @type {string} */
+export const PARTICLE_PASS_FOLD_CONSTANTS = "fold_constants";
+
+/**
+ * The opcodes whose result a known zero operand decides on its own — the ones
+ * `fold_multiply_by_zero` rewrites, and therefore the ones whose results the equivalence harness's
+ * reach mode has to follow. Stated once so the two cannot drift.
+ * @type {Set<number>}
+ */
+export const PARTICLE_ZERO_ABSORBING_OPS = new Set([VM_OP.MUL]);
+
+/**
+ * Track what each register lane is known to hold, and rewrite the instructions that turn out not to
+ * need computing.
+ *
+ * Two things come out of this. Instructions whose every output lane is a known number become a
+ * `LOAD_CONST`, which usually makes everything feeding them dead. And instructions that are a known
+ * *shape* rather than a known value collapse: a `SELECT` whose condition is a compile-time mask is
+ * per-lane copying, and a multiply by one is a copy.
+ *
+ * The graph compiler emits both shapes constantly. It has no notion of a compile-time-known lane
+ * mask, so `graph/particle_graph_distributions.js` assembling `(cos, sin, 0)` out of a `select` on
+ * the literal `[0, 1, 0]` lowers to a broadcast, a second broadcast, a constant load and a `SELECT`
+ * — four instructions for what is one `MOV`, and this pass is what notices.
+ *
+ * ## What is not folded, and why
+ *
+ * A lane is tracked only while its value is FINITE. `NaN` and `±Inf` are dropped from the analysis
+ * rather than propagated, which removes at a stroke every rewrite that is right for ordinary numbers
+ * and wrong at the edges — `min(NaN, x)` is the reference's `NaN` and the GPU's anything, and a
+ * baked `NaN` constant is at the mercy of a driver that assumes there are none.
+ *
+ * Only operations both executors are obliged to round identically are evaluated here — see
+ * `foldable` in {@link ./particle_vm_semantics.js}. Folding `sin` would quietly hand the GPU the
+ * CPU's answer, so it happens only when a caller asks for it by name: see `fold_inexact` below.
+ *
+ * Every identity here is exact — `x * 1`, `x / 1` and `x - (+0)` are `x` for every value a register
+ * can hold — with one deliberate exception, below.
+ *
+ * ## Multiplying by zero: the one place this is not exact
+ *
+ * `x * 0` is `+0` for finite non-negative `x`, `-0` for finite negative `x`, and `NaN` for `±Inf`
+ * and `NaN`. Folding it to `+0` is therefore a fast-math relaxation rather than a rewrite, and it is
+ * on by default (`fold_multiply_by_zero`) because a particle effect essentially never needs the
+ * distinction and the shape it unlocks is everywhere.
+ *
+ * That shape is the lane mask. `graph/particle_graph_distributions.js` clears the lanes a disk has
+ * nothing to say about by multiplying through `[1, 1, 0]`, and the lowering has no way to know the
+ * result of that lane is a constant. With the fold it becomes one, the tail of the instruction is
+ * peeled off as a constant load, and the multiply, the mask's own load and the broadcast feeding it
+ * all go dead behind it.
+ *
+ * What it costs is not bounded by a shape — a substituted zero is read by whatever comes next, and
+ * a comparison or a division downstream can turn the difference into any number. The equivalence
+ * harness bounds its REACH instead: see `reached_by_zero_fold` in
+ * {@link ./particle_program_equivalence.js}. Switch the fold off
+ * (`{ fold_multiply_by_zero: false }`) and every pass in the
+ * optimizer is bit-exact again.
+ *
+ * ## `fold_inexact`: the transcendentals, off by default
+ *
+ * `{ fold_inexact: true }` also evaluates the operations whose two
+ * executors are allowed to round apart — `foldable_inexact` in
+ * {@link ./particle_vm_semantics.js}: the trigonometry and its inverses, `exp`, `log`, `pow`,
+ * `smoothstep`, `mix`, `mad` and `rsqrt`. That is HLSL's fast-math trade and it is worth naming
+ * rather than assuming: what is bought is a literal instead of a transcendental, and what is sold
+ * is the GPU's own last bits — `Math.sin` and a GPU's `sin` agree to about a part in 10^7, and
+ * with the fold on it is the CPU's answer that ships.
+ *
+ * It is off because that is not a trade the compiler gets to make on an author's behalf, and
+ * because there is nothing here to buy with it. The fold only fires where an argument is already a
+ * compile-time constant, and over all eighteen built-in groups — `curl4`, the simplex noises, the
+ * quaternion and sampling groups, 6,523 instructions optimized — turning it on changes not one
+ * instruction: every `sin` in the tree takes its argument from a `random`, an attribute or a
+ * builtin. On the fuzzer's programs, where the opcode mix is uniform and operands are often
+ * literals, it takes another 8.8% off what the default pipeline leaves (5,443 to 4,963 over 200
+ * programs). So the option is real and tested and worth having for a frontend that folds harder
+ * than this one — and on today's effects it is a switch with nothing behind it.
+ *
+ * What it does NOT do is turn a hardware `NaN` into a number. Only finite values are tracked, so
+ * `log` of zero, `asin` of two and `rsqrt` of a negative are all left alone by the same rule that
+ * leaves every other edge alone; the two operations whose reference spelling is defined where the
+ * hardware's is not — `pow` of a non-positive base and `smoothstep` with equal edges, both of which
+ * WGSL computes through a division or a `log2` that the reference does not — are refused in
+ * {@link evaluate} rather than relaxed. The relaxation is a rounding, and stays one.
+ *
+ * ## Operands
+ *
+ * A literal operand is a known value by construction, and a register operand's lanes are looked up
+ * through its swizzle — so a broadcast of a known register is known in every lane, and a `SELECT`
+ * between a register and a literal collapses to a `MOV` from whichever the mask picks, with the
+ * operand's kind and swizzle carried along.
+ *
+ * @type {import("./optimize_particle_program.js").ParticleOptimizerPass}
+ */
+export function pass_fold_constants(instructions, context) {
+    const decoded = decode_particle_instructions(instructions);
+    const slots = context.register_slots;
+
+    /** Whether a slot's value is known — and finite, which is the only kind that is tracked. */
+    const known = new Uint8Array(slots);
+    /** f32, so a tracked value is exactly the one the register would hold. */
+    const value = new Float32Array(slots);
+
+    const options = {
+        max_select_moves: 2,
+        fold_multiply_by_zero: true,
+        fold_inexact: false,
+        peel_constant_lanes: true,
+        ...context,
+    };
+
+    /** @type {number[][]} */
+    const out = [];
+
+    let changed = false;
+
+    for (const instruction of decoded) {
+        const lanes = evaluate_lanes(instruction, known, value, options);
+        const replacement = rewrite(instruction, lanes, known, value, options);
+
+        if (replacement === null) {
+            out.push(instruction.words);
+        } else {
+            out.push(...replacement);
+            changed = true;
+        }
+
+        publish(instruction, lanes, known, value);
+    }
+
+    return changed ? out : null;
+}
+
+/**
+ * What each lane of the destination will hold, as far as it can be worked out here.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @param {object} options
+ * @returns {Array<number|null>} one entry per destination lane; `null` where the value is not known
+ */
+function evaluate_lanes(instruction, known, value, options) {
+    if (instruction.write === null) {
+        return [];
+    }
+
+    const count = vm_dest_width(instruction.op, instruction.width);
+    /** @type {Array<number|null>} */
+    const lanes = new Array(count).fill(null);
+
+    if (instruction.op === VM_OP.LOAD_CONST) {
+        for (let lane = 0; lane < count; lane++) {
+            lanes[lane] = finite(options.constants[instruction.words[1] + lane]);
+        }
+
+        return lanes;
+    }
+
+    if (instruction.op === VM_OP.LOAD_ATTR) {
+        // Lanes past the component count are the zero an over-wide load is defined to read. The
+        // ones inside it are whatever the record holds, which is not knowable here.
+        for (let lane = instruction.words[2]; lane < count; lane++) {
+            lanes[lane] = 0;
+        }
+
+        return lanes;
+    }
+
+    // Exact always; the ones the two executors may round apart only when the caller has asked for
+    // that trade by name.
+    const foldable = instruction.semantics.foldable
+        || (options.fold_inexact && instruction.semantics.foldable_inexact);
+
+    if (!foldable) {
+        return lanes;
+    }
+
+    for (let lane = 0; lane < count; lane++) {
+        /** @type {Array<number|undefined>} */
+        const inputs = [];
+        let complete = true;
+
+        for (const source of instruction.sources) {
+            const held = source_lane_value(source, lane, known, value);
+
+            if (held === null) {
+                complete = false;
+                continue;
+            }
+
+            inputs[source.operand] = held;
+        }
+
+        if (complete) {
+            lanes[lane] = finite(evaluate_particle_operation(instruction.op, inputs[0], inputs[1], inputs[2]));
+        } else if (options.fold_multiply_by_zero) {
+            lanes[lane] = absorbed_by_zero(instruction.op, inputs);
+        }
+    }
+
+    return lanes;
+}
+
+/**
+ * Zero as an absorbing element: a known zero on either side of a multiply gives zero, whatever the
+ * other operand turns out to be.
+ *
+ * This is the one thing here that is not true of every value a register can hold — `±Inf * 0` and
+ * `NaN * 0` are `NaN`, and a negative operand gives `-0` — and it is what the module comment above
+ * argues the trade for. A known `-0` absorbs as readily as a known `+0`: once the sign of the result
+ * is being given up, it is being given up either way.
+ *
+ * @param {number} op
+ * @param {Array<number|undefined>} inputs by operand slot, `undefined` where the value is unknown
+ * @returns {number|null}
+ */
+function absorbed_by_zero(op, inputs) {
+    if (!PARTICLE_ZERO_ABSORBING_OPS.has(op)) {
+        return null;
+    }
+
+    return inputs[0] === 0 || inputs[1] === 0 ? 0 : null;
+}
+
+/**
+ * One lane of an operation, in the arithmetic the reference executes it in: `f32` operands, an
+ * `f64` computation, and the result rounded back to `f32` — which for a single correctly-rounded
+ * operation is the same number an `f32` machine produces.
+ *
+ * @param {number} op
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @returns {number}
+ */
+export function evaluate_particle_operation(op, a, b, c) {
+    switch (op) {
+        case VM_OP.MOV: return a;
+        case VM_OP.ADD: return Math.fround(a + b);
+        case VM_OP.SUB: return Math.fround(a - b);
+        case VM_OP.MUL: return Math.fround(a * b);
+        case VM_OP.DIV: return Math.fround(a / b);
+        // `Math.min(-0, 0)` is `-0` and WGSL's `min`, spelled `select(e1, e2, e2 < e1)`, is `0` —
+        // the one place these two executors are allowed to disagree bit for bit. Refusing the fold
+        // wherever a zero is involved closes it without pretending the rest of `min` is unreliable.
+        case VM_OP.MIN: return a === 0 || b === 0 ? NaN : Math.min(a, b);
+        case VM_OP.MAX: return a === 0 || b === 0 ? NaN : Math.max(a, b);
+        case VM_OP.CLAMP: return a === 0 || b === 0 || c === 0 ? NaN : Math.min(Math.max(a, b), c);
+        case VM_OP.NEG: return -a;
+        case VM_OP.ABS: return Math.abs(a);
+        case VM_OP.FLOOR: return Math.floor(a);
+        case VM_OP.FRACT: return Math.fround(a - Math.floor(a));
+        case VM_OP.SQRT: return Math.fround(Math.sqrt(a));
+        case VM_OP.STEP: return b < a ? 0 : 1;
+        case VM_OP.CMP_LT: return a < b ? 1 : 0;
+        case VM_OP.CMP_LE: return a <= b ? 1 : 0;
+        case VM_OP.CMP_GT: return a > b ? 1 : 0;
+        case VM_OP.CMP_GE: return a >= b ? 1 : 0;
+        case VM_OP.CMP_EQ: return a === b ? 1 : 0;
+        case VM_OP.SELECT: return c > 0.5 ? b : a;
+
+        // --- reached only under `fold_inexact` ---
+        //
+        // Each of these is spelled exactly as `../vm/ParticleVMReference.js` spells it, so the fold
+        // and the reference agree to the bit and it is the GPU that is allowed to differ. That is
+        // the whole of what the option trades; anything an executor could disagree about by more
+        // than a rounding is refused below rather than folded.
+        case VM_OP.MAD: return Math.fround(a * b + c);
+        case VM_OP.MIX: return Math.fround(a + (b - a) * c);
+        case VM_OP.SIN: return Math.fround(Math.sin(a));
+        case VM_OP.COS: return Math.fround(Math.cos(a));
+        case VM_OP.TAN: return Math.fround(Math.tan(a));
+        case VM_OP.ASIN: return Math.fround(Math.asin(a));
+        case VM_OP.ACOS: return Math.fround(Math.acos(a));
+        case VM_OP.EXP: return Math.fround(Math.exp(a));
+        case VM_OP.LOG: return Math.fround(Math.log(a));
+        // `1 / sqrt(a)` for `a <= 0` is an infinity or a `NaN`, and `finite` drops both — the same
+        // rule that keeps `SQRT` next door out of trouble, so there is nothing to say here.
+        case VM_OP.RSQRT: return Math.fround(1 / Math.sqrt(a));
+        // WGSL's `pow` is `exp2(e2 * log2(e1))`, which is a `NaN` for every base at or below zero
+        // — including `pow(0, 0)`, where JS says 1. A fold that turned the hardware's `NaN` into a
+        // number would not be a rounding, so the non-positive bases are not folded at all.
+        case VM_OP.POW: return a > 0 ? Math.fround(Math.pow(a, b)) : NaN;
+        // Equal edges divide by zero on the GPU; the reference answers 0 or 1 instead. Same
+        // argument as `pow`: refuse the case rather than ship the reference's answer for it.
+        case VM_OP.SMOOTHSTEP: {
+            if (a === b) {
+                return NaN;
+            }
+
+            const t = Math.min(Math.max((c - a) / (b - a), 0), 1);
+
+            return Math.fround(t * t * (3 - 2 * t));
+        }
+        // `atan2(0, 0)` is 0 in JS and left to the implementation in WGSL. Every other pair is an
+        // angle both agree on to a rounding.
+        case VM_OP.ATAN2: return a === 0 && b === 0 ? NaN : Math.fround(Math.atan2(a, b));
+
+        default: return NaN;
+    }
+}
+
+/**
+ * Only finite values are tracked. Dropping `NaN` and `±Inf` here is what keeps every rewrite below
+ * from having to restate its own edge cases.
+ *
+ * @param {number} x
+ * @returns {number|null}
+ */
+function finite(x) {
+    return Number.isFinite(x) ? Math.fround(x) : null;
+}
+
+/**
+ * What one lane of a source is known to hold: a literal is its own value, a register operand is
+ * whatever the analysis has tracked into the slot its swizzle names for that lane. `null` where the
+ * value is not known — or not finite, since only finite values are ever tracked.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} lane output lane
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @returns {number|null}
+ */
+function source_lane_value(source, lane, known, value) {
+    if (source.kind === VM_KIND.IMM) {
+        return finite(vm_f32_value(source.word));
+    }
+
+    // A scalar source feeds every lane from its first; everything else reads straight across.
+    const slot = source.base + swizzle_selector(source.pattern, source.lanes === 1 ? 0 : lane);
+
+    return slot < known.length && known[slot] ? value[slot] : null;
+}
+
+/**
+ * A `MOV` of `width` lanes into `dst` from a source operand, from `first` lanes into it, keeping the
+ * source's kind: a copy of a register is that register read through the selectors those lanes use,
+ * a copy of a literal is that literal.
+ *
+ * @param {number} width
+ * @param {number} dst
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} [first]
+ * @returns {number[]}
+ */
+function move_from(width, dst, source, first = 0) {
+    if (source.kind === VM_KIND.IMM) {
+        return vm_pack_instruction(VM_OP.MOV, width, dst, [VM_KIND.IMM, VM_KIND.NONE, VM_KIND.NONE], [source.word, 0, 0]);
+    }
+
+    let pattern = 0;
+
+    for (let lane = 0; lane < 4; lane++) {
+        pattern |= swizzle_selector(source.pattern, first + lane) << (2 * lane);
+    }
+
+    return vm_pack_instruction(
+        VM_OP.MOV, width, dst,
+        [VM_KIND.REG, VM_KIND.NONE, VM_KIND.NONE],
+        [vm_register(source.base, pattern), 0, 0]
+    );
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ */
+function publish(instruction, lanes, known, value) {
+    if (instruction.write === null) {
+        return;
+    }
+
+    for (let lane = 0; lane < lanes.length; lane++) {
+        const slot = instruction.write.base + lane;
+
+        if (slot >= known.length) {
+            continue;
+        }
+
+        known[slot] = lanes[lane] === null ? 0 : 1;
+        value[slot] = lanes[lane] ?? 0;
+    }
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @param {object} options
+ * @returns {number[][]|null} what to emit instead, or `null` to keep the instruction
+ */
+function rewrite(instruction, lanes, known, value, options) {
+    if (instruction.semantics.side_effects) {
+        return null;
+    }
+
+    const materialised = materialise(instruction, lanes, options);
+
+    if (materialised !== null) {
+        return materialised;
+    }
+
+    if (instruction.op === VM_OP.SELECT) {
+        const collapsed = collapse_select(instruction, known, value, options.max_select_moves);
+
+        if (collapsed !== null) {
+            return collapsed;
+        }
+    }
+
+    const identity = collapse_identity(instruction, known, value);
+
+    if (identity !== null) {
+        return identity;
+    }
+
+    return options.peel_constant_lanes ? peel_constant_tail(instruction, lanes, options) : null;
+}
+
+/**
+ * Split an instruction whose trailing lanes turn out to be constants into the narrower instruction
+ * that computes the rest, plus one load for the tail.
+ *
+ * One instruction becomes two, which only pays for itself through what it frees: the narrowed
+ * instruction stops reading the upper lanes of its sources, and those are usually a broadcast, a
+ * mask, and the arithmetic that built them. A distribution's mask lane is exactly this shape.
+ *
+ * Only for opcodes that compute their result from registers. `LOAD_ATTR`'s lanes past its component
+ * count are already the zero it reads for free, and peeling those would be a load in place of
+ * nothing at all.
+ *
+ * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+ * @param {Array<number|null>} lanes
+ * @param {object} options
+ * @returns {number[][]|null}
+ */
+function peel_constant_tail(instruction, lanes, options) {
+    if (
+        options.intern_constant === null
+        || instruction.write === null
+        || instruction.sources.length === 0
+        || !instruction.semantics.narrowable
+        || instruction.write.span !== instruction.operation_width
+    ) {
+        return null;
+    }
+
+    // The longest run of known lanes at the top, leaving at least one below it for the instruction
+    // to still be worth issuing — one that is constant all the way down was materialised above.
+    let first = lanes.length;
+
+    while (first > 0 && lanes[first - 1] !== null) {
+        first--;
+    }
+
+    if (first === lanes.length || first < Math.max(1, instruction.meta.min_width)) {
+        return null;
+    }
+
+    const narrowed = instruction.words.slice();
+
+    narrowed[0] = vm_with_width(narrowed[0], first);
+
+    const load = vm_pack_instruction(
+        VM_OP.LOAD_CONST, lanes.length - first, instruction.write.base + first,
+        [VM_KIND.NONE, VM_KIND.NONE, VM_KIND.NONE],
+        [options.intern_constant(lanes.slice(first)), 0, 0]
+    );
+
+    return particle_instruction_is_well_formed(narrowed) && particle_instruction_is_well_formed(load)
+        ? [narrowed, load]
+        : null;
+}
+
+/**
+ * Replace an instruction whose every output lane is a known number with the load of that number.
+ *
+ * Neutral in instruction count on its own; the win is that it cuts the instruction loose from
+ * everything that fed it, which is usually then dead.
+ *
+ * @returns {number[][]|null}
+ */
+function materialise(instruction, lanes, options) {
+    if (
+        instruction.op === VM_OP.LOAD_CONST
+        || options.intern_constant === null
+        || lanes.length === 0
+        || lanes.some(lane => lane === null)
+    ) {
+        return null;
+    }
+
+    // A reduction writes one lane whatever it reads, so the load that replaces it is one lane wide.
+    const words = vm_pack_instruction(
+        VM_OP.LOAD_CONST, lanes.length, instruction.write.base,
+        [VM_KIND.NONE, VM_KIND.NONE, VM_KIND.NONE],
+        [options.intern_constant(lanes), 0, 0]
+    );
+
+    return particle_instruction_is_well_formed(words) ? [words] : null;
+}
+
+/**
+ * A `SELECT` whose condition is known lane by lane is not a choice, it is copying — and most of
+ * those copies are a register into itself.
+ *
+ * The replacement is capped at `max_select_moves` instructions: what pays for the split is the
+ * constant load feeding the condition going dead, so a mask that alternates lane by lane and needs
+ * a `MOV` for each run is not worth taking apart.
+ *
+ * The `SELECT` read every source before it wrote; the `MOV`s run one after another. So a copy is
+ * refused where a later one would read a slot an earlier one has already written — the case the
+ * split cannot express — and a run taken from the destination itself is a copy of a register into
+ * itself and is left out.
+ *
+ * @returns {number[][]|null}
+ */
+function collapse_select(instruction, known, value, max_select_moves) {
+    const [when_false, when_true, condition] = instruction.sources;
+    const width = instruction.operation_width;
+    /** @type {import("./particle_program_analysis.js").ParticleOperandRun[]} the source picked, per lane */
+    const chosen = new Array(width);
+
+    for (let lane = 0; lane < width; lane++) {
+        const mask = source_lane_value(condition, lane, known, value);
+
+        if (mask === null) {
+            return null;
+        }
+
+        chosen[lane] = mask > 0.5 ? when_true : when_false;
+    }
+
+    /** @type {number[][]} */
+    const moves = [];
+    /** @type {Set<number>} slots the copies emitted so far have written */
+    const written = new Set();
+
+    for (let lane = 0; lane < width;) {
+        let end = lane + 1;
+
+        while (end < width && chosen[end] === chosen[lane]) {
+            end++;
+        }
+
+        const picked = chosen[lane];
+        const is_itself = picked.kind === VM_KIND.REG
+            && particle_read_slots(picked, width).slice(lane, end).every((slot, i) => slot === instruction.write.base + lane + i);
+
+        if (!is_itself) {
+            const words = move_from(end - lane, instruction.write.base + lane, picked, lane);
+
+            if (!particle_instruction_is_well_formed(words)) {
+                return null;
+            }
+
+            if (picked.kind === VM_KIND.REG
+                && particle_read_slots(picked, width).slice(lane, end).some(slot => written.has(slot))) {
+                return null;
+            }
+
+            moves.push(words);
+        }
+
+        for (let slot = lane; slot < end; slot++) {
+            written.add(instruction.write.base + slot);
+        }
+
+        lane = end;
+    }
+
+    return moves.length <= max_select_moves ? moves : null;
+}
+
+/**
+ * The arithmetic identities that hold for every value a register can hold, not merely the ordinary
+ * ones.
+ *
+ * `x * 1`, `x / 1` and `x - (+0)` are `x` bit for bit — including `-0`, `±Inf` and `NaN` — so they
+ * are copies. `x + 0` is not: `-0 + 0` is `+0`. `x * 0` is not: it is `-0` for negative `x` and
+ * `NaN` for a non-finite one. The line is drawn at what is exactly true, because the record a
+ * program leaves is compared to the bit.
+ *
+ * `MAD` with a multiplier of one becomes an `ADD` for the same reason: `a * 1` is exact, so a
+ * contracted `fma(a, 1, c)` and a plain `a + c` are the same number.
+ *
+ * @returns {number[][]|null}
+ */
+function collapse_identity(instruction, known, value) {
+    const op = instruction.op;
+    const width = instruction.operation_width;
+    const sources = instruction.sources;
+    const is = (source, expected) => source !== undefined && all_lanes_are(source, width, expected, known, value);
+
+    /** Rebuild as a copy of one source, whatever kind it is and however it is swizzled. */
+    const copy_of = (source) => {
+        const words = move_from(width, instruction.write.base, source);
+
+        return particle_instruction_is_well_formed(words) ? [words] : null;
+    };
+
+    switch (op) {
+        case VM_OP.MUL:
+            if (is(sources[1], 1)) return copy_of(sources[0]);
+            if (is(sources[0], 1)) return copy_of(sources[1]);
+            return null;
+
+        case VM_OP.DIV:
+            return is(sources[1], 1) ? copy_of(sources[0]) : null;
+
+        case VM_OP.SUB:
+            // Positive zero only, which is what `Object.is` in `all_lanes_are` gets us: `x - (-0)`
+            // is `x + 0`, and that turns a `-0` into a `+0`.
+            return is(sources[1], 0) ? copy_of(sources[0]) : null;
+
+        case VM_OP.MAD: {
+            const add = (a, b) => {
+                const words = vm_pack_instruction(
+                    VM_OP.ADD, width, instruction.write.base,
+                    [a.kind, b.kind, VM_KIND.NONE],
+                    [a.word, b.word, 0]
+                );
+
+                return particle_instruction_is_well_formed(words) ? [words] : null;
+            };
+
+            if (is(sources[1], 1)) return add(sources[0], sources[2]);
+            if (is(sources[0], 1)) return add(sources[1], sources[2]);
+            return null;
+        }
+
+        default:
+            return null;
+    }
+}
+
+/**
+ * @param {import("./particle_program_analysis.js").ParticleOperandRun} source
+ * @param {number} width
+ * @param {number} expected
+ * @param {Uint8Array} known
+ * @param {Float32Array} value
+ * @returns {boolean}
+ */
+function all_lanes_are(source, width, expected, known, value) {
+    for (let lane = 0; lane < width; lane++) {
+        const held = source_lane_value(source, lane, known, value);
+
+        // `Object.is`, so a `-0` never passes for the `+0` the identity actually needs.
+        if (held === null || !Object.is(held, expected)) {
+            return false;
+        }
+    }
+
+    return true;
+}

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

@@ -0,0 +1,22 @@
+export function pass_inline_constants(instructions: number[][], context: import("./optimize_particle_program.js").ParticleOptimizerContext): number[][];
+/** @type {string} */
+export const PARTICLE_PASS_INLINE_CONSTANTS: string;
+export type ParticleConstantSource = {
+    /**
+     * first register slot the constant is written to
+     */
+    base: number;
+    /**
+     * slots it fills
+     */
+    span: number;
+    /**
+     * the `f32` bit pattern each slot receives
+     */
+    bits: Uint32Array;
+    /**
+     * whether every slot receives the same bits
+     */
+    uniform: boolean;
+};
+//# sourceMappingURL=pass_inline_constants.d.ts.map