@woosh/meep-engine 3.17.1 → 3.18.0

package/src/shade/renderer/particles/shaders/chunk_particle_emitter_warmup.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How many seconds of simulation this frame's newborns of an emitter owe before they may be shown,
+ * as the tick pass left it this frame.
+ *
+ * Zero on all but one frame of an emitter's life. The tick writes the emitter's `prewarm` here on
+ * the row's first tick and zero on every tick after, so a newborn asks this rather than asking the
+ * record's `prewarm` directly: the record says how long the emitter wants pre-warming *for*, and
+ * only the tick knows *whether this is that frame* — it is the generation comparison, and by the
+ * time the emit pass runs the tick has already made the two generations agree.
+ *
+ * Read off the `emitter_state` table of the same database the emitter record came from
+ * ({@link ../data/PARTICLE_EMITTER_STATE.js}), through the table's single-field reader, exactly as
+ * {@link ./chunk_particle_emitter_age.js} reads the age beside it — one binding for both, and no
+ * second copy of the row layout here to drift from the table's.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_warmup: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emitter_warmup.d.ts.map

package/src/shade/renderer/particles/shaders/chunk_particle_emitter_warmup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_emitter_warmup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_emitter_warmup.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,4CAFU,SAAS,CAMgD;0BAxBzC,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.d.ts

@@ -4,6 +4,10 @@
  *
  * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
  *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
+ *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
+ *   pass: the two are one statement, and they drift the moment they are written apart.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CA2FhB;0BA3GuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCAFU,SAAS,CA2HhB;0BA/IuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_render_math.js

@@ -7,6 +7,10 @@ import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_STRU
  *
  * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
  *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
+ *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
+ *   pass: the two are one statement, and they drift the moment they are written apart.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.
@@ -75,6 +79,32 @@ fn particle_billboard_offset(
     return (right * rc.x + up * rc.y) * size;
 }
 
