@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/runtime/ParticleEmitter.js

@@ -1,4 +1,10 @@
 import { assert } from "../../../../core/assert.js";
+import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
+import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 import { Node3D } from "../../scene/Node3D.js";
 import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
@@ -44,76 +50,63 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
  * particles, within a frame, because the emitter's table row is retired with it and its particles
  * carry that row's generation. There is no transform of its own to keep in step with anything.
  *
- * The rest is the CPU model of one row of the emitter table
- * ({@link ../data/PARTICLE_EMITTER_STRUCT.js}): the compiled effect and its placement in the
- * program arena, spawn rate, blend / projection / feature flags, bounds sphere, render-attribute
- * bindings, atlas region and flipbook grid. {@link write_record} is the whole of the translation
- * between the two. Fields are plain data with no setters — after changing any of them, set
- * {@link dirty} so {@link ./EmitterRegistry.js} restages the row on its next flush. A flag rather
- * than a setter per field because a row is restaged whole either way: one changed field and ten
- * cost the same upload.
+ * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
+ * compiled {@link program}, the {@link texture} to draw with, spawn rate, blend / projection /
+ * feature flags, bounds sphere, render-attribute bindings and flipbook grid. Every one of those is
+ * the author's, means the same thing with no device present, and is what a saved effect is made of.
  *
- * What is NOT here is anything the GPU integrates per frame — spawn accumulator, age, sleep. That
- * is {@link ../data/PARTICLE_EMITTER_STATE.js}, and it stays on the GPU.
+ * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
+ * its program was placed in the program heap, which `transforms` row its node ended up in, where
+ * its texture was packed into the atlas — all of that is
+ * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
+ * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
+ * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
+ * "is this emitter live?" is asked. Nor is anything the GPU integrates per frame here — spawn
+ * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
  *
