@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -0,0 +1,477 @@
+import { assert } from "../../../../core/assert.js";
+import { PARTICLE_VM_INSTRUCTION_WORDS, PARTICLE_VM_REGISTER_SLOTS } from "../ParticleConstants.js";
+import { InstructionStream } from "../isa/InstructionStream.js";
+import { ParticleAssembler } from "../isa/ParticleAssembler.js";
+import { ParticleProgram } from "../isa/ParticleProgram.js";
+import { VM_OP, vm_decode_op } from "../isa/ParticleVMISA.js";
+import { PARTICLE_PASS_ALLOCATE_REGISTERS, pass_allocate_registers } from "./pass_allocate_registers.js";
+import { PARTICLE_PASS_DEAD_CODE, pass_eliminate_dead_code } from "./pass_eliminate_dead_code.js";
+import {
+    PARTICLE_PASS_DEDUP_CONSTANTS,
+    pass_dedup_constants,
+    visit_particle_constant_reads,
+} from "./pass_dedup_constants.js";
+import { PARTICLE_PASS_FOLD_CONSTANTS, pass_fold_constants } from "./pass_fold_constants.js";
+import { PARTICLE_PASS_INLINE_CONSTANTS, pass_inline_constants } from "./pass_inline_constants.js";
+import { PARTICLE_PASS_NARROW_WIDTHS, pass_narrow_widths } from "./pass_narrow_widths.js";
+import { PARTICLE_PASS_PACK_REGISTERS, pass_pack_registers } from "./pass_pack_registers.js";
+import { PARTICLE_PASS_PEEPHOLE, pass_peephole } from "./pass_peephole.js";
+import { PARTICLE_PASS_PROPAGATE_COPIES, pass_propagate_copies } from "./pass_propagate_copies.js";
+import { PARTICLE_PASS_SHARE_SUBEXPRESSIONS, pass_share_subexpressions } from "./pass_share_subexpressions.js";
+import { PARTICLE_PASS_SCHEDULE, pass_schedule } from "./pass_schedule.js";
+
+/**
+ * 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,
+ * and whatever comes next — and the same waste appears in all of them. The node compiler lowers a
+ * value at a time and has no way to know that the broadcast it just emitted will be read one lane
+ * wide; a pass over the finished stream can simply look.
+ *
+ * ## Shape
+ *
+ * Passes are ordinary functions from an instruction array to a new one, with `null` for "changed
+ * 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 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. 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
+ * @param {number[][]} instructions five-word tuples, in program order
+ * @param {ParticleOptimizerContext} context
+ * @returns {number[][]|null} the rewritten stream, or `null` when the pass changed nothing
+ */
+
+/**
+ * @typedef {object} ParticleOptimizerContext
+ * @property {ArrayLike<number>} constants the shared constant pool, one float per word
+ * @property {((values: number[]) => number)|null} intern_constant interns a run of constants and
+ *   returns its first word index — {@link ../isa/ParticleAssembler.js}'s `constant`. Without it a
+ *   pass can read the pool but not add to it, which only costs it the folds that need a new literal.
+ * @property {number} register_slots size of the register file
+ * @property {number} max_iterations how many times this pass may repeat itself
+ */
+
+/**
+ * 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, enabled?: boolean}>}
+ */
+export const PARTICLE_OPTIMIZER_PASSES = [
+    { name: PARTICLE_PASS_DEAD_CODE, run: pass_eliminate_dead_code, max_iterations: 1 },
+    { name: PARTICLE_PASS_NARROW_WIDTHS, run: pass_narrow_widths, max_iterations: 1 },
+    { name: PARTICLE_PASS_FOLD_CONSTANTS, run: pass_fold_constants, max_iterations: 1 },
+    // Before sharing, and after the folds that intern new literals: two loads of one value are the
+    // same subexpression only once they name the same pool word.
+    { name: PARTICLE_PASS_DEDUP_CONSTANTS, run: pass_dedup_constants, max_iterations: 1 },
+    { name: PARTICLE_PASS_SHARE_SUBEXPRESSIONS, run: pass_share_subexpressions, max_iterations: 1 },
+    { name: PARTICLE_PASS_PROPAGATE_COPIES, run: pass_propagate_copies, max_iterations: 3 },
+    { name: PARTICLE_PASS_PEEPHOLE, run: pass_peephole, max_iterations: 1 },
+    // Last in the sweep: every pass above reasons about constants as loads into registers, and
+    // once a constant is an operand of its consumer there is nothing left for them to see. This is
+    // where the literal kind pays — a third of the simulate pass on a constant-heavy effect, see
+    // ../vm/chunk_particle_vm.js — so it is on like the rest.
+    { name: PARTICLE_PASS_INLINE_CONSTANTS, run: pass_inline_constants, max_iterations: 1 },
+    // Once the instructions have settled, their order: a value that lives no longer than it must
+    // is a slot the allocator below can give back.
+    { name: PARTICLE_PASS_SCHEDULE, run: pass_schedule, max_iterations: 1, final: true },
+    // Allocation packs after every placement itself, so packing on its own is what runs when the
+    // allocator is switched off — and a no-op after it.
+    { name: PARTICLE_PASS_ALLOCATE_REGISTERS, run: pass_allocate_registers, max_iterations: 1, final: true },
+    { name: PARTICLE_PASS_PACK_REGISTERS, run: pass_pack_registers, max_iterations: 1, final: true },
+];
+
+/**
+ * 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 {ReadonlyArray<string>}
+ */
+export const PARTICLE_OPTIMIZER_DEFAULT_PASSES = Object.freeze(
+    PARTICLE_OPTIMIZER_PASSES.filter(pass => pass.enabled !== false).map(pass => pass.name)
+);
+
+/**
+ * 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
+ * value above narrow — so one sweep is never enough. Two settle every program in this tree and
+ * three settle the worst of a hundred generated ones; the budget is well clear of that, because a
+ * program that ran out of sweeps would be a program whose optimization depended on the budget.
+ *
+ * @type {number}
+ */
+export const PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS = 8;
+
+/**
+ * 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 {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_section(stream, {
+    constants = [],
+    intern_constant = null,
+    register_slots = PARTICLE_VM_REGISTER_SLOTS,
+    passes = PARTICLE_OPTIMIZER_DEFAULT_PASSES,
+    max_iterations = PARTICLE_OPTIMIZER_DEFAULT_ITERATIONS,
+    speculate = true,
+    ...settings
+} = {}) {
+    assert.ok(stream instanceof InstructionStream, "stream must be an InstructionStream");
+    assert.isNonNegativeInteger(max_iterations, "max_iterations");
+
+    /** @type {number[][]} */
+    const instructions = stream.instructions.map(words => words.slice());
+    const enabled = new Set(passes);
+    const base_context = { ...settings, constants, intern_constant, register_slots };
+
+    const speculative = to_stream(run_pipeline(instructions, base_context, enabled, max_iterations));
+
+    if (speculate === false || !enabled.has(PARTICLE_PASS_FOLD_CONSTANTS) || settings.peel_constant_lanes === false) {
+        return speculative;
+    }
+
+    // Peeling a constant tail off an instruction always costs one instruction where it fires, and
+    // pays only through what dies above it — a mask's load, the broadcast feeding it, the arithmetic
+    // that built them. Whether that cascade happens is not a local question, and a heuristic for it
+    // would be wrong on somebody's effect. So the pipeline is run both ways and the better program
+    // kept; these are at most a few hundred instructions and settling one twice costs nothing worth
+    // measuring.
+    const conservative = to_stream(
+        run_pipeline(instructions, { ...base_context, peel_constant_lanes: false }, enabled, max_iterations)
+    );
+
+    return better_of(conservative, speculative);
+}
+
+/**
+ * Sweep the enabled passes to a fixed point, then the closing ones to theirs — and round again
+ * while the closing passes keep finding something.
+ *
+ * The two halves feed each other. A schedule frees slots the allocator then reuses, and an
+ * allocated file constrains the next schedule; and a program in a new order is a program the sweep
+ * passes have not seen — a copy whose original is now intact until the read, two loads that are now
+ * adjacent. Each closing acceptance shrinks the file or its peak, so the rounds are bounded by the
+ * file's size, and a program that comes back unchanged from a round is one a second run of the
+ * optimizer would also leave alone.
+ *
+ * @param {number[][]} instructions
+ * @param {object} base_context
+ * @param {Set<string>} enabled
+ * @param {number} max_iterations sweeps of the pass list per round
+ * @returns {number[][]}
+ */
+function run_pipeline(instructions, base_context, enabled, max_iterations) {
+    const running = PARTICLE_OPTIMIZER_PASSES.filter(pass => enabled.has(pass.name));
+    const sweep = running.filter(pass => pass.final !== true);
+    const closing = running.filter(pass => pass.final === true);
+
+    let current = instructions;
+
+    for (let round = 0; round < 2 * base_context.register_slots; round++) {
+        current = run_to_fixed_point(sweep, current, base_context, max_iterations);
+
+        const closed = run_to_fixed_point(closing, current, base_context, 2 * base_context.register_slots);
+
+        if (closed === current) {
+            break;
+        }
+
+        current = closed;
+    }
+
+    return current;
+}
+
+/**
+ * @param {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number}>} passes
+ * @param {number[][]} instructions
+ * @param {object} base_context
+ * @param {number} max_iterations
+ * @returns {number[][]} the settled stream — `instructions` itself when nothing changed
+ */
+function run_to_fixed_point(passes, instructions, base_context, max_iterations) {
+    let current = instructions;
+
+    for (let iteration = 0; iteration < max_iterations; iteration++) {
+        let changed = false;
+
+        for (const pass of passes) {
+            const result = pass.run(current, { ...base_context, max_iterations: pass.max_iterations });
+
+            if (result !== null) {
+                current = result;
+                changed = true;
+            }
+        }
+
+        if (!changed) {
+            break;
+        }
+    }
+
+    return current;
+}
+
+/**
+ * Fewer instructions wins; a tie goes to the smaller register file, and a tie there to the
+ * speculative one, whose instructions are the narrower of the two.
+ *
+ * @param {InstructionStream} conservative
+ * @param {InstructionStream} speculative
+ * @returns {InstructionStream}
+ */
+function better_of(conservative, speculative) {
+    if (conservative.instruction_count !== speculative.instruction_count) {
+        return conservative.instruction_count < speculative.instruction_count ? conservative : speculative;
+    }
+
+    return conservative.register_count < speculative.register_count ? conservative : speculative;
+}
+
+/**
+ * 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 {string[]}
+ */
+export function particle_passes_except(...names) {
+    return PARTICLE_OPTIMIZER_DEFAULT_PASSES.filter(name => !names.includes(name));
+}
+
+/**
+ * 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.
+ *
+ * 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_section}, minus the pool it supplies itself
+ * @returns {ParticleProgram}
+ */
+export function optimize_particle_program(program, options = {}) {
+    assert.ok(program instanceof ParticleProgram, "program must be a ParticleProgram");
+
+    const assembler = new ParticleAssembler();
+
+    assembler.constants = Array.from(program.constants);
+
+    const shared = {
+        ...options,
+        constants: assembler.constants,
+        intern_constant: (values) => assembler.constant(...values),
+    };
+
+    const init = optimize_particle_section(stream_from_words(program.init), shared);
+    const update = optimize_particle_section(stream_from_words(program.update), shared);
+
+    const init_words = init.toWords();
+    const update_words = update.toWords();
+
+    // Last, and here rather than in a pass: which pool words are dead is a question about the whole
+    // program, and a pass sees one section. Running it before the sections settled would be wrong
+    // twice over — the folds are still interning, and the speculation below has not yet thrown away
+    // the run whose literals are the dead ones.
+    const constants = sweep_particle_constants(
+        [init_words, update_words],
+        assembler.constants,
+        (options.passes ?? PARTICLE_OPTIMIZER_DEFAULT_PASSES).includes(PARTICLE_PASS_DEDUP_CONSTANTS)
+            && options.sweep !== false
+    );
+
+    return new ParticleProgram({
+        init: init_words,
+        update: update_words,
+        constants,
+        register_count: Math.max(init.register_count, update.register_count),
+    });
+}
+
+/**
+ * Drop the pool words no section loads any more, and move the loads onto what is left.
+ *
+ * Marking is per word rather than per run, and that is what makes compaction safe for runs that
+ * overlap — a scalar sharing the leading word of a `vec4` is something the assembler deliberately
+ * produces. Every word of a live run is marked, and compaction keeps marked words in order, so a run
+ * whose words were consecutive still is; only its base moves.
+ *
+ * @param {Uint32Array[]} sections instruction words, rewritten in place
+ * @param {ArrayLike<number>} constants the shared pool
+ * @param {boolean} enabled
+ * @returns {Float32Array} the pool the sections now address
+ */
+function sweep_particle_constants(sections, constants, enabled) {
+    if (!enabled) {
+        return new Float32Array(constants);
+    }
+
+    const live = new Uint8Array(constants.length);
+
+    let well_formed = true;
+
+    for (const words of sections) {
+        visit_particle_constant_reads(instruction_tuples(words), (index, base, span) => {
+            if (base < 0 || base + span > constants.length) {
+                // Out of the pool already. Compacting under it would turn a program that fails
+                // validation into one that fails it somewhere else, so nothing is touched.
+                well_formed = false;
+                return;
+            }
+
+            for (let i = 0; i < span; i++) {
+                live[base + i] = 1;
+            }
+        });
+    }
+
+    if (!well_formed) {
+        return new Float32Array(constants);
+    }
+
+    /** @type {number[]} */
+    const kept = [];
+
+    /** @type {Int32Array} old word index -> new one; only meaningful where `live` */
+    const remap = new Int32Array(constants.length);
+
+    for (let i = 0; i < constants.length; i++) {
+        remap[i] = kept.length;
+
+        if (live[i] === 1) {
+            kept.push(constants[i]);
+        }
+    }
+
+    if (kept.length !== constants.length) {
+        for (const words of sections) {
+            for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+                if (vm_decode_op(words[base]) === VM_OP.LOAD_CONST) {
+                    words[base + 1] = remap[words[base + 1]];
+                }
+            }
+        }
+    }
+
+    return new Float32Array(kept);
+}
+
+/**
+ * A packed section as the four-word tuples the pass helpers read.
+ *
+ * @param {Uint32Array} words
+ * @returns {Uint32Array[]} views, so nothing is copied
+ */
+function instruction_tuples(words) {
+    const out = [];
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        out.push(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
+    }
+
+    return out;
+}
+
+/**
+ * @param {Uint32Array} words a packed instruction section
+ * @returns {InstructionStream}
+ */
+export function stream_from_words(words) {
+    const out = new InstructionStream();
+
+    for (let base = 0; base < words.length; base += PARTICLE_VM_INSTRUCTION_WORDS) {
+        out.emitWords(words.subarray(base, base + PARTICLE_VM_INSTRUCTION_WORDS));
+    }
+
+    return out;
+}
+
+/**
+ * Re-emit into a fresh stream, so the register high-water mark is the optimized program's rather
+ * than the one it was built from. A file that shrank is itself part of the win — it is the
+ * interpreter's dominant register cost (see the occupancy note in `vm/chunk_particle_vm.js`) — and
+ * carrying the old count forward would hide it.
+ *
+ * @param {number[][]} instructions
+ * @returns {InstructionStream}
+ */
+function to_stream(instructions) {
+    const out = new InstructionStream();
+
+    for (const words of instructions) {
+        out.emitWords(words);
+    }
+
+    return out;
+}

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

