@driftengine/core 4.8.7 → 4.10.0

package/dist/render/surfaceTexture.d.ts

@@ -9,7 +9,7 @@
  * so a merged block wearing forty facades is one draw.
  */
 import type { SurfaceModel } from './surfaceModel.ts';
-import type { CompressedTextureFormat, SurfaceSource } from './compressedSource.ts';
+import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from './compressedSource.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
 import type { CutoutMode } from './cutoutDither.ts';
 import type { LightmapTexels } from './lightmap.ts';
@@ -107,7 +107,7 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * which is every light's default too, so a scene that names no channel is lit as it always was.
      *
      * A point or spot light shades this surface only where its `PointLightSet.lightChannels` and this
-     * share a bit — Unreal's lighting channels. A character's own key and rim lights on channel 2,
+     * share a bit — lighting channels. A character's own key and rim lights on channel 2,
      * and the character's materials on 3, light the character and leave the floor around it as the
      * stage's lights alone have it. **What it does not reach**: the sun, the sky and the probes, area
      * lights, DriftLight's volume and the GPU-driven pipeline light every surface whatever its mask.
@@ -141,6 +141,22 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * which is the opposite of what the caller asked for.
      */
     occlusionStrength?: number;
+    /**
+     * How much of the environment this material's draws mirror, 0 to 1: the number
+     * `setSurfaceReflectivity` sets for every draw, stated by the material for its own. Absent, its
+     * draws wear the setter's, as every material's did before this existed.
+     *
+     * **Here so a static list can carry it.** A list keeps each entry's material and none of the
+     * renderer's state between draws (`createStaticDraws`), so a stage whose batches each mirror their
+     * own share of a baked reflection says so in the material it records. What it gives up is nothing a
+     * setter could do: one called after this material is set is ignored for the material's draws.
+     */
+    reflectivity?: number;
+    /**
+     * How bright the environment this material's draws reflect is: `setEnvironmentGain`'s number,
+     * stated by the material for its own, and absent the setter's. Held non-negative.
+     */
+    environmentGain?: number;
     /**
      * Scales the emissive map, per channel. Default 1.
      *
@@ -164,14 +180,14 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
     modelMap?: Texture | null;
     /**
      * Whether a lamp's and the sun's highlight on this surface is GGX's own, `π · D · Vis · F · N·L`,
-     * as Unreal and this engine's skin and eye shade it, rather than the engine's lobe scaled to a
-     * peak of one. **False by default**, every surface as it was.
+     * as physically based renderers and this engine's skin and eye shade it, rather than the engine's
+     * lobe scaled to a peak of one. **False by default**, every surface as it was.
      *
      * The peak-normalised lobe is a look control: the specular attribute says how strong a highlight
      * is and roughness how wide, apart. Physical, they are entangled as they are in a real surface —
      * the peak is `1 / (4 α²)` of the light head-on, so a polished surface's highlight is many times
      * the look's and a rough one's lower and broader — and the specular attribute is read as the
-     * reflectance at normal incidence, F0: Unreal's `0.08 × Specular`, 0.04 at its default. Fresnel
+     * reflectance at normal incidence, F0: `0.08 × Specular`, 0.04 at its default. Fresnel
      * then brightens every surface toward grazing, not only a metal. A rectangle's highlight is the
      * lobe integrated over it with the attribute as F0 already, so it is unchanged either way.
      *
@@ -275,7 +291,16 @@ export declare class SurfaceTexture {
     /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
     private effectsTable;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
-    private readonly blockFormat;
+    private blockFormat;
+    /** How the texture is sampled, kept so blocks swapped in by `update` are sampled the same way. */
+    private readonly sampling;
+    /** Level 0's size, which `flatLayer` copies; kept as `update` changes it. */
+    private width;
+    private height;
+    /** The texture's storage format, which `flatLayer`'s copy matches so the copy converts nothing. */
+    private readonly storage;
+    /** Layer 0 as a plain 2D texture, made by `flatLayer` and dropped when the pixels change. */
+    private flat;
     /**
      * 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
@@ -296,7 +321,20 @@ export declare class SurfaceTexture {
      * Not a hot path: it re-uploads the whole image and regenerates the chain. A caller
      * doing this every frame at any size wants to know that it costs what it costs.
      */
