@woosh/meep-engine 3.42.0 → 3.43.0

package/src/shade/renderer/water/surface/particles/shader_water_particles.d.ts

@@ -11,25 +11,54 @@ export const WATER_PARTICLE_CORNERS: 4;
 /** Buckets ordered by particle; a crowded bucket past this keeps its arrival order. */
 export const WATER_PARTICLE_RANK_LIMIT: 64;
 /**
- * Packets a crowded cell keeps: where more crowd a cell, each is drawn by its share of the cell's summed steepness
- * times this, so about this many stay, the steepest whole. Well under the surface sampler's gather budget and the rank
- * limit, so a point reads all of its cell and every bucket keeps the particles' order.
+ * Packets a crowded point keeps. A point reads a cell of every level its body has, and a cell is crowded where its most
+ * crowded point reads more than this: a point of it at its level and the coarser ones, or one under it where finer
+ * levels hold packets too. Then each run of a front in it is drawn by its packets' least share of their cells: this
+ * many times the packet's steepness over the summed steepness that point reads, whatever the levels it is read at. So
+ * about this many stay at a point, the steepest whole wherever they sit, and a front stays whole or goes. What is
+ * elsewhere on the body does not count, so a splash far off, or a front moving to a coarser level, changes nothing here.
+ *
+ * A front's lot is its own for life and the same in every cell it reaches, so the fronts of the lowest lots are kept in
+ * every crowd they are in, whatever their size: the count at a point varies by fronts' worth around this, and a front
+ * the outline broke is drawn particle by particle, ~20 entries in one cell. Where a point would read more than the
+ * gather budget, its cells keep no more of it than their steepness's part, the lowest keys first
+ * ({@link WATER_PARTICLE_CROWD_BINS}), so no point reads past the budget. A whole front is drawn as the seven it was
+ * emitted as (water_particle_group), so three fresh splashes cross whole, whatever their steepness and levels; a fourth
+ * over them thins one.
+ *
+ * A cell only one front reaches is not crowded, however many of its packets it holds: one front puts at most ~40 in
+ * a cell, within the gather budget.
+ */
+export const WATER_PARTICLE_CELL_SHARE: 24;
+/**
+ * Octaves a crowded cell counts its entries in, by the key its lottery keeps them by (a front's lot over its
+ * steepness; the lowest kept first), below the most it can keep: bin j holds keys from 2^-(j+1) of that reach to
+ * 2^-j of it, the last everything below. A cell whose point could read past the gather budget drops its octaves from
+ * the top until the rest fit its part of the budget, so it may keep up to an octave's worth fewer than would fit.
+ */
+export const WATER_PARTICLE_CROWD_BINS: 4;
+/**
+ * Words a bucket's crowd takes, as the weigh pass sums it: its summed steepness, its largest front and complement of a
+ * front entered, and its entries.
  */
-export const WATER_PARTICLE_CELL_SHARE: 16;
+export const WATER_PARTICLE_CROWD_WORDS: 4;
+/**
+ * Words the nest pass adds to a bucket's crowd, in a buffer of their own so that it reads weigh's sums as plain loads:
+ * the most entries and the most summed steepness a point under it reads where finer levels hold packets, and its
+ * entries by key, {@link WATER_PARTICLE_CROWD_BINS} octaves.
+ */
+export const WATER_PARTICLE_NEST_WORDS: number;
 /** Width of the ramp a thinned packet fades over, a fraction of its share. */
 export const WATER_PARTICLE_THINNING_RAMP: 0.25;
 /** The step's settings: one immediate per entry point. */
 export const WATER_PARTICLE_STEP_STRUCT: WebGPUStruct;
 /** The pool's limits for the frame's finalize. */
 export const WATER_PARTICLE_LIMITS_STRUCT: WebGPUStruct;
-/**
- * Advance every live particle of a body simulated this frame in place and count what it leaves: 0, 1 or 3. A paused
- * body's particles stand still and leave themselves.
- */
 export const shader_water_particles_update: ComputeShader;
 /**
- * Write what each particle leaves into the next array at its scanned offset, in order: a split particle's
- * three at θ − β/3, θ, θ + β/3 with β/3 each. Past capacity, the tail is dropped.
+ * Write what each particle leaves into the next array at its scanned offset, in order: the particle, then the mirror
+ * image it left; each split one's three at θ − β/3, θ, θ + β/3 with β/3 each. So a front's particles stay in a row
+ * and in order, and an image follows its packet as a front of its own. Past capacity, the tail is dropped.
  */
 export const shader_water_particles_split: ComputeShader;
 /** The next array's count: everything the scan placed, up to capacity. */
