@driftengine/core 4.8.4 → 4.8.6

package/dist/render/backend/webgl2/skinScatter.js

@@ -5,14 +5,15 @@
  *
  * **Drawn as it goes, not kept**: this backend issues a draw when it is asked for, and the state a
  * skin draw reads — its joint palette, its uniforms — is rewritten by the draw after it. So the
- * renderer draws each skin twice in place, the frame's half and then at once its diffuse half into
- * this target, which shares the frame's depth and tests for equality against it.
+ * renderer draws each skin three times in place: the frame's half, then at once the diffuse's light
+ * alone into this target and its colour alone into the other, both sharing the frame's depth and
+ * testing for equality against it. The blur spreads the light and multiplies it by the colour.
  *
  * **The units it reads are its own** — `SKIN_BLUR_TEXTURE_UNIT` and the one after — past every
  * unit a lit program binds, because it runs in the middle of a frame and the draws after it must
  * find their textures where they left them.
  */
-import { SKIN_BLUR_DEPTH_UNIT, SKIN_BLUR_TEXTURE_UNIT } from '../../lightBudget.js';
+import { SKIN_BLUR_ALBEDO_UNIT, SKIN_BLUR_DEPTH_UNIT, SKIN_BLUR_TEXTURE_UNIT, } from '../../lightBudget.js';
 import { blendKeeping } from '../../sceneCoverage.js';
 import { compileProgram, uniformLocations } from '../../shader.js';
 import { FULLSCREEN_VERT } from '../../shaders/fullscreen.js';
