@woosh/meep-engine 3.11.3 → 3.13.0

package/src/shade/renderer/particles/graph_particles.js

@@ -92,8 +92,10 @@ export function graph_particles({ graph, gpu, capacity, frame }) {
             bindings: {
                 emitters: gr_emitters, program: gr_program, vm_constants: gr_constants,
                 pool, spawn_requests: gr_spawn, alive_out: alive_write, dead, counters,
-                u_dt: frame.dt, u_time: frame.time, u_frame: frame.index,
-                u_count: frame.spawn_count, u_capacity: capacity,
+                settings: {
+                    u_dt: frame.dt, u_time: frame.time, u_frame: frame.index,
+                    u_count: frame.spawn_count, u_capacity: capacity,
+                },
             },
             group_count: [Math.ceil(frame.spawn_count / PARTICLE_EMIT_WORKGROUP_SIZE), 1, 1],
         });
@@ -111,7 +113,7 @@ export function graph_particles({ graph, gpu, capacity, frame }) {
             bindings: {
                 emitters: gr_emitters, program: gr_program, vm_constants: gr_constants,
                 pool, alive_in: gr_alive_read, alive_out: alive_write, dead, counters,
-                u_dt: frame.dt, u_time: frame.time, u_frame: frame.index,
+                settings: { u_dt: frame.dt, u_time: frame.time, u_frame: frame.index },
             },
             command: gr_dispatch,
         });

package/src/shade/renderer/particles/prototypeParticleSystem.js