@@ -37,30 +66,71 @@ export const shader_water_particles_total: ComputeShader;
 /**
  * Each queued splash of a row on the culling pass's emit list becomes a ring
  * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.3): packets of the splash's radius r, two radii out from its centre,
- * a front's width apart, ridge height strength·r/c (a vertical velocity over the time a crest takes to cross the
+ * their windows' arcs no longer than their envelopes, ridge height strength·r/c (a vertical velocity over the time a crest takes to cross the
  * packet), no steeper than 0.1. The row's queue is spent. A paused body's ring stands still with its other particles,
  * which this frame's binning does not visit, so the ring's bound is added to the body's own here.
  */
 export const shader_water_particles_emit: ComputeShader;
 /**
  * The live count, clamped to capacity (emitters append past it), and the frame's hash table size: twice the
- * entries the particles can take, a power of two, at least ${WATER_PARTICLE_TABLE_MIN}.
+ * entries the particles can take, a power of two, at least ${WATER_PARTICLE_TABLE_MIN}; and the command that clears
+ * that much of the table, a thread a bucket.
  */
 export const shader_water_particles_finalize: ComputeShader;
 /**
- * Each particle of a body simulated this frame adds its steepness to every cell its support overlaps: how crowded a
- * cell is, for the bin pass to thin it by.
+ * Zero the frame's table, as far as finalize sized it: each bucket's count, largest |a| and crowd. A frame pays for the
+ * table its particles take, not for the pool's capacity; the buckets past it are never read.
+ */
+export const shader_water_particles_clear: ComputeShader;
+/**
+ * Where each front's run of particles begins: 1 at a particle not of the front before it, else 0. A front keeps its
+ * particles in a row and in order — a ring is emitted whole, a split puts its three in its place, the dead leave no
+ * gap — so the inclusive scan of these numbers each run from 1. A mirror image follows its packet in the row: it
+ * breaks its front's run there, as a death does, and is a front of its own.
+ */
+export const shader_water_particles_fronts: ComputeShader;
+/**
+ * Two words a run: its first particle, and the share its crowd leaves it, none yet (the share pass lowers it).
+ */
+export const shader_water_particles_runs: ComputeShader;
+/**
+ * Two words a particle: its run, and how the frame draws it ({@link chunk_water_particle}'s water_particle_group): 1 as
+ * itself, 0 not at all, 3^g for the middle of a whole front's group of 3^g, drawn as one packet.
+ */
+export const shader_water_particles_groups: ComputeShader;
+/**
+ * Each packet drawn of a body simulated this frame adds its steepness to every cell its support overlaps: how crowded
+ * a cell is, for the share pass to thin it by. Per bucket ({@link WATER_PARTICLE_CROWD_WORDS}) the sum, the largest
+ * front and complement of a front entered, which are each other's complements only where one front alone was, and the
+ * entries. And its level to its body's: a point reads a cell of every level its body has.
  */
 export const shader_water_particles_weigh: ComputeShader;
 /**
- * Enter each particle of a body simulated this frame in every hash cell its support overlaps: count it into the cell's
- * bucket, keep its slot there, raise the bucket's largest |a| to its own, and mark its level on its body. One atomic
- * each: no compare-exchange loop a crowded bucket would serialize. A paused body's particles take no slot: nothing
- * draws them this frame.
+ * Each packet drawn of a body simulated this frame, its cells weighed: what a point of each of its cells reads at its
+ * level and the coarser ones, entries and summed steepness, raised onto the cell over it at every coarser level its
+ * body has, so a cell knows its most crowded point where finer levels hold packets under it; and its entry counted
+ * among its cell's by its key (water_particle_crowd_bin), for the share pass to cap a crowd by.
+ */
+export const shader_water_particles_nest: ComputeShader;
+/**
+ * Each packet drawn its share of the most crowded of its cells, lowered onto its run: a run is thinned whole, by the most
+ * crowded cell any of its packets is in, so a front is never holed. A cell is crowded where its most crowded point (one
+ * of it at its level and the coarser ones, or one under it the nest pass raised) reads more than
+ * {@link WATER_PARTICLE_CELL_SHARE} entries, and a packet's share there is that many times its steepness over the summed
+ * steepness that point reads. Where that point would read more than the gather budget, the cell keeps no more of it
+ * than its own steepness's part: its keys' octaves dropped from the top until the rest fit
+ * ({@link WATER_PARTICLE_CROWD_BINS}). A cell only one front reaches does not count.
+ */
+export const shader_water_particles_share: ComputeShader;
+/**
+ * Enter each packet drawn of a body simulated this frame in every hash cell its support overlaps: count it into the
+ * cell's bucket, keep its slot there, raise the bucket's largest |a| to its own, and mark its level on its body. One
+ * atomic each: no compare-exchange loop a crowded bucket would serialize. A paused body's particles take no slot:
+ * nothing draws them this frame.
  *
- * Where cells are crowded (the weigh pass), a particle is drawn by how much its most crowded cell leaves it
- * ({@link WATER_PARTICLE_CELL_SHARE}): one decision for all its cells, so the surface stays continuous across them, and
- * from its own lot, so it does not change with the order particles arrive in. One left out takes no slot.
+ * Where cells are crowded (the share pass), a run is drawn by the share its most crowded cell leaves it and its
+ * front's lot: one decision for all its packets and all their cells, so neither a front nor the surface across cells
+ * is holed, and it does not change with the order particles arrive in. One left out takes no slot.
  */
 export const shader_water_particles_bin: ComputeShader;
 /** Each entry to its bucket's range, in arrival order, at the height its crowd leaves it; the rank pass orders it. */

