@driftengine/core 4.8.5 → 4.8.7

package/dist/render/surfaceTexture.js

@@ -2,6 +2,8 @@ import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.js';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.js';
 import { uploadCompressedArray } from './glCompressed.js';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.js';
+import { isLightmapTexels } from './lightmap.js';
+import { isSceneCaptureTexels } from './sceneCapture.js';
 const DEFAULT_ANISOTROPY = 4;
 /**
  * An image uploaded once and bound per draw.
@@ -29,7 +31,11 @@ export class SurfaceTexture {
      * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
     constructor(gl, source, options = {}, compressed = []) {
-        const listed = (Array.isArray(source) ? source : [source]);
+        /* A scene capture's target: one empty layer the renderer draws into. See `sceneCapture.ts`. */
+        const capture = isSceneCaptureTexels(source) ? source : null;
+        /* A lightmap's page: two layers of bytes, uploaded as they are. See `lightmap.ts`. */
+        const baked = isLightmapTexels(source) ? source : null;
+        const listed = (baked !== null || capture !== null ? [] : Array.isArray(source) ? source : [source]);
         const blocks = compressedLayers(listed);
         this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
         /* Refused before anything is allocated, so a refusal leaves no texture behind. */
@@ -40,7 +46,29 @@ export class SurfaceTexture {
         this.texture = texture;
         const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
-        if (blocks !== null && plan !== null) {
+        if (capture !== null) {
+            /* Immutable storage, one level: a framebuffer attachment, and radiance read linear. */
+            this.layers = 1;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, capture.float ? gl.RGBA16F : gl.RGBA8, capture.width, capture.height, 1);
+        }
+        else 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.length;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            /* A typed array refuses either flag set, so both are put down here rather than assumed. */
+            gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+            gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+            /* Bytes, and read by `texelFetch` alone: the shader decodes and filters. See `lightmap.ts`. */
+            gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, gl.RGBA8, baked.width, baked.height, this.layers, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+            /* A layer at a time, so a page's arrays are uploaded where they lie rather than joined. */
+            for (let layer = 0; layer < this.layers; layer++) {
+                gl.texSubImage3D(gl.TEXTURE_2D_ARRAY, 0, 0, 0, layer, baked.width, baked.height, 1, gl.RGBA, gl.UNSIGNED_BYTE, baked.layers[layer]);
+            }
+        }
+        else if (blocks !== null && plan !== null) {
             /* The stored chain, or level 0 alone where no chain was asked for. Nothing is generated:
                `generateMipmap` cannot write a compressed format. */
             this.layers = blocks.length;
@@ -122,6 +150,13 @@ export class SurfaceTexture {
             gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
     }
+    /**
+     * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
+     * by `captureScene`. Engine-internal, as `bind` is.
+     */
+    attachColor(gl) {
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, 0);
+    }
     /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
     bind(gl, unit) {
         gl.activeTexture(gl.TEXTURE0 + unit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.8.5",
+  "version": "4.8.7",
   "description": "The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.8.5",
-    "@driftengine/physics": "4.8.5",
+    "@driftengine/drft": "4.8.7",
+    "@driftengine/physics": "4.8.7",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.8.5",
-    "@driftengine/network": "4.8.5",
-    "@driftengine/texture": "4.8.5"
+    "@driftengine/nav": "4.8.7",
+    "@driftengine/network": "4.8.7",
+    "@driftengine/texture": "4.8.7"
   }
 }

package/src/index.ts

@@ -454,6 +454,12 @@ export type { ReflectionOptions, ReflectiveSample } from './render/gi/reflection
  */
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.ts';
 export type { ColourGradeLut } from './render/colourGrade.ts';
+/**
+ * How bloom answers past its threshold — a ramp in place of the subtraction, and a tint for each
+ * of the pyramid's `BLOOM_LEVELS` octaves — the third argument of `setBloom`.
+ */
+export { BLOOM_LEVELS } from './render/bloomChain.ts';
+export type { BloomResponse } from './render/bloomChain.ts';
 export { probeDevice } from './render/backend/probe.ts';
 export type { ProbeVerdict } from './render/backend/probe.ts';
 /*
@@ -491,15 +497,28 @@ export type { ClothBindingData } from './render/clothBindingData.ts';
  * A frozen descriptor made by a factory and set as `SurfaceMaterial.model`; each is a pipeline of
  * its own, compiled the first time a draw asks.
  */
