@driftengine/core 4.8.6 → 4.9.0

package/dist/render/surfaceTexture.js

@@ -3,6 +3,7 @@ import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSou
 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.
@@ -24,15 +25,24 @@ export class SurfaceTexture {
     effectsTable = null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     blockFormat;
+    /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
+    width = 0;
+    height = 0;
+    /** The texture's storage format, which `flatLayer`'s copy matches so the copy converts nothing. */
+    storage;
+    /** Layer 0 as a plain 2D texture, made by `flatLayer` and dropped when the pixels change. */
+    flat = null;
     /**
      * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
      * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
      * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
     constructor(gl, source, options = {}, compressed = []) {
-        /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+        /* 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 ? [] : Array.isArray(source) ? source : [source]);
+        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. */
@@ -43,21 +53,40 @@ 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 (baked !== null) {
+        if (capture !== null) {
+            /* Immutable storage, one level: a framebuffer attachment, and radiance read linear. */
+            this.layers = 1;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            this.width = capture.width;
+            this.height = capture.height;
+            this.storage = capture.float ? gl.RGBA16F : gl.RGBA8;
+            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;
+            this.layers = baked.layers.length;
             this.blockFormat = null;
             this.mipmapped = false;
+            this.width = baked.width;
+            this.height = baked.height;
+            this.storage = gl.RGBA8;
             /* 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);
-            gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, gl.RGBA16F, baked.width, baked.height, baked.layers, 0, gl.RGBA, gl.HALF_FLOAT, baked.texels);
+            /* 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;
             this.blockFormat = blocks[0].format;
+            this.storage = gl.NONE;
             this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
             uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
         }
@@ -66,6 +95,10 @@ export class SurfaceTexture {
             this.layers = sources.length;
             this.blockFormat = null;
             this.mipmapped = options.mipmap ?? true;
+            const { width, height } = layerSize(sources);
+            this.width = width;
+            this.height = height;
+            this.storage = this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA8;
             uploadImages(gl, sources, this.srgb);
         }
         gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
@@ -128,6 +161,9 @@ export class SurfaceTexture {
         refuseArrayUpdate(this.layers);
         refuseBlockUpdate(this.blockFormat);
         const { width, height } = sourceSize(source);
+        this.width = width;
+        this.height = height;
+        this.dropFlat(gl);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
         /* Unflipped, matching the constructor. See it for why, and for what it cost. */
         gl.texImage3D(gl.TEXTURE_2D_ARRAY, 0, this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA, width, height, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, source);
@@ -135,14 +171,69 @@ 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);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     }
+    /**
+     * Layer 0 as a plain 2D texture: what a `sampler2D` can be handed, which an array cannot. Copied
+     * the first time it is asked for, by a framebuffer blit into storage of the same format, and kept
+     * until `update` or `dispose`. Engine-internal: a surface overlay's atlas is bound where the
+     * lit stage's one 2D image slot is (`surfaceOverlay.ts`).
+     *
+     * **Null for blocks**, which no framebuffer can read; the caller says so. What it costs is a copy
+     * of level 0 in memory beside the array, and the bindings of both framebuffer targets, which are
+     * read back before the blit and put back after it — a sync query, paid once per image.
+     */
+    flatLayer(gl) {
+        if (this.texture === null || this.blockFormat !== null)
+            return null;
+        if (this.flat !== null)
+            return this.flat;
+        const flat = gl.createTexture();
+        const read = gl.createFramebuffer();
+        const draw = gl.createFramebuffer();
+        if (flat === null || read === null || draw === null)
+            return null;
+        gl.bindTexture(gl.TEXTURE_2D, flat);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, this.storage, this.width, this.height);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        const heldRead = gl.getParameter(gl.READ_FRAMEBUFFER_BINDING);
+        const heldDraw = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING);
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+        gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, 0, 0);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, draw);
+        gl.framebufferTexture2D(gl.DRAW_FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, flat, 0);
+        const [w, h] = [this.width, this.height];
+        gl.blitFramebuffer(0, 0, w, h, 0, 0, w, h, gl.COLOR_BUFFER_BIT, gl.NEAREST);
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, heldRead);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, heldDraw);
+        gl.deleteFramebuffer(read);
+        gl.deleteFramebuffer(draw);
+        this.flat = flat;
+        return flat;
+    }
+    dropFlat(gl) {
+        if (this.flat !== null)
+            gl.deleteTexture(this.flat);
+        this.flat = null;
+    }
     dispose(gl) {
         if (this.texture === null)
             return;
+        this.dropFlat(gl);
         gl.deleteTexture(this.texture);
         this.texture = null;
         if (this.effectsTable !== null)

package/dist/render/temporalAa.d.ts

@@ -248,12 +248,26 @@ export declare class TemporalHistory {
     private picture;
     private width;
     private height;
+    /** Whether this frame of the renderer's has opened one of the sequence, and what it answered. */
+    private opened;
+    private answer;
+    /**
+     * A frame of the renderer's began: the next `openFrame` opens a frame of the sequence. Called at
+     * `beginFrame`, by both backends.
+     */
+    nextFrame(): void;
     /**
      * Open a frame at this target size, and answer whether the history may be sampled.
      *
      * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
      * resize or a cut discarded would sample the same position twice running, which is one sample
      * and not two.
+     *
+     * **Once a frame, however many times it is asked.** A renderer asks where the scene's camera
+     * arrives, and a frame binds that camera again after a scene capture or anything else that bound
+     * another; each asking opened a frame of its own, so the sequence stepped twice in such a frame
+     * and the edges of the picture swam. Asked again, it gives the answer it gave. What it gives up:
+     * a size changed between two asks in one frame is seen at the next frame, not at once.
      */
     openFrame(width: number, height: number): boolean;
     /**

package/dist/render/temporalAa.js

@@ -355,20 +355,40 @@ export class TemporalHistory {
     picture = false;
     width = 0;
     height = 0;
+    /** Whether this frame of the renderer's has opened one of the sequence, and what it answered. */
+    opened = false;
+    answer = false;
+    /**
+     * A frame of the renderer's began: the next `openFrame` opens a frame of the sequence. Called at
+     * `beginFrame`, by both backends.
+     */
+    nextFrame() {
+        this.opened = false;
+    }
     /**
      * Open a frame at this target size, and answer whether the history may be sampled.
      *
      * **The jitter advances whether or not it may be.** Holding the sequence still on the frames a
      * resize or a cut discarded would sample the same position twice running, which is one sample
      * and not two.
+     *
+     * **Once a frame, however many times it is asked.** A renderer asks where the scene's camera
+     * arrives, and a frame binds that camera again after a scene capture or anything else that bound
+     * another; each asking opened a frame of its own, so the sequence stepped twice in such a frame
+     * and the edges of the picture swam. Asked again, it gives the answer it gave. What it gives up:
+     * a size changed between two asks in one frame is seen at the next frame, not at once.
      */
     openFrame(width, height) {
+        if (this.opened)
+            return this.answer;
+        this.opened = true;
         this.frameIndex++;
         const usable = this.picture && width === this.width && height === this.height;
         if (!usable)
             this.picture = false;
         this.width = width;
         this.height = height;
+        this.answer = usable;
         return usable;
     }
     /**

package/dist/render/vertexDefaults.d.ts

@@ -38,6 +38,12 @@ export declare const ABSENT_ATTRIBUTE: Readonly<Record<string, readonly number[]
  * value that produces a picture. `flat.ts` reads `0` as none, `1` as sRGB and `2` as ACES.
  */
 export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
+/**
+ * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
+ * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
+ * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ */
+export declare function forwardTransformCode(transform: string): number;
 /**
  * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
  *
@@ -46,3 +52,14 @@ export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
  */
 export declare const RUSH_REACH_UV = 0.012;
 export declare const MOTION_BLUR_MAX_UV = 0.03;
+/**
+ * A longest smear as `setCameraMotionBlur` takes it: a share of the frame, above zero and at most
+ * half, and the default where the number is not one. Shared, so both backends cap one way.
+ */
+export declare function clampMotionShare(share: number): number;
+/**
+ * Said once where a draw names where it was last frame and the frame blurs by motion, but keeps no
+ * motion target to blur that draw by: each object's own motion is drawn only under a
+ * reconstruction on WebGPU, and anywhere else the camera's motion alone smears the frame.
+ */
+export declare const OBJECT_BLUR_UNKEPT: string;

package/dist/render/vertexDefaults.js

@@ -110,7 +110,16 @@ export const OUTPUT_TRANSFORM_CODE = {
     srgb: 1,
     aces: 2,
     shoulder: 3,
+    filmic: 4,
 };
+/**
+ * The code a **forward** pass grades with: the transform's own, except `filmic`, which only the
+ * composite carries the constants for, and which a pass grading itself therefore draws as `aces`.
+ * Both backends' `gradeCode` read this, so neither can hand a forward stage a code it lacks.
+ */
+export function forwardTransformCode(transform) {
+    return transform === 'filmic' ? 2 : (OUTPUT_TRANSFORM_CODE[transform] ?? 0);
+}
 /**
  * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
  *
@@ -119,3 +128,18 @@ export const OUTPUT_TRANSFORM_CODE = {
  */
 export const RUSH_REACH_UV = 0.012;
 export const MOTION_BLUR_MAX_UV = 0.03;
+/**
+ * A longest smear as `setCameraMotionBlur` takes it: a share of the frame, above zero and at most
+ * half, and the default where the number is not one. Shared, so both backends cap one way.
+ */
+export function clampMotionShare(share) {
+    return Number.isFinite(share) && share > 0 ? Math.min(share, 0.5) : MOTION_BLUR_MAX_UV;
+}
+/**
+ * Said once where a draw names where it was last frame and the frame blurs by motion, but keeps no
+ * motion target to blur that draw by: each object's own motion is drawn only under a
+ * reconstruction on WebGPU, and anywhere else the camera's motion alone smears the frame.
+ */
+export const OBJECT_BLUR_UNKEPT = "[driftengine] motion blur follows each draw's own motion only under a reconstruction " +
+    "(DriftTR, WebGPU), which draws the motion target it reads; here the camera's motion alone " +
+    'blurs the frame, and a moving object is smeared only as the camera moved past it.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.8.6",
+  "version": "4.9.0",
   "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.6",
-    "@driftengine/physics": "4.8.6",
+    "@driftengine/drft": "4.9.0",
+    "@driftengine/physics": "4.9.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -67,8 +67,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.8.6",
-    "@driftengine/network": "4.8.6",
-    "@driftengine/texture": "4.8.6"
+    "@driftengine/nav": "4.9.0",
+    "@driftengine/network": "4.9.0",
+    "@driftengine/texture": "4.9.0"
   }
 }

