@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/particles/effect/ParticleEffectDocument.d.ts

@@ -0,0 +1,396 @@
+/**
+ * Which representation {@link ParticleEffectDocumentcompile } builds the program from.
+ */
+export type PARTICLE_EFFECT_SOURCE = string;
+/**
+ * One particle effect being edited: the thing both layers of the editor point at.
+ *
+ * An effect is four things — the per-particle attribute schema, an INIT graph, an UPDATE graph, and
+ * the emitter settings that say how the result is drawn. The graph editor edits the middle two, the
+ * code editor edits what they compile to, the emitter inspector edits the last, and the preview
+ * watches all of it. Putting them in one object with one change signal is what lets those be four
+ * independent views rather than four copies of the same state.
+ *
+ * ## Which layer is in charge
+ *
+ * The two editing layers are not two views of one representation — the graph compiles to the
+ * program and nothing compiles back. So the document names which one the program comes from:
+ *
+ * - {@link PARTICLE_EFFECT_SOURCE.GRAPH}: the program is compiled from the graphs on every
+ *   {@link compile}. The assembly text is a lowering of them, shown but not read.
+ * - {@link PARTICLE_EFFECT_SOURCE.ASSEMBLY}: the program is assembled from {@link assembly}. The
+ *   graphs are still there and still editable, but they are not what runs.
+ *
+ * {@link lowerToAssembly} moves from the first to the second, seeding the text with what the graphs
+ * compile to. Going back is {@link source} set to GRAPH: the text is kept, so an author who
+ * switches by accident has not lost their edits, but it stops being what runs.
+ *
+ * ## Optimizing
+ *
+ * {@link optimize} runs the compiled program through
+ * {@link ../../../src/shade/renderer/particles/optimizer/optimize_particle_program.js the optimizer}
+ * before anybody gets it. It is a property of the effect rather than of a view because it changes
+ * what runs — the preview, the reference simulation and anything else downstream of {@link compile}
+ * all get the optimized program — and a switch that changed what runs while living in one panel
+ * would be invisible from the other three.
+ *
+ * It applies whichever layer is authoritative, including hand-written assembly, which is a program
+ * like any other. What it never does is rewrite {@link assembly}: the author's text stays the text
+ * they typed, and only the program underneath it changes. See {@link assemblyText}.
+ */
+/**
+ * Which representation {@link ParticleEffectDocument#compile} builds the program from.
+ * @enum {string}
+ */
+export const PARTICLE_EFFECT_SOURCE: Readonly<{
+    GRAPH: "graph";
+    ASSEMBLY: "assembly";
+}>;
+/**
+ * A compile attempt's outcome.
+ *
+ * @typedef {object} ParticleEffectCompilation
+ * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} program
+ *   null when anything went wrong
+ * @property {ParticleLayout|null} layout the attribute schema the program was compiled against;
+ *   null when the declarations themselves are not a valid layout
+ * @property {import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null} unoptimized
+ *   what `program` was built from, before the optimizer. The same object as `program` when
+ *   {@link ParticleEffectDocument#optimize} is off, so a caller wanting the comparison can always
+ *   ask for it and gets "no difference" rather than a special case.
+ * @property {Array<{scope: string, node: number, line: number, message: string, severity: string}>} diagnostics
+ *   `scope` is `"init"`, `"update"`, `"assembly"` or `"effect"`; `node` is a node id or -1;
+ *   `line` is a 1-based assembly line or 0
+ */
+export class ParticleEffectDocument {
+    /**
+     * @type {string}
+     */
+    name: string;
+    /**
+     * The per-particle attribute declarations, in the order they are packed into a record.
+     *
+     * `type` is optional and says what the words are for rather than how many there are — see
+     * {@link ../../../src/shade/renderer/particles/layout/ParticleLayout.js ParticleLayout}. It is
+     * why reading `color` gives a colour in the graph and reading `position` gives a `vec3`.
+     *
+     * @type {Array<{name: string, components: number, type?: string}>}
+     */
+    attributes: Array<{
+        name: string;
+        components: number;
+        type?: string;
+    }>;
+    /**
+     * The node groups this document carries of its own — the ones an author made in it.
+     *
+     * A group the library ships is code, is shared by every effect, and is looked up by name. One of
+     * these is a thing in this file: it travels with the effect, it is nobody else's, and it is
+     * always the author's to edit. Two documents may each have a `group.1` and they are different
+     * groups, which is why a document resolves its own names first — see {@link groupNamed}.
+     *
+     * @type {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup[]}
+     */
+    groups: import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup[];
+    /**
+     * @type {NodeGraph}
+     */
+    init: NodeGraph;
+    /**
+     * @type {NodeGraph}
+     */
+    update: NodeGraph;
+    /**
+     * Node positions for the INIT graph. Part of the document, not of the view: an effect whose
+     * arrangement is not saved with it has to be re-arranged every time it is opened.
+     * @type {NodeGraphVisualData}
+     */
+    init_visual: NodeGraphVisualData;
+    /**
+     * @type {NodeGraphVisualData}
+     */
+    update_visual: NodeGraphVisualData;
+    /**
+     * The emitter settings — everything about the effect that is not the simulation itself. Shaped
+     * to be handed straight to {@link ParticleEmitter.from}.
+     * @type {object}
+     */
+    emitter: object;
+    /**
+     * Which representation the program comes from.
+     * @type {string}
+     */
+    source: string;
+    /**
+     * The code layer's text buffer. Under {@link PARTICLE_EFFECT_SOURCE.GRAPH} this is a lowering of
+     * the graphs, refreshed by {@link compile}; under ASSEMBLY it is the author's, and what runs.
+     * @type {string}
+     */
+    assembly: string;
+    /**
+     * Whether {@link compile} hands back the optimized program.
+     *
+     * Off by default, and off for every effect saved before it existed, because it is a thing an
+     * author turns on to see what it does rather than something done to their effect behind them.
+     *
+     * @type {boolean}
+     */
+    optimize: boolean;
+    /**
+     * Bumped on every {@link touch}. A view that caches something derived from the document can
+     * compare against this instead of recomputing on every frame.
+     * @type {number}
+     */
+    version: number;
+    /**
+     * @readonly
+     */
+    readonly on: {
+        /**
+         * Something about the effect changed. Carries the document.
+         * @readonly
+         * @type {Signal<ParticleEffectDocument>}
+         */
+        readonly changed: any;
+    };
+    /**
+     * Announce a change. Every edit path — a graph action, an attribute added, a parameter set,
+     * assembly typed — ends here, and every view that shows the effect is downstream of it.
+     *
+     * Inside a {@link batch} the announcement is held until the batch ends, and however many changes
+     * it covered arrive as one.
+     */
+    touch(): void;
+    /**
+     * Run a run of edits as one change.
+     *
+     * Loading a document is a hundred and fifty node and connection additions, and every one of them
+     * is a change to the document. Without this the preview would recompile the effect once per
+     * node, and every control in the editor would rebuild as many times.
+     *
+     * Nests, and announces even if the body throws — a half-applied edit is still an edit, and a
+     * view left showing the state before it would be showing something that is not there.
+     *
+     * @template T
+     * @param {function():T} body
+     * @returns {T}
+     */
+    batch<T>(body: () => T): T;
+    /**
+     * A node type this document carries of its own, by name; `undefined` for anything else.
+     *
+     * What every path that resolves a type name consults before the standard library, so that a
+     * group made here is found here — see {@link groups}.
+     *
+     * @param {string} name
+     * @returns {import("../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js").ParticleNodeDescription|undefined}
+     */
+    ownDescription(name: string): import("../../../src/shade/renderer/particles/graph/ParticleNodeDescription.js").ParticleNodeDescription | undefined;
+    /**
+     * @param {string} name
+     * @returns {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup|undefined}
+     */
+    groupNamed(name: string): import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup | undefined;
+    /**
+     * A name no type answers to yet, here or in the standard library.
+     *
+     * Groups an author makes are numbered rather than asked about, because a dialog between wanting
+     * a group and having one is a dialog in the way. The name is an address and stays put; what an
+     * author renames is the label, which is what they read.
+     *
+     * @param {string} [prefix]
+     * @returns {string}
+     */
+    unusedGroupName(prefix?: string): string;
+    /**
+     * Take on a group.
+     *
+     * @param {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {void}
+     * @throws if something already answers to that name
+     */
+    addGroup(group: import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup): void;
+    /**
+     * Give up a group.
+     *
+     * Nodes still using it are left alone and become unresolvable, which is loud and recoverable;
+     * quietly rewriting somebody's graph to remove them would be neither. Callers that remove a group
+     * are expected to have removed its uses first, and the undo of a grouping does exactly that.
+     *
+     * @param {import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup} group
+     * @returns {boolean} false when the document did not have it
+     */
+    removeGroup(group: import("../../../src/shade/renderer/particles/graph/ParticleNodeGroup.js").ParticleNodeGroup): boolean;
+    /**
+     * The attribute schema as the compiler and the runtime want it.
+     *
+     * Rebuilt on demand rather than held, because {@link attributes} is what an author edits and a
+     * cached layout would be one edit behind. Building one is a walk over a handful of declarations.
+     *
+     * @returns {ParticleLayout}
+     * @throws if the declarations are not a valid layout (duplicate name, too many words)
+     */
+    buildLayout(): ParticleLayout;
+    /**
+     * Compile the effect as it stands.
+     *
+     * Never throws: everything that can go wrong comes back as a diagnostic, because every caller is
+     * a view that has to show the author what is wrong rather than fall over. Nor does it change the
+     * document — a compile that quietly rewrote the assembly buffer would be a change no view was
+     * told about.
+     *
+     * Memoized on {@link #compilation}, so the panels that all ask this on the same change pay for
+     * one. The result is shared rather than copied; nobody may write to it.
+     *
+     * @returns {ParticleEffectCompilation}
+     */
+    compile(): ParticleEffectCompilation;
+    /**
+     * What is wrong with the two graphs, whichever layer is authoritative.
+     *
+     * The graph editor is about the graph. Which representation happens to be running decides what
+     * the preview shows, not whether a dangling input in front of the author is worth saying — so
+     * this is separate from {@link compile}, which reports on the thing that runs.
+     *
+     * @param {ParticleLayout} [layout] the schema to check attribute references against; built from
+     *   the document when not supplied, and skipped when it cannot be built
+     * @returns {ParticleEffectCompilation['diagnostics']}
+     */
+    graphDiagnostics(layout?: ParticleLayout): ParticleEffectCompilation['diagnostics'];
+    /**
+     * Hand the code layer the graphs' output and make it authoritative.
+     *
+     * A one-way door, and deliberately an explicit one: from here the graphs are no longer what
+     * runs, so nothing silently recompiles over the author's instructions.
+     *
+     * The text is seeded from the *unoptimized* lowering even with {@link optimize} on. The reason
+     * to come here is to write something the node library cannot say, and that is done by editing
+     * what the graph produced — which means reading it. Folded constants, shared subexpressions and
+     * a packed register file are the opposite of readable, and this door does not open the other
+     * way, so seeding from them would spend the author's only copy of the legible program. Nothing
+     * is lost by it: with the box ticked what they type is optimized on its way to the preview all
+     * the same.
+     *
+     * @returns {ParticleEffectCompilation} the compilation the text was seeded from; when it failed,
+     *   the source is left alone and the diagnostics say why
+     */
+    lowerToAssembly(): ParticleEffectCompilation;
+    /**
+     * What the code layer should show: the author's buffer under ASSEMBLY, and what the graphs
+     * lower to under GRAPH.
+     *
+     * Derived rather than cached, so it cannot be a compile behind the graphs. A graph that does not
+     * compile has no text to show, and says so where the instructions would be.
+     *
+     * Under GRAPH this is the program that runs, so with {@link optimize} on it is the optimized
+     * one — showing the author the lowering while the preview ran something else would make the
+     * panel a lie about the effect. Under ASSEMBLY it stays the author's text whether the box is
+     * ticked or not: it is a live buffer they are typing into, and the one thing worse than not
+     * seeing the optimized program is having your own text replaced by it mid-edit. What the
+     * optimizer made of it shows up in the counts instead.
+     *
+     * @param {ParticleEffectCompilation} [compilation] a compile already in hand, to save repeating one
+     * @returns {string}
+     */
+    assemblyText(compilation?: ParticleEffectCompilation): string;
+    /**
+     * Go back to the graphs being what runs. The assembly text is kept — an author who switched by
+     * accident has not lost it — but it stops being read.
+     */
+    useGraphs(): void;
+    /**
+     * Turn the optimizer on or off. Announces, because it changes what runs.
+     *
+     * @param {boolean} enabled
+     */
+    setOptimize(enabled: boolean): void;
+    /**
+     * Add an attribute to the per-particle record.
+     *
+     * @param {string} name
+     * @param {number} components 1..4
+     * @param {string} [type] what the words are for, see {@link attributes}; omitted, they are
+     *   whatever `components` of them means and nothing more
+     * @throws if the name is taken or the record has no room left
+     */
+    addAttribute(name: string, components: number, type?: string): void;
+    /**
+     * Remove an attribute, and unbind any render channel that pointed at it.
+     *
+     * Nodes naming it are left alone: they become invalid, which the validator reports against the
+     * node, and that is a better outcome than silently rewriting an author's graph.
+     *
+     * @param {string} name
+     * @returns {boolean} false when there was no such attribute
+     */
+    removeAttribute(name: string): boolean;
+    /**
+     * The emitter settings as {@link ParticleEmitter.from} takes them, with the compiled effect.
+     *
+     * Render channels naming an attribute the layout no longer has are dropped rather than passed
+     * on, because `bind_render` throws on one — and an effect that fails to build over a stale
+     * binding is a worse thing to hand an author than one that draws without a colour.
+     *
+     * @param {{layout: ParticleLayout, program: object}} effect what {@link compile} produced,
+     *   packaged the way `create_particle_effect` does
+     * @returns {object}
+     */
+    emitterConfig(effect: {
+        layout: ParticleLayout;
+        program: object;
+    }): object;
+    /**
+     * The emitter's packed flags word, for anything that wants it without building an emitter.
+     * @returns {number}
+     */
+    emitterFlags(): number;
+    /**
+     * @returns {object} the whole document, as JSON
+     */
+    toJSON(): object;
+    /**
+     * Replace this document's contents with what the JSON describes.
+     *
+     * @param {object} json
+     * @param {NodeDescriptionVisualRegistry} visualRegistry needed to place nodes whose saved
+     *        position is missing, and to size the ones that have one
+     * @returns {ParticleEffectDocument} this
+     */
+    fromJSON(json: object, visualRegistry: NodeDescriptionVisualRegistry): ParticleEffectDocument;
+    #private;
+}
+/**
+ * A compile attempt's outcome.
+ */
+export type ParticleEffectCompilation = {
+    /**
+     *   null when anything went wrong
+     */
+    program: import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram | null;
+    /**
+     * the attribute schema the program was compiled against;
+     * null when the declarations themselves are not a valid layout
+     */
+    layout: ParticleLayout | null;
+    /**
+     *   what `program` was built from, before the optimizer. The same object as `program` when
+     *   {@link ParticleEffectDocumentoptimize } is off, so a caller wanting the comparison can always
+     *   ask for it and gets "no difference" rather than a special case.
+     */
+    unoptimized: import("../../../src/shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram | null;
+    /**
+     *   `scope` is `"init"`, `"update"`, `"assembly"` or `"effect"`; `node` is a node id or -1;
+     *   `line` is a 1-based assembly line or 0
+     */
+    diagnostics: Array<{
+        scope: string;
+        node: number;
+        line: number;
+        message: string;
+        severity: string;
+    }>;
+};
+import { NodeGraph } from "../../../src/core/model/node-graph/NodeGraph.js";
+import { NodeGraphVisualData } from "../../../src/core/model/node-graph/visual/NodeGraphVisualData.js";
+import { ParticleLayout } from "../../../src/shade/renderer/particles/layout/ParticleLayout.js";
+//# sourceMappingURL=ParticleEffectDocument.d.ts.map

package/editor/particles/effect/ParticleEffectDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffectDocument.d.ts","sourceRoot":"","sources":["../../../../editor/particles/effect/ParticleEffectDocument.js"],"names":[],"mappings":"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"}