@driftengine/core 4.8.4 → 4.8.6

package/src/render/backend/webgpu/shaders/clusterBin.wgsl.ts

@@ -102,6 +102,41 @@ fn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {
   return dot(d, d);
 }
 
+/**
+ * Whether a spot's cone misses this froxel: \`coneBoxGap\` in \`clusteredLights.ts\`, the same
+ * arithmetic in the same order — the froxel's bounding sphere against the infinite cone, its apex
+ * included, which can keep a light the shader would not draw and never drop one it would. A light
+ * with no cone carries a cosine of -2 and never reaches the test.
+ */
+fn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {
+  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);
+  if (cosOuter <= -1.0) {
+    return false;
+  }
+  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);
+  let a = (params.view * vec4<f32>(world, 0.0)).xyz;
+  let axis = vec3<f32>(a.x, a.y, -a.z);
+  let len = length(axis);
+  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */
+  if (len <= 1e-6 || cosOuter / len <= -1.0) {
+    return false;
+  }
+  let cosA = cosOuter / len;
+  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));
+  let unit = axis / len;
+  let extent = (hi - lo) * 0.5;
+  let toCentre = (lo + hi) * 0.5 - apex;
+  let along = dot(toCentre, unit);
+  let lengthSq = dot(toCentre, toCentre);
+  let across = sqrt(max(lengthSq - along * along, 0.0));
+  let reach = sqrt(lengthSq);
+  var distance = cosA * across - along * sinA;
+  if (along < -sinA * reach) {
+    distance = reach;
+  }
+  return distance - length(extent) > 0.0;
+}
+
 @compute @workgroup_size(64)
 fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let id = gid.x;