+// The radius of the sphere holding every offset particle_billboard_offset can return for a particle
+// of this size, velocity and projection — over all four corners, every roll angle, and any camera.
+//
+// A corner is (±1, ±1), so a rolled corner \`rc\` has |rc| = sqrt(2) whatever the angle: rotation
+// moves a corner around the quad's circumcircle, it does not shrink it. Every mode then lays \`rc\`
+// down on two orthonormal axes and scales by \`size\`, which makes |offset| = sqrt(2) * size exactly
+// — camera-facing, ground-aligned, axis-locked and world-facing alike, because "which two unit
+// axes" is the only thing that separates them.
+//
+// STRETCHED is the one that reaches further: it elongates the corner along the screen-space
+// velocity by (1 + |v_screen|) before the same two axes. |v_screen| is a projection of the world
+// velocity onto two orthonormal axes and so is at most |v|, which is what makes the world-space
+// speed the camera-independent bound this needs to be.
+//
+// Camera-independent is the requirement, not a nicety: the box this feeds is measured over one
+// frame and read on the next, by which time the camera has moved.
+fn particle_billboard_radius(size : f32, velocity_ws : vec3<f32>, projection : u32) -> f32 {
+    var stretch = 0.0;
+
+    if (projection == PARTICLE_PROJ_STRETCHED) {
+        stretch = length(velocity_ws);
+    }
+
+    return abs(size) * 1.4142135623730951 * (1.0 + stretch);
+}
+
 // Map a local quad uv (0..1) into an atlas sub-rect + flipbook cell.
 fn particle_atlas_uv(local_uv : vec2<f32>, region : vec4<f32>, flipbook : vec2<f32>, frame : f32) -> vec2<f32> {
     let cols = max(flipbook.x, 1.0);
@@ -90,10 +120,16 @@ fn particle_atlas_uv(local_uv : vec2<f32>, region : vec4<f32>, flipbook : vec2<f
 
 // Soft-particle fade: 0 when the particle is at/behind the scene surface, ramping to 1 across
 // fade_range in view-space units. A non-positive scene depth means background (no fade).
-fn particle_soft_fade(scene_view_depth : f32, particle_view_depth : f32, fade_range : f32) -> f32 {
+fn particle_soft_fade(scene_view_depth : f32, particle_view_depth : f32, fade_range : f32) -> f32 {
     if (scene_view_depth <= 0.0) { return 1.0; }
     return smoothstep(0.0, max(fade_range, 1e-4), scene_view_depth - particle_view_depth);
-}
+}
+
+// Premultiplied RGB already includes coverage, so fading it must scale both parts of the pair.
+fn particle_fade_color(color : vec4<f32>, blend : u32, fade : f32) -> vec4<f32> {
+    if (blend == PARTICLE_BLEND_PREMULTIPLIED) { return color * fade; }
+    return vec4<f32>(color.rgb, color.a * fade);
+}
 
 // Produce the premultiplied colour the single blend pipeline expects.
 fn particle_premultiply(color : vec4<f32>, blend : u32) -> vec4<f32> {

package/src/shade/renderer/particles/shaders/chunk_particle_spawn_budget.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Take up to `wanted` particles from a frame's spawn budget, returning what was actually granted.
+ *
+ * The budget is `counters[SPAWN_BUDGET]`, seeded from the free count by whichever reset pass opened
+ * the frame, so an emitter is only ever debited for particles the pool can hold. Many rows race the
+ * counter, and the shape of the race is the dead-list pop's ({@link ./chunk_particle_emit_step.js}):
+ * a thread that drives it below zero sees an old value smaller than its request and keeps only that
+ * much; one that reads while another's over-subtraction is still un-undone sees a wrapped (huge)
+ * value and keeps nothing. Each adds back exactly what it did not keep, so the counter converges to
+ * zero rather than to garbage.
+ *
+ * A chunk because two ticks spend the budget the same way — the emitter tick over the live table
+ * ({@link ./shader_particle_emitter_tick.js}) and the warm-up tick over its queue
+ * (`../warmup/shader_particle_warmup.js`) — and the second must not be a second copy of the first's
+ * wrap guard. It names the `counters` binding directly, as every counter-touching chunk in this
+ * directory does: an atomic array behind a pointer parameter is a shape nothing in the engine uses.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_spawn_budget: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_spawn_budget.d.ts.map

package/src/shade/renderer/particles/shaders/chunk_particle_spawn_budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_spawn_budget.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_spawn_budget.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0CAFU,SAAS,CAqBhB;0BAzCuB,oCAAoC"}

package/src/shade/renderer/particles/shaders/chunk_particle_spawn_budget.js

@@ -0,0 +1,42 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
+
+/**
+ * Take up to `wanted` particles from a frame's spawn budget, returning what was actually granted.
+ *
+ * The budget is `counters[SPAWN_BUDGET]`, seeded from the free count by whichever reset pass opened
+ * the frame, so an emitter is only ever debited for particles the pool can hold. Many rows race the
+ * counter, and the shape of the race is the dead-list pop's ({@link ./chunk_particle_emit_step.js}):
+ * a thread that drives it below zero sees an old value smaller than its request and keeps only that
+ * much; one that reads while another's over-subtraction is still un-undone sees a wrapped (huge)
+ * value and keeps nothing. Each adds back exactly what it did not keep, so the counter converges to
+ * zero rather than to garbage.
+ *
+ * A chunk because two ticks spend the budget the same way — the emitter tick over the live table
+ * ({@link ./shader_particle_emitter_tick.js}) and the warm-up tick over its queue
+ * (`../warmup/shader_particle_warmup.js`) — and the second must not be a second copy of the first's
+ * wrap guard. It names the `counters` binding directly, as every counter-touching chunk in this
+ * directory does: an atomic array behind a pointer parameter is a shape nothing in the engine uses.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_spawn_budget = CodeChunk.from(/* language=wgsl */ `
+const COUNTER_SPAWN_BUDGET : u32 = ${PARTICLE_COUNTER.SPAWN_BUDGET}u;
+
+fn particle_take_spawn_budget(wanted : u32, capacity : u32) -> u32 {
+    let old = atomicSub(&counters[COUNTER_SPAWN_BUDGET], wanted);
+
+    var granted = wanted;
+    if (old > capacity) {
+        granted = 0u;
+    } else if (old < wanted) {
+        granted = old;
+    }
+
+    if (granted != wanted) {
+        atomicAdd(&counters[COUNTER_SPAWN_BUDGET], wanted - granted);
+    }
+
+    return granted;
+}
+`);

package/src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js

@@ -97,7 +97,7 @@ fn fs_main(in : ParticleVertexOut) -> ParticleAVBOITDrawOutput {
 
     if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
         let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r, camera);
-        color.a = color.a * particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE);
+        color = particle_fade_color(color, in.blend, particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE));
     }
 
     if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {

package/src/shade/renderer/particles/shaders/shader_particle_avboit_occupancy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_avboit_occupancy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_occupancy.js"],"names":[],"mappings":"AAuHA,6DAIG;8BAlH2B,+BAA+B"}
+{"version":3,"file":"shader_particle_avboit_occupancy.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_occupancy.js"],"names":[],"mappings":"AAsJA,6DAIG;8BAjJ2B,+BAA+B"}

