babylon.quarks 0.26.0 → 0.27.0

package/src/shaders/stretched_bb_particle_vert.glsl.ts

@@ -1,4 +1,5 @@
 import {fogVertexDeclarationGLSL, fogVertexGLSL} from './chunks/fog';
+import {sheetVertexDeclarationGLSL, sheetVertexGLSL} from './chunks/sheet';
 
 export default /* glsl */ `
 // Per-vertex attributes
@@ -17,12 +18,7 @@ attribute vec4 velocity;
 uniform mat4 world;
 uniform mat4 view;
 uniform mat4 projection;
-uniform float speedFactor;
-
-#ifdef UV_TILE
-uniform float tileCountX;
-uniform float tileCountY;
-#endif
+${sheetVertexDeclarationGLSL}
 
 #ifdef PIVOT
 // Streak offset in particle-size units: x from head to tail, y across.
@@ -36,10 +32,6 @@ varying vec4 vColor;
 // The particle's own UV, never moved by the sheet (UV channel 1).
 varying vec2 vUV1;
 #endif
-#ifdef TILE_BLEND
-varying vec2 vUV2;
-varying float vTileBlend;
-#endif
 #ifdef SOFT_PARTICLES
 varying vec4 projPosition;
 varying float linearDepth;
@@ -61,15 +53,11 @@ void main() {
     float vlength = length(viewVelocity);
     // Stretch direction is the velocity direction; only a genuinely motionless particle has none.
     // Deriving it via normalize keeps the stretch aligned even when the speed contribution is ~0
-    // (e.g. speedFactor 0), instead of collapsing the whole burst onto a fixed screen axis.
+    // (e.g. a speed factor of 0), instead of collapsing the whole burst onto a fixed screen axis.
     vec3 vdir = vlength > 0.000001 ? viewVelocity / vlength : vec3(0.0, 0.0, 1.0);
-#ifdef BEAM
-    // Seen straight along its length a beam has no side to face; any will do.
+    // Seen straight along its length a streak has no side to face; any will do.
     vec3 sideRaw = cross(mvPosition.xyz, vdir);
     vec3 side = dot(sideRaw, sideRaw) > 1e-12 ? normalize(sideRaw) : vec3(1.0, 0.0, 0.0);
-#else
-    vec3 side = normalize(cross(mvPosition.xyz, vdir));
-#endif
 #ifdef SIZE_LIMITS
     // The streak's width on screen as a fraction of the viewport height, held
     // between the limits; a perspective projection divides by the view depth.
@@ -98,25 +86,11 @@ ${fogVertexGLSL('mvPosition.xyz')}
     vec2 quadUV = vec2(size.x < 0.0 ? 1.0 - uv.x : uv.x, size.y < 0.0 ? 1.0 - uv.y : uv.y);
 #ifdef SOFT_PARTICLES
     projPosition = gl_Position;
-    linearDepth = -mvPosition.z;
+    // View depth is +z ahead of a left-handed camera and -z ahead of a right-handed one.
+    linearDepth = abs(mvPosition.z);
 #endif
 
-    #ifdef UV_TILE
-        vec2 tc = vec2(tileCountX, tileCountY);
-        float baseTile = floor(uvTile);
-        float tileU = mod(baseTile, tc.x) / tc.x;
-        float tileV = 1.0 - floor(baseTile / tc.x) / tc.y - 1.0 / tc.y;
-        vUV = quadUV / tc + vec2(tileU, tileV);
-        #ifdef TILE_BLEND
-            float nextTile = ceil(uvTile);
-            float nextU = mod(nextTile, tc.x) / tc.x;
-            float nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;
-            vUV2 = quadUV / tc + vec2(nextU, nextV);
-            vTileBlend = fract(uvTile);
-        #endif
-    #else
-        vUV = quadUV;
-    #endif
+${sheetVertexGLSL('quadUV')}
 
 #ifdef UV1
     vUV1 = quadUV;

package/src/shaders/stretched_bb_particle_vert.wgsl.ts

@@ -1,4 +1,5 @@
 import {fogVertexDeclarationWGSL, fogVertexWGSL} from './chunks/fog';
+import {sheetVertexDeclarationWGSL, sheetVertexWGSL} from './chunks/sheet';
 
 export default /* wgsl */ `
 // Per-vertex attributes