-export { anisotropicModel, eyeModel, hairModel, skinModel } from './render/surfaceModel.ts';
+export {
+  anisotropicModel,
+  eyeModel,
+  hairModel,
+  lightmapModel,
+  skinModel,
+} from './render/surfaceModel.ts';
 export type {
   AnisotropicModel,
   EyeModel,
   HairModel,
+  LightmapModel,
   SkinModel,
   SurfaceModel,
   SurfaceModelKind,
 } from './render/surfaceModel.ts';
+/*
+ * A baked lightmap: the page a consumer decoded, which `createLightmap` uploads as a lightmapped
+ * material's `modelMap`, and the region of it a material or an instance reads.
+ */
+export { WHOLE_PAGE } from './render/lightmap.ts';
+export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
 /*
  * A skinned cloth solved where the renderer can: compute on WebGPU, the CPU under WebGL2. A function
  * rather than a renderer method so only a game that imports it carries the solver.
@@ -1046,8 +1065,12 @@ export {
   INSTANCE_FLOATS,
   INSTANCE_STRIDE,
 } from './render/instances.ts';
-export { ParticlePool } from './render/particlePool.ts';
-export type { ParticlePoolOptions, ParticleInstances } from './render/particlePool.ts';
+export { ParticlePool, DEVICE_PARTICLE_FLOATS } from './render/particlePool.ts';
+export type {
+  DeviceParticles,
+  ParticlePoolOptions,
+  ParticleInstances,
+} from './render/particlePool.ts';
 export { ParticleBatch } from './render/particleBatch.ts';
 export type {
   ParticleBatchOptions,

package/src/render/ambientHarmonics.ts

@@ -0,0 +1,92 @@
+/**
+ * A draw's own ambient light, as nine spherical-harmonic coefficients: what `setAmbientSH` takes,
+ * how both backends pack it, and the arithmetic the lit stage evaluates, which its tests hold.
+ *
+ * **Why a draw needs its own.** The engine's diffuse ambient is one answer for a whole frame — the
+ * sky-and-ground gradient, or the probe grid's irradiance — so everything standing in one place is
+ * lit alike. A stage with a baked volume of indirect light (Unreal's volumetric lightmap) lights a
+ * character by sampling that volume where the character stands; a consumer that samples it each
+ * frame hands the result here, around that character's draws, and the character takes the light of
+ * the spot it is in rather than the frame's average.
+ *
+ * **The coefficients are of incoming radiance**, `L(ω) ≈ Σ c_lm Y_lm(ω)`, on the standard real
+ * basis in its usual order — `Y00`, then `Y1,-1 Y1,0 Y1,1`, then `Y2,-2 Y2,-1 Y2,0 Y2,1 Y2,2` —
+ * evaluated on the engine's own world axes as written: `Y1,-1 = 0.488603 y`, `Y1,0 = 0.488603 z`,
+ * `Y1,1 = 0.488603 x`, `Y2,-2 = 1.092548 xy`, `Y2,-1 = 1.092548 yz`, `Y2,0 = 0.315392 (3z² − 1)`,
+ * `Y2,1 = 1.092548 xz`, `Y2,2 = 0.546274 (x² − y²)`, with y up. Three numbers a coefficient, red
+ * green blue, twenty-seven in all. A source in another engine's axes is rotated into these first.
+ *
+ * **What the surface receives is the cosine convolution**, Ramamoorthi and Hanrahan's: the bands
+ * scaled by π, 2π/3 and π/4 and divided by π, which is the irradiance over π a Lambertian surface
+ * multiplies its albedo by — the same quantity the gradient and the probes hand the shader. A
+ * constant radiance `L` everywhere is `c00 = L / 0.282095` and lights a surface exactly as an
+ * ambient of `L` does. Negative ringing, which a second-order fit of a sharp source has, is clamped
+ * to zero.
+ *
+ * **What it gives up** is the reflections: these replace the diffuse ambient only, and a glossy
+ * surface still reflects the frame's probes or sky. **What would make it wrong** is light the
+ * volume holds at a frequency nine coefficients cannot carry — a sharp sun patch — which is the
+ * stage's own direct light's job and not this.
+ */
+
+/** Numbers `setAmbientSH` takes: nine coefficients of three channels. */
+export const AMBIENT_SH_VALUES = 27;
+
+/** Floats the lit stage's `uAmbientSH` holds: the coefficients, and whether they are on. */
+export const AMBIENT_SH_FLOATS = 28;
+
+/**
+ * The coefficients as the lit stage reads them, into `out` of `AMBIENT_SH_FLOATS`: the twenty-seven
+ * numbers in order and a last one that is 1, or every float zero for `null` — the frame's own
+ * ambient. Refuses a list that is not twenty-seven numbers, naming its length.
+ */
+export function packAmbientSH(coefficients: ArrayLike<number> | null, out: Float32Array): void {
+  if (coefficients === null) {
+    out.fill(0);
+    return;
+  }
+  if (coefficients.length !== AMBIENT_SH_VALUES) {
+    throw new Error(
+      `setAmbientSH: ${coefficients.length} values, where nine coefficients of red, green and ` +
+        `blue are ${AMBIENT_SH_VALUES}`,
+    );
+  }
+  for (let i = 0; i < AMBIENT_SH_VALUES; i++) {
+    const value = coefficients[i] as number;
+    out[i] = Number.isFinite(value) ? value : 0;
+  }
+  out[AMBIENT_SH_VALUES] = 1;
+}
+
+/** The band factors of the cosine convolution, over π: 1, 2/3 and 1/4. */
+const BAND = [1, 2 / 3, 1 / 4] as const;
+
+/**
+ * The ambient a surface facing `nx, ny, nz` (unit) receives from these coefficients, into `out`
+ * (three floats): what `ambientHarmonics` in the lit stage computes. Run at no point by the engine;
+ * the reference its tests hold.
+ */
+export function ambientFromSH(
+  coefficients: ArrayLike<number>,
+  nx: number,
+  ny: number,
+  nz: number,
+  out: Float32Array,
+): void {
+  const basis = [
+    0.282095 * BAND[0],
+    0.488603 * ny * BAND[1],
+    0.488603 * nz * BAND[1],
+    0.488603 * nx * BAND[1],
+    1.092548 * nx * ny * BAND[2],
+    1.092548 * ny * nz * BAND[2],
+    0.315392 * (3 * nz * nz - 1) * BAND[2],
+    1.092548 * nx * nz * BAND[2],
+    0.546274 * (nx * nx - ny * ny) * BAND[2],
+  ];
+  for (let c = 0; c < 3; c++) {
+    let sum = 0;
+    for (let k = 0; k < 9; k++) sum += (coefficients[k * 3 + c] as number) * (basis[k] as number);
+    out[c] = Math.max(sum, 0);
+  }
+}