- * Instances become live through a {@link ./EmitterRegistry.js}, which assigns {@link row} and
- * {@link generation} and resolves the program placement. Constructing one directly gives you an
- * emitter no table knows about.
+ * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
+ * node's own change counter, the same one the renderer reads to decide whether a transform needs
+ * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
+ * counter rather than a setter per field because a row is restaged whole either way: one changed
+ * field and ten cost the same upload.
  */
 export class ParticleEmitter extends Node3D {
 
     /**
-     * Row this emitter occupies in the emitter table. Stable for the emitter's whole life — it is
-     * what every live particle's record header stores, so it cannot be renumbered while particles
-     * are in flight. `-1` until the registry assigns one.
+     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
+     * wide each is, and what word of the record it sits at.
      *
-     * Not to be confused with {@link Node3D#id}, which is the node's own identity and the key the
-     * scene context maps to a `transforms` row.
-     *
-     * @type {number}
-     */
-    row = -1;
-
-    /**
-     * Which tenancy of {@link row} this emitter is. Assigned by the registry, distinct from every
-     * other emitter it has ever assigned, never zero. Stamped into every particle the emitter
-     * spawns, and what lets the simulate pass tell those particles from a later tenant's.
-     *
-     * @type {number}
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout}
      */
-    generation = 0;
+    layout;
 
     /**
-     * Row of the scene database's `transforms` table this node occupies, as the scene context
-     * reported it — what the record's `node` field carries. `0` (the scene root) until bound, so
-     * an emitter that is registered before its node is placed still reads a valid row.
+     * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
      *
-     * @type {number}
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram}
      */
-    transform_row = 0;
+    program;
 
     /**
-     * Compiled effect: the per-particle attribute layout plus the INIT/UPDATE bytecode.
+     * Image to draw the particles with, by URL, or `null` to draw against the default atlas — a
+     * single white texel, so an untextured emitter is a flat quad of its colour.
      *
-     * @type {{layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram}}
-     */
-    effect;
-
-    /**
-     * Where this emitter's program sits in the shared arena, and the dense program id the
-     * simulation-order bucketing keys on. Assigned by {@link EmitterRegistry#add} from
-     * {@link ../runtime/ProgramArena.js}; emitters compiled from the same graph share one.
+     * A URL rather than a texture, and no uv rect: the particle system packs every emitter's image
+     * into one sheet so that a hundred effects sharing a puff of smoke pay for one image, and where
+     * a given image lands in that sheet is the system's answer, not the author's — it changes on
+     * every repack, without the emitter changing. The resolved patch is
+     * {@link ./GPUParticleEmitterContext.js#atlas_region}.
      *
-     * @type {{init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
+     * @type {string|null}
      */
-    placement;
+    texture = null;
 
     /**
      * Base RNG seed.
      *
-     * Two emitters running one program produce identical particles from identical seeds, so leaving
-     * this at 0 is almost never what an author wants — {@link EmitterRegistry#add} reads 0 as
-     * "unset" and derives one from the generation instead.
+     * Two emitters running one program produce identical particles from identical seeds. `0` reads
+     * as "unset", and the row written for such an emitter takes its registration's generation
+     * instead, which no other emitter of that registry shares.
      *
      * @type {number}
      */
@@ -155,13 +148,8 @@ export class ParticleEmitter extends Node3D {
     bounds_radius = 1;
 
     /**
-     * Atlas sub-rect: uv offset `.xy`, uv scale `.zw`. Mirrors meep's `AtlasPatch`.
-     * @type {Float32Array}
-     */
-    atlas_region = new Float32Array([0, 0, 1, 1]);
-
-    /**
-     * Flipbook grid: columns, rows. `[1, 1]` is a single frame.
+     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
+     * is a single frame.
      * @type {Float32Array}
      */
     flipbook = new Float32Array([1, 1]);
@@ -179,14 +167,6 @@ export class ParticleEmitter extends Node3D {
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
     render_velocity = EMITTER_ATTRIBUTE_ABSENT;
 
-    /**
-     * Whether the table row is out of step with the fields above. Set it after changing anything;
-     * {@link EmitterRegistry#flush} clears it once the row has been staged for upload.
-     *
-     * @type {boolean}
-     */
-    dirty = true;
-
     get type() {
         return "ParticleEmitter";
     }
@@ -206,9 +186,9 @@ export class ParticleEmitter extends Node3D {
      */
     bind_render(channels) {
         assert.isObject(channels, 'channels');
-        assert.defined(this.effect, 'effect');
+        assert.defined(this.layout, 'layout');
 
-        const layout = this.effect.layout;
+        const layout = this.layout;
 
         for (const channel of Object.keys(channels)) {
             const offset = layout.offsetOf(channels[channel]);
@@ -227,100 +207,181 @@ export class ParticleEmitter extends Node3D {
             }
         }
 
-        this.dirty = true;
+        this.needsUpdate = true;
+    }
+
+    /**
+     * Structural equality over everything an emitter *is*: where it sits, what it runs, what it
+     * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
+     * effect in one place, and one row would serve both.
+     *
+     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
+     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
+     * be compared. {@link transform_global} is left out too, being derived from
+     * {@link transform_local} and the parent chain.
+     *
+     * @param {ParticleEmitter} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+
+        return this.name === other.name
+            && this.texture === other.texture
+            && this.seed === other.seed
+            && this.spawn_rate === other.spawn_rate
+            && this.flags === other.flags
+            && this.bounds_radius === other.bounds_radius
+            && this.render_position === other.render_position
+            && this.render_size === other.render_size
+            && this.render_color === other.render_color
+            && this.render_rotation === other.render_rotation
+            && this.render_frame === other.render_frame
+            && this.render_velocity === other.render_velocity
+            && is_typed_array_equals(this.bounds_center, other.bounds_center)
+            && is_typed_array_equals(this.flipbook, other.flipbook)
+            && this.transform_local.equals(other.transform_local)
+            && this.layout.equals(other.layout)
+            && this.program.equals(other.program);
     }
 
     /**
-     * Fill `record` with this emitter as the value the emitter table stores — every field of
-     * {@link ../data/PARTICLE_EMITTER_STRUCT.js}, none omitted.
+     * Hash over everything {@link equals} compares, in the same terms — the compiled program hashes
+     * by its own bytecode rather than by object identity, so two emitters separately compiled from
+     * one graph hash equally, as they compare equally.
      *
-     * 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.
+     * @returns {number} int32
+     */
+    hash() {
+        const bindings = hash_mix3(
+            hash_mix3(this.render_position, this.render_size, this.render_color),
+            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
+            this.flags
+        );
+
+        const geometry = hash_mix3(
+            float32_array_hash(this.bounds_center, 0, this.bounds_center.length),
+            computeHashFloat(this.bounds_radius),
+            float32_array_hash(this.flipbook, 0, this.flipbook.length)
+        );
+
+        const appearance = hash_mix3(
+            computeStringHash(this.name),
+            computeStringHash(this.texture),
+            hash_mix2(this.seed, computeHashFloat(this.spawn_rate))
+        );
+
+        return hash_mix3(
+            hash_mix2(bindings, geometry),
+            hash_mix2(appearance, this.transform_local.hash()),
+            hash_mix2(this.layout.hash(), this.program.hash())
+        );
+    }
+
+    /**
+     * Make this emitter a copy of `other`: same effect, same settings, same placement.
      *
-     * 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.
+     * The layout and the compiled program are shared rather than duplicated — both are immutable
+     * once compiled, and sharing them is what puts two emitters of one effect on one program id in
+     * the program heap, hence in one simulation bucket.
      *
-     * @param {object} record the staging object, see {@link create_emitter_record}
-     * @returns {object} `record`
+     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
+     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
+     * a second reference to the first one's table row.
+     *
+     * @param {ParticleEmitter} other
      */
-    write_record(record) {
-        assert.defined(this.placement, 'placement');
-
-        const placement = this.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;
-
-        record.seed = this.seed;
-        record.flags = this.flags;
-        record.spawn_rate = this.spawn_rate;
-        record.node = this.transform_row;
-        record.generation = this.generation;
-
-        record.bounds_center.set(this.bounds_center);
-        record.bounds_radius = this.bounds_radius;
-
-        record.render_position = this.render_position;
-        record.render_size = this.render_size;
-        record.render_color = this.render_color;
-        record.render_rotation = this.render_rotation;
-        record.render_frame = this.render_frame;
-        record.render_velocity = this.render_velocity;
-
-        record.atlas_region.set(this.atlas_region);
-        record.flipbook.set(this.flipbook);
-
-        return record;
+    copy(other) {
+        super.copy(other);
+
+        this.name = other.name;
+
+        this.layout = other.layout;
+        this.program = other.program;
+        this.texture = other.texture;
+
+        this.seed = other.seed;
+        this.spawn_rate = other.spawn_rate;
+        this.flags = other.flags;
+
+        this.bounds_center.set(other.bounds_center);
+        this.bounds_radius = other.bounds_radius;
+        this.flipbook.set(other.flipbook);
+
+        this.render_position = other.render_position;
+        this.render_size = other.render_size;
+        this.render_color = other.render_color;
+        this.render_rotation = other.render_rotation;
+        this.render_frame = other.render_frame;
+        this.render_velocity = other.render_velocity;
     }
 
     /**
-     * This emitter as a fresh record object. {@link write_record} into a shared one is what the
-     * per-frame path uses; this is for tests and one-off inspection.
+     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
+     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
+     * `Node3D`, which would keep the transform and drop the effect.
      *
-     * @returns {object}
+     * @returns {ParticleEmitter}
      */
-    to_record() {
-        return this.write_record(create_emitter_record());
+    clone() {
+        const r = new ParticleEmitter();
+
+        r.copy(this);
+
+        for (const child of this.children) {
+            const clone = child.clone();
+
+            clone.parent = r;
+
+            r.children.push(clone);
+        }
+
+        return r;
     }
 
     /**
-     * Build an emitter from a plain description. Every parameter is optional except the effect —
-     * an emitter with no program has nothing to run.
+     * Build an emitter from a plain description. Every parameter is optional except the compiled
+     * effect — an emitter with no program has nothing to run.
+     *
+     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
+     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
      *
      * @param {object} config
-     * @param {{layout: object, program: object}} config.effect compiled effect, see
-     *        {@link ./create_particle_effect.js}
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
+     *        attribute schema
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
+     *        UPDATE bytecode
      * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @param {string|null} [config.texture] image URL to draw with
      * @param {number} [config.seed]
      * @param {number} [config.spawn_rate] particles/second
      * @param {object} [config.flags] passed to {@link make_emitter_flags}
      * @param {{center?: ArrayLike<number>, radius?: number}} [config.bounds]
      * @param {Object<string,string>} [config.render] render channel -> attribute name
-     * @param {ArrayLike<number>} [config.atlas_region] [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
      * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
      * @param {string} [config.name]
      * @returns {ParticleEmitter}
      */
     static from(config) {
         assert.isObject(config, 'config');
-        assert.defined(config.effect, 'config.effect');
-        assert.defined(config.effect.program, 'config.effect.program');
-        assert.defined(config.effect.layout, 'config.effect.layout');
+        assert.defined(config.layout, 'config.layout');
+        assert.defined(config.program, 'config.program');
 
         const emitter = new ParticleEmitter();
 
-        emitter.effect = config.effect;
+        emitter.layout = config.layout;
+        emitter.program = config.program;
 
         if (config.name !== undefined) {
             emitter.name = config.name;
         }
 
+        if (config.texture !== undefined) {
+            emitter.texture = config.texture;
+        }
+
         if (config.position !== undefined) {
             emitter.transform_local.setTranslation(config.position[0], config.position[1], config.position[2]);
             emitter.updateMatrices();
@@ -345,10 +406,6 @@ export class ParticleEmitter extends Node3D {
             }
         }
 
-        if (config.atlas_region !== undefined) {
-            emitter.atlas_region.set(config.atlas_region);
-        }
-
         if (config.flipbook !== undefined) {
             emitter.flipbook.set(config.flipbook);
         }
@@ -366,39 +423,3 @@ export class ParticleEmitter extends Node3D {
  * @type {boolean}
  */
 ParticleEmitter.prototype.isParticleEmitter = true;
-
-/**
- * An empty staging record with every field of {@link ../data/PARTICLE_EMITTER_STRUCT.js} present,
- * typed arrays for the vector fields so {@link ParticleEmitter#write_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/runtime/ProgramArena.d.ts

@@ -34,6 +34,32 @@ export class ProgramArena {
      * @type {number}
      */
     constant_word_count: number;
+    /**
+     * Slots the hungriest program in the arena needs — the maximum of every added program's
+     * `register_count`.
+     *
+     * This is the number that picks an interpreter. It is a property of the SET, not of a program:
+     * one program past {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} moves every
+     * pass in the system onto the wide register file, including the emitters whose programs would
+     * have fit. Per-program dispatch would be the other design, and a much larger one — two pipelines
+     * live at once, the coherence pass's buckets split along a second axis, and two indirect
+     * commands to size. This is a fallback for a case that should not arise, so it is the whole
+     * system or none of it.
+     *
+     * @type {number}
+     */
+    register_high_water: number;
+    /**
+     * Whether the arena holds a program the fast interpreter's register file cannot hold, and the
+     * system must therefore run on {@link ../vm/chunk_particle_vm_registers_wide.js}.
+     *
+     * Monotonic in practice: removing an emitter does not remove its program from the arena (ids are
+     * dense and buckets are keyed on them), so once the set has seen a wide program it stays wide
+     * until the arena itself is rebuilt.
+     *
+     * @returns {boolean}
+     */
+    get requires_wide_registers(): boolean;
     /**
      * Content key -> the placement the first identical program got.
      * @type {Map<string, {init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}>}

package/src/shade/renderer/particles/runtime/ProgramArena.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAEI;;;OAGG;IACH,mBAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAEE;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,UAFU,IAAI,MAAM,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAErI;IAErB;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;qBACnC,MAAM;oBAAc,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAgC9I;IAUD;;;;;;OAMG;IACH,wBAFa,WAAW,CAcvB;;CACJ"}
+{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH;IAEI;;;OAGG;IACH,mBAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAEE;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;;;;;;;;;;;OAaG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;;;;;;;OASG;IACH,uCAEC;IAED;;;OAGG;IACH,UAFU,IAAI,MAAM,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAErI;IAErB;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;qBACnC,MAAM;oBAAc,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAkC9I;IAUD;;;;;;OAMG;IACH,wBAFa,WAAW,CAcvB;;CACJ"}

package/src/shade/renderer/particles/runtime/ProgramHeap.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Holds every distinct compiled {@link ../isa/ParticleProgram.js ParticleProgram} the emitter set
+ * runs, packs them into one buffer — a header, every constant pool, then every instruction stream —
+ * and hands back the {@link ./ProgramPlacement.js placement} each emitter records.
+ *
+ * Data before code, behind a four-word header whose first word says where the code starts: the VM
+ * reads both sections through one binding (a storage buffer per stage is not free, and code and
+ * constants are read together), and an emitter's constant pool sits next to the pools of the
+ * programs it shares a wave with.
+ *
+ * **Programs are placed, not appended.** Each section is a range allocator
+ * ({@link ../../../../core/binary/allocator/OffsetAllocator.js}) over a flat word array, so a
+ * program that is no longer wanted gives its space back and the next one takes it. This is what the
+ * emitter table has always been able to do, and what the packed buffer could not: an authoring
+ * session that adds, edits and drops effects for an hour no longer grows the buffer for an hour.
+ *
+ * Because VM instructions carry no absolute code addresses (control flow is branchless) and constant
+ * references are program-local (the VM adds the emitter's `constant_offset`), a program is
+ * relocatable — it can be placed at any offset, and moved to another one by copying its words and
+ * rewriting the placement. INIT and UPDATE are one allocation, laid out back-to-back, because they
+ * are always wanted together.
+ *
+ * **Deduplication is by CONTENT, not object identity**, and it is the {@link HashMap} that does it:
+ * two emitters that authored the same graph separately compile to distinct `ParticleProgram` objects
+ * holding the same bytecode, and `ParticleProgram` already answers `equals`/`hash` over exactly
+ * that. They land on one placement, one bucket, and one copy of the code. Keying on the emitter
+ * instead would be simpler and strictly worse: N emitters running one shared effect would become N
+ * buckets, each padded out to a whole workgroup, which both wastes lanes and splits a run that was
+ * already program-coherent.
+ *
+ * **Sharing is what makes {@link ProgramHeap#release} a reference count** rather than a delete: the
+ * last emitter of an effect frees it, and the ones before it do not.
+ */
+export class ProgramHeap {
+    /**
+     * Bumped whenever the packed buffer would come out different from the last one
+     * {@link ProgramHeap#build_buffer} produced — a program was placed, or the sections were
+     * repacked. A holder that uploads the buffer re-uploads when this moves.
+     *
+     * Releasing a program does NOT move it. The words it occupied are dead rather than changed, and
+     * re-uploading the buffer to remove bytes nothing addresses would be a rebuild for nothing; the
+     * next program placed there is what makes the buffer differ, and that bumps this.
+     *
+     * @type {number}
+     */
+    version: number;
+    /**
+     * Bumped when a repack moved programs that were already placed — every existing placement now
+     * holds different offsets, so every emitter record built from one is out of date.
+     *
+     * Separate from {@link ProgramHeap#version} because the two ask for different work: that one
+     * says "upload the buffer again", this one says "restage every row". A repack moves both; an
+     * ordinary placement moves only the first.
+     *
+     * @type {number}
+     */
+    placement_version: number;
+    /**
+     * Distinct programs currently held — and therefore effects, not emitters.
+     * @returns {number}
+     */
+    get program_count(): number;
+    /**
+     * How many program ids the heap has had in play at once, which is the number of bins the
+     * simulation-order pass has to histogram into: live ids are all below it.
+     *
+     * It rises to the set's peak and stays there, because released ids are reused rather than
+     * renumbered. That costs an empty bin per id the set is currently below its peak by, and an
+     * empty bin is free — it rounds up to zero workgroups and shifts nothing after it — whereas
+     * renumbering would mean rewriting every emitter record that carries an id, and resizing the
+     * coherence buffers every time an effect came or went.
+     *
+     * @returns {number}
+     */
+    get program_id_capacity(): number;
+    /**
+     * Register slots the hungriest program currently held needs — the maximum of every live
+     * program's `register_count`, and `0` for an empty heap.
+     *
+     * The heap has no opinion about what that number means; it is the caller that compares it
+     * against {@link ../ParticleConstants.js PARTICLE_VM_FAST_REGISTER_SLOTS} and picks an
+     * interpreter, because which register backing a pass is compiled against is the VM's business
+     * and not the store's. What matters here is that the number is a property of the SET: there is
+     * one pipeline per pass and it is chosen once, so one hungry effect decides for every emitter in
+     * the system, including the ones whose programs would have fit.
+     *
+     * It falls again when that effect is released. The heap knows exactly what it holds, so there is
+     * no reason for the answer to be a high-water mark that only a full rebuild could bring down.
+     *
+     * @returns {number}
+     */
+    get max_register_count(): number;
+    /**
+     * Take a reference on `program`, placing it if the heap does not already hold an identical one.
+     *
+     * The placement it returns is what the emitter record carries and what the coherence pass
+     * buckets on. It is SHARED with every other holder of the same bytecode, and the heap mutates it
+     * in place when it repacks, so a caller keeps the object rather than copying its fields —
+     * copies go stale, the object does not.
+     *
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+     * @returns {ProgramPlacement}
+     */
+    acquire(program: import("../isa/ParticleProgram.js").ParticleProgram): ProgramPlacement;
+    /**
+     * Give back a reference taken by {@link ProgramHeap#acquire}. The program's ranges and its id are
+     * released when the last one goes.
+     *
+     * @param {ProgramPlacement} placement
+     * @returns {boolean} whether that was the last reference, and the program is now gone
+     */
+    release(placement: ProgramPlacement): boolean;
+    /**
+     * The packed buffer: `[header][constants][code]`. Word
+     * {@link ../ParticleConstants.js PARTICLE_PROGRAM_CODE_BASE_WORD} of the header is the word index
+     * the code starts at — the only absolute address in the buffer, and the reason a placement can
+     * hold section-relative offsets and survive the sections being resized.
+     *
+     * Both sections come out at their full capacity rather than trimmed to what is live: the offsets
+     * a placement holds are offsets into the capacity, and trimming would mean moving programs to
+     * close the holes, which is what a repack is for and what a buffer rebuild should not silently
+     * become.
+     *
+     * @returns {Uint32Array}
+     */
+    build_buffer(): Uint32Array;
+    #private;
+}
+import { ProgramPlacement } from "./ProgramPlacement.js";
+//# sourceMappingURL=ProgramHeap.d.ts.map

package/src/shade/renderer/particles/runtime/ProgramHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgramHeap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramHeap.js"],"names":[],"mappings":"AAmJA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IAEI;;;;;;;;;;OAUG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAEM;IAgDtB;;;OAGG;IACH,4BAEC;IAED;;;;;;;;;;;OAWG;IACH,kCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,iCAEC;IAED;;;;;;;;;;OAUG;IACH,iBAHW,OAAO,2BAA2B,EAAE,eAAe,GACjD,gBAAgB,CAuC5B;IAED;;;;;;OAMG;IACH,mBAHW,gBAAgB,GACd,OAAO,CAiCnB;IAED;;;;;;;;;;;;OAYG;IACH,gBAFa,WAAW,CAcvB;;CAwJJ;iCA5iBgC,uBAAuB"}