@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1,18 @@
+/**
+ * The opaque scene's view-space depth behind a particle fragment, for the soft fade.
+ *
+ * The linearization is the engine's own (`get_view_space_depth`); what this adds is the reverse-Z
+ * background case. A device depth at or below zero is the cleared far plane — nothing opaque was
+ * drawn on that pixel — and dividing by it would put the scene *in front of* the particle and fade
+ * it out against empty space. Far away is the honest answer, so the fade returns 1 there.
+ *
+ * Shared by the AVBOIT splat and the AVBOIT draw so that the coverage the volume records and the
+ * coverage the accumulators are weighted by are the same number. They were not, before: the draw
+ * faded and the splat did not, so a card fading out where it met the floor still wrote full
+ * extinction there and darkened the floor through itself along the seam it exists to remove.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_scene_view_depth: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_scene_view_depth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_scene_view_depth.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_scene_view_depth.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,8CAFU,SAAS,CAMc;0BArBP,oCAAoC"}

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

@@ -0,0 +1,24 @@
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_get_view_space_depth } from "../../shader/chunk/depth/chunk_get_view_space_depth.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * The opaque scene's view-space depth behind a particle fragment, for the soft fade.
+ *
+ * The linearization is the engine's own (`get_view_space_depth`); what this adds is the reverse-Z
+ * background case. A device depth at or below zero is the cleared far plane — nothing opaque was
+ * drawn on that pixel — and dividing by it would put the scene *in front of* the particle and fade
+ * it out against empty space. Far away is the honest answer, so the fade returns 1 there.
+ *
+ * Shared by the AVBOIT splat and the AVBOIT draw so that the coverage the volume records and the
+ * coverage the accumulators are weighted by are the same number. They were not, before: the draw
+ * faded and the splat did not, so a card fading out where it met the floor still wrote full
+ * extinction there and darkened the floor through itself along the seam it exists to remove.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_scene_view_depth = CodeChunk.from(/* language=wgsl */ `
+fn particle_scene_view_depth(device_depth : f32, camera : ${CAMERA_UNIFORM_STRUCT.wgsl_ref}) -> f32 {
+    return select(get_view_space_depth(device_depth, camera), 1e9, device_depth <= 0.0);
+}
+`, [chunk_get_view_space_depth]);

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