-    update(gl: WebGL2RenderingContext, source: TexImageSource): void;
+    update(gl: WebGL2RenderingContext, source: TexImageSource | CompressedTextureSource, compressed?: readonly CompressedTextureFormat[]): void;
+    /**
+     * Blocks in place of the image, behind the same handle: **a new GL object** rather than the
+     * image's levels respecified, because a chain shorter than the image's would leave the levels
+     * past it allocated, and immutable storage could not be respecified at all. Sampled as the image
+     * was, and refused before anything changes where the context does not take the format.
+     */
+    private swapToBlocks;
+    /**
+     * Wrap, filters and anisotropy on the bound texture. Nearest where the caller said their pixels
+     * are the subject; see `filter`. The mip chain is still blended between levels, because that is
+     * minification and this option is about magnification.
+     */
+    private applySampling;
     /**
      * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
      * by `captureScene`. Engine-internal, as `bind` is.
@@ -304,5 +342,17 @@ export declare class SurfaceTexture {
     attachColor(gl: WebGL2RenderingContext): void;
     /** Bind to a unit for sampling. Engine-internal: the renderer owns unit assignment. */
     bind(gl: WebGL2RenderingContext, unit: number): void;
+    /**
+     * 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: WebGL2RenderingContext): WebGLTexture | null;
+    private dropFlat;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/surfaceTexture.js

@@ -1,5 +1,5 @@
 import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.js';
-import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.js';
+import { compressedLayers, isCompressedSource, planBlocks, refuseBlockUpdate, } from './compressedSource.js';
 import { uploadCompressedArray } from './glCompressed.js';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.js';
 import { isLightmapTexels } from './lightmap.js';
@@ -25,6 +25,15 @@ export class SurfaceTexture {
     effectsTable = null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     blockFormat;
+    /** How the texture is sampled, kept so blocks swapped in by `update` are sampled the same way. */
+    sampling;
+    /** 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
@@ -51,6 +60,9 @@ export class SurfaceTexture {
             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) {
@@ -58,6 +70,9 @@ export class SurfaceTexture {
             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);
@@ -73,6 +88,7 @@ export class SurfaceTexture {
                `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);
         }
@@ -81,25 +97,20 @@ 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);
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
-        /* Nearest where the caller said their pixels are the subject; see `filter`. The mip chain is
-           still blended between levels, because that is minification and this option is about
-           magnification. */
-        const nearest = options.filter === 'nearest';
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, this.mipmapped
-            ? nearest
-                ? gl.NEAREST_MIPMAP_LINEAR
-                : gl.LINEAR_MIPMAP_LINEAR
-            : nearest
-                ? gl.NEAREST
-                : gl.LINEAR);
+        this.sampling = {
+            wrap,
+            nearest: options.filter === 'nearest',
+            anisotropy: options.anisotropy ?? DEFAULT_ANISOTROPY,
+        };
+        this.applySampling(gl);
         if (this.mipmapped && this.blockFormat === null)
             gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
-        applyAnisotropy(gl, options.anisotropy ?? DEFAULT_ANISOTROPY);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
         /* Half floats, nearest, clamped: a table read by texelFetch, whose every whole number is under
            what a half holds exactly. */
