@driftengine/core 4.8.4 → 4.8.6

package/src/render/backend/webgl2/skinScatter.ts

@@ -5,14 +5,19 @@
  *
  * **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.ts';
+import {
+  SKIN_BLUR_ALBEDO_UNIT,
+  SKIN_BLUR_DEPTH_UNIT,
+  SKIN_BLUR_TEXTURE_UNIT,
+} from '../../lightBudget.ts';
 import { blendKeeping } from '../../sceneCoverage.ts';
 import type { SceneTarget } from '../../sceneTarget.ts';
 import { compileProgram, uniformLocations } from '../../shader.ts';
@@ -33,9 +38,13 @@ export class GlSkinScatter {
   private readonly depthToViewZ = new Float32Array(4);
   private diffuse: WebGLTexture | null = null;
   private across: WebGLTexture | null = null;
+  private albedo: WebGLTexture | null = null;
   private multisampled: WebGLRenderbuffer | null = null;
+  private albedoMultisampled: WebGLRenderbuffer | null = null;
   private drawFramebuffer: WebGLFramebuffer | null = null;
   private resolveFramebuffer: WebGLFramebuffer | null = null;
+  private albedoFramebuffer: WebGLFramebuffer | null = null;
+  private albedoResolveFramebuffer: WebGLFramebuffer | null = null;
   private acrossFramebuffer: WebGLFramebuffer | null = null;
   private width = 0;
   private height = 0;
@@ -44,6 +53,7 @@ export class GlSkinScatter {
   /** Refused once and for good: a driver that will not render to half floats. */
   private unavailable = false;
   private cleared = false;
+  private albedoCleared = false;
   private drawn = false;
 
   constructor(gl: WebGL2RenderingContext) {
@@ -115,6 +125,17 @@ export class GlSkinScatter {
     this.drawn = true;
   }
 
+  /** Bind the target for the same skin's colour half, cleared the first time a frame does. */
+  beginAlbedo(): void {
+    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
@@ -129,20 +150,8 @@ export class GlSkinScatter {
   ): void {
     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);
@@ -153,6 +162,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] as number) ?? 0;
     this.depthToViewZ[1] = (inverse[14] as number) ?? 0;
@@ -175,6 +187,8 @@ 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();
@@ -182,6 +196,7 @@ export class GlSkinScatter {
     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);
@@ -199,9 +214,29 @@ export class GlSkinScatter {
   /** Spent at the frame's start: what was drawn into the target was last frame's. */
   reset(): void {
     this.cleared = false;
+    this.albedoCleared = false;
     this.drawn = false;
   }
 
+  /** A multisampled target into its single-sampled texture. */
+  private resolve(from: WebGLFramebuffer | null, to: WebGLFramebuffer | null): void {
+    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(): void {
     const { gl } = this;
     this.release();
@@ -226,19 +261,59 @@ export class GlSkinScatter {
     this.sharedDepth = depthRenderbuffer ?? depthTexture;
     this.diffuse = this.halfFloatTexture(width, height);
     this.across = this.halfFloatTexture(width, height);
+    this.albedo = 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,
+    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 (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.
+   */
+  private drawTarget(
+    texture: WebGLTexture | null,
+    multisampled: boolean,
+    depthTexture: WebGLTexture | null,
+    depthRenderbuffer: WebGLRenderbuffer | null,
+  ): {
+    framebuffer: WebGLFramebuffer | null;
+    multisampled: WebGLRenderbuffer | null;
+    resolve: WebGLFramebuffer | null;
+    ready: boolean;
+  } {
+    const { gl } = this;
+    const framebuffer = gl.createFramebuffer();
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    let samples: WebGLRenderbuffer | null = null;
+    if (multisampled && depthRenderbuffer !== null) {
+      samples = gl.createRenderbuffer();
+      gl.bindRenderbuffer(gl.RENDERBUFFER, samples);
+      gl.renderbufferStorageMultisample(
         gl.RENDERBUFFER,
-        this.multisampled,
+        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,
@@ -246,25 +321,17 @@ export class GlSkinScatter {
         depthRenderbuffer,
       );
     } else {
-      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.diffuse, 0);
+      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 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);
+    const ready = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+    let resolve: WebGLFramebuffer | null = null;
+    if (samples !== null) {
+      resolve = gl.createFramebuffer();
+      gl.bindFramebuffer(gl.FRAMEBUFFER, resolve);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
     }
-    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) return true;
-    this.release();
-    this.refuse();
-    return false;
+    return { framebuffer, multisampled: samples, resolve, ready };
   }
 
   private refuse(): void {
@@ -294,16 +361,26 @@ export class GlSkinScatter {
     const { gl } = this;
     if (this.drawFramebuffer !== null) 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/src/render/backend/webgpu/buffers.ts

@@ -766,7 +766,8 @@ const INSTANCE_ATTRIBUTES: GPUVertexAttribute[] = [
   { 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. */

package/src/render/backend/webgpu/clusterBinner.ts

@@ -5,6 +5,7 @@ import {
   TABLE_HEIGHT,
   TABLE_WIDTH,
   type ClusterLightSet,
+  clusteredLightTotal,
   writeLightRecord,
 } from '../../clusteredLights.ts';
 import { MAX_POINT_LIGHTS } from '../../lightBudget.ts';
@@ -167,7 +168,8 @@ export class ClusterBinner {
     if (frame === null || device === null || pipeline === null || group === null) 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

package/src/render/backend/webgpu/flatPass.ts

@@ -1,6 +1,6 @@
 import { SURFACE_MODEL_SWITCH } from '../../surfaceModel.ts';
 import type { SurfaceModelKind } from '../../surfaceModel.ts';
-import type { SkinHalf } from '../../shaders/flat/models.ts';
+import { SKIN_HALF_SWITCH, type SkinHalf } from '../../shaders/flat/models.ts';
 import { DEPTH_COMPARE, DEPTH_FORMAT, depthOffsetForLayer } from '../../depthConvention.ts';
 import {
   FLAT_BINDINGS,
@@ -153,8 +153,8 @@ export function flatVertexBindings(
 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.
  */
@@ -162,11 +162,14 @@ export function vertexConstants(
   bindings: StageBindings,
   skinEight: boolean,
   cloth = false,
+  /** Whether an instanced stage reads its tint lane as a lightmap region. See `lightmap.ts`. */
+  lightmapRegions = false,
 ): Record<string, number> {
   const constants: Record<string, number> = {};
   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`);
   }
   return constants;
@@ -263,13 +266,9 @@ function flatFragmentConstants(
       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)) {
@@ -608,7 +607,7 @@ export function flatPipeline(
   cloth = false,
   /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
   model: SurfaceModelKind | null = 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 = 'whole',
 ): GPURenderPipeline {
   return cache.get(
@@ -768,7 +767,8 @@ function flatDescriptor(
   skinPass: SkinHalf = 'whole',
 ): GPURenderPipelineDescriptor {
   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] }),
@@ -784,7 +784,12 @@ function flatDescriptor(
       }),
       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/src/render/backend/webgpu/particlePass.ts

@@ -3,7 +3,8 @@ import { particleShaders, type ParticleMaterial } from '../../particleMaterial.t
 import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.ts';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.ts';
 import type { ParticleInstances } from '../../particlePool.ts';
-import type { ParticleBlend, ParticleFacing } from '../../particleBatch.ts';
+import { packSpriteStream, type ParticleBlend, type ParticleFacing } from '../../particleBatch.ts';
+import { createParticleSort, type ParticleSort } from '../../particleSort.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 import type { UniformFields } from './scatterPass.ts';
@@ -34,7 +35,9 @@ export function particleFragBindings(material: ParticleMaterial): {
       ? 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 as UniformFields, size: stage.uniformSize };
 }
 
@@ -45,17 +48,17 @@ 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: GPUVertexAttribute[] = [
   { shaderLocation: 2, offset: 0, format: 'float32x3' },
@@ -66,6 +69,7 @@ const INSTANCE_ATTRIBUTES: GPUVertexAttribute[] = [
   { 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(): GPUVertexBufferLayout[] {
@@ -102,8 +106,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
@@ -118,7 +136,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.
    *
@@ -160,6 +179,7 @@ export function createGpuParticles(
   layout: GPUBindGroupLayout,
   fragFields: UniformFields,
   fragSize: number,
+  sprite: SpriteOptions | null = null,
 ): GpuParticles {
   /* The cross, built once: two blades of four corners, interleaved with the blade index. */
   const corners = new Float32Array(PARTICLE_VERTS * 3);
@@ -236,7 +256,17 @@ export function createGpuParticles(
     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,
@@ -245,7 +275,10 @@ export function createGpuParticles(
     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(): void {
       cornerBuffer.destroy();
       instances.destroy();
@@ -265,6 +298,8 @@ export function createGpuParticles(
 export function packInstances(batch: GpuParticles, data: ParticleInstances): number {
   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;
@@ -282,16 +317,34 @@ export function packInstances(batch: GpuParticles, data: ParticleInstances): num
     out[o + 11] = data.velocities[p] as number;
     out[o + 12] = data.velocities[p + 1] as number;
     out[o + 13] = data.velocities[p + 2] as number;
+    out[o + 14] = batch.spriteStaging[i * 2] as number;
+    out[o + 15] = batch.spriteStaging[i * 2 + 1] as number;
   }
   return n;
 }
 
+/** The floats `packInstances` writes per particle, for the caller's upload. */
+export const PARTICLE_INSTANCE_FLOATS = INSTANCE_FLOATS;
+
+/** 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 function createParticleBindGroupLayout(
   device: GPUDevice,
   fragSize: number,
+  sprite = false,
 ): GPUBindGroupLayout {
+  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,
@@ -303,6 +356,59 @@ export function createParticleBindGroupLayout(
         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' as const, viewDimension: '2d-array' as const },
+            },
+            {
+              binding: textures.uSprite.sampler,
+              visibility: VISIBILITY_FRAGMENT,
+              sampler: { type: 'filtering' as const },
+            },
+            {
+              binding: textures.uDepth.texture,
+              visibility: VISIBILITY_FRAGMENT,
+              texture: { sampleType: 'unfilterable-float' as const },
+            },
+            {
+              binding: textures.uDepth.sampler,
+              visibility: VISIBILITY_FRAGMENT,
+              sampler: { type: 'non-filtering' as const },
+            },
+          ]
+        : []),
+    ],
+  });
+}
+
+/**
+ * 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: GPUDevice,
+  layout: GPUBindGroupLayout,
+  batch: GpuParticles,
+  fragSize: number,
+  depth: GPUTextureView,
+  linear: GPUSampler,
+  nearest: GPUSampler,
+): GPUBindGroup {
+  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 as GPUTextureView },
+      { binding: textures.uSprite.sampler, resource: linear },
+      { binding: textures.uDepth.texture, resource: depth },
+      { binding: textures.uDepth.sampler, resource: nearest },
     ],
   });
 }

package/src/render/backend/webgpu/postPass.ts

@@ -331,8 +331,13 @@ export const REFLECTION_OVER_BLEND: GPUBlendState = {
   alpha: SCENE_ALPHA_KEEPS,
 };
 
-export const ADDITIVE_BLEND: GPUBlendState = {
-  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: GPUBlendState = {
+  color: { srcFactor: 'one', dstFactor: 'constant', operation: 'add' },
   alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
 };