babylon.quarks 0.26.0 → 0.28.0

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;
+    }
+}

package/src/system/BoundsTracker.ts

@@ -0,0 +1,181 @@
+import {RendererEmitterSettings, StretchedBillBoardSettings, Vector3} from 'quarks.core';
+import type {VFXBatchSettings} from '../BatchedRenderer';
+import {RenderMode} from '../VFXBatch';
+
+/** Steps between full measurements of a system's bounds; in between they are carried and padded. */
+const BOUNDS_REFRESH_STEPS = 4;
+
+/** Anything with a world matrix, such as the system's emitter node; read only when the bounds are local. */
+export interface BoundsSpace {
+    /** Its world matrix, column-major. */
+    readonly matrixWorld: {readonly elements: ArrayLike<number>};
+}
+
+/** The largest axis of the scale in a column-major 4x4 matrix. */
+export function maxAxisScale(e: ArrayLike<number>): number {
+    return Math.sqrt(
+        Math.max(
+            e[0] * e[0] + e[1] * e[1] + e[2] * e[2],
+            e[4] * e[4] + e[5] * e[5] + e[6] * e[6],
+            e[8] * e[8] + e[9] * e[9] + e[10] * e[10]
+        )
+    );
+}
+
+/**
+ * The bounds a {@link ParticleSystem} keeps of what it draws, for culling: an axis-aligned box of
+ * its live particles in simulation space, and how far a particle's quad, mesh or stretch reaches
+ * past its position. The simulation step measures the box in full every few steps and carries it,
+ * padded for the motion since, in between.
+ */
+export class BoundsTracker {
+    /** Axis-aligned bounds of the live particles, in simulation space. */
+    readonly min = new Vector3();
+    readonly max = new Vector3();
+    /** How far a particle's quad, mesh or stretch can reach past its position, in simulation units. */
+    padding = 0;
+    valid = false;
+    /** Steps since the last full measurement; between them the bounds are carried and padded. */
+    private stepsSince = 0;
+    /** Largest particle size seen since the last full measurement. */
+    maxSize = 0;
+    /** Largest squared particle speed seen since the last full measurement. */
+    maxSpeedSq = 0;
+    /** True when the bounds are already in world space (a world-space system, or bounds the renderer measured). */
+    inWorld = false;
+    private geometryRadiusFor?: Float32Array;
+    private geometryRadius = 1;
+
+    /** Whether this step should measure every particle instead of carrying the last bounds. */
+    get due(): boolean {
+        return this.stepsSince >= BOUNDS_REFRESH_STEPS || !this.valid;
+    }
+
+    /**
+     * Records the box the sprite step measured (or carried) over the live particles, and pads it
+     * for how the system draws. Trails are measured by their renderer instead, since their ribbons
+     * live outside the store; see {@link setWorld}.
+     * @param step - The simulation step in seconds, which the renderer moves particles along their velocity by.
+     */
+    store(
+        count: number,
+        measured: boolean,
+        minX: number,
+        minY: number,
+        minZ: number,
+        maxX: number,
+        maxY: number,
+        maxZ: number,
+        maxSize: number,
+        maxSpeedSq: number,
+        settings: VFXBatchSettings,
+        emitterSettings: RendererEmitterSettings,
+        worldSpace: boolean,
+        step: number
+    ): void {
+        if (count === 0) {
+            this.valid = false;
+            return;
+        }
+        this.stepsSince = measured ? 0 : this.stepsSince + 1;
+        this.maxSize = maxSize;
+        this.maxSpeedSq = maxSpeedSq;
+        const maxSpeed = Math.sqrt(maxSpeedSq);
+        const renderMode = settings.renderMode;
+        // How far past its position a particle can be drawn: half a quad's
+        // diagonal plus its pivot, a mesh's radius, or a stretched quad's tail.
+        // Plus the motion since the last measurement, and the step the renderer
+        // moves particles on along their velocity.
+        let padding = maxSpeed * step * (this.stepsSince + 1);
+        if (renderMode === RenderMode.Mesh) {
+            padding += maxSize * this.meshGeometryRadius(settings.instancingGeometry);
+        } else if (renderMode === RenderMode.StretchedBillBoard) {
+            const stretch = emitterSettings as StretchedBillBoardSettings;
+            padding += maxSize * (1 + (stretch.lengthFactor ?? 0) + maxSpeed * (stretch.speedFactor ?? 0));
+        } else {
+            const pivot = settings.pivot;
+            const pivotReach = pivot === undefined ? 0 : Math.abs(pivot.x) + Math.abs(pivot.y) + Math.abs(pivot.z);
+            padding += maxSize * (0.75 + pivotReach);
+        }
+        this.min.set(minX, minY, minZ);
+        this.max.set(maxX, maxY, maxZ);
+        this.padding = padding;
+        this.inWorld = worldSpace;
+        this.valid = true;
+    }
+
+    /** Records bounds already in world space, which a renderer measured. */
+    setWorld(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, padding: number) {
+        this.min.set(minX, minY, minZ);
+        this.max.set(maxX, maxY, maxZ);
+        this.padding = padding;
+        this.inWorld = true;
+        this.valid = true;
+    }
+
+    /** The padding in world units, for bounds kept in `space`. */
+    worldPadding(space: BoundsSpace): number {
+        return this.inWorld ? this.padding : this.padding * maxAxisScale(space.matrixWorld.elements);
+    }
+
+    /**
+     * The padded bounds in world space into `min` and `max`, for bounds kept in `space`; false
+     * while there are none.
+     */
+    toWorld(min: Vector3, max: Vector3, space: BoundsSpace): boolean {
+        if (!this.valid) {
+            return false;
+        }
+        const bmin = this.min;
+        const bmax = this.max;
+        if (this.inWorld) {
+            const pad = this.padding;
+            min.set(bmin.x - pad, bmin.y - pad, bmin.z - pad);
+            max.set(bmax.x + pad, bmax.y + pad, bmax.z + pad);
+            return true;
+        }
+        // Local bounds: the box of the eight transformed corners, padded by the
+        // reach scaled by the emitter's largest axis.
+        const e = space.matrixWorld.elements;
+        const pad = this.padding * maxAxisScale(e);
+        let minX = Infinity;
+        let minY = Infinity;
+        let minZ = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        let maxZ = -Infinity;
+        for (let corner = 0; corner < 8; corner++) {
+            const x = corner & 1 ? bmax.x : bmin.x;
+            const y = corner & 2 ? bmax.y : bmin.y;
+            const z = corner & 4 ? bmax.z : bmin.z;
+            const w = 1 / (e[3] * x + e[7] * y + e[11] * z + e[15]);
+            const wx = (e[0] * x + e[4] * y + e[8] * z + e[12]) * w;
+            const wy = (e[1] * x + e[5] * y + e[9] * z + e[13]) * w;
+            const wz = (e[2] * x + e[6] * y + e[10] * z + e[14]) * w;
+            if (wx < minX) minX = wx;
+            if (wx > maxX) maxX = wx;
+            if (wy < minY) minY = wy;
+            if (wy > maxY) maxY = wy;
+            if (wz < minZ) minZ = wz;
+            if (wz > maxZ) maxZ = wz;
+        }
+        min.set(minX - pad, minY - pad, minZ - pad);
+        max.set(maxX + pad, maxY + pad, maxZ + pad);
+        return true;
+    }
+
+    /** Distance of the farthest vertex of the mesh particles' geometry from its origin. */
+    private meshGeometryRadius(geometry: Float32Array): number {
+        if (geometry !== this.geometryRadiusFor) {
+            let radiusSq = 0;
+            for (let o = 0; o + 2 < geometry.length; o += 3) {
+                const d =
+                    geometry[o] * geometry[o] + geometry[o + 1] * geometry[o + 1] + geometry[o + 2] * geometry[o + 2];
+                if (d > radiusSq) radiusSq = d;
+            }
+            this.geometryRadius = Math.sqrt(radiusSq);
+            this.geometryRadiusFor = geometry;
+        }
+        return this.geometryRadius;
+    }
+}