@@ -30,9 +31,13 @@ export class GlSkinScatter {
     depthToViewZ = new Float32Array(4);
     diffuse = null;
     across = null;
+    albedo = null;
     multisampled = null;
+    albedoMultisampled = null;
     drawFramebuffer = null;
     resolveFramebuffer = null;
+    albedoFramebuffer = null;
+    albedoResolveFramebuffer = null;
     acrossFramebuffer = null;
     width = 0;
     height = 0;
@@ -41,6 +46,7 @@ export class GlSkinScatter {
     /** Refused once and for good: a driver that will not render to half floats. */
     unavailable = false;
     cleared = false;
+    albedoCleared = false;
     drawn = false;
     constructor(gl) {
         this.gl = gl;
@@ -102,6 +108,16 @@ export class GlSkinScatter {
         }
         this.drawn = true;
     }
+    /** Bind the target for the same skin's colour half, cleared the first time a frame does. */
+    beginAlbedo() {
+        const { gl } = this;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.albedoFramebuffer);
+        gl.viewport(0, 0, this.width, this.height);
+        if (!this.albedoCleared) {
+            gl.clearBufferfv(gl.COLOR, 0, CLEAR);
+            this.albedoCleared = true;
+        }
+    }
     /**
      * Across into the second target, then down and added into the frame, which `scene` binds. `depth`
      * is the frame's depth as a single-sampled texture, or null where none could be had — and then
@@ -110,9 +126,8 @@ export class GlSkinScatter {
     spread(scene, depth, empty, projection, inverse) {
         const { gl } = this;
         if (this.multisampled !== null) {
-            gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.drawFramebuffer);
-            gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.resolveFramebuffer);
-            gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+            this.resolve(this.drawFramebuffer, this.resolveFramebuffer);
+            this.resolve(this.albedoFramebuffer, this.albedoResolveFramebuffer);
         }
         gl.disable(gl.DEPTH_TEST);
         gl.disable(gl.CULL_FACE);
@@ -123,6 +138,9 @@ export class GlSkinScatter {
         const u = this.uniforms;
         gl.uniform1i(u['uSkin'] ?? null, SKIN_BLUR_TEXTURE_UNIT);
         gl.uniform1i(u['uDepth'] ?? null, SKIN_BLUR_DEPTH_UNIT);
+        gl.uniform1i(u['uAlbedo'] ?? null, SKIN_BLUR_ALBEDO_UNIT);
+        gl.activeTexture(gl.TEXTURE0 + SKIN_BLUR_ALBEDO_UNIT);
+        gl.bindTexture(gl.TEXTURE_2D, this.albedo ?? empty);
         /* The four terms that carry a depth back to view-space metres: the occlusion blur's own. */
         this.depthToViewZ[0] = inverse[10] ?? 0;
         this.depthToViewZ[1] = inverse[14] ?? 0;
@@ -141,12 +159,15 @@ export class GlSkinScatter {
         this.step[0] = 1 / this.width;
         this.step[1] = 0;
         gl.uniform2fv(u['uStep'] ?? null, this.step);
+        /* The light spreads on both axes; the colour is applied once, on the one adding into the frame. */
+        gl.uniform1f(u['uApplyAlbedo'] ?? null, 0);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         scene.bind();
         gl.bindTexture(gl.TEXTURE_2D, this.across);
         this.step[0] = 0;
         this.step[1] = 1 / this.height;
         gl.uniform2fv(u['uStep'] ?? null, this.step);
+        gl.uniform1f(u['uApplyAlbedo'] ?? null, 1);
         /* Added: its colour onto the frame's, the frame's alpha kept. */
         gl.enable(gl.BLEND);
         gl.blendEquation(gl.FUNC_ADD);
@@ -162,8 +183,16 @@ export class GlSkinScatter {
     /** Spent at the frame's start: what was drawn into the target was last frame's. */
     reset() {
         this.cleared = false;
+        this.albedoCleared = false;
         this.drawn = false;
     }
+    /** A multisampled target into its single-sampled texture. */
+    resolve(from, to) {
+        const { gl } = this;
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, from);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, to);
+        gl.blitFramebuffer(0, 0, this.width, this.height, 0, 0, this.width, this.height, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+    }
     dispose() {
         const { gl } = this;
         this.release();
@@ -181,36 +210,56 @@ export class GlSkinScatter {
         this.sharedDepth = depthRenderbuffer ?? depthTexture;
         this.diffuse = this.halfFloatTexture(width, height);
         this.across = this.halfFloatTexture(width, height);
-        this.drawFramebuffer = gl.createFramebuffer();
-        gl.bindFramebuffer(gl.FRAMEBUFFER, this.drawFramebuffer);
-        if (samples > 1 && depthRenderbuffer !== null) {
-            this.multisampled = gl.createRenderbuffer();
-            gl.bindRenderbuffer(gl.RENDERBUFFER, this.multisampled);
-            gl.renderbufferStorageMultisample(gl.RENDERBUFFER, samples, gl.RGBA16F, width, height);
-            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.RENDERBUFFER, this.multisampled);
-            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, depthRenderbuffer);
-        }
-        else {
-            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.diffuse, 0);
-            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, depthTexture, 0);
-        }
-        const drawReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
-        if (this.multisampled !== null) {
-            this.resolveFramebuffer = gl.createFramebuffer();
-            gl.bindFramebuffer(gl.FRAMEBUFFER, this.resolveFramebuffer);
-            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.diffuse, 0);
-        }
+        this.albedo = this.halfFloatTexture(width, height);
+        const multisampled = samples > 1 && depthRenderbuffer !== null;
+        const diffuse = this.drawTarget(this.diffuse, multisampled, depthTexture, depthRenderbuffer);
+        this.drawFramebuffer = diffuse.framebuffer;
+        this.multisampled = diffuse.multisampled;
+        this.resolveFramebuffer = diffuse.resolve;
+        const albedo = this.drawTarget(this.albedo, multisampled, depthTexture, depthRenderbuffer);
+        this.albedoFramebuffer = albedo.framebuffer;
+        this.albedoMultisampled = albedo.multisampled;
+        this.albedoResolveFramebuffer = albedo.resolve;
         this.acrossFramebuffer = gl.createFramebuffer();
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.acrossFramebuffer);
         gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.across, 0);
         const acrossReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
         gl.bindRenderbuffer(gl.RENDERBUFFER, null);
-        if (drawReady && acrossReady)
+        if (diffuse.ready && albedo.ready && acrossReady)
             return true;
         this.release();
         this.refuse();
         return false;
     }
