babylon.quarks 0.26.0 → 0.27.0

package/src/VFXBatch.ts

@@ -1,6 +1,6 @@
 import {BoundingInfo} from '@babylonjs/core/Culling/boundingInfo';
-import {Constants} from '@babylonjs/core/Engines/constants';
 import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import type {Effect} from '@babylonjs/core/Materials/effect';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
 import {Color3} from '@babylonjs/core/Maths/math.color';
 import {Vector2 as BVector2, Vector3 as BVector3, Vector4 as BVector4} from '@babylonjs/core/Maths/math.vector';
@@ -9,6 +9,8 @@ import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Vector3} from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
 import type {ParticleSystem} from './ParticleSystem';
+import {storedBatchSettings} from './batchKey';
+import {DepthBinding, softDepthParams} from './softDepth';
 
 /**
  * The order the particles of a batch are drawn in (Unity's Sort Mode). Alpha
@@ -23,12 +25,25 @@ import type {ParticleSystem} from './ParticleSystem';
  */
 export type SortMode = 'none' | 'distance' | 'oldestInFront' | 'youngestInFront';
 
+/** How a system draws its particles (Unity's Render Mode), see {@link ParticleSystem.renderMode}. */
 export enum RenderMode {
+    /** A quad facing the camera (Unity's Billboard). The default. */
     BillBoard = 0,
+    /**
+     * A quad facing the camera and stretched along the particle's velocity (Unity's Stretched
+     * Billboard), by `speedFactor` and `lengthFactor` in the system's `rendererEmitterSettings`.
+     */
     StretchedBillBoard = 1,
+    /** The system's mesh, one instance per particle (Unity's Mesh), see {@link ParticleSystem.instancingGeometry}. */
     Mesh = 2,
+    /**
+     * A ribbon drawn through the particle's past positions (Unity's Trails module, Niagara's
+     * ribbon), facing the camera; its settings are `TrailSettings` in `rendererEmitterSettings`.
+     */
     Trail = 3,
+    /** A quad lying flat in the world's XZ plane, facing up (Unity's Horizontal Billboard). */
     HorizontalBillBoard = 4,
+    /** A quad standing upright and turning only about the world's Y axis to face the camera (Unity's Vertical Billboard). */
     VerticalBillBoard = 5,
     /**
      * A quad laid from each particle to the system's {@link ParticleSystem.beamEnd}
@@ -224,8 +239,9 @@ export type GradientMapChannel = 'r' | 'g' | 'b' | 'a' | 'luminance';
 
 /**
  * A gradient map (colour ramp): the map is recoloured by looking its
- * {@link channel} up along U of {@link ramp}. See
- * {@link VFXBatchSettings.gradientMap}.
+ * {@link channel} up along U of {@link ramp}. Without a map the lookup reads
+ * white, so the ramp's right-hand end tints every particle, in every render
+ * mode alike. See {@link VFXBatchSettings.gradientMap}.
  */
 export interface ParticleGradientMap {
     /**
@@ -301,7 +317,13 @@ export interface ParticleErosion {
 // Scrolling runs on the renderer's clock, not a system's playback speed.
 
 /** {@link ParticleErosion} as given: any field may be left out, the mask's layout too. */
-export type ParticleErosionOptions = Partial<Omit<ParticleErosion, 'maskUV'>> & {maskUV?: Partial<TextureUV>};
+export type ParticleErosionOptions = Partial<Omit<ParticleErosion, 'maskUV'>> & {
+    /** See {@link ParticleErosion.maskUV}; fields left out take their defaults. */
+    maskUV?: Partial<TextureUV>;
+};
+
+/** The width of the soft band an erosion cut fades over when `softness` is left out, in mask units. */
+export const EROSION_DEFAULT_SOFTNESS = 0.05;
 
 /** A complete erosion from a partial one, every field defaulted, or undefined when `erosion` is unset. */
 export function normalizeErosion(erosion: ParticleErosionOptions | null | undefined): ParticleErosion | undefined {
@@ -314,7 +336,7 @@ export function normalizeErosion(erosion: ParticleErosionOptions | null | undefi
     return {
         mask: erosion.mask ?? null,
         maskUV: normalizeTextureUV(erosion.maskUV),
-        softness: Math.max(0.0001, num(erosion.softness, 0.05)),
+        softness: Math.max(0.0001, num(erosion.softness, EROSION_DEFAULT_SOFTNESS)),
         edgeWidth: Math.max(0, num(erosion.edgeWidth, 0)),
         edgeColor: [num(color[0], 1), num(color[1], 1), num(color[2], 1)],
     };
@@ -363,7 +385,13 @@ export interface ParticleUVDistortion {
 }
 
 /** {@link ParticleUVDistortion} as given: any field may be left out, the noise's layout too. */
-export type ParticleUVDistortionOptions = Partial<Omit<ParticleUVDistortion, 'mapUV'>> & {mapUV?: Partial<TextureUV>};
+export type ParticleUVDistortionOptions = Partial<Omit<ParticleUVDistortion, 'mapUV'>> & {
+    /** See {@link ParticleUVDistortion.mapUV}; fields left out take their defaults. */
+    mapUV?: Partial<TextureUV>;
+};
+
+/** How far a distortion pushes the map's UV at most when `strength` is left out, in UV units. */
+export const UV_DISTORTION_DEFAULT_STRENGTH = 0.05;
 
 /** A complete distortion from a partial one, or undefined when unset or without a map. */
 export function normalizeUVDistortion(
@@ -376,7 +404,10 @@ export function normalizeUVDistortion(
     return {
         map: distortion.map,
         mapUV: normalizeTextureUV(distortion.mapUV, UV_DISTORTION_DEFAULT_UV),
-        strength: Math.max(0, typeof strength === 'number' && Number.isFinite(strength) ? strength : 0.05),
+        strength: Math.max(
+            0,
+            typeof strength === 'number' && Number.isFinite(strength) ? strength : UV_DISTORTION_DEFAULT_STRENGTH
+        ),
     };
 }
 
@@ -424,31 +455,58 @@ export function readsUV1(settings: {
     );
 }
 
+/**
+ * A batch's copy of the {@link VFXBatchSettings} its systems share: every optional field
+ * defaulted, and every field the batch's render mode ignores at its default (an opaque batch's
+ * `materialBlendMode` reads `ALPHA_DISABLE`, a billboard batch's `rim` is unset). The renderer
+ * adds a system to the batch whose settings match its own.
+ */
 export interface StoredBatchSettings {
+    /** See {@link VFXBatchSettings.instancingGeometry}. */
     instancingGeometry: Float32Array;
+    /** See {@link VFXBatchSettings.instancingIndices}. */
     instancingIndices: Uint32Array | Uint16Array;
+    /** See {@link VFXBatchSettings.instancingUVs}. */
     instancingUVs?: Float32Array;
     /** The mesh's second UV set, see {@link UVChannel}. */
     instancingUVs2?: Float32Array;
+    /** See {@link VFXBatchSettings.instancingNormals}. */
     instancingNormals?: Float32Array;
+    /** See {@link VFXBatchSettings.renderMode}. */
     renderMode: RenderMode;
+    /** See {@link VFXBatchSettings.renderOrder}. */
     renderOrder: number;
+    /** See {@link VFXBatchSettings.uTileCount}. */
     uTileCount: number;
+    /** See {@link VFXBatchSettings.vTileCount}. */
     vTileCount: number;
+    /** See {@link VFXBatchSettings.blendTiles}. */
     blendTiles: boolean;
+    /** See {@link VFXBatchSettings.softParticles}. */
     softParticles: boolean;
+    /** See {@link VFXBatchSettings.softNearFade}. */
     softNearFade: number;
+    /** See {@link VFXBatchSettings.softFarFade}. */
     softFarFade: number;
+    /** See {@link VFXBatchSettings.materialBlendMode}. */
     materialBlendMode: number;
+    /** See {@link VFXBatchSettings.materialTransparent}. */
     materialTransparent: boolean;
+    /** See {@link VFXBatchSettings.materialDepthTest}. */
     materialDepthTest: boolean;
+    /** See {@link VFXBatchSettings.materialDepthWrite}. */
     materialDepthWrite: boolean;
+    /** See {@link VFXBatchSettings.materialAlphaTest}. */
     materialAlphaTest: number;
-    texture: any;
+    /** See {@link VFXBatchSettings.texture}. */
+    texture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionTexture}. */
     reflectionTexture: BaseTexture | null;
+    /** See {@link VFXBatchSettings.reflectionLevel}. */
     reflectionLevel: number;
-    reflectionFaces: BaseTexture[] | null;
+    /** See {@link VFXBatchSettings.reflectionAtlas}. */
     reflectionAtlas: BaseTexture | null;
+    /** See {@link VFXBatchSettings.layerMask}. */
     layerMask: number;
     /** Babylon rendering group the batch mesh draws in, see {@link VFXBatchSettings.renderingGroupId}. */
     renderingGroupId: number;
@@ -476,56 +534,38 @@ export interface StoredBatchSettings {
     erosion?: ParticleErosion;
 }
 
+/**
+ * One draw call of a {@link BatchedRenderer}: the systems that share a material, texture and
+ * geometry, drawn together from one instanced mesh. The renderer makes and frees batches as
+ * systems are added and their settings change; read them through `renderer.batches` to inspect
+ * what is drawn, not to change it.
+ */
 export abstract class VFXBatch {
+    /** The Babylon mesh the batch draws with. */
     mesh: Mesh;
+    /** The systems drawn by this batch. */
     systems: Set<IParticleSystem>;
+    /** The settings every system in the batch shares, with what the render mode ignores at its default. */
     settings: StoredBatchSettings;
+    /** @internal */
     protected maxParticles: number;
+    /** @internal */
     protected scene: Scene;
+    /** @internal */
     protected readonly visibleSystems: IParticleSystem[] = [];
+    /**
+     * The depth texture soft particles read, from {@link BatchedRenderer.setDepthTexture}.
+     * @internal
+     */
+    protected depth: DepthBinding | null;
 
-    protected constructor(settings: VFXBatchSettings, scene: Scene) {
+    /** @internal */
+    protected constructor(settings: VFXBatchSettings, scene: Scene, depth: DepthBinding | null = null) {
         this.scene = scene;
+        this.depth = depth;
         this.maxParticles = 1000;
         this.systems = new Set<IParticleSystem>();
-        this.settings = {
-            instancingGeometry: settings.instancingGeometry,
-            instancingIndices: settings.instancingIndices,
-            instancingUVs: settings.instancingUVs,
-            instancingUVs2: settings.instancingUVs2,
-            instancingNormals: settings.instancingNormals,
-            renderMode: settings.renderMode,
-            renderOrder: settings.renderOrder,
-            uTileCount: settings.uTileCount,
-            vTileCount: settings.vTileCount,
-            blendTiles: settings.blendTiles,
-            softParticles: settings.softParticles,
-            softNearFade: settings.softNearFade,
-            softFarFade: settings.softFarFade,
-            materialBlendMode: settings.materialBlendMode,
-            materialTransparent: settings.materialTransparent,
-            materialDepthTest: settings.materialDepthTest,
-            materialDepthWrite: settings.materialDepthWrite,
-            materialAlphaTest: settings.materialAlphaTest,
-            texture: settings.texture,
-            reflectionTexture: settings.reflectionTexture ?? null,
-            reflectionLevel: settings.reflectionLevel ?? 1,
-            reflectionFaces: settings.reflectionFaces ?? null,
-            reflectionAtlas: settings.reflectionAtlas ?? null,
-            pivot: settings.pivot?.clone(),
-            sortMode: settings.sortMode ?? 'none',
-            minParticleSize: settings.minParticleSize ?? 0,
-            maxParticleSize: settings.maxParticleSize ?? Infinity,
-            layerMask: settings.layerMask,
-            renderingGroupId: settings.renderingGroupId ?? 0,
-            applyFog: settings.applyFog ?? true,
-            lighting: settings.lighting,
-            rim: normalizeMeshRim(settings.rim),
-            mapUV: normalizeMapUV(settings.mapUV),
-            uvDistortion: normalizeUVDistortion(settings.uvDistortion),
-            gradientMap: normalizeGradientMap(settings.gradientMap),
-            erosion: normalizeErosion(settings.erosion),
-        };
+        this.settings = storedBatchSettings(settings);
         this.mesh = new Mesh('vfxBatch', scene);
         this.configureMesh();
     }
@@ -553,6 +593,12 @@ export abstract class VFXBatch {
         mesh.alphaIndex = this.settings.renderOrder;
         // The shaders fog themselves; Babylon's own fog pass does not apply to a ShaderMaterial.
         mesh.applyFog = false;
+        // Its geometry is one quad or mesh at the origin, not the particles, so a pick or a
+        // collision against it would hit nothing that is drawn. The renderer rebuilds batches
+        // from its systems, so a scene serializer has nothing to write either.
+        mesh.isPickable = false;
+        mesh.checkCollisions = false;
+        mesh.doNotSerialize = true;
     }
 
     private readonly boundsMin_ = new Vector3();
@@ -615,23 +661,26 @@ export abstract class VFXBatch {
     }
 
     /**
-     * Fog defines and uniforms for a material of this batch, and the per-bind
-     * upload of the scene's current fog. Mode 0 (none) when the scene has fog
-     * disabled, so toggling fog at runtime needs no recompile.
+     * Writes a uniform that changes per bind, such as one read off the active camera, to the
+     * material for the next bind and to its bound effect for this one: ShaderMaterial uploads its
+     * stored values before the bind observers run, so a value written only to the material would
+     * reach the GPU one draw late, and with two cameras it would always be the other camera's.
      */
-    protected static readonly FOG_UNIFORMS = ['vFogInfos', 'vFogColor'];
-
-    protected fogDefines(): string[] {
-        if (!this.settings.applyFog) {
-            return [];
+    protected static writeBound(material: ShaderMaterial, write: (target: ShaderMaterial | Effect) => void): void {
+        write(material);
+        // An effect still compiling has no pipeline context to write to; it gets the stored value
+        // when it is first bound. A sub mesh's effect override is not reached here.
+        const effect = material.getEffect();
+        if (effect?.isReady()) {
+            write(effect);
         }
-        const additive =
-            this.settings.materialTransparent &&
-            (this.settings.materialBlendMode === Constants.ALPHA_ADD ||
-                this.settings.materialBlendMode === Constants.ALPHA_ONEONE);
-        return additive ? ['FOG', 'FOG_ADDITIVE'] : ['FOG'];
     }
 
+    /**
+     * The per-bind upload of the scene's current fog. Mode 0 (none) when the scene has fog
+     * disabled, so toggling fog at runtime needs no recompile.
+     * @internal
+     */
     protected bindFog(material: ShaderMaterial): void {
         if (!this.settings.applyFog) {
             return;
@@ -659,85 +708,19 @@ export abstract class VFXBatch {
         return readsUV1(this.settings);
     }
 
-    /** Defines of the texture effects (see `shaders/chunks/surface.ts`) this batch uses. */
-    protected surfaceDefines(): string[] {
-        const defines: string[] = [];
-        const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
-        if (this.usesUV1()) {
-            defines.push('UV1');
-        }
-        if (mapUV) {
-            defines.push('MAP_TRANSFORM');
-            if (mapUV.channel === 1) {
-                defines.push('MAP_UV1');
-            }
-        }
-        if (uvDistortion) {
-            defines.push('UV_DISTORTION');
-            if (uvDistortion.mapUV.channel === 1) {
-                defines.push('UV_DISTORTION_UV1');
-            }
-        }
-        if (gradientMap) {
-            defines.push('GRADIENT_MAP');
-        }
-        if (erosion) {
-            defines.push('EROSION');
-            if (erosion.mask) {
-                defines.push('EROSION_MASK');
-                if (erosion.maskUV.channel === 1) {
-                    defines.push('EROSION_MASK_UV1');
-                }
-            }
-        }
-        return defines;
-    }
-
-    /** Adds the uniforms and samplers of the texture effects this batch uses. */
-    protected surfaceUniforms(uniforms: string[], samplers: string[]): void {
-        const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
-        if (mapUV) {
-            uniforms.push('mapTransform');
-        }
-        if (uvDistortion) {
-            samplers.push('distortionMap');
-            uniforms.push('distortionTransform', 'distortionStrength');
-        }
-        if (gradientMap) {
-            samplers.push('gradientMap');
-            uniforms.push('gradientMapRange', 'gradientMapChannel');
-        }
-        if (erosion) {
-            uniforms.push('erosionParams', 'erosionEdgeColor');
-            if (erosion.mask) {
-                samplers.push('erosionMask');
-                uniforms.push('erosionMaskTransform');
-            }
-        }
-    }
-
     /** Sets the texture effects' textures and constants, and advances their scrolling on every bind. */
     protected bindSurface(material: ShaderMaterial): void {
         const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
         if (uvDistortion?.map) {
             material.setTexture('distortionMap', uvDistortion.map);
-            material.setFloat('distortionStrength', uvDistortion.strength);
         }
         if (gradientMap?.ramp) {
             material.setTexture('gradientMap', gradientMap.ramp);
-            const [r, g, b, a] = GRADIENT_MAP_WEIGHTS[gradientMap.channel];
-            material.setVector4('gradientMapChannel', new BVector4(r, g, b, a));
         }
-        if (erosion) {
-            if (erosion.mask) {
-                material.setTexture('erosionMask', erosion.mask);
-            }
-            material.setVector2('erosionParams', new BVector2(erosion.softness, erosion.edgeWidth));
-            material.setVector3(
-                'erosionEdgeColor',
-                new BVector3(erosion.edgeColor[0], erosion.edgeColor[1], erosion.edgeColor[2])
-            );
+        if (erosion?.mask) {
+            material.setTexture('erosionMask', erosion.mask);
         }
+        this.writeSurfaceParams(material);
         if (!mapUV && !uvDistortion && !erosion?.mask && !gradientMap) {
             return;
         }
@@ -760,9 +743,12 @@ export abstract class VFXBatch {
             );
         // Written to the material for the next bind and to the bound effect for
         // this one: ShaderMaterial uploads its values before the bind observers run.
+        // The layouts are read off the settings on every bind, so a live change
+        // to a tiling or scroll reaches the next draw.
         const write = () => {
             const time = this.time;
             const effect = material.getEffect();
+            const {mapUV, uvDistortion, gradientMap, erosion} = this.settings;
             if (mapUV) {
                 transform(mapUV, time, mapTransform);
                 material.setVector4('mapTransform', mapTransform);
@@ -792,11 +778,56 @@ export abstract class VFXBatch {
         material.onBindObservable.add(write);
     }
 
-    addSystem(system: IParticleSystem) {
+    /** Writes the texture effects' constants (the uniforms their live parameters set). */
+    private writeSurfaceParams(material: ShaderMaterial): void {
+        const {uvDistortion, gradientMap, erosion} = this.settings;
+        if (uvDistortion?.map) {
+            material.setFloat('distortionStrength', uvDistortion.strength);
+        }
+        if (gradientMap?.ramp) {
+            const [r, g, b, a] = GRADIENT_MAP_WEIGHTS[gradientMap.channel];
+            material.setVector4('gradientMapChannel', new BVector4(r, g, b, a));
+        }
+        if (erosion) {
+            material.setVector2('erosionParams', new BVector2(erosion.softness, erosion.edgeWidth));
+            material.setVector3(
+                'erosionEdgeColor',
+                new BVector3(erosion.edgeColor[0], erosion.edgeColor[1], erosion.edgeColor[2])
+            );
+        }
+    }
+
+    /**
+     * Takes new live parameters (see {@link BatchedRenderer.updateSystem}): settings with the same
+     * shader key as the batch's, whose uniform values differ. They are copied into the batch's
+     * settings and written to its material, which is kept.
+     * @internal
+     */
+    applyLiveSettings(settings: StoredBatchSettings): void {
+        Object.assign(this.settings, settings);
+        const material = this.mesh.material;
+        if (material instanceof ShaderMaterial) {
+            this.writeLiveUniforms(material);
+        }
+    }
+
+    /**
+     * Writes every uniform a live parameter sets, from the batch's settings. The base writes the
+     * ones every render mode has; a mode adds its own.
+     * @internal
+     */
+    protected writeLiveUniforms(material: ShaderMaterial): void {
+        this.writeSoftParams(material);
+        this.writeSurfaceParams(material);
+    }
+
+    /** @internal */
+    addSystem(system: IParticleSystem): void {
         this.systems.add(system);
     }
 
-    removeSystem(system: IParticleSystem) {
+    /** @internal */
+    removeSystem(system: IParticleSystem): void {
         this.systems.delete(system);
     }
 
@@ -819,21 +850,90 @@ export abstract class VFXBatch {
         return visibleSystems;
     }
 
-    applyDepthTexture(depthTexture: BaseTexture | null): void {
+    /**
+     * Sets the depth texture soft particles read. Soft particles are compiled in only while there
+     * is one, as Unity turns them off for a camera without a depth texture, so attaching or
+     * removing it, or changing how it is packed, rebuilds a soft batch's material.
+     *
+     * @param depth - The binding, or a bare texture, read as `'linear'` and unpacked.
+     * @internal Use {@link BatchedRenderer.setDepthTexture}.
+     */
+    applyDepthTexture(depth: DepthBinding | BaseTexture | null): void {
+        if (depth instanceof BaseTexture) {
+            depth = {texture: depth, encoding: 'linear', packed: false};
+        }
+        const previous = this.depth;
+        this.depth = depth;
+        if (!this.settings.softParticles) {
+            return;
+        }
+        if (!previous !== !depth || previous?.packed !== depth?.packed) {
+            this.rebuildMaterial();
+            return;
+        }
         const material = this.mesh.material;
-        if (material && material instanceof ShaderMaterial) {
-            material.setTexture('depthTexture', depthTexture);
+        if (depth && material instanceof ShaderMaterial) {
+            material.setTexture('depthTexture', depth.texture);
         }
     }
 
-    /** Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it. */
+    /**
+     * Sets the soft-particle and alpha-test values on a material, and decodes the depth for the
+     * camera of each draw.
+     */
+    protected bindSoft(material: ShaderMaterial): void {
+        this.writeSoftParams(material);
+        if (this.drawsSoft()) {
+            material.setTexture('depthTexture', this.depth!.texture);
+            // Reused across binds: this runs on every draw call.
+            const projParams = new BVector4(1, 0, 0, 1);
+            material.onBindObservable.add(() => {
+                const camera = this.scene.activeCamera;
+                if (camera && this.depth) {
+                    softDepthParams(camera, this.depth.encoding, projParams);
+                    VFXBatch.writeBound(material, (target) => target.setVector4('projParams', projParams));
+                }
+            });
+        }
+    }
+
+    /** Writes the soft-particle fade and the alpha cutoff, the live parameters every mode shares. */
+    private writeSoftParams(material: ShaderMaterial): void {
+        if (this.drawsSoft()) {
+            material.setVector2(
+                'softParams',
+                new BVector2(
+                    this.settings.softNearFade,
+                    1.0 / Math.max(this.settings.softFarFade - this.settings.softNearFade, 0.0001)
+                )
+            );
+        }
+        if (this.settings.materialAlphaTest > 0) {
+            material.setFloat('alphaTest', this.settings.materialAlphaTest);
+        }
+    }
+
+    /** True when this batch draws soft particles: they are on and a depth texture is attached. */
+    protected drawsSoft(): boolean {
+        return this.settings.softParticles && this.depth !== null;
+    }
+
+    /**
+     * Sets the light `'fixed'` mesh particles are lit by. Batches that draw no meshes ignore it.
+     * @internal Use {@link BatchedRenderer.setMeshLighting}.
+     */
     applyMeshLighting(_lighting: MeshLightingSettings): void {}
 
+    /** @internal */
     abstract setupBuffers(): void;
+    /** @internal */
     abstract expandBuffers(target: number): void;
+    /** @internal */
     abstract rebuildMaterial(): void;
+    /** @internal */
     abstract update(): void;
 
+    /** @internal */
     dispose(): void {
         this.mesh.dispose();
     }