@codexo/exojs-particles 0.15.3 → 0.16.0

package/dist/esm/gpu/ParticleGpuState.d.ts

@@ -1,7 +1,24 @@
 import type { Rectangle } from '@codexo/exojs';
 import type { Texture } from '@codexo/exojs';
-import type { UpdateModule } from "#modules/UpdateModule";
-import type { ParticleSystem } from "#ParticleSystem";
+import type { UpdateModule } from '#modules/UpdateModule';
+import type { ParticleSystem } from '#ParticleSystem';
+/**
+ * One particle's state as the compute shader captured it at death, plus the
+ * slot it occupied. The slot orders the records; it never leaves the package.
+ * @internal
+ */
+export interface ParticleDeathRecord {
+    readonly x: number;
+    readonly y: number;
+    readonly velocityX: number;
+    readonly velocityY: number;
+    readonly rotation: number;
+    readonly scaleX: number;
+    readonly scaleY: number;
+    readonly elapsed: number;
+    readonly color: number;
+    readonly slot: number;
+}
 export declare class ParticleGpuState {
     readonly device: GPUDevice;
     readonly capacity: number;
@@ -13,14 +30,45 @@ export declare class ParticleGpuState {
     private readonly _rotInfo;
     private readonly _timing;
     private readonly _color;
-    private readonly _textureIndex;
+    private readonly _instanceStorageBuffer;
+    /**
+     * Death records the compute shader appended, plus the atomic append counter
+     * in its first four bytes. Allocated only while the system has death modules,
+     * so a system without them pays neither the memory nor the copy.
+     *
+     * Detecting a death and reporting one have separate lifetimes, and the path
+     * between them has four stages: the shader appends here; records the copy has
+     * not taken yet stay here as a device-side backlog; a copy moves a batch into
+     * a staging slot; and the mapped batches are handed on in submission order.
+     */
+    private _deathBuffer;
+    private readonly _deathCounterReset;
+    /**
+     * Readback slots for the death buffer. A slot stays unavailable from the
+     * submit that copies into it until its map resolves, so a single slot would
+     * make every death that happens while a readback is in flight either a
+     * validation error or a lost record. Three slots cover the queue depth a
+     * frame loop runs at; a fourth death batch waits on the device instead.
+     */
+    private readonly _deathStaging;
+    /** Copies submitted into a staging slot, oldest first, awaiting delivery. */
+    private readonly _stagedDeaths;
+    /**
+     * Whether the death buffer holds records no readback has claimed yet. The
+     * append counter is reset only once a copy has taken them, so a step that
+     * finds no free staging slot leaves its records in place and the next step
+     * appends behind them.
+     */
+    private _deathBufferDirty;
+    /** Tail of the delivery chain, so batches are reported in submission order. */
+    private _deathDelivery;
     private readonly _simUniformBuffer;
     private readonly _simUniformData;
     private readonly _simUniformView;
-    private readonly _moduleUniformBuffer;
-    private readonly _moduleUniformData;
-    private readonly _moduleUniformView;
-    private readonly _moduleSlots;
+    private _moduleUniformBuffer;
+    private _moduleUniformData;
+    private _moduleUniformView;
+    private _moduleSlots;
     private readonly _framesUniformBuffer;
     private readonly _framesUniformData;
     private readonly _framesUniformView;
@@ -28,30 +76,107 @@ export declare class ParticleGpuState {
     private readonly _moduleTextures;
     private readonly _samplerFiltering;
     private readonly _samplerNonFiltering;
-    private readonly _pipeline;
-    private readonly _bindGroup0;
-    private readonly _bindGroup1;
-    constructor(device: GPUDevice, capacity: number, modules: readonly UpdateModule[], frames: readonly Rectangle[], texture: Texture);
-    dispatch(system: ParticleSystem, dt: number): void;
+    private _pipelineWrapper;
+    private _bindGroup0;
+    private _bindGroup1;
+    private _reportsDeaths;
+    private _destroyed;
+    constructor(device: GPUDevice, capacity: number, modules: readonly UpdateModule[], frames: readonly Rectangle[], texture: Texture, reportsDeaths?: boolean);
+    /**
+     * Compiles the pipeline for `modules` and binds it to the buffers this state
+     * already owns.
+     *
+     * The simulation lives in those buffers, not in the program, so changing the
+     * module list rebuilds the shader, its uniforms and its lookup textures while
+     * every live particle keeps the position and velocity the GPU last integrated.
+     */
+    setProgram(modules: readonly UpdateModule[], reportsDeaths: boolean): void;
+    /** Releases everything the current program owns, leaving the simulation buffers untouched. */
+    private _destroyProgram;
+    /**
+     * Runs one simulation step over `[0, dispatchCount)`.
+     *
+     * `pendingDeaths` is how many expired particles the caller is still holding,
+     * including the ones it marked for this step. The shader appends exactly one
+     * record per marked particle, so the readback copies the used prefix of the
+     * death buffer without first having to read its counter back - the count is
+     * already known on this side.
+     *
+     * Returns whether a death batch was staged for readback. Deaths stay on the
+     * device while every staging slot is in flight, so a step can report deaths
+     * without staging any, and a later step can stage a batch spanning several
+     * steps. A caller keeping per-death state has to hold it, and keep counting it
+     * into `pendingDeaths`, until a step stages - then hand over all of it.
+     */
+    dispatch(dt: number, dispatchCount: number, pendingDeaths?: number): boolean;
+    /**
+     * Resolves the oldest staged death batch and hands its records to `receive`
+     * once the copy has landed.
+     *
+     * The mapping is asynchronous by nature, so a death is delivered no earlier
+     * than the frame after it happened. Batches are delivered in the order they
+     * were submitted, and nothing blocks on a map: further steps keep staging
+     * into other slots while one is in flight. A device that goes away mid-map
+     * resolves to nothing rather than throwing: the deaths are lost with the
+     * simulation that produced them.
+     */
+    readDeaths(receive: (records: readonly ParticleDeathRecord[]) => void): Promise<void>;
+    private _deliverDeaths;
+    /**
+     * Claims a staging slot able to hold `records`, or null while every slot of
+     * the ring is still in flight.
+     */
+    private _acquireDeathStaging;
+    private _releaseDeathStaging;
     destroy(): void;
     private _writeFrames;
     /**
      * Push the listed CPU SoA slots to the GPU. Called by `ParticleSystem`
      * with newly-spawned slots and just-expired slots (lifetime sentinel).
-     * Slots not in the dirty set are left alone — GPU keeps the integrated
+     * Slots not in the dirty set are left alone - GPU keeps the integrated
      * state from previous compute dispatches.
      *
-     * Each dirty slot triggers 7 small `queue.writeBuffer` calls (one per
-     * SoA channel). For typical spawn rates (≤200/s) this is negligible
-     * (≤1400 calls/s); contiguous-range batching is a future optimisation.
+     * Each dirty slot triggers 7 small writes (one per SoA channel, via
+     * {@link WebGpuStorageBuffer.write}). For typical spawn rates (≤200/s)
+     * this is negligible (≤1400 calls/s); contiguous-range batching is a
+     * future optimisation.
      */
     uploadDirty(system: ParticleSystem, slots: Iterable<number>): void;
+    /**
+     * Marks `slot` expired for the device without touching anything else about
+     * it. Only the lifetime lane is written: a full slot upload would push the
+     * CPU's stale position and velocity over the values the device integrated,
+     * and those are exactly what the death record is supposed to carry.
+     */
+    uploadExpiry(slot: number): void;
+    private readonly _expiryScratch;
     private readonly _dirtyScratchVec2;
+    private readonly _dirtyScratchVec4;
     private readonly _dirtyScratchU32;
     private _writeSimUniforms;
     private _writeModuleUniforms;
-    private _buildBindGroup0Layout;
-    private _buildBindGroup0;
+    /**
+     * WGSL variable names of module lookup textures/samplers whose format isn't natively
+     * filterable (`r32float` Curve LUTs) - fed to {@link reflectComputeBindings} so it declares
+     * `'unfilterable-float'`/`'non-filtering'` for those specific bindings instead of the default
+     * `'float'`/`'filtering'`, an ambiguity the WGSL text itself can't resolve (see that
+     * function's doc comment).
+     */
+    private _nonFilteringResourceNames;
+    /** Group-0 bind-group entries, matching group 0's bindings (reflected from the shader text) one-to-one. */
+    private _buildBindGroup0Entries;
+    /** Group-1 bind-group entries: the 8 SoA storage buffers, matching group 1's bindings (reflected from the shader text) one-to-one. */
+    private _buildSoaBindGroupEntries;
     private _buildShader;
+    /**
+     * The block that captures a particle's state the first time the shader sees
+     * its expiry sentinel, or nothing when the system has no death modules.
+     *
+     * The CPU marks an expired particle with `lifetime = -1` and the shader
+     * rewrites that to `-2` once captured, so exactly one record is appended per
+     * death even though a dead slot is visited every frame until it is reused.
+     */
+    private _deathReportSource;
     private _renderModuleStruct;
 }
+//# sourceMappingURL=ParticleGpuState.d.ts.map

package/dist/esm/gpu/ParticleGpuState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleGpuState.d.ts","sourceRoot":"","sources":["../../../src/gpu/ParticleGpuState.ts"],"names":[],"mappings":"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"}