@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/graph/flatten_particle_graph.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [options]
+ * @param {number} [options.max_passes] see {@link MAX_INLINE_PASSES}
+ * @returns {NodeGraph} a graph with no group nodes in it — `graph` itself when it had none, and a
+ *   separate graph otherwise. The input is never modified.
+ */
+export function flatten_particle_graph(graph: NodeGraph, { max_passes }?: {
+    max_passes?: number;
+}): NodeGraph;
+//# sourceMappingURL=flatten_particle_graph.d.ts.map

package/src/shade/renderer/particles/graph/flatten_particle_graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten_particle_graph.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/flatten_particle_graph.js"],"names":[],"mappings":"AA6CA;;;;;;GAMG;AACH;IAJ4B,UAAU,GAA3B,MAAM;cAgChB"}

package/src/shade/renderer/particles/graph/flatten_particle_graph.js

@@ -0,0 +1,213 @@
+import { is_particle_group_node } from "./ParticleNodeGroup.js";
+
+/**
+ * Replace every node group in a graph with the nodes it is made of, until none is left.
+ *
+ * The step that lets {@link ./ParticleNodeGroup.js groups} exist at all. Everything downstream of
+ * here — type resolution, register allocation, lowering — works on one flat expression over the
+ * stock library, exactly as it did before there were groups, and a group therefore costs precisely
+ * what its contents cost. There is no call, no frame, and nothing to pay for the abstraction with.
+ *
+ * ## What happens to the wires
+ *
+ * A group node's ports are wires to nothing — the work is inside. So each is re-made against what
+ * was on the other side of the boundary:
+ *
+ * - a wire *into* the group's input `p` is re-made to every node inside that read the input block's
+ *   `p`,
+ * - a wire *out of* the group's output `q` is re-made from whatever inside wrote the output block's
+ *   `q`,
+ * - and where the two meet — the input block wired straight to the output block, a group that passes
+ *   a value through — the outer source is joined directly to the outer targets, and nothing of the
+ *   group survives at all.
+ *
+ * A group input with nothing wired to it leaves its inner consumers unbound, which is the same
+ * problem stated one level down and is what the compiler already refuses. A group output nobody
+ * reads leaves its producer unreachable, which is what the compiler already drops.
+ *
+ * ## One level at a time
+ *
+ * Nesting is handled by repeating rather than by recursing: inlining a group can only introduce
+ * group nodes that were in its body, and the next pass takes those. It terminates because a group's
+ * body can only reference groups that already existed when it was built, so the reference graph is
+ * acyclic — see {@link ParticleNodeGroup}. The pass cap is a backstop against a library assembled
+ * some other way, not the reason this finishes.
+ */
+
+/**
+ * How many rounds of inlining to allow. Each round opens one level of nesting, so this is a limit on
+ * how deeply groups may be stacked — far past anything an author would build, and low enough that a
+ * library that somehow does contain a cycle fails with a sentence instead of a hung tab.
+ *
+ * @type {number}
+ */
+const MAX_INLINE_PASSES = 32;
+
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [options]
+ * @param {number} [options.max_passes] see {@link MAX_INLINE_PASSES}
+ * @returns {NodeGraph} a graph with no group nodes in it — `graph` itself when it had none, and a
+ *   separate graph otherwise. The input is never modified.
+ */
+export function flatten_particle_graph(graph, { max_passes = MAX_INLINE_PASSES } = {}) {
+    if (!graph.getNodes().some(is_particle_group_node)) {
+        // Nothing to open. Returned as-is rather than copied, so that a graph without groups is
+        // compiled under the ids the author sees — which is what every diagnostic naming a node
+        // depends on.
+        return graph;
+    }
+
+    const flat = graph.clone();
+
+    for (let pass = 0; ; pass++) {
+        const groups = flat.getNodes().filter(is_particle_group_node);
+
+        if (groups.length === 0) {
+            return flat;
+        }
+
+        if (pass >= max_passes) {
+            throw new Error(
+                `Node groups are nested more than ${max_passes} deep, or a group contains itself. `
+                + `'${groups[0].description.name}' is still unopened after ${max_passes} passes.`
+            );
+        }
+
+        for (const node of groups) {
+            inline_group(flat, node);
+        }
+    }
+}
+
+/**
+ * Splice one group instance's body into the graph around it, and remove the instance.
+ *
+ * @param {NodeGraph} graph the graph being flattened, modified in place
+ * @param {NodeInstance} node the group instance
+ */
+function inline_group(graph, node) {
+    const group = node.description.group;
+    const body = group.graph;
+
+    // What the group is wired to, read before anything is taken apart.
+
+    /** @type {Map<string, {node: number, port: number}>} group input port name -> the outer source */
+    const sources = new Map();
+
+    for (const connection of node.inConnections) {
+        const name = connection.target.port.name;
+
+        if (sources.has(name)) {
+            // More than one source on an input is a graph the validator already refuses; taking the
+            // first keeps flattening total rather than adding a second opinion about it.
+            continue;
+        }
+
+        sources.set(name, { node: connection.source.instance.id, port: connection.source.port.id });
+    }
+
+    /** @type {Map<string, Array<{node: number, port: number}>>} group output port name -> outer targets */
+    const targets = new Map();
+
+    for (const connection of node.outConnections) {
+        const name = connection.source.port.name;
+
+        const listed = targets.get(name) ?? [];
+
+        listed.push({ node: connection.target.instance.id, port: connection.target.port.id });
+
+        targets.set(name, listed);
+    }
+
+    // A copy of every node in the body, boundary blocks excepted: those are the group's edge, and
+    // the edge is what is being dissolved.
+
+    /** @type {Map<number, NodeInstance>} body node id -> its copy in `graph` */
+    const copies = new Map();
+
+    for (const inner of body.getNodes()) {
+        if (inner === group.inputNode || inner === group.outputNode) {
+            continue;
+        }
+
+        const copy = graph.getNodeSafe(graph.createNode(inner.description));
+
+        copy.setParameters(clone_parameters(inner.parameters));
+
+        copies.set(inner.id, copy);
+    }
+
+    for (const connection of body.getConnections()) {
+        const from = connection.source;
+        const to = connection.target;
+
+        const from_boundary = from.instance === group.inputNode;
+        const to_boundary = to.instance === group.outputNode;
+
+        if (from_boundary && to_boundary) {
+            // straight through: the group contributes nothing but a rename
+            const source = sources.get(from.port.name);
+
+            for (const target of targets.get(to.port.name) ?? []) {
+                if (source !== undefined) {
+                    graph.createConnection(source.node, source.port, target.node, target.port);
+                }
+            }
+
+            continue;
+        }
+
+        if (from_boundary) {
+            const source = sources.get(from.port.name);
+
+            if (source !== undefined) {
+                const target = copies.get(to.instance.id);
+
+                graph.createConnection(source.node, source.port, target.id, to.port.id);
+            }
+
+            continue;
+        }
+
+        if (to_boundary) {
+            const source = copies.get(from.instance.id);
+
+            for (const target of targets.get(to.port.name) ?? []) {
+                graph.createConnection(source.id, from.port.id, target.node, target.port);
+            }
+
+            continue;
+        }
+
+        graph.createConnection(
+            copies.get(from.instance.id).id, from.port.id,
+            copies.get(to.instance.id).id, to.port.id
+        );
+    }
+
+    // takes the group's own wires with it; every one of them has been re-made above
+    graph.deleteNode(node.id);
+}
+
+/**
+ * A node's parameters, deep enough that the copy and the original cannot write through to each
+ * other. Values are numbers, strings, and arrays of numbers.
+ *
+ * A body's node is the template for every instance of its group, so sharing an array between them
+ * would make an edit to one instance an edit to all of them — including the definition itself.
+ *
+ * @param {object} parameters
+ * @returns {object}
+ */
+function clone_parameters(parameters) {
+    const result = {};
+
+    for (const key of Object.keys(parameters)) {
+        const value = parameters[key];
+
+        result[key] = Array.isArray(value) ? value.slice() : value;
+    }
+
+    return result;
+}

