@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -17,8 +17,8 @@ import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
  * 0. Replace every node group with the nodes it is made of, until none is left — see
  *    {@link ./flatten_particle_graph.js}. Everything after this point works on one flat expression
  *    over the stock library, and so is written as though groups did not exist.
- * 1. Walk the graph from its sinks (attribute writes / kill), flattening it into an SSA-style value
- *    list in dependency order. Shared sub-expressions are evaluated once (DAG sharing via
+ * 1. Walk the graph from its sinks (particle field writes / kill), flattening it into an SSA-style
+ *    value list in dependency order. Shared sub-expressions are evaluated once (DAG sharing via
  *    memoisation).
  * 2. Resolve every value's type — see {@link ./infer_particle_graph_types.js} — which is how many
  *    lanes it has. A value whose type cannot be told is a graph that cannot be compiled.
@@ -31,10 +31,12 @@ import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
  *
  * @param {NodeGraph} graph
  * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream target section
- * @param {ParticleAssembler} asm assembler owning the shared constant pool
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout attribute schema
+ * @param {ParticleAssembler} asm assembler owning the shared constant pool and the global imports
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout particle field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  */
-export function compile_particle_graph(graph, stream, asm, layout) {
+export function compile_particle_graph(graph, stream, asm, layout, emitter_layout, global_layout) {
     // A graph with no groups in it comes back unchanged, so the node ids in anything raised below
     // are the ids the author sees.
     const source = flatten_particle_graph(graph);
@@ -44,13 +46,13 @@ export function compile_particle_graph(graph, stream, asm, layout) {
         // inside a group, under a number that exists nowhere an author can look — so the message
         // says as much rather than sending them to hunt for it.
         try {
-            return lower(source, stream, asm, layout);
+            return lower(source, stream, asm, layout, emitter_layout, global_layout);
         } catch (e) {
             throw new Error(`${e.message} (inside a node group, where node ids are not the graph's)`);
         }
     }
 
-    return lower(source, stream, asm, layout);
+    return lower(source, stream, asm, layout, emitter_layout, global_layout);
 }
 
 /**
@@ -60,14 +62,16 @@ export function compile_particle_graph(graph, stream, asm, layout) {
  * @param {import("../isa/ParticleAssembler.js").InstructionStream} stream
  * @param {ParticleAssembler} asm
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  */
-function lower(graph, stream, asm, layout) {
+function lower(graph, stream, asm, layout, emitter_layout, global_layout) {
     const values = flatten(graph);
 
-    resolve_types(values, graph, layout);
+    resolve_types(values, graph, layout, emitter_layout, global_layout);
 
     const last_use = compute_last_use(values);
-    const widths = compute_widths(values, layout);
+    const widths = compute_widths(values, layout, emitter_layout, global_layout);
 
     const register_of = new Array(values.length).fill(-1);
     const span_of = new Array(values.length).fill(0);
@@ -109,7 +113,7 @@ function lower(graph, stream, asm, layout) {
             // source to write slot `c` of its destination, so an aliased operand is fine and a
             // shifted one would read slots it has already overwritten. Runs make that possible in a
             // way interchangeable registers never did.
-            const sources = source_ranges(value, description, input_registers, widths[i], layout);
+            const sources = source_ranges(value, description, input_registers, widths[i], layout, emitter_layout, global_layout);
 
             out = allocate(occupied, span, (base) => sources.every(
                 (range) => base === range.base || base + span <= range.base || range.base + range.span <= base
@@ -141,6 +145,8 @@ function lower(graph, stream, asm, layout) {
             source_types: value.source_types,
             parameters: value.parameters,
             layout,
+            emitter_layout,
+            global_layout,
             asm,
         });
 
@@ -208,10 +214,12 @@ function allocate(occupied, span, is_acceptable = () => true) {
  * @param {Object<string, number>} input_registers port -> the slot its value sits at
  * @param {{operation: number}} width
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  * @returns {Array<{base: number, span: number}>}
  */
-function source_ranges(value, description, input_registers, width, layout) {
-    const overrides = description.input_widths(width_context(value, layout, { operation_width: width.operation }));
+function source_ranges(value, description, input_registers, width, layout, emitter_layout, global_layout) {
+    const overrides = description.input_widths(width_context(value, layout, emitter_layout, global_layout, { operation_width: width.operation }));
 
     const ranges = [];
 
@@ -242,16 +250,20 @@ function release(occupied, base, span) {
  *
  * @param {{parameters: object, type: ParticleValueType|null, input_types: object, source_types: object}} value
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  * @param {object} extra `demand` or `operation_width`, whichever the rule takes
  * @returns {object}
  */
-function width_context(value, layout, extra) {
+function width_context(value, layout, emitter_layout, global_layout, extra) {
     return {
         type: value.type,
         input_types: value.input_types,
         source_types: value.source_types,
         parameters: value.parameters,
         layout,
+        emitter_layout,
+        global_layout,
         ...extra,
     };
 }
@@ -260,17 +272,19 @@ function width_context(value, layout, extra) {
  * Decide how many lanes each value occupies, and how wide the instruction producing it runs.
  *
  * Backward pass: a value is as wide as the widest thing that asks for it, and a sink asks for
- * exactly the attribute it writes. An instruction runs at the lanes wanted of it and never more
- * than its type has — so a `vec4` literal feeding a three-component attribute is loaded three
- * wide, and a `vec3` nobody reads past `.x` of is computed one wide. Where a consumer wants more
- * lanes than the type has, the value is widened after it is produced (see the compile loop), and
- * `demand` is what says by how much.
+ * exactly the particle field it writes. An instruction runs at the lanes wanted of it and never
+ * more than its type has — so a `vec4` literal feeding a three-component particle field is loaded
+ * three wide, and a `vec3` nobody reads past `.x` of is computed one wide. Where a consumer wants
+ * more lanes than the type has, the value is widened after it is produced (see the compile loop),
+ * and `demand` is what says by how much.
  *
  * @param {Array<{description: ParticleNodeDescription, parameters: object, inputs: object, type: ParticleValueType|null, input_types: object, source_types: object}>} values
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  * @returns {Array<{operation: number, result: number, demand: number}>} indexed by value
  */
-function compute_widths(values, layout) {
+function compute_widths(values, layout, emitter_layout, global_layout) {
     const demand = new Array(values.length).fill(1);
 
     // Values are in dependency order, so walking backwards visits every consumer of a value before
@@ -281,12 +295,12 @@ function compute_widths(values, layout) {
         const value = values[i];
         const description = value.description;
 
-        const operation = clamp_width(description.operation_width(width_context(value, layout, { demand: demand[i] })));
+        const operation = clamp_width(description.operation_width(width_context(value, layout, emitter_layout, global_layout, { demand: demand[i] })));
         const produced = clamp_width(description.result_width({ operation_width: operation, type: value.type }));
 
         result[i] = { operation, result: produced, demand: demand[i] };
 
-        const overrides = description.input_widths(width_context(value, layout, { operation_width: operation }));
+        const overrides = description.input_widths(width_context(value, layout, emitter_layout, global_layout, { operation_width: operation }));
 
         for (const port of Object.keys(value.inputs)) {
             const wanted = clamp_width(overrides[port] ?? operation);
@@ -316,15 +330,18 @@ function clamp_width(width) {
  * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.emitter_layout] emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [params.global_layout] the global fields the effect imports.
+ *   The program's `global_imports` are the ones its graphs read, in the order they are first read.
  * @returns {import("../isa/ParticleProgram.js").ParticleProgram}
  */
-export function compile_particle_effect({ init, update, layout }) {
+export function compile_particle_effect({ init, update, layout, emitter_layout = undefined, global_layout = undefined }) {
     const asm = new ParticleAssembler();
     if (init !== undefined) {
-        compile_particle_graph(init, asm.init, asm, layout);
+        compile_particle_graph(init, asm.init, asm, layout, emitter_layout, global_layout);
     }
     if (update !== undefined) {
-        compile_particle_graph(update, asm.update, asm, layout);
+        compile_particle_graph(update, asm.update, asm, layout, emitter_layout, global_layout);
     }
     const program = asm.build();
     validate_particle_program(program);
@@ -389,9 +406,11 @@ function flatten(graph) {
  * @param {Array<{node: number, description: ParticleNodeDescription, inputs: object}>} values
  * @param {NodeGraph} graph
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} layout
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} emitter_layout emitter field schema
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|undefined} global_layout the global fields the effect imports
  */
-function resolve_types(values, graph, layout) {
-    const types = infer_particle_graph_types(graph, { layout });
+function resolve_types(values, graph, layout, emitter_layout, global_layout) {
+    const types = infer_particle_graph_types(graph, { layout, emitter_layout, global_layout });
 
     for (const value of values) {
         value.type = types.output(value.node);

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

@@ -2,11 +2,17 @@
  * @param {NodeGraph} graph
  * @param {object} [context]
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
- *   attribute schema; without it, attribute reads and writes are of unknown type
+ *   particle field schema; without it, particle field reads and writes are of unknown type
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.emitter_layout] the
+ *   effect's emitter field schema; without it, emitter field reads are of unknown type
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout|null} [context.global_layout] the
+ *   global fields the effect imports; without it, global field reads are of unknown type
  * @returns {ParticleGraphTypes}
  */
-export function infer_particle_graph_types(graph: NodeGraph, { layout }?: {
+export function infer_particle_graph_types(graph: NodeGraph, { layout, emitter_layout, global_layout }?: {
     layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+    emitter_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
+    global_layout?: import("../layout/ParticleLayout.js").ParticleLayout | null;
 }): ParticleGraphTypes;
 /**
  * Resolve the type of every value in a particle graph.

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

@@ -1 +1 @@
-{"version":3,"file":"infer_particle_graph_types.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js"],"names":[],"mappings":"AAgIA;;;;;;GAMG;AACH;IAJ0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,kBAAkB,CAoG9B;AAtOD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH;IA0BI;;;OAGG;IACH,aAFU,OAAO,gCAAgC,EAAE,uBAAuB,EAAE,CAE3D;IAEjB;;;;;;OAMG;IACH,aANW,MAAM,UACN,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;YAChD,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;;YAC/D,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;aAUhF;IAED;;;OAGG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,SACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAYnE;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAInE;IAED;;;;;OAKG;IACH,gBAHW,MAAM;YACG,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;MAIlF;;CACJ"}
+{"version":3,"file":"infer_particle_graph_types.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js"],"names":[],"mappings":"AAgIA;;;;;;;;;;GAUG;AACH;IAR0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAEgB,cAAc,GAAlF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEW,aAAa,GAAjF,OAAO,6BAA6B,EAAE,cAAc,GAAC,IAAI;IAEvD,kBAAkB,CAsG9B;AA5OD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH;IA0BI;;;OAGG;IACH,aAFU,OAAO,gCAAgC,EAAE,uBAAuB,EAAE,CAE3D;IAEjB;;;;;;OAMG;IACH,aANW,MAAM,UACN,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;YAChD,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;;YAC/D,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;aAUhF;IAED;;;OAGG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,SACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAYnE;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAInE;IAED;;;;;OAKG;IACH,gBAHW,MAAM;YACG,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;MAIlF;;CACJ"}