package/src/render/anisotropicLobe.ts

@@ -39,3 +39,32 @@ export function anisotropicLobe(
   const d = x * x + y * y + nh * nh;
   return 1 / Math.max(d * d, 1e-8);
 }
+
+/** Three components in the lobe's frame: along the direction, across it, along the normal. */
+export type FrameVector = readonly [number, number, number];
+
+/**
+ * The physical form of the same lobe, `π · D · Vis · N·L`, for a surface whose highlight is GGX's
+ * own (`SurfaceMaterial.physicalSpecular`): the stretched distribution normalised as a BRDF's, and
+ * Smith's height-correlated masking stretched with it (Heitz 2014, as Filament writes it), Fresnel
+ * left to the caller. The half vector, the light and the view are each in the lobe's frame. At
+ * strength 0 it is isotropic GGX, the term skin's and the eye's highlights are.
+ */
+export function anisotropicPhysicalLobe(
+  half: FrameVector,
+  light: FrameVector,
+  view: FrameVector,
+  alphaT: number,
+  alphaB: number,
+): number {
+  const x = half[0] / alphaT;
+  const y = half[1] / alphaB;
+  const d = x * x + y * y + half[2] * half[2];
+  const distribution = 1 / (Math.PI * alphaT * alphaB * d * d);
+  const ndl = light[2];
+  const ndv = view[2];
+  const lambdaView = ndl * Math.hypot(alphaT * view[0], alphaB * view[1], ndv);
+  const lambdaLight = ndv * Math.hypot(alphaT * light[0], alphaB * light[1], ndl);
+  const visibility = 0.5 / Math.max(lambdaView + lambdaLight, 1e-5);
+  return Math.PI * distribution * visibility * ndl;
+}