package/src/shade/renderer/particles/graph/groups/particle_builtin_groups.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The node groups the editor ships with, registered.
+ *
+ * Every one of them is locked: the body is shared by every instance in every effect, and these
+ * particular bodies are the ones the library's own specs pin. An author who wants a different
+ * simplex noise builds one; they do not get to change this one out from under everybody else's
+ * effects.
+ *
+ * Registration order is the order they are offered in, and — because a group's body may only wire up
+ * groups that already exist — it is also a build order: `sampleSphereVolume` is made of
+ * `sampleSphereSurface`, and `curl3` of twelve `simplex3`s.
+ *
+ * Importing this module is what puts them in the library. Anything that resolves a node type by name
+ * should reach for {@link ../particle_node_library.js} instead of importing this directly, so it
+ * cannot end up with a library that has the groups missing.
+ */
+/**
+ * The groups this module registers, in the order it registers them.
+ *
+ * Exported so the library's own specs can make claims about *these* rather than about whatever
+ * happens to be registered: a host — or a test — may add a group of its own, and "every shipped
+ * group is locked" would then be a claim about somebody else's group.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
+ */
+export const PARTICLE_BUILTIN_GROUPS: import("../ParticleNodeGroup.js").ParticleNodeGroup[];
+//# sourceMappingURL=particle_builtin_groups.d.ts.map