package/src/index.ts

@@ -454,6 +454,8 @@ 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';
+export { DEFAULT_FILMIC_CURVE } from './render/filmicCurve.ts';
+export type { FilmicCurve } from './render/filmicCurve.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`.
@@ -513,6 +515,20 @@ export type {
   SurfaceModel,
   SurfaceModelKind,
 } from './render/surfaceModel.ts';
+/*
+ * What a draw lays over its surface beyond its material — a rim of light, a dissolve, wrinkle
+ * normals by region — set per draw with `setSurfaceOverlay`, its images regions of one atlas.
+ */
+/* Every opaque lit surface reflecting the frame by its own material: `screenSpaceReflections`. */
+export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.ts';
+export type { FrameReflections } from './render/frameReflections.ts';
+export type {
+  OverlayRegion,
+  SurfaceDissolve,
+  SurfaceOverlay,
+  SurfaceRim,
+  SurfaceWrinkle,
+} from './render/surfaceOverlay.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.
@@ -1065,8 +1081,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/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

@@ -97,6 +97,22 @@ export interface AreaLightSource {
    * 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`. */
@@ -113,6 +129,11 @@ export interface AreaLightBuffer {
   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 {
@@ -125,9 +146,45 @@ export function createAreaLightBuffer(capacity: number = MAX_AREA_LIGHTS): AreaL
     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
@@ -227,6 +284,7 @@ export function selectAreaLights(
           ? 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/atmosphere.ts

@@ -47,6 +47,19 @@ export interface Atmosphere {
   /** Linear mode only: where haze begins, and where it is total. */
   fogNear?: number;
   fogFar?: number;
+  /**
+   * The medium only: how far along the view ray it begins, in metres. Absent or 0 is at the
+   * camera, as every world before it was drawn.
+   *
+   * The air nearer than this is perfectly clear, and what lies beyond is fogged by the air past
+   * this point alone — so a faint, bright haze can lie over a distant crowd while the figures a
+   * few metres from the camera stay sharp, which no density can do when the medium starts at the
+   * eye: there it veils the whole frame, lifting the shadows and draining the colour before it
+   * reaches anything far enough to want it. Unlike `linear`'s `fogNear`, nothing past it is a
+   * ramp: it is the same extinction, integrated from further out. **What it gives up** is the air
+   * between the camera and the start, which a real medium has; that is the point of it.
+   */
+  fogStart?: number;
   underwater: UnderwaterAtmosphere | null;
 }
 
@@ -132,7 +145,15 @@ export function resolveAtmosphere(
   out.fogHeightFalloff = atmosphere.fogHeightFalloff;
   out.fogEyeY = cameraY;
   out.fogMode = atmosphere.fogMode === 'linear' ? 1 : 0;
-  out.fogNear = atmosphere.fogNear ?? 0;
+  /*
+   * **One slot, two meanings, and never both**: the ramp's near distance in linear mode, and in
+   * the medium where it begins (`fogStart`), which the medium never read before — so a world that
+   * left a `fogNear` on an exponential fog starts nothing, and draws exactly as it did.
+   */
+  out.fogNear =
+    atmosphere.fogMode === 'linear'
+      ? (atmosphere.fogNear ?? 0)
+      : Math.max(0, Number.isFinite(atmosphere.fogStart) ? (atmosphere.fogStart ?? 0) : 0);
   out.fogFar = atmosphere.fogFar ?? 1;
   /*
    * The air medium stands in when nothing is submerged. The shaders multiply by the factor

package/src/render/backend/api.ts

@@ -1,13 +1,16 @@
 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';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
+import type { SurfaceOverlay } from '../surfaceOverlay.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';
@@ -276,6 +279,7 @@ export type RendererApi = Omit<
   | 'disposeCaustics'
   | 'createParticles'
   | 'drawParticles'
+  | 'drawDeviceParticles'
   | 'disposeParticles'
   | 'createWindStreaks'
   | 'drawWindStreaks'
@@ -302,10 +306,13 @@ export type RendererApi = Omit<
   | 'createSurfaceTexture'
   | 'createSurfaceTextureArray'
   | 'createLightmap'
+  | 'createSceneCapture'
+  | 'captureScene'
   | 'updateSurfaceTexture'
   | 'disposeSurfaceTexture'
   | 'setSurfaceTexture'
   | 'setMaterial'
+  | 'setSurfaceOverlay'
   | 'createClothBinding'
   | 'createClothParticles'
   | 'updateClothParticles'
@@ -336,6 +343,13 @@ export type RendererApi = Omit<
   setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
   disposeClothBinding(binding: ClothBindingHandle): void;
   disposeClothParticles(particles: ClothParticlesHandle): void;
+  /**
+   * What the following draws lay over their surfaces beyond their materials — a rim of light, a
+   * dissolve with a glowing edge, wrinkle normals by region — or null for none, which every pass
+   * starts with. Per draw, so one character's whole set of materials changes together. Its images
+   * are regions of one atlas (`SurfaceOverlay.maps`). See `surfaceOverlay.ts`.
+   */
+  setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
   /**
    * Upload a caller's image, or a BC image's blocks with their stored chain where
    * `compressedFormats` has the format. See `SurfaceTextureHandle` for the boundary this guards.
@@ -365,13 +379,41 @@ export type RendererApi = Omit<
 
   /**
    * 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
+   * `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.
    *
@@ -735,6 +777,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;