@woosh/meep-engine 3.16.0 → 3.17.0

package/src/shade/renderer/particles/particle_test_fixtures.js

@@ -1,203 +1,229 @@
-import { SoftwareGPUDevice } from "../../device/mock/SoftwareGPUDevice.js";
-import { GraphicsContext } from "../GraphicsContext.js";
-import { gpu_database_words } from "../buffer/table/gpu_database_words.js";
-import { Scene } from "../scene/Scene.js";
-import { SceneManager } from "../scene/SceneManager.js";
-import { PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
-import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "./data/PARTICLE_DATABASE_SPEC.js";
-import { PARTICLE_EMITTER_STATE_STRUCT } from "./data/PARTICLE_EMITTER_STATE.js";
-import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
-import { ParticleEmitter } from "./runtime/ParticleEmitter.js";
-
-/**
- * Shared scaffolding for the particle specs that run shaders under the WGSL emulator.
- *
- * An emitter is a scene node, so a shader that reads one needs two databases laid out the way the
- * GPU would hold them: the scene's (for the node's world matrix) and the particle system's (for the
- * emitter row). Both are real `GPUDatabase`s on the software device, filled through the real
- * {@link GPUSceneContext} and {@link EmitterRegistry}, and serialised by
- * {@link gpu_database_words} — so a spec exercises the actual writers, and the only thing standing
- * in for the GPU is the upload.
- */
-
-/**
- * @typedef {object} ParticleSceneFixture
- * @property {SoftwareGPUDevice} device
- * @property {GraphicsContext} graphics
- * @property {Scene} scene
- * @property {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
- * @property {EmitterRegistry} registry
- */
-
-/**
- * A scene with a GPU context and an emitter registry, both on a fresh software device.
- *
- * @returns {ParticleSceneFixture}
- */
-export function particle_scene_fixture() {
-    const device = new SoftwareGPUDevice({ requiredFeatures: ["subgroups"] });
-    const graphics = new GraphicsContext(device);
-    const scene = new Scene();
-    const scene_context = new SceneManager(graphics).obtain(scene);
-    const registry = new EmitterRegistry(device);
-
-    return { device, graphics, scene, scene_context, registry };
-}
-
-/**
- * Put an emitter in the scene and register it, the way the system does: the node gets its
- * `transforms` row from the scene context's sweep, and the emitter record points at that row.
- *
- * @param {ParticleSceneFixture} fixture
- * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or what {@link ParticleEmitter.from} accepts
- * @param {import("../scene/Node3D.js").Node3D} [parent] node to hang the emitter under, itself already in the scene
- * @returns {ParticleEmitter}
- */
-export function place_emitter(fixture, config, parent) {
-    const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
-
-    if (parent !== undefined) {
-        parent.addChild(emitter);
-        parent.updateMatrices();
-    }
-
-    fixture.scene.add(emitter);
-    fixture.scene_context.build();
-
-    const transform_row = fixture.scene_context.id_mapping.get(emitter.id);
-
-    fixture.registry.add(emitter, transform_row);
-
-    return emitter;
-}
-
-/**
- * The two databases as the `array<u32>` buffers the particle shaders bind. Call after the last
- * change to either; it flushes both.
- *
- * @param {ParticleSceneFixture} fixture
- * @returns {{scene_database: Uint32Array, emitter_database: Uint32Array}}
- */
-export function particle_database_words(fixture) {
-    fixture.scene_context.build();
-    fixture.registry.flush();
-
-    return {
-        scene_database: gpu_database_words(fixture.scene_context.scene_database, fixture.graphics),
-        emitter_database: gpu_database_words(fixture.registry.database, fixture.graphics),
-    };
-}
-
-/**
- * An `array<atomic<u32>>` the way the emulator models one: a `{value}` object per word.
- *
- * @param {number} length
- * @param {number} [fill]
- * @returns {{value: number}[]}
- */
-export function atomic_words(length, fill = 0) {
-    return Array.from({ length }, () => ({ value: fill }));
-}
-
-/**
- * A counters buffer, every slot zero.
- *
- * @returns {{value: number}[]}
- */
-export function particle_counters() {
-    return atomic_words(PARTICLE_COUNTER_COUNT);
-}
-
-/**
- * Where a row of the `emitter_state` table sits in the serialised database, in words — the same
- * arithmetic the table's generated readers do.
- *
- * @param {Uint32Array} emitter_database the database as {@link particle_database_words} lays it out
- * @param {number} row
- * @returns {number}
- */
-function emitter_state_base(emitter_database, row) {
-    const descriptor = PARTICLE_EMITTER_STATE_DESCRIPTOR;
-    const per_page = descriptor.elements_per_page;
-    const page_address = emitter_database[descriptor.page_lookup_address + Math.floor(row / per_page)];
-
-    if (page_address === 0xffffffff) {
-        throw new Error(`emitter state row ${row} is on a page the database has not allocated`);
-    }
-
-    return page_address + descriptor.page_header_words + (row % per_page) * (descriptor.packed_element_size_bytes / 4);
-}
-
-/** @type {Object<string, number>} word offset of each state field within its row */
-const STATE_FIELD_WORD = Object.fromEntries(
-    PARTICLE_EMITTER_STATE_STRUCT.fields.map((field) => [field.name, field.offset / 4]),
-);
-
-/**
- * One emitter's GPU-owned state, read back out of the serialised database.
- *
- * @param {Uint32Array} emitter_database
- * @param {number} row
- * @returns {{generation: number, accumulator: number, age: number, sleep: number, pending: number}}
- */
-export function emitter_state_read(emitter_database, row) {
-    const base = emitter_state_base(emitter_database, row);
-    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
-
-    return {
-        generation: emitter_database[base + STATE_FIELD_WORD.generation],
-        accumulator: floats[base + STATE_FIELD_WORD.accumulator],
-        age: floats[base + STATE_FIELD_WORD.age],
-        sleep: floats[base + STATE_FIELD_WORD.sleep],
-        pending: emitter_database[base + STATE_FIELD_WORD.pending],
-    };
-}
-
-/**
- * Overwrite some of one emitter's state fields in the serialised database — what a previous tick
- * would have left there.
- *
- * @param {Uint32Array} emitter_database
- * @param {number} row
- * @param {{generation?: number, accumulator?: number, age?: number, sleep?: number, pending?: number}} fields
- */
-export function emitter_state_write(emitter_database, row, fields) {
-    const base = emitter_state_base(emitter_database, row);
-    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
-
-    if (fields.generation !== undefined) emitter_database[base + STATE_FIELD_WORD.generation] = fields.generation;
-    if (fields.accumulator !== undefined) floats[base + STATE_FIELD_WORD.accumulator] = fields.accumulator;
-    if (fields.age !== undefined) floats[base + STATE_FIELD_WORD.age] = fields.age;
-    if (fields.sleep !== undefined) floats[base + STATE_FIELD_WORD.sleep] = fields.sleep;
-    if (fields.pending !== undefined) emitter_database[base + STATE_FIELD_WORD.pending] = fields.pending;
-}
-
-/**
- * A `{count, elements}` collection as the emulator binds one — the shape both the emitter tick's
- * output and the emit pass's input take.
- *
- * @param {number} count
- * @param {ArrayLike<number>} [elements] defaults to `count` zeros
- * @returns {{count: number, elements: Uint32Array}}
- */
-export function u32_collection(count, elements) {
-    return { count, elements: elements === undefined ? new Uint32Array(count) : Uint32Array.from(elements) };
-}
-
-/**
- * The CSDLDF scan's stand-in: inclusive prefix sums over a collection's elements, in place, the
- * count left alone.
- *
- * @param {{count: number, elements: Uint32Array}} collection
- * @returns {{count: number, elements: Uint32Array}} the same object
- */
-export function inclusive_scan(collection) {
-    let running = 0;
-
-    for (let i = 0; i < collection.count; i++) {
-        running += collection.elements[i];
-        collection.elements[i] = running;
-    }
-
-    return collection;
-}
+import { SoftwareGPUDevice } from "../../device/mock/SoftwareGPUDevice.js";
+import { GraphicsContext } from "../GraphicsContext.js";
+import { gpu_database_words } from "../buffer/table/gpu_database_words.js";
+import { Scene } from "../scene/Scene.js";
+import { SceneManager } from "../scene/SceneManager.js";
+import { PARTICLE_COUNTER_COUNT } from "./data/PARTICLE_COUNTERS.js";
+import { PARTICLE_EMITTER_STATE_DESCRIPTOR } from "./data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_EMITTER_STATE_STRUCT } from "./data/PARTICLE_EMITTER_STATE.js";
+import { EmitterRegistry } from "./runtime/EmitterRegistry.js";
+import { ParticleEmitter } from "./runtime/ParticleEmitter.js";
+
+/**
+ * Shared scaffolding for the particle specs that run shaders under the WGSL emulator.
+ *
+ * An emitter is a scene node, so a shader that reads one needs two databases laid out the way the
+ * GPU would hold them: the scene's (for the node's world matrix) and the particle system's (for the
+ * emitter row). Both are real `GPUDatabase`s on the software device, filled through the real
+ * {@link GPUSceneContext} and {@link EmitterRegistry}, and serialised by
+ * {@link gpu_database_words} — so a spec exercises the actual writers, and the only thing standing
+ * in for the GPU is the upload.
+ */
+
+/**
+ * @typedef {object} ParticleSceneFixture
+ * @property {SoftwareGPUDevice} device
+ * @property {GraphicsContext} graphics
+ * @property {Scene} scene
+ * @property {import("../scene/GPUSceneContext.js").GPUSceneContext} scene_context
+ * @property {EmitterRegistry} registry
+ */
+
+/**
+ * A scene with a GPU context and an emitter registry, both on a fresh software device.
+ *
+ * @returns {ParticleSceneFixture}
+ */
+export function particle_scene_fixture() {
+    const device = new SoftwareGPUDevice({ requiredFeatures: ["subgroups"] });
+    const graphics = new GraphicsContext(device);
+    const scene = new Scene();
+    const scene_context = new SceneManager(graphics).obtain(scene);
+    const registry = new EmitterRegistry(device);
+
+    return { device, graphics, scene, scene_context, registry };
+}
+
+/**
+ * Put an emitter in the scene and register it, the way the system does: the node gets its
+ * `transforms` row from the scene context's sweep, and the emitter record points at that row.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or what {@link ParticleEmitter.from} accepts
+ * @param {import("../scene/Node3D.js").Node3D} [parent] node to hang the emitter under, itself already in the scene
+ * @returns {ParticleEmitter}
+ */
+export function place_emitter(fixture, config, parent) {
+    const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
+
+    if (parent !== undefined) {
+        parent.addChild(emitter);
+        parent.updateMatrices();
+    }
+
+    fixture.scene.add(emitter);
+    fixture.scene_context.build();
+
+    const transform_row = fixture.scene_context.id_mapping.get(emitter.id);
+
+    fixture.registry.add(emitter, transform_row);
+
+    return emitter;
+}
+
+/**
+ * What the fixture's registry assigned an emitter: its table row, its generation, the heap
+ * placement of its program, the atlas patch. The emitter carries none of it — see
+ * {@link ./runtime/GPUParticleEmitterContext.js} — so a spec that wants the row a particle header
+ * should carry asks the registry, the way the passes' own callers do.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @param {ParticleEmitter} emitter
+ * @returns {import("./runtime/GPUParticleEmitterContext.js").GPUParticleEmitterContext}
+ */
+export function emitter_context(fixture, emitter) {
+    return fixture.registry.context(emitter);
+}
+
+/**
+ * The emitter table row an emitter was given — {@link emitter_context}`.row`, which specs index
+ * per-emitter buffers with often enough to be worth naming.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @param {ParticleEmitter} emitter
+ * @returns {number}
+ */
+export function emitter_row(fixture, emitter) {
+    return emitter_context(fixture, emitter).row;
+}
+
+/**
+ * The two databases as the `array<u32>` buffers the particle shaders bind. Call after the last
+ * change to either; it flushes both.
+ *
+ * @param {ParticleSceneFixture} fixture
+ * @returns {{scene_database: Uint32Array, emitter_database: Uint32Array}}
+ */
+export function particle_database_words(fixture) {
+    fixture.scene_context.build();
+    fixture.registry.flush();
+
+    return {
+        scene_database: gpu_database_words(fixture.scene_context.scene_database, fixture.graphics),
+        emitter_database: gpu_database_words(fixture.registry.database, fixture.graphics),
+    };
+}
+
+/**
+ * An `array<atomic<u32>>` the way the emulator models one: a `{value}` object per word.
+ *
+ * @param {number} length
+ * @param {number} [fill]
+ * @returns {{value: number}[]}
+ */
+export function atomic_words(length, fill = 0) {
+    return Array.from({ length }, () => ({ value: fill }));
+}
+
+/**
+ * A counters buffer, every slot zero.
+ *
+ * @returns {{value: number}[]}
+ */
+export function particle_counters() {
+    return atomic_words(PARTICLE_COUNTER_COUNT);
+}
+
+/**
+ * Where a row of the `emitter_state` table sits in the serialised database, in words — the same
+ * arithmetic the table's generated readers do.
+ *
+ * @param {Uint32Array} emitter_database the database as {@link particle_database_words} lays it out
+ * @param {number} row
+ * @returns {number}
+ */
+function emitter_state_base(emitter_database, row) {
+    const descriptor = PARTICLE_EMITTER_STATE_DESCRIPTOR;
+    const per_page = descriptor.elements_per_page;
+    const page_address = emitter_database[descriptor.page_lookup_address + Math.floor(row / per_page)];
+
+    if (page_address === 0xffffffff) {
+        throw new Error(`emitter state row ${row} is on a page the database has not allocated`);
+    }
+
+    return page_address + descriptor.page_header_words + (row % per_page) * (descriptor.packed_element_size_bytes / 4);
+}
+
+/** @type {Object<string, number>} word offset of each state field within its row */
+const STATE_FIELD_WORD = Object.fromEntries(
+    PARTICLE_EMITTER_STATE_STRUCT.fields.map((field) => [field.name, field.offset / 4]),
+);
+
+/**
+ * One emitter's GPU-owned state, read back out of the serialised database.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @returns {{generation: number, accumulator: number, age: number, sleep: number, pending: number}}
+ */
+export function emitter_state_read(emitter_database, row) {
+    const base = emitter_state_base(emitter_database, row);
+    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
+
+    return {
+        generation: emitter_database[base + STATE_FIELD_WORD.generation],
+        accumulator: floats[base + STATE_FIELD_WORD.accumulator],
+        age: floats[base + STATE_FIELD_WORD.age],
+        sleep: floats[base + STATE_FIELD_WORD.sleep],
+        pending: emitter_database[base + STATE_FIELD_WORD.pending],
+    };
+}
+
+/**
+ * Overwrite some of one emitter's state fields in the serialised database — what a previous tick
+ * would have left there.
+ *
+ * @param {Uint32Array} emitter_database
+ * @param {number} row
+ * @param {{generation?: number, accumulator?: number, age?: number, sleep?: number, pending?: number}} fields
+ */
+export function emitter_state_write(emitter_database, row, fields) {
+    const base = emitter_state_base(emitter_database, row);
+    const floats = new Float32Array(emitter_database.buffer, emitter_database.byteOffset, emitter_database.length);
+
+    if (fields.generation !== undefined) emitter_database[base + STATE_FIELD_WORD.generation] = fields.generation;
+    if (fields.accumulator !== undefined) floats[base + STATE_FIELD_WORD.accumulator] = fields.accumulator;
+    if (fields.age !== undefined) floats[base + STATE_FIELD_WORD.age] = fields.age;
+    if (fields.sleep !== undefined) floats[base + STATE_FIELD_WORD.sleep] = fields.sleep;
+    if (fields.pending !== undefined) emitter_database[base + STATE_FIELD_WORD.pending] = fields.pending;
+}
+
+/**
+ * A `{count, elements}` collection as the emulator binds one — the shape both the emitter tick's
+ * output and the emit pass's input take.
+ *
+ * @param {number} count
+ * @param {ArrayLike<number>} [elements] defaults to `count` zeros
+ * @returns {{count: number, elements: Uint32Array}}
+ */
+export function u32_collection(count, elements) {
+    return { count, elements: elements === undefined ? new Uint32Array(count) : Uint32Array.from(elements) };
+}
+
+/**
+ * The CSDLDF scan's stand-in: inclusive prefix sums over a collection's elements, in place, the
+ * count left alone.
+ *
+ * @param {{count: number, elements: Uint32Array}} collection
+ * @returns {{count: number, elements: Uint32Array}} the same object
+ */
+export function inclusive_scan(collection) {
+    let running = 0;
+
+    for (let i = 0; i < collection.count; i++) {
+        running += collection.elements[i];
+        collection.elements[i] = running;
+    }
+
+    return collection;
+}

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

@@ -12,15 +12,21 @@
  * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
  * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
  *
+ * **None of that bookkeeping is on the emitter.** An emitter is a scene node and a description of
+ * an effect, with nothing in it that depends on a device; the row, the generation, the program
+ * placement, the node's `transforms` row and the atlas patch are a
+ * {@link ./GPUParticleEmitterContext.js} this registry holds against the emitter and hands out
+ * through {@link EmitterRegistry#context}. Registering an emitter creates one, removing it destroys
+ * one, and an emitter with no context here is an emitter this registry does not have.
+ *
  * The GPU-owned per-emitter state is the database's second table, claimed and released here at the
  * emitter's row and never written by the CPU otherwise.
  *
  * Programs are the one thing NOT in the database: they are variable-length and shared, so they go
- * into a packed {@link ProgramArena} buffer and the emitter record carries offsets into it. The arena is
- * append-only and content-deduplicated — two emitters compiled from the same graph land on one
- * program id, which is what the simulation-order bucketing buckets on. Removing an emitter does not
- * reclaim its program: the dense `program_id`s are baked into every other emitter's record, so
- * compacting them would mean rewriting the whole table to save a few hundred words.
+ * into a packed {@link ProgramHeap} buffer and the emitter record carries offsets into it. The heap
+ * is content-deduplicated and reference-counted — two emitters compiled from the same graph land on
+ * one program id, which is what the simulation-order bucketing buckets on, and the last emitter of
+ * an effect is what releases it.
  */
 export class EmitterRegistry {
     /**
@@ -33,11 +39,11 @@ export class EmitterRegistry {
     database: GPUDatabase;
     /**
      * Packed instruction + constant buffers for every distinct program in the set.
-     * @type {ProgramArena}
+     * @type {ProgramHeap}
      */
-    arena: ProgramArena;
+    programs: ProgramHeap;
     /**
-     * The live emitters, in no particular order — {@link ParticleEmitter#row} is the identity.
+     * The live emitters, in no particular order — the row in {@link context} is the identity.
      * @type {ParticleEmitter[]}
      */
     emitters: ParticleEmitter[];
@@ -49,14 +55,17 @@ export class EmitterRegistry {
      */
     by_row: ParticleEmitter[];
     /**
-     * Whether {@link arena} has grown since the instruction/constant buffers were last built. Those
-     * two are monolithic (a program is variable-length, so there is no table to page them into), so
-     * a new program means re-uploading them whole — which is why the arena dedupes by content and
-     * why this is a separate flag from the per-row dirtiness the table tracks.
+     * Whether {@link programs} has changed since {@link build_program} last packed it. The buffer is
+     * monolithic (a program is variable-length, so there is no table to page it into), so any change
+     * means re-uploading it whole — which is why the heap dedupes by content, and why this is
+     * separate from the per-row dirtiness the table tracks.
+     *
+     * Read off the heap's own version rather than kept as a flag: there is then no path that changes
+     * the programs and forgets to say so.
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
-    programs_dirty: boolean;
+    get programs_dirty(): boolean;
     /**
      * The emitter table.
      * @returns {GPUTypedTable}
@@ -73,12 +82,37 @@ export class EmitterRegistry {
      */
     get count(): number;
     /**
-     * Number of distinct compiled programs — the number of buckets the simulation-order coherence
-     * pass histograms into.
-     *
+     * Number of distinct compiled programs registered.
      * @returns {number}
      */
     get program_count(): number;
+    /**
+     * Number of buckets the simulation-order coherence pass histograms into: every live program id
+     * is below it. See {@link ProgramHeap#program_id_capacity}.
+     *
+     * @returns {number}
+     */
+    get program_id_capacity(): number;
+    /**
+     * Register slots the hungriest registered effect needs — a property of the whole set, since
+     * there is one simulate pipeline and it is chosen once. What a caller does with the number (pick
+     * a register backing, refuse the effect, warn an author) is the caller's; see
+     * {@link ProgramHeap#max_register_count}.
+     *
+     * @returns {number}
+     */
+    get max_register_count(): number;
+    /**
+     * What this registry assigned an emitter: its table row, generation, program placement, the
+     * `transforms` row of its node and its atlas patch.
+     *
+     * `undefined` for an emitter this registry does not hold — which is the way to ask whether one
+     * is live, there being no `-1` on the emitter to read instead.
+     *
+     * @param {ParticleEmitter} emitter
+     * @returns {GPUParticleEmitterContext|undefined}
+     */
+    context(emitter: ParticleEmitter): GPUParticleEmitterContext | undefined;
     /**
      * Register an emitter and give it a table row.
      *
@@ -97,9 +131,30 @@ export class EmitterRegistry {
      * them the next time it sees them. Retiring an emitter gently — spawn rate to zero, remove once
      * its particles have died — remains available to an author who wants the tail to play out.
      *
+     * The emitter itself comes out of this unchanged: what it loses is its context, which is
+     * everything being registered gave it. Its program goes with the context — the heap counts
+     * references, so an effect is only unpacked when its last emitter leaves.
+     *
      * @param {ParticleEmitter} emitter
      */
     remove(emitter: ParticleEmitter): void;
+    /**
+     * Give a registered emitter different bytecode to run: its old program loses a reference, the new
+     * one gains one, and its row is restaged with the new placement.
+     *
+     * This is the runtime edit the emitter table has always allowed and the program buffer used not
+     * to — an author reworking an effect in the editor changes the program of an emitter that is
+     * already live, and the effect it used to run goes away with the last emitter that ran it.
+     *
+     * The attribute {@link ../layout/ParticleLayout.js layout} is NOT part of this and must not
+     * change with it: particles already in flight are laid out the old way, and new bytecode reading
+     * them at new offsets would read somebody else's field. Re-laying-out an effect means new
+     * emitters.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
+     */
+    set_program(emitter: ParticleEmitter, program: import("../isa/ParticleProgram.js").ParticleProgram): void;
     /**
      * Look up a live emitter by its table row.
      *
@@ -115,21 +170,39 @@ export class EmitterRegistry {
      * @param {number} transform_row
      */
     set_transform_row(emitter: ParticleEmitter, transform_row: number): void;
+    /**
+     * Point an emitter's record at the patch its texture was packed into: uv offset `.xy`, uv scale
+     * `.zw`. The row is restaged on the next flush.
+     *
+     * For whoever owns the atlas to call, on registration and again after every repack — a repack
+     * moves every patch, and an emitter left holding the old one draws the wrong image.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {ArrayLike<number>} region [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
+     */
+    set_atlas_region(emitter: ParticleEmitter, region: ArrayLike<number>): void;
     /**
      * Restage the table rows of every emitter whose fields have moved since the last flush.
      *
-     * Cheap to call every frame: an emitter that has not changed costs one boolean test, and the
-     * table coalesces repeated writes to one row within a frame anyway. Allocates nothing — every
-     * row goes through the one module-static staging record.
+     * "Moved" is the node's own change counter: an emitter is restaged when its
+     * {@link ../../scene/Node3D.js Node3D#version} is not the one its row was staged from, or when
+     * something in its context changed. So an author marks an edited emitter the way they mark any
+     * edited node, with `needsUpdate = true`, and there is no second flag to forget.
+     *
+     * Cheap to call every frame: an emitter that has not changed costs one integer comparison, and
+     * the table coalesces repeated writes to one row within a frame anyway. Walks the context map
+     * rather than the emitter list so that a pass over the set is not also a lookup per emitter.
+     * Stages through the one module-static record, so a frame's restaging allocates nothing however
+     * many rows it touches.
      */
     flush(): void;
     /**
      * The packed program buffer — header, constant pools, code — rebuilt whole.
      *
-     * Call when {@link programs_dirty}; it clears the flag. The buffer is monolithic (a program is
-     * variable-length, so there is no table to page it into), so this is a full rebuild — the
-     * arena's content deduplication is what keeps it rare (it only grows when an effect the set has
-     * never seen is registered).
+     * Call when {@link programs_dirty}; it answers the flag. The buffer is monolithic (a program is
+     * variable-length, so there is no table to page it into), so this is a full rebuild — the heap's
+     * content deduplication is what keeps it rare (it changes only when an effect the set has never
+     * seen is registered, or when the sections are repacked to make room for one).
      *
      * @returns {Uint32Array}
      */
@@ -137,6 +210,7 @@ export class EmitterRegistry {
     #private;
 }
 import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
-import { ProgramArena } from "./ProgramArena.js";
+import { ProgramHeap } from "./ProgramHeap.js";
 import { ParticleEmitter } from "./ParticleEmitter.js";
+import { GPUParticleEmitterContext } from "./GPUParticleEmitterContext.js";
 //# sourceMappingURL=EmitterRegistry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IA2CI;;OAEG;IACH,+BASC;IArDD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,OAFU,YAAY,CAEK;IAE3B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;OAOG;IACH,gBAFU,OAAO,CAEK;IAsBtB;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;;;OAKG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CAwC3B;IAED;;;;;;;;;OASG;IACH,gBAFW,eAAe,QAwBzB;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAWhB;IAED;;;;;;OAMG;IACH,cAeC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;4BA5R2B,mCAAmC;6BAUlC,mBAAmB;gCADO,sBAAsB"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAwEI;;OAEG;IACH,+BASC;IAlFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,2BAEC;IAED;;;;OAIG;IACH,iCAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA8B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA4BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QAqB7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cAoBC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;4BApb2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}