@woosh/meep-engine 3.15.0 → 3.17.0

package/src/shade/renderer/particles/runtime/ProgramPlacement.js

@@ -0,0 +1,106 @@
+/**
+ * Where one program sits in the {@link ./ProgramHeap.js ProgramHeap}, and what an emitter record
+ * carries to find it.
+ *
+ * A placement is the heap's, not the caller's: {@link ./ProgramHeap.js#acquire} hands one out and
+ * {@link ./ProgramHeap.js#release} takes it back, and every field here is written by the heap. It is
+ * shared — every emitter running the same bytecode holds the same placement object, which is what
+ * puts them in one simulation bucket — and it is MUTATED IN PLACE when the heap repacks. Holders
+ * therefore see the new offsets without being handed a new object, and only have to restage the
+ * record they wrote the old ones into.
+ *
+ * The offsets are section-relative, which is what lets the heap move a program without the shader
+ * knowing: instruction offsets count instructions from the code section's base, and
+ * {@link ProgramPlacement#constant_offset} counts words from the constant section's base. The one
+ * absolute address in the whole buffer is the header word saying where the code section starts.
+ */
+export class ProgramPlacement {
+
+    /**
+     * Dense-ish id of this program: the value the emitter record carries and the simulation-order
+     * pass histograms on. Stable for the life of the placement, repacks included — the offsets move,
+     * the id does not.
+     *
+     * Ids are handed out lowest-free-first and a released one is reused, so they stay inside
+     * `[0, ProgramHeap#program_id_capacity)` however many programs come and go.
+     *
+     * @type {number}
+     */
+    program_id = -1;
+
+    /**
+     * First instruction of the INIT section, counted in instructions from the code base.
+     * @type {number}
+     */
+    init_offset = 0;
+
+    /**
+     * Instructions in the INIT section.
+     * @type {number}
+     */
+    init_count = 0;
+
+    /**
+     * First instruction of the UPDATE section, counted in instructions from the code base. Directly
+     * after INIT — the two sections of a program are allocated as one contiguous range.
+     * @type {number}
+     */
+    update_offset = 0;
+
+    /**
+     * Instructions in the UPDATE section.
+     * @type {number}
+     */
+    update_count = 0;
+
+    /**
+     * First word of this program's constant pool, counted in words from the constant base. The VM
+     * adds it to every program-local constant reference.
+     * @type {number}
+     */
+    constant_offset = 0;
+
+    /**
+     * The heap's own copy of the bytecode — the key it is filed under, and what a repack rewrites
+     * into the moved range.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    program = null;
+
+    /**
+     * How many emitters hold this placement. The heap frees the ranges and releases the id when it
+     * reaches zero, so one emitter of a shared effect going away does not take the effect with it.
+     *
+     * @type {number}
+     */
+    references = 0;
+
+    /**
+     * The code range, in instructions, as {@link ../../../../core/binary/allocator/OffsetAllocator.js}
+     * handed it out. `null` for a program with no instructions at all.
+     *
+     * @type {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation|null}
+     */
+    code_allocation = null;
+
+    /**
+     * The constant-pool range, in words. `null` for a program with an empty pool.
+     * @type {import("../../../../core/binary/allocator/OffsetAllocator.js").Allocation|null}
+     */
+    constant_allocation = null;
+
+    /**
+     * @returns {number} instructions this program occupies in the code section, both sections summed
+     */
+    get instruction_count() {
+        return this.init_count + this.update_count;
+    }
+
+    /**
+     * @returns {number} words this program occupies in the constant section
+     */
+    get constant_word_count() {
+        return this.program === null ? 0 : this.program.constant_word_count;
+    }
+}

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts

@@ -1,19 +1,22 @@
 /**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
  * and UPDATE node graphs, lowered to VM bytecode.
  *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
+ * The two halves come back together because they are compiled together, and an emitter takes both:
+ * the layout is what a render binding resolves a name against, the program is what the heap packs.
+ * They are not a value in their own right, so they go into an emitter by being spread —
+ * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
+ * the emitter keeps them as two fields rather than as one bag.
  *
  * @param {object} params
  * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {NodeGraph} [params.spawn]
+ * @param {NodeGraph} [params.init]
  * @param {NodeGraph} [params.update]
  * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
  */
