@woosh/meep-engine 3.46.0 → 3.49.0

package/src/shade/renderer/particles/graph/groups/particle_groups_geometry.js

@@ -1,3 +1,4 @@
+import { VM_BUILTIN } from "../../isa/ParticleVMISA.js";
 import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
 import {
     PARTICLE_TYPE_F32,
@@ -292,3 +293,158 @@ export const PARTICLE_GROUP_QUAT_LOOK_ROTATION = (() => {
 
     return g.build();
 })();
+
+/**
+ * Two rotations, one after the other: the turn by `b`, then the turn by `a`.
+ *
+ * The Hamilton product, `(a.w b.xyz + b.w a.xyz + a.xyz × b.xyz, a.w b.w - a.xyz · b.xyz)`, in the
+ * order the engine's `Quaternion.multiplyQuaternions(a, b)` writes it — so turning a vector by the
+ * result is turning it by `b` and then by `a`. Not commutative: swapping the inputs turns about the
+ * other frame.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_MULTIPLY = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "quatMultiply",
+        label: "Multiply Quaternions",
+        icon: "M5 12a5 5 0 1 0 10 0a5 5 0 1 0-10 0 M9 12a5 5 0 1 0 10 0a5 5 0 1 0-10 0",
+        help: "the turn by b, then the turn by a",
+        inputs: [
+            { name: "a", type: PARTICLE_TYPE_VEC4 },
+            { name: "b", type: PARTICLE_TYPE_VEC4 },
+        ],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const av = g.swz(g.in.a, "xyz");
+    const bv = g.swz(g.in.b, "xyz");
+    const aw = g.w(g.in.a);
+    const bw = g.w(g.in.b);
+
+    const vector = g.add(g.add(g.scale(bv, aw), g.scale(av, bw)), g.cross(av, bv));
+    const scalar = g.sub(g.mul(aw, bw), g.dot(av, bv));
+
+    g.out("quat", g.vec4(g.x(vector), g.y(vector), g.z(vector), scalar));
+
+    return g.build();
+})();
+
+/**
+ * An orientation advanced by an angular velocity over a step: `quat` turned by `omega`, in radians
+ * per second about the axis it points along, for `dt` seconds.
+ *
+ * Exact for a constant `omega` at any `dt` — the step is the rotation itself,
+ * `quatFromAxisAngle(omega, |omega| dt)`, composed in front — rather than the first-order
+ * `q + dt/2 (omega, 0) q` a rigid-body solver takes. That one turns by `2 atan(|omega| dt / 2)` instead
+ * of `|omega| dt`, which a solver stepping at a fixed 1/60 never notices, and a particle does: the
+ * warm-up stretches its ticks to cover a whole pre-warm in at most
+ * {@link ../../ParticleConstants.js PARTICLE_WARMUP_MAX_TICKS} of them, 156 ms each for five seconds,
+ * where a 10 rad/s tumble would come out 15% slow. A program does not get to care what `dt` it is
+ * handed.
+ *
+ * `omega` turns in the frame the orientation is in — the world, for a FACING_WORLD emitter — which is
+ * why the step goes in front. The result is renormalised, so a tumble integrated for a minute is
+ * still a unit quaternion and `quatRotate` does not start scaling what it turns. A zero `omega` is
+ * no turn.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_QUAT_INTEGRATE = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "quatIntegrate",
+        label: "Integrate Angular Velocity",
+        icon: "M12 4a8 8 0 1 1-8 8 M4 12l-2-3 M4 12l3-2 M12 12l4-4",
+        help: "an orientation turned by an angular velocity over dt",
+        inputs: [
+            { name: "quat", type: PARTICLE_TYPE_VEC4 },
+            { name: "omega", type: PARTICLE_TYPE_VEC3 },
+            { name: "dt", type: PARTICLE_TYPE_F32 },
+        ],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const step = g.call(PARTICLE_GROUP_QUAT_FROM_AXIS_ANGLE, {
+        axis: g.in.omega,
+        angle: g.mul(g.length(g.in.omega), g.in.dt),
+    }).quat;
+
+    const turned = g.call(PARTICLE_GROUP_QUAT_MULTIPLY, { a: step, b: g.in.quat }).quat;
+
+    g.out("quat", g.normalize(turned));
+
+    return g.build();
+})();
+
+/**
+ * A rotation drawn uniformly from all of them, from three numbers in `[0, 1)`.
+ *
+ * Shoemake's construction ("Uniform random rotations", Graphics Gems III): with `u` the first number,
+ * the quaternion is `(sqrt(1-u) sin 2πv, sqrt(1-u) cos 2πv, sqrt(u) sin 2πw, sqrt(u) cos 2πw)`. It
+ * lands on the unit sphere in four dimensions uniformly, which is what a uniform rotation is. Drawing
+ * three Euler angles uniformly is the tempting wrong one, and clusters the turns.
+ *
+ * Feed it a three-lane `random` and it is a tumbling flake's starting orientation.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_SAMPLE_ROTATION = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "sampleRotation",
+        label: "Sample Rotation",
+        icon: "M12 3a9 9 0 1 0 0 18a9 9 0 1 0 0-18 M7 9l5-4 5 4 M12 5v14",
+        help: "uvw in [0,1) to a rotation, uniformly over all of them",
+        inputs: [{ name: "uvw", type: PARTICLE_TYPE_VEC3 }],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const u = g.x(g.in.uvw);
+
+    // the max guards the rounding at the ends, as the sphere samplers do
+    const first = g.sqrt(g.max(g.sub(1, u), 0));
+    const second = g.sqrt(g.max(u, 0));
+
+    const a = g.mul(g.y(g.in.uvw), g.f(TAU));
+    const b = g.mul(g.z(g.in.uvw), g.f(TAU));
+
+    g.out("quat", g.vec4(
+        g.mul(first, g.sin(a)),
+        g.mul(first, g.cos(a)),
+        g.mul(second, g.sin(b)),
+        g.mul(second, g.cos(b)),
+    ));
+
+    return g.build();
+})();
+
+/**
+ * The emitter's own rotation: the turn that takes the world's axes to its node's.
+ *
+ * The VM hands an effect the node's axes rather than its rotation — `EMITTER_DIRECTION`, which is the
+ * node's forward and so its **-Z**, and `EMITTER_UP`, its +Y — and a look rotation maps **+Z** to the
+ * forward it is given. Wiring the two straight together therefore turns a sprite half a turn and
+ * shows its back. This is that wiring with the sign put right, which is the whole reason it is a
+ * group.
+ *
+ * Write it into a FACING_WORLD particle's orientation at birth and the sprite starts out lying in
+ * its emitter's XY plane, facing the emitter's +Z.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_EMITTER_ROTATION = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "emitterRotation",
+        label: "Emitter Rotation",
+        icon: "M4 20h16 M12 20V8 M12 8l-4 4 M12 8l4 4 M6 4h12",
+        help: "the emitter's own rotation, as a quaternion",
+        inputs: [],
+        outputs: [{ name: "quat", type: PARTICLE_TYPE_VEC4 }],
+    });
+
+    const forward = g.neg(g.builtin(VM_BUILTIN.EMITTER_DIRECTION));
+    const up = g.builtin(VM_BUILTIN.EMITTER_UP);
+
+    g.out("quat", g.call(PARTICLE_GROUP_QUAT_LOOK_ROTATION, { forward, up }).quat);
+
+    return g.build();
+})();

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

@@ -202,8 +202,8 @@ export class ParticleEmitter {
     render_size: number;
     /** @type {number} record word offset of rgba colour */
     render_color: number;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation: number;
+    /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
+    render_orientation: number;
     /** @type {number} record word offset of flipbook frame index */
     render_frame: number;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAiSI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CA+C3B;IApWD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAUV;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;OAUG;IACH,cAHW,eAAe,GACb,OAAO,CAsBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;;OAWG;IACH,YAFW,eAAe,QA6BzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAQ3B;IAyEL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C"}
+{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH;IAiSI;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH;QAfwE,MAAM,EAAnE,OAAO,6BAA6B,EAAE,cAAc;QAEQ,OAAO,EAAnE,OAAO,2BAA2B,EAAE,eAAe;QAExB,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACI,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CA+C3B;IApWD;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAUV;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,gCAIC;IAED;;;;;OAKG;IACH,QAFU,OAAO,6BAA6B,EAAE,cAAc,CAEvD;IAEP;;;;;OAKG;IACH,SAFU,OAAO,2BAA2B,EAAE,eAAe,CAErD;IAER;;;;;;;;;;;OAWG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;OAIG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,4IAA4I;IAC5I,oBADW,MAAM,CAC6B;IAC9C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;OAUG;IACH,cAHW,eAAe,GACb,OAAO,CAsBnB;IAED;;;;;;OAMG;IACH,QAFa,MAAM,CAsBlB;IAED;;;;;;;;;;;OAWG;IACH,YAFW,eAAe,QA6BzB;IAED;;;;OAIG;IACH,SAFa,eAAe,CAQ3B;IAyEL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;;CAN1C"}

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

@@ -14,7 +14,7 @@ import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_E
  * @type {string[]}
  */
 export const EMITTER_RENDER_CHANNELS = Object.freeze([
-    "position", "size", "color", "rotation", "frame", "velocity",
+    "position", "size", "color", "orientation", "frame", "velocity",
 ]);
 
 /**
@@ -34,7 +34,7 @@ export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
     position: 3,
     size: 1,
     color: 4,
-    rotation: 1,
+    orientation: 4,
     frame: 1,
     velocity: 3,
 });
@@ -207,8 +207,8 @@ export class ParticleEmitter {
     render_size = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of rgba colour */
     render_color = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of the orientation, a quaternion (x, y, z, w) turning the sprite inside its projection mode's frame */
+    render_orientation = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of flipbook frame index */
     render_frame = EMITTER_ATTRIBUTE_ABSENT;
     /** @type {number} record word offset of velocity, read by the STRETCHED projection */
@@ -244,7 +244,7 @@ export class ParticleEmitter {
                 case "position": this.render_position = offset; break;
                 case "size": this.render_size = offset; break;
                 case "color": this.render_color = offset; break;
-                case "rotation": this.render_rotation = offset; break;
+                case "orientation": this.render_orientation = offset; break;
                 case "frame": this.render_frame = offset; break;
                 case "velocity": this.render_velocity = offset; break;
                 default:
@@ -282,7 +282,7 @@ export class ParticleEmitter {
             && this.render_position === other.render_position
             && this.render_size === other.render_size
             && this.render_color === other.render_color
-            && this.render_rotation === other.render_rotation
+            && this.render_orientation === other.render_orientation
             && this.render_frame === other.render_frame
             && this.render_velocity === other.render_velocity
             && is_typed_array_equals(this.flipbook, other.flipbook)
@@ -300,7 +300,7 @@ export class ParticleEmitter {
     hash() {
         const bindings = hash_mix3(
             hash_mix3(this.render_position, this.render_size, this.render_color),
-            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
+            hash_mix3(this.render_orientation, this.render_frame, this.render_velocity),
             this.flags
         );
 
@@ -348,7 +348,7 @@ export class ParticleEmitter {
         this.render_position = other.render_position;
         this.render_size = other.render_size;
         this.render_color = other.render_color;
-        this.render_rotation = other.render_rotation;
+        this.render_orientation = other.render_orientation;
         this.render_frame = other.render_frame;
         this.render_velocity = other.render_velocity;
 

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

@@ -1 +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,CAyE6D;0BA/FtD,oCAAoC"}
+{"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,CA2E6D;0BAjGtD,oCAAoC"}

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

@@ -66,8 +66,9 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     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]); }
+    // the identity when the effect binds none
+    var orientation = vec4<f32>(0.0, 0.0, 0.0, 1.0);
+    if (em.render_orientation != PARTICLE_ATTRIBUTE_ABSENT) { orientation = particle_read_vec(base, em.render_orientation, 4u); }
     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);
@@ -79,7 +80,8 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     let cam_position = camera.transform[3].xyz;
 
     let projection = particle_emitter_projection(em.flags);
-    let offset = particle_billboard_offset(corner, size, rotation, cam_right, cam_up, cam_forward, velocity, projection);
+    let basis = particle_basis(orientation, cam_right, cam_up, cam_forward, velocity, projection);
+    let offset = particle_billboard_offset(corner, size, basis);
     let world = world_center + offset;
 
     var out : ParticleVertexOut;
@@ -87,7 +89,7 @@ fn particle_billboard_vertex(vi : u32, ii : u32) -> ParticleVertexOut {
     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 = particle_billboard_normal(offset, cam_position - world, cam_forward, projection);
+    out.normal = particle_billboard_normal(offset, cam_position - world, basis);
     out.view_depth = -(camera.view_matrix * vec4<f32>(world, 1.0)).z;
     out.flags = em.flags;
     out.blend = particle_emitter_blend(em.flags);

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

@@ -2,15 +2,16 @@
  * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
  * unit-tested in isolation (they take no bindings):
  *
- * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
- *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_basis` — where a particle's quad lies in the world: the projection mode's frame
+ *   (camera-facing, velocity-stretched, ground-aligned, axis-locked, world) composed with the
+ *   particle's own orientation, plus the mode's stretch.
+ * - `particle_billboard_offset` — expand a quad corner into a world-space offset on that basis.
  * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
- *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   every orientation and every camera. What a bounds pass has to dilate a particle's centre by to
  *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
  *   pass: the two are one statement, and they drift the moment they are written apart.
- * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the plane
- *   that function lays the quad in, turned to the side the camera sees and bent out toward the
- *   corner.
+ * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the basis's
+ *   face, turned to the side the camera sees and bent out toward the corner.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yCAFU,SAAS,CA8JhB;0BArLuB,oCAAoC"}
+{"version":3,"file":"chunk_particle_render_math.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/shaders/chunk_particle_render_math.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,yCAFU,SAAS,CA6LQ;0BAtND,oCAAoC"}

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

@@ -1,19 +1,21 @@
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_quat_rotate_v3 } from "../../shader/chunk/geometry/quaternion/chunk_v3_apply_quat.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../data/PARTICLE_EMITTER_STRUCT.js";
 
 /**
  * Pure render-math helpers shared by every pass that draws a particle, kept separate so they can be
  * unit-tested in isolation (they take no bindings):
  *
- * - `particle_billboard_offset` — expand a quad corner into a world-space offset for each projection
- *   / orientation mode (camera-facing, velocity-stretched, ground-aligned, axis-locked, world).
+ * - `particle_basis` — where a particle's quad lies in the world: the projection mode's frame
+ *   (camera-facing, velocity-stretched, ground-aligned, axis-locked, world) composed with the
+ *   particle's own orientation, plus the mode's stretch.
+ * - `particle_billboard_offset` — expand a quad corner into a world-space offset on that basis.
  * - `particle_billboard_radius` — the largest offset that function can return, over every corner,
- *   every roll angle and every camera. What a bounds pass has to dilate a particle's centre by to
+ *   every orientation and every camera. What a bounds pass has to dilate a particle's centre by to
  *   hold its quad, and the reason it sits next to the function it bounds rather than with the bounds
  *   pass: the two are one statement, and they drift the moment they are written apart.
- * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the plane
- *   that function lays the quad in, turned to the side the camera sees and bent out toward the
- *   corner.
+ * - `particle_billboard_normal` — the normal a lit particle is shaded with at a corner: the basis's
+ *   face, turned to the side the camera sees and bent out toward the corner.
  * - `particle_atlas_uv` — map a local quad uv into an atlas sub-rect, honouring a flipbook grid +
  *   frame index (mirrors meep's AtlasPatch offset/scale convention).
  * - `particle_soft_fade` — soft-particle alpha fade from scene-vs-particle view depth.
@@ -36,65 +38,108 @@ const PARTICLE_BLEND_ALPHA : u32 = ${EMITTER_BLEND.ALPHA}u;
 const PARTICLE_BLEND_ADDITIVE : u32 = ${EMITTER_BLEND.ADDITIVE}u;
 const PARTICLE_BLEND_PREMULTIPLIED : u32 = ${EMITTER_BLEND.PREMULTIPLIED}u;
 
-// Expand a quad corner (components in {-1,+1}) into a world-space offset from the particle centre.
-fn particle_billboard_offset(
-    corner : vec2<f32>,
-    size : f32,
-    rotation : f32,
+// Where a particle's quad lies in the world: the directions its own +X, +Y and +Z point once the
+// projection mode's frame and the particle's orientation are composed, and how far the mode
+// elongates the sprite along its own +Y.
+struct ParticleBasis {
+    right : vec3<f32>,
+    up : vec3<f32>,
+    face : vec3<f32>,
+    stretch : f32,
+}
+
+// A unit quaternion out of whatever a program wrote. A program integrating a spin drifts off unit
+// length, and an unnormalised quaternion turns a vector by its rotation AND scales it by its squared
+// length — the drift would show as size. The zero quaternion stays zero, which quat_rotate_v3 reads
+// as no rotation at all, so an attribute nobody wrote yet is the identity rather than a NaN.
+fn particle_orientation_unit(q : vec4<f32>) -> vec4<f32> {
+    return q * inverseSqrt(max(dot(q, q), 1e-30));
+}
+
+// The basis a projection mode lays a particle's quad on.
+//
+// A mode contributes a frame and nothing else: a proper rotation whose x and y are the screen's
+// right and up for BILLBOARD, and whose z is the side the mode shows — toward the eye for the
+// camera-facing modes, world +Y for HORIZONTAL, world +Z for FACING_WORLD — so the sprite reads the
+// way round BILLBOARD draws it from that side rather than as its mirror image. STRETCHED adds its
+// elongation, which belongs to the sprite and stretches it along its own +Y.
+//
+// The particle's orientation is a rotation inside that frame. FACING_WORLD's frame is the world's,
+// so there it is the particle's rotation in the world; BILLBOARD's is the view's, so there it turns
+// the quad relative to the eye — a rotation about +Z is a roll on the screen. The frame is the one
+// part that depends on a view, which is why it is the renderer's and the rotation is the record's:
+// one record is drawn by every view, and no rotation written into it could face them all.
+fn particle_basis(
+    orientation : vec4<f32>,
     cam_right : vec3<f32>,
     cam_up : vec3<f32>,
     cam_forward : vec3<f32>,
     velocity_ws : vec3<f32>,
     projection : u32,
-) -> vec3<f32> {
-    // In-plane roll about the view direction.
-    let cr = cos(rotation);
-    let sr = sin(rotation);
-    let rc = vec2<f32>(corner.x * cr - corner.y * sr, corner.x * sr + corner.y * cr);
-
+) -> ParticleBasis {
     var right = cam_right;
     var up = cam_up;
+    var stretch = 1.0;
 
     if (projection == PARTICLE_PROJ_HORIZONTAL) {
+        // faces world +Y: seen from above with -Z at the top of the screen, it reads as on the page
         right = vec3<f32>(1.0, 0.0, 0.0);
-        up = vec3<f32>(0.0, 0.0, 1.0);
+        up = vec3<f32>(0.0, 0.0, -1.0);
     } else if (projection == PARTICLE_PROJ_VERTICAL) {
         up = vec3<f32>(0.0, 1.0, 0.0);
-        let r = cross(up, cam_forward);
+        let r = cross(cam_forward, up);
         let rl = length(r);
         right = select(vec3<f32>(1.0, 0.0, 0.0), r / rl, rl > 1e-5);
     } else if (projection == PARTICLE_PROJ_STRETCHED) {
-        // Align the quad's local Y with the screen-projected velocity and elongate it by the
-        // projected speed (a particle moving 2 units/s draws 3x as long as it is wide).
+        // Align the sprite's +Y with the screen-projected velocity and elongate it by the projected
+        // speed (a particle moving 2 units/s draws 3x as long as it is wide).
         let v_screen = vec2<f32>(dot(velocity_ws, cam_right), dot(velocity_ws, cam_up));
         let vl = length(v_screen);
         let dir = select(vec2<f32>(0.0, 1.0), v_screen / vl, vl > 1e-5);
-        let perp = vec2<f32>(-dir.y, dir.x);
-        let local = perp * rc.x + dir * rc.y * (1.0 + vl);
-        return (cam_right * local.x + cam_up * local.y) * size;
+        // the direction turned clockwise on the screen, so (right, up) is the camera's at rest
+        right = cam_right * dir.y - cam_up * dir.x;
+        up = cam_right * dir.x + cam_up * dir.y;
+        stretch = 1.0 + vl;
     } else if (projection == PARTICLE_PROJ_FACING_WORLD) {
-        // Fixed world-space orientation: the quad lies in the world XY plane (faces +/-Z) and the
-        // rotation attribute rolls it in that plane — independent of the camera.
         right = vec3<f32>(1.0, 0.0, 0.0);
         up = vec3<f32>(0.0, 1.0, 0.0);
     }
 
-    return (right * rc.x + up * rc.y) * size;
+    let face = cross(right, up);
+
+    // the orientation, as where it sends the sprite's own three axes
+    let q = particle_orientation_unit(orientation);
+    let ox = quat_rotate_v3(q, vec3<f32>(1.0, 0.0, 0.0));
+    let oy = quat_rotate_v3(q, vec3<f32>(0.0, 1.0, 0.0));
+    let oz = quat_rotate_v3(q, vec3<f32>(0.0, 0.0, 1.0));
+
+    var basis : ParticleBasis;
+    basis.right = right * ox.x + up * ox.y + face * ox.z;
+    basis.up = right * oy.x + up * oy.y + face * oy.z;
+    basis.face = right * oz.x + up * oz.y + face * oz.z;
+    basis.stretch = stretch;
+    return basis;
+}
+
+// Expand a quad corner (components in {-1,+1}) into a world-space offset from the particle centre.
+fn particle_billboard_offset(corner : vec2<f32>, size : f32, basis : ParticleBasis) -> vec3<f32> {
+    return (basis.right * corner.x + basis.up * (corner.y * basis.stretch)) * size;
 }
 
 // The radius of the sphere holding every offset particle_billboard_offset can return for a particle
-// of this size, velocity and projection — over all four corners, every roll angle, and any camera.
+// of this size, velocity and projection — over all four corners, every orientation, and any camera.
 //
-// A corner is (±1, ±1), so a rolled corner \`rc\` has |rc| = sqrt(2) whatever the angle: rotation
-// moves a corner around the quad's circumcircle, it does not shrink it. Every mode then lays \`rc\`
-// down on two orthonormal axes and scales by \`size\`, which makes |offset| = sqrt(2) * size exactly
-// — camera-facing, ground-aligned, axis-locked and world-facing alike, because "which two unit
-// axes" is the only thing that separates them.
+// A corner is (±1, ±1), so |corner| = sqrt(2). Every mode lays it on its basis, which is a rotation —
+// the mode's frame composed with the particle's orientation, both rotations — and scales it by
+// \`size\`, which makes |offset| = sqrt(2) * size exactly: camera-facing, ground-aligned, axis-locked
+// and world-facing alike, whatever way the particle is turned, because a rotation moves a corner
+// around a sphere and never off it. The orientation is therefore not an argument here, and the
+// bounds pass never reads it.
 //
-// STRETCHED is the one that reaches further: it elongates the corner along the screen-space
-// velocity by (1 + |v_screen|) before the same two axes. |v_screen| is a projection of the world
-// velocity onto two orthonormal axes and so is at most |v|, which is what makes the world-space
-// speed the camera-independent bound this needs to be.
+// STRETCHED is the one that reaches further: it elongates the sprite along its own +Y by
+// (1 + |v_screen|) before the rotation, which moves no corner further than that factor.
+// |v_screen| is a projection of the world velocity onto two orthonormal axes and so is at most |v|,
+// which is what makes the world-space speed the camera-independent bound this needs to be.
 //
 // Camera-independent is the requirement, not a nicety: the box this feeds is measured over one
 // frame and read on the next, by which time the camera has moved.
@@ -115,26 +160,14 @@ const PARTICLE_NORMAL_CURVATURE : f32 = 1.0;
 
 // The shading normal at a corner that particle_billboard_offset put at offset from the centre.
 //
-// Each projection mode lays the quad on two fixed axes, and the face normal is theirs: the camera
-// plane for BILLBOARD and STRETCHED, world up for HORIZONTAL, the camera direction flattened onto
-// the ground for VERTICAL (world Z when the camera looks straight down, as the offset falls back to
-// world X there), world Z for FACING_WORLD. A quad has two sides and is drawn from both, so the face
-// is turned toward to_camera, the vector from the corner to the eye, not the camera's axis: a
-// camera tilted up at a quad lying on the ground below it still sees its top.
-fn particle_billboard_normal(offset : vec3<f32>, to_camera : vec3<f32>, cam_forward : vec3<f32>, projection : u32) -> vec3<f32> {
-    var face = -cam_forward;
-
-    if (projection == PARTICLE_PROJ_HORIZONTAL) {
-        face = vec3<f32>(0.0, 1.0, 0.0);
-    } else if (projection == PARTICLE_PROJ_VERTICAL) {
-        let horizontal = vec3<f32>(cam_forward.x, 0.0, cam_forward.z);
-        let hl = length(horizontal);
-        face = select(vec3<f32>(0.0, 0.0, 1.0), horizontal / hl, hl > 1e-5);
-    } else if (projection == PARTICLE_PROJ_FACING_WORLD) {
-        face = vec3<f32>(0.0, 0.0, 1.0);
-    }
-
-    face = select(face, -face, dot(face, to_camera) < 0.0);
+// The face is the basis's own: the same frame and orientation that laid the quad down, so the two
+// cannot disagree about which way a mode faces. A stretch scales the sprite along a direction in
+// its own plane, which leaves the plane — and so the face — where it was. A quad has two sides and
+// is drawn from both, so the face is turned toward to_camera, the vector from the corner to the eye,
+// not the camera's axis: a camera tilted up at a quad lying on the ground below it still sees its
+// top.
+fn particle_billboard_normal(offset : vec3<f32>, to_camera : vec3<f32>, basis : ParticleBasis) -> vec3<f32> {
+    let face = select(basis.face, -basis.face, dot(basis.face, to_camera) < 0.0);
 
     // a zero-size particle has no corner to lean toward
     let ol = length(offset);
@@ -179,4 +212,4 @@ fn particle_premultiply(color : vec4<f32>, blend : u32) -> vec4<f32> {
     }
     return vec4<f32>(color.rgb * color.a, color.a);
 }
-`);
+`, [chunk_quat_rotate_v3]);

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;GAcG;AACH;IA8EI;;;OAGG;IACH,sBAFW,eAAe,EAkBzB;IAhGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IA+NtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;;OAOG;IACH;QAJmC,IAAI,EAA5B,cAAc;QACM,KAAK,EAAzB,UAAU;QACR,MAAM,CA0JlB;;CACJ;yBAzcY,OAAO,8DAA8D,EAAE,UAAU;8BAIjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc"}
+{"version":3,"file":"AccumulatingPathTracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;GAcG;AACH;IAoFI;;;OAGG;IACH,sBAFW,eAAe,EAmBzB;IAvGD;;;;OAIG;IACH,kBAFU,MAAM,CAEO;IAEvB;;;;OAIG;IACH,wBAFU,MAAM,CAEc;IAE9B;;;;OAIG;IACH,eAFU,OAAO,CAEK;IAsOtB;;;;;;;OAOG;IACH,+BAgBC;IAED;;;;;;;OAOG;IACH;QAJmC,IAAI,EAA5B,cAAc;QACM,KAAK,EAAzB,UAAU;QACR,MAAM,CA4JlB;;CACJ;yBAldY,OAAO,8DAA8D,EAAE,UAAU;8BAIjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc"}

package/src/shade/renderer/path_tracer/accumulating/AccumulatingPathTracer.js

@@ -6,6 +6,7 @@ import { GPUTextureContext } from "../../texture/GPUTextureContext.js";
 import { graph_flood_fill } from "./graph_flood_fill.js";
 import { graph_float32rgba_to_float16rgba } from "./graph_float32rgba_to_float16rgba.js";
 import { shader_accumulating_path_tracer } from "./shader_accumulating_path_tracer.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 
 /**
  * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
@@ -98,6 +99,12 @@ export class AccumulatingPathTracer {
     /** @type {GPUDevice} */
     #device;
 
+    /**
+     * For the sampler cache: the volumes' noise atlas is sampled through a shared sampler.
+     * @type {GraphicsContext}
+     */
+    #graphics;
+
     /**
      * Cached zero-filled CPU buffer used to clear ping-pong textures via
      * `queue.writeTexture`. Lazily grown to fit the current resolution.
@@ -120,6 +127,7 @@ export class AccumulatingPathTracer {
         assert.defined(graphics, 'graphics');
 
         this.#device = graphics.device;
+        this.#graphics = graphics;
 
         for (let i = 0; i < 2; i++) {
             const t = new GPUTextureContext(graphics.device);
@@ -424,6 +432,8 @@ export class AccumulatingPathTracer {
 
                     light_data: scene_ctx.lights.buffer_data,
                     tEnvironment: view.scene.lights.environment.obtainView(),
+                    tParticipatingMediaNoise: view.scene.volumetrics.noise_atlas.texture.obtainView(),
+                    sParticipatingMediaNoise: this.#graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
 
                     settings,
                     camera: view.camera.gpu_buffer,

package/src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAkBA,2DAKG;AA+EH,4DAIG;6BAxG0B,mCAAmC;8BAOlC,+BAA+B"}
+{"version":3,"file":"shader_accumulating_path_tracer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js"],"names":[],"mappings":"AAmBA,2DAKG;AAkFH,4DAIG;6BA5G0B,mCAAmC;8BAOlC,+BAA+B"}

package/src/shade/renderer/path_tracer/accumulating/shader_accumulating_path_tracer.js

@@ -13,6 +13,7 @@ import { sr_create_group_RTX } from "../../geometry/sr_create_group_RTX.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
 import { MEDIA_TABLE_STRUCT } from "../../medium/MEDIA_TABLE_STRUCT.js";
 import { chunk_render_trace_path } from "../shader/chunk_render_trace_path.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 
 const resources = new ShaderResourceSetDescriptor();
 
@@ -36,7 +37,10 @@ resources.createGroup()
 
 resources.createGroup()
     .addStorageBuffer("light_data", WebGPUArray.u32)
-    .addTexture("tEnvironment", "unfilterable-float", "2d");
+    .addTexture("tEnvironment", "unfilterable-float", "2d")
+    // the fog volumes' noise, read through participating_media_volume_density_at
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR);
 
 resources.createGroup()
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)

package/src/shade/renderer/path_tracer/graph_path_trace_scene.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAkGA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACD,IAAI;IAC1B,MAAM,CAqFlB"}
+{"version":3,"file":"graph_path_trace_scene.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/path_tracer/graph_path_trace_scene.js"],"names":[],"mappings":"AAsGA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACD,IAAI;IAC1B,MAAM,CAuFlB"}

package/src/shade/renderer/path_tracer/graph_path_trace_scene.js

@@ -16,6 +16,7 @@ import { sr_create_group_RTX } from "../geometry/sr_create_group_RTX.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
 import { MEDIA_TABLE_STRUCT } from "../medium/MEDIA_TABLE_STRUCT.js";
 import { chunk_render_trace_path } from "./shader/chunk_render_trace_path.js";
+import { PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR } from "../volumetrics/noise/PARTICIPATING_MEDIA_NOISE.js";
 
 const RAY_TRACING_UNIFORMS_STRUCT = WebGPUStruct.from({
     random_seed: u32
@@ -33,6 +34,9 @@ resources.createGroup()
 resources.createGroup()
     .addStorageBuffer("light_data", WebGPUArray.u32)
     .addTexture("tEnvironment", "unfilterable-float", "2d")
+    // the fog volumes' noise, read through participating_media_volume_density_at
+    .addTexture("tParticipatingMediaNoise", "float", "3d")
+    .addSampler("sParticipatingMediaNoise", "filtering", PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR)
 
 resources.createGroup()
     .addUniform("common_uniforms", RAY_TRACING_UNIFORMS_STRUCT)
@@ -166,6 +170,8 @@ export function graph_path_trace_scene({
                 //
                 light_data: scene_ctx.lights.buffer_data,
                 tEnvironment: view.scene.lights.environment.obtainView(),
+                tParticipatingMediaNoise: scene_ctx.volumetrics.noise_atlas.texture.obtainView(),
+                sParticipatingMediaNoise: graphics.samplers.obtain(PARTICIPATING_MEDIA_NOISE_SAMPLER_DESCRIPTOR),
 
                 common_uniforms: rt_uniforms,
                 camera: view.camera.gpu_buffer,