@@ -50,7 +50,6 @@ import {
  */
 
 const CAPACITY = 1 << 15; // 32k particles
-const EMIT_WG = 64;
 const NEAR = 0.2;
 
 async function main() {
@@ -178,7 +177,6 @@ async function main() {
         if (requests.length > 0) device.queue.writeBuffer(spawnRequests, 0, requests);
 
         const cmd = ShadeGPUCommandContext.create(graphics);
-        const u = (type, value) => cmd.allocateTransientValueBuffer(type, value, GPUBufferUsage.UNIFORM);
         const colorView = context.getCurrentTexture().createView();
 
         // --- geometry pass: clear colour + reverse-Z depth (far = 0), lit, writes depth ---
@@ -195,21 +193,21 @@ async function main() {
         // --- emit + simulate (simulate is sized by LAST frame's GPU-written dispatch args) ---
         shader_particle_reset_counters.dispatch({ encoder: cmd, bindings: { counters }, group_count_x: 1 });
         if (requests.length > 0) {
-            shader_particle_emit.dispatch({
+            shader_particle_emit.dispatchThreads({
                 encoder: cmd,
-                bindings: { emitters, program, vm_constants: constants, pool, spawn_requests: spawnRequests, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame), u_count: u(u32, requests.length), u_capacity: u(u32, CAPACITY) },
-                group_count_x: Math.ceil(requests.length / EMIT_WG),
+                bindings: { emitters, program, vm_constants: constants, pool, spawn_requests: spawnRequests, alive_out: aliveWrite, dead, counters, settings: { u_dt: dt, u_time: now / 1000, u_frame: system.frame, u_count: requests.length, u_capacity: CAPACITY } },
+                thread_count_x: requests.length,
             });
         }
         shader_particle_simulate.dispatchIndirect({
             encoder: cmd,
-            bindings: { emitters, program, vm_constants: constants, pool, alive_in: aliveRead, alive_out: aliveWrite, dead, counters, u_dt: u(f32, dt), u_time: u(f32, now / 1000), u_frame: u(u32, system.frame) },
+            bindings: { emitters, program, vm_constants: constants, pool, alive_in: aliveRead, alive_out: aliveWrite, dead, counters, settings: { u_dt: dt, u_time: now / 1000, u_frame: system.frame } },
             command: dispatchArgs,
         });
         // Snapshot the final alive count (next frame's simulate input) + write this frame's draw args.
         shader_particle_build_indirect.dispatch({
             encoder: cmd,
-            bindings: { counters, dispatch_args: dispatchArgs, draw_args: drawArgs, u_workgroup_size: u(u32, PARTICLE_SIMULATE_WORKGROUP_SIZE) },
+            bindings: { counters, dispatch_args: dispatchArgs, draw_args: drawArgs, u_workgroup_size: PARTICLE_SIMULATE_WORKGROUP_SIZE },
             group_count_x: 1,
         });
 

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;GAYG;AAEH,2CAHU,aAAa,CAGwB;AA+E/C,iDAKG;8BAnH2B,+BAA+B"}
+{"version":3,"file":"shader_particle_emit.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_emit.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AAEH,2CAHU,aAAa,CAGwB;AA6F/C,iDAIG;8BAhI2B,+BAA+B"}

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

@@ -1,5 +1,6 @@
 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";
@@ -33,7 +34,27 @@ import { chunk_particle_context, chunk_particle_curve_disabled } from "./chunk_p
 
 export const PARTICLE_EMIT_WORKGROUP_SIZE = 64;
 
+/**
+ * Per-dispatch, 20 bytes, read-only.
+ *
+ * These were five separate uniforms, which meant five transient buffers, five staging copies and
+ * five bind group entries for twenty bytes of frame state. WGSL allows one immediate per entry
+ * point, so carrying them as immediate data means carrying them together.
+ *
+ * @type {WebGPUStruct}
+ */
+const EMIT_SETTINGS = WebGPUStruct.from({
+    u_dt: f32,
+    u_time: f32,
+    u_frame: u32,
+    u_count: u32,
+    u_capacity: u32,
+}, 'ParticleEmitSettings');
+
 const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate('settings', EMIT_SETTINGS);
+
 resources.createGroup()
     .addStorageBuffer("emitters", WebGPUArray.u32, false)
     .addStorageBuffer("program", WebGPUArray.u32, false)
@@ -42,13 +63,7 @@ resources.createGroup()
     .addStorageBuffer("spawn_requests", WebGPUArray.u32, false)
     .addStorageBuffer("alive_out", WebGPUArray.u32, true)
     .addStorageBuffer("dead", WebGPUArray.u32, true)
-    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true)
-    .addUniform("u_dt", f32)
-    .addUniform("u_time", f32)
-    .addUniform("u_frame", u32)
-    .addUniform("u_count", u32)
-    .addUniform("u_capacity", u32);
-
+    .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true);
 const body = CodeChunk.from(/* wgsl */ `
 const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
 const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
@@ -60,11 +75,11 @@ const COUNTER_DEAD : u32 = ${PARTICLE_COUNTER.DEAD}u;
 @compute @workgroup_size(${PARTICLE_EMIT_WORKGROUP_SIZE}, 1, 1)
 fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let i = gid.x;
-    if (i >= u_count) { return; }
+    if (i >= settings.u_count) { return; }
 
     // Packed request: low 16 bits = emitter index, high 16 = batch fraction (see
     // spawn_request_encoding.js). The fraction is LOCAL to this emitter's batch this frame
-    // (SPAWN_FRACTION contract: n / spawn_count), not the global request index / u_count.
+    // (SPAWN_FRACTION contract: n / spawn_count), not the global request index / settings.u_count.
     let request = spawn_requests[i];
     let emitter_index = request & ${SPAWN_REQUEST_EMITTER_MASK}u;
     let spawn_fraction = f32(request >> ${SPAWN_REQUEST_FRACTION_SHIFT}u) / ${SPAWN_REQUEST_FRACTION_MAX}.0;
@@ -75,10 +90,10 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     // first over-pop wraps the counter to 0xFFFFFFFF before its undo lands, and a concurrent thread
     // then observes a huge old value. Checking only ==0 would let it index dead[old-1] with garbage
     // and hand out a bogus slot, corrupting a live record. The dead count can never legitimately
-    // exceed the pool capacity, so >u_capacity identifies every wrapped state; each thread that
+    // exceed the pool capacity, so >settings.u_capacity identifies every wrapped state; each thread that
     // subtracted also adds back exactly once, so the counter converges to 0.
     let old_dead = atomicSub(&counters[COUNTER_DEAD], 1u);
-    if (old_dead == 0u || old_dead > u_capacity) {
+    if (old_dead == 0u || old_dead > settings.u_capacity) {
         atomicAdd(&counters[COUNTER_DEAD], 1u); // undo the over-pop
         return;
     }
@@ -94,7 +109,7 @@ fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
     let em = particle_emitter_read(&emitters, emitter_index);
 
     particle_vm_reset();
-    particle_setup_context(em, slot, u_dt, u_time, 0.0, spawn_fraction, u_frame);
+    particle_setup_context(em, slot, settings.u_dt, settings.u_time, 0.0, spawn_fraction, settings.u_frame);
     particle_vm_execute(
         &program,
         em.spawn_offset * PARTICLE_INSTRUCTION_WORDS,
@@ -114,5 +129,4 @@ export const shader_particle_emit = ComputeShader.from({
     label: "Particle Emit",
     resources,
     body,
-    group_size: [PARTICLE_EMIT_WORKGROUP_SIZE, 1, 1],
 });

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAYG;AAWH,2DAyBG;;8BA1E2B,+BAA+B;iDAIZ,+BAA+B"}
+{"version":3,"file":"shader_particle_finalize.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_finalize.js"],"names":[],"mappings":"AA4BA,2DAWG;AAaH,2DAwBG;;8BA1E2B,+BAA+B;iDAIZ,+BAA+B"}

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

@@ -37,17 +37,18 @@ fn main() {
     atomicStore(&counters[${PARTICLE_COUNTER.SORTED}u], 0u);
 }
 `),
-    group_size: [1, 1, 1],
 });
 
 // --- build indirect args ---
 
 const indirect_resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, four bytes, read-only: immediate data rather than a uniform buffer holding one u32
+indirect_resources.setImmediate("u_workgroup_size", u32);
 indirect_resources.createGroup()
     .addStorageBuffer("counters", WebGPUArray.from(atomic_u32), true) // atomics require a read_write binding even for atomicLoad
     .addStorageBuffer("dispatch_args", WebGPUArray.u32, true) // {x,y,z}
-    .addStorageBuffer("draw_args", WebGPUArray.u32, true)     // {vertexCount, instanceCount, firstVertex, firstInstance}
-    .addUniform("u_workgroup_size", u32);
+    .addStorageBuffer("draw_args", WebGPUArray.u32, true)     // {vertexCount, instanceCount, firstVertex, firstInstance};
 
 export const shader_particle_build_indirect = ComputeShader.from({
     label: "Particle Build Indirect",
@@ -73,7 +74,6 @@ fn main() {
     draw_args[3] = 0u;
 }
 `),
-    group_size: [1, 1, 1],
 });
 
 export { PARTICLE_SIMULATE_WORKGROUP_SIZE };

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AAqJA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CAsBpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCAtLb,iEAAiE;4CAO9D,sDAAsD"}
+{"version":3,"file":"shader_particle_render.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_render.js"],"names":[],"mappings":"AA6JA;;;;;;;;;GASG;AACH;IAP4B,YAAY,GAA7B,MAAM;IACgB,YAAY,GAAlC,MAAM,GAAC,IAAI;IAEkB,aAAa;IAExC,wBAAwB,CAqBpC;;;;;;;;;;;;;;;;AAED,yFAAyF;AACzF,uEAAsD;yCA7Lb,iEAAiE;4CAO9D,sDAAsD"}

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

@@ -1,183 +1,190 @@
-import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
-import { ColorTargetState } from "../../../descriptor/pipeline/render/ColorTargetState.js";
-import { DepthStencilState } from "../../../descriptor/pipeline/render/DepthStencilState.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
-import { ShaderDescriptor } from "../../shader/ShaderDescriptor.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, EMITTER_FLAG } from "../data/PARTICLE_EMITTER_LAYOUT.js";
-import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
-import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
-import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
-
-/**
- * The billboard renderer.
- *
- * One instanced draw covers every visible particle: `instance_index` indexes the depth-`sorted` slot
- * list, `vertex_index` (0..5) picks a quad corner. The vertex stage reads the particle's render-bound
- * attributes (position / size / colour / rotation / flipbook frame), expands the corner per the
- * emitter's projection mode, and projects with the camera. The fragment stage samples the atlas
- * sub-rect + flipbook cell, applies an optional soft-depth fade against the scene depth, runs the
- * pluggable lighting hook (unlit by default; the feature swaps in the shading-chunk-backed one when
- * an emitter enables lighting), and emits premultiplied colour.
- *
- * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
- * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
- * the whole draw stays GPU-driven with no pipeline switches.
- *
- * The math (billboard expansion, atlas/flipbook UV, soft fade, premultiply) is unit-tested in
- * {@link ./chunk_particle_render_math.spec.js}; this module assembles it into a render pipeline.
- */
-
-/** Premultiplied blend: additive when a=0 (dst preserved, colour adds), over-blend when a=srcAlpha. */
-export const PARTICLE_BILLBOARD_BLEND = {
-    color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-    alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
-};
-
-const resources = new ShaderResourceSetDescriptor();
-resources.createGroup()
-    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
-    .addStorageBuffer("pool", WebGPUArray.u32, false)
-    .addStorageBuffer("sorted", WebGPUArray.u32, false)
-    .addStorageBuffer("emitters", WebGPUArray.u32, false)
-    // Sampled with a filtering sampler, so the atlas must be a filterable float texture.
-    .addTexture("atlas", "float")
-    .addSampler("atlas_sampler", "filtering")
-    // Only textureLoad-ed (soft depth), so it can be unfilterable — matches an r32float scene depth.
-    .addTexture("scene_depth", "unfilterable-float");
-
-const 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;
-const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
-const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
-const PARTICLE_SOFT_FADE_RANGE : f32 = 0.5;
-
-struct ParticleVertexOut {
-    @builtin(position) clip : vec4<f32>,
-    @location(0) uv : vec2<f32>,
-    @location(1) color : vec4<f32>,
-    @location(2) world_position : vec3<f32>,
-    @location(3) normal : vec3<f32>,
-    @location(4) view_depth : f32,
-    @location(5) @interpolate(flat) flags : u32,
-    @location(6) @interpolate(flat) blend : u32,
-}
-
-fn particle_read_vec(base : u32, offset : u32, count : u32) -> vec4<f32> {
-    var v = vec4<f32>(0.0);
-    if (count > 0u) { v.x = bitcast<f32>(pool[base + offset]); }
-    if (count > 1u) { v.y = bitcast<f32>(pool[base + offset + 1u]); }
-    if (count > 2u) { v.z = bitcast<f32>(pool[base + offset + 2u]); }
-    if (count > 3u) { v.w = bitcast<f32>(pool[base + offset + 3u]); }
-    return v;
-}
-
-@vertex
-fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
-    var corners = array<vec2<f32>, 6>(
-        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
-        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(-1.0, 1.0),
-    );
-    let corner = corners[vi];
-
-    let slot = sorted[ii];
-    let base = slot * PARTICLE_RECORD_WORDS;
-    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
-    let em = particle_emitter_read(&emitters, emitter_index);
-
-    var world_center = vec3<f32>(0.0);
-    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
-    var size = 1.0;
-    if (em.render_size != PARTICLE_ATTRIBUTE_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
-    var color = vec4<f32>(1.0);
-    if (em.render_color != PARTICLE_ATTRIBUTE_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
-    var rotation = 0.0;
-    if (em.render_rotation != PARTICLE_ATTRIBUTE_ABSENT) { rotation = bitcast<f32>(pool[base + em.render_rotation]); }
-    var frame = 0.0;
-    if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
-    var velocity = vec3<f32>(0.0);
-    if (em.render_velocity != PARTICLE_ATTRIBUTE_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
-
-    let cam_right = camera.transform[0].xyz;
-    let cam_up = camera.transform[1].xyz;
-    let cam_forward = -camera.transform[2].xyz;
-
-    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, particle_emitter_projection(em.flags));
-    let world = world_center + offset;
-
-    var out : ParticleVertexOut;
-    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
-    out.uv = particle_atlas_uv(corner * 0.5 + vec2<f32>(0.5), em.atlas_region, em.flipbook, frame);
-    out.color = color;
-    out.world_position = world;
-    out.normal = -cam_forward;
-    out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
-    out.flags = em.flags;
-    out.blend = particle_emitter_blend(em.flags);
-    return out;
-}
-
-@fragment
-fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
-    let sampled = textureSample(atlas, atlas_sampler, in.uv);
-    var color = sampled * in.color;
-
-    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
-        let scene_dev = textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r;
-        // Reverse-Z hyperbolic linearisation: view_depth = A / (device_depth + B).
-        let A = camera.device_depth_to_view_space.y;
-        let B = camera.device_depth_to_view_space.x;
-        let scene_vd = select(A / (scene_dev + B), 1e9, scene_dev <= 0.0);
-        color.a = color.a * particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE);
-    }
-
-    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
-        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
-    }
-
-    return particle_premultiply(color, in.blend);
-}
-`, [chunk_particle_emitter, chunk_particle_render_math, chunk_particle_lighting_unlit]);
-
-/**
- * Build the billboard render pipeline descriptor.
- * @param {object} [options]
- * @param {string} [options.color_format] colour target format
- * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
- *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
- * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
- *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
- * @returns {RenderPipelineDescriptor}
- */
-export function create_particle_billboard_pipeline({ color_format = "rgba16float", depth_format = "depth32float", depth_compare = "greater" } = {}) {
-    const descriptor = ShaderDescriptor.from({ label: "Particle Billboard", body, resources });
-    const code = descriptor.compile();
-
-    return RenderPipelineDescriptor.from({
-        label: "Particle Billboard",
-        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
-        vertex: { module: { code }, entryPoint: "vs_main" },
-        fragment: {
-            module: { code },
-            entryPoint: "fs_main",
-            targets: [ColorTargetState.from({ format: color_format, blend: PARTICLE_BILLBOARD_BLEND })],
-        },
-        // Depth-test against the scene, but never write (transparent). Omitted entirely when no depth
-        // attachment is bound.
-        depthStencil: depth_format == null
-            ? undefined
-            : DepthStencilState.from({ format: depth_format, depthWriteEnabled: false, depthCompare: depth_compare }),
-        primitive: { topology: "triangle-list", cullMode: "none" },
-    });
-}
-
-/** The billboard shader's resource set (for building bind groups + the draw command). */
-export const PARTICLE_BILLBOARD_RESOURCES = resources;
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { ColorTargetState } from "../../../descriptor/pipeline/render/ColorTargetState.js";
+import { DepthStencilState } from "../../../descriptor/pipeline/render/DepthStencilState.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.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, EMITTER_FLAG } from "../data/PARTICLE_EMITTER_LAYOUT.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
+import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
+
+/**
+ * The billboard renderer.
+ *
+ * One instanced draw covers every visible particle: `instance_index` indexes the depth-`sorted` slot
+ * list, `vertex_index` (0..5) picks a quad corner. The vertex stage reads the particle's render-bound
+ * attributes (position / size / colour / rotation / flipbook frame), expands the corner per the
+ * emitter's projection mode, and projects with the camera. The fragment stage samples the atlas
+ * sub-rect + flipbook cell, applies an optional soft-depth fade against the scene depth, runs the
+ * pluggable lighting hook (unlit by default; the feature swaps in the shading-chunk-backed one when
+ * an emitter enables lighting), and emits premultiplied colour.
+ *
+ * A single blend state — `src*1 + dst*(1-srcAlpha)` on both channels — expresses alpha and additive
+ * blending; the shader chooses per particle by how it premultiplies (see `particle_premultiply`), so
+ * the whole draw stays GPU-driven with no pipeline switches.
+ *
+ * The math (billboard expansion, atlas/flipbook UV, soft fade, premultiply) is unit-tested in
+ * {@link ./chunk_particle_render_math.spec.js}; this module assembles it into a render pipeline.
+ */
+
+/** Premultiplied blend: additive when a=0 (dst preserved, colour adds), over-blend when a=srcAlpha. */
+export const PARTICLE_BILLBOARD_BLEND = {
+    color: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+    alpha: { operation: "add", srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+};
+
+const resources = new ShaderResourceSetDescriptor();
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("sorted", WebGPUArray.u32, false)
+    .addStorageBuffer("emitters", WebGPUArray.u32, false)
+    // Sampled with a filtering sampler, so the atlas must be a filterable float texture.
+    .addTexture("atlas", "float")
+    .addSampler("atlas_sampler", "filtering")
+    // Only textureLoad-ed (soft depth), so it can be unfilterable — matches an r32float scene depth.
+    .addTexture("scene_depth", "unfilterable-float");
+
+const 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;
+const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
+const PARTICLE_FLAG_LIGHTING : u32 = ${EMITTER_FLAG.LIGHTING}u;
+const PARTICLE_SOFT_FADE_RANGE : f32 = 0.5;
+
+struct ParticleVertexOut {
+    @builtin(position) clip : vec4<f32>,
+    @location(0) uv : vec2<f32>,
+    @location(1) color : vec4<f32>,
+    @location(2) world_position : vec3<f32>,
+    @location(3) normal : vec3<f32>,
+    @location(4) view_depth : f32,
+    @location(5) @interpolate(flat) flags : u32,
+    @location(6) @interpolate(flat) blend : u32,
+}
+
+fn particle_read_vec(base : u32, offset : u32, count : u32) -> vec4<f32> {
+    var v = vec4<f32>(0.0);
+    if (count > 0u) { v.x = bitcast<f32>(pool[base + offset]); }
+    if (count > 1u) { v.y = bitcast<f32>(pool[base + offset + 1u]); }
+    if (count > 2u) { v.z = bitcast<f32>(pool[base + offset + 2u]); }
+    if (count > 3u) { v.w = bitcast<f32>(pool[base + offset + 3u]); }
+    return v;
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
+    var corners = array<vec2<f32>, 6>(
+        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, -1.0), vec2<f32>(1.0, 1.0),
+        vec2<f32>(-1.0, -1.0), vec2<f32>(1.0, 1.0), vec2<f32>(-1.0, 1.0),
+    );
+    let corner = corners[vi];
+
+    let slot = sorted[ii];
+    let base = slot * PARTICLE_RECORD_WORDS;
+    let emitter_index = pool[base + PARTICLE_HEADER_EMITTER];
+    let em = particle_emitter_read(&emitters, emitter_index);
+
+    var world_center = vec3<f32>(0.0);
+    if (em.render_position != PARTICLE_ATTRIBUTE_ABSENT) { world_center = particle_read_vec(base, em.render_position, 3u).xyz; }
+    var size = 1.0;
+    if (em.render_size != PARTICLE_ATTRIBUTE_ABSENT) { size = bitcast<f32>(pool[base + em.render_size]); }
+    var color = vec4<f32>(1.0);
+    if (em.render_color != PARTICLE_ATTRIBUTE_ABSENT) { color = particle_read_vec(base, em.render_color, 4u); }
+    var rotation = 0.0;
+    if (em.render_rotation != PARTICLE_ATTRIBUTE_ABSENT) { rotation = bitcast<f32>(pool[base + em.render_rotation]); }
+    var frame = 0.0;
+    if (em.render_frame != PARTICLE_ATTRIBUTE_ABSENT) { frame = bitcast<f32>(pool[base + em.render_frame]); }
+    var velocity = vec3<f32>(0.0);
+    if (em.render_velocity != PARTICLE_ATTRIBUTE_ABSENT) { velocity = particle_read_vec(base, em.render_velocity, 3u).xyz; }
+
+    let cam_right = camera.transform[0].xyz;
+    let cam_up = camera.transform[1].xyz;
+    let cam_forward = -camera.transform[2].xyz;
+
+    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, particle_emitter_projection(em.flags));
+    let world = world_center + offset;
+
+    var out : ParticleVertexOut;
+    out.clip = camera.view_projection_matrix * vec4<f32>(world, 1.0);
+    out.uv = particle_atlas_uv(corner * 0.5 + vec2<f32>(0.5), em.atlas_region, em.flipbook, frame);
+    out.color = color;
+    out.world_position = world;
+    out.normal = -cam_forward;
+    out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
+    out.flags = em.flags;
+    out.blend = particle_emitter_blend(em.flags);
+    return out;
+}
+
+@fragment
+fn fs_main(in : ParticleVertexOut) -> @location(0) vec4<f32> {
+    let sampled = textureSample(atlas, atlas_sampler, in.uv);
+    var color = sampled * in.color;
+
+    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
+        let scene_dev = textureLoad(scene_depth, vec2<i32>(in.clip.xy), 0).r;
+        // Reverse-Z hyperbolic linearisation: view_depth = A / (device_depth + B).
+        let A = camera.device_depth_to_view_space.y;
+        let B = camera.device_depth_to_view_space.x;
+        let scene_vd = select(A / (scene_dev + B), 1e9, scene_dev <= 0.0);
+        color.a = color.a * particle_soft_fade(scene_vd, in.view_depth, PARTICLE_SOFT_FADE_RANGE);
+    }
+
+    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
+        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
+    }
+
+    return particle_premultiply(color, in.blend);
+}
+`, [chunk_particle_emitter, chunk_particle_render_math, chunk_particle_lighting_unlit]);
+
+/**
+ * The shader itself. One compilation, shared by every pipeline built from it — the options below
+ * vary the pipeline state, never the WGSL.
+ *
+ * @type {ShaderDescriptor}
+ */
+const descriptor = ShaderDescriptor.from({ label: "Particle Billboard", body, resources });
+
+/**
+ * Build the billboard render pipeline descriptor.
+ * @param {object} [options]
+ * @param {string} [options.color_format] colour target format
+ * @param {string|null} [options.depth_format] scene depth format (test-only, no write); pass null to
+ *   render without a depth attachment (e.g. an additive-only prototype with no scene geometry)
+ * @param {GPUCompareFunction} [options.depth_compare] depth test — "greater"/"greater-equal" for
+ *   reverse-Z scenes (the engine convention), "less"/"less-equal" for a standard-Z scene
+ * @returns {RenderPipelineDescriptor}
+ */
+export function create_particle_billboard_pipeline({ color_format = "rgba16float", depth_format = "depth32float", depth_compare = "greater" } = {}) {
+    const code = descriptor.source;
+
+    return RenderPipelineDescriptor.from({
+        label: "Particle Billboard",
+        layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+        vertex: { module: { code }, entryPoint: "vs_main" },
+        fragment: {
+            module: { code },
+            entryPoint: "fs_main",
+            targets: [ColorTargetState.from({ format: color_format, blend: PARTICLE_BILLBOARD_BLEND })],
+        },
+        // Depth-test against the scene, but never write (transparent). Omitted entirely when no depth
+        // attachment is bound.
+        depthStencil: depth_format == null
+            ? undefined
+            : DepthStencilState.from({ format: depth_format, depthWriteEnabled: false, depthCompare: depth_compare }),
+        primitive: { topology: "triangle-list", cullMode: "none" },
+    });
+}
+
+/** The billboard shader's resource set (for building bind groups + the draw command). */
+export const PARTICLE_BILLBOARD_RESOURCES = resources;

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

@@ -1 +1 @@
-{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AA0DnD,qDAKG;8BAjG2B,+BAA+B"}
+{"version":3,"file":"shader_particle_simulate.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_simulate.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,+CAHU,aAAa,CAG4B;AAqEnD,qDAIG;8BA3G2B,+BAA+B"}