@driftengine/core 4.8.4 → 4.8.6

package/dist/index.d.ts

@@ -145,12 +145,20 @@ export { placeCascade } from './render/gi/globalField.ts';
 export type { ReflectionOptions, ReflectiveSample } from './render/gi/reflection.ts';
 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';
 export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHandle, FlockHandle, IncrementalMeshHandle, LineHandle, MeshHandle, MeshOptions, RenderBackend, RendererApi, ParticleHandle, PlumeHandle, ScatterHandle, InstancedHandle, SdfTextHandle, SurfaceTextureHandle, TextHandle, WaterHandle, WindStreakHandle, } from './render/backend/api.ts';
 export type { ClothBindingData } from './render/clothBindingData.ts';
-export { anisotropicModel, eyeModel, hairModel, skinModel } from './render/surfaceModel.ts';
-export type { AnisotropicModel, EyeModel, HairModel, SkinModel, SurfaceModel, SurfaceModelKind, } 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';
+export { WHOLE_PAGE } from './render/lightmap.ts';
+export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
 export { createSkinnedCloth } from './render/skinnedClothRun.ts';
 export type { SkinnedClothSolver } from './render/skinnedClothRun.ts';
 /**

package/dist/index.js

@@ -209,13 +209,23 @@ export { placeCascade } from './render/gi/globalField.js';
  * take the identity, bend it, hand it back — and because it is what the placeholder is.
  */
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.js';
+/**
+ * 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.js';
 export { probeDevice } from './render/backend/probe.js';
 /*
  * A material's shading model, for what the standard one is not: brushed metal, hair, skin, an eye.
  * 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.js';
+export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.js';
+/*
+ * 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.js';
 /*
  * 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.

package/dist/render/ambientHarmonics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare const AMBIENT_SH_VALUES = 27;
+/** Floats the lit stage's `uAmbientSH` holds: the coefficients, and whether they are on. */
+export declare 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 declare function packAmbientSH(coefficients: ArrayLike<number> | null, out: Float32Array): void;
+/**
+ * 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 declare function ambientFromSH(coefficients: ArrayLike<number>, nx: number, ny: number, nz: number, out: Float32Array): void;

package/dist/render/ambientHarmonics.js

@@ -0,0 +1,80 @@
+/**
+ * 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, out) {
+    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];
+        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];
+/**
+ * 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, nx, ny, nz, out) {
+    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] * basis[k];
+        out[c] = Math.max(sum, 0);
+    }
+}

package/dist/render/areaLights.d.ts

@@ -86,7 +86,18 @@ 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;
 }
+/** The irradiance a derived `range` ends at, in scene units. See `AreaLightSource.range`. */
+export declare const AREA_RANGE_CUTOFF = 0.001;
 /** The five arrays the shader declares, filled once a frame from whatever a caller supplied. */
 export interface AreaLightBuffer {
     count: number;
@@ -96,8 +107,16 @@ 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;
 }
 export declare function createAreaLightBuffer(capacity?: number): AreaLightBuffer;
+/**
+ * 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 declare function areaRange(r: number, g: number, b: number, halfWidth: number, halfHeight: number): number;
 /**
  * Fill the buffer from a caller's list, normalising the axes and orthogonalising them.
  *

package/dist/render/areaLights.js

@@ -8,6 +8,8 @@
  * iteration of the loop, exactly as `MAX_POINT_LIGHTS` is.
  */
 export const MAX_AREA_LIGHTS = 4;
