@woosh/meep-engine 3.11.2 → 3.12.0

package/src/shade/renderer/particles/sort/shader_particle_sort.js

@@ -1,161 +1,158 @@
-import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-
-/**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
- *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
- *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
- *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
- * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
- *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
- *    `keys`, and atomically bump the per-bucket `histogram`.
- * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
- * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
- *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
- *    into `sorted` at that position.
- *
- * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
- * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
- * algorithm.
- */
-
-export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
-
-// --- reset pass ---
-
-const reset_resources = new ShaderResourceSetDescriptor();
-reset_resources.createGroup()
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_bucket_count", u32);
-
-const reset_body = CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i == 0u) {
-        // The {count, elements} header the csdldf scan sizes itself from.
-        atomicStore(&histogram[0], u_bucket_count);
-    }
-    if (i < u_bucket_count) {
-        atomicStore(&histogram[1u + i], 0u);
-        atomicStore(&cursor[i], 0u);
-    }
-}
-`);
-
-export const shader_particle_sort_reset = ComputeShader.from({
-    label: "Particle Sort Reset",
-    resources: reset_resources,
-    body: reset_body,
-    group_size: [PARTICLE_SORT_WORKGROUP_SIZE, 1, 1],
-});
-
-const READ_MAT4 = /* wgsl */ `
-fn particle_read_mat4(m : ptr<storage, array<u32>, read>, o : u32) -> mat4x4<f32> {
-    return mat4x4<f32>(
-        vec4<f32>(bitcast<f32>((*m)[o + 0u]), bitcast<f32>((*m)[o + 1u]), bitcast<f32>((*m)[o + 2u]), bitcast<f32>((*m)[o + 3u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 4u]), bitcast<f32>((*m)[o + 5u]), bitcast<f32>((*m)[o + 6u]), bitcast<f32>((*m)[o + 7u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 8u]), bitcast<f32>((*m)[o + 9u]), bitcast<f32>((*m)[o + 10u]), bitcast<f32>((*m)[o + 11u])),
-        vec4<f32>(bitcast<f32>((*m)[o + 12u]), bitcast<f32>((*m)[o + 13u]), bitcast<f32>((*m)[o + 14u]), bitcast<f32>((*m)[o + 15u])),
-    );
-}
-`;
-
-// --- histogram pass ---
-
-const histogram_resources = new ShaderResourceSetDescriptor();
-histogram_resources.createGroup()
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("view_matrix", WebGPUArray.u32, false)
-    .addStorageBuffer("keys", WebGPUArray.u32, true)
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_near", f32)
-    .addUniform("u_far", f32)
-    .addUniform("u_bucket_count", u32)
-    .addUniform("u_count", u32);
-
-const histogram_body = CodeChunk.from(/* wgsl */ `
-const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
-const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
-const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
-
-${READ_MAT4}
-
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= u_count) { return; }
-
-    let slot = alive[i];
-    let base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    var world_pos = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) {
-        let o = base + em.render_position;
-        world_pos = vec3<f32>(bitcast<f32>(pool[o]), bitcast<f32>(pool[o + 1u]), bitcast<f32>(pool[o + 2u]));
-    }
-
-    let view = particle_read_mat4(&view_matrix, 0u);
-    let view_depth = -(view * vec4<f32>(world_pos, 1.0)).z;
-
-    let t = (view_depth - u_near) / max(u_far - u_near, 1e-6);
-    let clamped = clamp(1.0 - t, 0.0, 1.0);
-    let bucket = min(u32(clamped * f32(u_bucket_count)), u_bucket_count - 1u);
-
-    keys[i] = bucket;
-    atomicAdd(&histogram[1u + bucket], 1u);
-}
-`, [chunk_particle_emitter]);
-
-export const shader_particle_sort_histogram = ComputeShader.from({
-    label: "Particle Sort Histogram",
-    resources: histogram_resources,
-    body: histogram_body,
-    group_size: [PARTICLE_SORT_WORKGROUP_SIZE, 1, 1],
-});
-
-// --- scatter pass ---
-
-const scatter_resources = new ShaderResourceSetDescriptor();
-scatter_resources.createGroup()
-    .addStorageBuffer("keys", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("scanned", WebGPUArray.u32, false)
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("sorted", WebGPUArray.u32, true)
-    .addUniform("u_count", u32);
-
-const scatter_body = CodeChunk.from(/* wgsl */ `
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= u_count) { return; }
-
-    let bucket = keys[i];
-    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
-    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
-    let exclusive = select(0u, scanned[bucket], bucket > 0u);
-    let rank = atomicAdd(&cursor[bucket], 1u);
-    sorted[exclusive + rank] = alive[i];
-}
-`);
-
-export const shader_particle_sort_scatter = ComputeShader.from({
-    label: "Particle Sort Scatter",
-    resources: scatter_resources,
-    body: scatter_body,
-    group_size: [PARTICLE_SORT_WORKGROUP_SIZE, 1, 1],
-});
+import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
+import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+
+/**
+ * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
+ *
+ * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count}` field
+ *    (= bucket count, which the csdldf scan reads to size itself) and zero the histogram bins and
+ *    the scatter cursor. Without this the scan consumes garbage counts and the scatter compounds
+ *    last frame's ranks — the buffers are only zeroed by WebGPU on CREATION, not per frame.
+ * 1. {@link shader_particle_sort_histogram} — per alive particle, project its render position into
+ *    view space, quantise the depth into a back-to-front bucket (far first), store the bucket in
+ *    `keys`, and atomically bump the per-bucket `histogram`.
+ * 2. graph_prefix_scan_csdldf turns the histogram into inclusive prefix sums.
+ * 3. {@link shader_particle_sort_scatter} — per particle, read its bucket, take the exclusive
+ *    offset from the scanned histogram and an atomic per-bucket rank, and write the particle's slot
+ *    into `sorted` at that position.
+ *
+ * The `csdldf` scan uses subgroup ops and isn't runnable under the emulator; the reset, histogram
+ * and scatter passes are, and the CPU reference {@link ./particle_counting_sort.js} pins the
+ * algorithm.
+ */
+
+export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
+
+// --- reset pass ---
+
+const reset_resources = new ShaderResourceSetDescriptor();
+reset_resources.createGroup()
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addUniform("u_bucket_count", u32);
+
+const reset_body = CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i == 0u) {
+        // The {count, elements} header the csdldf scan sizes itself from.
+        atomicStore(&histogram[0], u_bucket_count);
+    }
+    if (i < u_bucket_count) {
+        atomicStore(&histogram[1u + i], 0u);
+        atomicStore(&cursor[i], 0u);
+    }
+}
+`);
+
+export const shader_particle_sort_reset = ComputeShader.from({
+    label: "Particle Sort Reset",
+    resources: reset_resources,
+    body: reset_body,
+});
+
+const READ_MAT4 = /* wgsl */ `
+fn particle_read_mat4(m : ptr<storage, array<u32>, read>, o : u32) -> mat4x4<f32> {
+    return mat4x4<f32>(
+        vec4<f32>(bitcast<f32>((*m)[o + 0u]), bitcast<f32>((*m)[o + 1u]), bitcast<f32>((*m)[o + 2u]), bitcast<f32>((*m)[o + 3u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 4u]), bitcast<f32>((*m)[o + 5u]), bitcast<f32>((*m)[o + 6u]), bitcast<f32>((*m)[o + 7u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 8u]), bitcast<f32>((*m)[o + 9u]), bitcast<f32>((*m)[o + 10u]), bitcast<f32>((*m)[o + 11u])),
+        vec4<f32>(bitcast<f32>((*m)[o + 12u]), bitcast<f32>((*m)[o + 13u]), bitcast<f32>((*m)[o + 14u]), bitcast<f32>((*m)[o + 15u])),
+    );
+}
+`;
+
+// --- histogram pass ---
+
+const histogram_resources = new ShaderResourceSetDescriptor();
+histogram_resources.createGroup()
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("view_matrix", WebGPUArray.u32, false)
+    .addStorageBuffer("keys", WebGPUArray.u32, true)
+    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
+    .addUniform("u_near", f32)
+    .addUniform("u_far", f32)
+    .addUniform("u_bucket_count", u32)
+    .addUniform("u_count", u32);
+
+const histogram_body = CodeChunk.from(/* wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_ATTRIBUTE_ABSENT : u32 = ${EMITTER_ATTRIBUTE_ABSENT}u;
+
+${READ_MAT4}
+
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= u_count) { return; }
+
+    let slot = alive[i];
+    let base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
+    let em = particle_emitter_read(&emitters, emitter_index);
+
+    var world_pos = vec3<f32>(0.0);
+    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) {
+        let o = base + em.render_position;
+        world_pos = vec3<f32>(bitcast<f32>(pool[o]), bitcast<f32>(pool[o + 1u]), bitcast<f32>(pool[o + 2u]));
+    }
+
+    let view = particle_read_mat4(&view_matrix, 0u);
+    let view_depth = -(view * vec4<f32>(world_pos, 1.0)).z;
+
+    let t = (view_depth - u_near) / max(u_far - u_near, 1e-6);
+    let clamped = clamp(1.0 - t, 0.0, 1.0);
+    let bucket = min(u32(clamped * f32(u_bucket_count)), u_bucket_count - 1u);
+
+    keys[i] = bucket;
+    atomicAdd(&histogram[1u + bucket], 1u);
+}
+`, [chunk_particle_emitter]);
+
+export const shader_particle_sort_histogram = ComputeShader.from({
+    label: "Particle Sort Histogram",
+    resources: histogram_resources,
+    body: histogram_body,
+});
+
+// --- scatter pass ---
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+scatter_resources.createGroup()
+    .addStorageBuffer("keys", WebGPUArray.u32, false)
+    .addStorageBuffer("alive", WebGPUArray.u32, false)
+    .addStorageBuffer("scanned", WebGPUArray.u32, false)
+    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("sorted", WebGPUArray.u32, true)
+    .addUniform("u_count", u32);
+
+const scatter_body = CodeChunk.from(/* wgsl */ `
+@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+    let i = gid.x;
+    if (i >= u_count) { return; }
+
+    let bucket = keys[i];
+    // Exclusive offset = inclusive prefix sum up to bucket-1. With the count field at index 0 the
+    // scanned inclusive value for bucket b lives at index (1+b), so bucket b-1 is at index b.
+    let exclusive = select(0u, scanned[bucket], bucket > 0u);
+    let rank = atomicAdd(&cursor[bucket], 1u);
+    sorted[exclusive + rank] = alive[i];
+}
+`);
+
+export const shader_particle_sort_scatter = ComputeShader.from({
+    label: "Particle Sort Scatter",
+    resources: scatter_resources,
+    body: scatter_body,
+});