@woosh/meep-engine 3.44.0 → 3.46.0

package/src/shade/renderer/water/surface/particles/chunk_water_particle.js

@@ -37,6 +37,18 @@ export const WATER_PARTICLE_STRETCH = [
 /** log₂(k/k_m) of the stretch table's first entry; entries are a quarter apart. */
 const WATER_PARTICLE_STRETCH_FIRST = -7;
 
+/** Bits of a hash entry's run word that hold its count of particles; the two above them mark its open ends. */
+export const WATER_PARTICLE_RUN_MEMBERS = 0x3fffffff;
+
+/** A run whose first particle has no neighbour of its front before it: it tapers there by that particle's window. */
+export const WATER_PARTICLE_RUN_OPEN_START = 0x40000000;
+
+/** A run whose last particle has no neighbour of its front after it. */
+export const WATER_PARTICLE_RUN_OPEN_END = 0x80000000;
+
+/** A particle drawn alone: a run of one, open at both ends, which is its own window. */
+export const WATER_PARTICLE_LONE = (1 | WATER_PARTICLE_RUN_OPEN_START | WATER_PARTICLE_RUN_OPEN_END) >>> 0;
+
 /**
  * The physics of one wave particle as pure functions (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
  *
@@ -52,7 +64,8 @@ const WATER_PARTICLE_STRETCH_FIRST = -7;
  * The particles of a front are β apart in angle around its centre, and a packet's crests are arcs around that
  * centre; a cosine window of half-angle β is a partition of unity over them at every radius, so the front's
  * height is the packet's amplitude whatever the spacing, splitting a front changes none of it, and one front
- * adds at most two particles at any point.
+ * adds at most two particles at any point. So a run of neighbours alike in all but angle is drawn as one: height one
+ * over its particles and its own window past either end that has no neighbour, the same surface its windows sum to.
  *
  * @type {CodeChunk}
  */
@@ -62,6 +75,10 @@ const WATER_PARTICLE_LEVEL_BITS: u32 = ${WATER_PARTICLE_LEVEL_BITS}u;
 const WATER_PARTICLE_LEVEL0_CELL: f32 = ${WATER_PARTICLE_LEVEL0_CELL};
 const WATER_PARTICLE_STRETCH = array<f32, ${WATER_PARTICLE_STRETCH.length}>(${WATER_PARTICLE_STRETCH.join(', ')});
 const WATER_PARTICLE_STRETCH_FIRST: f32 = ${WATER_PARTICLE_STRETCH_FIRST}.0;
+const WATER_PARTICLE_RUN_MEMBERS: u32 = ${WATER_PARTICLE_RUN_MEMBERS}u;
+const WATER_PARTICLE_RUN_OPEN_START: u32 = ${WATER_PARTICLE_RUN_OPEN_START}u;
+const WATER_PARTICLE_RUN_OPEN_END: u32 = ${WATER_PARTICLE_RUN_OPEN_END}u;
+const WATER_PARTICLE_LONE: u32 = ${WATER_PARTICLE_LONE}u;
 // kinematic viscosity of water, m²/s
 const WATER_VISCOSITY: f32 = 1e-6;
 const WATER_PI: f32 = 3.14159265358979;
@@ -153,38 +170,57 @@ fn water_particle_support_limit() -> f32 {
     return 0.5 * water_particle_cell_size(WATER_PARTICLE_LEVELS - 1u);
 }
 
-// Whether two particles are of one front: one splash's, neither reflected or faded apart, alike in all but angle.
-fn water_particle_same_front(a: ${WATER_PARTICLE_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> bool {
+// An angle as a turn from 0 round to 2π.
+fn water_particle_turn(angle: f32) -> f32 {
+    return angle - WATER_TAU * floor(angle / WATER_TAU);
+}
+
+// Where round its centre a front's particles are not neighbours: an angle of the front's own, from its centre, so that
+// fronts' ends lie anywhere rather than all to one side of them.
+fn water_particle_break(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    let bits = pcg3d(vec3<u32>(bitcast<u32>(particle.origin.x), bitcast<u32>(particle.origin.y), particle.body)).x;
+    return f32(bits >> 8u) * (WATER_TAU / 16777216.0);
+}
+
+// Whether two particles are of one front as it is drawn: one splash's, neither faded apart from the other, alike in all
+// but angle. A doom does not part them until the fade it starts does: what is drawn is all that links them.
+fn water_particle_alike(a: ${WATER_PARTICLE_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> bool {
     return a.body == b.body && all(a.origin == b.origin) && a.age == b.age && a.amplitude == b.amplitude
         && a.radius == b.radius && a.dispersion == b.dispersion;
 }
 
-// How a particle is drawn, given its front's run of particles in the array and its place in it: 1 as itself; 0 not at
-// all, or a group of 3^g as one packet with 3^g times its window, when its front is whole. Whole is every particle
-// the front split into still there, in order and alike: as many as fill its circle. The step puts a particle's three
-// in its place, the middle at its own angle, so a group of 3^g is 3^g in a row and its middle stands at the angle
-// the group was emitted at; with curved crests the groups draw what the particles do. The largest group whose packet
-// the hash holds: the seven a front was emitted as, until their windows outgrow the coarsest cell.
-fn water_particle_group(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, members: u32, offset: u32) -> u32 {
-    if (members != u32(round(WATER_TAU / particle.dispersion))) { return 1u; }
-    var group = 1u;
-    for (var g = 0u; g < 20u && members % (3u * group) == 0u; g++) { group *= 3u; }
-    let distance = water_particle_distance(particle);
-    let half_length = water_particle_half_length_at(particle.radius, distance);
-    for (var g = 0u; g < 20u && group > 1u; g++) {
-        let dispersion = particle.dispersion * f32(group);
-        let width = max(dispersion * distance, 1e-3 * particle.radius);
-        if (water_particle_support(half_length, width, dispersion) <= water_particle_support_limit()) { break; }
-        group /= 3u;
-    }
-    return select(0u, group, offset % group == group / 2u);
+// Whether b is a's neighbour round their front, β further on. Angles are compared as turns from the front's break, so
+// its particles either side of it are never neighbours and a run of them never closes on itself; that pair's windows sum
+// to one there as any unlinked pair's do.
+fn water_particle_linked(a: ${WATER_PARTICLE_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> bool {
+    if (!water_particle_alike(a, b)) { return false; }
+    let cut = water_particle_break(a);
+    return abs(water_particle_turn(b.angle - cut) - water_particle_turn(a.angle - cut) - a.dispersion) < 0.01 * a.dispersion;
 }
 
-// The particle as its group draws it: one packet with the group's window.
-fn water_particle_drawn(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, group: u32) -> ${WATER_PARTICLE_STRUCT.wgsl_ref} {
-    var drawn = particle;
-    drawn.dispersion *= f32(group);
-    return drawn;
+// A particle's window over x from its axis, |x| < β, and its derivative.
+fn water_particle_taper(x: f32, dispersion: f32) -> vec2<f32> {
+    let t = WATER_PI * x / dispersion;
+    return vec2<f32>(0.5 * (1.0 + cos(t)), -0.5 * WATER_PI / dispersion * sin(t));
+}
+
+// The angular profile of a run of a front's particles at ψ round the front's centre from its first particle's axis, and
+// its derivative: one from its first particle's axis to its last's, where the windows of neighbours β apart sum to one;
+// past an open end the end particle's own window, all there is of the front there; past an end with a neighbour, nothing,
+// since that neighbour's own run draws it there.
+fn water_particle_run_profile(psi: f32, dispersion: f32, run: u32) -> vec2<f32> {
+    let span = f32(max(run & WATER_PARTICLE_RUN_MEMBERS, 1u) - 1u) * dispersion;
+    let onward = water_particle_turn(psi);
+    if (onward <= span) { return vec2<f32>(1.0, 0.0); }
+    var profile = vec2<f32>(0.0);
+    if ((run & WATER_PARTICLE_RUN_OPEN_START) != 0u && psi < 0.0 && psi > -dispersion) {
+        profile += water_particle_taper(psi, dispersion);
+    }
+    let past = onward - span;
+    if ((run & WATER_PARTICLE_RUN_OPEN_END) != 0u && past < dispersion) {
+        profile += water_particle_taper(past, dispersion);
+    }
+    return profile;
 }
 
 // The smallest hash level whose cell is at least the support's diameter, so the support overlaps at most
@@ -220,13 +256,13 @@ struct WaterParticleField {
     displacement_gradient: vec2<f32>,
 }
 
-// The packet at offset d from its particle, which stands distance from its front's centre. ρ the radius from the
-// centre and u = ρ − distance across the front, ψ the angle around the centre from the particle's direction:
-// envelope E(u) over half_length either side, window T(ψ) over the dispersion β either side, carrier phase πu/r − phase.
-// Height a·E·T·cos; horizontal displacement −a·E·T·sin along the radius (Gerstner-like orbits, Yuksel's longitudinal
-// sign); with derivatives, ∇ψ = e_ψ/ρ.
-fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, half_length: f32, dispersion: f32, distance: f32,
-    phase: f32) -> WaterParticleField {
+// The run of a front's packets from the particle at offset d (water_particle_run_profile), which stands distance from
+// its front's centre. ρ the radius from the centre and u = ρ − distance across the front, ψ the angle around the centre
+// from the particle's direction: envelope E(u) over half_length either side, the run's profile T(ψ), carrier phase
+// πu/r − phase. Height a·E·T·cos; horizontal displacement −a·E·T·sin along the radius (Gerstner-like orbits, Yuksel's
+// longitudinal sign); with derivatives, ∇ψ = e_ψ/ρ.
+fn water_particle_run_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, half_length: f32, dispersion: f32, distance: f32,
+    phase: f32, run: u32) -> WaterParticleField {
     var field: WaterParticleField;
     let direction = water_particle_direction(angle);
     let tangent = vec2<f32>(-direction.y, direction.x);
@@ -236,15 +272,15 @@ fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, h
     let u = (dot(d, d) + 2.0 * distance * dot(d, direction)) / max(rho + distance, 1e-30);
     if (abs(u) >= half_length || !(rho > 0.0)) { return field; }
     let psi = atan2(dot(d, tangent), distance + dot(d, direction));
-    if (abs(psi) >= dispersion) { return field; }
+    let profile = water_particle_run_profile(psi, dispersion, run);
+    if (!(profile.x > 0.0)) { return field; }
     let radial = q / rho;
     let around = vec2<f32>(-radial.y, radial.x);
     let eu = WATER_PI * u / half_length;
     let envelope = 0.5 * (1.0 + cos(eu));
     let envelope_du = -0.5 * WATER_PI / half_length * sin(eu);
-    let tv = WATER_PI * psi / dispersion;
-    let window = 0.5 * (1.0 + cos(tv));
-    let window_dpsi = -0.5 * WATER_PI / dispersion * sin(tv);
+    let window = profile.x;
+    let window_dpsi = profile.y;
     let carrier = WATER_PI * u / radius - phase;
     let c = cos(carrier);
     let s = sin(carrier);
@@ -257,12 +293,18 @@ fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, h
     let h_psi = -amplitude * envelope * window_dpsi * s;
     let gradient_h = h_u * radial + (h_psi / rho) * around;
     // the radius turns as the point moves around the centre: ∂e_ρ/∂x_j = e_ψ (e_ψ)_j / ρ
-    let turn = (h / rho) * around;
+    let swing = (h / rho) * around;
     field.height = z;
     field.slope = z_u * radial + (z_psi / rho) * around;
     field.displacement = h * radial;
-    field.jacobian = mat2x2<f32>(radial * gradient_h.x + turn * around.x, radial * gradient_h.y + turn * around.y);
+    field.jacobian = mat2x2<f32>(radial * gradient_h.x + swing * around.x, radial * gradient_h.y + swing * around.y);
     field.displacement_gradient = gradient_h;
     return field;
 }
+
+// One particle's packet: a run of one, its window over the dispersion β either side of its axis.
+fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, half_length: f32, dispersion: f32, distance: f32,
+    phase: f32) -> WaterParticleField {
+    return water_particle_run_field(d, angle, amplitude, radius, half_length, dispersion, distance, phase, WATER_PARTICLE_LONE);
+}
 `, [chunk_water_spectrum, chunk_pcg3d, WATER_PARTICLE_STRUCT.declaration_chunk, WATER_PARTICLE_ENTRY_STRUCT.declaration_chunk]);

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

@@ -1,4 +1,7 @@
-/** Seconds over which a packet that has fallen below the drawing threshold fades to a tenth of it, where it dies. */
+/**
+ * Time constant of a dying packet's fade: one that has fallen below the drawing threshold fades to a tenth of it, where
+ * it dies, and one a crowd doomed to a tenth of its steepness then; about a third of a second either way.
+ */
 export const WATER_PARTICLE_FADE_SECONDS: 0.15;
 /**
  * One frame of one wave particle (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.1): it ages, spreads over its

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAQA,qHAAqH;AACrH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAsN8E;0BA9OvE,uCAAuC"}
+{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAuN8E;0BAlPvE,uCAAuC"}

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.js

@@ -6,7 +6,10 @@ import { RAY_HIT_INFO } from "../../../shader/chunk/geometry/ray/RAY_HIT_INFO.js
 import { WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
 import { chunk_water_particle } from "./chunk_water_particle.js";
 
-/** Seconds over which a packet that has fallen below the drawing threshold fades to a tenth of it, where it dies. */
+/**
+ * Time constant of a dying packet's fade: one that has fallen below the drawing threshold fades to a tenth of it, where
+ * it dies, and one a crowd doomed to a tenth of its steepness then; about a third of a second either way.
+ */
 export const WATER_PARTICLE_FADE_SECONDS = 0.15;
 
 /**
@@ -141,11 +144,12 @@ fn water_particle_advance(input: ${WATER_PARTICLE_STRUCT.wgsl_ref}, dt: f32, geo
     particle.amplitude *= sqrt(max(distance_before, 1e-30) / max(distance_after, 1e-30)
         * half_length_before / water_particle_half_length(particle)) * exp(-water_particle_damping(particle.radius) * dt);
     // below the threshold a packet fades out rather than vanishing: its amplitude decays on top of the water's own
-    // damping until it is a tenth of the threshold's height, where it dies
+    // damping until it is a tenth of the threshold's height, where it dies; and so does one a crowd doomed, until it is
+    // as steep as its doom says
     let floor = threshold * particle.radius;
-    if (!(abs(particle.amplitude) >= floor)) {
+    if (particle.fading > 0.0 || !(abs(particle.amplitude) >= floor)) {
         particle.amplitude *= exp(-dt / WATER_PARTICLE_FADE_SECONDS);
-        if (!(abs(particle.amplitude) >= 0.1 * floor)) { return WaterParticleStep(particle, particle, 0u); }
+        if (!(abs(particle.amplitude) >= max(0.1 * floor, particle.fading * particle.radius))) { return WaterParticleStep(particle, particle, 0u); }
     }
     // its support: its envelope's half-length either side of its front, its window's angle either side of its axis
     let reach = water_particle_half_length(particle);

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

@@ -11,45 +11,47 @@ 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 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_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;
+ * How many places along the array either side a particle looks for its front's neighbours. 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 — and a mirror image sits right after the packet it left, so a neighbour is a place or two away, a few where
+ * images split beside their packets. A pair further apart, as a ring's last and first are, is drawn as two runs whose
+ * windows meet, the same surface.
+ */
+export const WATER_PARTICLE_LINK_REACH: 8;
+/**
+ * Most particles one entry draws. A run ends where its neighbours' supports leave its cell. A cell is under four
+ * support radii s across, so the particles reaching it stand within a square of under 6s, and an arc of a circle inside a
+ * square of side L is at most about πL long; the step keeps a front's neighbours at least a third of their envelope's
+ * half-length h apart (they split at h), so s is at most ~3.2 of their spacing, and a cell holds at most ~62 of one
+ * front. A front closer set than the step leaves is drawn with a hole past this many.
+ */
+export const WATER_PARTICLE_RUN_LIMIT: 96;
+/**
+ * Steepness classes a cell counts its runs in: half octaves of |a|/r below 0.1, the steepest a splash makes, the last
+ * everything flatter. A run's class is its front's, the same in every cell it reaches. The cut pass reads a cell's
+ * classes and total as vectors, written out for ten (WaterParticleCrowd).
+ */
+export const WATER_PARTICLE_CROWD_BINS: 10;
+/** Words a bucket's crowd takes, as the weigh pass counts it: its runs by steepness class, then all of them. */
+export const WATER_PARTICLE_CROWD_WORDS: number;
+/**
+ * Words the nest, cut and mark passes keep per bucket: the most runs a point under it reads at finer levels and its own
+ * and the coarser ones; how many steepness classes its points keep, the steepest first, within
+ * {@link WATER_PARTICLE_CROWD_KEEP}, and within the gather budget; and a slot of the frame's table of cut fronts.
+ */
+export const WATER_PARTICLE_NEST_WORDS: 4;
+/** Slots of the cut fronts' table a front's tag is looked for in, from its own: at most an eighth of them hold one. */
+export const WATER_PARTICLE_FRONT_PROBES: 8;
+/**
+ * Runs a crowded point keeps: the steepest, class by class, as many as fit. A run a crowd cannot keep at any of its
+ * cells dooms its particles (WATER_PARTICLE_STRUCT's `fading`): they fade and die as packets below the drawing threshold
+ * do, so the weakest go first and nothing doomed comes back. The surface sampler's gather budget above this holds the
+ * doomed while they fade; a run past the budget itself, as where fresh fronts arrive faster than doomed ones fade, is
+ * cut: it is not drawn and dies at its next step, and so does all of its front, which a cut would otherwise leave in
+ * pieces no cell counted. The steepest class is always kept: a fresh splash is drawn, though points where more of those
+ * cross than the budget holds then lose some.
+ */
+export const WATER_PARTICLE_CROWD_KEEP: 48;
 /** 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. */
@@ -71,81 +73,91 @@ export const shader_water_particles_total: ComputeShader;
  * 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;
+/**
+ * Words the frame's clear writes per bucket of the table: its count, its largest |a|, its crowd and its nest, four to a
+ * thread (the table is a power of two of at least {@link WATER_PARTICLE_TABLE_MIN} buckets, so each array is whole vec4s).
+ */
+export const WATER_PARTICLE_CLEAR_WORDS: number;
 /**
  * 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}; and the command that clears
- * that much of the table, a thread a bucket.
+ * that much of the table, a thread every four words, folded.
  */
 export const shader_water_particles_finalize: ComputeShader;
 /**
- * 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.
+ * Clear the frame's table, as far as finalize sized it: each bucket's count, largest |a| and crowd, its points let keep
+ * and draw every steepness class until the cut pass says otherwise, and its slot of the cut fronts' table. A thread
+ * every four words, the words of each array in a row, so neighbouring threads write neighbouring words; a bucket's nest
+ * is its four. 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.
+ * Two words a particle: its front's neighbours β before and after it round the front (water_particle_linked), or none,
+ * from the particles {@link WATER_PARTICLE_LINK_REACH} places either side of it. A pair is linked from both ends or
+ * neither, so each draws the other's side of their meeting or neither does, and their windows sum to one. And three
+ * more: the cells its support overlaps, which every pass after reads rather than works out again.
  */
-export const shader_water_particles_fronts: ComputeShader;
+export const shader_water_particles_links: ComputeShader;
 /**
- * Two words a run: its first particle, and the share its crowd leaves it, none yet (the share pass lowers it).
+ * Each run of a body simulated this frame counted into every cell it is drawn in, by its steepness class
+ * ({@link WATER_PARTICLE_CROWD_WORDS}): how crowded the cell is, for the cut pass to keep its steepest by. And its level
+ * to its body's: a point reads a cell of every level its body has.
  */
-export const shader_water_particles_runs: ComputeShader;
+export const shader_water_particles_weigh: 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.
+ * Each run of a body simulated this frame, its cells weighed: the runs a point of the cell it is drawn in reads at that
+ * level and the coarser ones, raised onto the cell over it at every coarser level its body has, so a cell knows the most
+ * its points read where finer levels hold runs under it.
  */
-export const shader_water_particles_groups: ComputeShader;
+export const shader_water_particles_nest: 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.
+ * How many steepness classes each cell's points keep, the steepest first: as many as keep its most crowded point within
+ * {@link WATER_PARTICLE_CROWD_KEEP} runs, over its own cell and the coarser ones over it, class by class, and what finer
+ * levels add under it (the nest pass's most, less what its own and coarser cells hold), counted as the steepest, since a
+ * run sits finer the younger it is; and as many as keep it within the gather budget. Never fewer than one. Each run
+ * lowers its cell's bucket to what it finds.
  */
-export const shader_water_particles_weigh: ComputeShader;
+export const shader_water_particles_cut: ComputeShader;
 /**
- * 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.
+ * Each particle of a body simulated this frame whose steepness class some cell it reaches cannot draw within the gather
+ * budget, or that an earlier frame cut, puts its front's tag in the frame's table of cut fronts: the first free slot of
+ * {@link WATER_PARTICLE_FRONT_PROBES} from its front's own, or the one already holding it. Its front's particles are
+ * alike and β apart, so every one of them then finds the tag, and the front is cut whole.
  */
-export const shader_water_particles_nest: ComputeShader;
+export const shader_water_particles_mark: ComputeShader;
+/**
+ * What each crowd leaves of a body simulated this frame, particle by particle: a particle whose steepness class some
+ * cell it reaches does not keep is doomed, to fade from its next step and die (chunk_water_particle_step), and is drawn
+ * as it is until then; one whose front is in the frame's table of cut fronts (the mark pass) is not drawn, here or
+ * anywhere, and dies at its next step. So a crowd loses its flattest runs, and never by a lot or an order the particles
+ * arrive in. A frame that does not step decides the same again: nothing it reads has changed. One word a particle:
+ * whether it is drawn.
+ */
+export const shader_water_particles_keep: 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 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.
+ * Enter each drawn run of a body simulated this frame in every cell it is drawn in, by its first particle: 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, nor
+ * does one its crowd does not draw: nothing draws them this frame.
  */
 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. */
+/**
+ * Each run's entry to its bucket's range, in arrival order; the rank pass orders it. A run is its first particle and its
+ * front's drawn neighbours after it, one by one, while their supports overlap the cell, at most
+ * {@link WATER_PARTICLE_RUN_LIMIT}; an end is open where the front has no drawn neighbour beyond it.
+ */
 export const shader_water_particles_scatter: ComputeShader;
 /**
- * Order every bucket by particle index then cell, so a gather that runs out of budget drops the same
+ * Order every bucket by its runs' first particles then cells, so a gather that runs out of budget drops the same
  * entries every frame (the particle array keeps its order from frame to frame). A bucket of more than
  * ${WATER_PARTICLE_RANK_LIMIT} keeps its arrival order: a fixed budget of comparisons per entry.
  */
 export const shader_water_particles_rank: ComputeShader;
 /**
- * Each body's bound per level: the largest of count × max |a| over the buckets its particles are in, which is
- * at least the bucket's Σ|a|. Every particle that reaches a point is in that point's cell's bucket, and neither
- * its height nor its horizontal displacement exceeds |a|, so the bound holds everywhere; a hash collision only
- * adds to it.
+ * Each body's bound per level: the largest of count × max |a| over the buckets its runs are in, which is at least the
+ * bucket's Σ|a|. Every run that reaches a point is in that point's cell's bucket, and neither its height nor its
+ * horizontal displacement exceeds |a|, so the bound holds everywhere; a hash collision only adds to it.
  */
 export const shader_water_particles_bounds: ComputeShader;
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";

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":"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"}
+{"version":3,"file":"shader_water_particles.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/shader_water_particles.js"],"names":[],"mappings":"AA2BA,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;;;;;;GAMG;AACH,0CAA2C;AAE3C;;;;;;GAMG;AACH,0CAA2C;AAE3C;;;;GAIG;AACH,2CAA4C;AAE5C,gHAAgH;AAChH,gDAAwE;AAExE;;;;GAIG;AACH,0CAA2C;AAE3C,uHAAuH;AACvH,4CAA6C;AAE7C;;;;;;;;GAQG;AACH,2CAA4C;AAU5C,0DAA0D;AAC1D,sDAAqH;AAErH,kDAAkD;AAClD,wDAA0H;AAuF1H,0DACyB;AAUzB;;;;GAIG;AACH,yDA4B+E;AAQ/E,0EAA0E;AAC1E,yDAOiD;AAYjD;;;;;;GAMG;AACH,wDAyC0C;AAS1C;;;GAGG;AACH,gDAAqG;AAErG;;;;GAIG;AACH,4DAciD;AASjD;;;;;;GAMG;AACH,yDAkBsC;AAkHtC;;;;;GAKG;AACH,yDAwBkE;AAYlE;;;;GAIG;AACH,yDAqBsE;AAatE;;;;GAIG;AACH,wDAiCsE;AAatE;;;;;;GAMG;AACH,uDA6EsE;AAUtE;;;;;GAKG;AACH,wDA2BuE;AAWvE;;;;;;;GAOG;AACH,wDAiCuE;AA0BvE;;;;;GAKG;AACH,uDA6B4E;AAY5E;;;;GAIG;AACH,2DAsCuE;AAWvE;;;;GAIG;AACH,wDA8BuE;AAYvE;;;;GAIG;AACH,0DAqBuE;6BAl/B1C,sCAAsC;8BAJrC,kCAAkC"}