@driftengine/core 4.8.5 → 4.8.7

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

@@ -63,7 +63,9 @@ import {
   clusteredMode,
   createClusterLightSet,
   createClusterTable,
+  clusteredLightTotal,
   fillClusterLightSet,
+  lightChannelsOf,
 } from '../../clusteredLights.ts';
 import type {
   PassContext,
@@ -88,7 +90,14 @@ import { FILM_FRAG, FILM_VERT } from '../../shaders/film.ts';
 import { SceneTarget } from '../../sceneTarget.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
 import { FILM_LOOK_WITHOUT_COMPOSITE } from '../../shaders/filmLook.ts';
-import { bloomProfileWarning, bloomThresholdOf } from '../../bloomChain.ts';
+import { AMBIENT_SH_FLOATS, packAmbientSH } from '../../ambientHarmonics.ts';
+import {
+  bloomProfileWarning,
+  bloomThresholdOf,
+  defaultBloomResponse,
+  resolveBloomResponse,
+  type BloomResponse,
+} from '../../bloomChain.ts';
 import {
   createEmptyTexture2D,
   createEmptyTexture2DArray,
@@ -127,9 +136,21 @@ import {
   MORPH_DELTA_TEXTURE_UNIT,
   SKIN_PALETTE_TEXTURE_UNIT,
 } from '../../lightBudget.ts';
-import { MODEL_PARAM_FLOATS, eyeAxisInWorld, packModel } from '../../surfaceModel.ts';
+import {
+  MODEL_PARAM_FLOATS,
+  eyeAxisInWorld,
+  packModel,
+  skinProfileDistance,
+} from '../../surfaceModel.ts';
 import type { SurfaceModelKind } from '../../surfaceModel.ts';
-import { modelBound, skinHalfBound } from '../../shaders/flat/models.ts';
+import { lightmapRegionsBound, modelBound, skinHalfBound } from '../../shaders/flat/models.ts';
+import {
+  lightmapTexels,
+  warnRegionsWithoutPage,
+  warnUnpagedLightmap,
+  withLightmapUvs,
+} from '../../lightmap.ts';
+import type { LightmapPage } from '../../lightmap.ts';
 import type { SkinHalf } from '../../shaders/flat/models.ts';
 import { GlSkinScatter } from './skinScatter.ts';
 import {
@@ -224,6 +245,7 @@ import {
   bindAreaLights,
   bindAreaShadows,
   openCones,
+  PARTICLE_DEPTH_UNIT,
 } from '../../lightBudget.ts';
 import { resolveRenderQuality } from '../../renderQuality.ts';
 import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts';
@@ -234,6 +256,8 @@ import type { IncrementalMesh } from '../../mesh.ts';
 import type { MeshData } from '../../mesh.ts';
 import type { MeshOptions } from '../api.ts';
 import { SurfaceTexture } from '../../surfaceTexture.ts';
+import { sceneCaptureTexels } from '../../sceneCapture.ts';
+import { GlSceneCaptureTarget } from './sceneCaptureTarget.ts';
 import { glCompressedFormats } from '../../glCompressed.ts';
 import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
@@ -257,7 +281,7 @@ import { PlanarReflection } from '../../planarReflection.ts';
 import { InstancedMesh } from '../../instancedMesh.ts';
 import { ParticleBatch } from '../../particleBatch.ts';
 import type { ParticleBatchOptions } from '../../particleBatch.ts';
-import type { ParticleInstances } from '../../particlePool.ts';
+import type { DeviceParticles, ParticleInstances } from '../../particlePool.ts';
 import { BoltBatch } from '../../boltBatch.ts';
 import type { BoltSegments } from '../../boltPool.ts';
 import { LineBatch } from '../../lineBatch.ts';
@@ -418,6 +442,11 @@ export interface Environment extends Atmosphere {
   lightDirections: Float32Array;
   /** Two per active light: the cosine of the inner cone angle, then of the outer. */
   lightConeCos: Float32Array;
+  /**
+   * One per active light: its own falloff exponent, or 0 for the frame's. Optional: absent is 0 for
+   * every light. See `PointLightSource.falloffExponent`.
+   */
+  lightFalloffExponents?: Float32Array;
   /** One per active light: a row of the photometric atlas, or −1 for none. */
   lightIesProfiles: Float32Array;
   /**
@@ -430,6 +459,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.
    *
@@ -508,6 +543,8 @@ export function createEnvironment(overrides: Partial<Environment> = {}): Environ
     lightIesAxes: new Float32Array(MAX_POINT_LIGHTS * 3),
     /* −1, because tile 0 is a real cookie and no light here has asked for one. */
     lightCookies: new Float32Array(MAX_POINT_LIGHTS).fill(-1),
+    /* Channel 1, the default every surface is on, so every light lights everything. */
+    lightChannels: new Float32Array(MAX_POINT_LIGHTS).fill(1),
     /* None, so the shader's loop breaks before it reads anything. */
     areaLights: null,
     activeLightWorldIndices: new Int32Array(MAX_POINT_LIGHTS).fill(-1),
@@ -618,6 +655,9 @@ export interface SkyColors {
 export { MAX_DEPTH_LAYER } from '../../depthConvention.ts';
 
 /** The identity tint, handed back after any draw that asked for one. See `drawMesh`. */
+/** The far corner of no highlight box: what an environment that names none reads. */
+const NO_HIGHLIGHT: readonly number[] = [0, 0, 0];
+
 const WHITE_TINT = new Float32Array([1, 1, 1]);
 /** The lit stage's clip plane when there is no mirror: zero, which clips nothing. */
 const NO_CLIP_PLANE = new Float32Array(4);
@@ -1364,6 +1404,23 @@ export class WebGL2Renderer implements RendererApi {
   private motionBlurScale = 1;
   /** How much of the bloom ceiling this frame takes. See `setBloom`. */
   private bloomScale = 1;
+  /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
+  private readonly ambientSH = new Float32Array(AMBIENT_SH_FLOATS);
+  /** Scratch for a sprite's depth conversion, so a particle draw allocates nothing. */
+  private readonly spriteInverseProjection = mat4.create();
+  /** Said once: a sprite asked for a soft edge where no depth copy could be had. */
+  private warnedSpriteDepth = false;
+  /** Said once: more rectangles than the fixed arm shades, and no froxel table for the rest. */
+  private warnedAreaOverflow = false;
+  /**
+   * `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 = new Float32Array(3);
+  /** `uEmission` as it stands: the emissive gain and the night factor. */
+  private readonly emission = new Float32Array([1, 0]);
+  /** The ramp and each level's tint, as `resolveBloomResponse` writes them; the subtraction and white. */
+  private readonly bloomResponse = defaultBloomResponse();
   /** In scene units, once `setBloom` has moved it; null reads the profile's. */
   private bloomThresholdSet: number | null = null;
   /**
@@ -1576,6 +1633,15 @@ export class WebGL2Renderer implements RendererApi {
   private warnedEnvironmentAmbient = false;
   /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
   private probePassActive = false;
+  /**
+   * Whether a scene capture is being drawn (`captureScene`): an off-screen pass like a bake, so the
+   * frame's own view, its refraction copy and skin's spread are left alone, but lit as the frame is.
+   */
+  private capturePassActive = false;
+  /** Each capture's framebuffer, beside the texture a material binds. See `createSceneCapture`. */
+  private readonly captureTargets = new WeakMap<SurfaceTexture, GlSceneCaptureTarget>();
+  /** Said once, where a driver refuses to draw into a capture. */
+  private warnedCapture = false;
   /** Whether the bake under way lights its faces by the grid. `ProbeBakeOptions.bounce`. */
   private probeBounce = false;
   /** The clip-control extension, or null where this context does not offer it. */
@@ -1647,12 +1713,14 @@ export class WebGL2Renderer implements RendererApi {
    * the camera's matrix unchanged and multiplies nothing.
    */
   private viewProjFor(camera: { readonly viewProjection: ReadonlyMat4 }): ReadonlyMat4 {
-    const scene = this.probePassActive
-      ? (cubeFaceProjection(
-          this.cubeFaceViewProj,
-          this.sceneMatrix(camera.viewProjection) as unknown as ArrayLike<number>,
-        ) as unknown as ReadonlyMat4)
-      : this.sceneMatrix(camera.viewProjection);
+    /* A capture's rows are flipped as a probe face's are, so it reads as an image does. */
+    const scene =
+      this.probePassActive || this.capturePassActive
+        ? (cubeFaceProjection(
+            this.cubeFaceViewProj,
+            this.sceneMatrix(camera.viewProjection) as unknown as ArrayLike<number>,
+          ) as unknown as ReadonlyMat4)
+        : this.sceneMatrix(camera.viewProjection);
     /*
      * **The jitter goes on here and nowhere else.** This is the one funnel every geometry upload
      * passes through, so one line covers the mesh passes, the sky, the water and the effects
@@ -2460,9 +2528,7 @@ export class WebGL2Renderer implements RendererApi {
     gl.activeTexture(gl.TEXTURE0 + FIXTURE_ATLAS_TEXTURE_UNIT);
     gl.bindTexture(gl.TEXTURE_2D, this.fixtureTexture);
     gl.uniform1i(u['uFixtureAtlas'] ?? null, FIXTURE_ATLAS_TEXTURE_UNIT);
-    gl.uniform1f(u['uIesAtlasRows'] ?? null, this.iesRows);
-    gl.uniform1f(u['uIesPlaneCount'] ?? null, this.iesPlanes);
-    gl.uniform1f(u['uCookieTiles'] ?? null, this.cookieTiles);
+    gl.uniform3f(u['uFixtureShape'] ?? null, this.iesRows, this.iesPlanes, this.cookieTiles);
     gl.activeTexture(gl.TEXTURE0);
   }
 
@@ -2516,7 +2582,8 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniformMatrix4fv(u['uView'] ?? null, false, camera.view);
 
     this.clusterTable ??= createClusterTable();
-    const lights = fillClusterLightSet(env, this.clusterLights);
+    /* The rectangles past the fixed arm's go into the table. See `ClusterLightSet.areas`. */
+    const lights = fillClusterLightSet(env, this.clusterLights, this.shadedAreaLights);
     /* A slot is read only under `POINT_SHADOWS`; see `lightHasFixture`. */
     const shadowSlots = this.quality.pointShadows ? this.lightBudget.maxLights : 0;
     buildLightClusters(
@@ -2536,7 +2603,10 @@ export class WebGL2Renderer implements RendererApi {
        */
       shadowSlots,
     );
-    gl.uniform1i(u['uClustered'] ?? null, clusteredMode(lights, lights.count, shadowSlots));
+    gl.uniform1i(
+      u['uClustered'] ?? null,
+      clusteredMode(lights, clusteredLightTotal(lights), shadowSlots),
+    );
     gl.texSubImage2D(
       gl.TEXTURE_2D,
       0,
@@ -3252,8 +3322,9 @@ export class WebGL2Renderer implements RendererApi {
      * one. Measured on hardware: WebGL2 drew neither the bend nor the bulge while WebGPU drew
      * both, which is the two-backend comparison doing exactly what it is for.
      */
-    this.warmVariants(data);
-    return new Mesh(this.gl, data, options.dynamic === true);
+    const drawn = withLightmapUvs(data);
+    this.warmVariants(drawn);
+    return new Mesh(this.gl, drawn, options.dynamic === true);
   }
 
   /**
@@ -3266,8 +3337,9 @@ export class WebGL2Renderer implements RendererApi {
    * the signal that it was abandoned.
    */
   createMeshIncremental(data: MeshData, options: MeshOptions = {}): IncrementalMesh {
-    this.warmVariants(data);
-    const { mesh, upload } = createMeshIncremental(this.gl, data, options.dynamic === true);
+    const drawn = withLightmapUvs(data);
+    this.warmVariants(drawn);
+    const { mesh, upload } = createMeshIncremental(this.gl, drawn, options.dynamic === true);
     return {
       mesh,
       upload: {
@@ -3445,6 +3517,97 @@ export class WebGL2Renderer implements RendererApi {
     return new SurfaceTexture(this.gl, sources, options, this.compressedFormats);
   }
 
+  /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
+  createLightmap(page: LightmapPage): SurfaceTexture {
+    return new SurfaceTexture(this.gl, lightmapTexels(page), { wrap: 'clamp', mipmap: false });
+  }
+
+  /**
+   * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+   * `sceneCapture.ts`. Half floats where the frame keeps range, as a probe does.
+   */
+  createSceneCapture(width: number, height: number): SurfaceTexture {
+    const float = this.quality.hdrScene && this.gl.getExtension('EXT_color_buffer_float') !== null;
+    const texture = new SurfaceTexture(this.gl, sceneCaptureTexels(width, height, float), {
+      wrap: 'clamp',
+      mipmap: false,
+    });
+    this.captureTargets.set(
+      texture,
+      new GlSceneCaptureTarget(
+        this.gl,
+        texture,
+        width,
+        height,
+        this.sceneTarget?.sampleCount ?? 1,
+        float,
+      ),
+    );
+    return texture;
+  }
+
+  /**
+   * Draw the scene into a capture from `camera`: `draw` is handed the camera, its matrices updated
+   * for the capture's shape, and submits the scene as it would to the screen. See `RendererApi`.
+   *
+   * **Radiance, as a probe bake stores it**: the output transform and exposure are held off for the
+   * pass, so the frame grades a screen showing it once. No temporal jitter, which a capture has no
+   * resolve to undo. Returns whether it drew: false for a texture that is not a capture, or one the
+   * driver will not draw into.
+   */
+  captureScene(
+    capture: SurfaceTexture,
+    camera: Camera,
+    clearColor: Vec3,
+    draw: (camera: Camera) => void,
+  ): boolean {
+    if (this.contextLost) return false;
+    const target = this.captureTargets.get(capture);
+    if (target === undefined) return false;
+    if (!target.usable) {
+      if (!this.warnedCapture) {
+        this.warnedCapture = true;
+        console.warn(
+          'Renderer: this driver will not draw into a scene capture, so it keeps its clear. ' +
+            'Nothing else is affected.',
+        );
+      }
+      return false;
+    }
+    camera.updateMatrices(target.width / target.height);
+    const { gl } = this;
+    const jittering = this.temporalJittering;
+    this.temporalJittering = false;
+    this.capturePassActive = true;
+    this.useFlatProgram();
+    gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, 0);
+    gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, 1);
+    this.materials.dirty();
+    target.begin(gl, clearColor, this.depthClear);
+    /*
+     * **Rows flipped, as a probe face's are.** A GL framebuffer's first row is its bottom and an
+     * image's is its top, so a capture drawn upright would be shown upside down by every material
+     * reading it as the image it is; `viewProjFor` negates clip y for the pass, and negating one axis
+     * reverses every triangle's winding, which the front face follows. WebGPU's rows already run
+     * the image's way.
+     */
+    gl.frontFace(gl.CW);
+    try {
+      draw(camera);
+    } finally {
+      target.end(gl);
+      gl.frontFace(gl.CCW);
+      this.useFlatProgram();
+      gl.uniform1i(this.flatUniforms['uOutputTransform'] ?? null, this.gradeCode());
+      gl.uniform1f(this.flatUniforms['uOutputExposure'] ?? null, this.gradeExposure());
+      this.materials.dirty();
+      this.capturePassActive = false;
+      this.temporalJittering = jittering;
+      this.restoreViewport();
+    }
+    return true;
+  }
+
   /**
    * Replace a surface texture's pixels, keeping the GPU object and its sampler state.
    *
@@ -3465,6 +3628,8 @@ export class WebGL2Renderer implements RendererApi {
   disposeSurfaceTexture(texture: SurfaceTexture): void {
     if (this.contextLost) return;
     texture.dispose(this.gl);
+    this.captureTargets.get(texture)?.dispose(this.gl);
+    this.captureTargets.delete(texture);
   }
 
   /**
@@ -3522,7 +3687,7 @@ export class WebGL2Renderer implements RendererApi {
     const label = `flat.${variant}.${kind}.${half}`;
     const program = compileProgram(
       gl,
-      litVertexOf(variant),
+      modelVertexOf(variant, kind),
       skinHalfBound(modelBound(this.flatFragSource, kind), half),
       label,
     );
@@ -3693,12 +3858,13 @@ export class WebGL2Renderer implements RendererApi {
     this.currentMaterial = material;
     /* What the blur spreads this skin by: the last material to name a profile says. */
     const model = material?.model;
+    warnUnpagedLightmap(model, material?.modelMap);
     if (model?.kind === 'skin' && this.skinScatter !== null) {
       this.skinScatter.setProfile(
         model.profile,
-        model.scatterColor[0] * model.radius,
-        model.scatterColor[1] * model.radius,
-        model.scatterColor[2] * model.radius,
+        skinProfileDistance(model, 0),
+        skinProfileDistance(model, 1),
+        skinProfileDistance(model, 2),
       );
     }
     /*
@@ -3738,7 +3904,8 @@ export class WebGL2Renderer implements RendererApi {
     v[0] = material?.cutout ?? 0;
     v[1] = CUTOUT_RESOLVE_CODE[this.cutoutResolveNow(material, translucent)];
     v[2] = this.cutoutFrame;
-    v[3] = 0;
+    /* The material's lighting channels, which the lamps' are compared with. See `uCutout`. */
+    v[3] = lightChannelsOf(material?.lightChannels);
     return v;
   }
 
@@ -3845,7 +4012,14 @@ export class WebGL2Renderer implements RendererApi {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     if (modelMap !== null) modelMap.bind(gl, MODEL_MAP_TEXTURE_UNIT);
     gl.uniform1i(u['uModelMap'] ?? null, MODEL_MAP_TEXTURE_UNIT);
-    packModel(material?.model ?? null, modelMap !== null, this.modelParams);
+    packModel(
+      material?.model ?? null,
+      modelMap !== null,
+      this.modelParams,
+      material?.physicalSpecular === true,
+    );
+    /* The first physical highlight asked for is when the lit programs start carrying one. */
+    if (material?.physicalSpecular === true) this.askLit('PHYSICAL_SPECULAR');
     gl.uniform4fv(u['uModelParams'] ?? null, this.modelParams);
 
     /* The albedo's effects table, or the stand-in the shader reads as none. Before the early
@@ -3866,6 +4040,8 @@ export class WebGL2Renderer implements RendererApi {
       gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
       this.materialFlags[0] = 0;
       gl.uniform4iv(u['uMaterialFlags'] ?? null, this.materialFlags);
+      /* No image to cut, and the channels all the same: a material needs no albedo to name them. */
+      gl.uniform4f(u['uCutout'] ?? null, 0, 0, 0, lightChannelsOf(material?.lightChannels));
       return;
     }
     albedo.bind(gl, SURFACE_TEXTURE_UNIT);
@@ -3906,17 +4082,27 @@ export class WebGL2Renderer implements RendererApi {
   }
 
   /**
-   * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+   * 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.
    *
-   * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
-   * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
-   * This stays as the override for the case that has no answer to state: an imported model
-   * arrives with no grain information at all, and a caller drawing one decides for it.
-   *
-   * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
-   * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
-   * leaves geometry that did not exactly as it is.
+   * **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.
    */
+  setAmbientSH(coefficients: ArrayLike<number> | null): void {
+    if (this.contextLost) return;
+    packAmbientSH(coefficients, this.ambientSH);
+    this.materials.dirty();
+    for (const target of this.flatTargets) {
+      this.gl.useProgram(target.program);
+      this.gl.uniform4fv(target.uniforms['uAmbientSH[0]'] ?? null, this.ambientSH);
+    }
+    this.useFlatProgram();
+  }
+
   /**
    * How much of the environment the following draws mirror, 0 to 1.
    *
@@ -3930,7 +4116,8 @@ export class WebGL2Renderer implements RendererApi {
   setSurfaceReflectivity(amount: number): void {
     if (this.contextLost) return;
     this.materials.dirty();
-    this.writeFlatFloat('uReflectivity', Math.min(1, Math.max(0, amount)));
+    this.environmentDials[1] = Math.min(1, Math.max(0, amount));
+    this.writeFlatVector('uEnvironmentDials', this.environmentDials);
   }
 
   /**
@@ -3948,7 +4135,8 @@ export class WebGL2Renderer implements RendererApi {
   setEnvironmentGain(gain: number): void {
     if (this.contextLost) return;
     this.materials.dirty();
-    this.writeFlatFloat('uEnvironmentGain', Math.max(0, gain));
+    this.environmentDials[2] = Math.max(0, gain);
+    this.writeFlatVector('uEnvironmentDials', this.environmentDials);
   }
 
   /**
@@ -3974,6 +4162,18 @@ export class WebGL2Renderer implements RendererApi {
     );
   }
 
+  /**
+   * A pass-level scale over the grain the geometry itself declared, 0 to 1.
+   *
+   * Which surfaces are mineral is now `MeshData.grain`, stated per vertex through
+   * `MeshBuilder.setGrain` — because it is a property of a material, and absent means none.
+   * This stays as the override for the case that has no answer to state: an imported model
+   * arrives with no grain information at all, and a caller drawing one decides for it.
+   *
+   * Pass state, like `setSurfaceTexture`, because a material covers many draws. The default
+   * is 1 and `bindMeshPass` restores it, so it scales geometry that declared grain and
+   * leaves geometry that did not exactly as it is.
+   */
   setSurfaceGrain(amount: number): void {
     if (this.contextLost) return;
     this.materials.dirty();
@@ -4019,6 +4219,18 @@ export class WebGL2Renderer implements RendererApi {
     this.useFlatProgram();
   }
 
+  /** A vector of material state, two to four floats, into every flat program. */
+  private writeFlatVector(name: string, value: Float32Array): void {
+    for (const target of this.flatTargets) {
+      this.gl.useProgram(target.program);
+      const at = target.uniforms[name] ?? null;
+      if (value.length === 2) this.gl.uniform2fv(at, value);
+      else if (value.length === 3) this.gl.uniform3fv(at, value);
+      else this.gl.uniform4fv(at, value);
+    }
+    this.useFlatProgram();
+  }
+
   /** One int of material state, into every flat program, for `writeFlatFloat`'s reason. */
   private writeFlatInt(name: string, value: number): void {
     for (const target of this.flatTargets) {
@@ -4083,8 +4295,13 @@ export class WebGL2Renderer implements RendererApi {
   setSurfaceRelief(amount: number, cyclesPerMetre = 60): void {
     if (this.contextLost) return;
     this.materials.dirty();
-    this.writeFlatFloat('uRelief', Math.min(1, Math.max(0, amount)));
-    this.writeFlatFloat('uReliefCycles', Math.max(0.01, cyclesPerMetre));
+    const strength = Math.min(1, Math.max(0, amount));
+    const cycles = Math.max(0.01, cyclesPerMetre);
+    for (const target of this.flatTargets) {
+      this.gl.useProgram(target.program);
+      this.gl.uniform2f(target.uniforms['uRelief'] ?? null, strength, cycles);
+    }
+    this.useFlatProgram();
   }
 
   /**
@@ -4142,7 +4359,8 @@ export class WebGL2Renderer implements RendererApi {
   setEmissiveGain(gain: number): void {
     if (this.contextLost) return;
     this.materials.dirty();
-    this.writeFlatFloat('uEmissiveGain', gain);
+    this.emission[0] = gain;
+    this.writeFlatVector('uEmission', this.emission);
   }
 
   /* -- Instanced meshes --------------------------------------------------------------- */
@@ -4254,6 +4472,7 @@ export class WebGL2Renderer implements RendererApi {
     options: TranslucentMeshOptions,
   ): void {
     if (this.contextLost) return;
+    warnRegionsWithoutPage(this.currentMaterial?.model, data.lightmapRegions);
     const mesh = batch.mesh;
     /* Nor a batch of a mesh with nothing in it: see `Mesh.indexCount`. */
     if (!mesh.complete || mesh.indexCount === 0) return;
@@ -4384,7 +4603,7 @@ export class WebGL2Renderer implements RendererApi {
     const refraction = options.refraction ?? 0;
     const glassy = resolveGlass(options.glass, this.glassScratch);
     if (refraction <= 0 && !glassy) return false;
-    if (this.probePassActive || this.reflectionPassActive) return false;
+    if (this.probePassActive || this.reflectionPassActive || this.capturePassActive) return false;
     const snapshot = this.sceneTarget?.snapshotColor(false, glassy) ?? null;
     if (snapshot === null) return false;
     gl.activeTexture(gl.TEXTURE0 + REFRACT_SCENE_TEXTURE_UNIT);
@@ -4746,6 +4965,29 @@ export class WebGL2Renderer implements RendererApi {
     return new ParticleBatch(this.gl, capacity, options);
   }
 
+  /**
+   * Particles a caller's own compute wrote: WebGPU's alone, since this backend has no compute stage
+   * to have written them (`computeSupported`). Said once, and nothing is drawn.
+   */
+  drawDeviceParticles(
+    _batch: ParticleBatch,
+    _particles: DeviceParticles,
+    _camera: Camera,
+    _env: Environment,
+    _timeSeconds: number,
+  ): void {
+    if (this.warnedDeviceParticles) return;
+    this.warnedDeviceParticles = true;
+    console.warn(
+      'Renderer: drawDeviceParticles draws particles a compute shader wrote, and WebGL2 has no ' +
+        'compute stage, so nothing is drawn. Check `computeSupported`, and draw a pool with ' +
+        '`drawParticles` where it is false.',
+    );
+  }
+
+  /** Said once: see `drawDeviceParticles`. */
+  private warnedDeviceParticles = false;
+
   /**
    * Draw a live particle pool.
    *
@@ -4767,8 +5009,9 @@ export class WebGL2Renderer implements RendererApi {
     const { gl } = this;
     const u = batch.uniforms;
     gl.useProgram(batch.program);
-    batch.upload(gl, data);
+    batch.upload(gl, data, camera.position);
     batch.bindMaterial(gl);
+    if (batch.material === 'sprite') this.bindSpriteFades(batch, camera);
     gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, this.viewProjFor(camera));
     gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
     gl.uniform1f(u['uTime'] ?? null, timeSeconds);
@@ -4800,6 +5043,53 @@ export class WebGL2Renderer implements RendererApi {
     if (this.materialDoubleSided) gl.enable(gl.CULL_FACE);
   }
 
+  /**
+   * 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(batch: ParticleBatch, camera: Camera): void {
+    const { gl } = this;
+    const u = batch.uniforms;
+    const scene = this.sceneTarget;
+    let depth: WebGLTexture | null = null;
+    if (
+      batch.softDepth > 0 &&
+      !this.reflectionPassActive &&
+      !this.probePassActive &&
+      !this.capturePassActive
+    ) {
+      depth = scene?.snapshotDepth(true) ?? null;
+      if (depth === null && !this.warnedSpriteDepth) {
+        this.warnedSpriteDepth = true;
+        console.warn(
+          "WebGL2: a 'sprite' asked for a soft edge, which reads a copy of the frame's depth, and " +
+            'this profile keeps none — screenEffects is off, or the driver refused the copy. The ' +
+            'edge is hard.',
+        );
+      }
+    }
+    gl.activeTexture(gl.TEXTURE0 + PARTICLE_DEPTH_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, depth ?? this.emptyTexture2D);
+    gl.uniform1i(u['uDepth'] ?? null, PARTICLE_DEPTH_UNIT);
+    gl.uniform4f(u['uFade'] ?? null, batch.softDepth, batch.cameraFade, depth === null ? 0 : 1, 0);
+    mat4.invert(this.spriteInverseProjection, camera.projection);
+    const inverse = this.spriteInverseProjection;
+    gl.uniform4f(
+      u['uDepthToViewZ'] ?? null,
+      inverse[10] ?? 0,
+      inverse[14] ?? 0,
+      inverse[11] ?? 0,
+      inverse[15] ?? 1,
+    );
+    gl.uniform2f(
+      u['uViewport'] ?? null,
+      scene?.frameWidth ?? gl.drawingBufferWidth,
+      scene?.frameHeight ?? gl.drawingBufferHeight,
+    );
+  }
+
   /** Build a batch for electrical arcs. `capacity` is in segments, not arcs. */
   createBolts(segmentCapacity: number, label = 'bolts'): BoltBatch {
     return new BoltBatch(this.gl, segmentCapacity, label);
@@ -5838,6 +6128,7 @@ export class WebGL2Renderer implements RendererApi {
       lightFixtures: this.litOn.LIGHT_FIXTURES,
       surfaceEffects: this.litOn.SURFACE_EFFECTS,
       driftLight: this.litOn.DRIFT_LIGHT,
+      physicalSpecular: this.litOn.PHYSICAL_SPECULAR,
       maxLights: budget.maxLights,
       maxAreaLights: budget.maxAreaLights,
     });
@@ -5918,7 +6209,7 @@ export class WebGL2Renderer implements RendererApi {
       const label = `flat.${variant}.${kind}.${half}`;
       const program = compileProgram(
         gl,
-        litVertexOf(variant),
+        modelVertexOf(variant, kind),
         skinHalfBound(modelBound(this.flatFragSource, kind), half),
         label,
       );
@@ -6800,10 +7091,17 @@ export 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 {
     this.bloomScale = Math.min(Math.max(scale, 0), 1);
     if (threshold !== undefined) this.bloomThresholdSet = bloomThresholdOf(threshold);
+    if (response !== undefined) resolveBloomResponse(response, this.bloomResponse);
   }
 
   /**
@@ -7364,6 +7662,7 @@ export class WebGL2Renderer implements RendererApi {
         ? {
             strength: bloomStrength,
             threshold: this.bloomThresholdSet ?? this.quality.bloomThreshold,
+            response: this.bloomResponse,
           }
         : undefined;
 
@@ -7699,6 +7998,19 @@ export class WebGL2Renderer implements RendererApi {
   bindMeshPass(camera: Camera, env: Environment): void {
     /* The pass's own material is reopened, so the next draw opens one. See `materialChanges.ts`. */
     this.materials.dirty();
+    /* Rectangles past the fixed arm's are the froxel table's, and without it nobody shades them. */
+    if (
+      !this.warnedAreaOverflow &&
+      !this.quality.clusteredLights &&
+      (env.areaLights?.count ?? 0) > this.shadedAreaLights
+    ) {
+      this.warnedAreaOverflow = true;
+      console.warn(
+        `WebGL2: ${env.areaLights?.count ?? 0} rectangular lights and ${this.shadedAreaLights} ` +
+          'shaded without clusteredLights: the rest are not drawn. Turn clusteredLights on, and the ' +
+          'froxel table shades every one past the fixed ones, unshadowed.',
+      );
+    }
     /*
      * Captured here rather than taken as an argument to `endFrame`, because this is the
      * camera the world was drawn with and a caller should not have to hand it over twice.
@@ -7712,7 +8024,12 @@ export class WebGL2Renderer implements RendererApi {
      * other position, and the anti-flicker's period never started.
      */
     if (this.framePresented) this.temporalJittering = false;
-    if (!this.reflectionPassActive && !this.probePassActive && !this.framePresented) {
+    if (
+      !this.reflectionPassActive &&
+      !this.probePassActive &&
+      !this.capturePassActive &&
+      !this.framePresented
+    ) {
       this.frameViewProj = camera.viewProjection;
       /* Copied rather than referenced: a caller moves its camera in place, and the decal pass
          reads this at the end of the frame. */
@@ -7810,6 +8127,13 @@ export class WebGL2Renderer implements RendererApi {
     this.materialHasMaps = false;
     this.currentMaterial = null;
     this.currentSurfaceTexture = null;
+    /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
+    this.ambientSH.fill(0);
+    /* No reflection and an environment at its own brightness; the emission the world asks for. */
+    this.environmentDials[1] = 0;
+    this.environmentDials[2] = 1;
+    this.emission[0] = env.emissiveGain;
+    this.emission[1] = env.nightFactor;
     for (const target of this.flatTargets) {
       this.gl.useProgram(target.program);
       this.writeMeshPassState(target.uniforms, camera, env);
@@ -8036,13 +8360,18 @@ export class WebGL2Renderer implements RendererApi {
     this.oitWeight = 0;
     this.ditherFade = 0;
     gl.uniform2f(u['uWriteMode'] ?? null, 0, 0);
-    /* No environment reflection unless a caller asks, so existing scenes are unchanged. */
-    gl.uniform1f(u['uReflectivity'] ?? null, 0);
-    /* 1, not 0: this one is a multiplier and its identity is one. See `setEnvironmentGain`. */
-    gl.uniform1f(u['uEnvironmentGain'] ?? null, 1);
+    /* The draw's own ambient as it stands, which `bindMeshPass` has just cleared: a program built
+       in the middle of a pass takes what the caller set. See `setAmbientSH`. */
+    gl.uniform4fv(u['uAmbientSH[0]'] ?? null, this.ambientSH);
+    /*
+     * Which chain the probe holds, no environment reflection, and an environment at its own
+     * brightness — the reflectivity's identity is 0 and the gain's is 1 — as `bindMeshPass` set
+     * them, or as a draw since has: a program built in the middle of a pass takes what stands.
+     * See `setSurfaceReflectivity` and `setEnvironmentGain`.
+     */
+    gl.uniform3fv(u['uEnvironmentDials'] ?? null, this.environmentDials);
     /* And no relief unless a caller asks, for the same reason. */
-    gl.uniform1f(u['uRelief'] ?? null, 0);
-    gl.uniform1f(u['uReliefCycles'] ?? null, 60);
+    gl.uniform2f(u['uRelief'] ?? null, 0, 60);
     /* And no relief read off a surface texture either, for the same reason. */
     gl.uniform1f(u['uTextureRelief'] ?? null, 0);
     /* The mirror's plane in a reflection pass, and zero — which clips nothing — in every other. */
@@ -8060,8 +8389,8 @@ export class WebGL2Renderer implements RendererApi {
       this.reflectionPassActive ? this.reflectionAtmosphereY : (camera.position[1] ?? 0),
       this.quality.underwaterAtmosphere,
     );
-    gl.uniform1f(u['uEmissiveGain'] ?? null, env.emissiveGain);
-    gl.uniform1f(u['uNightFactor'] ?? null, env.nightFactor);
+    /* The emissive gain and the night factor, as the pass set them. See `uEmission`. */
+    gl.uniform2fv(u['uEmission'] ?? null, this.emission);
     /* Absent means zero, so a world written before this term existed adds nothing. */
     gl.uniform1f(u['uNightEmissive'] ?? null, env.nightEmissive ?? 0);
     /*
@@ -8083,8 +8412,16 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform1f(u['uShadowMaxSlope'] ?? null, this.quality.directionalShadowMaxSlope);
     gl.uniform1i(u['uShadowFilterTaps'] ?? null, this.quality.shadowFilterTaps);
     gl.uniform3fv(u['uHighlightMin'] ?? null, env.highlightMin);
-    gl.uniform3fv(u['uHighlightMax'] ?? null, env.highlightMax);
-    gl.uniform1f(u['uHighlightGain'] ?? null, env.highlightGain);
+    /* The far corner, and the gain in its w. See `uHighlightMax`. */
+    /* An environment written by hand may leave the box out; then there is none, as before. */
+    const max = env.highlightMax ?? NO_HIGHLIGHT;
+    gl.uniform4f(
+      u['uHighlightMax'] ?? null,
+      max[0] ?? 0,
+      max[1] ?? 0,
+      max[2] ?? 0,
+      env.highlightGain ?? 0,
+    );
 
     bindPointLights(gl, u, env, this.quality.pointLightFalloff);
     this.bindClusters(u, camera, env);
@@ -8184,7 +8521,8 @@ export class WebGL2Renderer implements RendererApi {
        * between them; there is one array, so `RenderQuality.environmentPrefilter` decides what the
        * convolution writes and a profile that changes it has to bake again.
        */
-      gl.uniform1f(u['uEnvironmentPrefiltered'] ?? null, this.quality.environmentPrefilter ? 1 : 0);
+      this.environmentDials[0] = this.quality.environmentPrefilter ? 1 : 0;
+      gl.uniform3fv(u['uEnvironmentDials'] ?? null, this.environmentDials);
       gl.uniform1f(u['uEnvironmentMaxLod'] ?? null, array?.ggxMaxLevel ?? 0);
       /*
        * The map's edge, which used to be `exp2(maxLod)` and is not any more: the chain stops one
@@ -8383,12 +8721,17 @@ export class WebGL2Renderer implements RendererApi {
     if (this.quality.cullDraws && this.occluded(mesh.bounds, model)) return;
     this.drawBudget.ask();
     this.takeMaterial();
-    /* Skin under the screen-space blur draws its two halves: the frame's, then at once its diffuse. */
+    /*
+     * Skin under the screen-space blur draws its halves: the frame's, then at once its diffuse's
+     * light and its colour, each into the blur's own target.
+     */
     const splits = this.skinSplits();
     this.drawMeshHalf(mesh, model, depthLayer, tint, splits ? 'scene' : 'whole');
     if (splits && this.skinScatter !== null) {
       this.skinScatter.begin();
       this.drawMeshHalf(mesh, model, depthLayer, tint, 'diffuse');
+      this.skinScatter.beginAlbedo();
+      this.drawMeshHalf(mesh, model, depthLayer, tint, 'albedo');
       this.sceneTarget?.bind();
     }
   }
@@ -8408,6 +8751,7 @@ export class WebGL2Renderer implements RendererApi {
       !this.skinScattered &&
       !this.reflectionPassActive &&
       !this.probePassActive &&
+      !this.capturePassActive &&
       !this.framePresented &&
       skin.ready(scene)
     );
@@ -8428,7 +8772,8 @@ export class WebGL2Renderer implements RendererApi {
     /* Latched whether or not skin was drawn: a skin drawn after this point is the whole surface. */
     this.skinScattered = true;
     if (!skin.pending) return;
-    if (this.reflectionPassActive || this.probePassActive || projection === null) return;
+    if (this.reflectionPassActive || this.probePassActive || this.capturePassActive) return;
+    if (projection === null) return;
     const depth = scene.snapshotDepth(true);
     mat4.invert(this.skinInverseProjection, projection);
     skin.spread(scene, depth, this.emptyTexture2D, projection, this.skinInverseProjection);
@@ -8574,8 +8919,9 @@ export class WebGL2Renderer implements RendererApi {
      * depth 1.0 against a buffer cleared to 1.0, and under `LESS` it would not draw at
      * all. Film, caustics and text lie flush on surfaces for the same reason.
      */
-    /* A skin's diffuse half is the same surface again: it finds the depth its frame half wrote. */
-    const again = half === 'diffuse';
+    /* A skin's diffuse and colour halves are the same surface again: each finds the depth its
+       frame half wrote. */
+    const again = half === 'diffuse' || half === 'albedo';
     gl.depthFunc(again ? gl.EQUAL : this.reversedDepth ? gl.GREATER : gl.LESS);
     if (again) gl.depthMask(false);
     /* A dithered cutout in a multisampled frame with no temporal resolve: its share becomes the
@@ -9030,6 +9376,62 @@ export class WebGL2Renderer implements RendererApi {
     return true;
   }
 
+  /**
+   * 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 {
+    if (this.contextLost) return false;
+    const probe = this.probeCapture;
+    const array = this.probeArray;
+    const grid = this.probes;
+    const sweeps = this.probeSweeps;
+    if (probe === null || array === null || grid === null || sweeps === null) {
+      console.warn(
+        'Renderer: setProbeLayerImage needs a reflection probe (`reflectionProbeSize`) and a grid ' +
+          'declared with setProbeGrid; the image was ignored.',
+      );
+      return false;
+    }
+    if (!Number.isInteger(layer) || layer < 0 || layer >= grid.layers) {
+      console.warn(
+        `Renderer: setProbeLayerImage was given layer ${layer}, and the grid has ${grid.layers}.`,
+      );
+      return false;
+    }
+    if (!probe.upload(this.gl, equirectToCubeFaces(image, probe.size))) return false;
+    this.probeAmbient = options?.irradiance ?? true;
+    this.environmentPrefilter?.run(
+      this.gl,
+      probe,
+      array,
+      sweeps.writeLayer(layer),
+      ENVIRONMENT_TEXTURE_UNIT,
+      this.quality.environmentPrefilterSamples,
+      this.quality.environmentPrefilter,
+    );
+    sweeps.baked(layer);
+    return true;
+  }
+
   /**
    * Draw a volume of light: a beam from a lamp, a shaft through a window, the cone under a
    * street light.
@@ -9420,6 +9822,15 @@ const NO_MODEL_PARAMS = new Float32Array(MODEL_PARAM_FLOATS);
  * The lit vertex stage a program of this variant compiles: the standard programs' and the cloth's,
  * which `modelProgram` pairs a model's fragment stage with.
  */
+/**
+ * The vertex stage a model's program draws with: the variant's own, but for a lightmapped instanced
+ * batch, whose tint lane is each instance's region of the page. See `lightmap.ts`.
+ */
+function modelVertexOf(variant: string, kind: SurfaceModelKind): string {
+  const vertex = litVertexOf(variant);
+  return kind === 'lightmap' && variant === 'instanced' ? lightmapRegionsBound(vertex) : vertex;
+}
+
 function litVertexOf(variant: string): string {
   if (variant.startsWith('cloth')) {
     const eight = variant[5] === '8';