@@ -0,0 +1,100 @@
+/**
+ * The bound on one lane of an operation's result, from the bounds on that lane of its sources.
+ *
+ * The rules are magnitudes and nothing else — `|a * b| <= |a| * |b|` — so they say the same thing
+ * about a lane of an instruction and about a node of a value graph, and both callers read them from
+ * here rather than each keeping a copy of the table.
+ *
+ * @param {number} op
+ * @param {number} a bound on source 0, `Infinity` when it is unknown or absent
+ * @param {number} b bound on source 1
+ * @param {number} c bound on source 2
+ * @param {number} [width] lanes the operation spans — read only by the reductions
+ * @param {function(): number[]} [whole_operands] bounds over EVERY lane of sources 0 and 1, which is
+ *   what a reduction sums over; never called for a lanewise operation
+ * @returns {number}
+ */
+export function particle_integer_bound_of_operation(op: number, a: number, b: number, c: number, width?: number, whole_operands?: () => number[]): number;
+/**
+ * @param {number} value
+ * @returns {number} the value's magnitude when it is an integer, `Infinity` otherwise
+ */
+export function particle_integer_bound_of_value(value: number): number;
+/**
+ * Which register slots hold an integer, and how big it can be — the one fact that makes a float
+ * rewrite exact.
+ *
+ * `a * b + c` as `MAD` is a different number from `MUL` then `ADD` because the pair rounds the
+ * product before adding it and the fused form does not. When the product is an integer below 2^24
+ * it needs no rounding, and the two forms are then the same number on every executor — whether the
+ * hardware contracts the `MAD` into an FMA or not. So the peephole can fuse those pairs without
+ * giving anything up, provided it can PROVE the product is that small, and this is the analysis
+ * that proves it.
+ *
+ * The facts come from the shapes effects are actually made of. A comparison or a `step` is 0 or 1;
+ * a mask built from one, `cmp * 2 - 1`, is -1 or 1; a literal is whatever it is. Those flow through
+ * copies, negation, `abs`, `floor`, `min`, `max`, `clamp` and `select` unchanged in kind, and
+ * through the arithmetic with their bounds combined. Everything else — a draw, an attribute, a
+ * builtin, `fract`, a division, a transcendental — is unknown. So is any value whose bound would
+ * pass 2^24: above it an integer may no longer be representable, and once a rounding could have
+ * happened nothing downstream is exact any more.
+ *
+ * ## Why the bound is a magnitude and not an interval
+ *
+ * Exactness of a product is a question about magnitudes, and `|a * b| <= |a| * |b|` is all it
+ * needs. An interval would prove more — that `x - floor(x / 289) * 289` is small, say, which is
+ * the other shape the noise library is made of — but only from a bound on `x`, which is a
+ * position, and there is none. That rewrite stays behind the `fuse_multiply_add` switch.
+ *
+ * The file starts zeroed on both executors, so every slot begins as the integer 0.
+ */
+export class ParticleIntegerBounds {
+    /**
+     * @param {ArrayLike<number>} constants the shared constant pool, which `LOAD_CONST` reads
+     * @param {number} [slots]
+     */
+    constructor(constants: ArrayLike<number>, slots?: number);
+    /** @type {ArrayLike<number>} */
+    constants: ArrayLike<number>;
+    /** @type {Float64Array} per slot, the largest magnitude the integer it holds can have; `Infinity` when it is not known to hold one */
+    bound: Float64Array;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the largest bound among the lanes read, or `Infinity`
+     */
+    bound_of_read(read: import("./particle_program_analysis.js").ParticleOperandRun, lanes?: number): number;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} source any operand
+     * @param {number} [lanes] how many lanes are read; the operand's own count when left out
+     * @returns {number} the bound on what it reads: a literal's own magnitude, or a run's
+     */
+    bound_of_source(source: import("./particle_program_analysis.js").ParticleOperandRun, lanes?: number): number;
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * @param {ArrayLike<number>} words the four words of a single instruction, as they will run
+     */
+    publish(words: ArrayLike<number>): void;
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleDecodedInstruction} instruction
+     * @param {number} span lanes the instruction writes
+     * @returns {number[]} the bound each written lane will hold — gathered before anything is
+     *   written, since a source may alias the destination
+     */
+    lanes_written(instruction: import("./particle_program_analysis.js").ParticleDecodedInstruction, span: number): number[];
+    /**
+     * @param {import("./particle_program_analysis.js").ParticleOperandRun} read a `REG` run
+     * @param {number} lane
+     * @returns {number} the bound of the slot that lane reads
+     */
+    bound_of_slot(read: import("./particle_program_analysis.js").ParticleOperandRun, lane: number): number;
+}
+/**
+ * Integers up to here are exactly representable as `f32`, and so are all their sums and products
+ * that stay under it. Above it, integers thin out and a rounding could have happened.
+ *
+ * @type {number}
+ */
+export const PARTICLE_EXACT_INTEGER_LIMIT: number;
+//# sourceMappingURL=particle_integer_bounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_integer_bounds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_integer_bounds.js"],"names":[],"mappings":"AAmJA;;;;;;;;;;;;;;;GAeG;AACH,wDATW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,UACN,MAAM,yBACM,MAAM,EAAE,GAElB,MAAM,CAkDlB;AAUD;;;GAGG;AACH,uDAHW,MAAM,GACJ,MAAM,CAIlB;AA/ND;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;OAGG;IACH,uBAHW,UAAU,MAAM,CAAC,UACjB,MAAM,EAOhB;IAJG,gCAAgC;IAChC,WADW,UAAU,MAAM,CAAC,CACF;IAC1B,sIAAsI;IACtI,OADW,YAAY,CACa;IAGxC;;;;OAIG;IACH,oBAJW,OAAO,gCAAgC,EAAE,kBAAkB,UAC3D,MAAM,GACJ,MAAM,CAclB;IAED;;;;OAIG;IACH,wBAJW,OAAO,gCAAgC,EAAE,kBAAkB,UAC3D,MAAM,GACJ,MAAM,CAMlB;IAED;;;;OAIG;IACH,eAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;;;OAKG;IACH,2BALW,OAAO,gCAAgC,EAAE,0BAA0B,QACnE,MAAM,GACJ,MAAM,EAAE,CAkCpB;IAED;;;;OAIG;IACH,oBAJW,OAAO,gCAAgC,EAAE,kBAAkB,QAC3D,MAAM,GACJ,MAAM,CAMlB;CACJ;AAoED;;;;;GAKG;AACH,2CAFU,MAAM,CAEoC"}