+    /**
+     * A framebuffer a skin half draws into against the frame's depth: the texture itself, or a
+     * multisampled renderbuffer and the framebuffer that resolves it into the texture.
+     */
+    drawTarget(texture, multisampled, depthTexture, depthRenderbuffer) {
+        const { gl } = this;
+        const framebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        let samples = null;
+        if (multisampled && depthRenderbuffer !== null) {
+            samples = gl.createRenderbuffer();
+            gl.bindRenderbuffer(gl.RENDERBUFFER, samples);
+            gl.renderbufferStorageMultisample(gl.RENDERBUFFER, this.samples, gl.RGBA16F, this.width, this.height);
+            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.RENDERBUFFER, samples);
+            gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, depthRenderbuffer);
+        }
+        else {
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, depthTexture, 0);
+        }
+        const ready = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+        let resolve = null;
+        if (samples !== null) {
+            resolve = gl.createFramebuffer();
+            gl.bindFramebuffer(gl.FRAMEBUFFER, resolve);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+        }
+        return { framebuffer, multisampled: samples, resolve, ready };
+    }
     refuse() {
         if (this.unavailable)
             return;
@@ -237,20 +286,33 @@ export class GlSkinScatter {
             gl.deleteFramebuffer(this.drawFramebuffer);
         if (this.resolveFramebuffer !== null)
             gl.deleteFramebuffer(this.resolveFramebuffer);
+        if (this.albedoFramebuffer !== null)
+            gl.deleteFramebuffer(this.albedoFramebuffer);
+        if (this.albedoResolveFramebuffer !== null) {
+            gl.deleteFramebuffer(this.albedoResolveFramebuffer);
+        }
         if (this.acrossFramebuffer !== null)
             gl.deleteFramebuffer(this.acrossFramebuffer);
         if (this.multisampled !== null)
             gl.deleteRenderbuffer(this.multisampled);
+        if (this.albedoMultisampled !== null)
+            gl.deleteRenderbuffer(this.albedoMultisampled);
         if (this.diffuse !== null)
             gl.deleteTexture(this.diffuse);
         if (this.across !== null)
             gl.deleteTexture(this.across);
+        if (this.albedo !== null)
+            gl.deleteTexture(this.albedo);
         this.drawFramebuffer = null;
         this.resolveFramebuffer = null;
+        this.albedoFramebuffer = null;
+        this.albedoResolveFramebuffer = null;
         this.acrossFramebuffer = null;
         this.multisampled = null;
+        this.albedoMultisampled = null;
         this.diffuse = null;
         this.across = null;
+        this.albedo = null;
         this.sharedDepth = null;
     }
 }

package/dist/render/backend/webgpu/buffers.js

@@ -501,7 +501,8 @@ const INSTANCE_ATTRIBUTES = [
     { shaderLocation: 12, offset: 16, format: 'float32x4' },
     { shaderLocation: 13, offset: 32, format: 'float32x4' },
     { shaderLocation: 14, offset: 48, format: 'float32x4' },
-    { shaderLocation: 15, offset: 64, format: 'float32x3' },
+    /* The tint and, in w, the opacity. See `INSTANCE_FLOATS`. */
+    { shaderLocation: 15, offset: 64, format: 'float32x4' },
 ];
 /** The locations above, as the set the base layout must stand clear of on an instanced draw. */
 const INSTANCE_LOCATIONS = new Set(INSTANCE_ATTRIBUTES.map((attribute) => attribute.shaderLocation));

package/dist/render/backend/webgpu/clusterBinner.js

