@woosh/meep-engine 3.15.0 → 3.17.0

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"}