@@ -0,0 +1,26 @@
+/**
+ * Populates the VM's builtin context and seeds its RNG for one particle before a program section
+ * runs.
+ *
+ * The emitter's world position / direction / up come from its scene node — the `global` of its row
+ * in the scene database's `transforms` table, which the GPU hierarchy pass composed this frame from
+ * the node's own transform and its parents'. An emitter parented to an animated joint therefore
+ * spawns and simulates where the joint is *now*, with nothing copied through the CPU: the joint's
+ * pose was written by the animation passes and composed by the hierarchy pass, and this reads the
+ * result. The caller fetches the node with `scene_read_node(&scene_database, em.node)`, and the age
+ * with {@link ./chunk_particle_emitter_age.js}.
+ *
+ * The RNG seed is `hash_lowbias32_vec3u` over (emitter seed, slot, frame) — the engine's house
+ * hash, not a private one. It only has to be well mixed, since `random()` does the real work from
+ * here, and `rnd_state` feeds a PCG whose LCG step has a nonzero increment, so no seed value
+ * (zero included) is degenerate.
+ *
+ * Depends on {@link chunk_particle_vm} (owns `vm_ctx`, and pulls in the shared `rnd_state`),
+ * {@link chunk_particle_emitter} (the `ParticleEmitter` struct) and
+ * {@link chunk_scene_database_access} (the node struct + reader).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_setup_context: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_setup_context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_setup_context.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_setup_context.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,2CAFU,SAAS,CA8BhB;0BA1DuB,oCAAoC"}

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

@@ -0,0 +1,59 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_hash_lowbias32_vec3u } from "../../shader/chunk/random/lowbias/chunk_hash_lowbias32_vec3u.js";
+import { NODE3D_STRUCT } from "../../scene/NODE3D_STRUCT.js";
+import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
+import { chunk_particle_emitter } from "../data/chunk_particle_emitter.js";
+import { chunk_particle_vm } from "../vm/chunk_particle_vm.js";
+
+/**
+ * Populates the VM's builtin context and seeds its RNG for one particle before a program section
+ * runs.
+ *
+ * The emitter's world position / direction / up come from its scene node — the `global` of its row
+ * in the scene database's `transforms` table, which the GPU hierarchy pass composed this frame from
+ * the node's own transform and its parents'. An emitter parented to an animated joint therefore
+ * spawns and simulates where the joint is *now*, with nothing copied through the CPU: the joint's
+ * pose was written by the animation passes and composed by the hierarchy pass, and this reads the
+ * result. The caller fetches the node with `scene_read_node(&scene_database, em.node)`, and the age
+ * with {@link ./chunk_particle_emitter_age.js}.
+ *
+ * The RNG seed is `hash_lowbias32_vec3u` over (emitter seed, slot, frame) — the engine's house
+ * hash, not a private one. It only has to be well mixed, since `random()` does the real work from
+ * here, and `rnd_state` feeds a PCG whose LCG step has a nonzero increment, so no seed value
+ * (zero included) is degenerate.
+ *
+ * Depends on {@link chunk_particle_vm} (owns `vm_ctx`, and pulls in the shared `rnd_state`),
+ * {@link chunk_particle_emitter} (the `ParticleEmitter` struct) and
+ * {@link chunk_scene_database_access} (the node struct + reader).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_setup_context = CodeChunk.from(/* wgsl */ `
+fn particle_setup_context(
+    em : ParticleEmitter,
+    node : ${NODE3D_STRUCT.wgsl_ref},
+    slot : u32,
+    dt : f32,
+    time : f32,
+    emitter_age : f32,
+    spawn_fraction : f32,
+    frame : u32,
+) {
+    let transform = node.global;
+
+    vm_ctx.delta_time = dt;
+    vm_ctx.time = time;
+    vm_ctx.emitter_age = emitter_age;
+    vm_ctx.spawn_fraction = spawn_fraction;
+    vm_ctx.particle_index = f32(slot);
+    vm_ctx.emitter_position = (transform * vec4<f32>(0.0, 0.0, 0.0, 1.0)).xyz;
+    vm_ctx.emitter_direction = normalize((transform * vec4<f32>(0.0, 0.0, -1.0, 0.0)).xyz);
+    vm_ctx.emitter_up = normalize((transform * vec4<f32>(0.0, 1.0, 0.0, 0.0)).xyz);
+    rnd_state = hash_lowbias32_vec3u(vec3<u32>(em.seed, slot, frame));
+}
+`, [
+    chunk_particle_vm,
+    chunk_particle_emitter,
+    chunk_scene_database_access,
+    chunk_hash_lowbias32_vec3u,
+]);

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

@@ -0,0 +1,14 @@
+/**
+ * The draw pipeline: the four additive accumulators, reverse-Z depth test against the scene, no
+ * depth write.
+ * @type {RenderPipelineDescriptor}
+ */
+export const PARTICLE_AVBOIT_DRAW_PIPELINE: RenderPipelineDescriptor;
+/** The draw shader's resource set, for building its bind group. */
+export const PARTICLE_AVBOIT_DRAW_RESOURCES: ShaderResourceSetDescriptor;
+/** The assembled shader, for the validity tier. */
+export const shader_particle_avboit_draw: ShaderDescriptor;
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+//# sourceMappingURL=shader_particle_avboit_draw.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_avboit_draw.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_draw.js"],"names":[],"mappings":"AAkIA;;;;GAIG;AACH,4CAFU,wBAAwB,CAa/B;AAEH,mEAAmE;AACnE,yEAAwD;AAExD,mDAAmD;AACnD,2DAAsD;yCAxJb,iEAAiE;4CAW9D,sDAAsD;iCAFjE,kCAAkC"}

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