package/src/shade/renderer/particles/graph/groups/particle_builtin_groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_builtin_groups.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_builtin_groups.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,sCAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAuB7D"}

package/src/shade/renderer/particles/graph/groups/particle_builtin_groups.js

@@ -0,0 +1,75 @@
+import { register_particle_group } from "../particle_group_library.js";
+import {
+    PARTICLE_GROUP_ANGLE_BETWEEN,
+    PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE,
+    PARTICLE_GROUP_QUAT_LOOK_ROTATION,
+    PARTICLE_GROUP_QUAT_ROTATE,
+    PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE,
+    PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME,
+} from "./particle_groups_geometry.js";
+import {
+    PARTICLE_GROUP_CURL_3,
+    PARTICLE_GROUP_CURL_4,
+    PARTICLE_GROUP_SIMPLEX_3,
+    PARTICLE_GROUP_SIMPLEX_4,
+} from "./particle_groups_noise.js";
+import {
+    PARTICLE_GROUP_CEIL,
+    PARTICLE_GROUP_DECOMPOSE,
+    PARTICLE_GROUP_ONE_MINUS,
+    PARTICLE_GROUP_REMAP,
+    PARTICLE_GROUP_ROUND,
+} from "./particle_groups_utility.js";
+
+/**
+ * The node groups the editor ships with, registered.
+ *
+ * Every one of them is locked: the body is shared by every instance in every effect, and these
+ * particular bodies are the ones the library's own specs pin. An author who wants a different
+ * simplex noise builds one; they do not get to change this one out from under everybody else's
+ * effects.
+ *
+ * Registration order is the order they are offered in, and — because a group's body may only wire up
+ * groups that already exist — it is also a build order: `sampleSphereVolume` is made of
+ * `sampleSphereSurface`, and `curl3` of twelve `simplex3`s.
+ *
+ * Importing this module is what puts them in the library. Anything that resolves a node type by name
+ * should reach for {@link ../particle_node_library.js} instead of importing this directly, so it
+ * cannot end up with a library that has the groups missing.
+ */
+
+/**
+ * The groups this module registers, in the order it registers them.
+ *
+ * Exported so the library's own specs can make claims about *these* rather than about whatever
+ * happens to be registered: a host — or a test — may add a group of its own, and "every shipped
+ * group is locked" would then be a claim about somebody else's group.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
+ */
+export const PARTICLE_BUILTIN_GROUPS = [
+    // the small ones
+    PARTICLE_GROUP_ROUND,
+    PARTICLE_GROUP_CEIL,
+    PARTICLE_GROUP_ONE_MINUS,
+    PARTICLE_GROUP_REMAP,
+    ...PARTICLE_GROUP_DECOMPOSE,
+
+    // directions and rotations
+    PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE,
+    PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME,
+    ...PARTICLE_GROUP_ANGLE_BETWEEN,
+    PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE,
+    PARTICLE_GROUP_QUAT_LOOK_ROTATION,
+    PARTICLE_GROUP_QUAT_ROTATE,
+
+    // the expensive ones
+    PARTICLE_GROUP_SIMPLEX_3,
+    PARTICLE_GROUP_SIMPLEX_4,
+    PARTICLE_GROUP_CURL_3,
+    PARTICLE_GROUP_CURL_4,
+];
+
+for (const group of PARTICLE_BUILTIN_GROUPS) {
+    register_particle_group(group);
+}

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A point on the unit sphere, from two numbers in `[0, 1)`.
+ *
+ * Uniform over the surface, which is what the `z` lane being taken straight from `u` buys: the area
+ * of a band of the sphere between two heights depends only on the heights, so spreading `z` evenly
+ * spreads the points evenly. Taking a latitude evenly instead — the obvious thing, and the wrong one
+ * — piles them up at the poles.
+ *
+ * Feed it a two-lane `random` and it is an unbiased direction.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_SPHERE_SURFACE: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * A point inside the unit ball, from three numbers in `[0, 1)`.
+ *
+ * A direction from the first two and a radius from the third — and the radius is the cube root of it,
+ * because the volume inside a radius grows as its cube. Using the number itself would put half the
+ * points inside the half-radius sphere, which holds an eighth of the volume, and every effect built
+ * on it would have a bright core it never asked for.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_SPHERE_VOLUME: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * The angle between two directions, in radians, in `[0, pi]`.
+ *
+ * `acos` of the cosine, and the cosine is the dot product of the two normalised. The clamp is not
+ * decoration: a dot product of two unit vectors is arithmetically in `[-1, 1]` and in floating point
+ * is occasionally a hair outside it, which is exactly where `acos` stops being defined.
+ *
+ * Two of them, one per shape, because there is no honest way to do this at "whatever width arrives"
+ * — the answer for two lanes and the answer for three are different questions about different
+ * things, and a node that took either would be a node whose result depended on what was plugged in.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
+ */
+export const PARTICLE_GROUP_ANGLE_BETWEEN: import("../ParticleNodeGroup.js").ParticleNodeGroup[];
+/**
+ * A quaternion for a rotation of `angle` radians about `axis`.
+ *
+ * `(axis * sin(angle/2), cos(angle/2))`, with the axis normalised first so the result is a unit
+ * quaternion whatever length the axis arrived at. A zero axis normalises to zero, which gives the
+ * quaternion `(0, 0, 0, cos(angle/2))` — not a rotation, and not a crash either.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * Turn a vector by a quaternion.
+ *
+ * `v + 2w(q x v) + 2(q x (q x v))`, written the way it is usually written: one cross product, one
+ * scale, one more cross product. Two cross products beat building a rotation matrix, and there is
+ * no matrix type here to build one into anyway.
+ *
+ * The quaternion is expected to be a unit one. A longer one scales the result by the square of its
+ * length, which is the identity behaving as it always has rather than anything this checks.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_ROTATE: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+/**
+ * The rotation that points `forward` along +Z with `up` as near to +Y as it can be.
+ *
+ * The basis is built first — forward, then a right that is perpendicular to both, then the up that
+ * completes it — and then read off as a quaternion by Shepperd's method: four expressions, one per
+ * component of the quaternion being the largest, and the largest is picked because the other three
+ * divide by something near zero.
+ *
+ * There are no branches, so all four are computed and one is chosen. That is what a VM with no
+ * control flow costs, and the choice is a pair of comparisons rather than a jump. Each divisor is
+ * floored at {@link DIVISOR_FLOOR} first, so the three expressions that are *not* chosen produce a
+ * finite number rather than an infinity — the selection reads registers rather than blending them,
+ * but a program that computes infinities is one bad edit away from writing one out.
+ *
+ * Degenerate input — `forward` and `up` parallel, or either of them zero — leaves the basis without a
+ * right vector, and what comes back is finite and arbitrary. Feeding this an `up` that could line up
+ * with `forward` is the caller's to avoid, exactly as it is in every engine that offers this.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_LOOK_ROTATION: import("../ParticleNodeGroup.js").ParticleNodeGroup;
+//# sourceMappingURL=particle_groups_geometry.d.ts.map

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"particle_groups_geometry.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/particle_groups_geometry.js"],"names":[],"mappings":"AA8DA;;;;;;;;;;;GAWG;AACH,mDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;GASG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAmBxD;AAEL;;;;;;;;;;;;GAYG;AACH,2CAFU,OAAO,yBAAyB,EAAE,iBAAiB,EAAE,CAiB5D;AAEH;;;;;;;;GAQG;AACH,kDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAsBxD;AAEL;;;;;;;;;;;GAWG;AACH,yCAFU,OAAO,yBAAyB,EAAE,iBAAiB,CAuBxD;AAEL;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gDAFU,OAAO,yBAAyB,EAAE,iBAAiB,CA+ExD"}