package/src/shade/renderer/water/surface/particles/shader_water_particles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_particles.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/shader_water_particles.js"],"names":[],"mappings":"AAuBA,uFAAuF;AACvF,uDAGE;AAEF,+DAA+D;AAC/D,8DAGE;AAEF,oFAAoF;AACpF,yDAGE;AAEF,0DAA0D;AAC1D,4CAA6C;AAE7C,gFAAgF;AAChF,uCAAwC;AAExC,uFAAuF;AACvF,2CAA4C;AAE5C;;;;GAIG;AACH,2CAA4C;AAE5C,8EAA8E;AAC9E,gDAAiD;AAOjD,0DAA0D;AAC1D,sDAAqH;AAErH,kDAAkD;AAClD,wDAA0H;AAe1H;;;GAGG;AACH,0DA0B8G;AAS9G;;;GAGG;AACH,yDAsB+E;AAQ/E,0EAA0E;AAC1E,yDAOiD;AAYjD;;;;;;GAMG;AACH,wDAwC0C;AAQ1C;;;GAGG;AACH,4DASiD;AA+DjD;;;GAGG;AACH,yDAekE;AAalE;;;;;;;;;GASG;AACH,uDAqCkE;AAUlE,sHAAsH;AACtH,2DAqBkE;AAUlE;;;;GAIG;AACH,wDA8BkE;AAUlE;;;;;GAKG;AACH,0DAqBkE;6BAjfrC,sCAAsC;8BAJrC,kCAAkC"}
+{"version":3,"file":"shader_water_particles.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/shader_water_particles.js"],"names":[],"mappings":"AA0BA,uFAAuF;AACvF,uDAGE;AAEF,+DAA+D;AAC/D,8DAGE;AAEF,oFAAoF;AACpF,yDAGE;AAEF,0DAA0D;AAC1D,4CAA6C;AAE7C,gFAAgF;AAChF,uCAAwC;AAExC,uFAAuF;AACvF,2CAA4C;AAE5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,2CAA4C;AAE5C;;;;;GAKG;AACH,0CAA2C;AAE3C;;;GAGG;AACH,2CAA4C;AAE5C;;;;GAIG;AACH,+CAAuE;AAEvE,8EAA8E;AAC9E,gDAAiD;AAUjD,0DAA0D;AAC1D,sDAAqH;AAErH,kDAAkD;AAClD,wDAA0H;AAuF1H,0DACyB;AAUzB;;;;GAIG;AACH,yDA4B+E;AAQ/E,0EAA0E;AAC1E,yDAOiD;AAYjD;;;;;;GAMG;AACH,wDAyC0C;AAS1C;;;;GAIG;AACH,4DAaiD;AASjD;;;GAGG;AACH,yDAWsC;AA6FtC;;;;;GAKG;AACH,0DAQ4D;AAQ5D;;GAEG;AACH,wDAY+E;AAS/E;;;GAGG;AACH,0DAc4D;AAW5D;;;;;GAKG;AACH,yDAuBkE;AAYlE;;;;;GAKG;AACH,wDAwCkE;AAalE;;;;;;;;GAQG;AACH,yDAoDkE;AAclE;;;;;;;;;GASG;AACH,uDA6BkE;AAWlE,sHAAsH;AACtH,2DAuBkE;AAWlE;;;;GAIG;AACH,wDAgCkE;AAWlE;;;;;GAKG;AACH,0DAuBkE;6BAp2BrC,sCAAsC;8BAJrC,kCAAkC"}