@woosh/meep-engine 3.21.0 → 3.23.0

package/src/shade/renderer/particles/sort/graph_particle_sort.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"graph_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/graph_particle_sort.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IAbqG,KAAK,EAA/F,OAAO,8DAA8D,EAAE,UAAU;IAClE,MAAM,EAArB,MAAM;IACS,gBAAgB,EAA/B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,KAAK,EAApB,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,aAAa,EAA5B,MAAM;IACS,QAAQ,EAAvB,MAAM;IACS,YAAY,EAA3B,MAAM;IACS,IAAI,EAAnB,MAAM;IACS,GAAG,EAAlB,MAAM;IACJ,MAAM,CA0ElB"}

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

@@ -1,130 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import { align_4 } from "../../../../core/binary/align_4.js";
-import { BufferResourceDescriptor } from "../../../device/graph/BufferResourceDescriptor.js";
-import { graph_prefix_scan_csdldf } from "../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
-import { PREFIX_SCAN_CSDLDF_HEADER_WORDS } from "../../gpu_primitive/prefix_sum/v1/shader_prefix_scan_csdldf.js";
-import { graph_compute_indirect_pass } from "../../shader/graph/compute/graph_compute_indirect_pass.js";
-import { graph_compute_pass } from "../../shader/graph/compute/graph_compute_pass.js";
-import {
-    PARTICLE_SORT_WORKGROUP_SIZE,
-    shader_particle_sort_histogram,
-    shader_particle_sort_reset,
-    shader_particle_sort_scatter,
-} from "./shader_particle_sort.js";
-
-const WORD = Uint32Array.BYTES_PER_ELEMENT;
-
-/**
- * Frame-graph wiring for the RENDER order: the frame's alive list quantised by view depth and
- * scattered back-to-front, for a draw whose blending is order-dependent.
- *
- * reset -> histogram -> csdldf scan -> scatter. The two per-particle passes are indirect, sized by
- * the same `sim_dispatch_args` the coherence reset wrote from the GPU's own alive count, so nothing
- * here is sized by a host-side particle count.
- *
- * ## Every buffer here is the graph's
- *
- * Nothing the sort touches outlives the frame — the reset zeroes the bins and cursors, and the two
- * per-particle lists are written for every entry the scatter goes on to read. So the pass that
- * first writes each one declares it (a {@link BufferResourceDescriptor} in place of a handle) and
- * the graph allocates it at that pass and releases it at its last reader, into the pool every other
- * feature draws from. Two of them are a word per particle: at the renderer's default capacity that
- * is 4 MiB the system would otherwise reserve for a mode it may never be drawn in.
- *
- * None of them asks for a clear. The reset pass covers the histogram (header, padding and the bins
- * up to the whole `vec4` the last one lands in) and the cursor; `keys` and `sorted` are written by
- * the same indirect dispatch that later reads them, entry for entry.
- *
- * This is the ONLY producer of a depth ordering, and only {@link ParticleRenderMode.BILLBOARD} runs
- * it. It must never be confused with the simulation order the coherence passes build (`coherence/`):
- * that one groups by VM program so a wave runs one program, is camera-independent, and lives in a
- * different buffer with a different counter slot. Depth-sorting it would destroy the coherence;
- * running the padded coherence list through a blended draw would draw its sentinels.
- *
- * @param {object} params
- * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} params.graph
- * @param {number} params.camera graph handle of the camera uniform buffer
- * @param {number} params.emitter_database graph handle
- * @param {number} params.pool graph handle of the particle pool
- * @param {number} params.alive graph handle of this frame's compacted alive list
- * @param {number} params.counters graph handle of the atomic counters
- * @param {number} params.dispatch_args graph handle of one workgroup per live particle
- * @param {number} params.capacity pool capacity in particles — the length of the two lists below
- * @param {number} params.bucket_count depth bins the sort quantises into
- * @param {number} params.near view depth the first bin starts at
- * @param {number} params.far view depth the last bin ends at
- * @returns {number} graph handle of the sorted slot list
- */
-export function graph_particle_sort({
-                                        graph,
-                                        camera,
-                                        emitter_database,
-                                        pool,
-                                        alive,
-                                        counters,
-                                        dispatch_args,
-                                        capacity,
-                                        bucket_count,
-                                        near,
-                                        far,
-                                    }) {
-    assert.isPositiveInteger(capacity, "capacity");
-    assert.isPositiveInteger(bucket_count, "bucket_count");
-
-    // The reset's widest loop is the scan header plus the bins rounded up to a whole vec4, and so
-    // is the buffer it clears.
-    const reset_words = PREFIX_SCAN_CSDLDF_HEADER_WORDS + align_4(bucket_count);
-
-    const LIST_DESCRIPTOR = BufferResourceDescriptor.from(capacity * WORD, GPUBufferUsage.STORAGE);
-
-    // Each pass below is handed a descriptor for the buffers it is the first to write, and a handle
-    // for everything else; `graph_compute_pass` creates the one and threads the other.
-    let histogram;
-    let cursor;
-    {
-        const out = graph_compute_pass({
-            graph,
-            shader: shader_particle_sort_reset,
-            bindings: {
-                histogram: BufferResourceDescriptor.from(reset_words * WORD, GPUBufferUsage.STORAGE),
-                cursor: BufferResourceDescriptor.from(bucket_count * WORD, GPUBufferUsage.STORAGE),
-                settings: { u_bucket_count: bucket_count },
-            },
-            group_count: [Math.ceil(reset_words / PARTICLE_SORT_WORKGROUP_SIZE), 1, 1],
-        });
-        histogram = out.histogram;
-        cursor = out.cursor;
-    }
-
-    // The counters are only read here, but an atomic read needs a read_write binding, and the
-    // graph sees a write — so the handle is threaded through like any other.
-    let keys;
-    {
-        const out = graph_compute_indirect_pass({
-            graph,
-            shader: shader_particle_sort_histogram,
-            bindings: {
-                camera, emitter_database, pool, alive, counters, histogram,
-                keys: LIST_DESCRIPTOR,
-                settings: { u_near: near, u_far: far, u_bucket_count: bucket_count },
-            },
-            command: dispatch_args,
-        });
-        keys = out.keys;
-        histogram = out.histogram;
-        counters = out.counters;
-    }
-
-    const scanned = graph_prefix_scan_csdldf({
-        graph,
-        data: histogram,
-        element_max_count: bucket_count,
-    });
-
-    return graph_compute_indirect_pass({
-        graph,
-        shader: shader_particle_sort_scatter,
-        bindings: { keys, alive, scanned, counters, cursor, sorted: LIST_DESCRIPTOR },
-        command: dispatch_args,
-    }).sorted;
-}

