@driftengine/core 4.8.5 → 4.8.7

package/src/render/particleBatch.ts

@@ -3,6 +3,27 @@ import { particleShaders, type ParticleMaterial } from './particleMaterial.ts';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from './shaders/particle.ts';
 import type { ParticleInstances } from './particlePool.ts';
 import { blendCovering, blendKeeping } from './sceneCoverage.ts';
+import type { SurfaceTexture } from './surfaceTexture.ts';
+import { PARTICLE_SPRITE_UNIT } from './lightBudget.ts';
+import { createParticleSort, sortBackToFront, type ParticleSort } from './particleSort.ts';
+
+/** The vertex stage's `uCameraFacing` for a facing: the cross 0, the camera 1, the travel 2. */
+export function facingCode(facing: ParticleFacing): number {
+  return facing === 'cross' ? 0 : facing === 'velocity' ? 2 : 1;
+}
+
+/**
+ * A sprite's frame and half-height, two floats a particle, into `out` — the stream the vertex
+ * stage reads at location 10. Shared by both backends, so the two read one layout.
+ */
+export function packSpriteStream(data: ParticleInstances, count: number, out: Float32Array): void {
+  const frames = data.frames;
+  const heights = data.heights;
+  for (let i = 0; i < count; i++) {
+    out[i * 2] = frames?.[i] ?? 0;
+    out[i * 2 + 1] = heights?.[i] ?? 0;
+  }
+}
 
 /**
  * One draw call for a live particle pool: one camera-facing quad per particle, or a
@@ -26,9 +47,11 @@ export type ParticleBlend = 'additive' | 'alpha';
  * `'camera'` is one quad facing the viewer, and the default. `'cross'` is the pair of
  * world-fixed blades this batch drew before the option existed — see `uCameraFacing` in
  * `shaders/particle.ts` for the artifact that made the default the other one, and for what
- * the cross still buys a caller who wants it back.
+ * the cross still buys a caller who wants it back. `'velocity'` faces the camera with its up along
+ * the particle's travel across the view — a streak, a spark stretched by its motion — and a
+ * particle at rest faces the camera as `'camera'` does.
  */