@@ -137,12 +148,19 @@ export class SurfaceTexture {
      * Not a hot path: it re-uploads the whole image and regenerates the chain. A caller
      * doing this every frame at any size wants to know that it costs what it costs.
      */
-    update(gl, source) {
+    update(gl, source, compressed = []) {
         if (this.texture === null)
             return;
         refuseArrayUpdate(this.layers);
+        if (isCompressedSource(source)) {
+            this.swapToBlocks(gl, source, compressed);
+            return;
+        }
         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);
@@ -150,6 +168,48 @@ export class SurfaceTexture {
             gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
     }
+    /**
+     * Blocks in place of the image, behind the same handle: **a new GL object** rather than the
+     * image's levels respecified, because a chain shorter than the image's would leave the levels
+     * past it allocated, and immutable storage could not be respecified at all. Sampled as the image
+     * was, and refused before anything changes where the context does not take the format.
+     */
+    swapToBlocks(gl, source, compressed) {
+        const plan = planBlocks([source], this.srgb, compressed);
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('SurfaceTexture: createTexture failed');
+        this.dropFlat(gl);
+        if (this.texture !== null)
+            gl.deleteTexture(this.texture);
+        this.texture = texture;
+        this.blockFormat = source.format;
+        this.width = source.width;
+        this.height = source.height;
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+        uploadCompressedArray(gl, plan.name, [source], this.mipmapped ? plan.levels : 1);
+        this.applySampling(gl);
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+    }
+    /**
+     * Wrap, filters and anisotropy on the bound texture. Nearest where the caller said their pixels
+     * are the subject; see `filter`. The mip chain is still blended between levels, because that is
+     * minification and this option is about magnification.
+     */
+    applySampling(gl) {
+        const { wrap, nearest, anisotropy } = this.sampling;
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, wrap);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, wrap);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, nearest ? gl.NEAREST : gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, this.mipmapped
+            ? nearest
+                ? gl.NEAREST_MIPMAP_LINEAR
+                : gl.LINEAR_MIPMAP_LINEAR
+            : nearest
+                ? gl.NEAREST
+                : gl.LINEAR);
+        applyAnisotropy(gl, anisotropy);
+    }
     /**
      * Attach the only layer as the bound framebuffer's colour: a scene capture's target, drawn into
      * by `captureScene`. Engine-internal, as `bind` is.
@@ -162,9 +222,57 @@ export class SurfaceTexture {
         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.7",
+  "version": "4.10.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.7",
-    "@driftengine/physics": "4.8.7",
+    "@driftengine/drft": "4.10.0",
+    "@driftengine/physics": "4.10.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.7",
-    "@driftengine/network": "4.8.7",
-    "@driftengine/texture": "4.8.7"
+    "@driftengine/nav": "4.10.0",
+    "@driftengine/network": "4.10.0",
+    "@driftengine/texture": "4.10.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.
@@ -552,6 +568,10 @@ export type {
   ShadowCasterSink,
   ShadowCasters,
 } from './render/shadowCasters.ts';
+/* What `createStaticDraws` hands back, so a consumer can hold one in a field it declares. */
+export type { StaticDrawsHandle } from './render/staticDraws.ts';
+/* A bone animation's clip as a caller hands it over, and the handle `createBoneAnimation` returns. */
+export type { BoneAnimationClip, BoneAnimationHandle } from './render/boneAnimation.ts';
 export type { Atmosphere, UnderwaterAtmosphere } from './render/atmosphere.ts';
 /*
  * Reading an image's texels back exactly, which no canvas and no `VideoFrame` will do.
@@ -644,12 +664,14 @@ export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
 /*
- * BC compressed textures: the source `createSurfaceTexture` takes as blocks, and the one question to
- * ask before handing one over — whether this device takes its format (`renderer.compressedFormats`).
+ * Compressed textures — BC, ETC2 and EAC, ASTC: the source `createSurfaceTexture` takes as blocks,
+ * the one question to ask before handing one over — whether this device takes its format
+ * (`renderer.compressedFormats`) — and the bytes a level of it holds, for a reader checking a file.
  */
 export {
   compressedFormatName,
   isCompressedSource,
+  levelBytes,
   uploadsCompressed,
 } from './render/compressedSource.ts';
 export type {

package/src/render/ambientHarmonics.ts

@@ -4,7 +4,7 @@
  *
  * **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
+ * lit alike. A stage with a baked volume of indirect light (a 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.

package/src/render/areaLights.ts

@@ -94,14 +94,14 @@ export interface AreaLightSource {
    * 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.
+   * of a scene unit, and never inside the rectangle itself. An attenuation radius, 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.
+   * its hemisphere. 88° is the usual default, 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.
@@ -111,7 +111,7 @@ export interface AreaLightSource {
    * rectangle's back face has none.
    */
   barnDoorAngle?: number;
-  /** The barn doors' length in metres. Absent, 0.2: Unreal's default of 20 cm. */
+  /** The barn doors' length in metres. Absent, 0.2: the usual default of 20 cm. */
   barnDoorLength?: number;
 }
 
@@ -150,7 +150,7 @@ export function createAreaLightBuffer(capacity: number = MAX_AREA_LIGHTS): AreaL
   };
 }
 
-/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+/** The usual default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
 export const DEFAULT_BARN_DOOR_LENGTH = 0.2;
 
 /**

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