@woosh/meep-engine 3.40.0 → 3.42.0

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

@@ -0,0 +1,121 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { BVH_TRAVERSAL_STACK_SIZE } from "../../../shader/chunk/bvh/BVH_TRAVERSAL_STACK_SIZE.js";
+import { chunk_ray_query_blas_nearest } from "../../../shader/chunk/geometry/ray/chunk_ray_query_blas_nearest.js";
+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. */
+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
+ * widening front, damps, reflects off its body's authored outline, and dies or splits.
+ *
+ * Whether a point is over the body is a down-ray into the body's own BLAS, so the outline is exactly the
+ * authored mesh's, holes for islands included. Bindings: `geometries`, `blas_lookup`, `blas_data`,
+ * `meshlet_metadata`, `meshlet_data`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_particle_step = CodeChunk.from(/* language=WGSL */ `
+const WATER_PARTICLE_FADE_SECONDS: f32 = ${WATER_PARTICLE_FADE_SECONDS};
+
+struct WaterParticleStep {
+    particle: ${WATER_PARTICLE_STRUCT.wgsl_ref},
+    // 0 dies, 1 lives on, 3 splits into three
+    children: u32,
+}
+
+// The body's surface under a point of its local xz, or a miss (t < 0) off its outline.
+fn water_particle_over_body(geometry_index: u32, local: vec2<f32>) -> ${RAY_HIT_INFO.wgsl_ref} {
+    let box = geometries[geometry_index].bounding_box;
+    let margin = max(1e-3, (box[4] - box[1]) * 1e-4);
+    let top = box[4] + margin;
+    var stack: array<u32, ${BVH_TRAVERSAL_STACK_SIZE}>;
+    return ray_query_blas_nearest(Ray(vec3<f32>(local.x, top, local.y), vec3<f32>(0.0, -1.0, 0.0),
+        top - box[1] + margin), geometry_index, &stack, 0u);
+}
+
+// The line of the edge of a triangle nearest a point inside it, in the metric xz frame: a point on it and a
+// unit normal. Which side the normal points to does not matter: a mirror in a line is the same for either.
+struct WaterOutlineLine {
+    point: vec2<f32>,
+    normal: vec2<f32>,
+}
+
+fn water_outline_line(geometry_index: u32, triangle: u32, point: vec2<f32>, scale: vec2<f32>) -> WaterOutlineLine {
+    let vertices = geometry_read_triangle_vertices(geometries[geometry_index], triangle);
+    let corners = array<vec2<f32>, 3>(vertices.a.position.xz * scale, vertices.b.position.xz * scale, vertices.c.position.xz * scale);
+    var nearest = 3.0e38;
+    var line = WaterOutlineLine(point, vec2<f32>(0.0));
+    for (var edge = 0u; edge < 3u; edge++) {
+        let p = corners[edge];
+        let along = corners[(edge + 1u) % 3u] - p;
+        let t = clamp(dot(point - p, along) / max(dot(along, along), 1e-30), 0.0, 1.0);
+        let gap = length(point - (p + t * along));
+        if (gap < nearest) {
+            nearest = gap;
+            line = WaterOutlineLine(p, normalize(vec2<f32>(along.y, -along.x)));
+        }
+    }
+    return line;
+}
+
+// Advance a particle by dt. scale turns the body's metric frame into its local one; reflection is the
+// outline's amplitude reflection coefficient; threshold is the steepness |a|/r below which it dies.
+fn water_particle_advance(input: ${WATER_PARTICLE_STRUCT.wgsl_ref}, dt: f32, geometry_index: u32, scale: vec2<f32>,
+    reflection: f32, threshold: f32) -> WaterParticleStep {
+    var particle = input;
+    let before = water_particle_position(particle);
+    let distance_before = water_particle_distance(particle);
+    particle.age += dt;
+    let distance_after = water_particle_distance(particle);
+    // energy spread over the widening circumference, and the water's own damping
+    particle.amplitude *= sqrt(max(distance_before, 1e-30) / max(distance_after, 1e-30))
+        * exp(-water_particle_damping(particle.radius) * dt);
+    let after = water_particle_position(particle);
+    if (water_particle_over_body(geometry_index, after / scale).t < 0.0) {
+        let start = water_particle_over_body(geometry_index, before / scale);
+        if (!(reflection > 0.0) || start.t < 0.0) { return WaterParticleStep(particle, 0u); }
+        // where along this frame's step it left the mesh
+        var lo = 0.0;
+        var hi = 1.0;
+        var last = start;
+        for (var halving = 0u; halving < 6u; halving++) {
+            let mid = 0.5 * (lo + hi);
+            let probe = water_particle_over_body(geometry_index, mix(before, after, mid) / scale);
+            if (probe.t >= 0.0) { lo = mid; last = probe; } else { hi = mid; }
+        }
+        // the mirror image of its front in the outline's own line, wherever along the step it was crossed
+        let line = water_outline_line(geometry_index, last.triangle, mix(before, after, lo), scale);
+        let normal = line.normal;
+        let direction = water_particle_direction(particle.angle);
+        let reflected = direction - 2.0 * dot(direction, normal) * normal;
+        particle.origin -= 2.0 * dot(particle.origin - line.point, normal) * normal;
+        particle.angle = atan2(reflected.y, reflected.x);
+        particle.amplitude *= reflection;
+        // a corner can send the mirror image off the mesh too
+        if (water_particle_over_body(geometry_index, water_particle_position(particle) / scale).t < 0.0) {
+            return WaterParticleStep(particle, 0u);
+        }
+    }
+    // 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
+    let floor = threshold * particle.radius;
+    if (!(abs(particle.amplitude) >= floor)) {
+        particle.amplitude *= exp(-dt / WATER_PARTICLE_FADE_SECONDS);
+        if (!(abs(particle.amplitude) >= 0.1 * floor)) { return WaterParticleStep(particle, 0u); }
+    }
+    // Yuksel's subdivision, at a coarser spacing: the window along the front keeps its height
+    if (water_particle_width(particle) > 2.0 * particle.radius) { return WaterParticleStep(particle, 3u); }
+    return WaterParticleStep(particle, 1u);
+}
+
+// The death threshold: a packet flatter than the body's own wind waves is not drawn, and the fuller the pool,
+// the steeper a packet must be to stay.
+fn water_particle_threshold(slope_variance: f32, live: u32, capacity: u32) -> f32 {
+    let pressure = f32(live) / f32(max(capacity, 1u));
+    return max(0.003, 0.1 * sqrt(max(slope_variance, 0.0))) / max(1.0 - pressure, 0.05);
+}
+`, [chunk_water_particle, chunk_ray_query_blas_nearest]);

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

@@ -0,0 +1,83 @@
+/** A particle array with its live count in front, as the indirect commands read it. */
+export const WATER_PARTICLE_ARRAY_STRUCT: WebGPUStruct;
+/** The same array where emitters append by an atomic count. */
+export const WATER_PARTICLE_ARRAY_APPEND_STRUCT: WebGPUStruct;
+/** Bucket counts while binning: the table size in front, atomic counters behind. */
+export const WATER_PARTICLE_BUCKETS_STRUCT: WebGPUStruct;
+/** Smallest hash table, so an idle frame scans little. */
+export const WATER_PARTICLE_TABLE_MIN: 1024;
+/** Bucket entries one particle can take: the 2×2 cells its support overlaps. */
+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.
+ */
+export const WATER_PARTICLE_CELL_SHARE: 16;
+/** 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.
+ */
+export const shader_water_particles_split: ComputeShader;
+/** The next array's count: everything the scan placed, up to capacity. */
+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
+ * 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}.
+ */
+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.
+ */
+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.
+ *
+ * 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.
+ */
+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. */
+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
+ * 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.
+ */
+export const shader_water_particles_bounds: ComputeShader;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_water_particles.d.ts.map

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

@@ -0,0 +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"}