@@ -161,7 +196,9 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 
   /* Increasing light index, which is what makes the list sorted without a sort. */
   for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {
-    let radius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
+    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */
+    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
+    let radius = abs(signedRadius);
     let v = viewOf(light);
     if (v.z + radius <= 0.0) {
       continue;
@@ -169,6 +206,9 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
     if (distanceSqToBounds(v, lo, hi) > radius * radius) {
       continue;
     }
+    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {
+      continue;
+    }
 
     if (count < MAX_LIGHTS_PER_CLUSTER) {
       indices[count] = light;

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

@@ -1,27 +1,5 @@
 import { SkinPaletteTexture } from './skinPaletteTexture.ts';
 
-/**
- * How many palettes one frame may set before the ring is full.
- *
- * The arithmetic rather than a round number: a character's palette is uploaded once per *pass*
- * that draws it, and a full profile draws the same character five times — the main pass, a planar
- * reflection, and the static, peel and dynamic shadow layers. So this is twenty-five characters at
- * once, which is a crowd rather than a cast.
- *
- * **What it costs is nothing until it is used.** A slot allocates its texture on the first frame
- * that reaches it and keeps it, so a scene with two characters holds two: a 24-joint rig is 96
- * texels of `rgba32float`, which is 1.5 KB, and a 96-joint humanoid is 6 KB.
- *
- * **What would make it wrong** is a genuine crowd — a stadium, a swarm of rigged birds — and the
- * fix is then the one `skinPalette.ts` names: one texture holding every palette with a per-draw
- * row offset, which spends a uniform and a shader change to stop spending textures.
- *
- * **A reconstructing frame spends one more per skinned mover**: last frame's pose is uploaded into
- * a slot of its own for the motion pass. So the same budget is about twelve such characters with a
- * reflection and three shadow layers each.
- */
-export const MAX_SKIN_PALETTES = 128;
-
 /**
  * Every joint palette a frame sets, each in its own texture, reused frame after frame.
  *
@@ -42,20 +20,53 @@ export const MAX_SKIN_PALETTES = 128;
  * draws separates them there by construction. The decision — a palette belongs to a draw — is one;
  * only what it takes to honour it differs, which is what `skinPalette.ts` says a binder is for.
  *
- * **A slot is written at most once per frame**, since every `setSkinPalette` takes a fresh one.
- * That is what makes the reallocation inside `SkinPaletteTexture` safe: a joint count can only
- * change a slot's texture between frames, never while a recorded draw is still pointing at it.
+ * **A palette set again with the same numbers is the slot it already has.** A rig is drawn in
+ * every pass of a frame — the main pass, a reflection, three shadow layers — and each one used to
+ * upload the same matrices into a slot of its own, so a crowd ran out five times sooner than it
+ * had characters. The ring now remembers the slot each array last went into and compares what it
+ * holds, so a rig posed once a frame spends one slot however many passes draw it. Identity alone
+ * would be wrong: a caller may pose every rig into one scratch array, and that array then holds a
+ * different rig at every set — the comparison is what tells the two apart.
+ *
+ * **It was capped at 128 until 4.8.6, and the cap declined draws.** A stage of three dozen idling
+ * extras beside two fighters filled it in one frame and every skinned draw past it was refused, so
+ * the consumer stood its crowd in the bind pose. The ring now holds as many palettes as a frame
+ * holds draws (`RenderQuality.drawsPerFrame`), since no frame can bind more palettes than it draws;
+ * a slot still allocates its texture only the first time a frame reaches it, so a scene with two
+ * characters holds two. **What it costs** is a texture and a cached bind group a slot, 1.5 KB for a
+ * 24-joint rig and 6 KB for a 96-joint humanoid. **What would make it wrong** is a crowd of
+ * thousands, where a texture a palette is the expensive half; the fix is then one texture holding
+ * every palette with a row offset per draw, which spends a per-draw uniform and a vertex-stage
+ * change to stop spending textures.
+ *
+ * **A slot is written at most once per frame**, since a palette that differs from what a slot
+ * holds always takes a fresh one. That is what makes the reallocation inside `SkinPaletteTexture`
+ * safe: a joint count can only change a slot's texture between frames, never while a recorded draw
+ * is still pointing at it.
  */
 export class SkinPaletteRing {
   private readonly slots: SkinPaletteTexture[] = [];
+  /** What each slot was last written with, for the comparison that lets a pass reuse it. */
+  private readonly held: Float32Array[] = [];
+  /** The slot each palette array last went into, by identity. Weak, so a caller's array can go. */
+  private readonly lastSlot = new WeakMap<Float32Array, number>();
   private used = 0;
+  private uploads = 0;
   private warnedFull = false;
 
+  /** `capacity` is how many palettes one frame may hold: one per draw at most. */
+  constructor(private readonly capacity: number) {}
+
   /** How many slots this frame has taken. */
   get count(): number {
     return this.used;
   }
 
+  /** How many palettes have been written to the device since the ring was made. */
+  get uploaded(): number {
+    return this.uploads;
+  }
+
   /**
    * Start a frame: every slot is free again.
    *
@@ -78,20 +89,23 @@ export class SkinPaletteRing {
   }
 
   /**
-   * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+   * The slot this frame holds for these numbers, uploading them into a fresh one where none does,
+   * or null when the ring is full.
    *
-   * **Null rather than reusing a slot**, because reusing one is the defect this class is named
-   * after: the caller's character would silently take another character's pose. A caller that runs
-   * out declines the draw and says so once.
+   * **Null rather than reusing a slot that holds something else**, because that is the defect this
+   * class is named after: the caller's character would silently take another character's pose. A
+   * caller that runs out declines the draw and says so once.
    */
   take(device: GPUDevice, palette: Float32Array): number | null {
-    if (this.used >= MAX_SKIN_PALETTES) {
+    const known = this.lastSlot.get(palette);
+    if (known !== undefined && known < this.used && this.holds(known, palette)) return known;
+    if (this.used >= this.capacity) {
       if (!this.warnedFull) {
         this.warnedFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_SKIN_PALETTES} skin palettes in one frame; the rest of the ` +
-            'skinned draws are declined this frame rather than drawn in another rig’s pose. ' +
-            'See MAX_SKIN_PALETTES.',
+          `WebGPU: more than ${this.capacity} distinct skin palettes in one frame, which is ` +
+            'RenderQuality.drawsPerFrame; the rest of the skinned draws are declined this frame ' +
+            'rather than drawn in another rig’s pose.',
         );
       }
       return null;
@@ -103,6 +117,15 @@ export class SkinPaletteRing {
       this.slots[at] = slot;
     }
     slot.update(device, palette);
+    this.uploads += 1;
+    let copy = this.held[at];
+    if (copy === undefined || copy.length !== palette.length) {
+      /* Once per slot and joint count, the way the slot's own texture is: never per frame. */
+      copy = new Float32Array(palette.length);
+      this.held[at] = copy;
+    }
+    copy.set(palette);
+    this.lastSlot.set(palette, at);
     return at;
   }
 
@@ -114,6 +137,15 @@ export class SkinPaletteRing {
   dispose(): void {
     for (const slot of this.slots) slot.dispose();
     this.slots.length = 0;
+    this.held.length = 0;
     this.used = 0;
   }
+
+  /** Whether a slot was last written with exactly these numbers. */
+  private holds(slot: number, palette: Float32Array): boolean {
+    const copy = this.held[slot];
+    if (copy === undefined || copy.length !== palette.length) return false;
+    for (let i = 0; i < copy.length; i++) if (copy[i] !== palette[i]) return false;
+    return true;
+  }
 }

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

@@ -3,19 +3,21 @@
  * that spread them. `skinBlur.ts` is what the blur computes and why; this is where it runs.
  *
  * **What the renderer hands it.** Each skin draw, recorded into the frame with its diffuse taken
- * out, is recorded a second time here with the diffuse alone. When the frame first draws something
- * blended — or ends, if nothing is — the renderer ends its pass and calls `drawDiffuse`, which
- * replays them into a half-float target against the frame's own depth; resolves the depth; and
- * calls `spread`, which blurs across into a second target and then down, adding into the frame.
+ * out, is recorded twice more here: with the diffuse's light alone, and with its colour alone.
+ * When the frame first draws something blended — or ends, if nothing is — the renderer ends its
+ * pass and calls `drawDiffuse`, which replays them into two half-float targets against the frame's
+ * own depth; resolves the depth; and calls `spread`, which blurs the light across into a third
+ * target and then down, multiplied by the colour, adding into the frame.
  *
  * **The draws are commands, not calls**, for the reason `LatePass` keeps its own pool: the frame
  * graph's is spent at every flush, and these are replayed after the flush that ends the frame's
  * pass. Each holds the per-draw ring slot its frame half used, and those stay valid until the
  * encoder is replaced, which is after this has run.
  *
- * **What it costs**: every skin draw twice; two half-float targets the size of the frame, and a
- * third multisampled one under multisampling; a depth resolve; and two full-screen passes that
- * leave at once wherever no skin was drawn.
+ * **What it costs**: every skin draw three times — the frame's half, the light alone, and the
+ * colour alone, which the spread light is multiplied by; three half-float targets the size of the
+ * frame, and two multisampled ones under multisampling; a depth resolve; and two full-screen passes
+ * that leave at once wherever no skin was drawn.
  */
 import { SKIN_PROFILES } from '../../skinBlur.ts';
 import { SKINBLUR_BINDINGS, SKIN_BLUR_FRAG_WGSL } from '../../shaders/generated/skinBlur.wgsl.ts';
@@ -42,14 +44,20 @@ export class SkinScatterPass {
   private readonly linear: GPUSampler;
   private readonly nearest: GPUSampler;
   private readonly commands: CommandPool = createCommandPool(16);
+  /** The same draws again, through the pipelines that write the skin's colour alone. */
+  private readonly albedoCommands: CommandPool = createCommandPool(16);
   /** Each profile's scatter distance per channel, in metres: four floats a profile. */
   private readonly profiles = new Float32Array(SKIN_PROFILES * 4);
   private diffuse: GPUTexture | null = null;
   private diffuseMsaa: GPUTexture | null = null;
   private across: GPUTexture | null = null;
+  private albedo: GPUTexture | null = null;
+  private albedoMsaa: GPUTexture | null = null;
   private diffuseView: GPUTextureView | null = null;
   private diffuseMsaaView: GPUTextureView | null = null;
   private acrossView: GPUTextureView | null = null;
+  private albedoView: GPUTextureView | null = null;
+  private albedoMsaaView: GPUTextureView | null = null;
   private groupAcross: GPUBindGroup | null = null;
   private groupDown: GPUBindGroup | null = null;
   private groupsDepth: GPUTextureView | null = null;
@@ -59,6 +67,7 @@ export class SkinScatterPass {
     this.layout = createPostStageLayout(device, BINDINGS.uniforms, BINDINGS.uniformSize, [
       { binding: BINDINGS.textures.uSkin },
       { binding: BINDINGS.textures.uDepth, filterable: false },
+      { binding: BINDINGS.textures.uAlbedo },
     ]);
     this.uniforms = device.createBuffer({
       label: 'skin.blurUniforms',
@@ -89,6 +98,11 @@ export class SkinScatterPass {
     return this.commands.commands[takeCommand(this.commands)] as DrawCommand;
   }
 
+  /** A command for the same draw's colour half, filled by the caller. */
+  takeAlbedo(): DrawCommand {
+    return this.albedoCommands.commands[takeCommand(this.albedoCommands)] as DrawCommand;
+  }
+
   /** What one profile scatters, per channel, in metres: the last material to name it says. */
   setProfile(index: number, r: number, g: number, b: number): void {
     const at = Math.min(Math.max(Math.round(index), 0), SKIN_PROFILES - 1) * 4;
@@ -119,17 +133,21 @@ export class SkinScatterPass {
       });
     this.diffuse = make('skin.diffuse', 1);
     this.across = make('skin.across', 1);
+    this.albedo = make('skin.albedo', 1);
     this.diffuseMsaa = samples > 1 ? make('skin.diffuseMsaa', samples) : null;
+    this.albedoMsaa = samples > 1 ? make('skin.albedoMsaa', samples) : null;
     this.diffuseView = this.diffuse.createView();
     this.acrossView = this.across.createView();
+    this.albedoView = this.albedo.createView();
     this.diffuseMsaaView = this.diffuseMsaa?.createView() ?? null;
+    this.albedoMsaaView = this.albedoMsaa?.createView() ?? null;
     this.groupAcross = null;
     this.groupDown = null;
   }
 
   /**
-   * Every kept draw's diffuse into the target, against the frame's own depth, which it reads and
-   * does not write. Called with no pass open on `encoder`.
+   * Every kept draw's diffuse into the target, and its colour into the other, against the frame's
+   * own depth, which they read and do not write. Called with no pass open on `encoder`.
    */
   drawDiffuse(
     encoder: GPUCommandEncoder,
@@ -157,6 +175,26 @@ export class SkinScatterPass {
       issue(pass, this.commands.commands[i] as DrawCommand);
     }
     pass.end();
+
+    const colour = this.albedoView;
+    if (colour === null) return;
+    const albedoPass = encoder.beginRenderPass({
+      label: 'skin.albedo',
+      colorAttachments: [
+        {
+          view: this.albedoMsaaView ?? colour,
+          resolveTarget: this.albedoMsaaView === null ? undefined : colour,
+          clearValue: [0, 0, 0, 0],
+          loadOp: 'clear',
+          storeOp: this.albedoMsaaView === null ? 'store' : 'discard',
+        },
+      ],
+      depthStencilAttachment: { view: depth, depthLoadOp: 'load', depthStoreOp: 'store' },
+    });
+    for (let i = 0; i < this.albedoCommands.taken; i += 1) {
+      issue(albedoPass, this.albedoCommands.commands[i] as DrawCommand);
+    }
+    albedoPass.end();
   }
 
   /**
@@ -177,6 +215,7 @@ export class SkinScatterPass {
   ): void {
     const diffuse = this.diffuse;
     if (diffuse === null || this.diffuseView === null || this.acrossView === null) return;
+    if (this.albedoView === null) return;
     if (this.groupAcross === null || this.groupDown === null || this.groupsDepth !== depth) {
       this.groupAcross = this.group('skin.blurAcross', this.diffuseView, depth);
       this.groupDown = this.group('skin.blurDown', this.acrossView, depth);
@@ -244,6 +283,7 @@ export class SkinScatterPass {
   /** Spent at the frame's start: the kept draws were this frame's. */
   reset(): void {
     resetPool(this.commands);
+    resetPool(this.albedoCommands);
   }
 
   dispose(): void {
@@ -264,6 +304,8 @@ export class SkinScatterPass {
         { binding: BINDINGS.textures.uSkin.sampler, resource: this.linear },
         { binding: BINDINGS.textures.uDepth.texture, resource: depth },
         { binding: BINDINGS.textures.uDepth.sampler, resource: this.nearest },
+        { binding: BINDINGS.textures.uAlbedo.texture, resource: this.albedoView ?? skin },
+        { binding: BINDINGS.textures.uAlbedo.sampler, resource: this.nearest },
       ],
     });
   }
@@ -291,6 +333,8 @@ export class SkinScatterPass {
          too wherever a pixel is square. */
       f[base + fields.uFocal.offset / 4] = ((projection[5] as number) * height) / 2;
       f.set(this.profiles, base + fields.uProfiles.offset / 4);
+      /* The colour is applied once, on the axis that adds into the frame. */
+      f[base + fields.uApplyAlbedo.offset / 4] = axis;
     }
     this.device.queue.writeBuffer(this.uniforms, 0, f);
   }
@@ -299,11 +343,17 @@ export class SkinScatterPass {
     this.diffuse?.destroy();
     this.diffuseMsaa?.destroy();
     this.across?.destroy();
+    this.albedo?.destroy();
+    this.albedoMsaa?.destroy();
     this.diffuse = null;
     this.diffuseMsaa = null;
     this.across = null;
+    this.albedo = null;
+    this.albedoMsaa = null;
     this.diffuseView = null;
     this.diffuseMsaaView = null;
     this.acrossView = null;
+    this.albedoView = null;
+    this.albedoMsaaView = null;
   }
 }

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

@@ -1,6 +1,8 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.ts';
 import { toHalfFloats } from '../../halfFloat.ts';
+import { isLightmapTexels } from '../../lightmap.ts';
+import type { LightmapTexels } from '../../lightmap.ts';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.ts';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.ts';
 import type {
@@ -193,17 +195,36 @@ export class GpuSurfaceTexture {
   constructor(
     private readonly device: GPUDevice,
     private readonly pipelines: PipelineCache,
-    source: SurfaceSource | readonly SurfaceSource[],
+    source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels,
     options: SurfaceTextureOptions = {},
     compressed: readonly CompressedTextureFormat[] = [],
   ) {
-    const listed = (Array.isArray(source) ? source : [source]) as readonly SurfaceSource[];
+    /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+    const baked = isLightmapTexels(source) ? source : null;
+    const listed = (
+      baked !== null ? [] : Array.isArray(source) ? source : [source]
+    ) as readonly SurfaceSource[];
     const blocks = compressedLayers(listed);
     const srgb = (options.colorSpace ?? 'linear') === 'srgb';
     /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
        place it is correct — `surfaceTexture.ts` makes the argument in full. */
-    this.format = srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-    if (blocks !== null) {
+    this.format = baked !== null ? 'rgba16float' : srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
+    if (baked !== null) {
+      /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
+      this.layers = baked.layers;
+      this.blockFormat = null;
+      this.mipmapped = false;
+      this.width = baked.width;
+      this.height = baked.height;
+      this.levels = 1;
+      this.texture = this.allocate();
+      device.queue.writeTexture(
+        { texture: this.texture },
+        baked.texels,
+        { bytesPerRow: baked.width * 8, rowsPerImage: baked.height },
+        { width: baked.width, height: baked.height, depthOrArrayLayers: baked.layers },
+      );
+    } else if (blocks !== null) {
       /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
          was asked for. See `compressedUpload.ts`. */
       const plan = planBlocks(blocks, srgb, compressed);
@@ -261,7 +282,7 @@ export class GpuSurfaceTexture {
           : 1,
     });
 
-    if (blocks === null) this.upload(listed as readonly TexImageSource[]);
+    if (blocks === null && baked === null) this.upload(listed as readonly TexImageSource[]);
 
     /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
        and read by `textureLoad` alone, so the filter never runs. */

package/src/render/bloomChain.ts

@@ -81,6 +81,75 @@ export function bloomProfileWarning(quality: {
   return null;
 }
 
+/**
+ * How a frame's bloom answers the light it is given, beside the strength and threshold `setBloom`
+ * already takes. Absent, or a field absent, is the response every frame had before 4.8.6.
+ *
+ * **Why it exists: one band over the colour less the threshold washes a stage built for another
+ * engine.** Unreal's standard bloom keeps `saturate((L − threshold) / 2)` of a colour rather than
+ * the colour less the threshold, and spreads it over six bands, each in a tint of its own. A
+ * stage authored against that — a threshold of 0.1 and tints summing below one — came out white
+ * here, because subtracting so low a threshold keeps nearly every light in the frame at full
+ * strength. These are the two things that differ, as numbers.
+ */
+export interface BloomResponse {
+  /**
+   * Scene units over which a colour comes in, from none of it at the threshold to all of it this
+   * far past. **0, the default, subtracts instead**: a colour keeps what it has past the threshold,
+   * the response since bloom shipped. Unreal's is 2 after exposure, so a frame exposed by `e` that
+   * wants it passes `2 / e`, as it passes the threshold over the exposure.
+   *
+   * Brightness is still the largest channel rather than luminance, for the reason
+   * `shaders/bloom.ts` gives; on a neutral colour the two are equal.
+   */
+  readonly ramp?: number;
+  /**
+   * Each level's colour, three numbers a level, finest first: the halo at a few pixels first and
+   * at a twentieth of the frame last. **White, the default, is the identity**; a level not named
+   * takes white. Not clamped above one, which is how a tint carries a strength past the 0..1 the
+   * dial gives — a stage asking for twice the light names tints twice as bright.
+   *
+   * At most `BLOOM_LEVELS` levels. A frame too small for that many uses the first it has room for.
+   */
+  readonly tints?: ArrayLike<number>;
+}
+
+/** Floats `resolveBloomResponse` writes: the ramp, then a tint a level. */
+export const BLOOM_RESPONSE_FLOATS = 1 + BLOOM_LEVELS * 3;
+
+/**
+ * A response as both backends bind it, into a caller-owned `out` of `BLOOM_RESPONSE_FLOATS`: the
+ * ramp, then `BLOOM_LEVELS` tints, white where none was named. Refuses a tint list that is not
+ * whole colours or names more levels than the pyramid has, naming the length — a caller error with
+ * one correct outcome. A ramp that is not a positive number is the subtraction; a tint channel
+ * that is not a number or is below zero is zero.
+ */
+export function resolveBloomResponse(
+  response: BloomResponse | null | undefined,
+  out: Float32Array,
+): void {
+  const ramp = response?.ramp ?? 0;
+  out[0] = Number.isFinite(ramp) && ramp > 0 ? ramp : 0;
+  const tints = response?.tints;
+  if (tints !== undefined && (tints.length % 3 !== 0 || tints.length > BLOOM_LEVELS * 3)) {
+    throw new Error(
+      `setBloom: ${tints.length} tint values is not up to ${BLOOM_LEVELS} whole colours, three ` +
+        'numbers a level, finest first',
+    );
+  }
+  for (let i = 0; i < BLOOM_LEVELS * 3; i++) {
+    const value = tints !== undefined && i < tints.length ? (tints[i] as number) : 1;
+    out[1 + i] = Number.isFinite(value) && value > 0 ? value : 0;
+  }
+}
+
+/** The response every frame had before 4.8.6: the subtraction, every level white. */
+export function defaultBloomResponse(): Float32Array {
+  const out = new Float32Array(BLOOM_RESPONSE_FLOATS);
+  resolveBloomResponse(null, out);
+  return out;
+}
+
 /** One level of the pyramid: level 0 is half the frame and each one after it half again. */
 export interface BloomLevelSize {
   readonly width: number;

package/src/render/bloomPass.ts

@@ -159,7 +159,14 @@ export class BloomPass {
    * `threshold` is in scene units, so it only separates a light from white paint on a target
    * that kept the range. The caller owns that decision and the warning that goes with it.
    */
-  run(scene: WebGLTexture, width: number, height: number, threshold: number): WebGLTexture | null {
+  run(
+    scene: WebGLTexture,
+    width: number,
+    height: number,
+    threshold: number,
+    /** The ramp, then each level's tint: `resolveBloomResponse`'s floats. */
+    response: Float32Array,
+  ): WebGLTexture | null {
     if (!this.ensureSize(width, height)) return null;
     const { gl } = this;
     const levels = this.levels;
@@ -182,6 +189,7 @@ export class BloomPass {
     gl.bindTexture(gl.TEXTURE_2D, scene);
     gl.uniform1i(this.prefilterUniforms['uSource'] ?? null, 0);
     gl.uniform1f(this.prefilterUniforms['uThreshold'] ?? null, threshold);
+    gl.uniform1f(this.prefilterUniforms['uRamp'] ?? null, response[0] ?? 0);
     this.uploadTexel(this.prefilterUniforms, width, height);
     gl.drawArrays(gl.TRIANGLES, 0, 3);
 
@@ -204,8 +212,13 @@ export class BloomPass {
      * every octave at once. Additive blending rather than a second target to ping-pong through:
      * a level is only ever read while a *different* level is bound, so there is no feedback.
      */
+    /*
+     * Each level's tint rides the blend: the level being added onto is multiplied by its own as the
+     * octave below is added, and the deepest by `uScale` on the first draw, the only one reading it
+     * before anything has been added to it. White everywhere is `ONE, ONE` exactly.
+     */
     gl.enable(gl.BLEND);
-    gl.blendFunc(gl.ONE, gl.ONE);
+    gl.blendFunc(gl.ONE, gl.CONSTANT_COLOR);
     gl.useProgram(this.upsampleProgram);
     gl.uniform1i(this.upsampleUniforms['uSource'] ?? null, 0);
     gl.uniform1f(this.upsampleUniforms['uRadius'] ?? null, BLOOM_FILTER_RADIUS_UV);
@@ -213,12 +226,23 @@ export class BloomPass {
       const target = levels[index - 1];
       const source = levels[index];
       if (target === undefined || source === undefined) break;
+      const deepest = index === levels.length - 1;
+      const into = 1 + (index - 1) * 3;
+      const from = 1 + index * 3;
+      gl.blendColor(response[into] ?? 1, response[into + 1] ?? 1, response[into + 2] ?? 1, 1);
+      gl.uniform3f(
+        this.upsampleUniforms['uScale'] ?? null,
+        deepest ? (response[from] ?? 1) : 1,
+        deepest ? (response[from + 1] ?? 1) : 1,
+        deepest ? (response[from + 2] ?? 1) : 1,
+      );
       gl.bindFramebuffer(gl.FRAMEBUFFER, target.framebuffer);
       gl.viewport(0, 0, target.width, target.height);
       gl.bindTexture(gl.TEXTURE_2D, source.texture);
       gl.drawArrays(gl.TRIANGLES, 0, 3);
     }
 
+    gl.blendColor(0, 0, 0, 0);
     gl.disable(gl.BLEND);
     gl.bindVertexArray(null);
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);