babylon.quarks 0.25.0 → 0.27.0

package/src/SpriteBatch.ts

@@ -1,37 +1,32 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Constants} from '@babylonjs/core/Engines/constants';
+import type {Effect} from '@babylonjs/core/Materials/effect';
 import {ShaderMaterial} from '@babylonjs/core/Materials/shaderMaterial';
 import {RawTexture} from '@babylonjs/core/Materials/Textures/rawTexture';
-import {Vector2 as BVector2, Vector3 as BVector3, Vector4 as BVector4} from '@babylonjs/core/Maths/math.vector';
+import {Vector2 as BVector2, Vector3 as BVector3} from '@babylonjs/core/Maths/math.vector';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {VertexData} from '@babylonjs/core/Meshes/mesh.vertexData';
 import {Scene} from '@babylonjs/core/scene';
 import {
     IParticle,
-    IParticleSystem,
     Matrix3,
     ParticleStore,
     Quaternion,
     SpriteParticle,
     StretchedBillBoardSettings,
     Vector3,
+    Vector4,
 } from 'quarks.core';
 import {VFXBatchSettings} from './BatchedRenderer';
+import {hasSizeLimits, takesPivotAndSizeLimits, tilesSheet} from './batchKey';
 import {gather, sortByKey, SortScratch} from './instanceSort';
 import type {ParticleSystem} from './ParticleSystem';
-import local_particle_physics_vert from './shaders/local_particle_physics_vert.glsl';
-import local_particle_physics_vert_wgsl from './shaders/local_particle_physics_vert.wgsl';
-import particle_frag from './shaders/particle_frag.glsl';
-import particle_frag_wgsl from './shaders/particle_frag.wgsl';
-import particle_physics_frag from './shaders/particle_physics_frag.glsl';
-import particle_physics_frag_wgsl from './shaders/particle_physics_frag.wgsl';
-import particle_vert from './shaders/particle_vert.glsl';
-import particle_vert_wgsl from './shaders/particle_vert.wgsl';
-import {registerShaders, shaderLanguageFor, ShaderSources} from './shaders/shaderLanguageSupport';
-import stretched_bb_particle_vert from './shaders/stretched_bb_particle_vert.glsl';
-import stretched_bb_particle_vert_wgsl from './shaders/stretched_bb_particle_vert.wgsl';
+import {drawsAlongVelocity, shaderProgram} from './shaderProgram';
+import {registerShaders, shaderLanguageFor} from './shaders/shaderLanguageSupport';
+import type {DepthBinding} from './softDepth';
 import {defaultMeshLighting, MeshLightingSettings, RenderMode, VFXBatch} from './VFXBatch';
 