+/** The irradiance a derived `range` ends at, in scene units. See `AreaLightSource.range`. */
+export const AREA_RANGE_CUTOFF = 1e-3;
 export function createAreaLightBuffer(capacity = MAX_AREA_LIGHTS) {
     return {
         count: 0,
@@ -17,8 +19,20 @@ export function createAreaLightBuffer(capacity = MAX_AREA_LIGHTS) {
         up: new Float32Array(capacity * 3),
         sizes: new Float32Array(capacity * 2),
         twoSided: new Float32Array(capacity),
+        ranges: new Float32Array(capacity),
     };
 }
+/**
+ * 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, g, b, halfWidth, halfHeight) {
+    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.
  *
@@ -86,6 +100,12 @@ export function selectAreaLights(lights, out) {
         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);
+        }
     }
     return out;
 }

package/dist/render/backend/api.d.ts

@@ -7,6 +7,7 @@ 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 { ClothBindingData } from '../clothBindingData.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -186,7 +187,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -229,6 +230,14 @@ export type RendererApi = Omit<{
      * `updateSurfaceTexture` refuses an array.
      */
     createSurfaceTextureArray(sources: readonly SurfaceSource[], 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 half floats, the irradiance and the direction, filtered linearly and
+     * clamped at its edges, with no mip chain. 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;
     /**
      * Replace a texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -428,8 +437,10 @@ export type RendererApi = Omit<{
      * have shared one already do. WebGL2 still needs telling, and still checks that the two
      * materials match.
      */
-    createParticles(capacity: number, options: Omit<Parameters<Renderer['createParticles']>[1], 'reuse'> & {
+    createParticles(capacity: number, 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;
     /** Draw a pool's live particles, after the opaque scene. */
     drawParticles(batch: ParticleHandle, data: Parameters<Renderer['drawParticles']>[1], camera: Parameters<Renderer['drawParticles']>[2], env: Parameters<Renderer['drawParticles']>[3], timeSeconds: number): void;

package/dist/render/backend/webgl2/instanced.d.ts

@@ -26,6 +26,8 @@ export declare class InstancedBatch {
     private readonly buffer;
     private readonly vao;
     private readonly staging;
+    /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
+    private keptRegioned;
     private readonly kept;
     constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean);
     upload(gl: WebGL2RenderingContext, data: MeshInstances): void;

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

@@ -25,6 +25,8 @@ export class InstancedBatch {
     buffer;
     vao;
     staging;
+    /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
+    keptRegioned = null;
     kept;
     constructor(gl, mesh, capacity, cull = false) {
         this.mesh = mesh;
@@ -67,10 +69,17 @@ export class InstancedBatch {
         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);

package/dist/render/backend/webgl2/renderer.d.ts

@@ -13,6 +13,7 @@ import type { PassDefinition, PassHandle } from '../../pass.ts';
 import type { Vec3 } from '../../../math/color.ts';
 import { GpuTimer } from '../../gpuTimer.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
+import { type BloomResponse } from '../../bloomChain.ts';
 import { LightField } from '../../driftLight/lightField.ts';
 import type { LightFieldOptions, LightFieldSource } from '../../driftLight/lightField.ts';
 import type { DenseLightVolume } from '../../driftLight/denseField.ts';
@@ -33,6 +34,7 @@ import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts
  * Beyond this the velocity is shortened and the direction kept.
  */
 import type { RendererApi } from '../api.ts';
+import type { LightmapPage } from '../../lightmap.ts';
 import type { ClothBindingData } from '../../clothBindingData.ts';
 import { GlClothBinding, GlClothParticles } from './clothTextures.ts';
 import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
@@ -208,6 +210,12 @@ export interface Environment extends Atmosphere {
     lightIesAxes: Float32Array;
     /** One per active light: a tile of the cookie atlas, or −1 for none. */
     lightCookies: Float32Array;
+    /**
+     * One per active light: the lighting channels it lights, a mask from 1 to 255. Absent, short, or
+     * a light at 1 is the default channel every surface is on too. See `PointLightSet.lightChannels`
+     * and `SurfaceMaterial.lightChannels`.
+     */
+    lightChannels?: Float32Array;
     /**
      * The rectangular emitters this frame, or null for none.
      *
@@ -994,6 +1002,23 @@ export declare class WebGL2Renderer implements RendererApi {
     private motionBlurScale;
     /** How much of the bloom ceiling this frame takes. See `setBloom`. */
     private bloomScale;
+    /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
+    private readonly ambientSH;
+    /** Scratch for a sprite's depth conversion, so a particle draw allocates nothing. */
+    private readonly spriteInverseProjection;
+    /** Said once: a sprite asked for a soft edge where no depth copy could be had. */
+    private warnedSpriteDepth;
+    /** Said once: more rectangles than the fixed arm shades, and no froxel table for the rest. */
+    private warnedAreaOverflow;
+    /**
+     * `uEnvironmentDials` as it stands: which chain the probe holds, the reflectivity, the gain. One
+     * vector on the device, so written whole, and kept here so a setter moving one keeps the others.
+     */
+    private readonly environmentDials;
+    /** `uEmission` as it stands: the emissive gain and the night factor. */
+    private readonly emission;
+    /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
+    private readonly bloomResponse;
     /** In scene units, once `setBloom` has moved it; null reads the profile's. */
     private bloomThresholdSet;
     /**
@@ -1806,6 +1831,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * refusal names the first that is not.
      */
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): SurfaceTexture;
+    /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
+    createLightmap(page: LightmapPage): SurfaceTexture;
     /**
      * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -1948,6 +1975,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
      * leaves geometry that did not exactly as it is.
      */
+    /**
+     * The ambient the following draws take, as nine spherical-harmonic coefficients of incoming
+     * radiance — red, green and blue of each, twenty-seven numbers — or `null` for the frame's own:
+     * the sky's gradient, or the probes'. See `ambientHarmonics.ts` for the basis and the axes.
+     *
+     * **For a thing lit by where it stands**: a consumer sampling a stage's baked volume of indirect
+     * light at a character every frame sets the result around that character's draws, and the
+     * character takes the light of its spot rather than the frame's. It replaces the diffuse ambient
+     * only — a glossy surface still reflects the probes — and it is pass state like the material,
+     * which `bindMeshPass` clears, so a mirror or a probe bake drawn after does not inherit it.
+     */
     /**
      * How much of the environment the following draws mirror, 0 to 1.
      *
@@ -1958,6 +1996,7 @@ export declare class WebGL2Renderer implements RendererApi {
      * Defaults to zero and bindMeshPass restores it, so a scene that never calls this looks
      * exactly as it did.
      */
+    setAmbientSH(coefficients: ArrayLike<number> | null): void;
     setSurfaceReflectivity(amount: number): void;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
@@ -2014,6 +2053,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * reads, drew what was asked.
      */
     private writeFlatFloat;
+    /** A vector of material state, two to four floats, into every flat program. */
+    private writeFlatVector;
     /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
     private writeFlatInt;
     /**
@@ -2330,6 +2371,13 @@ export declare class WebGL2Renderer implements RendererApi {
      * whole milestone from a buffer nothing had ever written.
      */
     drawParticles(batch: ParticleBatch, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /**
+     * A sprite's two fades and the depth copy the soft one reads. The copy is the frame's opaque
+     * depth, so it is taken only in the frame's own picture: in a mirror or a probe's face it would
+     * be another view's, and the edge stays hard there. Without a scene target there is no copy at
+     * all, and the renderer says so once rather than drawing a hard edge that was asked to be soft.
+     */
+    private bindSpriteFades;
     /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
     createBolts(segmentCapacity: number, label?: string): BoltBatch;
     /**
@@ -3039,8 +3087,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * and wrong for a day whose exposure spans 2.5 to 14: a courtyard blooming at noon, or candles
      * never blooming at night. A caller whose exposure moves passes what it wants on screen over the
      * exposure. Omitted leaves it where it was, so a caller that never passes one keeps the profile's.
+     *
+     * **`response` is how a colour comes in past the threshold and what colour each octave of the
+     * halo takes** — a ramp in place of the subtraction, and a tint a level — held until moved like
+     * the threshold; `null` goes back to the subtraction and white. See `BloomResponse`: it is what
+     * matches a stage built for another engine's bloom, whose tints are how a strength past 1 is
+     * asked for.
      */
-    setBloom(scale: number, threshold?: number): void;
+    setBloom(scale: number, threshold?: number, response?: BloomResponse | null): void;
     /**
      * How thick the air is, this frame: a global participating medium filling the whole frustum.
      *
@@ -3550,6 +3604,25 @@ export declare class WebGL2Renderer implements RendererApi {
         readonly height: number;
         readonly data: Float32Array;
     }, options?: ProbeBakeOptions): boolean;
+    /**
+     * One layer of the declared probe grid from an image, the way `setEnvironmentImage` fills a
+     * single probe: the same equirectangular image of linear RGB floats, projected onto the capture
+     * cube and prefiltered into that layer, the others left as they are. Returns false — and says
+     * why — where there is no probe, no grid, or no such layer.
+     *
+     * **What it is for**: a scene baked somewhere else. Another engine's reflection captures are
+     * images taken where each one stands; a consumer fits them to a lattice — for each point, the
+     * capture whose reach holds it — and hands each point its image here, where `bakeProbe` would
+     * have drawn this engine's own world into it.
+     *
+     * `options.irradiance` decides, at grid scope as a bake's does, whether the grid also lights the
+     * scene's diffuse ambient. A grid that crossfades writes the set being swept, as a bake does.
+     */
+    setProbeLayerImage(layer: number, image: {
+        readonly width: number;
+        readonly height: number;
+        readonly data: Float32Array;
+    }, options?: ProbeBakeOptions): boolean;
     /**
      * Draw a volume of light: a beam from a lamp, a shaft through a window, the cone under a
      * street light.