@@ -0,0 +1,153 @@
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.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 { chunk_sample_volumetrics } from "../../deferred/chunk_sample_volumetrics.js";
+import { AVBOIT_EXTINCT_TRANSMITTANCE } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { AVBOIT_WARP_STRUCT } from "../../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
+import { AVBOIT_DRAW_TARGETS } from "../../rasterize/native/avboit/avboit_draw_fragment_body.js";
+import { chunk_avboit_sample_transmittance } from "../../rasterize/native/avboit/chunk_avboit_sample_transmittance.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
+import { VIEW_UNIFORM_STRUCT } from "../../view/VIEW_UNIFORM_STRUCT.js";
+import { VOLUMETRICS_METADATA_STRUCT } from "../../volumetrics/VOLUMETRICS_METADATA_STRUCT.js";
+import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
+import { chunk_particle_avboit_contribution } from "./chunk_particle_avboit_contribution.js";
+import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
+import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
+import { chunk_particle_lighting_unlit } from "./chunk_particle_lighting.js";
+
+/**
+ * The particles' AVBOIT draw: the billboard quads at internal resolution, depth-tested against the
+ * opaque scene, into the four accumulators the transparent meshes draw into
+ * (`avboit_draw_fragment_body`). The particle counterpart of `shader_avboit_draw_ibl`.
+ *
+ * Per fragment: the atlas sample times the particle colour, the soft-depth fade against the scene
+ * depth and the lighting hook exactly as the standalone renderer applies them, the volumetric fog
+ * composite exactly as the mesh draw applies it, then the transmittance of everything in front from
+ * the integral texture — and a fragment the volume already calls extinct is discarded unshaded.
+ *
+ * What is written depends on how the particle blends:
+ *
+ * - **alpha / premultiplied** — a surface: `color += premultiplied × T`, `norm += coverage × T`,
+ *   `extinction += -log(1 - coverage)`, the same three the meshes write, with an untinted
+ *   `T_self = 1 - coverage`; the splat recorded exactly that.
+ * - **additive** — light: `emission += premultiplied × T`, nothing else. It joins the resolve
+ *   attenuated by what is in front of it and outside the coverage normalization, which is what an
+ *   additive fragment means.
+ *
+ * The scene depth is bound twice: as the read-only depth attachment the pipeline tests against, and
+ * as the texture the soft fade reads. Both are reads, which WebGPU allows within one pass; the pass
+ * is recorded with the attachment read-only for that reason.
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addUniform("view", VIEW_UNIFORM_STRUCT)
+    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("draw_list", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addTexture("atlas", "float")
+    .addSampler("atlas_sampler", "filtering")
+    .addTexture("scene_depth", "unfilterable-float")
+    // sampled through sLinear: linear, clamped on every axis, which is what the integral needs
+    .addTexture("tIntegral", "float", "3d")
+    .addSampler("sLinear", "filtering", SAMPLER_LINEAR_UPSCALE)
+    // volumetrics (composited inline)
+    .addUniform("volumetrics_metadata", VOLUMETRICS_METADATA_STRUCT)
+    .addTexture("tVolumetrics", "float", "3d")
+    .addTexture("tSTBN_vec3", "float", "3d");
+
+const body = CodeChunk.from(
+    /* language=wgsl */ `
+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 = ${PARTICLE_SOFT_FADE_RANGE};
+
+struct ParticleAVBOITDrawOutput {
+    @location(0) color : vec4<f32>,
+    @location(1) norm : vec4<f32>,
+    @location(2) extinction : vec4<f32>,
+    @location(3) emission : vec4<f32>,
+}
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
+    return particle_billboard_vertex(vi, ii);
+}
+
+@fragment
+fn fs_main(in : ParticleVertexOut) -> ParticleAVBOITDrawOutput {
+    let screen_uv = in.clip.xy / vec2<f32>(f32(view.width), f32(view.height));
+
+    let transmittance = avboit_sample_transmittance(&warp, tIntegral, sLinear, screen_uv, in.view_depth);
+
+    if (all(transmittance <= vec3<f32>(${AVBOIT_EXTINCT_TRANSMITTANCE}))) {
+        // nothing this fragment contributes survives what is in front of it; skip the shading
+        discard;
+    }
+
+    var color = textureSample(atlas, atlas_sampler, in.uv) * in.color;
+
+    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);
+    }
+
+    if ((in.flags & PARTICLE_FLAG_LIGHTING) != 0u) {
+        color = particle_apply_lighting(color, in.world_position, normalize(in.normal));
+    }
+
+    let volumetrics = sample_volumetrics(in.view_depth, screen_uv, in.clip.xy);
+
+    let contribution = particle_avboit_contribution(color, in.blend, transmittance, volumetrics);
+
+    var out : ParticleAVBOITDrawOutput;
+
+    out.color = contribution.color;
+    out.norm = contribution.norm;
+    out.extinction = contribution.extinction;
+    out.emission = contribution.emission;
+
+    return out;
+}
+`, [
+    chunk_particle_avboit_contribution,
+    chunk_particle_scene_view_depth,
+    chunk_particle_billboard_vertex,
+    chunk_particle_lighting_unlit,
+    chunk_sample_volumetrics,
+    chunk_avboit_sample_transmittance,
+]);
+
+const descriptor = ShaderDescriptor.from({ label: "Particle AVBOIT Draw", body, resources });
+
+/**
+ * The draw pipeline: the four additive accumulators, reverse-Z depth test against the scene, no
+ * depth write.
+ * @type {RenderPipelineDescriptor}
+ */
+export const PARTICLE_AVBOIT_DRAW_PIPELINE = RenderPipelineDescriptor.from({
+    label: "Particle AVBOIT Draw",
+    layout: resources.generatePipelineLayout(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+    vertex: { module: { code: descriptor.source }, entryPoint: "vs_main" },
+    fragment: {
+        module: { code: descriptor.source },
+        entryPoint: "fs_main",
+        targets: AVBOIT_DRAW_TARGETS,
+    },
+    depthStencil: DepthStencilState.from({ format: "depth32float", depthWriteEnabled: false, depthCompare: "greater" }),
+    primitive: { topology: "triangle-list", cullMode: "none" },
+});
+
+/** The draw shader's resource set, for building its bind group. */
+export const PARTICLE_AVBOIT_DRAW_RESOURCES = resources;
+
+/** The assembled shader, for the validity tier. */
+export const shader_particle_avboit_draw = descriptor;

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

@@ -0,0 +1,3 @@
+export const shader_particle_avboit_occupancy: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_particle_avboit_occupancy.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,124 @@
+import { atomic_u32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { chunk_cluster_depth_to_z_slice } from "../../light/cluster/chunk_cluster_depth_to_z_slice.js";
+import { AVBOIT_OCCUPANCY_WORDS, AVBOIT_VIRTUAL_SLICES_MAX } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+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 { 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 { EMITTER_BLEND } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { chunk_particle_emitter_world_sphere } from "./chunk_particle_emitter_world_sphere.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.
+ * 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.
+ *
+ * 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.
+ *
+ * Walks the table with its page iterator, read-only: the rows are the tick's output of this frame.
+ *
+ * @type {ComputeShader}
+ */
+
+const GROUP_SIZE = PARTICLE_EMITTER_TICK_WORKGROUP_SIZE;
+
+const PG = PARTICLE_EMITTER_DESCRIPTOR.page_iterator_symbol_prefix(GROUP_SIZE);
+
+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);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const PARTICLE_BLEND_ADDITIVE : u32 = ${EMITTER_BLEND.ADDITIVE}u;
+
+@compute @workgroup_size(${GROUP_SIZE}, 1, 1)
+fn main(
+    @builtin(workgroup_id) wg_id : vec3<u32>,
+    @builtin(local_invocation_index) local_id : u32,
+) {
+    // page_address is uniform across the workgroup, so this branch is uniform.
+    if (!${PG}_setup(&emitter_database, wg_id.x, local_id)) {
+        return;
+    }
+
+    let slot_in_page = ${PG}_slot_in_page(local_id);
+
+    if (slot_in_page >= ${PG}_ELEMENTS_PER_PAGE || !${PG}_is_occupied(slot_in_page)) {
+        return;
+    }
+
+    let em = ${PG}_read(&emitter_database, slot_in_page);
+
+    if (particle_emitter_blend(em.flags) == PARTICLE_BLEND_ADDITIVE) {
+        // adds light, occludes nothing: no extinction to place
+        return;
+    }
+
+    let node = scene_read_node(&scene_database, em.node);
+    let sphere = particle_emitter_world_sphere(em, node.global);
+
+    let center_view = (camera.view_matrix * vec4<f32>(sphere.xyz, 1.0)).xyz;
+
+    // camera looks down -Z
+    let depth_min = -center_view.z - sphere.w;
+    let depth_max = -center_view.z + sphere.w;
+
+    if (depth_max < camera.clip_near_far.x) {
+        // entirely in front of the near plane
+        return;
+    }
+
+    let limit = ${AVBOIT_VIRTUAL_SLICES_MAX}.0;
+    let slice_near = cluster_depth_to_z_slice(max(depth_min, camera.clip_near_far.x), settings.cluster_parameters, limit);
+    let slice_far = cluster_depth_to_z_slice(depth_max, settings.cluster_parameters, limit);
+
+    let range = avboit_occupancy_range(slice_near, slice_far);
+
+    let word_first = u32(range.x) >> 5u;
+    let word_last = u32(range.y) >> 5u;
+
+    for (var word = word_first; word <= word_last; word++) {
+        let mask = avboit_occupancy_word_mask(word, range.x, range.y);
+        if (mask != 0u) {
+            atomicOr(&occupancy[word], mask);
+        }
+    }
+}
+    `, [
+        PARTICLE_EMITTER_DESCRIPTOR.chunk_iterate(GROUP_SIZE),
+        chunk_particle_emitter_world_sphere,
+        chunk_scene_database_access,
+        chunk_cluster_depth_to_z_slice,
+        chunk_avboit_occupancy_range,
+        chunk_avboit_occupancy_word_mask,
+    ]
+);
+
+export const shader_particle_avboit_occupancy = ComputeShader.from({
+    label: "Particle AVBOIT Occupancy",
+    resources,
+    body,
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Bind group of the volume atomics; group 0 is everything the billboard vertex stage and the atlas
+ * need.
+ * @type {number}
+ */
+export const PARTICLE_AVBOIT_SPLAT_BIND_GROUP_VOLUME: number;
+/**
+ * The splat pipeline: no depth, one never-written attachment to size the raster.
+ * @type {RenderPipelineDescriptor}
+ */
+export const PARTICLE_AVBOIT_SPLAT_PIPELINE: RenderPipelineDescriptor;
+/** The splat shader's resource set, for building its bind groups against the layout above. */
+export const PARTICLE_AVBOIT_SPLAT_RESOURCES: ShaderResourceSetDescriptor;
+/** The assembled shader, for the validity tier. */
+export const shader_particle_avboit_splat: ShaderDescriptor;
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+//# sourceMappingURL=shader_particle_avboit_splat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_particle_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/shader_particle_avboit_splat.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,sDAFU,MAAM,CAEyC;AAqGzD;;;GAGG;AACH,6CAFU,wBAAwB,CAY/B;AAEH,8FAA8F;AAC9F,0EAAyD;AAEzD,mDAAmD;AACnD,4DAAuD;yCAjJd,iEAAiE;4CAY9D,sDAAsD;iCAFjE,kCAAkC"}

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

@@ -0,0 +1,147 @@
+import { PipelineLayoutDescriptor } from "../../../descriptor/pipeline/PipelineLayoutDescriptor.js";
+import { RenderPipelineDescriptor } from "../../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { atomic_u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../camera/CAMERA_UNIFORM_STRUCT.js";
+import { OIT_COVERAGE_MAX } from "../../rasterize/native/oit/OIT_CONSTANTS.js";
+import { AVBOIT_WARP_STRUCT } from "../../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
+import { chunk_avboit_splat_slice } from "../../rasterize/native/avboit/chunk_avboit_splat_slice.js";
+import { chunk_avboit_transmittance_to_extinction } from "../../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
+import { chunk_avboit_view_depth_to_physical } from "../../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
+import { AVBOIT_SPLAT_DUMMY_FORMAT } from "../../rasterize/native/avboit/shader_avboit_splat.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { PARTICLE_SOFT_FADE_RANGE } from "../ParticleConstants.js";
+import { EMITTER_FLAG } from "../data/PARTICLE_EMITTER_STRUCT.js";
+import { AVBOIT_VOXEL_DOWNSCALE } from "../../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
+import { chunk_particle_billboard_vertex } from "./chunk_particle_billboard_vertex.js";
+import { chunk_particle_scene_view_depth } from "./chunk_particle_scene_view_depth.js";
+
+/**
+ * Bind group of the volume atomics; group 0 is everything the billboard vertex stage and the atlas
+ * need.
+ * @type {number}
+ */
+export const PARTICLE_AVBOIT_SPLAT_BIND_GROUP_VOLUME = 1;
+
+/**
+ * The particles' AVBOIT splat: the billboard quads rasterized at the volume's resolution, each
+ * fragment's extinction added into the voxel volume through `avboit_splat_slice` — the same write
+ * path as the meshlet splat, so a particle and a surface at one depth pile up in one field.
+ *
+ * Coverage is the sampled atlas alpha times the particle's colour alpha, capped like a surface's;
+ * `T_self = 1 - coverage`, untinted. An additive particle (`particle_premultiply` would give it
+ * alpha 0) covers nothing and writes nothing.
+ *
+ * Depth is the fragment's own view depth, from the vertex stage, through curve → warp → physical
+ * and the two-slice linear splat. No depth attachment, for the reason the meshlet splat has none.
+ *
+ * The `draw_list` this binds is the alive list, unsorted: the volume does not care about order.
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT)
+    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT)
+    .addStorageBuffer("pool", WebGPUArray.u32, false)
+    .addStorageBuffer("draw_list", WebGPUArray.u32, false)
+    .addStorageBuffer("emitter_database", WebGPUArray.u32, false)
+    .addTexture("atlas", "float")
+    .addSampler("atlas_sampler", "filtering")
+    .addTexture("scene_depth", "unfilterable-float");
+
+resources.createGroup()
+    .addStorageBuffer("extinction_volume", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("overflow_slice", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    /* language=wgsl */ `
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32, @builtin(instance_index) ii : u32) -> ParticleVertexOut {
+    return particle_billboard_vertex(vi, ii);
+}
+
+const PARTICLE_FLAG_SOFT_DEPTH : u32 = ${EMITTER_FLAG.SOFT_DEPTH}u;
+
+@fragment
+fn fs_main(in : ParticleVertexOut) {
+    let premultiplied = particle_premultiply(textureSample(atlas, atlas_sampler, in.uv) * in.color, in.blend);
+
+    var alpha = premultiplied.a;
+
+    if ((in.flags & PARTICLE_FLAG_SOFT_DEPTH) != 0u) {
+        /*
+         The same fade the draw applies to the same fragment, so the volume records the coverage the
+         accumulators are weighted by. Sampled once per voxel: this pass rasterizes at the volume's
+         resolution, so the scene texel under the fragment is the downscale factor times out.
+        */
+        let scene_texel = vec2<i32>(in.clip.xy) * ${AVBOIT_VOXEL_DOWNSCALE};
+        let scene_vd = particle_scene_view_depth(textureLoad(scene_depth, scene_texel, 0).r, camera);
+
+        alpha = alpha * particle_soft_fade(scene_vd, in.view_depth, ${PARTICLE_SOFT_FADE_RANGE});
+    }
+
+    let coverage = clamp(alpha, 0.0, ${OIT_COVERAGE_MAX});
+
+    if (coverage <= 0.0) {
+        // additive, faded out against the surface behind it, or fully transparent: occludes nothing
+        return;
+    }
+
+    let extinction = avboit_transmittance_to_extinction(vec3<f32>(1.0 - coverage));
+
+    let p = avboit_view_depth_to_physical(&warp, in.view_depth);
+
+    // in.clip is @builtin(position): .xy the low-resolution pixel
+    let texel = vec2<u32>(in.clip.xy);
+    let column = (texel.y * warp.voxel_width + texel.x) * warp.physical_count;
+
+    // linear splat between the two slices around the fragment
+    let c = p - 0.5;
+    let slice = i32(floor(c));
+    let fraction = c - floor(c);
+
+    avboit_splat_slice(column, slice, extinction * (1.0 - fraction), texel);
+    avboit_splat_slice(column, slice + 1, extinction * fraction, texel);
+}
+`, [
+    chunk_particle_billboard_vertex,
+    chunk_particle_scene_view_depth,
+    chunk_avboit_transmittance_to_extinction,
+    chunk_avboit_view_depth_to_physical,
+    chunk_avboit_splat_slice,
+]);
+
+const descriptor = ShaderDescriptor.from({ label: "Particle AVBOIT Splat", body, resources });
+
+// Built group by group: the atomics are fragment-only, and WebGPU refuses a read-write storage
+// buffer that is visible to the vertex stage.
+const groups = resources.groups;
+const layout = PipelineLayoutDescriptor.from([
+    groups[0].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+    groups[PARTICLE_AVBOIT_SPLAT_BIND_GROUP_VOLUME].generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT),
+], resources.immediateSize);
+
+/**
+ * The splat pipeline: no depth, one never-written attachment to size the raster.
+ * @type {RenderPipelineDescriptor}
+ */
+export const PARTICLE_AVBOIT_SPLAT_PIPELINE = RenderPipelineDescriptor.from({
+    label: "Particle AVBOIT Splat",
+    layout,
+    vertex: { module: { code: descriptor.source }, entryPoint: "vs_main" },
+    fragment: {
+        module: { code: descriptor.source },
+        entryPoint: "fs_main",
+        targets: [{ format: AVBOIT_SPLAT_DUMMY_FORMAT, writeMask: 0 }],
+    },
+    primitive: { topology: "triangle-list", cullMode: "none" },
+});
+
+/** The splat shader's resource set, for building its bind groups against the layout above. */
+export const PARTICLE_AVBOIT_SPLAT_RESOURCES = resources;
+
+/** The assembled shader, for the validity tier. */
+export const shader_particle_avboit_splat = descriptor;