@@ -17,12 +18,7 @@ attribute velocity: vec4f;
 uniform world: mat4x4f;
 uniform view: mat4x4f;
 uniform projection: mat4x4f;
-uniform speedFactor: f32;
-
-#ifdef UV_TILE
-uniform tileCountX: f32;
-uniform tileCountY: f32;
-#endif
+${sheetVertexDeclarationWGSL}
 
 #ifdef PIVOT
 // Streak offset in particle-size units: x from head to tail, y across.
@@ -36,10 +32,6 @@ varying vColor: vec4f;
 // The particle's own UV, never moved by the sheet (UV channel 1).
 varying vUV1: vec2f;
 #endif
-#ifdef TILE_BLEND
-varying vUV2: vec2f;
-varying vTileBlend: f32;
-#endif
 #ifdef SOFT_PARTICLES
 varying projPosition: vec4f;
 varying linearDepth: f32;
@@ -64,21 +56,17 @@ fn main(input: VertexInputs) -> FragmentInputs {
     let vlength = length(viewVelocity);
     // Stretch direction is the velocity direction; only a genuinely motionless particle has none.
     // Deriving it via normalize keeps the stretch aligned even when the speed contribution is ~0
-    // (e.g. speedFactor 0), instead of collapsing the whole burst onto a fixed screen axis.
+    // (e.g. a speed factor of 0), instead of collapsing the whole burst onto a fixed screen axis.
     var vdir = vec3f(0.0, 0.0, 1.0);
     if (vlength > 0.000001) {
         vdir = viewVelocity / vlength;
     }
-#ifdef BEAM
-    // Seen straight along its length a beam has no side to face; any will do.
+    // Seen straight along its length a streak has no side to face; any will do.
     let sideRaw = cross(mvPosition.xyz, vdir);
     var side = vec3f(1.0, 0.0, 0.0);
     if (dot(sideRaw, sideRaw) > 1e-12) {
         side = normalize(sideRaw);
     }
-#else
-    let side = normalize(cross(mvPosition.xyz, vdir));
-#endif
 #ifdef SIZE_LIMITS
     // The streak's width on screen as a fraction of the viewport height, held
     // between the limits; a perspective projection divides by the view depth.
@@ -113,25 +101,11 @@ ${fogVertexWGSL('mvPosition.xyz')}
     let quadUV = select(vertexInputs.uv, 1.0 - vertexInputs.uv, vertexInputs.size.xy < vec2f(0.0));
 #ifdef SOFT_PARTICLES
     vertexOutputs.projPosition = clipPosition;
-    vertexOutputs.linearDepth = -mvPosition.z;
+    // View depth is +z ahead of a left-handed camera and -z ahead of a right-handed one.
+    vertexOutputs.linearDepth = abs(mvPosition.z);
 #endif
 
-    #ifdef UV_TILE
-        let tc = vec2f(uniforms.tileCountX, uniforms.tileCountY);
-        let baseTile = floor(vertexInputs.uvTile);
-        let tileU = (baseTile % tc.x) / tc.x;
-        let tileV = 1.0 - floor(baseTile / tc.x) / tc.y - 1.0 / tc.y;
-        vertexOutputs.vUV = quadUV / tc + vec2f(tileU, tileV);
-        #ifdef TILE_BLEND
-            let nextTile = ceil(vertexInputs.uvTile);
-            let nextU = (nextTile % tc.x) / tc.x;
-            let nextV = 1.0 - floor(nextTile / tc.x) / tc.y - 1.0 / tc.y;
-            vertexOutputs.vUV2 = quadUV / tc + vec2f(nextU, nextV);
-            vertexOutputs.vTileBlend = fract(vertexInputs.uvTile);
-        #endif
-    #else
-        vertexOutputs.vUV = quadUV;
-    #endif
+${sheetVertexWGSL('quadUV')}
 
 #ifdef UV1
     vertexOutputs.vUV1 = quadUV;

package/src/shaders/trail_frag.glsl.ts

@@ -1,4 +1,5 @@
 import {fogFragmentDeclarationGLSL, fogFragmentGLSL} from './chunks/fog';
+import {softFragmentDeclarationGLSL, softFragmentGLSL} from './chunks/soft';
 import {surfaceColorGLSL, surfaceFragmentDeclarationGLSL} from './chunks/surface';
 
 export default /* glsl */ `
@@ -12,13 +13,22 @@ varying vec2 vUV1;
 uniform sampler2D map;
 #endif
 
+#ifdef USE_ALPHATEST
+uniform float alphaTest;
+#endif
+
 ${fogFragmentDeclarationGLSL}
+${softFragmentDeclarationGLSL}
 ${surfaceFragmentDeclarationGLSL}
 void main() {
 ${surfaceColorGLSL(false)}
+#ifdef USE_ALPHATEST
+    if (baseColor.a < alphaTest) discard;
+#else
     if (baseColor.a < 0.01) discard;
+#endif
 
 ${fogFragmentGLSL('baseColor.rgb')}
     gl_FragColor = baseColor;
-}
+${softFragmentGLSL('gl_FragColor')}}
 `;

package/src/shaders/trail_frag.wgsl.ts

@@ -1,4 +1,5 @@
 import {fogFragmentDeclarationWGSL, fogFragmentWGSL} from './chunks/fog';
+import {softFragmentDeclarationWGSL, softFragmentWGSL} from './chunks/soft';
 import {surfaceColorWGSL, surfaceFragmentDeclarationWGSL} from './chunks/surface';
 
 export default /* wgsl */ `
@@ -13,14 +14,24 @@ var mapSampler: sampler;
 var map: texture_2d<f32>;
 #endif
 
+#ifdef USE_ALPHATEST
+uniform alphaTest: f32;
+#endif
+
 ${fogFragmentDeclarationWGSL}
+${softFragmentDeclarationWGSL}
 ${surfaceFragmentDeclarationWGSL}
 @fragment
 fn main(input: FragmentInputs) -> FragmentOutputs {
 ${surfaceColorWGSL(false)}
+#ifdef USE_ALPHATEST
+    if (baseColor.a < uniforms.alphaTest) { discard; }
+#else
     if (baseColor.a < 0.01) { discard; }
+#endif
 
 ${fogFragmentWGSL('baseColor')}
+${softFragmentWGSL('baseColor')}
     fragmentOutputs.color = baseColor;
 }
 `;

package/src/shaders/trail_vert.glsl.ts

@@ -11,9 +11,6 @@ attribute vec4 color;
 
 uniform mat4 view;
 uniform mat4 projection;
-uniform float lineWidth;
-uniform vec2 resolution;
-uniform float sizeAttenuation;
 
 varying vec2 vUV;
 varying vec4 vColor;
@@ -23,44 +20,56 @@ attribute vec2 uv2;
 varying vec2 vUV1;
 #endif
 
-vec2 fix(vec4 i, float aspect) {
-    vec2 res = i.xy / i.w;
-    res.x *= aspect;
-    return res;
+#ifdef SOFT_PARTICLES
+varying vec4 projPosition;
+varying float linearDepth;
+#endif
+
+// The unit tangent of a segment, or zero for a segment of no length.
+vec3 trailDirection(vec3 d) {
+    float l = dot(d, d);
+    return l > 1e-12 ? d * inversesqrt(l) : vec3(0.0);
+}
+
+// The direction a ribbon point is widened along, in view space: across the trail's tangent and
+// the line of sight, as Unity's View alignment and Niagara's ribbon facing do. Stays finite at
+// repeated points, at a hairpin and for a segment pointing at the camera.
+vec3 trailSide(vec3 previousPoint, vec3 point, vec3 nextPoint) {
+    vec3 incoming = trailDirection(point - previousPoint);
+    vec3 outgoing = trailDirection(nextPoint - point);
+    vec3 tangent = incoming + outgoing;
+    if (dot(tangent, tangent) < 1e-6) {
+        // A hairpin turns the two directions against each other: face the way it now goes.
+        tangent = dot(outgoing, outgoing) > 0.0 ? outgoing : incoming;
+    }
+    // The line of sight: to the point for a perspective camera, the view axis for an orthographic one.
+    vec3 sight = projection[3][3] > 0.5 ? vec3(0.0, 0.0, 1.0) : point;
+    vec3 side = cross(tangent, sight);
+    if (dot(side, side) < 1e-12) {
+        side = cross(tangent, vec3(0.0, 0.0, 1.0));
+    }
+    if (dot(side, side) < 1e-12) {
+        side = vec3(1.0, 0.0, 0.0);
+    }
+    return normalize(side);
 }
 
 ${fogVertexDeclarationGLSL}
 void main() {
-    float aspect = resolution.x / resolution.y;
-    vec4 finalPosition = projection * view * vec4(position, 1.0);
-    vec4 prevPos = projection * view * vec4(previous, 1.0);
-    vec4 nextPos = projection * view * vec4(next, 1.0);
-
-    vec2 currentP = fix(finalPosition, aspect);
-    vec2 prevP = fix(prevPos, aspect);
-    vec2 nextP = fix(nextPos, aspect);
-
-    float w = lineWidth * width;
-    vec2 dir;
-    if (distance(nextP, currentP) < 0.0001) {
-        dir = normalize(currentP - prevP);
-    } else if (distance(prevP, currentP) < 0.0001) {
-        dir = normalize(nextP - currentP);
-    } else {
-        vec2 dir1 = normalize(currentP - prevP);
-        vec2 dir2 = normalize(nextP - currentP);
-        dir = normalize(dir1 + dir2);
+    vec3 point = (view * vec4(position, 1.0)).xyz;
+    // A swept trail lays its vertices out on the CPU and gives them no width.
+    if (width > 0.0) {
+        vec3 previousPoint = (view * vec4(previous, 1.0)).xyz;
+        vec3 nextPoint = (view * vec4(next, 1.0)).xyz;
+        point += trailSide(previousPoint, point, nextPoint) * (0.5 * width * side);
     }
-    vec4 normal = vec4(-dir.y, dir.x, 0.0, 1.0);
-    normal.xy *= 0.5 * w;
-    normal *= projection;
-    if (sizeAttenuation == 0.0) {
-        normal.xy *= finalPosition.w;
-        normal.xy /= (vec4(resolution, 0.0, 1.0) * projection).xy;
-    }
-    finalPosition.xy += normal.xy * side;
-    gl_Position = finalPosition;
-${fogVertexGLSL('(view * vec4(position, 1.0)).xyz')}
+    gl_Position = projection * vec4(point, 1.0);
+${fogVertexGLSL('point')}
+#ifdef SOFT_PARTICLES
+    projPosition = gl_Position;
+    // View depth is +z ahead of a left-handed camera and -z ahead of a right-handed one.
+    linearDepth = abs(point.z);
+#endif
     vUV = uv;
 #ifdef UV1
     vUV1 = uv2;

package/src/shaders/trail_vert.wgsl.ts

@@ -11,9 +11,6 @@ attribute color: vec4f;
 
 uniform view: mat4x4f;
 uniform projection: mat4x4f;
-uniform lineWidth: f32;
-uniform resolution: vec2f;
-uniform sizeAttenuation: f32;
 
 varying vUV: vec2f;
 varying vColor: vec4f;
@@ -23,49 +20,58 @@ attribute uv2: vec2f;
 varying vUV1: vec2f;
 #endif
 
-fn fix(i: vec4f, aspect: f32) -> vec2f {
-    var res = i.xy / i.w;
-    res.x *= aspect;
-    return res;
+#ifdef SOFT_PARTICLES
+varying projPosition: vec4f;
+varying linearDepth: f32;
+#endif
+
+// The unit tangent of a segment, or zero for a segment of no length.
+fn trailDirection(d: vec3f) -> vec3f {
+    let l = dot(d, d);
+    return select(vec3f(0.0), d * inverseSqrt(max(l, 1e-24)), l > 1e-12);
+}
+
+// The direction a ribbon point is widened along, in view space: across the trail's tangent and
+// the line of sight, as Unity's View alignment and Niagara's ribbon facing do. Stays finite at
+// repeated points, at a hairpin and for a segment pointing at the camera.
+fn trailSide(previousPoint: vec3f, point: vec3f, nextPoint: vec3f) -> vec3f {
+    let incoming = trailDirection(point - previousPoint);
+    let outgoing = trailDirection(nextPoint - point);
+    var tangent = incoming + outgoing;
+    if (dot(tangent, tangent) < 1e-6) {
+        // A hairpin turns the two directions against each other: face the way it now goes.
+        tangent = select(incoming, outgoing, dot(outgoing, outgoing) > 0.0);
+    }
+    // The line of sight: to the point for a perspective camera, the view axis for an orthographic one.
+    let sight = select(point, vec3f(0.0, 0.0, 1.0), uniforms.projection[3][3] > 0.5);
+    var side = cross(tangent, sight);
+    if (dot(side, side) < 1e-12) {
+        side = cross(tangent, vec3f(0.0, 0.0, 1.0));
+    }
+    if (dot(side, side) < 1e-12) {
+        side = vec3f(1.0, 0.0, 0.0);
+    }
+    return normalize(side);
 }
 
 ${fogVertexDeclarationWGSL}
 @vertex
 fn main(input: VertexInputs) -> FragmentInputs {
-    let aspect = uniforms.resolution.x / uniforms.resolution.y;
-    var finalPosition = uniforms.projection * uniforms.view * vec4f(vertexInputs.position, 1.0);
-    let prevPos = uniforms.projection * uniforms.view * vec4f(vertexInputs.previous, 1.0);
-    let nextPos = uniforms.projection * uniforms.view * vec4f(vertexInputs.next, 1.0);
-
-    let currentP = fix(finalPosition, aspect);
-    let prevP = fix(prevPos, aspect);
-    let nextP = fix(nextPos, aspect);
-
-    let w = uniforms.lineWidth * vertexInputs.width;
-    var dir: vec2f;
-    if (distance(nextP, currentP) < 0.0001) {
-        dir = normalize(currentP - prevP);
-    } else if (distance(prevP, currentP) < 0.0001) {
-        dir = normalize(nextP - currentP);
-    } else {
-        let dir1 = normalize(currentP - prevP);
-        let dir2 = normalize(nextP - currentP);
-        dir = normalize(dir1 + dir2);
+    var point = (uniforms.view * vec4f(vertexInputs.position, 1.0)).xyz;
+    // A swept trail lays its vertices out on the CPU and gives them no width.
+    if (vertexInputs.width > 0.0) {
+        let previousPoint = (uniforms.view * vec4f(vertexInputs.previous, 1.0)).xyz;
+        let nextPoint = (uniforms.view * vec4f(vertexInputs.next, 1.0)).xyz;
+        point += trailSide(previousPoint, point, nextPoint) * (0.5 * vertexInputs.width * vertexInputs.side);
     }
-    var normal = vec4f(-dir.y, dir.x, 0.0, 1.0);
-    normal.x *= 0.5 * w;
-    normal.y *= 0.5 * w;
-    normal = normal * uniforms.projection;
-    if (uniforms.sizeAttenuation == 0.0) {
-        let screen = (vec4f(uniforms.resolution, 0.0, 1.0) * uniforms.projection).xy;
-        normal.x = normal.x * finalPosition.w / screen.x;
-        normal.y = normal.y * finalPosition.w / screen.y;
-    }
-    finalPosition.x += normal.x * vertexInputs.side;
-    finalPosition.y += normal.y * vertexInputs.side;
-
-    vertexOutputs.position = finalPosition;
-${fogVertexWGSL('(uniforms.view * vec4f(vertexInputs.position, 1.0)).xyz')}
+    let clipPosition = uniforms.projection * vec4f(point, 1.0);
+    vertexOutputs.position = clipPosition;
+${fogVertexWGSL('point')}
+#ifdef SOFT_PARTICLES
+    vertexOutputs.projPosition = clipPosition;
+    // View depth is +z ahead of a left-handed camera and -z ahead of a right-handed one.
+    vertexOutputs.linearDepth = abs(point.z);
+#endif
     vertexOutputs.vUV = vertexInputs.uv;
 #ifdef UV1
     vertexOutputs.vUV1 = vertexInputs.uv2;

package/src/softDepth.ts

@@ -0,0 +1,136 @@
+import {Camera} from '@babylonjs/core/Cameras/camera';
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {Vector4} from '@babylonjs/core/Maths/math.vector';
+
+/**
+ * What a soft-particle depth texture stores per pixel, so the shaders can turn it back into the
+ * distance from the camera. These are the three outputs of Babylon's `DepthRenderer`:
+ *
+ * - `'linear'`: Babylon's default depth metric, `scene.enableDepthRenderer()`. Linear in view
+ *   depth between the camera's near and far planes.
+ * - `'nonLinear'`: the depth buffer value, `enableDepthRenderer(camera, true)`. This is what
+ *   Unity's `_CameraDepthTexture` holds and what `LinearEyeDepth` undoes.
+ * - `'viewZ'`: the view-space Z itself, `enableDepthRenderer(camera, false, true, sampling, true)`.
+ *   Exact at any range and with an infinite far plane (`camera.maxZ = 0`), which the other two
+ *   cannot represent; this is the closest match to Unreal's SceneDepth.
+ *
+ * Perspective and orthographic cameras, both NDC depth ranges (WebGL, WebGPU) and a reverse
+ * depth buffer are all handled, from the camera drawing the particles. With a reverse depth buffer
+ * and `'nonLinear'`, clear the depth renderer to 0 (`depthRenderer.clearColor.r = 0`): it clears
+ * to 1 by default, which a reverse buffer reads as the near plane, so empty sky would fade every
+ * particle in front of it. A packed `'viewZ'` cannot be decoded.
+ */
+export type SoftDepthEncoding = 'linear' | 'nonLinear' | 'viewZ';
+
+/** How a depth texture given to {@link BatchedRenderer.setDepthTexture} is read. */
+export interface DepthTextureOptions {
+    /** What the texture stores. Defaults to the encoding of the `DepthRenderer` given, else `'linear'`. */
+    encoding?: SoftDepthEncoding;
+    /**
+     * The depth is packed into the four 8-bit channels, as a `DepthRenderer` of type
+     * `UNSIGNED_BYTE` writes it. Defaults to the `DepthRenderer`'s `isPacked`, else false.
+     */
+    packed?: boolean;
+}
+
+/** The depth texture a batch's soft particles read, and how. */
+export interface DepthBinding {
+    texture: BaseTexture;
+    encoding: SoftDepthEncoding;
+    packed: boolean;
+}
+
+/** The parts of a Babylon `DepthRenderer` read here, without importing it and its side effects. */
+interface DepthRendererLike {
+    getDepthMap(): BaseTexture;
+    readonly isPacked: boolean;
+}
+
+/** True for a Babylon `DepthRenderer`, as opposed to a texture. */
+export function isDepthRenderer(value: unknown): value is DepthRendererLike {
+    return typeof (value as DepthRendererLike | null)?.getDepthMap === 'function';
+}
+
+/** The binding for a depth texture or `DepthRenderer`, with its encoding read off the renderer. */
+export function depthBinding(depth: BaseTexture | DepthRendererLike, options: DepthTextureOptions = {}): DepthBinding {
+    const binding = readBinding(depth, options);
+    if (binding.packed && binding.encoding === 'viewZ') {
+        // Packing keeps only the fraction of the value, which loses a view Z past 1 unit.
+        throw new Error('[babylon.quarks] A packed view-Z depth cannot be decoded; use a float depth texture');
+    }
+    return binding;
+}
+
+function readBinding(depth: BaseTexture | DepthRendererLike, options: DepthTextureOptions): DepthBinding {
+    if (isDepthRenderer(depth)) {
+        // DepthRenderer keeps its encoding private; these are its constructor's own fields.
+        const stored = depth as unknown as {_storeCameraSpaceZ?: boolean; _storeNonLinearDepth?: boolean};
+        const detected: SoftDepthEncoding = stored._storeCameraSpaceZ
+            ? 'viewZ'
+            : stored._storeNonLinearDepth
+              ? 'nonLinear'
+              : 'linear';
+        return {
+            texture: depth.getDepthMap(),
+            encoding: options.encoding ?? detected,
+            packed: options.packed ?? depth.isPacked,
+        };
+    }
+    return {texture: depth, encoding: options.encoding ?? 'linear', packed: options.packed ?? false};
+}
+
+/**
+ * Writes the four coefficients the soft-particle shaders decode a depth sample `d` with:
+ * view depth = |(x·d + y) / (z·d + w)|. Each encoding is a ratio of linear terms in `d` for
+ * every projection Babylon builds, so one formula covers them all.
+ *
+ * @param camera - The camera the particles are drawn for, normally the one the depth was drawn for.
+ * @param encoding - What the depth texture stores.
+ * @param out - Receives the coefficients.
+ */
+export function softDepthParams(camera: Camera, encoding: SoftDepthEncoding, out: Vector4): Vector4 {
+    if (encoding === 'viewZ') {
+        return out.set(1, 0, 0, 1);
+    }
+    const engine = camera.getEngine();
+    const reverse = engine.useReverseDepthBuffer;
+    const halfZ = engine.isNDCHalfZRange;
+    // A view-space point (0, 0, z) projects to clip z = z·m10 + m14, clip w = z·m11 + m15.
+    const m = camera.getProjectionMatrix().m;
+    const m10 = m[10];
+    const m11 = m[11];
+    const m14 = m[14];
+    const m15 = m[15];
+    if (encoding === 'linear') {
+        // Babylon's depth metric, (±clip z + depthValues.x) / depthValues.y, solved for z.
+        const ortho = camera.mode === Camera.ORTHOGRAPHIC_CAMERA;
+        let near: number;
+        let far: number;
+        if (ortho) {
+            near = !reverse && halfZ ? 0 : 1;
+            far = reverse && halfZ ? 0 : 1;
+        } else {
+            near = reverse && halfZ ? camera.minZ : halfZ ? 0 : camera.minZ;
+            far = reverse && halfZ ? 0 : camera.maxZ;
+        }
+        const sign = reverse ? -1 : 1;
+        const span = near + far;
+        return out.set((sign * span) / m10, (-sign * near - m14) / m10, 0, 1);
+    }
+    // The depth buffer value: NDC z = d on a half range, 2d - 1 on a full one; then
+    // z = (m14 - ndc·m15) / (ndc·m11 - m10).
+    const scale = halfZ ? 1 : 2;
+    const offset = halfZ ? 0 : -1;
+    return out.set(-scale * m15, m14 - offset * m15, scale * m11, offset * m11 - m10);
+}
+
+/**
+ * The view depth the shaders read off a depth sample, for the coefficients of
+ * {@link softDepthParams}. Nothing there (a `'viewZ'` sample of 0, or a sample at an infinite far
+ * plane) reads as infinitely far, so the particle does not fade.
+ */
+export function decodeSoftDepth(sample: number, params: Vector4): number {
+    const denominator = params.z * sample + params.w;
+    const depth = Math.abs(denominator) > 1e-8 ? Math.abs((params.x * sample + params.y) / denominator) : 0;
+    return depth > 0 ? depth : 1e30;
+}

package/src/system/BehaviorPlan.ts

@@ -0,0 +1,85 @@
+import {Behavior, FusionStep, planBehaviorFusion} from 'quarks.core';
+
+/** Built-in behaviors that write a particle's size / colour, and those that touch neither. */
+const SIZE_BEHAVIORS = new Set(['SizeOverLife', 'SizeBySpeed']);
+const COLOR_BEHAVIORS = new Set(['ColorOverLife', 'ColorBySpeed']);
+const INERT_FOR_SIZE_AND_COLOR = new Set([
+    'ApplyForce',
+    'Noise',
+    'TurbulenceField',
+    'GravityForce',
+    'RotationOverLife',
+    'Rotation3DOverLife',
+    'RotationBySpeed',
+    'SpeedOverLife',
+    'FrameOverLife',
+    'ForceOverLife',
+    'VelocityOverLife',
+    'InheritVelocity',
+    'OrbitOverLife',
+    'WidthOverLength',
+    'ChangeEmitDirection',
+    'EmitSubParticleSystem',
+    'LimitSpeedOverLife',
+    'ApplyCollision',
+]);
+
+/**
+ * How a {@link ParticleSystem}'s behaviors run each step: consecutive behaviors that can be compiled
+ * into one loop are merged, and the plan records whether any of them can change a particle's size
+ * or colour after birth.
+ */
+export class BehaviorPlan {
+    /** Behaviors the cached plan was built from, compared by identity. */
+    private plan?: Array<Behavior>;
+    private fusionSteps: Array<FusionStep> = [];
+    /**
+     * Whether any behavior in the plan can change a particle's size or colour
+     * after birth. Only then does a step have to snapshot them for the renderer.
+     */
+    changesSize = true;
+    changesColor = true;
+
+    /**
+     * Execution plan for this system's behaviors, rebuilt when the list changes.
+     *
+     * Consecutive behaviors that can be compiled into one loop are merged, so
+     * the particles are walked once instead of once per behavior. The plan is
+     * keyed on the behavior instances, not their types: swapping one out has to
+     * change the generated code's indices.
+     */
+    steps(behaviors: Array<Behavior>): Array<FusionStep> {
+        const cached = this.plan;
+        if (cached !== undefined && cached.length === behaviors.length) {
+            let same = true;
+            for (let i = 0; i < behaviors.length; i++) {
+                if (cached[i] !== behaviors[i]) {
+                    same = false;
+                    break;
+                }
+            }
+            if (same) {
+                return this.fusionSteps;
+            }
+        }
+        this.plan = behaviors.slice();
+        this.fusionSteps = planBehaviorFusion(behaviors);
+        let changesSize = false;
+        let changesColor = false;
+        for (let i = 0; i < behaviors.length; i++) {
+            const type = behaviors[i].type;
+            if (SIZE_BEHAVIORS.has(type)) {
+                changesSize = true;
+            } else if (COLOR_BEHAVIORS.has(type)) {
+                changesColor = true;
+            } else if (!INERT_FOR_SIZE_AND_COLOR.has(type)) {
+                // Unknown to this list, so it may write anything.
+                changesSize = true;
+                changesColor = true;
+            }
+        }
+        this.changesSize = changesSize;
+        this.changesColor = changesColor;
+        return this.fusionSteps;
+    }
+}