@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts

@@ -8,22 +8,44 @@
  * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
  * emitter index; user attributes are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
+ *
+ * ## The `type` tag
+ *
+ * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
+ * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
+ * and every instruction that touches the attribute are exactly what they were without it — and is
+ * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
+ * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ *
+ * A plain string rather than a type object, because the runtime schema has no business importing a
+ * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
+ * as the plain vector it is instead of failing.
  */
 export class ParticleLayout {
     /**
-     * @param {Array<{name: string, components: number}>} attributes ordered attribute declarations
+     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
+     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
+     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
      */
     constructor(attributes: Array<{
         name: string;
         components: number;
+        type?: string;
     }>);
-    /** @type {Map<string, {name: string, offset: number, components: number}>} */
+    /**
+     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
+     */
     attributes: Map<string, {
         name: string;
         offset: number;
         components: number;
+        type: string | undefined;
     }>;
-    /** @type {number} first free word after all attributes */
+    /**
+     * First free word after all attributes.
+     * @type {number}
+     */
     word_cursor: number;
     /**
      * @param {string} name

package/src/shade/renderer/particles/layout/ParticleLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AAMA;;;;;;;;;;GAUG;AACH;IACI;;OAEG;IACH,wBAFW,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,EAsCnD;IAjCG,8EAA8E;IAC9E,YADW,IAAI,MAAM,EAAE;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAC/C;IAuB3B,0DAA0D;IAC1D,aADW,MAAM,CACQ;IAU7B;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}
+{"version":3,"file":"ParticleLayout.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/layout/ParticleLayout.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAcI;;;;OAIG;IACH,wBAJW,MAAM;QAAC,MAAM,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC,EAyClE;IAtDD;;;OAGG;IACH,YAFU,IAAI,MAAM,EAAE;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAC,SAAS,CAAA;KAAC,CAAC,CAE1E;IAEvB;;;OAGG;IACH,aAFU,MAAM,CAE8B;IA8C9C;;;OAGG;IACH,UAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ;QAAC,MAAM,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAQ9D;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

package/src/shade/renderer/particles/layout/ParticleLayout.js

@@ -14,17 +14,41 @@ import {
  * size, colour, …) via a separate render binding. Word 0 of every record is reserved for the owning
  * emitter index; user attributes are packed sequentially from
  * {@link PARTICLE_RECORD_USER_WORD_START}.
+ *
+ * ## The `type` tag
+ *
+ * An attribute may also say what its words are *for*: four of them tagged `color` are a colour
+ * rather than four numbers that happen to be four. It changes nothing here — the offset, the width
+ * and every instruction that touches the attribute are exactly what they were without it — and is
+ * read by the authoring layer, where {@link ../graph/ParticleValueType.js particle_semantic_type}
+ * turns the tag into a type that an editor can offer a swatch for and colour a wire by.
+ *
+ * A plain string rather than a type object, because the runtime schema has no business importing a
+ * frontend's vocabulary, and an effect saved with a tag this build has never heard of has to load
+ * as the plain vector it is instead of failing.
  */
 export class ParticleLayout {
+
+    /**
+     * Attribute name -> where it sits in a particle record, how wide it is, and what it is for.
+     * @type {Map<string, {name: string, offset: number, components: number, type: string|undefined}>}
+     */
+    attributes = new Map();
+
     /**
-     * @param {Array<{name: string, components: number}>} attributes ordered attribute declarations
+     * First free word after all attributes.
+     * @type {number}
+     */
+    word_cursor = PARTICLE_RECORD_USER_WORD_START;
+
+    /**
+     * @param {Array<{name: string, components: number, type?: string}>} attributes ordered
+     *   attribute declarations. `type` optionally says what the words are *for* — see the note on
+     *   {@link #attributes} — and never what shape they are, which is `components` and only that.
      */
     constructor(attributes) {
         assert.isArray(attributes, "attributes");
 
-        /** @type {Map<string, {name: string, offset: number, components: number}>} */
-        this.attributes = new Map();
-
         let cursor = PARTICLE_RECORD_USER_WORD_START;
 
         for (const attribute of attributes) {
@@ -33,6 +57,10 @@ export class ParticleLayout {
             assert.greaterThanOrEqual(attribute.components, 1, "attribute.components must be >= 1");
             assert.lessThanOrEqual(attribute.components, 4, "attribute.components must be <= 4");
 
+            if (attribute.type !== undefined) {
+                assert.isString(attribute.type, "attribute.type");
+            }
+
             if (this.attributes.has(attribute.name)) {
                 throw new Error(`Duplicate particle attribute '${attribute.name}'`);
             }
@@ -41,12 +69,12 @@ export class ParticleLayout {
                 name: attribute.name,
                 offset: cursor,
                 components: attribute.components,
+                type: attribute.type,
             });
 
             cursor += attribute.components;
         }
 
-        /** @type {number} first free word after all attributes */
         this.word_cursor = cursor;
 
         if (cursor > PARTICLE_RECORD_WORD_COUNT) {

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

@@ -0,0 +1,160 @@
+/**
+ * Optimize one section of a particle program.
+ *
+ * @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 {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]
+ * @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?: {
+    constants?: ArrayLike<number>;
+    intern_constant?: (arg0: number[]) => number;
+    passes?: {
+        [x: string]: boolean | object;
+    };
+    max_iterations?: number;
+    speculate?: boolean;
+    register_slots?: number;
+}): 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.
+ *
+ * @param {...string} names
+ * @returns {Object<string, boolean>}
+ */
+export function only_particle_passes(...names: string[]): {
+    [x: string]: boolean;
+};
+/**
+ * Optimize both sections of a compiled program against their shared constant pool.
+ *
+ * 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.
+ *
+ * @param {ParticleProgram} program
+ * @param {object} [options] as {@link optimize_particle_program}, minus the pool it supplies itself
+ * @returns {ParticleProgram}
+ */
+export function optimize_compiled_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.
+ *
+ * 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". 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.
+ *
+ * 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.
+ *
+ * ## 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.
+ */
+/**
+ * @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.
+ *
+ * @type {Array<{name: string, run: ParticleOptimizerPass, max_iterations: number, final?: boolean}>}
+ */
+export const PARTICLE_OPTIMIZER_PASSES: Array<{
+    name: string;
+    run: ParticleOptimizerPass;
+    max_iterations: number;
+    final?: 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.
+ *
+ * @type {Readonly<Object<string, boolean>>}
+ */
+export const PARTICLE_OPTIMIZER_DEFAULT_PASSES: Readonly<{
+    [x: string]: boolean;
+}>;
+/**
+ * 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: number;
+export type ParticleOptimizerPass = (instructions: number[][], context: ParticleOptimizerContext) => number[][] | null;
+export type ParticleOptimizerContext = {
+    /**
+     * the shared constant pool, one float per word
+     */
+    constants: ArrayLike<number>;
+    /**
+     * 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.
+     */
+    intern_constant: (values: number[]) => number;
+    /**
+     * size of the register file
+     */
+    register_slots: number;
+    /**
+     * how many times this pass may repeat itself
+     */
+    max_iterations: number;
+};
+import { InstructionStream } from "../isa/InstructionStream.js";
+import { ParticleProgram } from "../isa/ParticleProgram.js";
+//# sourceMappingURL=optimize_particle_program.d.ts.map

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

@@ -0,0 +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"}