babylon.quarks 0.25.0 → 0.27.0

package/src/shaderProgram.ts

@@ -0,0 +1,325 @@
+import {Constants} from '@babylonjs/core/Engines/constants';
+import {hasSizeLimits, takesPivotAndSizeLimits, tilesSheet} from './batchKey';
+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 type {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 trail_frag from './shaders/trail_frag.glsl';
+import trail_frag_wgsl from './shaders/trail_frag.wgsl';
+import trail_vert from './shaders/trail_vert.glsl';
+import trail_vert_wgsl from './shaders/trail_vert.wgsl';
+import {readsUV1, RenderMode, StoredBatchSettings} from './VFXBatch';
+
+/**
+ * The part of a batch's settings that decides its shader: the render mode, which textures and
+ * effects are compiled in, and the blend state the fog and the fade read. Everything else a
+ * batch holds (geometry, draw order, the effects' parameters) is a buffer or a uniform value.
+ */
+export type ShaderSettings = Pick<
+    StoredBatchSettings,
+    | 'renderMode'
+    | 'texture'
+    | 'reflectionAtlas'
+    | 'uTileCount'
+    | 'vTileCount'
+    | 'blendTiles'
+    | 'softParticles'
+    | 'materialAlphaTest'
+    | 'materialTransparent'
+    | 'materialBlendMode'
+    | 'applyFog'
+    | 'pivot'
+    | 'minParticleSize'
+    | 'maxParticleSize'
+    | 'lighting'
+    | 'rim'
+    | 'mapUV'
+    | 'uvDistortion'
+    | 'gradientMap'
+    | 'erosion'
+>;
+
+/** What the material needs to know about the depth texture soft particles read. */
+export interface ShaderDepth {
+    /** Whether the depth is packed into four 8-bit channels, as a `DepthRenderer` of type `UNSIGNED_BYTE` writes it. */
+    packed: boolean;
+}
+
+/**
+ * What a batch knows at compile time that its settings do not say: whether the textures it
+ * depends on are there to be sampled.
+ */
+export interface ShaderContext {
+    /**
+     * The depth texture soft particles read, when one is attached to the renderer. Soft particles
+     * compile only with a depth texture.
+     */
+    depth: ShaderDepth | null;
+    /** Whether the mesh batch's reflection atlas has finished loading; it is sampled only then. */
+    envAtlasReady: boolean;
+    /** Whether the mesh batch has a second UV set to read for {@link UVChannel} 1. */
+    meshUV2: boolean;
+}
+
+/**
+ * One compiled shader of the library: the sources in both languages and the defines, attributes,
+ * uniforms and samplers the material is built with. Built by {@link shaderProgram} from a
+ * batch's settings, so a batch and a shader validator describe the same material.
+ */
+export interface ShaderProgram {
+    /** The name the sources are registered under in Babylon's shader store, one per render mode. */
+    name: string;
+    /** The vertex shader in both languages. */
+    vertex: ShaderSources;
+    /** The fragment shader in both languages. */
+    fragment: ShaderSources;
+    /** The preprocessor defines, without the `#define`. */
+    defines: string[];
+    /** The vertex attributes the material binds. */
+    attributes: string[];
+    /** The uniforms the material declares. */
+    uniforms: string[];
+    /** The texture samplers the material declares. */
+    samplers: string[];
+}
+
+/** The vertex attributes every sprite shader reads. */
+const SPRITE_ATTRIBUTES = ['position', 'uv', 'offset', 'color', 'size', 'rotation', 'uvTile'];
+/** The vertex attributes the trail shader reads. */
+const TRAIL_ATTRIBUTES = ['position', 'previous', 'next', 'side', 'width', 'uv', 'color'];
+/** The fog uniforms, declared on every material so a scene can turn its fog on without a recompile. */
+export const FOG_UNIFORMS = ['vFogInfos', 'vFogColor'];
+
+/** Whether `renderMode` is drawn by the stretched shader: along a per-instance vector. */
+export function drawsAlongVelocity(renderMode: RenderMode): boolean {
+    return renderMode === RenderMode.StretchedBillBoard || renderMode === RenderMode.Beam;
+}
+
+/**
+ * Whether the material samples a map: the settings' texture, or the white placeholder a mesh
+ * batch gets, since a mesh effect with no sampler at all often never becomes drawable on iOS
+ * WebKit.
+ */
+export function samplesMap(settings: {renderMode: RenderMode; texture: unknown}): boolean {
+    return settings.texture !== null || settings.renderMode === RenderMode.Mesh;
+}
+
+/** Whether the blend mode adds to the frame, in which case fog and fade darken instead of mixing. */
+export function blendsAdditively(settings: {materialTransparent: boolean; materialBlendMode: number}): boolean {
+    return (
+        settings.materialTransparent &&
+        (settings.materialBlendMode === Constants.ALPHA_ADD || settings.materialBlendMode === Constants.ALPHA_ONEONE)
+    );
+}
+
+/** The shader program a batch with `settings` compiles, given what it knows about its textures. */
+export function shaderProgram(settings: ShaderSettings, context: ShaderContext): ShaderProgram {
+    return settings.renderMode === RenderMode.Trail
+        ? trailShaderProgram(settings, context)
+        : spriteShaderProgram(settings, context);
+}
+
+/** The program of a sprite, stretched or mesh batch. */
+function spriteShaderProgram(settings: ShaderSettings, context: ShaderContext): ShaderProgram {
+    const renderMode = settings.renderMode;
+    const isMesh = renderMode === RenderMode.Mesh;
+    // The sources only depend on the render mode, so the store entry is registered once per
+    // mode: a unique name per material would leak store entries and defeat the effect cache.
+    const name = `quarksParticle_${renderMode}`;
+    let vertex: ShaderSources;
+    let fragment: ShaderSources;
+    if (isMesh) {
+        vertex = {glsl: local_particle_physics_vert, wgsl: local_particle_physics_vert_wgsl};
+        fragment = {glsl: particle_physics_frag, wgsl: particle_physics_frag_wgsl};
+    } else if (drawsAlongVelocity(renderMode)) {
+        vertex = {glsl: stretched_bb_particle_vert, wgsl: stretched_bb_particle_vert_wgsl};
+        fragment = {glsl: particle_frag, wgsl: particle_frag_wgsl};
+    } else {
+        vertex = {glsl: particle_vert, wgsl: particle_vert_wgsl};
+        fragment = {glsl: particle_frag, wgsl: particle_frag_wgsl};
+    }
+
+    const defines = fogDefines(settings);
+    const attributes = [...SPRITE_ATTRIBUTES];
+    const uniforms = ['world', 'view', 'projection', ...FOG_UNIFORMS];
+    const samplers: string[] = [];
+
+    if (samplesMap(settings)) {
+        defines.push('USE_MAP');
+        samplers.push('map');
+    }
+    const envAtlas = isMesh && settings.reflectionAtlas !== null && context.envAtlasReady;
+    if (envAtlas) {
+        defines.push('USE_ENVMAP_ATLAS');
+        samplers.push('envAtlas');
+        uniforms.push('reflectionLevel');
+    }
+    if (tilesSheet(settings)) {
+        defines.push('UV_TILE');
+        uniforms.push('tileCountX', 'tileCountY');
+        // The second cell only exists on a sheet; a 1×1 sheet has nothing to blend into.
+        if (settings.blendTiles) {
+            defines.push('TILE_BLEND');
+        }
+    }
+    softDefines(settings, context, defines, uniforms, samplers);
+    if (renderMode === RenderMode.VerticalBillBoard) {
+        defines.push('VERTICAL');
+    }
+    if (renderMode === RenderMode.HorizontalBillBoard) {
+        defines.push('HORIZONTAL');
+    }
+    if (renderMode === RenderMode.Beam) {
+        defines.push('BEAM');
+    }
+    if (takesPivotAndSizeLimits(renderMode)) {
+        if (settings.pivot) {
+            defines.push('PIVOT');
+            uniforms.push('pivot');
+        }
+        if (hasSizeLimits(settings)) {
+            defines.push('SIZE_LIMITS');
+            uniforms.push('sizeLimits');
+        }
+    }
+    const lit = isMesh && (settings.lighting ?? 'fixed') !== 'unlit';
+    if (isMesh && !lit) {
+        defines.push('MESH_UNLIT');
+    }
+    if (lit) {
+        uniforms.push('lightDirection', 'lightColor', 'ambientColor');
+    }
+    const rim = isMesh ? settings.rim : undefined;
+    if (rim) {
+        defines.push('MESH_RIM');
+        if (rim.mode === 'fade') {
+            defines.push('MESH_RIM_FADE');
+        } else if (rim.mode === 'mix') {
+            defines.push('MESH_RIM_MIX');
+        }
+        uniforms.push('rimColor', 'rimParams');
+    }
+    if (envAtlas || rim) {
+        uniforms.push('eyePosition');
+    }
+    surfaceDefines(settings, defines, uniforms, samplers);
+    if (isMesh) {
+        attributes.push('normal');
+        if (readsUV1(settings) && context.meshUV2) {
+            defines.push('MESH_UV2');
+            attributes.push('uv2');
+        }
+    }
+    if (drawsAlongVelocity(renderMode)) {
+        attributes.push('velocity');
+    }
+    return {name, vertex, fragment, defines, attributes, uniforms, samplers};
+}
+
+/** The program of a trail batch. */
+function trailShaderProgram(settings: ShaderSettings, context: ShaderContext): ShaderProgram {
+    const defines = fogDefines(settings);
+    const attributes = [...TRAIL_ATTRIBUTES];
+    const uniforms = ['view', 'projection', ...FOG_UNIFORMS];
+    const samplers: string[] = [];
+    if (settings.texture !== null) {
+        defines.push('USE_MAP');
+        samplers.push('map');
+    }
+    surfaceDefines(settings, defines, uniforms, samplers);
+    softDefines(settings, context, defines, uniforms, samplers);
+    if (readsUV1(settings)) {
+        // A trail's channel 1 arrives as its own vertex buffer.
+        attributes.push('uv2');
+    }
+    return {
+        name: 'quarksTrail',
+        vertex: {glsl: trail_vert, wgsl: trail_vert_wgsl},
+        fragment: {glsl: trail_frag, wgsl: trail_frag_wgsl},
+        defines,
+        attributes,
+        uniforms,
+        samplers,
+    };
+}
+
+/**
+ * The fog defines: `FOG` when the settings apply the scene's fog, and `FOG_ADDITIVE` when the
+ * particles add to the frame, so that they fade toward black instead of the fog colour, which
+ * would fog the whole screen (what Unity does for additive materials).
+ */
+function fogDefines(settings: ShaderSettings): string[] {
+    if (!settings.applyFog) {
+        return [];
+    }
+    return blendsAdditively(settings) ? ['FOG', 'FOG_ADDITIVE'] : ['FOG'];
+}
+
+/** Soft particles, when on and a depth texture is there to read, and the alpha test. */
+function softDefines(
+    settings: ShaderSettings,
+    context: ShaderContext,
+    defines: string[],
+    uniforms: string[],
+    samplers: string[]
+): void {
+    if (settings.softParticles && context.depth !== null) {
+        defines.push('SOFT_PARTICLES');
+        if (context.depth.packed) {
+            defines.push('SOFT_DEPTH_PACKED');
+        }
+        uniforms.push('softParams', 'projParams');
+        samplers.push('depthTexture');
+    }
+    if (settings.materialAlphaTest > 0) {
+        defines.push('USE_ALPHATEST');
+        uniforms.push('alphaTest');
+    }
+}
+
+/** The texture effects of `chunks/surface.ts`: the map's layout, distortion, gradient map and erosion. */
+function surfaceDefines(settings: ShaderSettings, defines: string[], uniforms: string[], samplers: string[]): void {
+    const {mapUV, uvDistortion, gradientMap, erosion} = settings;
+    if (readsUV1(settings)) {
+        defines.push('UV1');
+    }
+    if (mapUV) {
+        defines.push('MAP_TRANSFORM');
+        if (mapUV.channel === 1) {
+            defines.push('MAP_UV1');
+        }
+        uniforms.push('mapTransform');
+    }
+    if (uvDistortion) {
+        defines.push('UV_DISTORTION');
+        if (uvDistortion.mapUV.channel === 1) {
+            defines.push('UV_DISTORTION_UV1');
+        }
+        samplers.push('distortionMap');
+        uniforms.push('distortionTransform', 'distortionStrength');
+    }
+    if (gradientMap) {
+        defines.push('GRADIENT_MAP');
+        samplers.push('gradientMap');
+        uniforms.push('gradientMapRange', 'gradientMapChannel');
+    }
+    if (erosion) {
+        defines.push('EROSION');
+        uniforms.push('erosionParams', 'erosionEdgeColor');
+        if (erosion.mask) {
+            defines.push('EROSION_MASK');
+            if (erosion.maskUV.channel === 1) {
+                defines.push('EROSION_MASK_UV1');
+            }
+            samplers.push('erosionMask');
+            uniforms.push('erosionMaskTransform');
+        }
+    }
+}

package/src/shaderVariants.ts

@@ -0,0 +1,225 @@
+import {Constants} from '@babylonjs/core/Engines/constants';
+import type {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import {Vector3} from 'quarks.core';
+import {ShaderContext, shaderProgram, ShaderProgram, ShaderSettings} from './shaderProgram';
+import {
+    normalizeErosion,
+    normalizeGradientMap,
+    normalizeMapUV,
+    normalizeMeshRim,
+    normalizeUVDistortion,
+    RenderMode,
+} from './VFXBatch';
+
+/**
+ * One shader the library can compile: a {@link ShaderProgram} with the settings that produce it,
+ * named for the renderer's benefit. See {@link shaderVariants}.
+ */
+export interface ShaderVariant {
+    /** The render mode and the features compiled in, for a report. */
+    name: string;
+    /** The program a batch with these settings builds. */
+    program: ShaderProgram;
+}
+
+/** A texture reference for settings that only ask whether one is set; it is never sampled. */
+const TEXTURE = {} as BaseTexture;
+
+/** The settings of a bare batch in `renderMode`: no texture, no effects, fog off, 1×1 sheet. */
+function bare(renderMode: RenderMode): ShaderSettings {
+    return {
+        renderMode,
+        texture: null,
+        reflectionAtlas: null,
+        uTileCount: 1,
+        vTileCount: 1,
+        blendTiles: false,
+        softParticles: false,
+        materialAlphaTest: 0,
+        materialTransparent: true,
+        materialBlendMode: Constants.ALPHA_COMBINE,
+        applyFog: false,
+        pivot: undefined,
+        minParticleSize: 0,
+        maxParticleSize: Infinity,
+        lighting: renderMode === RenderMode.Mesh ? 'fixed' : undefined,
+        rim: undefined,
+        mapUV: undefined,
+        uvDistortion: undefined,
+        gradientMap: undefined,
+        erosion: undefined,
+    };
+}
+
+/** A settings change with the name it adds to the variant. */
+interface Axis {
+    name: string;
+    settings?: Partial<ShaderSettings>;
+    context?: Partial<ShaderContext>;
+}
+
+const NONE: Axis = {name: ''};
+
+/** The render modes and the mode-specific features: quad pivot and size limits, mesh lighting, rim and reflection. */
+const TARGETS: Axis[] = [
+    {name: 'billboard', settings: {renderMode: RenderMode.BillBoard}},
+    {name: 'vertical billboard', settings: {renderMode: RenderMode.VerticalBillBoard}},
+    {name: 'horizontal billboard', settings: {renderMode: RenderMode.HorizontalBillBoard}},
+    {name: 'stretched', settings: {renderMode: RenderMode.StretchedBillBoard}},
+    {name: 'beam', settings: {renderMode: RenderMode.Beam}},
+    {name: 'mesh', settings: {renderMode: RenderMode.Mesh}},
+    {name: 'mesh scene lit', settings: {renderMode: RenderMode.Mesh, lighting: 'scene'}},
+    {name: 'mesh unlit', settings: {renderMode: RenderMode.Mesh, lighting: 'unlit'}},
+    {name: 'mesh rim', settings: {renderMode: RenderMode.Mesh, rim: normalizeMeshRim({mode: 'add'})}},
+    {
+        name: 'mesh unlit rim mix',
+        settings: {renderMode: RenderMode.Mesh, lighting: 'unlit', rim: normalizeMeshRim({mode: 'mix'})},
+    },
+    {
+        name: 'mesh unlit rim fade',
+        settings: {renderMode: RenderMode.Mesh, lighting: 'unlit', rim: normalizeMeshRim({mode: 'fade'})},
+    },
+    {
+        name: 'mesh reflecting',
+        settings: {renderMode: RenderMode.Mesh, reflectionAtlas: TEXTURE},
+        context: {envAtlasReady: true},
+    },
+    {
+        name: 'mesh unlit reflecting rim fade',
+        settings: {
+            renderMode: RenderMode.Mesh,
+            lighting: 'unlit',
+            reflectionAtlas: TEXTURE,
+            rim: normalizeMeshRim({mode: 'fade'}),
+        },
+        context: {envAtlasReady: true},
+    },
+    {name: 'trail', settings: {renderMode: RenderMode.Trail}},
+];
+
+/** Pivot and screen-size limits, which only the quad modes read. */
+const QUAD: Axis[] = [
+    NONE,
+    {name: 'pivot', settings: {pivot: new Vector3(0.5, 0, 0)}},
+    {name: 'size limits', settings: {minParticleSize: 0.01}},
+    {name: 'pivot size limits', settings: {pivot: new Vector3(0, 0.5, 0.5), maxParticleSize: 0.5}},
+];
+
+const TILE: Axis[] = [
+    NONE,
+    {name: 'sheet', settings: {uTileCount: 4, vTileCount: 2}},
+    {name: 'sheet blend', settings: {uTileCount: 4, vTileCount: 2, blendTiles: true}},
+];
+const MAP: Axis[] = [NONE, {name: 'map', settings: {texture: TEXTURE}}];
+const SOFT: Axis[] = [
+    NONE,
+    {name: 'soft', settings: {softParticles: true}, context: {depth: {packed: false}}},
+    {name: 'soft packed', settings: {softParticles: true}, context: {depth: {packed: true}}},
+];
+const ALPHA_TEST: Axis[] = [NONE, {name: 'alpha test', settings: {materialAlphaTest: 0.5}}];
+const FOG: Axis[] = [
+    NONE,
+    {name: 'fog', settings: {applyFog: true}},
+    {name: 'fog additive', settings: {applyFog: true, materialBlendMode: Constants.ALPHA_ADD}},
+];
+
+/** Texture effects (`chunks/surface.ts`), alone and together, on both UV channels. */
+const SURFACE: Axis[] = (() => {
+    const uv0 = normalizeMapUV({tiling: [2, 2]});
+    const uv1 = normalizeMapUV({channel: 1, tiling: [2, 2]});
+    const distortion0 = normalizeUVDistortion({map: TEXTURE});
+    const distortion1 = normalizeUVDistortion({map: TEXTURE, mapUV: {channel: 1}});
+    const gradient = normalizeGradientMap({ramp: TEXTURE});
+    const erosion = normalizeErosion({});
+    const erosionMask0 = normalizeErosion({mask: TEXTURE});
+    const erosionMask1 = normalizeErosion({mask: TEXTURE, maskUV: {channel: 1}});
+    return [
+        {name: 'map transform', settings: {mapUV: uv0}},
+        {name: 'map transform uv1', settings: {mapUV: uv1}},
+        {name: 'gradient map', settings: {gradientMap: gradient}},
+        {name: 'erosion', settings: {erosion}},
+        {name: 'erosion mask', settings: {erosion: erosionMask0}},
+        {name: 'erosion mask uv1', settings: {erosion: erosionMask1}},
+        {name: 'distortion', settings: {uvDistortion: distortion0}},
+        {name: 'distortion uv1', settings: {uvDistortion: distortion1}},
+        {
+            name: 'map transform distortion gradient erosion mask',
+            settings: {mapUV: uv0, uvDistortion: distortion0, gradientMap: gradient, erosion: erosionMask0},
+        },
+        {
+            name: 'map transform uv1 distortion gradient erosion',
+            settings: {mapUV: uv1, uvDistortion: distortion0, gradientMap: gradient, erosion},
+        },
+        {
+            name: 'every effect on uv1',
+            settings: {mapUV: uv1, uvDistortion: distortion1, gradientMap: gradient, erosion: erosionMask1},
+        },
+    ];
+})();
+
+/** The targets the texture effects are tried on: one per vertex shader and fragment family. */
+const SURFACE_TARGETS = [
+    'billboard',
+    'stretched',
+    'beam',
+    'mesh',
+    'mesh unlit',
+    'mesh unlit rim mix',
+    'mesh reflecting',
+    'trail',
+];
+
+/** A mesh batch whose geometry has a second UV set. */
+const MESH_UV2: Axis = {name: 'uv2', context: {meshUV2: true}};
+
+/** Soft, alpha-tested and fogged at once, to try the effects with the rest of the fragment. */
+const EVERYTHING_ELSE: Axis = {
+    name: 'soft packed alpha test fog additive',
+    settings: {softParticles: true, materialAlphaTest: 0.5, applyFog: true, materialBlendMode: Constants.ALPHA_ADD},
+    context: {depth: {packed: true}},
+};
+
+/**
+ * Every shader program the library can compile, one per distinct set of defines: every render
+ * mode with every combination of sheet, map, soft particles, alpha test and fog, and the texture
+ * effects alone and together on each shader family. What a shader validator compiles, and what
+ * an application can warm the shader cache with before its first frame (Unity's
+ * ShaderVariantCollection). Built by {@link shaderProgram}, so a variant here is a material a
+ * batch would build.
+ */
+export function shaderVariants(): ShaderVariant[] {
+    const seen = new Set<string>();
+    const out: ShaderVariant[] = [];
+    const add = (axes: Axis[]) => {
+        const settings = bare(RenderMode.BillBoard);
+        const context: ShaderContext = {depth: null, envAtlasReady: false, meshUV2: false};
+        for (const axis of axes) {
+            Object.assign(settings, axis.settings);
+            Object.assign(context, axis.context);
+        }
+        const program = shaderProgram(settings, context);
+        const key = program.name + ' ' + program.defines.join(',');
+        if (seen.has(key)) {
+            return;
+        }
+        seen.add(key);
+        const features = axes.map((axis) => axis.name).filter((name) => name !== '');
+        out.push({name: `${features.join(', ')} [${program.defines.join(',') || 'none'}]`, program});
+    };
+
+    for (const target of TARGETS)
+        for (const quad of QUAD)
+            for (const tile of TILE)
+                for (const map of MAP)
+                    for (const soft of SOFT)
+                        for (const alphaTest of ALPHA_TEST)
+                            for (const fog of FOG) add([target, quad, tile, map, soft, alphaTest, fog]);
+
+    for (const target of TARGETS.filter((t) => SURFACE_TARGETS.includes(t.name)))
+        for (const uv2 of target.settings?.renderMode === RenderMode.Mesh ? [NONE, MESH_UV2] : [NONE])
+            for (const surface of SURFACE)
+                for (const map of MAP)
+                    for (const tile of [NONE, TILE[2]])
+                        for (const rest of [NONE, EVERYTHING_ELSE]) add([target, uv2, surface, map, tile, rest]);
+    return out;
+}

package/src/shaders/chunks/fog.ts

@@ -44,7 +44,8 @@ float quarksFogFactor() {
     float fogDensity = vFogInfos.w;
     float fogDistance = length(vFogDistance);
     if (vFogInfos.x == 3.0) {
-        fogCoeff = (fogEnd - fogDistance) / (fogEnd - fogStart);
+        // A zero-width band is a cut at its distance, not a division by zero.
+        fogCoeff = (fogEnd - fogDistance) / max(fogEnd - fogStart, 1e-6);
     } else if (vFogInfos.x == 1.0) {
         fogCoeff = exp(-fogDistance * fogDensity);
     } else if (vFogInfos.x == 2.0) {
@@ -101,7 +102,8 @@ fn quarksFog(rgb: vec3f, fogDistanceVector: vec3f) -> vec3f {
     let fogDensity = uniforms.vFogInfos.w;
     let fogDistance = length(fogDistanceVector);
     if (uniforms.vFogInfos.x == 3.0) {
-        fogCoeff = (fogEnd - fogDistance) / (fogEnd - fogStart);
+        // A zero-width band is a cut at its distance, not a division by zero.
+        fogCoeff = (fogEnd - fogDistance) / max(fogEnd - fogStart, 1e-6);
     } else if (uniforms.vFogInfos.x == 1.0) {
         fogCoeff = exp(-fogDistance * fogDensity);
     } else if (uniforms.vFogInfos.x == 2.0) {

package/src/shaders/chunks/sheet.ts

@@ -0,0 +1,111 @@
+/**
+ * The flipbook (sprite sheet) cell for the sprite, stretched and mesh vertex
+ * shaders, in both shader languages: Unity's Texture Sheet Animation, Unreal's
+ * SubUV.
+ *
+ * `uvTile` is the particle's frame, counted along the rows from the top-left
+ * cell; `tileCountX` and `tileCountY` are the sheet's columns and rows. The
+ * frame is wrapped into the sheet, so a frame past the last cell starts over
+ * and a negative one counts back from the end, in both languages alike (the
+ * WGSL `%` truncates where GLSL's `mod` floors, so the wrap is spelled out).
+ * Under `TILE_BLEND` the next frame, wrapped the same way, is passed with the
+ * fraction between the two, for the fragment to cross-fade (Unity's flipbook
+ * blending).
+ */
+
+/**
+ * The cell of `frame` on a sheet of `columns` × `rows`, counted along the rows
+ * from the top-left cell and wrapped into the sheet, as the shaders count it.
+ * For a host that lays its cells out on the CPU, such as the trail.
+ */
+export function sheetCell(frame: number, columns: number, rows: number): {column: number; row: number} {
+    const total = columns * rows;
+    const tile = wrap(Math.floor(frame), total);
+    return {column: wrap(tile, columns), row: Math.floor(tile / columns)};
+}
+
+/** A floored modulo, as GLSL's `mod`: never negative for a positive divisor. */
+function wrap(value: number, divisor: number): number {
+    return value - divisor * Math.floor(value / divisor);
+}
+
+/** Vertex-side declarations, GLSL: the sheet's size and the cell varyings. */
+export const sheetVertexDeclarationGLSL = /* glsl */ `
+#ifdef UV_TILE
+uniform float tileCountX;
+uniform float tileCountY;
+#endif
+#ifdef TILE_BLEND
+varying vec2 vUV2;
+varying float vTileBlend;
+#endif
+`;
+
+/**
+ * Writes `vUV` (and the blend varyings) from the quad UV expression `uv` and the
+ * frame `uvTile`, GLSL.
+ */
+export function sheetVertexGLSL(uv: string): string {
+    return /* glsl */ `
+#ifdef UV_TILE
+    {
+        vec2 tc = vec2(tileCountX, tileCountY);
+        float tileTotal = tc.x * tc.y;
+        float baseTile = mod(floor(uvTile), tileTotal);
+        vec2 tileUV = vec2(mod(baseTile, tc.x), tc.y - 1.0 - floor(baseTile / tc.x)) / tc;
+        vUV = ${uv} / tc + tileUV;
+#ifdef TILE_BLEND
+        float nextTile = mod(baseTile + 1.0, tileTotal);
+        vec2 nextUV = vec2(mod(nextTile, tc.x), tc.y - 1.0 - floor(nextTile / tc.x)) / tc;
+        vUV2 = ${uv} / tc + nextUV;
+        vTileBlend = fract(uvTile);
+#endif
+    }
+#else
+    vUV = ${uv};
+#endif
+`;
+}
+
+/** Vertex-side declarations, WGSL: the sheet's size and the cell varyings. */
+export const sheetVertexDeclarationWGSL = /* wgsl */ `
+#ifdef UV_TILE
+uniform tileCountX: f32;
+uniform tileCountY: f32;
+
+// A floored modulo, as GLSL's mod: never negative for a positive divisor.
+fn quarksWrap(value: f32, divisor: f32) -> f32 {
+    return value - divisor * floor(value / divisor);
+}
+#endif
+#ifdef TILE_BLEND
+varying vUV2: vec2f;
+varying vTileBlend: f32;
+#endif
+`;
+
+/**
+ * Writes `vertexOutputs.vUV` (and the blend varyings) from the quad UV
+ * expression `uv` and the frame `vertexInputs.uvTile`, WGSL.
+ */
+export function sheetVertexWGSL(uv: string): string {
+    return /* wgsl */ `
+#ifdef UV_TILE
+    {
+        let tc = vec2f(uniforms.tileCountX, uniforms.tileCountY);
+        let tileTotal = tc.x * tc.y;
+        let baseTile = quarksWrap(floor(vertexInputs.uvTile), tileTotal);
+        let tileUV = vec2f(quarksWrap(baseTile, tc.x), tc.y - 1.0 - floor(baseTile / tc.x)) / tc;
+        vertexOutputs.vUV = ${uv} / tc + tileUV;
+#ifdef TILE_BLEND
+        let nextTile = quarksWrap(baseTile + 1.0, tileTotal);
+        let nextUV = vec2f(quarksWrap(nextTile, tc.x), tc.y - 1.0 - floor(nextTile / tc.x)) / tc;
+        vertexOutputs.vUV2 = ${uv} / tc + nextUV;
+        vertexOutputs.vTileBlend = fract(vertexInputs.uvTile);
+#endif
+    }
+#else
+    vertexOutputs.vUV = ${uv};
+#endif
+`;
+}