@@ -1,4 +1,4 @@
-import { CLUSTER_COUNT, LIGHT_TEXELS, MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, writeLightRecord, } from '../../clusteredLights.js';
+import { CLUSTER_COUNT, LIGHT_TEXELS, MAX_CLUSTERED_LIGHTS, TABLE_HEIGHT, TABLE_WIDTH, clusteredLightTotal, writeLightRecord, } from '../../clusteredLights.js';
 import { MAX_POINT_LIGHTS } from '../../lightBudget.js';
 import { CLUSTER_BIN_WGSL } from './shaders/clusterBin.wgsl.js';
 /**
@@ -129,7 +129,8 @@ export class ClusterBinner {
             return;
         if (params === null || lightBuffer === null)
             return;
-        const count = Math.min(frame.lights.count, MAX_CLUSTERED_LIGHTS);
+        /* The lamps and the clustered rectangles after them. See `ClusterLightSet.areas`. */
+        const count = clusteredLightTotal(frame.lights);
         /*
          * The records, by the function `buildLightClusters` writes them with, because the shader
          * copies them into the table verbatim and the lit pass reads one layout on both backends.

package/dist/render/backend/webgpu/flatPass.d.ts

@@ -1,5 +1,5 @@
 import type { SurfaceModelKind } from '../../surfaceModel.ts';
-import type { SkinHalf } from '../../shaders/flat/models.ts';
+import { type SkinHalf } from '../../shaders/flat/models.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { ClothViews } from './clothTextures.ts';
 /**
@@ -69,12 +69,14 @@ export declare function flatVertexKey(skinned: boolean, morphed: boolean, instan
 /** Everything the generator recorded about one variant of the vertex stage. */
 export declare function flatVertexBindings(skinned: boolean, morphed?: boolean, instanced?: boolean): StageBindings;
 /**
- * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` in
- * a skinned stage, nothing in any other. Every override a stage declares is set, and one this does
+ * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` and
+ * `CLOTH_BOUND` in a skinned stage, `LIGHTMAP_REGIONS` in an instanced one, nothing in any other. Every override a stage declares is set, and one this does
  * not know is refused here rather than defaulted. Shared with the shadow and glass-tint casters,
  * whose skinned stages declare the same switch.
  */