package/src/shade/renderer/particles/sort/particle_counting_sort.d.ts

@@ -1,26 +0,0 @@
-/**
- * CPU reference for the GPU depth sort — a bucketed counting sort. The GPU pipeline is exactly this
- * with the exclusive-offset step performed by the `csdldf` prefix scan:
- *
- *   histogram (atomic per bucket) -> csdldf scan -> scatter (exclusive offset + atomic rank).
- *
- * Particles are bucketed by view depth (far buckets first, so the result is back-to-front for
- * correct premultiplied transparency); order within a bucket is arbitrary but stable here.
- *
- * @param {ArrayLike<number>} buckets bucket index per item
- * @param {number} bucket_count number of buckets
- * @returns {number[]} item indices in sorted (ascending-bucket) order
- */
-export function particle_counting_sort(buckets: ArrayLike<number>, bucket_count: number): number[];
-/**
- * Quantise a view-space depth into a back-to-front bucket index. Far depths map to low buckets so
- * they are drawn first. Mirrors the WGSL in the histogram shader.
- *
- * @param {number} view_depth positive view-space depth (distance from camera)
- * @param {number} near
- * @param {number} far
- * @param {number} bucket_count
- * @returns {number}
- */
-export function particle_depth_bucket(view_depth: number, near: number, far: number, bucket_count: number): number;
-//# sourceMappingURL=particle_counting_sort.d.ts.map

package/src/shade/renderer/particles/sort/particle_counting_sort.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"particle_counting_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/particle_counting_sort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,gDAJW,UAAU,MAAM,CAAC,gBACjB,MAAM,GACJ,MAAM,EAAE,CAuBpB;AAED;;;;;;;;;GASG;AACH,kDANW,MAAM,QACN,MAAM,OACN,MAAM,gBACN,MAAM,GACJ,MAAM,CAMlB"}

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

@@ -1,51 +0,0 @@
-/**
- * CPU reference for the GPU depth sort — a bucketed counting sort. The GPU pipeline is exactly this
- * with the exclusive-offset step performed by the `csdldf` prefix scan:
- *
- *   histogram (atomic per bucket) -> csdldf scan -> scatter (exclusive offset + atomic rank).
- *
- * Particles are bucketed by view depth (far buckets first, so the result is back-to-front for
- * correct premultiplied transparency); order within a bucket is arbitrary but stable here.
- *
- * @param {ArrayLike<number>} buckets bucket index per item
- * @param {number} bucket_count number of buckets
- * @returns {number[]} item indices in sorted (ascending-bucket) order
- */
-export function particle_counting_sort(buckets, bucket_count) {
-    const histogram = new Array(bucket_count).fill(0);
-    for (let i = 0; i < buckets.length; i++) {
-        histogram[buckets[i]]++;
-    }
-
-    // Exclusive prefix sum -> per-bucket start offset (this is the csdldf step on the GPU).
-    const offset = new Array(bucket_count);
-    let acc = 0;
-    for (let b = 0; b < bucket_count; b++) {
-        offset[b] = acc;
-        acc += histogram[b];
-    }
-
-    const cursor = offset.slice();
-    const sorted = new Array(buckets.length);
-    for (let i = 0; i < buckets.length; i++) {
-        const b = buckets[i];
-        sorted[cursor[b]++] = i;
-    }
-    return sorted;
-}
-
-/**
- * Quantise a view-space depth into a back-to-front bucket index. Far depths map to low buckets so
- * they are drawn first. Mirrors the WGSL in the histogram shader.
- *
- * @param {number} view_depth positive view-space depth (distance from camera)
- * @param {number} near
- * @param {number} far
- * @param {number} bucket_count
- * @returns {number}
- */
-export function particle_depth_bucket(view_depth, near, far, bucket_count) {
-    const t = (view_depth - near) / Math.max(far - near, 1e-6);
-    const clamped = Math.min(Math.max(1 - t, 0), 1);
-    return Math.min(Math.floor(clamped * bucket_count), bucket_count - 1);
-}

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts

@@ -1,14 +0,0 @@
-export const PARTICLE_SORT_WORKGROUP_SIZE: 64;
-/**
- * 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;
-export const shader_particle_sort_histogram: ComputeShader;
-export const shader_particle_sort_scatter: ComputeShader;
-import { ComputeShader } from "../../shader/ComputeShader.js";
-//# sourceMappingURL=shader_particle_sort.d.ts.map

package/src/shade/renderer/particles/sort/shader_particle_sort.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shader_particle_sort.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/sort/shader_particle_sort.js"],"names":[],"mappings":"AAyDA,8CAA+C;AAgD/C;;;;;;;GAOG;AACH,yCAFU,aAAa,CAMpB;AAgEH,2DAIG;AAiCH,yDAIG;8BA3N2B,+BAA+B"}

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,
-});