@woosh/meep-engine 3.20.0 → 3.22.0

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

@@ -1,223 +0,0 @@
-import { atomic_u32, f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { ComputeShader } from "../../shader/ComputeShader.js";
-import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
-import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
-import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.js";
-import { PARTICLE_COUNTER } from "../data/PARTICLE_COUNTERS.js";
-import { EMITTER_ATTRIBUTE_ABSENT } from "../data/PARTICLE_EMITTER_STRUCT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-import { chunk_particle_header } from "../data/particle_header.js";
-
-/**
- * Depth-sort shaders. Three passes bracket a `csdldf` prefix scan:
- *
- * 0. {@link shader_particle_sort_reset} — every frame, write the histogram's `{count, elements}`
- *    header (the bucket count the csdldf scan sizes itself from), clear the header padding and the
- *    bins, and zero 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 buffer the four passes share
- *
- * The histogram IS the scan's `{count: u32, elements: array<vec4u>}`, bound flat here as
- * `array<atomic<u32>>` because these passes need atomics on it. `elements` is `@align(16)`, so bin
- * `b` is word {@link PREFIX_SCAN_CSDLDF_HEADER_WORDS}` + b` and words 1..3 are padding the scan
- * never reads. Every pass below steps over that header by hand; the reset clears whole vec4s of
- * bins, because whole vec4s is what the scan loads.
- *
- * ## This is the render order
- *
- * The camera-dependent back-to-front list the billboard draw consumes. `../coherence/` produces the
- * simulation order from the same three-phase shape — different buffers, different passes, different
- * counter slots (`PARTICLE_COUNTER.SORTED` against `PARTICLE_COUNTER.SIM_PADDED`), on purpose.
- *
- * 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.
- */
-
-/** @type {number} words of `{count, elements}` header in front of the scan's bins */
-const HEADER = PREFIX_SCAN_CSDLDF_HEADER_WORDS;
-
-/** The header stride every pass in this file interpolates. */
-const COMMON = /* wgsl */ `
-const SORT_HEADER_WORDS : u32 = ${HEADER}u;
-`;
-
-export const PARTICLE_SORT_WORKGROUP_SIZE = 64;
-
-// --- reset pass ---
-
-/**
- * Per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer.
- *
- * @type {WebGPUStruct}
- */
-const SORT_RESET_SETTINGS = WebGPUStruct.from({
-    u_bucket_count: u32,
-}, 'ParticleSortResetSettings');
-
-const reset_resources = new ShaderResourceSetDescriptor();
-
-reset_resources.setImmediate('settings', SORT_RESET_SETTINGS);
-reset_resources.createGroup()
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true);
-const reset_body = CodeChunk.from(/* wgsl */ `
-${COMMON}
-
-@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], settings.u_bucket_count);
-    }
-
-    // Header padding: never read by the scan, but it shares the buffer and the pool may have left
-    // something in it.
-    if (i > 0u && i < SORT_HEADER_WORDS) {
-        atomicStore(&histogram[i], 0u);
-    }
-
-    // The scan reads whole vec4s, so the bins are cleared up to the vec4 the last one lands in.
-    if (i < ((settings.u_bucket_count + 3u) & 0xfffffffcu)) {
-        atomicStore(&histogram[SORT_HEADER_WORDS + i], 0u);
-    }
-
-    if (i < settings.u_bucket_count) {
-        atomicStore(&cursor[i], 0u);
-    }
-}
-`);
-
-/**
- * Dispatch this over `PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count)` threads, not over
- * `bucket_count`: its widest loop is the scan header plus the bins rounded up to the whole vec4 the
- * last bin lands in. Under-dispatching leaves the tail of that vec4 holding last frame's counts,
- * and the scan adds them in.
- *
- * @type {ComputeShader}
- */
-export const shader_particle_sort_reset = ComputeShader.from({
-    label: "Particle Sort Reset",
-    resources: reset_resources,
-    body: reset_body,
-});
-
-// --- histogram pass ---
-
-/**
- * Per-dispatch, 12 bytes, read-only. Separate uniforms meant a transient buffer each per sort;
- * WGSL allows one immediate per entry point, so they travel together.
- *
- * The particle count is NOT here: it is the alive counter the simulate pass finished writing on
- * the GPU, read from the counters buffer. A host-supplied count would be last frame's.
- *
- * @type {WebGPUStruct}
- */
-const SORT_HISTOGRAM_SETTINGS = WebGPUStruct.from({
-    u_near: f32,
-    u_far: f32,
-    u_bucket_count: u32,
-}, 'ParticleSortHistogramSettings');
-
-const histogram_resources = new ShaderResourceSetDescriptor();
-
-histogram_resources.setImmediate('settings', SORT_HISTOGRAM_SETTINGS);
-histogram_resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("alive", WebGPUArray.u32, false)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
-    .addStorageBuffer("keys", WebGPUArray.u32, true)
-    .addStorageBuffer("histogram", WebGPUArray.from(atomic_u32), true);
-const histogram_body = CodeChunk.from(/* wgsl */ `
-${COMMON}
-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;
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
-
-    let slot = alive[i];
-    let base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = particle_header_emitter(pool[base + PARTICLE_HEADER_EMITTER]);
-    let em = particle_emitter_read(&emitter_database, 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_depth = -(camera.view_matrix * vec4<f32>(world_pos, 1.0)).z;
-
-    let t = (view_depth - settings.u_near) / max(settings.u_far - settings.u_near, 1e-6);
-    let clamped = clamp(1.0 - t, 0.0, 1.0);
-    let bucket = min(u32(clamped * f32(settings.u_bucket_count)), settings.u_bucket_count - 1u);
-
-    keys[i] = bucket;
-    atomicAdd(&histogram[SORT_HEADER_WORDS + bucket], 1u);
-}
-`, [chunk_particle_emitter, chunk_particle_header]);
-
-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("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
-    .addStorageBuffer("cursor", WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer("sorted", WebGPUArray.u32, true);
-const scatter_body = CodeChunk.from(/* wgsl */ `
-${COMMON}
-const COUNTER_ALIVE : u32 = ${PARTICLE_COUNTER.ALIVE}u;
-
-@compute @workgroup_size(${PARTICLE_SORT_WORKGROUP_SIZE}, 1, 1)
-fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
-    let i = gid.x;
-    if (i >= atomicLoad(&counters[COUNTER_ALIVE])) { return; }
-
-    let bucket = keys[i];
-
-    // The scan is inclusive, so bucket b's exclusive offset is bucket b-1's inclusive value, one
-    // word earlier. For bucket 0 the index lands on the last header word — in bounds, and unused,
-    // because select() takes the 0 branch there.
-    let exclusive = select(0u, scanned[SORT_HEADER_WORDS + bucket - 1u], 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,
-});