@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,291 @@
+/**
+ * The analysis every optimizer pass reads: instructions decoded into the operand runs they touch,
+ * the def-use graph over those runs, and per-lane liveness.
+ *
+ * Everything here is derived, never authoritative — the instruction words are. A pass rewrites
+ * words and the next one re-derives, which is why there is no incremental update path and no
+ * mutation of an analysis in place: the programs are at most
+ * {@link ../ParticleConstants.js PARTICLE_VM_MAX_INSTRUCTIONS} instructions over
+ * {@link PARTICLE_VM_REGISTER_SLOTS} slots, and re-deriving all of it is cheaper than keeping it
+ * honest.
+ *
+ * ## Lanes, not registers
+ *
+ * A register is one `f32` slot and an operand of width `w` is a RUN of `w` of them, so nothing here
+ * is per-register: a value's producer is per (instruction, lane), and so is its liveness. The rules
+ * for how far an operand reaches are irregular — reductions write one lane, `SCALE` and `CURVE`
+ * have a scalar source, a `SWIZZLE` reads as far as its pattern names, `STORE_ATTR` and `KILL` keep
+ * a *source* in the destination slot — and they are not restated here:
+ * {@link vm_visit_register_operands} is the one place that knows them.
+ */
+/**
+ * @typedef {object} ParticleOperandRun
+ * @property {number} operand which operand this is: `-1` for the source that `STORE_ATTR` and
+ *   `KILL` keep in the destination slot, otherwise the source slot `0..2`.
+ * @property {number} base first register slot
+ * @property {number} span consecutive slots the operand reaches
+ */
+/**
+ * @typedef {object} ParticleDecodedInstruction
+ * @property {number} index position in the stream
+ * @property {number[]} words the five instruction words
+ * @property {number} op
+ * @property {number} width the encoded width field
+ * @property {number} operation_width lanes the operation spans, after the ISA's fixed-width rules
+ * @property {object} meta the {@link VM_ISA} entry
+ * @property {import("./particle_vm_semantics.js").ParticleOpSemantics} semantics
+ * @property {ParticleOperandRun|null} write destination run, or null when the opcode writes nothing
+ * @property {ParticleOperandRun[]} reads every register run the instruction reads
+ */
+/**
+ * Decode one instruction into the runs of register slots it reads and writes.
+ *
+ * @param {ArrayLike<number>} words the five words of a single instruction
+ * @param {number} [index]
+ * @returns {ParticleDecodedInstruction}
+ */
+export function decode_particle_instruction(words: ArrayLike<number>, index?: number): ParticleDecodedInstruction;
+/**
+ * @param {ArrayLike<ArrayLike<number>>} instructions five-word tuples
+ * @returns {ParticleDecodedInstruction[]}
+ */
+export function decode_particle_instructions(instructions: ArrayLike<ArrayLike<number>>): ParticleDecodedInstruction[];
+/**
+ * Whether an instruction's operands satisfy the rule {@link ../isa/ParticleProgram.js} enforces:
+ * two runs of one instruction name the same slots or disjoint ones, never a partial overlap.
+ *
+ * Every executor reads slot `c` of a source to write slot `c` of the destination, so an exact alias
+ * is fine and a shifted one would read slots the same instruction has already written. A pass that
+ * moves a base or changes a width can turn a legal pair into an illegal one, so each of them checks
+ * its candidate here before keeping it — cheaper than discovering it in `validate()` downstream, and
+ * it keeps the rule stated once.
+ *
+ * @param {ArrayLike<number>} words the five words of a single instruction
+ * @returns {boolean}
+ */
+export function particle_instruction_is_well_formed(words: ArrayLike<number>): boolean;
+/**
+ * Def-use over the instruction stream: an edge `i -> j` says instruction `j` reads a slot
+ * instruction `i` last wrote.
+ *
+ * Straight-line code with no control flow, so "last wrote" is exact rather than a may-reach
+ * approximation: one forward scan of a slot-indexed table finds every producer. The result is a
+ * {@link CSRGraph} because that is what the rest of the engine walks — `edge_addresses` /
+ * `adjacency` directly, without a per-vertex closure — and because dead-code elimination is then a
+ * reachability question over it rather than a bespoke container.
+ *
+ * A read of a slot nothing has written yet has no producer and contributes no edge: the register
+ * file starts zeroed on both executors, so such a read is a constant, not a dependency.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {CSRGraph} vertices are instructions; vertex `i`'s adjacency lists its consumers
+ */
+export function build_particle_def_use_graph(decoded: ParticleDecodedInstruction[], register_slots?: number): CSRGraph;
+/**
+ * @typedef {object} ParticleLaneAnalysis
+ * @property {Uint8Array} keep per instruction: whether it has to survive — it runs, and either it
+ *   has an effect beyond its destination or something reads a lane it writes
+ * @property {Int32Array} width per instruction: the width field it could carry, once the lanes
+ *   nothing reads are dropped. Equal to the encoded one wherever narrowing is not allowed.
+ * @property {Int32Array} pattern per instruction: the swizzle pattern at that width; the encoded
+ *   one for every other opcode.
+ * @property {Uint8Array} live_lanes per instruction: bitmask of destination lanes read later
+ * @property {number} halt_index index of the first `HALT`, or `-1`
+ */
+/**
+ * Backward per-lane liveness: which lanes of each instruction's destination anything downstream
+ * actually reads, and therefore how narrow the instruction could be and whether it is needed at all.
+ *
+ * Registers do not outlive a section — both executors start a particle with a zeroed file — so the
+ * walk starts with nothing live and everything a program means has already been written to the
+ * record, the kill flag or the RNG by the time it ends.
+ *
+ * Narrowing is decided inside the same backward pass rather than after it, because an instruction's
+ * reads follow its width: narrowing a broadcast to two lanes shortens the run it reads, which is
+ * what makes the value above it dead. Deciding both at once reaches that fixed point in one sweep.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} [register_slots]
+ * @returns {ParticleLaneAnalysis}
+ */
+export function analyze_particle_lanes(decoded: ParticleDecodedInstruction[], register_slots?: number): ParticleLaneAnalysis;
+/**
+ * How far a read reaches once the instruction is narrowed to `operation_width`.
+ *
+ * @param {ParticleDecodedInstruction} instruction
+ * @param {ParticleOperandRun} read
+ * @param {number} operation_width
+ * @param {number} pattern the (possibly trimmed) swizzle pattern
+ * @returns {number}
+ */
+export function read_span_at(instruction: ParticleDecodedInstruction, read: ParticleOperandRun, operation_width: number, pattern: number): number;
+/**
+ * @param {number} base_a
+ * @param {number} span_a
+ * @param {number} base_b
+ * @param {number} span_b
+ * @returns {boolean} whether the two runs share a slot
+ */
+export function particle_runs_overlap(base_a: number, span_a: number, base_b: number, span_b: number): boolean;
+/**
+ * Whether anything in `[from, to)` reads or writes any slot of a run.
+ *
+ * What a pass moving an instruction has to ask: a value that nothing in the gap looks at or
+ * disturbs can be produced anywhere in that gap.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} from inclusive
+ * @param {number} to exclusive
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_touched_between(decoded: ParticleDecodedInstruction[], from: number, to: number, base: number, span: number): boolean;
+/**
+ * Whether every slot of a run is overwritten — or the section ends — before anything reads it again.
+ *
+ * A run that is dead from `index` onwards belongs to nobody, so the instruction that filled it may
+ * be retargeted, folded into its consumer, or dropped.
+ *
+ * @param {ParticleDecodedInstruction[]} decoded
+ * @param {number} index the instruction after which to look
+ * @param {number} base
+ * @param {number} span
+ * @returns {boolean}
+ */
+export function particle_run_is_dead_after(decoded: ParticleDecodedInstruction[], index: number, base: number, span: number): boolean;
+/**
+ * Which value each register slot holds, as a number, and where that value was first computed.
+ *
+ * Two passes ask questions that turn out to be the same question underneath. "Is this register still
+ * the copy it was?" and "has this expression already been evaluated?" both reduce to comparing value
+ * numbers, and both need a copy to carry its source's number across rather than minting a new one —
+ * otherwise a value moved between registers stops being recognisable as itself.
+ *
+ * Numbers are minted per write and inherited by `MOV` and `SWIZZLE`, the only two opcodes that move
+ * a value without changing it. Because a number is never reused, a slot overwritten since simply
+ * fails to match, and there is no invalidation step to get wrong.
+ */
+export class ParticleValueNumbering {
+    /**
+     * @param {number} [slots]
+     */
+    constructor(slots?: number);
+    /** @type {number} */
+    slots: number;
+    /** @type {Int32Array} the value in each slot */
+    value_id: Int32Array;
+    /** @type {Int32Array} the slot each value was first computed in */
+    home: Int32Array;
+    /** @type {number} */
+    next_id: number;
+    /**
+     * @param {number} base
+     * @param {number} span
+     * @returns {number[]|null} the numbers in that run, or `null` if it leaves the file
+     */
+    ids_of(base: number, span: number): number[] | null;
+    /**
+     * @param {number} base
+     * @param {number[]} ids
+     * @returns {boolean} whether that run still holds exactly those values
+     */
+    holds(base: number, ids: number[]): boolean;
+    /**
+     * Where the values in a run were originally computed, when that is itself a run and still holds
+     * them.
+     *
+     * Two lanes of a broadcast were both computed in the same slot, which is not a run — so a
+     * broadcast as a whole has no origin to be read past, however each of its lanes does.
+     *
+     * @param {number} base
+     * @param {number} span
+     * @returns {number} the origin's base, or `-1`
+     */
+    origin_of(base: number, span: number): number;
+    /**
+     * Record what an instruction leaves in its destination.
+     *
+     * Takes the words as they will be EMITTED rather than as they were read, because a pass may have
+     * moved a source or rewritten the opcode by the time it gets here — the state has to describe
+     * the program that will run.
+     *
+     * @param {ArrayLike<number>} words the five words of a single instruction
+     */
+    publish(words: ArrayLike<number>): void;
+}
+export type ParticleOperandRun = {
+    /**
+     * which operand this is: `-1` for the source that `STORE_ATTR` and
+     * `KILL` keep in the destination slot, otherwise the source slot `0..2`.
+     */
+    operand: number;
+    /**
+     * first register slot
+     */
+    base: number;
+    /**
+     * consecutive slots the operand reaches
+     */
+    span: number;
+};
+export type ParticleDecodedInstruction = {
+    /**
+     * position in the stream
+     */
+    index: number;
+    /**
+     * the five instruction words
+     */
+    words: number[];
+    op: number;
+    /**
+     * the encoded width field
+     */
+    width: number;
+    /**
+     * lanes the operation spans, after the ISA's fixed-width rules
+     */
+    operation_width: number;
+    /**
+     * the {@link VM_ISA } entry
+     */
+    meta: object;
+    semantics: import("./particle_vm_semantics.js").ParticleOpSemantics;
+    /**
+     * destination run, or null when the opcode writes nothing
+     */
+    write: ParticleOperandRun | null;
+    /**
+     * every register run the instruction reads
+     */
+    reads: ParticleOperandRun[];
+};
+export type ParticleLaneAnalysis = {
+    /**
+     * per instruction: whether it has to survive — it runs, and either it
+     * has an effect beyond its destination or something reads a lane it writes
+     */
+    keep: Uint8Array;
+    /**
+     * per instruction: the width field it could carry, once the lanes
+     * nothing reads are dropped. Equal to the encoded one wherever narrowing is not allowed.
+     */
+    width: Int32Array;
+    /**
+     * per instruction: the swizzle pattern at that width; the encoded
+     * one for every other opcode.
+     */
+    pattern: Int32Array;
+    /**
+     * per instruction: bitmask of destination lanes read later
+     */
+    live_lanes: Uint8Array;
+    /**
+     * index of the first `HALT`, or `-1`
+     */
+    halt_index: number;
+};
+import { CSRGraph } from "../../../../core/graph/csr/CSRGraph.js";
+//# sourceMappingURL=particle_program_analysis.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_program_analysis.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/optimizer/particle_program_analysis.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,mDAJW,UAAU,MAAM,CAAC,UACjB,MAAM,GACJ,0BAA0B,CA8DtC;AAED;;;GAGG;AACH,2DAHW,UAAU,UAAU,MAAM,CAAC,CAAC,GAC1B,0BAA0B,EAAE,CAUxC;AAED;;;;;;;;;;;;GAYG;AACH,2DAHW,UAAU,MAAM,CAAC,GACf,OAAO,CAyBnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,sDAJW,0BAA0B,EAAE,mBAC5B,MAAM,GACJ,QAAQ,CA0DpB;AAED;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,gDAJW,0BAA0B,EAAE,mBAC5B,MAAM,GACJ,oBAAoB,CAmFhC;AAED;;;;;;;;GAQG;AACH,0CANW,0BAA0B,QAC1B,kBAAkB,mBAClB,MAAM,WACN,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;GAMG;AACH,8CANW,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,OAAO,CAInB;AAED;;;;;;;;;;;;GAYG;AACH,yDAPW,0BAA0B,EAAE,QAC5B,MAAM,MACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,OAAO,CAmBnB;AAED;;;;;;;;;;;GAWG;AACH,oDANW,0BAA0B,EAAE,SAC5B,MAAM,QACN,MAAM,QACN,MAAM,GACJ,OAAO,CAiCnB;AAED;;;;;;;;;;;GAWG;AACH;IACI;;OAEG;IACH,oBAFW,MAAM,EAkBhB;IAfG,qBAAqB;IACrB,OADW,MAAM,CACC;IAClB,gDAAgD;IAChD,UADW,UAAU,CACgB;IACrC,mEAAmE;IACnE,MADW,UAAU,CACY;IACjC,qBAAqB;IACrB,SADW,MAAM,CACG;IAUxB;;;;OAIG;IACH,aAJW,MAAM,QACN,MAAM,GACJ,MAAM,EAAE,GAAC,IAAI,CAczB;IAED;;;;OAIG;IACH,YAJW,MAAM,OACN,MAAM,EAAE,GACN,OAAO,CAcnB;IAED;;;;;;;;;;OAUG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;OAQG;IACH,eAFW,UAAU,MAAM,CAAC,QAwC3B;CACJ;;;;;;aA1kBa,MAAM;;;;UAEN,MAAM;;;;UACN,MAAM;;;;;;WAKN,MAAM;;;;WACN,MAAM,EAAE;QACR,MAAM;;;;WACN,MAAM;;;;qBACN,MAAM;;;;UACN,MAAM;eACN,OAAO,4BAA4B,EAAE,mBAAmB;;;;WACxD,kBAAkB,GAAC,IAAI;;;;WACvB,kBAAkB,EAAE;;;;;;;UAyMpB,UAAU;;;;;WAEV,UAAU;;;;;aAEV,UAAU;;;;gBAEV,UAAU;;;;gBACV,MAAM;;yBAtQK,wCAAwC"}