-export type ParticleFacing = 'camera' | 'cross';
+export type ParticleFacing = 'camera' | 'cross' | 'velocity';
 
 export interface ParticleBatchOptions {
   /**
@@ -78,6 +101,41 @@ export interface ParticleBatchOptions {
    * shader's own comment on `uCameraFacing` lays out.
    */
   facing?: ParticleFacing;
+  /**
+   * The image a `'sprite'` draws: a surface texture, its first layer. **Required by the sprite** and
+   * ignored by the procedural materials. Colour is the particle's times the image's, unlit.
+   */
+  texture?: SurfaceTexture;
+  /**
+   * A `'sprite'`'s flipbook: the image as `[columns, rows]` cells, numbered across then down from
+   * the top-left, a particle's `frames` naming one. `[1, 1]`, the default, is the whole image.
+   */
+  cells?: readonly [number, number];
+  /**
+   * Whether a `'sprite'` blends from a particle's cell toward the next by the fraction of its
+   * frame, so a slow flipbook moves rather than steps. Off by default: one cell, sampled once.
+   */
+  blendCells?: boolean;
+  /**
+   * Metres over which a `'sprite'` fades where it meets the opaque scene: the hard line a flat card
+   * draws where it cuts a floor or a body, softened. **0, the default, is a hard edge.** It reads a
+   * copy of the frame's depth, which needs `screenEffects`; without one the edge stays hard and
+   * the renderer says so once.
+   */
+  softDepth?: number;
+  /** Metres in front of the eye over which a `'sprite'` fades in. 0, the default, is no fade. */
+  cameraFade?: number;
+  /**
+   * Metres each particle is moved toward the eye before it is drawn, so a sprite born inside a
+   * surface is drawn in front of it. 0 by default. Every material reads it.
+   */
+  cameraOffset?: number;
+  /**
+   * Whether the live particles are drawn farthest first, the order an alpha blend assumes. Off
+   * by default, because sorting costs a pass over the particles on the CPU each frame and an
+   * additive blend is a sum that does not care. See `particleSort.ts`.
+   */
+  sort?: boolean;
   /**
    * Another batch whose compiled program this one should reuse.
    *
@@ -118,6 +176,17 @@ export class ParticleBatch {
   private readonly ageBuffer: WebGLBuffer;
   private readonly seedBuffer: WebGLBuffer;
   private readonly velocityBuffer: WebGLBuffer;
+  private readonly spriteBuffer: WebGLBuffer;
+  private readonly spriteStaging: Float32Array;
+  /** Room to draw farthest first, where the batch asked. See `ParticleBatchOptions.sort`. */
+  private readonly order: ParticleSort | null;
+  /** The sprite's own: its image, its flipbook and its fades. See `ParticleBatchOptions`. */
+  readonly texture: SurfaceTexture | null;
+  readonly cells: readonly [number, number];
+  readonly blendCells: boolean;
+  readonly softDepth: number;
+  readonly cameraFade: number;
+  readonly cameraOffset: number;
   private readonly blend: ParticleBlend;
   private readonly stretchSec: number;
   private readonly erosion: number;
@@ -152,6 +221,17 @@ export class ParticleBatch {
     this.coreGain = options.coreGain ?? 1;
     this.fog = options.fog ?? false;
     this.facing = options.facing ?? 'camera';
+    this.texture = options.texture ?? null;
+    this.cells = options.cells ?? [1, 1];
+    this.blendCells = options.blendCells === true;
+    this.softDepth = Math.max(0, options.softDepth ?? 0);
+    this.cameraFade = Math.max(0, options.cameraFade ?? 0);
+    this.cameraOffset = options.cameraOffset ?? 0;
+    this.order = options.sort === true ? createParticleSort(capacity) : null;
+    this.spriteStaging = new Float32Array(capacity * 2);
+    if (options.material === 'sprite' && this.texture === null) {
+      throw new Error("createParticles: a 'sprite' draws an image, and was given no `texture`");
+    }
 
     const corners = new Float32Array(PARTICLE_VERTS * 2);
     const blades = new Float32Array(PARTICLE_VERTS);
@@ -189,6 +269,7 @@ export class ParticleBatch {
     this.ageBuffer = this.attach(gl, 7, capacity, 1, 1, shaders.label);
     this.seedBuffer = this.attach(gl, 8, capacity, 1, 1, shaders.label);
     this.velocityBuffer = this.attach(gl, 9, capacity * 3, 3, 1, shaders.label);
+    this.spriteBuffer = this.attach(gl, 10, capacity * 2, 2, 1, shaders.label);
 
     const indexBuffer = gl.createBuffer();
     if (indexBuffer === null) throw new Error(`${shaders.label}: createBuffer failed`);
@@ -204,9 +285,12 @@ export class ParticleBatch {
    * Only the live prefix of each array, which is what the pool's compaction
    * exists for: a pool at a tenth of its capacity uploads a tenth of the bytes.
    */
-  upload(gl: WebGL2RenderingContext, data: ParticleInstances): void {
+  upload(gl: WebGL2RenderingContext, given: ParticleInstances, eye: ArrayLike<number>): void {
+    const data = this.order === null ? given : sortBackToFront(given, eye, this.order);
     const n = data.count;
     if (n === 0) return;
+    packSpriteStream(data, n, this.spriteStaging);
+    this.send(gl, this.spriteBuffer, this.spriteStaging, n * 2);
     this.send(gl, this.positionBuffer, data.positions, n * 3);
     this.send(gl, this.sizeBuffer, data.sizes, n);
     this.send(gl, this.spinBuffer, data.spins, n);
@@ -221,7 +305,14 @@ export class ParticleBatch {
   bindMaterial(gl: WebGL2RenderingContext): void {
     const u = this.uniforms;
     gl.uniform1f(u['uStretchSec'] ?? null, this.stretchSec);
-    gl.uniform1f(u['uCameraFacing'] ?? null, this.facing === 'camera' ? 1 : 0);
+    gl.uniform1f(u['uCameraFacing'] ?? null, facingCode(this.facing));
+    gl.uniform1f(u['uCameraOffset'] ?? null, this.cameraOffset);
+    /* The sprite's flipbook and its image; the fades are the renderer's, which owns the depth. */
+    if (this.texture !== null) {
+      gl.uniform4f(u['uCells'] ?? null, this.cells[0], this.cells[1], this.blendCells ? 1 : 0, 0);
+      this.texture.bind(gl, PARTICLE_SPRITE_UNIT);
+      gl.uniform1i(u['uSprite'] ?? null, PARTICLE_SPRITE_UNIT);
+    }
     gl.uniform1f(u['uErosion'] ?? null, this.erosion);
     gl.uniform1f(u['uCoreGain'] ?? null, this.coreGain);
     /* Only the mote program declares uFogEnabled, so this is a no-op — not a leak into the

package/src/render/particleMaterial.ts

@@ -2,6 +2,7 @@ import {
   PARTICLE_MOTE_FRAG,
   PARTICLE_SMOKE_FRAG,
   PARTICLE_SPARK_FRAG,
+  PARTICLE_SPRITE_FRAG,
   PARTICLE_VERT,
 } from './shaders/particle.ts';
 import {
@@ -9,6 +10,7 @@ import {
   PARTICLE_MOTE_FRAG_WGSL,
   PARTICLE_SMOKE_FRAG_WGSL,
   PARTICLE_SPARK_FRAG_WGSL,
+  PARTICLE_SPRITE_FRAG_WGSL,
   PARTICLE_VERT_WGSL,
 } from './shaders/generated/particle.wgsl.ts';
 
@@ -27,7 +29,7 @@ import {
  * document that. Naming them makes the pairing explicit instead of leaving it to a caller to
  * match a source with the constants that suit it.
  */
-export type ParticleMaterial = 'smoke' | 'spark' | 'mote';
+export type ParticleMaterial = 'smoke' | 'spark' | 'mote' | 'sprite';
 
 /** Both compilations of one material, and what the generator recorded about each stage. */
 export interface ParticleShaders {
@@ -66,6 +68,14 @@ const MATERIALS: Readonly<Record<ParticleMaterial, ParticleShaders>> = {
     vertexWgsl: PARTICLE_VERT_WGSL,
     fragmentWgsl: PARTICLE_MOTE_FRAG_WGSL,
   },
+  /* An image a consumer supplies, not a shape this engine draws: see `PARTICLE_SPRITE_FRAG`. */
+  sprite: {
+    label: 'particle:sprite',
+    vertexSource: PARTICLE_VERT,
+    fragmentSource: PARTICLE_SPRITE_FRAG,
+    vertexWgsl: PARTICLE_VERT_WGSL,
+    fragmentWgsl: PARTICLE_SPRITE_FRAG_WGSL,
+  },
 };
 
 /** What the generator recorded about the shared vertex stage. */

package/src/render/particlePool.ts

@@ -38,10 +38,44 @@ export interface ParticleInstances {
   seeds: Float32Array;
   /** Current velocity, three floats each: what a streak is stretched along. */
   velocities: Float32Array;
+  /**
+   * A sprite's flipbook frame, one float each: its whole part names a cell of the image, counted
+   * across then down from the top-left, and its fraction is how far toward the next a batch that
+   * blends cells has come. Read by the `'sprite'` material alone. Absent is frame 0.
+   */
+  frames?: Float32Array;
+  /**
+   * A sprite's half-height in metres, one float each, beside `sizes`' half-width — a sprite need
+   * not be square. Read by the `'sprite'` material alone; absent or 0 is as tall as it is wide.
+   */
+  heights?: Float32Array;
   count: number;
   capacity: number;
 }
 
+/**
+ * Floats one particle takes in a buffer a caller's own compute writes (`DeviceParticles`), in this
+ * order: position 3, half-width 1, roll 1, colour 3, opacity 1, age 1, seed 1, velocity 3, a
+ * sprite's frame 1 and its half-height 1 — `ParticleInstances`' streams, interleaved as the pool's
+ * own upload interleaves them. 64 bytes a particle.
+ */
+export const DEVICE_PARTICLE_FLOATS = 16;
+
+/**
+ * Particles a caller's own compute shader wrote into a buffer of its own (`registerCompute`), drawn
+ * where they lie by `drawDeviceParticles` rather than read back and uploaded again. WebGPU only.
+ *
+ * **Not sorted**, as a pool's are where its batch asks: the device holds them, so an alpha-blended
+ * set that must be drawn far to near sorts itself. A slot with a half-width of 0 draws nothing, which
+ * is how a fixed-size buffer holds fewer live particles than it has room for.
+ */
+export interface DeviceParticles {
+  /** A buffer with `VERTEX` usage, `DEVICE_PARTICLE_FLOATS` floats a particle. */
+  readonly buffer: GPUBuffer;
+  /** How many particles from its start to draw; no more than the buffer holds. */
+  readonly count: number;
+}
+
 function createParticleInstances(capacity: number): ParticleInstances {
   return {
     positions: new Float32Array(capacity * 3),
@@ -52,6 +86,8 @@ function createParticleInstances(capacity: number): ParticleInstances {
     ages: new Float32Array(capacity),
     seeds: new Float32Array(capacity),
     velocities: new Float32Array(capacity * 3),
+    frames: new Float32Array(capacity),
+    heights: new Float32Array(capacity),
     count: 0,
     capacity,
   };

package/src/render/particleSort.ts

@@ -0,0 +1,133 @@
+/**
+ * A pool's particles, farthest from the eye first, for a blended batch that asks to be sorted.
+ *
+ * **Why a blended batch wants it.** An alpha blend is order-dependent: a near puff drawn before a
+ * far one is covered by it, and a cloud of them drawn in the order they were born flickers as
+ * that order and the camera disagree. Back to front is the order the blend assumes. Additive
+ * blending is a sum and needs none of it, which is why sorting is the batch's choice.
+ *
+ * **Backend-neutral, as a copy**: the sorted particles are written into a second set of streams the
+ * batch owns, and each backend uploads that set exactly as it uploads an unsorted one — so the
+ * order is one decision, not two, by the 2026-08-13 rule. A merge sort into preallocated scratch,
+ * so nothing is allocated per frame however many particles there are; stable, so two particles at
+ * one distance keep their order and do not trade places from frame to frame.
+ *
+ * **What it gives up** is order between batches and within one particle: two sorted batches still
+ * draw one after the other, and two crossing cards cut through each other. **What would make it
+ * wrong** is a field of particles large enough that sorting it on the CPU costs a frame; the GPU
+ * sorts it then.
+ */
+import type { ParticleInstances } from './particlePool.ts';
+
+/** What sorting a batch keeps between frames: the order, its keys and the sorted copy. */
+export interface ParticleSort {
+  readonly order: Uint32Array;
+  readonly scratch: Uint32Array;
+  readonly keys: Float32Array;
+  readonly sorted: ParticleInstances;
+}
+
+/** Room to sort `capacity` particles, allocated once with the batch. */
+export function createParticleSort(capacity: number): ParticleSort {
+  return {
+    order: new Uint32Array(capacity),
+    scratch: new Uint32Array(capacity),
+    keys: new Float32Array(capacity),
+    sorted: {
+      positions: new Float32Array(capacity * 3),
+      sizes: new Float32Array(capacity),
+      spins: new Float32Array(capacity),
+      colors: new Float32Array(capacity * 3),
+      alphas: new Float32Array(capacity),
+      ages: new Float32Array(capacity),
+      seeds: new Float32Array(capacity),
+      velocities: new Float32Array(capacity * 3),
+      frames: new Float32Array(capacity),
+      heights: new Float32Array(capacity),
+      count: 0,
+      capacity,
+    },
+  };
+}
+
+/**
+ * `data`'s live particles into `sort.sorted`, farthest from `eye` first, and that copy returned.
+ * At most the sort's capacity are kept.
+ */
+export function sortBackToFront(
+  data: ParticleInstances,
+  eye: ArrayLike<number>,
+  sort: ParticleSort,
+): ParticleInstances {
+  const count = Math.min(data.count, sort.order.length);
+  const { order, keys } = sort;
+  const ex = eye[0] ?? 0;
+  const ey = eye[1] ?? 0;
+  const ez = eye[2] ?? 0;
+  for (let i = 0; i < count; i++) {
+    const dx = (data.positions[i * 3] as number) - ex;
+    const dy = (data.positions[i * 3 + 1] as number) - ey;
+    const dz = (data.positions[i * 3 + 2] as number) - ez;
+    keys[i] = dx * dx + dy * dy + dz * dz;
+    order[i] = i;
+  }
+  mergeSortFarFirst(order, sort.scratch, keys, count);
+
+  const out = sort.sorted;
+  for (let k = 0; k < count; k++) {
+    const i = order[k] as number;
+    copy3(data.positions, i, out.positions, k);
+    copy3(data.colors, i, out.colors, k);
+    copy3(data.velocities, i, out.velocities, k);
+    out.sizes[k] = data.sizes[i] as number;
+    out.spins[k] = data.spins[i] as number;
+    out.alphas[k] = data.alphas[i] as number;
+    out.ages[k] = data.ages[i] as number;
+    out.seeds[k] = data.seeds[i] as number;
+    (out.frames as Float32Array)[k] = data.frames?.[i] ?? 0;
+    (out.heights as Float32Array)[k] = data.heights?.[i] ?? 0;
+  }
+  out.count = count;
+  return out;
+}
+
+function copy3(from: Float32Array, i: number, to: Float32Array, k: number): void {
+  to[k * 3] = from[i * 3] as number;
+  to[k * 3 + 1] = from[i * 3 + 1] as number;
+  to[k * 3 + 2] = from[i * 3 + 2] as number;
+}
+
+/** A bottom-up merge sort of `order` by `keys`, largest first, stable, through `scratch`. */
+function mergeSortFarFirst(
+  order: Uint32Array,
+  scratch: Uint32Array,
+  keys: Float32Array,
+  count: number,
+): void {
+  let from = order;
+  let to = scratch;
+  for (let width = 1; width < count; width *= 2) {
+    for (let start = 0; start < count; start += 2 * width) {
+      const middle = Math.min(start + width, count);
+      const end = Math.min(start + 2 * width, count);
+      let a = start;
+      let b = middle;
+      let at = start;
+      while (a < middle && b < end) {
+        /* `>=` keeps the left run's particle first on a tie, which is what makes this stable. */
+        if ((keys[from[a] as number] as number) >= (keys[from[b] as number] as number)) {
+          to[at++] = from[a++] as number;
+        } else {
+          to[at++] = from[b++] as number;
+        }
+      }
+      while (a < middle) to[at++] = from[a++] as number;
+      while (b < end) to[at++] = from[b++] as number;
+    }
+    const swap = from;
+    from = to;
+    to = swap;
+  }
+  /* Copied by hand: a subarray would be a view allocated every frame. */
+  if (from !== order) for (let i = 0; i < count; i++) order[i] = from[i] as number;
+}

package/src/render/pointLightSelection.ts

@@ -1,6 +1,10 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
 
-import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.ts';
+import {
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  lightFalloffExponentOf,
+} from './clusteredLights.ts';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.ts';
 import { gatherLights } from './lightGrid.ts';
 import type { LightGrid } from './lightGrid.ts';
@@ -198,6 +202,14 @@ export interface PointLightSource {
    * whose uniform budget has none to spare.
    */
   inLightField?: boolean;
+  /**
+   * How the light fades with distance when it names its own way: `(1 - (d/R)^2)^n` with no distance
+   * term, `R` its radius and `n` this. Unreal's falloff for a light without inverse-square falloff,
+   * so a rig authored there — a fill of brightness 160 across 164 m, a key at exponent 8 — lights
+   * the space it was authored for rather than one that ends a few metres out. Absent or 0, the
+   * frame's own falloff (`pointLightFalloff`), which is every light before 4.8.7.
+   */
+  falloffExponent?: number;
 }
 
 export interface PointLightBuffer {
@@ -256,6 +268,11 @@ export interface PointLightBuffer {
   readonly directions: Float32Array;
   /** Two per slot: the cosine of the inner cone angle, then of the outer. */
   readonly coneCos: Float32Array;
+  /**
+   * One per slot: the light's own falloff exponent, or 0 for the frame's falloff. See
+   * `PointLightSource.falloffExponent`.
+   */
+  readonly falloffExponents: Float32Array;
   /** One per slot: a row of the photometric atlas, or −1 for a light with no profile. */
   readonly iesProfiles: Float32Array;
   /** Internal insertion-sort storage; exposed only to keep one flat object. */
@@ -307,6 +324,7 @@ export function createPointLightBuffer(capacity: number = MAX_POINT_LIGHTS): Poi
     weights: new Float32Array(shaded),
     directions: new Float32Array(shaded * 3),
     coneCos: new Float32Array(shaded * 2),
+    falloffExponents: new Float32Array(shaded),
     /* −1 rather than 0, because row 0 is a real fixture and a light that asked for none must not
        be shaped by whichever profile happened to load first. */
     iesProfiles: new Float32Array(shaded).fill(-1),
@@ -587,6 +605,7 @@ function choose(
      * Restricting it to spots would be a smaller feature for no saving.
      */
     out.iesProfiles[slot] = light.iesProfile ?? -1;
+    out.falloffExponents[slot] = lightFalloffExponentOf(light.falloffExponent);
   }
   out.count = chosen;
 

package/src/render/renderQuality.ts

@@ -219,13 +219,14 @@ export interface RenderQuality {
    * **`'pre-integrated'`, the default**: the lit stage's fit alone — a terminator softened and
    * reddened by the surface's curvature, light through thin parts, a penumbra each channel crosses
    * as far as it travels — at no cost beyond the skin pipeline itself. **`'screen-space'`** adds
-   * Burley's blur in the picture as well: a skin draw writes its diffuse to a target of its own (it
-   * is drawn twice to do so), which is spread across the pixels its scatter distance covers and
-   * added back before anything blended is drawn, so light crosses a shadow's edge and a nostril's
-   * rim in the picture rather than in a fit. See `skinBlur.ts`.
-   *
-   * Construction-time: two half-float targets the size of the frame, and a multisampled one under
-   * multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
+   * Burley's blur in the picture as well: a skin draw writes the light its diffuse is made of to a
+   * target of its own and its colour to another (it is drawn three times to do so), and the light is
+   * spread across the pixels its scatter distance covers, multiplied by the colour and added back
+   * before anything blended is drawn, so light crosses a shadow's edge and a nostril's rim in the
+   * picture rather than in a fit. See `skinBlur.ts`.
+   *
+   * Construction-time: three half-float targets the size of the frame, and two multisampled ones
+   * under multisampling, made at the first skin draw. It needs the composite (`screenEffects`), which is
    * where the frame is still linear light to add to; without one, skin is pre-integrated and the
    * renderer says so once. What would make the default wrong is a close-up face that reads as wax
    * at a shadow's edge — that is what the blur is for.

package/src/render/rendererHarness.ts

@@ -119,6 +119,9 @@ export function recordingGl(
     ONE: 1,
     ONE_MINUS_SRC_ALPHA: 0x0303,
     TRIANGLES: 0x0004,
+    /* The winding a pass names, so a test can tell which one it chose. */
+    CW: 0x0900,
+    CCW: 0x0901,
     TEXTURE0: 0x84c0,
     DEPTH_BUFFER_BIT: 0x00000100,
     DEPTH_TEST: 0x0b71,

package/src/render/rgb9e5.ts

@@ -0,0 +1,52 @@
+/**
+ * rgb9e5: three 9-bit mantissas over one shared 5-bit exponent, an unsigned float colour in four
+ * bytes. `EXT_texture_shared_exponent`'s encoding, the one a GPU's `rgb9e5ufloat` reads, written
+ * out so a lightmap page can hold its irradiance in four bytes a texel against a half float's eight.
+ *
+ * **What it gives up**: precision in the smaller channels, which share the largest one's exponent —
+ * a channel a thousandth of its neighbour keeps about one bit — and anything negative or past
+ * 65,408, which it clamps. Light is neither, and a bake's colours rarely span more than a few
+ * octaves within one texel, so a lightmap loses nothing visible; a value that needs each channel
+ * exact wants a format of its own.
+ *
+ * The bits, low to high: red in 0–8, green in 9–17, blue in 18–26, the exponent in 27–31, biased by
+ * 15, and a value is `mantissa * 2^(exponent - 15 - 9)`.
+ */
+
+const BIAS = 15;
+const MANTISSA_BITS = 9;
+const MANTISSA_VALUES = 1 << MANTISSA_BITS;
+const MAX_EXPONENT = 31;
+
+/** The largest value the format holds: 511/512 of 2^16. */
+export const RGB9E5_MAX = ((MANTISSA_VALUES - 1) / MANTISSA_VALUES) * 2 ** (MAX_EXPONENT - BIAS);
+
+const clampChannel = (v: number): number => (v > 0 ? Math.min(v, RGB9E5_MAX) : 0);
+
+/** One colour packed into its 32 bits, rounding to nearest; NaN and negatives are zero. */
+export function packRgb9e5(red: number, green: number, blue: number): number {
+  const r = clampChannel(red);
+  const g = clampChannel(green);
+  const b = clampChannel(blue);
+  const largest = Math.max(r, g, b);
+  let exponent = Math.max(-BIAS - 1, Math.floor(Math.log2(largest))) + 1 + BIAS;
+  let scale = 2 ** (exponent - BIAS - MANTISSA_BITS);
+  /* Rounding the largest channel up to 512 needs one more exponent, which the spec allows for. */
+  if (Math.floor(largest / scale + 0.5) === MANTISSA_VALUES) {
+    exponent += 1;
+    scale *= 2;
+  }
+  /* Inline rather than a helper: a page packs millions of texels, and a closure a call is one each. */
+  const mr = Math.min(MANTISSA_VALUES - 1, Math.floor(r / scale + 0.5));
+  const mg = Math.min(MANTISSA_VALUES - 1, Math.floor(g / scale + 0.5));
+  const mb = Math.min(MANTISSA_VALUES - 1, Math.floor(b / scale + 0.5));
+  return (mr | (mg << 9) | (mb << 18) | (exponent << 27)) >>> 0;
+}
+
+/** A packed colour's three channels, into `out[at…at+2]`. */
+export function unpackRgb9e5(bits: number, out: { [index: number]: number }, at = 0): void {
+  const scale = 2 ** ((bits >>> 27) - BIAS - MANTISSA_BITS);
+  out[at] = (bits & 511) * scale;
+  out[at + 1] = ((bits >>> 9) & 511) * scale;
+  out[at + 2] = ((bits >>> 18) & 511) * scale;
+}

package/src/render/sceneCapture.ts

@@ -0,0 +1,56 @@
+/**
+ * A scene capture: a texture the world is drawn into from a camera of the caller's, which a material
+ * then shows like any image — a screen in the world showing what a camera elsewhere sees, a monitor,
+ * a security feed. The planar reflection's pass, for a caller's camera rather than a mirrored one.
+ *
+ * **It holds radiance, not display pixels**, as a probe does: drawn with the output transform held
+ * off, at the colour format a probe takes — half floats under `hdrScene`, bytes otherwise — and
+ * sampled linear, so a material showing it as its `emissive` emits the light the capture saw and the
+ * frame's grade then applies once, to the screen as to everything around it.
+ *
+ * **What it gives up**: it is the mesh pass alone, as a probe bake is — the sky, water, particles and
+ * anything else a scene draws after its world are in the capture only if the callback draws them;
+ * no temporal resolve, bloom or other effect after the world runs on it; and it has no mip chain, so
+ * a screen seen small and far shimmers where a mipmapped image would not.
+ */
+
+/** What a capture's texture is made from, in place of an image: its size and colour format. */
+export interface SceneCaptureTexels {
+  readonly kind: 'scene-capture';
+  readonly width: number;
+  readonly height: number;
+  /** Half floats, which hold light past one; bytes otherwise. */
+  readonly float: boolean;
+}
+
+/** The largest side a capture may have, the size every WebGL2 device must take. */
+export const MAX_SCENE_CAPTURE_SIZE = 4096;
+
+/** A capture's description, refused by name where a side is not a whole number of pixels it can be. */
+export function sceneCaptureTexels(
+  width: number,
+  height: number,
+  float: boolean,
+): SceneCaptureTexels {
+  for (const [name, side] of [
+    ['width', width],
+    ['height', height],
+  ] as const) {
+    if (!Number.isInteger(side) || side < 1 || side > MAX_SCENE_CAPTURE_SIZE) {
+      throw new Error(
+        `createSceneCapture: ${name} must be a whole number from 1 to ${MAX_SCENE_CAPTURE_SIZE}, ` +
+          `not ${String(side)}`,
+      );
+    }
+  }
+  return { kind: 'scene-capture', width, height, float };
+}
+
+/** Whether a texture source is a capture's description rather than an image. */
+export function isSceneCaptureTexels(source: unknown): source is SceneCaptureTexels {
+  return (
+    typeof source === 'object' &&
+    source !== null &&
+    (source as { kind?: unknown }).kind === 'scene-capture'
+  );
+}

package/src/render/sceneTarget.ts

@@ -497,6 +497,15 @@ export class SceneTarget {
    * must reject it in the same place or the accumulation and the revealage cover different
    * fragments.
    */
+  /** The frame's size in pixels, as its targets are allocated. */
+  get frameWidth(): number {
+    return this.width;
+  }
+
+  get frameHeight(): number {
+    return this.height;
+  }
+
   /**
    * The depth the frame draws against, for a second framebuffer to share: skin's diffuse half,
    * which tests against it and writes none. The multisampled renderbuffer where the frame is
@@ -783,6 +792,8 @@ export class SceneTarget {
       readonly strength: number;
       /** In scene units, which is why this wants `keepsRange`. See `BloomPass`. */
       readonly threshold: number;
+      /** The ramp and each level's tint, as `resolveBloomResponse` writes them. */
+      readonly response: Float32Array;
     },
     /*
      * Depth of field, between the camera smear and the occlusion in the shader's own order. Like
@@ -966,7 +977,13 @@ export class SceneTarget {
     let bloomTexture: WebGLTexture | null = null;
     if (bloom !== undefined && scene !== null) {
       this.bloom ??= new BloomPass(gl);
-      bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold);
+      bloomTexture = this.bloom.run(
+        scene,
+        this.width,
+        this.height,
+        bloom.threshold,
+        bloom.response,
+      );
     }
 
     /*