-export declare function vertexConstants(bindings: StageBindings, skinEight: boolean, cloth?: boolean): Record<string, number>;
+export declare function vertexConstants(bindings: StageBindings, skinEight: boolean, cloth?: boolean, 
+/** Whether an instanced stage reads its tint lane as a lightmap region. See `lightmap.ts`. */
+lightmapRegions?: boolean): Record<string, number>;
 export declare const FLAT_VERT_FIELDS: {
     readonly uViewProj: {
         readonly offset: 0;
@@ -233,7 +235,7 @@ skinEight?: boolean,
 cloth?: boolean, 
 /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
 model?: SurfaceModelKind | null, 
-/** Which half of a skin it draws. The key must carry it: `|ss` or `|sd`. See `SkinHalf`. */
+/** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
 skinPass?: SkinHalf): GPURenderPipeline;
 /**
  * The same pipeline, compiled off the main thread.

package/dist/render/backend/webgpu/flatPass.js

@@ -1,4 +1,5 @@
 import { SURFACE_MODEL_SWITCH } from '../../surfaceModel.js';
+import { SKIN_HALF_SWITCH } from '../../shaders/flat/models.js';
 import { DEPTH_COMPARE, DEPTH_FORMAT, depthOffsetForLayer } from '../../depthConvention.js';
 import { FLAT_BINDINGS, FLAT_FRAG_WGSL, FLAT_VERT_WGSL, } from '../../shaders/generated/flat.wgsl.js';
 import { vertexBufferLayouts } from './buffers.js';
@@ -71,18 +72,22 @@ export function flatVertexBindings(skinned, morphed = false, instanced = false)
 }
 const PLAIN_VERTEX = flatVertexBindings(false);
 /**
- * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` in
- * a skinned stage, nothing in any other. Every override a stage declares is set, and one this does
+ * A vertex stage's constants, keyed by each override's **id** as the fragment's are: `SKIN_EIGHT` and
+ * `CLOTH_BOUND` in a skinned stage, `LIGHTMAP_REGIONS` in an instanced one, nothing in any other. Every override a stage declares is set, and one this does
  * not know is refused here rather than defaulted. Shared with the shadow and glass-tint casters,
  * whose skinned stages declare the same switch.
  */
-export function vertexConstants(bindings, skinEight, cloth = false) {
+export function vertexConstants(bindings, skinEight, cloth = false, 
+/** Whether an instanced stage reads its tint lane as a lightmap region. See `lightmap.ts`. */
+lightmapRegions = false) {
     const constants = {};
     for (const [name, id] of Object.entries(bindings.overrides ?? {})) {
         if (name === 'SKIN_EIGHT')
             constants[String(id)] = skinEight ? 1 : 0;
         else if (name === 'CLOTH_BOUND')
             constants[String(id)] = cloth ? 1 : 0;
+        else if (name === 'LIGHTMAP_REGIONS')
+            constants[String(id)] = lightmapRegions ? 1 : 0;
         else
             throw new Error(`flatPass: a vertex stage declares a switch "${name}" nothing sets`);
     }
@@ -168,13 +173,9 @@ function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
             constants[String(id)] = name === modelSwitch ? 1 : 0;
             continue;
         }
-        /* Skin's two halves under the screen-space blur, set from the key as a model's switch is. */
-        if (name === 'SKIN_SCREEN' || name === 'SKIN_DIFFUSE') {
-            constants[String(id)] =
-                (name === 'SKIN_SCREEN' && skinPass === 'scene') ||
-                    (name === 'SKIN_DIFFUSE' && skinPass === 'diffuse')
-                    ? 1
-                    : 0;
+        /* Skin's halves under the screen-space blur, set from the key as a model's switch is. */
+        if (name === 'SKIN_SCREEN' || name === 'SKIN_DIFFUSE' || name === 'SKIN_ALBEDO') {
+            constants[String(id)] = skinPass !== 'whole' && name === SKIN_HALF_SWITCH[skinPass] ? 1 : 0;
             continue;
         }
         if (!(name in cache.litSwitches)) {
@@ -479,7 +480,7 @@ skinEight = false,
 cloth = false, 
 /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
 model = null, 
-/** Which half of a skin it draws. The key must carry it: `|ss` or `|sd`. See `SkinHalf`. */
+/** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
 skinPass = 'whole') {
     return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass), true);
 }
@@ -563,7 +564,8 @@ doubleSided = false, alphaToCoverage = false, skinEight = false,
 /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
 cloth = false, model = null, skinPass = 'whole') {
     const offset = depthOffsetForLayer(depthLayer);
-    const diffuseAlone = skinPass === 'diffuse';
+    /* The diffuse and colour halves are the same surface again, into the blur's targets. */
+    const diffuseAlone = skinPass === 'diffuse' || skinPass === 'albedo';
     return {
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
@@ -579,7 +581,7 @@ cloth = false, model = null, skinPass = 'whole') {
             }),
             entryPoint: 'main',
             buffers: vertexBufferLayouts(present, instanced),
-            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced), skinEight, cloth),
+            constants: vertexConstants(flatVertexBindings(skinned, morphed, instanced), skinEight, cloth, model === 'lightmap'),
         },
         fragment: {
             module: shaderModule(device, {

package/dist/render/backend/webgpu/particlePass.d.ts

@@ -1,6 +1,7 @@
 import { type ParticleMaterial } from '../../particleMaterial.ts';
 import type { ParticleInstances } from '../../particlePool.ts';
-import type { ParticleBlend, ParticleFacing } from '../../particleBatch.ts';
+import { type ParticleBlend, type ParticleFacing } from '../../particleBatch.ts';
+import { type ParticleSort } from '../../particleSort.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { UniformFields } from './scatterPass.ts';
 /**
@@ -33,8 +34,22 @@ export interface GpuParticles {
     readonly coreGain: number;
     /** Whether the mote fragment stage mixes toward the medium. Ignored by the other materials. */
     readonly fog: boolean;
+    /** A sprite's image view, or null for a procedural material. See `ParticleBatchOptions`. */
+    readonly texture: GPUTextureView | null;
+    readonly cells: readonly [number, number];
+    readonly blendCells: boolean;
+    readonly softDepth: number;
+    readonly cameraFade: number;
+    readonly cameraOffset: number;
+    /** Room to draw farthest first, where the batch asked. See `particleSort.ts`. */
+    readonly order: ParticleSort | null;
+    /** A sprite's bind group, which holds the frame's depth copy and is rebuilt when that moves. */
+    spriteGroup: GPUBindGroup | null;
+    spriteGroupDepth: GPUTextureView | null;
     /** Reused every frame; see `packInstances`. */
     readonly staging: Float32Array;
+    /** The sprite stream, two floats a particle, before it is woven into `staging`. */
+    readonly spriteStaging: Float32Array;
     /**
      * This batch's own uniform buffers, staging and bind group — never shared with another
      * batch of the same material. See the note on `createGpuParticles` for why: two pools of one
@@ -49,7 +64,8 @@ export interface GpuParticles {
     readonly fragFloats: Float32Array;
     readonly fragInts: Int32Array;
     readonly fields: UniformFields;
-    readonly bindGroup: GPUBindGroup;
+    /** The procedural materials' group; a sprite's holds the depth copy, so it is `spriteGroup`. */
+    readonly bindGroup: GPUBindGroup | null;
     /**
      * The encoder this batch was last drawn into, by the renderer's count, or -1.
      *
@@ -77,7 +93,7 @@ export interface GpuParticles {
  * written last. `layout` still comes from the caller and is shared per material: it is
  * structural, not data, so nothing about sharing it can go stale mid-frame.
  */
-export declare function createGpuParticles(device: GPUDevice, capacity: number, material: ParticleMaterial, blend: ParticleBlend, stretchSec: number, facing: ParticleFacing, erosion: number, coreGain: number, fog: boolean, layout: GPUBindGroupLayout, fragFields: UniformFields, fragSize: number): GpuParticles;
+export declare function createGpuParticles(device: GPUDevice, capacity: number, material: ParticleMaterial, blend: ParticleBlend, stretchSec: number, facing: ParticleFacing, erosion: number, coreGain: number, fog: boolean, layout: GPUBindGroupLayout, fragFields: UniformFields, fragSize: number, sprite?: SpriteOptions | null): GpuParticles;
 /**
  * Interleave the live prefix of eight streams into the batch's own staging array.
  *
@@ -85,7 +101,24 @@ export declare function createGpuParticles(device: GPUDevice, capacity: number,
  * into an array allocated with the batch — the frame loop may not allocate.
  */
 export declare function packInstances(batch: GpuParticles, data: ParticleInstances): number;
-export declare function createParticleBindGroupLayout(device: GPUDevice, fragSize: number): GPUBindGroupLayout;
+/** The floats `packInstances` writes per particle, for the caller's upload. */
+export declare const PARTICLE_INSTANCE_FLOATS = 16;
+/** What a `'sprite'` batch carries beyond a procedural one. See `ParticleBatchOptions`. */
+export interface SpriteOptions {
+    readonly texture: GPUTextureView | null;
+    readonly cells: readonly [number, number];
+    readonly blendCells: boolean;
+    readonly softDepth: number;
+    readonly cameraFade: number;
+    readonly cameraOffset: number;
+    readonly sort: boolean;
+}
+export declare function createParticleBindGroupLayout(device: GPUDevice, fragSize: number, sprite?: boolean): GPUBindGroupLayout;
+/**
+ * A sprite batch's bind group: its uniforms, its image, and the frame's depth copy — or any
+ * single-sample float texture standing in, where the batch asks for no soft edge.
+ */
+export declare function createSpriteBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, batch: GpuParticles, fragSize: number, depth: GPUTextureView, linear: GPUSampler, nearest: GPUSampler): GPUBindGroup;
 export declare function createParticleBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perDraw: GPUBuffer, perFrame: GPUBuffer, fragSize: number): GPUBindGroup;
 /**
  * The pipeline for one material and blend.

package/dist/render/backend/webgpu/particlePass.js

@@ -2,6 +2,8 @@ import { DEPTH_COMPARE } from '../../depthConvention.js';
 import { particleShaders } from '../../particleMaterial.js';
 import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.js';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.js';
+import { packSpriteStream } from '../../particleBatch.js';
+import { createParticleSort } from '../../particleSort.js';
 import { DEPTH_FORMAT } from './flatPass.js';
 import { shaderModule } from './shaderModules.js';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
@@ -22,7 +24,9 @@ export function particleFragBindings(material) {
         ? PARTICLE_BINDINGS.PARTICLE_SPARK_FRAG
         : material === 'mote'
             ? PARTICLE_BINDINGS.PARTICLE_MOTE_FRAG
-            : PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG;
+            : material === 'sprite'
+                ? PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG
+                : PARTICLE_BINDINGS.PARTICLE_SMOKE_FRAG;
     return { fields: stage.fields, size: stage.uniformSize };
 }
 const VISIBILITY_VERTEX = 0x1;
@@ -31,17 +35,17 @@ const USAGE_VERTEX = 0x0020 | 0x0008;
 const USAGE_INDEX = 0x0010 | 0x0008;
 const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
 /**
- * Ten attributes and eight slots, so the per-instance eight share one buffer.
+ * Eleven attributes and eight slots, so the per-instance nine share one buffer.
  *
- * **`maxVertexBuffers` is eight and this shader declares ten inputs**, so something has to
- * interleave. The per-instance streams are the ones that do: the engine holds them as eight
- * separate arrays and they are packed into one interleaved buffer per frame, which is a copy
- * the upload was already paying per stream rather than new work.
+ * **`maxVertexBuffers` is eight and this shader declares eleven inputs**, so something has to
+ * interleave. The per-instance streams are the ones that do: the engine holds them as separate
+ * arrays and they are packed into one interleaved buffer per frame, which is a copy the upload
+ * was already paying per stream rather than new work.
  *
  * Floats per instance, in the order they are packed: position 3, size 1, spin 1, colour 3,
- * alpha 1, age 1, seed 1, velocity 3.
+ * alpha 1, age 1, seed 1, velocity 3, and a sprite's frame and half-height 2.
  */
-const INSTANCE_FLOATS = 14;
+const INSTANCE_FLOATS = 16;
 const INSTANCE_ATTRIBUTES = [
     { shaderLocation: 2, offset: 0, format: 'float32x3' },
     { shaderLocation: 3, offset: 12, format: 'float32' },
@@ -51,6 +55,7 @@ const INSTANCE_ATTRIBUTES = [
     { shaderLocation: 7, offset: 36, format: 'float32' },
     { shaderLocation: 8, offset: 40, format: 'float32' },
     { shaderLocation: 9, offset: 44, format: 'float32x3' },
+    { shaderLocation: 10, offset: 56, format: 'float32x2' },
 ];
 export function particleVertexLayouts() {
     return [
@@ -87,7 +92,7 @@ export function particleVertexLayouts() {
  * written last. `layout` still comes from the caller and is shared per material: it is
  * structural, not data, so nothing about sharing it can go stale mid-frame.
  */
-export function createGpuParticles(device, capacity, material, blend, stretchSec, facing, erosion, coreGain, fog, layout, fragFields, fragSize) {
+export function createGpuParticles(device, capacity, material, blend, stretchSec, facing, erosion, coreGain, fog, layout, fragFields, fragSize, sprite = null) {
     /* The cross, built once: two blades of four corners, interleaved with the blade index. */
     const corners = new Float32Array(PARTICLE_VERTS * 3);
     const CORNERS = [
@@ -158,7 +163,17 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
         erosion,
         coreGain,
         fog,
+        texture: sprite?.texture ?? null,
+        cells: sprite?.cells ?? [1, 1],
+        blendCells: sprite?.blendCells ?? false,
+        softDepth: sprite?.softDepth ?? 0,
+        cameraFade: sprite?.cameraFade ?? 0,
+        cameraOffset: sprite?.cameraOffset ?? 0,
+        order: sprite?.sort === true ? createParticleSort(capacity) : null,
+        spriteGroup: null,
+        spriteGroupDepth: null,
         staging: new Float32Array(capacity * INSTANCE_FLOATS),
+        spriteStaging: new Float32Array(capacity * 2),
         vertUniforms,
         fragUniforms,
         vertStaging,
@@ -167,7 +182,9 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
         fragFloats: new Float32Array(fragStaging),
         fragInts: new Int32Array(fragStaging),
         fields: fragFields,
-        bindGroup: createParticleBindGroup(device, layout, vertUniforms, fragUniforms, fragSize),
+        bindGroup: material === 'sprite'
+            ? null
+            : createParticleBindGroup(device, layout, vertUniforms, fragUniforms, fragSize),
         dispose() {
             cornerBuffer.destroy();
             instances.destroy();
@@ -186,6 +203,8 @@ export function createGpuParticles(device, capacity, material, blend, stretchSec
 export function packInstances(batch, data) {
     const n = Math.min(data.count, batch.capacity);
     const out = batch.staging;
+    /* The sprite's frame and half-height, two floats a particle, woven in below. */
+    packSpriteStream(data, n, batch.spriteStaging);
     for (let i = 0; i < n; i++) {
         const o = i * INSTANCE_FLOATS;
         const p = i * 3;
@@ -203,12 +222,17 @@ export function packInstances(batch, data) {
         out[o + 11] = data.velocities[p];
         out[o + 12] = data.velocities[p + 1];
         out[o + 13] = data.velocities[p + 2];
+        out[o + 14] = batch.spriteStaging[i * 2];
+        out[o + 15] = batch.spriteStaging[i * 2 + 1];
     }
     return n;
 }
-export function createParticleBindGroupLayout(device, fragSize) {
+/** The floats `packInstances` writes per particle, for the caller's upload. */
+export const PARTICLE_INSTANCE_FLOATS = INSTANCE_FLOATS;
+export function createParticleBindGroupLayout(device, fragSize, sprite = false) {
+    const textures = PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG.textures;
     return device.createBindGroupLayout({
-        label: 'particle.layout',
+        label: sprite ? 'particle.layout:sprite' : 'particle.layout',
         entries: [
             {
                 binding: VERT_BINDING,
@@ -220,6 +244,50 @@ export function createParticleBindGroupLayout(device, fragSize) {
                 visibility: VISIBILITY_FRAGMENT,
                 buffer: { type: 'uniform', minBindingSize: fragSize },
             },
+            /* The image, filtered, and the frame's depth copy, read texel for texel. */
+            ...(sprite
+                ? [
+                    {
+                        binding: textures.uSprite.texture,
+                        visibility: VISIBILITY_FRAGMENT,
+                        texture: { sampleType: 'float', viewDimension: '2d-array' },
+                    },
+                    {
+                        binding: textures.uSprite.sampler,
+                        visibility: VISIBILITY_FRAGMENT,
+                        sampler: { type: 'filtering' },
+                    },
+                    {
+                        binding: textures.uDepth.texture,
+                        visibility: VISIBILITY_FRAGMENT,
+                        texture: { sampleType: 'unfilterable-float' },
+                    },
+                    {
+                        binding: textures.uDepth.sampler,
+                        visibility: VISIBILITY_FRAGMENT,
+                        sampler: { type: 'non-filtering' },
+                    },
+                ]
+                : []),
+        ],
+    });
+}
+/**
+ * A sprite batch's bind group: its uniforms, its image, and the frame's depth copy — or any
+ * single-sample float texture standing in, where the batch asks for no soft edge.
+ */
+export function createSpriteBindGroup(device, layout, batch, fragSize, depth, linear, nearest) {
+    const textures = PARTICLE_BINDINGS.PARTICLE_SPRITE_FRAG.textures;
+    return device.createBindGroup({
+        label: 'particle.bindGroup:sprite',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: batch.vertUniforms, size: PARTICLE_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: batch.fragUniforms, size: fragSize } },
+            { binding: textures.uSprite.texture, resource: batch.texture },
+            { binding: textures.uSprite.sampler, resource: linear },
+            { binding: textures.uDepth.texture, resource: depth },
+            { binding: textures.uDepth.sampler, resource: nearest },
         ],
     });
 }

package/dist/render/backend/webgpu/postPass.d.ts

@@ -180,7 +180,12 @@ export declare const PREMULTIPLIED_OVER_BLEND: GPUBlendState;
  * the reflection's own and its alpha is the coverage this resolve reads.
  */
 export declare const REFLECTION_OVER_BLEND: GPUBlendState;
-export declare const ADDITIVE_BLEND: GPUBlendState;
+/**
+ * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
+ * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
+ * own levels, never the scene. See `BloomResponse`.
+ */
+export declare const TINTED_ADD_BLEND: GPUBlendState;
 /** A fullscreen pass over one or more inputs, writing to one colour target. */
 export declare function postPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, key: string, fragment: string, format: GPUTextureFormat, blend?: GPUBlendState): GPURenderPipeline;
 /**

package/dist/render/backend/webgpu/postPass.js

@@ -252,8 +252,13 @@ export const REFLECTION_OVER_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
     alpha: SCENE_ALPHA_KEEPS,
 };
-export const ADDITIVE_BLEND = {
-    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+/**
+ * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
+ * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
+ * own levels, never the scene. See `BloomResponse`.
+ */
+export const TINTED_ADD_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'constant', operation: 'add' },
     alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
 };
 /** A fullscreen pass over one or more inputs, writing to one colour target. */