package/src/render/areaLights.ts

@@ -88,8 +88,36 @@ export interface AreaLightSource {
    * every caster, not just the fixture.
    */
   shadowNear?: number;
+  /**
+   * How far the rectangle's light reaches, in metres from its centre: past it the light is zero,
+   * windowed down to it, so a clustered rectangle can be binned into the froxels it reaches and no
+   * others. **Read only where the rectangle is shaded through the froxel table** — the ones past
+   * `maxAreaLights` with `clusteredLights` on; the fixed four light everything they face, as they
+   * always have. Absent, it is where the rectangle's irradiance on its axis falls to a thousandth
+   * of a scene unit, and never inside the rectangle itself. Unreal's `AttenuationRadius`, in metres.
+   */
+  range?: number;
+  /**
+   * Barn doors: a flap hinged at each of the rectangle's four edges, standing this many degrees from
+   * its normal. 90, or absent, folds them flat and they hide nothing; smaller closes them, so the
+   * light narrows to the opening they leave — a rectangle at 50° throws a beam rather than filling
+   * its hemisphere. Unreal's `BarnDoorAngle`, whose default of 88° is nearly flat.
+   *
+   * What a fragment sees past the doors is the part of the rectangle no door's tip hides, one axis
+   * at a time, and the rectangle then shades as that smaller rectangle, its highlight included.
+   * Its shadow map is still baked from the whole rectangle's centre. **What it gives up**: each
+   * door is taken as endless along its hinge, so the two axes clip apart and the corner where two
+   * doors meet hides a square rather than the mitre two real flaps make. One-sided: a two-sided
+   * rectangle's back face has none.
+   */
+  barnDoorAngle?: number;
+  /** The barn doors' length in metres. Absent, 0.2: Unreal's default of 20 cm. */
+  barnDoorLength?: number;
 }
 
+/** The irradiance a derived `range` ends at, in scene units. See `AreaLightSource.range`. */
+export const AREA_RANGE_CUTOFF = 1e-3;
+
 /** The five arrays the shader declares, filled once a frame from whatever a caller supplied. */
 export interface AreaLightBuffer {
   count: number;
@@ -99,6 +127,13 @@ export interface AreaLightBuffer {
   readonly up: Float32Array;
   readonly sizes: Float32Array;
   readonly twoSided: Float32Array;
+  /** One a rectangle: how far its light reaches. See `AreaLightSource.range`. */
+  readonly ranges?: Float32Array;
+  /**
+   * Two a rectangle: the cosine of its barn doors' angle from its normal, then their length in
+   * metres — 0 and 0 for none. See `AreaLightSource.barnDoorAngle`.
+   */
+  readonly barnDoors?: Float32Array;
 }
 
 export function createAreaLightBuffer(capacity: number = MAX_AREA_LIGHTS): AreaLightBuffer {
@@ -110,9 +145,64 @@ export function createAreaLightBuffer(capacity: number = MAX_AREA_LIGHTS): AreaL
     up: new Float32Array(capacity * 3),
     sizes: new Float32Array(capacity * 2),
     twoSided: new Float32Array(capacity),
+    ranges: new Float32Array(capacity),
+    barnDoors: new Float32Array(capacity * 2),
   };
 }
 