+/** The batch of billboard, stretched, mesh and beam particles. @internal */
 export class SpriteBatch extends VFXBatch {
     private static whiteTextureByScene = new WeakMap<Scene, RawTexture>();
 
@@ -52,8 +47,11 @@ export class SpriteBatch extends VFXBatch {
     private uvTileBuffer!: Float32Array;
     private velocityBuffer?: Float32Array;
 
-    /** Concretely typed handle on the batch material, see syncStretchedSpeedFactor. */
+    /** Concretely typed handle on the batch material, for the lighting and live-parameter writes. */
     private shaderMaterial: ShaderMaterial | null = null;
+    /** Cancels the pending rebuild for an env atlas that has not loaded yet. */
+    private cancelAtlasRebuild: (() => void) | null = null;
+    private disposed = false;
     /** The `'fixed'` mesh light, as shader uniforms; see applyMeshLighting. */
     private readonly fixedLightDirection = new BVector3();
     private readonly fixedLightColor = new BVector3();
@@ -66,14 +64,15 @@ export class SpriteBatch extends VFXBatch {
     private uvTileVB!: VertexBuffer;
     private velocityVB?: VertexBuffer;
 
-    constructor(settings: VFXBatchSettings, scene: Scene) {
-        super(settings, scene);
+    constructor(settings: VFXBatchSettings, scene: Scene, depth: DepthBinding | null = null) {
+        super(settings, scene, depth);
         this.storeFixedLighting(defaultMeshLighting());
         this.maxParticles = 1000;
         this.setupBuffers();
         this.rebuildMaterial();
     }
 
+    /** @internal */
     setupBuffers(): void {
         this.mesh.dispose();
         this.mesh = new Mesh('spriteBatch', this.scene);
@@ -91,6 +90,9 @@ export class SpriteBatch extends VFXBatch {
         } else {
             vertexData.uvs = new Float32Array(vertexCount * 2);
         }
+        if (this.meshUV2()) {
+            vertexData.uvs2 = this.settings.instancingUVs2!;
+        }
         if (this.settings.instancingNormals) {
             vertexData.normals = this.settings.instancingNormals;
         }
@@ -99,6 +101,33 @@ export class SpriteBatch extends VFXBatch {
         this.buildExpandableBuffers();
     }
 
+    /**
+     * True when a mesh batch reads UV channel 1 and has a second UV set to
+     * read it from, two values per vertex. A set of any other length is left
+     * out with a warning, and channel 1 then reads the first set.
+     */
+    private warnedUV2 = false;
+
+    private meshUV2(): boolean {
+        const uvs2 = this.settings.instancingUVs2;
+        if (this.settings.renderMode !== RenderMode.Mesh || !uvs2 || !this.usesUV1()) {
+            return false;
+        }
+        const expected = (this.settings.instancingGeometry.length / 3) * 2;
+        if (uvs2.length !== expected) {
+            if (this.warnedUV2) {
+                return false;
+            }
+            this.warnedUV2 = true;
+            console.warn(
+                `[babylon.quarks] instancingUVs2 has ${uvs2.length} values for ${expected / 2} vertices ` +
+                    '(two per vertex expected); UV channel 1 reads the first UV set instead.'
+            );
+            return false;
+        }
+        return true;
+    }
+
     /** Releases the instance vertex buffers so a resize does not leak GPU memory. */
     private disposeExpandableBuffers(): void {
         this.offsetVB?.dispose();
@@ -139,7 +168,7 @@ export class SpriteBatch extends VFXBatch {
         }
         this.mesh.setVerticesBuffer(this.rotationVB);
 
-        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
+        if (drawsAlongVelocity(this.settings.renderMode)) {
             this.velocityBuffer = new Float32Array(this.maxParticles * 4);
             this.velocityVB = new VertexBuffer(engine, this.velocityBuffer, 'velocity', true, false, 4, true);
             this.mesh.setVerticesBuffer(this.velocityVB);
@@ -149,6 +178,7 @@ export class SpriteBatch extends VFXBatch {
         this.mesh.doNotSyncBoundingInfo = true;
     }
 
+    /** @internal */
     expandBuffers(target: number): void {
         while (target >= this.maxParticles) {
             this.maxParticles *= 2;
@@ -162,10 +192,7 @@ export class SpriteBatch extends VFXBatch {
     /** The screen-size limits as a uniform value, or null when the batch has none that apply. */
     private sizeLimits(): BVector2 | null {
         const {minParticleSize, maxParticleSize} = this.settings;
-        if (!SpriteBatch.takesPivotAndFlip(this.settings.renderMode)) {
-            return null;
-        }
-        if (minParticleSize <= 0 && maxParticleSize === Infinity) {
+        if (!takesPivotAndSizeLimits(this.settings.renderMode) || !hasSizeLimits(this.settings)) {
             return null;
         }
         // The shader clamps; an unlimited maximum is just a very large one.
@@ -264,147 +291,47 @@ export class SpriteBatch extends VFXBatch {
         return spare;
     }
 
+    /** @internal */
     rebuildMaterial(): void {
-        // The shader sources only depend on the render mode, so the store entry is
-        // registered once per mode. A unique name per rebuild would leak entries in
-        // Effect.ShadersStore and defeat Babylon's compiled-effect cache.
-        const shaderName = `quarksParticle_${this.settings.renderMode}`;
-        this.lastStretchedSpeedFactor = Number.NaN;
-        const defines: string[] = this.fogDefines();
-
-        let vertexShader: ShaderSources;
-        let fragmentShader: ShaderSources;
-        if (this.settings.renderMode === RenderMode.Mesh) {
-            vertexShader = {glsl: local_particle_physics_vert, wgsl: local_particle_physics_vert_wgsl};
-            fragmentShader = {glsl: particle_physics_frag, wgsl: particle_physics_frag_wgsl};
-        } else if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
-            vertexShader = {glsl: stretched_bb_particle_vert, wgsl: stretched_bb_particle_vert_wgsl};
-            fragmentShader = {glsl: particle_frag, wgsl: particle_frag_wgsl};
-        } else {
-            vertexShader = {glsl: particle_vert, wgsl: particle_vert_wgsl};
-            fragmentShader = {glsl: particle_frag, wgsl: particle_frag_wgsl};
-        }
-
+        const isMesh = this.settings.renderMode === RenderMode.Mesh;
         // Mesh batches without a diffuse map still need a sampler2D on iOS WebKit —
         // a zero-sampler particle mesh effect often never becomes drawable there.
-        const mapTexture =
-            this.settings.texture ??
-            (this.settings.renderMode === RenderMode.Mesh ? SpriteBatch.whiteTexture(this.scene) : null);
-        if (mapTexture) {
-            defines.push('USE_MAP');
-        }
+        const mapTexture = this.settings.texture ?? (isMesh ? SpriteBatch.whiteTexture(this.scene) : null);
         const atlas = this.settings.reflectionAtlas;
-        const atlasPending = this.settings.renderMode === RenderMode.Mesh && !!atlas && !atlas.isReady();
+        const atlasPending = isMesh && !!atlas && !atlas.isReady();
+        this.cancelAtlasRebuild?.();
+        this.cancelAtlasRebuild = null;
         if (atlasPending && atlas) {
-            const onLoad = (atlas as {onLoadObservable?: {addOnce: (cb: () => void) => void}}).onLoadObservable;
-            onLoad?.addOnce(() => {
-                this.rebuildMaterial();
-            });
-        }
-        const useEnvAtlas = this.settings.renderMode === RenderMode.Mesh && !!atlas && atlas.isReady();
-        if (useEnvAtlas) {
-            defines.push('USE_ENVMAP_ATLAS');
-        }
-        if (this.settings.uTileCount > 1 || this.settings.vTileCount > 1) {
-            defines.push('UV_TILE');
-        }
-        if (this.settings.blendTiles) {
-            defines.push('TILE_BLEND');
-        }
-        if (this.settings.softParticles) {
-            defines.push('SOFT_PARTICLES');
-        }
-        if (this.settings.materialAlphaTest > 0) {
-            defines.push('USE_ALPHATEST');
-        }
-        if (this.settings.renderMode === RenderMode.VerticalBillBoard) {
-            defines.push('VERTICAL');
-        }
-        if (this.settings.renderMode === RenderMode.HorizontalBillBoard) {
-            defines.push('HORIZONTAL');
-        }
-        if (this.settings.renderMode === RenderMode.Beam) {
-            defines.push('BEAM');
-        }
-        const pivot = SpriteBatch.takesPivotAndFlip(this.settings.renderMode) ? this.settings.pivot : undefined;
-        if (pivot) {
-            defines.push('PIVOT');
-        }
-        const sizeLimits = this.sizeLimits();
-        if (sizeLimits) {
-            defines.push('SIZE_LIMITS');
+            const onLoad = (
+                atlas as {
+                    onLoadObservable?: {addOnce: (cb: () => void) => unknown; remove: (observer: unknown) => boolean};
+                }
+            ).onLoadObservable;
+            if (onLoad) {
+                const observer = onLoad.addOnce(() => {
+                    this.cancelAtlasRebuild = null;
+                    if (!this.disposed) {
+                        this.rebuildMaterial();
+                    }
+                });
+                this.cancelAtlasRebuild = () => onLoad.remove(observer);
+            }
         }
-        const isMesh = this.settings.renderMode === RenderMode.Mesh;
+        const useEnvAtlas = this.usesEnvAtlas();
+        const program = shaderProgram(this.settings, {
+            depth: this.depth,
+            envAtlasReady: useEnvAtlas,
+            meshUV2: this.meshUV2(),
+        });
+        const {defines, attributes, uniforms, samplers} = program;
+        const shaderName = program.name;
         const lighting = this.settings.lighting ?? 'fixed';
         const lit = isMesh && lighting !== 'unlit';
-        if (isMesh && !lit) {
-            defines.push('MESH_UNLIT');
-        }
         const rim = isMesh ? this.settings.rim : undefined;
-        if (rim) {
-            defines.push('MESH_RIM');
-            if (rim.mode === 'mix') {
-                defines.push('MESH_RIM_MIX');
-            }
-        }
         const needsEyePosition = useEnvAtlas || !!rim;
-        defines.push(...this.surfaceDefines());
 
         const shaderLanguage = shaderLanguageFor(this.scene.getEngine());
-        registerShaders(shaderName, vertexShader, fragmentShader, shaderLanguage);
-
-        const attributes = ['position', 'uv', 'offset', 'color', 'size', 'rotation', 'uvTile'];
-        if (this.settings.renderMode === RenderMode.Mesh) {
-            attributes.push('normal');
-        }
-        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
-            attributes.push('velocity');
-        }
-
-        const uniforms = ['world', 'view', 'projection', 'worldView', 'worldViewProjection', ...VFXBatch.FOG_UNIFORMS];
-        const samplers: string[] = [];
-
-        if (this.settings.uTileCount > 1 || this.settings.vTileCount > 1) {
-            uniforms.push('tileCountX');
-            uniforms.push('tileCountY');
-        }
-        if (mapTexture) {
-            samplers.push('map');
-        }
-        if (useEnvAtlas) {
-            samplers.push('envAtlas');
-            uniforms.push('reflectionLevel');
-        }
-        if (needsEyePosition) {
-            uniforms.push('eyePosition');
-        }
-        if (rim) {
-            uniforms.push('rimColor');
-            uniforms.push('rimParams');
-        }
-        this.surfaceUniforms(uniforms, samplers);
-        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
-            uniforms.push('speedFactor');
-        }
-        if (this.settings.softParticles) {
-            uniforms.push('softParams');
-            uniforms.push('projParams');
-            samplers.push('depthTexture');
-        }
-        if (this.settings.materialAlphaTest > 0) {
-            uniforms.push('alphaTest');
-        }
-        if (pivot) {
-            uniforms.push('pivot');
-        }
-        if (sizeLimits) {
-            uniforms.push('sizeLimits');
-        }
-        if (lit) {
-            uniforms.push('lightDirection');
-            uniforms.push('lightColor');
-            uniforms.push('ambientColor');
-        }
+        registerShaders(shaderName, program.vertex, program.fragment, shaderLanguage);
 
         const mat = new ShaderMaterial(
             shaderName,
@@ -425,11 +352,6 @@ export class SpriteBatch extends VFXBatch {
         }
         if (useEnvAtlas && atlas) {
             mat.setTexture('envAtlas', atlas);
-            mat.setFloat('reflectionLevel', this.settings.reflectionLevel);
-        }
-        if (rim) {
-            mat.setVector3('rimColor', new BVector3(rim.color[0], rim.color[1], rim.color[2]));
-            mat.setVector2('rimParams', new BVector2(rim.power, rim.strength));
         }
         if (needsEyePosition) {
             const eyePosition = new BVector3();
@@ -440,44 +362,15 @@ export class SpriteBatch extends VFXBatch {
                     return;
                 }
                 eyePosition.copyFrom(camera.globalPosition);
-                mat.setVector3('eyePosition', eyePosition);
+                VFXBatch.writeBound(mat, (target) => target.setVector3('eyePosition', eyePosition));
             });
         }
-        if (this.settings.uTileCount > 1 || this.settings.vTileCount > 1) {
+        if (tilesSheet(this.settings)) {
             mat.setFloat('tileCountX', this.settings.uTileCount);
             mat.setFloat('tileCountY', this.settings.vTileCount);
         }
-        if (SpriteBatch.drawsAlongVelocity(this.settings.renderMode)) {
-            mat.setFloat('speedFactor', this.settings.softNearFade > 0 ? this.settings.softNearFade : 1.0);
-        }
-        if (this.settings.softParticles) {
-            mat.setVector2(
-                'softParams',
-                new BVector2(
-                    this.settings.softNearFade,
-                    1.0 / Math.max(this.settings.softFarFade - this.settings.softNearFade, 0.0001)
-                )
-            );
-            // Reused across binds: this runs on every draw call.
-            const projParams = new BVector4(0, 0, 0, 0);
-            mat.onBindObservable.add(() => {
-                const camera = this.scene.activeCamera;
-                if (camera) {
-                    projParams.x = camera.minZ;
-                    projParams.y = camera.maxZ;
-                    mat.setVector4('projParams', projParams);
-                }
-            });
-        }
-        if (this.settings.materialAlphaTest > 0) {
-            mat.setFloat('alphaTest', this.settings.materialAlphaTest);
-        }
-        if (pivot) {
-            mat.setVector3('pivot', new BVector3(pivot.x, pivot.y, pivot.z));
-        }
-        if (sizeLimits) {
-            mat.setVector2('sizeLimits', sizeLimits);
-        }
+        this.bindSoft(mat);
+        this.writeSpriteParams(mat, useEnvAtlas);
         if (lit) {
             this.writeFixedLighting(mat);
             if (lighting === 'scene') {
@@ -485,13 +378,15 @@ export class SpriteBatch extends VFXBatch {
                 const color = new BVector3();
                 const ambient = new BVector3();
                 mat.onBindObservable.add(() => {
-                    if (SpriteBatch.readSceneLight(this.scene, direction, color, ambient)) {
-                        mat.setVector3('lightDirection', direction);
-                        mat.setVector3('lightColor', color);
-                        mat.setVector3('ambientColor', ambient);
-                    } else {
-                        this.writeFixedLighting(mat);
-                    }
+                    const found = SpriteBatch.readSceneLight(this.scene, direction, color, ambient);
+                    VFXBatch.writeBound(mat, (target) =>
+                        found
+                            ? target
+                                  .setVector3('lightDirection', direction)
+                                  .setVector3('lightColor', color)
+                                  .setVector3('ambientColor', ambient)
+                            : this.writeFixedLighting(target)
+                    );
                 });
             }
         }
@@ -505,14 +400,52 @@ export class SpriteBatch extends VFXBatch {
         } else {
             mat.alphaMode = Constants.ALPHA_DISABLE;
         }
-        mat.needDepthPrePass = this.settings.materialDepthWrite;
+        // A transparent surface that writes depth is drawn into the depth buffer first, so its own
+        // overlapping pieces do not fight; an opaque one writes depth as it draws.
+        mat.needDepthPrePass = this.settings.materialDepthWrite && this.settings.materialTransparent;
         mat.forceDepthWrite = this.settings.materialDepthWrite;
         mat.disableDepthWrite = !this.settings.materialDepthWrite;
+        // 0 keeps the engine's depth function (LEQUAL); ALWAYS draws over everything, like ZTest Always.
+        mat.depthFunction = this.settings.materialDepthTest ? 0 : Constants.ALWAYS;
 
+        // A rebuild (an env atlas that finished loading) replaces the material; the old one and its
+        // bind observers go with it. Textures belong to the settings, so they stay.
+        this.shaderMaterial?.dispose(false, false);
         this.mesh.material = mat;
         this.shaderMaterial = mat;
     }
 
+    /** Writes the live parameters only sprite and mesh batches have: reflection level, rim, pivot and size limits. */
+    private writeSpriteParams(material: ShaderMaterial, envAtlas: boolean): void {
+        if (envAtlas) {
+            material.setFloat('reflectionLevel', this.settings.reflectionLevel);
+        }
+        const rim = this.settings.renderMode === RenderMode.Mesh ? this.settings.rim : undefined;
+        if (rim) {
+            material.setVector3('rimColor', new BVector3(rim.color[0], rim.color[1], rim.color[2]));
+            material.setVector2('rimParams', new BVector2(rim.power, rim.strength));
+        }
+        const pivot = takesPivotAndSizeLimits(this.settings.renderMode) ? this.settings.pivot : undefined;
+        if (pivot) {
+            material.setVector3('pivot', new BVector3(pivot.x, pivot.y, pivot.z));
+        }
+        const sizeLimits = this.sizeLimits();
+        if (sizeLimits) {
+            material.setVector2('sizeLimits', sizeLimits);
+        }
+    }
+
+    protected override writeLiveUniforms(material: ShaderMaterial): void {
+        super.writeLiveUniforms(material);
+        this.writeSpriteParams(material, this.usesEnvAtlas());
+    }
+
+    /** True when the material samples the env atlas: a mesh batch whose atlas has loaded. */
+    private usesEnvAtlas(): boolean {
+        const atlas = this.settings.reflectionAtlas;
+        return this.settings.renderMode === RenderMode.Mesh && !!atlas && atlas.isReady();
+    }
+
     applyMeshLighting(lighting: MeshLightingSettings): void {
         this.storeFixedLighting(lighting);
         const material = this.shaderMaterial;
@@ -527,7 +460,7 @@ export class SpriteBatch extends VFXBatch {
         this.fixedAmbientColor.set(lighting.ambient.r, lighting.ambient.g, lighting.ambient.b);
     }
 
-    private writeFixedLighting(material: ShaderMaterial): void {
+    private writeFixedLighting(material: ShaderMaterial | Effect): void {
         material.setVector3('lightDirection', this.fixedLightDirection);
         material.setVector3('lightColor', this.fixedLightColor);
         material.setVector3('ambientColor', this.fixedAmbientColor);
@@ -581,10 +514,10 @@ export class SpriteBatch extends VFXBatch {
     private quaternion5_ = new Quaternion();
     private rotationMat_ = new Matrix3();
     private rotationMat2_ = new Matrix3();
-    private lastStretchedSpeedFactor = Number.NaN;
     /** Slot 0 holds the zero-alpha instance since the batch last went empty. */
     private clearedInstanceUploaded = false;
 
+    /** @internal */
     update(): void {
         let index = 0;
         let particleCount = 0;
@@ -593,7 +526,7 @@ export class SpriteBatch extends VFXBatch {
         const isStretchedRender = renderMode === RenderMode.StretchedBillBoard;
         const isBeamRender = renderMode === RenderMode.Beam;
         const usesVelocity = isStretchedRender || isBeamRender;
-        const flipsSprites = SpriteBatch.takesPivotAndFlip(renderMode);
+        const flipsSprites = takesPivotAndSizeLimits(renderMode);
 
         const visibleSystems = this.getVisibleSystems();
         for (let i = 0; i < visibleSystems.length; i++) {
@@ -894,7 +827,7 @@ export class SpriteBatch extends VFXBatch {
                         const vx = velocity.x + (velocity.x - previousVelocity.x) * stepFraction;
                         const vy = velocity.y + (velocity.y - previousVelocity.y) * stepFraction;
                         const vz = velocity.z + (velocity.z - previousVelocity.z) * stepFraction;
-                        let vel: Vector3 = this.vector_;
+                        const vel: Vector3 = this.vector_;
                         vel.set(vx, vy, vz);
                         if (!systemWorldSpace) {
                             if (particle.parentMatrix) {
@@ -913,6 +846,10 @@ export class SpriteBatch extends VFXBatch {
                 }
             }
 
+            const tint = (system as ParticleSystem).tint;
+            if (tint !== undefined && index > firstIndex) {
+                SpriteBatch.applyTint(this.colorBuffer, firstIndex * 4, index - firstIndex, tint);
+            }
             if (flipsSprites && system.flip !== undefined) {
                 if (store !== undefined) {
                     SpriteBatch.applyFlip(this.sizeBuffer, firstIndex * 3, store.flip, particleNum);
@@ -925,10 +862,6 @@ export class SpriteBatch extends VFXBatch {
             }
         }
 
-        if (isStretchedRender && visibleSystems.length > 0) {
-            this.syncStretchedSpeedFactor(visibleSystems[0]);
-        }
-
         // Keep the mesh enabled even when count is 0 — toggling visibility off for a
         // single frame (common with short lifetimes + low emission overlap) causes flicker.
         this.mesh.forcedInstanceCount = index;
@@ -961,32 +894,6 @@ export class SpriteBatch extends VFXBatch {
         }
     }
 
-    /**
-     * Pushes the stretched-billboard speed factor to the shader when it changed.
-     *
-     * Deliberately kept out of `update`: touching the loosely typed
-     * `mesh.material` from inside that function gives V8 a generic property
-     * access it has no feedback for, which knocks the whole particle loop out of
-     * optimised code on every frame.
-     */
-    private syncStretchedSpeedFactor(system: IParticleSystem): void {
-        const material = this.shaderMaterial;
-        if (material === null) {
-            return;
-        }
-        const speedFactor = (system.rendererEmitterSettings as StretchedBillBoardSettings).speedFactor ?? 1.0;
-        const clampedSpeedFactor = speedFactor === 0 ? 0.001 : speedFactor;
-        if (clampedSpeedFactor !== this.lastStretchedSpeedFactor) {
-            material.setFloat('speedFactor', clampedSpeedFactor);
-            this.lastStretchedSpeedFactor = clampedSpeedFactor;
-        }
-    }
-
-    /** Stretched billboards and beams: drawn along a per-instance vector, by the stretched shader. */
-    private static drawsAlongVelocity(renderMode: RenderMode): boolean {
-        return renderMode === RenderMode.StretchedBillBoard || renderMode === RenderMode.Beam;
-    }
-
     private readonly beamEnd_ = new Vector3();
 
     /**
@@ -1010,14 +917,14 @@ export class SpriteBatch extends VFXBatch {
         }
     }
 
-    /** The quads that take a pivot and flip: every billboard kind, stretched included, but not meshes or beams. */
-    private static takesPivotAndFlip(renderMode: RenderMode): boolean {
-        return (
-            renderMode === RenderMode.BillBoard ||
-            renderMode === RenderMode.StretchedBillBoard ||
-            renderMode === RenderMode.VerticalBillBoard ||
-            renderMode === RenderMode.HorizontalBillBoard
-        );
+    /** Multiplies `count` RGBA colours starting at `base` by a system's {@link ParticleSystem.tint}. */
+    private static applyTint(colors: Float32Array, base: number, count: number, tint: Vector4): void {
+        for (let j = 0, o = base; j < count; j++, o += 4) {
+            colors[o] *= tint.x;
+            colors[o + 1] *= tint.y;
+            colors[o + 2] *= tint.z;
+            colors[o + 3] *= tint.w;
+        }
     }
 
     /**
@@ -1281,7 +1188,11 @@ export class SpriteBatch extends VFXBatch {
         }
     }
 
+    /** @internal */
     dispose(): void {
+        this.disposed = true;
+        this.cancelAtlasRebuild?.();
+        this.cancelAtlasRebuild = null;
         if (this.mesh.material) {
             this.mesh.material.dispose();
         }