-export function create_particle_effect({ layout, spawn, update }: {
+export function create_particle_effect({ layout, init, update }: {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;
-    spawn?: NodeGraph;
+    init?: NodeGraph;
     update?: NodeGraph;
 }): {
     layout: import("../layout/ParticleLayout.js").ParticleLayout;

package/src/shade/renderer/particles/runtime/create_particle_effect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,KAAK;IACL,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}
+{"version":3,"file":"create_particle_effect.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/create_particle_effect.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IALwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;IACjC,IAAI;IACJ,MAAM;;YACb,OAAO,6BAA6B,EAAE,cAAc;aAAW,OAAO,2BAA2B,EAAE,eAAe;EAKxI"}

package/src/shade/renderer/particles/runtime/create_particle_effect.js

@@ -1,19 +1,22 @@
-import { compile_particle_effect } from "../graph/compile_particle_graph.js";
-
-/**
- * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus SPAWN
- * and UPDATE node graphs, lowered to VM bytecode.
- *
- * The returned value bundles the layout with the compiled program so the {@link ./EmitterRegistry.js}
- * can resolve render-attribute names to record offsets and pack the program into the arena.
- *
- * @param {object} params
- * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
- * @param {NodeGraph} [params.spawn]
- * @param {NodeGraph} [params.update]
- * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
- */
-export function create_particle_effect({ layout, spawn, update }) {
-    const program = compile_particle_effect({ spawn, update, layout });
-    return { layout, program };
-}
+import { compile_particle_effect } from "../graph/compile_particle_graph.js";
+
+/**
+ * Compile a particle effect: a per-particle attribute {@link ../layout/ParticleLayout.js} plus INIT
+ * and UPDATE node graphs, lowered to VM bytecode.
+ *
+ * The two halves come back together because they are compiled together, and an emitter takes both:
+ * the layout is what a render binding resolves a name against, the program is what the heap packs.
+ * They are not a value in their own right, so they go into an emitter by being spread —
+ * `ParticleEmitter.from({ ...create_particle_effect({ layout, update }), spawn_rate: 100 })` — and
+ * the emitter keeps them as two fields rather than as one bag.
+ *
+ * @param {object} params
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} params.layout
+ * @param {NodeGraph} [params.init]
+ * @param {NodeGraph} [params.update]
+ * @returns {{ layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram }}
+ */
+export function create_particle_effect({ layout, init, update }) {
+    const program = compile_particle_effect({ init, update, layout });
+    return { layout, program };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * What one particle fragment contributes to AVBOIT's four accumulators.
+ *
+ * The whole of the particle draw's decision, taken apart from the sampling that feeds it: which
+ * accumulator a fragment belongs in, and with what weight. Lifted out of the fragment stage so it
+ * can be run on the WGSL emulator against plain numbers — a fragment that samples an atlas, a depth
+ * buffer, an integral texture and a froxel volume cannot be.
+ *
+ * The inputs are the shaded, *un*premultiplied colour and its emitter's blend mode; the
+ * transmittance the voxel volume leaves in front of this fragment, per channel; and
+ * `sample_volumetrics` at this fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_contribution: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_avboit_contribution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_avboit_contribution.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_avboit_contribution.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,iDAFU,SAAS,CA0Dc;0BA1EP,oCAAoC"}

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

@@ -0,0 +1,75 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { OIT_COVERAGE_MAX } from "../../rasterize/native/oit/OIT_CONSTANTS.js";
+import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
+
+/**
+ * What one particle fragment contributes to AVBOIT's four accumulators.
+ *
+ * The whole of the particle draw's decision, taken apart from the sampling that feeds it: which
+ * accumulator a fragment belongs in, and with what weight. Lifted out of the fragment stage so it
+ * can be run on the WGSL emulator against plain numbers — a fragment that samples an atlas, a depth
+ * buffer, an integral texture and a froxel volume cannot be.
+ *
+ * The inputs are the shaded, *un*premultiplied colour and its emitter's blend mode; the
+ * transmittance the voxel volume leaves in front of this fragment, per channel; and
+ * `sample_volumetrics` at this fragment, `.xyz` in-scatter and `.w` transmittance.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_avboit_contribution = CodeChunk.from(/* language=wgsl */ `
+struct ParticleAVBOITContribution {
+    color : vec4<f32>,
+    norm : vec4<f32>,
+    extinction : vec4<f32>,
+    emission : vec4<f32>,
+}
+
+fn particle_avboit_contribution(
+    shaded : vec4<f32>,
+    blend : u32,
+    transmittance : vec3<f32>,
+    fog : vec4<f32>
+) -> ParticleAVBOITContribution {
+    var out : ParticleAVBOITContribution;
+
+    let premultiplied = particle_premultiply(shaded, blend);
+
+    /*
+     Full opacity would be zero transmittance, whose logarithm breaks the accumulators; below zero
+     it would be a negative extinction, and the resolve's exp(-sum) would brighten what is behind
+     the fragment instead of dimming it.
+    */
+    let coverage = clamp(premultiplied.a, 0.0, ${OIT_COVERAGE_MAX});
+
+    if (coverage <= 0.0) {
+        /*
+         Covers nothing: an additive emitter, or a premultiplied sprite with no alpha, which the
+         billboard pipeline blends the same way. It is dimmed by the fog in front of it, but it does
+         not carry the fog's own in-scatter: the scene it draws over already has that composited in,
+         and the resolve adds emission outside the normalization that would otherwise take the
+         duplicate away. Carrying it would add one copy of the fog per fragment.
+        */
+        out.color = vec4<f32>(0.0);
+        out.norm = vec4<f32>(0.0);
+        out.extinction = vec4<f32>(0.0);
+        out.emission = vec4<f32>(max(premultiplied.rgb * fog.w * transmittance, vec3<f32>(0.0)), 0.0);
+        return out;
+    }
+
+    // the ceiling is on the pair, so the colour is rescaled with the coverage it is weighted by
+    let scale = coverage / premultiplied.a;
+
+    // this one does hide part of the scene, so it owes that part its in-scatter back — and the
+    // resolve's normalization is what keeps the sum to one copy however many fragments there are
+    let color = premultiplied.rgb * scale * fog.w + fog.xyz * coverage;
+
+    let self_transmittance = vec3<f32>(1.0 - coverage);
+
+    out.color = vec4<f32>(color * transmittance, 0.0);
+    out.norm = vec4<f32>((1.0 - self_transmittance) * transmittance, 0.0);
+    out.extinction = vec4<f32>(-log(self_transmittance), 0.0);
+    out.emission = vec4<f32>(0.0);
+
+    return out;
+}
+`, [chunk_particle_render_math]);

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

@@ -0,0 +1,20 @@
+/**
+ * The billboard vertex stage, shared by every pass that rasterizes particles: the standalone
+ * renderer, and the AVBOIT splat and draw. One instance per particle, six vertices per instance;
+ * the instance indexes the slot list, the vertex picks a quad corner, and the corner is expanded
+ * per the emitter's projection mode and projected with the camera.
+ *
+ * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
+ * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them
+ * directly, the way `sample_volumetrics` reads its textures. Which list that is, is the caller's
+ * choice: the standalone path binds the depth-sorted one because a blended draw needs order, the
+ * AVBOIT passes bind the alive list because the volume makes order irrelevant.
+ *
+ * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
+ * AVBOIT passes place the fragment at.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_billboard_vertex: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_billboard_vertex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_billboard_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_billboard_vertex.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAFU,SAAS,CAuE6D;0BA7FtD,oCAAoC"}

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

@@ -0,0 +1,94 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { PARTICLE_RECORD_HEADER_EMITTER, PARTICLE_RECORD_WORD_COUNT } from "../ParticleConstants.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";
+import { chunk_particle_render_math } from "./chunk_particle_render_math.js";
+
+/**
+ * The billboard vertex stage, shared by every pass that rasterizes particles: the standalone
+ * renderer, and the AVBOIT splat and draw. One instance per particle, six vertices per instance;
+ * the instance indexes the slot list, the vertex picks a quad corner, and the corner is expanded
+ * per the emitter's projection mode and projected with the camera.
+ *
+ * The enclosing shader binds `camera` (`CAMERA_UNIFORM_STRUCT`), `pool` and `emitter_database`
+ * (`array<u32>`) and `draw_list` (the slot list, `array<u32>`) under those names; this reads them
+ * directly, the way `sample_volumetrics` reads its textures. Which list that is, is the caller's
+ * choice: the standalone path binds the depth-sorted one because a blended draw needs order, the
+ * AVBOIT passes bind the alive list because the volume makes order irrelevant.
+ *
+ * `view_depth` is the vertex's own view-space depth, interpolated across the quad — the depth the
+ * AVBOIT passes place the fragment at.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_billboard_vertex = CodeChunk.from(
+    /* language=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;
+
+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;
+}
+
+fn particle_billboard_vertex(vi : u32, 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 = draw_list[ii];
+    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_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;
+}
+`, [chunk_particle_emitter, chunk_particle_header, chunk_particle_render_math]);

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

@@ -10,8 +10,7 @@
  *
  * The simulate shader that includes this chunk must also bind `particle_curve_database :
  * array<u32>` to `GPUAnimationManager.database.buffer` (in place of the no-op
- * {@link ./chunk_particle_context.js#chunk_particle_curve_disabled} provider used when no effect
- * uses curves).
+ * {@link ./chunk_particle_curve_disabled.js} provider used when no effect uses curves).
  *
  * @type {CodeChunk}
  */

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAFU,SAAS,CAS0C;0BA5BnC,oCAAoC"}
+{"version":3,"file":"chunk_particle_curve_animation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_animation.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,6CAFU,SAAS,CAS0C;0BA3BnC,oCAAoC"}

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

@@ -16,8 +16,7 @@ const CURVE_TABLE = ANIMATION_DATABASE_SPEC.get("animation_curves");
  *
  * The simulate shader that includes this chunk must also bind `particle_curve_database :
  * array<u32>` to `GPUAnimationManager.database.buffer` (in place of the no-op
- * {@link ./chunk_particle_context.js#chunk_particle_curve_disabled} provider used when no effect
- * uses curves).
+ * {@link ./chunk_particle_curve_disabled.js} provider used when no effect uses curves).
  *
  * @type {CodeChunk}
  */

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

@@ -0,0 +1,11 @@
+/**
+ * Default curve provider: no curves bound, `CURVE` opcodes evaluate to 0. The production feature
+ * swaps this for an animation-database-backed provider
+ * ({@link ./chunk_particle_curve_animation.js}). Kept separate so an effect that uses no curves
+ * compiles without any animation bindings.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_curve_disabled: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_curve_disabled.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_curve_disabled.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_curve_disabled.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,4CAFU,SAAS,CAIhB;0BAZuB,oCAAoC"}

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

@@ -0,0 +1,13 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+
+/**
+ * Default curve provider: no curves bound, `CURVE` opcodes evaluate to 0. The production feature
+ * swaps this for an animation-database-backed provider
+ * ({@link ./chunk_particle_curve_animation.js}). Kept separate so an effect that uses no curves
+ * compiles without any animation bindings.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_curve_disabled = CodeChunk.from(/* wgsl */ `
+fn particle_vm_sample_curve(handle : u32, t : f32) -> f32 { return 0.0; }
+`);

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

@@ -0,0 +1,28 @@
+/**
+ * What the emit pass does for one particle born this frame — which emitter it belongs to, and what
+ * its record holds once it exists.
+ *
+ * Shared by {@link ./shader_particle_emit.js} and {@link ./shader_particle_emit_wide.js} for the
+ * same reason {@link ./chunk_particle_simulate_step.js} is shared: two register backings, one
+ * meaning, and the difference between the shaders is how they get an index and nothing else.
+ *
+ * ## What stays in the entry points
+ *
+ * Both atomic sections: popping a free slot off the dead-list stack, and appending the newborn to
+ * the alive list. They bracket `particle_emit_one` rather than living inside it, because the pop
+ * has to fail before any record is touched, and because an atomic array behind a pointer parameter
+ * is a shape nothing else in the engine uses.
+ *
+ * The pop is the delicate one, and its guard must catch WRAPPED values rather than just zero. When
+ * many threads race an empty stack, the 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 `> capacity` identifies every
+ * wrapped state; each thread that subtracted also adds back exactly once, so the counter converges
+ * to 0. Both entry points spell that out; this paragraph is where it is explained.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emit_step: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emit_step.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_particle_emit_step.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_emit_step.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,uCAFU,SAAS,CAoGhB;0BAvIuB,oCAAoC"}

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

@@ -0,0 +1,136 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_lower_bound_branchless } from "../../shader/chunk/math/chunk_lower_bound_branchless.js";
+import {
+    PARTICLE_RECORD_HEADER_EMITTER,
+    PARTICLE_RECORD_USER_WORD_START,
+    PARTICLE_RECORD_WORD_COUNT,
+    PARTICLE_VM_INSTRUCTION_WORDS,
+} from "../ParticleConstants.js";
+import { chunk_particle_header } from "../data/particle_header.js";
+import { chunk_particle_emitter_age } from "./chunk_particle_emitter_age.js";
+import { chunk_particle_setup_context } from "./chunk_particle_setup_context.js";
+
+/**
+ * What the emit pass does for one particle born this frame — which emitter it belongs to, and what
+ * its record holds once it exists.
+ *
+ * Shared by {@link ./shader_particle_emit.js} and {@link ./shader_particle_emit_wide.js} for the
+ * same reason {@link ./chunk_particle_simulate_step.js} is shared: two register backings, one
+ * meaning, and the difference between the shaders is how they get an index and nothing else.
+ *
+ * ## What stays in the entry points
+ *
+ * Both atomic sections: popping a free slot off the dead-list stack, and appending the newborn to
+ * the alive list. They bracket `particle_emit_one` rather than living inside it, because the pop
+ * has to fail before any record is touched, and because an atomic array behind a pointer parameter
+ * is a shape nothing else in the engine uses.
+ *
+ * The pop is the delicate one, and its guard must catch WRAPPED values rather than just zero. When
+ * many threads race an empty stack, the 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 `> capacity` identifies every
+ * wrapped state; each thread that subtracted also adds back exactly once, so the counter converges
+ * to 0. Both entry points spell that out; this paragraph is where it is explained.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emit_step = CodeChunk.from(/* language=wgsl */ `
+const PARTICLE_RECORD_WORDS : u32 = ${PARTICLE_RECORD_WORD_COUNT}u;
+const PARTICLE_USER_WORD_START : u32 = ${PARTICLE_RECORD_USER_WORD_START}u;
+const PARTICLE_HEADER_EMITTER : u32 = ${PARTICLE_RECORD_HEADER_EMITTER}u;
+const PARTICLE_INSTRUCTION_WORDS : u32 = ${PARTICLE_VM_INSTRUCTION_WORDS}u;
+
+// Which emitter newborn i belongs to, and where in that emitter's batch it sits.
+struct ParticleEmitAssignment {
+    valid : bool,
+    emitter_row : u32,
+    // This particle's place in its emitter's batch this frame, n / count — the SPAWN_FRACTION
+    // contract, for spreading a batch along a spawn curve.
+    spawn_fraction : f32,
+}
+
+// Locate newborn i in the prefix scan of the tick pass's per-row spawn counts.
+//
+// The emitter is the first row whose inclusive sum exceeds i; its batch starts at the sum before,
+// which is the exclusive sum. Rows that spawned nothing this frame have equal sums and the search
+// steps over them. That is the meshes-to-meshlets expansion applied to particles: the per-emitter
+// count is unbounded and no thread loops over it.
+fn particle_emit_assignment(
+    prefix : ptr<storage, array<u32>>,
+    emitter_count : u32,
+    i : u32,
+) -> ParticleEmitAssignment {
+    var r : ParticleEmitAssignment;
+    r.valid = false;
+    r.emitter_row = 0u;
+    r.spawn_fraction = 0.0;
+
+    // The scan's last inclusive sum is the number of particles born this frame. An empty list has
+    // no last element to read; it also has no particles.
+    if (emitter_count == 0u) { return r; }
+    if (i >= (*prefix)[emitter_count - 1u]) { return r; }
+
+    let emitter_row = lower_bound_branchless(prefix, i + 1u, emitter_count);
+    var batch_start = 0u;
+    if (emitter_row > 0u) {
+        batch_start = (*prefix)[emitter_row - 1u];
+    }
+    let batch_size = (*prefix)[emitter_row] - batch_start;
+
+    r.valid = true;
+    r.emitter_row = emitter_row;
+    r.spawn_fraction = f32(i - batch_start) / f32(batch_size);
+
+    return r;
+}
+
+// Give a freshly popped slot its particle: clear what the last occupant left, stamp the header with
+// the emitter row and its generation, and run that emitter's INIT program over the record. The
+// emitter's position and axes come from its scene node, so a particle born of an emitter riding a
+// bone starts where the bone is this frame.
+fn particle_emit_one(
+    scene_database : ptr<storage, array<u32>>,
+    emitter_database : ptr<storage, array<u32>>,
+    program : ptr<storage, array<u32>>,
+    pool : ptr<storage, array<u32>, read_write>,
+    emitter_row : u32,
+    slot : u32,
+    spawn_fraction : f32,
+    dt : f32,
+    time : f32,
+    frame : u32,
+) {
+    let record_base = slot * PARTICLE_RECORD_WORDS;
+
+    let em = particle_emitter_read(emitter_database, emitter_row);
+    let node = scene_read_node(scene_database, em.node);
+
+    // Clear stale user state from a recycled slot (each write targets a distinct word).
+    for (var w = PARTICLE_USER_WORD_START; w < PARTICLE_RECORD_WORDS; w = w + 1u) {
+        (*pool)[record_base + w] = 0u;
+    }
+    (*pool)[record_base + PARTICLE_HEADER_EMITTER] = particle_header_pack(emitter_row, em.generation);
+
+    particle_vm_reset();
+    particle_setup_context(
+        em, node, slot,
+        dt, time,
+        particle_emitter_age(emitter_database, emitter_row),
+        spawn_fraction, frame,
+    );
+    particle_vm_execute(
+        program,
+        em.init_offset * PARTICLE_INSTRUCTION_WORDS,
+        em.init_count,
+        em.constant_offset,
+        pool,
+        record_base,
+    );
+}
+`, [
+    chunk_particle_setup_context,
+    chunk_particle_emitter_age,
+    chunk_particle_header,
+    chunk_lower_bound_branchless,
+]);

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

@@ -0,0 +1,17 @@
+/**
+ * The emitter's age, as the tick pass left it this frame.
+ *
+ * It is the tick pass's running total, read off the `emitter_state` table of the same database the
+ * emitter record came from ({@link ../data/PARTICLE_EMITTER_STATE.js}) — one binding for both,
+ * through the table's single-field reader, so there is no second copy of the row layout here to
+ * drift from the table's.
+ *
+ * Kept apart from {@link ./chunk_particle_setup_context.js} because the context setup takes the age
+ * as a value: a caller that already has it (or that has no emitter-state binding at all) pulls in
+ * the setup without pulling in this table read.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_particle_emitter_age: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_particle_emitter_age.d.ts.map