package/src/shade/renderer/particles/shaders/shader_particle_avboit_occupancy.js

@@ -6,30 +6,37 @@ import { AVBOIT_OCCUPANCY_WORDS, AVBOIT_VIRTUAL_SLICES_MAX } from "../../rasteri
 import { chunk_avboit_occupancy_range } from "../../rasterize/native/avboit/chunk_avboit_occupancy_range.js";
 import { chunk_avboit_occupancy_word_mask } from "../../rasterize/native/avboit/chunk_avboit_occupancy_word_mask.js";
 import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../../rasterize/native/avboit/shader_avboit_occupancy.js";
-import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { AABB3_STRUCT } from "../../shader/chunk/geometry/aabb3/AABB3_STRUCT.js";
 import { ComputeShader } from "../../shader/ComputeShader.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
 import { PARTICLE_EMITTER_TICK_WORKGROUP_SIZE } from "../ParticleConstants.js";
-import { PARTICLE_EMITTER_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_EMITTER_DESCRIPTOR, PARTICLE_EMITTER_STATE_DESCRIPTOR } from "../data/PARTICLE_DATABASE_SPEC.js";
 import { EMITTER_BLEND } from "../data/PARTICLE_EMITTER_STRUCT.js";
-import { chunk_particle_emitter_world_sphere } from "./chunk_particle_emitter_world_sphere.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_bounds_unknown } from "../bounds/chunk_particle_bounds_unknown.js";
 
 /**
  * The particles' AVBOIT occupancy: one thread per emitter table row, marking the virtual depth
- * slices the emitter's bounds sphere spans, so the warp keeps resolution where the particles are.
+ * slices the emitter's bounding box spans, so the warp keeps resolution where the particles are.
  * The particle counterpart of `shader_avboit_occupancy`, which does the same per meshlet AABB.
  *
- * Per emitter rather than per particle: the sphere is the bound the author gave the emitter (the
- * one the tick culls with), it is one thread per row instead of one per live particle contending
- * for the same few words, and a particle that strays past it is not lost — it lands on the
- * boundary of the nearest run, the warp's flat-in-a-gap property. Emitters that only add light
- * (`EMITTER_BLEND.ADDITIVE`) splat no extinction and mark nothing: a slice reserved for them would
- * be a slice the surfaces do not get.
+ * Per emitter rather than per particle: the box is the one the bounds passes measured from the
+ * particles ({@link ../data/PARTICLE_EMITTER_STATE.js}), it is one thread per row instead of one
+ * per live particle contending for the same few words, and a particle that strays past it is not
+ * lost — it lands on the boundary of the nearest run, the warp's flat-in-a-gap property. Emitters
+ * that only add light (`EMITTER_BLEND.ADDITIVE`) splat no extinction and mark nothing: a slice
+ * reserved for them would be a slice the surfaces do not get.
  *
- * The sphere goes to view space through the node's `global`; the camera looks down −Z, so the
- * depth interval is `[-(c.z) - r, -(c.z) + r]`, clamped at the near plane, through the same depth
- * curve and dilation the meshlet pass uses.
+ * The box is already in world space — it was measured from world-space particles, dilated to hold
+ * their quads — so all that is left is its view-depth interval, which is its centre's depth plus or
+ * minus the box's extent along the view axis. That is a support-function projection, not eight
+ * transformed corners: the box is axis-aligned in world space and only its extent along one axis is
+ * wanted. The camera looks down −Z, so the interval is clamped at the near plane and mapped through
+ * the same depth curve and dilation the meshlet pass uses.
+ *
+ * The box is published by this frame's bounds pass after emit and simulate. The next tick will cull
+ * against that same measurement. An infinite box means no measured population and marks nothing.
  *
  * Walks the table with its page iterator, read-only: the rows are the tick's output of this frame.
  *
@@ -39,13 +46,13 @@ import { chunk_particle_emitter_world_sphere } from "./chunk_particle_emitter_wo
 const GROUP_SIZE = PARTICLE_EMITTER_TICK_WORKGROUP_SIZE;
 
 const PG = PARTICLE_EMITTER_DESCRIPTOR.page_iterator_symbol_prefix(GROUP_SIZE);
+const STATE = PARTICLE_EMITTER_STATE_DESCRIPTOR;
 
 const resources = new ShaderResourceSetDescriptor();
 
 resources.createGroup()
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)
     .addUniform("settings", AVBOIT_OCCUPANCY_SETTINGS_STRUCT)
-    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
     .addStorageBuffer("emitter_database", WebGPUArray.from(u32))
     .addStorageBuffer("occupancy", WebGPUArray.from(atomic_u32, AVBOIT_OCCUPANCY_WORDS), true);
 
@@ -54,6 +61,27 @@ const body = CodeChunk.from(
     `
 const PARTICLE_BLEND_ADDITIVE : u32 = ${EMITTER_BLEND.ADDITIVE}u;
 
+// The view-space depth interval of a world-space box: the centre's depth, plus or minus the box's
+// extent along the view axis. \`view_axis\` is the view matrix's third ROW — read as the z of the
+// transformed basis vectors rather than as matrix columns, the same numbers in the form the WGSL
+// emulator also evaluates.
+fn particle_emitter_view_depth_range(box : ${AABB3_STRUCT.wgsl_ref}, view : mat4x4<f32>) -> vec2<f32> {
+    let center = (box.min + box.max) * 0.5;
+    let half_extent = (box.max - box.min) * 0.5;
+
+    let view_axis = vec3<f32>(
+        (view * vec4<f32>(1.0, 0.0, 0.0, 0.0)).z,
+        (view * vec4<f32>(0.0, 1.0, 0.0, 0.0)).z,
+        (view * vec4<f32>(0.0, 0.0, 1.0, 0.0)).z,
+    );
+
+    // camera looks down -Z, so depth is -z
+    let depth = -(view * vec4<f32>(center, 1.0)).z;
+    let extent = dot(abs(view_axis), half_extent);
+
+    return vec2<f32>(depth - extent, depth + extent);
+}
+
 @compute @workgroup_size(${GROUP_SIZE}, 1, 1)
 fn main(
     @builtin(workgroup_id) wg_id : vec3<u32>,
@@ -77,14 +105,15 @@ fn main(
         return;
     }
 
-    let node = scene_read_node(&scene_database, em.node);
-    let sphere = particle_emitter_world_sphere(em, node.global);
+    let state = ${STATE.marshalling_method_read}(&emitter_database, ${PG}_slot_to_index(slot_in_page));
+    // Unknown bounds have no live particles to splat; do not reserve the whole depth volume.
+    if (particle_bounds_unknown(state.bounds_min)) { return; }
+    let box = ${AABB3_STRUCT.make({ min: "state.bounds_min", max: "state.bounds_max" })};
 
-    let center_view = (camera.view_matrix * vec4<f32>(sphere.xyz, 1.0)).xyz;
+    let range_view = particle_emitter_view_depth_range(box, camera.view_matrix);
 
-    // camera looks down -Z
-    let depth_min = -center_view.z - sphere.w;
-    let depth_max = -center_view.z + sphere.w;
+    let depth_min = range_view.x;
+    let depth_max = range_view.y;
 
     if (depth_max < camera.clip_near_far.x) {
         // entirely in front of the near plane
@@ -109,8 +138,10 @@ fn main(
 }
     `, [
         PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(GROUP_SIZE),
-        chunk_particle_emitter_world_sphere,
-        chunk_scene_database_access,
+        chunk_particle_emitter,
+        chunk_particle_bounds_unknown,
+        STATE.chunk_read,
+        AABB3_STRUCT.declaration_chunk,
         chunk_cluster_depth_to_z_slice,
         chunk_avboit_occupancy_range,
         chunk_avboit_occupancy_word_mask,

package/src/shade/renderer/particles/shaders/shader_particle_emitter_tick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emitter_tick.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emitter_tick.js"],"names":[],"mappings":"AAiNA,yDAIG;;8BA5M2B,+BAA+B;qDAGR,yBAAyB"}
+{"version":3,"file":"shader_particle_emitter_tick.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emitter_tick.js"],"names":[],"mappings":"AA8MA,yDAIG;;8BAzM2B,+BAA+B;qDAGR,yBAAyB"}