+/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+export const DEFAULT_BARN_DOOR_LENGTH = 0.2;
+
+/**
+ * A rectangle's barn doors as the shader reads them, into `out[at]` and `out[at + 1]`: the cosine of
+ * their angle and their length. An angle not between 0 and 90 degrees, or a length not above zero,
+ * is no doors at all, written as 0 and 0 — which the shader reads as "nothing hidden".
+ */
+export function barnDoorsOf(light: AreaLightSource, out: Float32Array, at: number): void {
+  const angle = light.barnDoorAngle;
+  const length = light.barnDoorLength ?? DEFAULT_BARN_DOOR_LENGTH;
+  if (angle === undefined || !(angle >= 0 && angle < 90) || !(length > 0)) {
+    out[at] = 0;
+    out[at + 1] = 0;
+    return;
+  }
+  out[at] = Math.cos((angle * Math.PI) / 180);
+  out[at + 1] = length;
+}
+
+/**
+ * The fixed arm's half extents and barn doors, four a rectangle as `uAreaLightSize` holds them: the
+ * two half extents, then the doors' cosine and length. Into a target the binder owns, for the first
+ * `MAX_AREA_LIGHTS` alone, which are all the fixed arm reads.
+ */
+export function packAreaSizesAndDoors(lights: AreaLightBuffer, out: Float32Array): void {
+  const doors = lights.barnDoors;
+  for (let a = 0; a < MAX_AREA_LIGHTS; a++) {
+    out[a * 4] = lights.sizes[a * 2] ?? 0;
+    out[a * 4 + 1] = lights.sizes[a * 2 + 1] ?? 0;
+    out[a * 4 + 2] = doors?.[a * 2] ?? 0;
+    out[a * 4 + 3] = doors?.[a * 2 + 1] ?? 0;
+  }
+}
+
+/**
+ * How far a rectangle's light reaches when it names no range: where its irradiance on its own axis,
+ * `L · A / d²` for a rectangle of radiance `L` and area `A` seen from far, falls to
+ * `AREA_RANGE_CUTOFF`. Never less than the rectangle's own half-diagonal.
+ */
+export function areaRange(
+  r: number,
+  g: number,
+  b: number,
+  halfWidth: number,
+  halfHeight: number,
+): number {
+  const radiance = Math.max(r, g, b, 0);
+  const area = 4 * halfWidth * halfHeight;
+  const diagonal = Math.hypot(halfWidth, halfHeight);
+  return Math.max(Math.sqrt((radiance * area) / AREA_RANGE_CUTOFF), diagonal);
+}
+
 /**
  * Fill the buffer from a caller's list, normalising the axes and orthogonalising them.
  *
@@ -188,6 +278,13 @@ export function selectAreaLights(
     out.sizes[slot * 2] = Math.max(1e-4, light.halfWidth);
     out.sizes[slot * 2 + 1] = Math.max(1e-4, light.halfHeight);
     out.twoSided[slot] = light.twoSided === true ? 1 : 0;
+    if (out.ranges !== undefined) {
+      out.ranges[slot] =
+        light.range !== undefined && light.range > 0
+          ? light.range
+          : areaRange(light.r, light.g, light.b, light.halfWidth, light.halfHeight);
+    }
+    if (out.barnDoors !== undefined) barnDoorsOf(light, out.barnDoors, slot * 2);
   }
 
   return out;

package/src/render/backend/api.ts

@@ -1,5 +1,6 @@
 import type { Bounds } from '../../math/bounds.ts';
 import type { Vec3 } from '../../math/color.ts';
+import type { Camera } from '../camera.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { MeshData } from '../mesh.ts';
 import type { ProbeBakeOptions } from '../reflectionProbe.ts';
@@ -7,6 +8,8 @@ import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
 import type { SurfaceSource } from '../compressedSource.ts';
+import type { LightmapPage } from '../lightmap.ts';
+import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -275,6 +278,7 @@ export type RendererApi = Omit<
   | 'disposeCaustics'
   | 'createParticles'
   | 'drawParticles'
+  | 'drawDeviceParticles'
   | 'disposeParticles'
   | 'createWindStreaks'
   | 'drawWindStreaks'
@@ -300,6 +304,9 @@ export type RendererApi = Omit<
   | 'disposeSdfText'
   | 'createSurfaceTexture'
   | 'createSurfaceTextureArray'
+  | 'createLightmap'
+  | 'createSceneCapture'
+  | 'captureScene'
   | 'updateSurfaceTexture'
   | 'disposeSurfaceTexture'
   | 'setSurfaceTexture'
@@ -361,6 +368,43 @@ export type RendererApi = Omit<
     options?: Parameters<Renderer['createSurfaceTexture']>[1],
   ): SurfaceTextureHandle;
 
+  /**
+   * A baked lightmap page on the device, as the texture a `lightmapModel` material takes for its
+   * `modelMap`: two layers of four bytes a texel, the irradiance as an rgb9e5 word and the
+   * direction, which the lit stage decodes and filters itself, clamped at the page's edges, with no
+   * mip chain. A page whose irradiance arrives packed uploads where it lies. Disposed as any texture is, with
+   * `disposeSurfaceTexture`; `updateSurfaceTexture` refuses it, as it refuses any array. See
+   * `lightmap.ts` for what a surface does with it.
+   */
+  createLightmap(page: LightmapPage): SurfaceTextureHandle;
+
+  /**
+   * A texture the scene can be drawn into from a camera of the caller's (`captureScene`), which a
+   * material then shows like any image — most often as its `emissive`, for a screen in the world
+   * showing what a camera elsewhere sees. `width` and `height` in pixels, 1 to 4096. It holds
+   * radiance, at the colour format a probe takes: half floats under `hdrScene`, bytes otherwise.
+   * Disposed as any texture is; `updateSurfaceTexture` refuses it. See `sceneCapture.ts`.
+   */
+  createSceneCapture(width: number, height: number): SurfaceTextureHandle;
+
+  /**
+   * Draw the scene into a capture from `camera`, at the moment a caller says, usually once a frame
+   * before the frame's own world. `draw` is handed the camera, its matrices updated for the
+   * capture's shape, and submits the scene exactly as it would to the screen — `bindMeshPass`,
+   * `drawMesh` and the rest; `bindMeshPass` the frame's own camera again afterwards. The output
+   * transform is held off, so a screen showing it is graded once, with the frame.
+   *
+   * **The mesh pass alone**, as a probe bake is: what a scene draws after its world is in the
+   * capture only if `draw` draws it, and no temporal resolve or effect after the world runs on it.
+   * Returns whether it drew: false for a texture that is not a capture.
+   */
+  captureScene(
+    capture: SurfaceTextureHandle,
+    camera: Camera,
+    clearColor: Vec3,
+    draw: (camera: Camera) => void,
+  ): boolean;
+
   /**
    * Replace a texture's pixels, keeping the GPU object and its sampler state.
    *
@@ -708,8 +752,10 @@ export type RendererApi = Omit<
    */
   createParticles(
     capacity: number,
-    options: Omit<Parameters<Renderer['createParticles']>[1], 'reuse'> & {
+    options: Omit<Parameters<Renderer['createParticles']>[1], 'reuse' | 'texture'> & {
       readonly reuse?: ParticleHandle;
+      /** A `'sprite'`'s image. Re-typed to the handle for `reuse`'s reason. */
+      readonly texture?: SurfaceTextureHandle;
     },
   ): ParticleHandle;
 
@@ -722,6 +768,20 @@ export type RendererApi = Omit<
     timeSeconds: number,
   ): void;
 
