@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/data/particle_emitter_record.js

@@ -0,0 +1,109 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * The translation between an emitter and the row the GPU reads for it: one function that fills a
+ * {@link ./PARTICLE_EMITTER_STRUCT.js} record from a {@link ../runtime/ParticleEmitter.js} and the
+ * {@link ../runtime/GPUParticleEmitterContext.js} the registry holds for it.
+ *
+ * It sits here, with the struct, rather than on the emitter. Half of what a row says is the
+ * context's — the program placement, the tenancy, the `transforms` row, the atlas patch — and the other
+ * half only means anything in the terms this struct sets: `render_position` is a word offset
+ * because that is what the render pass indexes a particle record with. An emitter that knew how to
+ * write one would be an emitter that knew what a table row is.
+ */
+
+/**
+ * Fill `record` with an emitter as the value the emitter table stores — every field of
+ * {@link ./PARTICLE_EMITTER_STRUCT.js}, none omitted.
+ *
+ * Omitting one would not write zeros: the serializer skips absent fields, and table pages are
+ * recycled buffers, so a skipped field keeps whatever the previous tenant of the slot left there.
+ *
+ * Writes into a caller-supplied object rather than returning a fresh one so the registry can stage
+ * every row of a frame through one module-static record — the table serializes it synchronously, so
+ * nothing outlives the call.
+ *
+ * @param {object} record the staging object, see {@link create_emitter_record}
+ * @param {import("../runtime/ParticleEmitter.js").ParticleEmitter} emitter
+ * @param {import("../runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext} context the
+ *        registry's bookkeeping for `emitter`
+ * @returns {object} `record`
+ */
+export function write_emitter_record(record, emitter, context) {
+    assert.defined(record, 'record');
+    assert.defined(emitter, 'emitter');
+    assert.defined(context, 'context');
+    assert.notEqual(context.placement, null, 'context.placement — this emitter has no program in the heap');
+
+    const placement = context.placement;
+
+    record.init_offset = placement.init_offset;
+    record.init_count = placement.init_count;
+    record.update_offset = placement.update_offset;
+    record.update_count = placement.update_count;
+    record.constant_offset = placement.constant_offset;
+    record.program_id = placement.program_id;
+
+    // Two emitters running one program produce identical particles from identical seeds, and 0 is
+    // what an emitter that was never given one has. The generation stands in: it is distinct for
+    // every emitter the registry has ever registered, so "unset" comes out as "unlike anything
+    // else" rather than "the same as its twin". Derived here rather than written back onto the
+    // emitter, which is authoring data and has no seed of its own to gain from being registered.
+    record.seed = emitter.seed !== 0 ? emitter.seed : context.generation;
+
+    record.flags = emitter.flags;
+    record.spawn_rate = emitter.spawn_rate;
+    record.node = context.transform_row;
+    record.generation = context.generation;
+
+    record.bounds_center.set(emitter.bounds_center);
+    record.bounds_radius = emitter.bounds_radius;
+
+    record.render_position = emitter.render_position;
+    record.render_size = emitter.render_size;
+    record.render_color = emitter.render_color;
+    record.render_rotation = emitter.render_rotation;
+    record.render_frame = emitter.render_frame;
+    record.render_velocity = emitter.render_velocity;
+
+    record.atlas_region.set(context.atlas_region);
+    record.flipbook.set(emitter.flipbook);
+
+    return record;
+}
+
+/**
+ * An empty staging record with every field of {@link ./PARTICLE_EMITTER_STRUCT.js} present, typed
+ * arrays for the vector fields so {@link write_emitter_record} can copy into them.
+ *
+ * @returns {object}
+ */
+export function create_emitter_record() {
+    return {
+        init_offset: 0,
+        init_count: 0,
+        update_offset: 0,
+        update_count: 0,
+        constant_offset: 0,
+        program_id: 0,
+
+        seed: 0,
+        flags: 0,
+        spawn_rate: 0,
+        node: 0,
+        generation: 0,
+
+        bounds_center: new Float32Array(3),
+        bounds_radius: 0,
+
+        render_position: 0,
+        render_size: 0,
+        render_color: 0,
+        render_rotation: 0,
+        render_frame: 0,
+        render_velocity: 0,
+
+        atlas_region: new Float32Array(4),
+        flipbook: new Float32Array(2),
+    };
+}

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

@@ -17,9 +17,9 @@
  * Each mention of a number is its own node, deliberately. Sharing one would be fewer instructions and
  * a great deal worse: a value's registers are held from where it is produced to its last reader, so a
  * `2.0` shared between the first line of a body and the last would pin its slots across the whole
- * group. The register file is the scarce thing here — see
- * {@link ../ParticleConstants.js PARTICLE_VM_REGISTER_SLOTS} — and the constant pool interns the
- * words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
+ * group. The fast interpreter's register file is the scarce thing here — see
+ * {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} — and the constant pool interns
+ * the words anyway, so what the duplication costs is one `LOAD_CONST` and nothing else.
  *
  * ## What comes back
  *