+  /**
+   * Draw a pool's particles from a buffer a caller's own compute wrote (`registerCompute`), where
+   * they lie: the pool's material, blend, flipbook and fades, its instance stream the caller's
+   * buffer. WebGPU only; WebGL2 says so once and draws nothing. Not sorted. See `DeviceParticles`
+   * for the layout.
+   */
+  drawDeviceParticles(
+    batch: ParticleHandle,
+    particles: DeviceParticles,
+    camera: Parameters<Renderer['drawParticles']>[2],
+    env: Parameters<Renderer['drawParticles']>[3],
+    timeSeconds: number,
+  ): void;
+
   /** Release a particle pool. */
   disposeParticles(batch: ParticleHandle): void;
 

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

@@ -34,6 +34,8 @@ export class InstancedBatch {
   private readonly buffer: WebGLBuffer;
   private readonly vao: WebGLVertexArrayObject;
   private readonly staging: Float32Array;
+  /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
+  private keptRegioned: MeshInstances | null = null;
   private readonly kept: {
     readonly buffer: WebGLBuffer;
     readonly vao: WebGLVertexArrayObject;
@@ -80,9 +82,17 @@ export class InstancedBatch {
   drawCulled(gl: WebGL2RenderingContext, data: MeshInstances, frustum: FrustumPlanes): number {
     const kept = this.kept;
     if (kept === null) return 0;
-    const count = cullInstances(data, this.mesh.bounds, frustum, kept.instances);
+    /* A lightmapped batch's survivors keep their regions, in a copy that carries them. */
+    const into =
+      data.lightmapRegions === undefined
+        ? kept.instances
+        : (this.keptRegioned ??= {
+            ...createMeshInstances(this.capacity),
+            lightmapRegions: new Float32Array(this.capacity * 4),
+          });
+    const count = cullInstances(data, this.mesh.bounds, frustum, into);
     if (count === 0) return 0;
-    packInstances(kept.instances, this.staging);
+    packInstances(into, this.staging);
     gl.bindBuffer(gl.ARRAY_BUFFER, kept.buffer);
     gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
     this.mesh.drawInstancesThrough(gl, kept.vao, count);