@driftengine/core 4.8.7 → 4.10.0

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

@@ -7,7 +7,8 @@ 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 { SurfaceSource } from '../compressedSource.ts';
+import type { SurfaceOverlay } from '../surfaceOverlay.ts';
+import type { CompressedTextureSource, SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
 import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
@@ -189,7 +190,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -213,6 +214,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.
@@ -262,12 +270,19 @@ export type RendererApi = Omit<{
      */
     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.
+     * Replace a texture's pixels, keeping the handle and its sampler state.
      *
      * The binding a draw loop already holds stays valid, so the swap is a swap rather than a
      * rebuild. Not a hot path: it re-uploads the whole image and rebuilds the mip chain.
+     *
+     * **Blocks may replace an image**, at the format's own size and with the chain they carry: the
+     * same picture at a fraction of the memory, which is how a loader that first showed a decoded
+     * image hands the device the blocks it encoded afterwards. Read in the colour space the texture
+     * was made with, and refused as `createSurfaceTexture` refuses them where the device does not take
+     * that format (`compressedFormats`). **The way back is refused**: a texture holding blocks takes
+     * no image, since nothing could say what its chain should become.
      */
-    updateSurfaceTexture(texture: SurfaceTextureHandle, source: TexImageSource): void;
+    updateSurfaceTexture(texture: SurfaceTextureHandle, source: TexImageSource | CompressedTextureSource): void;
     disposeSurfaceTexture(texture: SurfaceTextureHandle): void;
     /**
      * Choose the texture the following `drawMesh` calls sample, or null for none.

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

@@ -132,6 +132,12 @@ export interface CreateRendererOptions {
      * badge is looked at on a deployed build.
      */
     readonly splash?: boolean | SplashOptions;
+    /**
+     * Whether the display shows a high dynamic range, asked only where `highDynamicRange` was. The
+     * browser's `(dynamic-range: high)` query by default; a host with no DOM, or one that knows
+     * better about its own display, answers instead. See `displayRange.ts`.
+     */
+    readonly highDynamicRangeDisplay?: () => boolean;
 }
 /** What was built, and which path built it. */
 export interface CreatedRenderer {

package/dist/render/backend/createRenderer.js

@@ -4,6 +4,7 @@ import { BACKEND_TIMEOUT_MS, forcedBackend, selectBackend } from './select.js';
 import { TIMED_OUT, withDeadline } from './deadline.js';
 import { mountSplash } from '../../ui/splash.js';
 import { gpuDrivenRefusal, gpuDrivenSupported } from '../gpudriven/pipeline.js';
+import { browserHighDynamicRange, chooseDisplayRange } from '../displayRange.js';
 /**
  * What a caller who says nothing gets.
  *
@@ -177,7 +178,9 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
                 const { createGpuSurface } = await import('./webgpu/device.js');
                 const { WebGPURenderer } = await import('./webgpu/renderer.js');
                 stage = 'creating the surface';
-                const surface = createGpuSurface(canvas, device);
+                const profile = resolveRenderQuality(qualityFor('webgpu'));
+                const surface = createGpuSurface(canvas, device, chooseDisplayRange(profile.highDynamicRange, profile.screenEffects && profile.hdrScene, profile.highDynamicRange &&
+                    (options.highDynamicRangeDisplay ?? browserHighDynamicRange)()));
                 stage = 'constructing the renderer';
                 return { surface, WebGPURenderer };
             })();

package/dist/render/backend/select.js

@@ -207,12 +207,18 @@ async function acquireWebGpu(gpu, wantsGpuTiming, shaders, stage) {
             features.push('timestamp-query');
         }
         /*
-         * BC compressed textures, on the same terms: asked for wherever the adapter offers it, because
-         * a device without it still draws — the loader decodes for it — and one with it samples a BC7
-         * texture at a byte a texel instead of four. See `compressedUpload.ts`.
+         * The three block families, on the same terms: each asked for wherever the adapter offers it,
+         * because a device without one still draws — the loader decodes, or encodes ETC2, for it — and
+         * one with it samples a texture at a byte a texel or half of one instead of four. Desktops
+         * offer BC; phones ETC2 and ASTC. See `compressedUpload.ts`.
          */
-        if (adapter.features?.has('texture-compression-bc') === true) {
-            features.push('texture-compression-bc');
+        for (const family of [
+            'texture-compression-bc',
+            'texture-compression-etc2',
+            'texture-compression-astc',
+        ]) {
+            if (adapter.features?.has(family) === true)
+                features.push(family);
         }
         const descriptor = {};
         if (Object.keys(required).length > 0)

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

@@ -0,0 +1,29 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads with `texelFetch`, made once and never filtered. The twin of
+ * `webgpu/boneAnimations.ts`, at the same formats for the same reason: a turn in half floats jitters
+ * a crowd's hands at the frame's rate.
+ */
+import { type BoneAnimationHandle, type BoneAnimationTexels } from '../../boneAnimation.ts';
+/** A clip on the device, from `createBoneAnimation`. */
+export declare class GlBoneAnimation implements BoneAnimationHandle {
+    readonly bones: number;
+    readonly frames: number;
+    readonly framesPerSecond: number;
+    readonly boneScale: number;
+    readonly places: WebGLTexture;
+    readonly turns: WebGLTexture;
+    disposed: boolean;
+    constructor(gl: WebGL2RenderingContext, texels: BoneAnimationTexels);
+    dispose(gl: WebGL2RenderingContext): void;
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export declare class GlInstanceClocks {
+    readonly texture: WebGLTexture;
+    readonly staging: Float32Array;
+    private readonly width;
+    constructor(gl: WebGL2RenderingContext, capacity: number);
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(gl: WebGL2RenderingContext, count: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * A bone animation's textures on this backend, and a batch's clocks: what
+ * `shaders/boneAnimation.ts` reads with `texelFetch`, made once and never filtered. The twin of
+ * `webgpu/boneAnimations.ts`, at the same formats for the same reason: a turn in half floats jitters
+ * a crowd's hands at the frame's rate.
+ */
+import { CLOCK_TEXTURE_WIDTH, } from '../../boneAnimation.js';
+/**
+ * A float texture read by index: one level, nearest, clamped. Bound on unit 0, chosen rather than
+ * inherited, for the reason `oitPass.ts` gives: `bindTexture` binds to whatever unit is active, and
+ * a frame leaves that wherever its last pass finished.
+ */
+function floatTexture(gl, internal, width, height) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('boneAnimations: createTexture failed');
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, internal, width, height);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    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);
+    return texture;
+}
+/** A clip on the device, from `createBoneAnimation`. */
+export class GlBoneAnimation {
+    bones;
+    frames;
+    framesPerSecond;
+    boneScale;
+    places;
+    turns;
+    disposed = false;
+    constructor(gl, texels) {
+        this.bones = texels.bones;
+        this.frames = texels.frames;
+        this.framesPerSecond = texels.framesPerSecond;
+        this.boneScale = texels.boneScale;
+        const make = (data) => {
+            const texture = floatTexture(gl, gl.RGBA32F, texels.bones, texels.frames);
+            gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, texels.bones, texels.frames, gl.RGBA, gl.FLOAT, data);
+            return texture;
+        };
+        this.places = make(texels.places);
+        this.turns = make(texels.turns);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    dispose(gl) {
+        this.disposed = true;
+        gl.deleteTexture(this.places);
+        gl.deleteTexture(this.turns);
+    }
+}
+/** A batch's clocks: two floats an instance, wrapped onto rows `CLOCK_TEXTURE_WIDTH` wide. */
+export class GlInstanceClocks {
+    texture;
+    staging;
+    width;
+    constructor(gl, capacity) {
+        this.width = Math.max(1, Math.min(capacity, CLOCK_TEXTURE_WIDTH));
+        const rows = Math.max(1, Math.ceil(capacity / this.width));
+        this.staging = new Float32Array(this.width * rows * 2);
+        this.texture = floatTexture(gl, gl.RG32F, this.width, rows);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /** The rows that hold the first `count` instances, from `staging`. */
+    upload(gl, count) {
+        if (count <= 0)
+            return;
+        const rows = Math.ceil(count / this.width);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, this.width, rows, gl.RG, gl.FLOAT, this.staging);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    dispose(gl) {
+        gl.deleteTexture(this.texture);
+    }
+}

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

@@ -1,6 +1,7 @@
 import type { MeshInstances } from '../../instances.ts';
 import type { Mesh } from '../../mesh.ts';
 import type { FrustumPlanes } from '../../../math/frustum.ts';
+import { GlInstanceClocks, type GlBoneAnimation } from './boneAnimations.ts';
 /**
  * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
@@ -29,7 +30,10 @@ export declare class InstancedBatch {
     /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
     private keptRegioned;
     private readonly kept;
-    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean);
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    readonly animation: GlBoneAnimation | null;
+    readonly clocks: GlInstanceClocks | null;
+    constructor(gl: WebGL2RenderingContext, mesh: Mesh, capacity: number, cull?: boolean, animation?: GlBoneAnimation | null);
     upload(gl: WebGL2RenderingContext, data: MeshInstances): void;
     /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
     draw(gl: WebGL2RenderingContext, count: number): void;

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

@@ -1,5 +1,7 @@
 import { cullInstances, instancesBox } from '../../instanceCull.js';
 import { INSTANCE_FLOATS, INSTANCE_STRIDE, createMeshInstances, packInstances, } from '../../instances.js';
+import { packInstanceClocks } from '../../boneAnimation.js';
+import { GlInstanceClocks } from './boneAnimations.js';
 /**
  * One batch of a mesh: its per-instance buffer and a vertex array of its own.
  *
@@ -28,10 +30,15 @@ export class InstancedBatch {
     /** The survivors of a lightmapped batch's cull, made the first time one is culled. */
     keptRegioned = null;
     kept;
-    constructor(gl, mesh, capacity, cull = false) {
+    /** The bone animation every instance plays, and its clocks; null for a batch that plays none. */
+    animation;
+    clocks;
+    constructor(gl, mesh, capacity, cull = false, animation = null) {
         this.mesh = mesh;
         this.capacity = capacity;
         this.cull = cull;
+        this.animation = animation;
+        this.clocks = animation === null ? null : new GlInstanceClocks(gl, capacity);
         this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
         this.buffer = allocate(gl, capacity);
         this.vao = mesh.createInstanceArray(gl, this.buffer, INSTANCE_STRIDE);
@@ -56,6 +63,10 @@ export class InstancedBatch {
         packInstances(data, this.staging);
         gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
         gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.staging, 0, count * INSTANCE_FLOATS);
+        if (this.clocks !== null) {
+            packInstanceClocks(data, this.clocks.staging);
+            this.clocks.upload(gl, count);
+        }
     }
     /** Draw the first `count` uploaded instances: every draw but a culling camera draw. */
     draw(gl, count) {
@@ -88,6 +99,7 @@ export class InstancedBatch {
     dispose(gl) {
         gl.deleteVertexArray(this.vao);
         gl.deleteBuffer(this.buffer);
+        this.clocks?.dispose(gl);
         if (this.kept !== null) {
             gl.deleteVertexArray(this.kept.vao);
             gl.deleteBuffer(this.kept.buffer);

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

@@ -12,6 +12,7 @@ import type { ComputeDefinition, ComputeHandle } from '../../compute.ts';
 import type { PassDefinition, PassHandle } from '../../pass.ts';
 import type { Vec3 } from '../../../math/color.ts';
 import { GpuTimer } from '../../gpuTimer.ts';
+import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ColourGradeLut } from '../../colourGrade.ts';
 import { type BloomResponse } from '../../bloomChain.ts';
 import { LightField } from '../../driftLight/lightField.ts';
@@ -43,13 +44,14 @@ import type { AreaLightBuffer, AreaLightSource } from '../../areaLights.ts';
 import type { PhotometricProfile } from '../../iesProfile.ts';
 import type { ShadowLight } from '../../pointShadowSystem.ts';
 import type { ShadowCasters } from '../../shadowCasters.ts';
+import type { StaticDrawsHandle } from '../../staticDraws.ts';
 import type { RenderQuality, RenderQualityOptions } from '../../renderQuality.ts';
 import { Mesh } from '../../mesh.ts';
 import type { IncrementalMesh } from '../../mesh.ts';
 import type { MeshData } from '../../mesh.ts';
 import type { MeshOptions } from '../api.ts';
 import { SurfaceTexture } from '../../surfaceTexture.ts';
-import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
+import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import { PlumeRenderer } from '../../plumeRenderer.ts';
 import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
@@ -72,6 +74,8 @@ import { TextRenderer } from '../../textRenderer.ts';
 import { SdfTextRenderer } from '../../sdfTextRenderer.ts';
 import type { SdfFont } from '../../sdfFont.ts';
 import type { SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { DisplayRange } from '../../displayRange.ts';
+import { type FilmicCurve } from '../../filmicCurve.ts';
 import type { RenderBackend } from '../api.ts';
 import type { TextStyle } from '../../textLayout.ts';
 import { WindStreakRenderer } from '../../windStreakRenderer.ts';
@@ -79,6 +83,7 @@ import type { WindStreakOptions } from '../../windStreakRenderer.ts';
 import type { WindField } from '../../windField.ts';
 import type { FlockParams } from '../../flockRenderer.ts';
 import { InstancedBatch } from './instanced.ts';
+import type { BoneAnimationClip, BoneAnimationHandle } from '../../boneAnimation.ts';
 import type { InstancedOptions, MeshInstances } from '../../instances.ts';
 /** Reused each frame: which shader light slot each bound cubemap serves. */
 export type { ShadowCasterSink, ShadowCasters } from '../../shadowCasters.ts';
@@ -974,6 +979,10 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly reflectionQueue;
     /** Built on the first frame that submits a surface, and never for a scene with none. */
     private ssr;
+    /** The frame's materials' reflections, resolved; null where off. See `frameReflections.ts`. */
+    private readonly frameReflections;
+    /** Their two maps on the scene's framebuffer, null where they cannot be drawn. */
+    private readonly reflectionTargets;
     /** Said once where a reflection cannot be traced at all. */
     private reflectionsRefused;
     /** Where the frame's camera stands, which is what gives a reconstructed normal its sign. */
@@ -1033,6 +1042,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it asked to be and nothing about it changes.
      */
     private exposure;
+    /** The `filmic` curve's eight constants, held until `setFilmicCurve` is called again. */
+    private readonly filmConstants;
     /**
      * This frame's veil colour, and how much of it to composite. See `setFrameVeil`.
      *
@@ -1147,6 +1158,11 @@ export declare class WebGL2Renderer implements RendererApi {
     private readonly depthCutoutUniforms;
     private readonly depthInstancedCutoutProgram;
     private readonly depthInstancedCutoutUniforms;
+    /** A crowd's casters: the instanced depth programs that play a bone animation. */
+    private readonly depthAnimatedProgram;
+    private readonly depthAnimatedUniforms;
+    private readonly depthAnimatedCutoutProgram;
+    private readonly depthAnimatedCutoutUniforms;
     private readonly scatterDepthProgram;
     private readonly scatterDepthUniforms;
     /** The sun's static, moving and peeled maps, as layers of one array. See `shadowMap.ts`. */
@@ -1234,6 +1250,15 @@ export declare class WebGL2Renderer implements RendererApi {
     private warnedNoPointShadowArray;
     /** Said once, for the retired ambient dial. */
     private warnedEnvironmentAmbient;
+    /** The overlay the draws wear, `uOverlay`: see `setSurfaceOverlay`. */
+    private readonly overlayFloats;
+    /** Its atlas, and the 2D copy of it bound where the refraction copy goes. */
+    private overlayMaps;
+    private overlayTexture;
+    /** Whether this device's lit stage has room for the overlay's vectors: asked once. */
+    private overlayRoom;
+    private warnedOverlayRoom;
+    private warnedOverlayBlocks;
     /** Whether a probe is being baked, so the passes that would recurse into one can tell. */
     private probePassActive;
     /**
@@ -1558,6 +1583,8 @@ export declare class WebGL2Renderer implements RendererApi {
      * call. `init` runs now rather than at the first frame, because building a pipeline in the
      * frame loop is the allocation the house rules are about.
      */
+    /** Each registered pass's declared reads, as a mask, resolved once at registration. */
+    private readonly passReads;
     registerPass(definition: PassDefinition): PassHandle;
     /**
      * How many registered passes declare `prepare`, so a frame with none walks nothing.
@@ -1874,7 +1901,7 @@ export declare class WebGL2Renderer implements RendererApi {
      *
      * Not a hot path — it re-uploads the whole image and regenerates the mip chain.
      */
-    updateSurfaceTexture(texture: SurfaceTexture, source: TexImageSource): void;
+    updateSurfaceTexture(texture: SurfaceTexture, source: TexImageSource | CompressedTextureSource): void;
     disposeSurfaceTexture(texture: SurfaceTexture): void;
     /**
      * Choose the surface texture the following `drawMesh` calls sample, or `null` for none.
@@ -2015,6 +2042,37 @@ export declare class WebGL2Renderer implements RendererApi {
      * exactly as it did.
      */
     setSurfaceReflectivity(amount: number): void;
+    /**
+     * The reflectivity and environment gain the setters gave the pass, and the ones the material
+     * set now states, or null where it states none (`SurfaceMaterial.reflectivity`). A draw wears the
+     * material's where it has one and the pass's otherwise.
+     */
+    private passReflectivity;
+    private passEnvironmentGain;
+    private materialReflectivity;
+    private materialEnvironmentGain;
+    private writeEnvironmentDials;
+    /**
+     * The overlay the following draws wear — a rim of light, a dissolve, wrinkles by region — or null
+     * for none. Pass state, as the material is: `bindMeshPass` puts it back to none. See
+     * `surfaceOverlay.ts` for what it lays and `shaders/flat/overlay.ts` for how.
+     *
+     * **Refused, said once, where the lit stage has no room for it.** Fifteen vectors more than the
+     * program this device fits: counted from the source as `fitFlatProgram` counts, and on a device
+     * whose limit is the 256 an Adreno 740 reports, the eight-light build at 254 has none. The draws
+     * then wear nothing, which is the picture a game without the feature draws. Its atlas is bound as
+     * a 2D copy of its first layer, in the refraction copy's unit (`SurfaceTexture.flatLayer`); a
+     * compressed atlas has no copy and is read as none, also said once.
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
+    /** The overlay's atlas into the refraction copy's unit, as a 2D copy, or the empty texture. */
+    private bindOverlayMaps;
+    /** The most fragment uniform vectors this GPU offers a stage. */
+    private fragmentVectorLimit;
+    /** What the lit shader at this renderer's budget leaves of the limit, with no overlay. */
+    private overlayRoomLeft;
+    /** Whether the lit shader with the overlay compiled in fits this GPU: counted once. */
+    private overlayFits;
     /**
      * How bright the environment the surfaces drawn next reflect is. 1 is the default and identity.
      *
@@ -2190,6 +2248,40 @@ export declare class WebGL2Renderer implements RendererApi {
      * one. `Mesh.attachInstances` is what refuses a second, and says why.
      */
     createInstanced(mesh: Mesh, capacity: number, options?: InstancedOptions): InstancedBatch;
+    /**
+     * A bone animation an instanced batch can play (`InstancedOptions.animation`): per frame, a turn
+     * and a place for each bone, which every vertex of the batch's mesh follows — the bone its second
+     * coordinates' u names, times `boneScale` — at each instance's own moment of the clip. What a
+     * crowd is made of: every instance moves at the frame's rate on its own clock, in the colour pass
+     * and in every shadow, with nothing on the processor after this. See `boneAnimation.ts` for the
+     * clip's layout and the arithmetic, which both backends run.
+     *
+     * What it gives up against skinning is the blend: a vertex follows one bone. Refused, with what
+     * was wrong, for a clip whose numbers are not its size, or past 2,048 bones or frames.
+     */
+    createBoneAnimation(clip: BoneAnimationClip): BoneAnimationHandle;
+    /** Release a clip. A batch still playing it draws nothing, and casts nothing, after. */
+    disposeBoneAnimation(animation: BoneAnimationHandle): void;
+    /**
+     * The clock a bone animation plays by this frame, in seconds on the caller's clock: an instance's
+     * moment is this times its rate plus its phase (`MeshInstances.clocks`). **Set it before the
+     * shadows are drawn**, once a frame, as the wind is set: a shadow drawn under one clock and its
+     * caster under another come apart at the frame's rate. 0 until set, which holds every crowd at
+     * the moment its phases name.
+     */
+    setAnimationTime(seconds: number): void;
+    /** The clock `setAnimationTime` set. */
+    private animationTime;
+    /**
+     * An animated batch's clip, clocks and numbers into whichever program is bound: the three vertex
+     * textures on units of their own (`lightBudget.ts`), the clip's speed and bone scale, the clock.
+     */
+    private bindAnimation;
+    /** The animated instanced program, compiled on first use. See `ensureInstancedProgram`. */
+    private flatAnimatedProgram;
+    private flatAnimatedUniforms;
+    /** Compile the animated variant, once, and feed it this frame's pass state. */
+    private ensureAnimatedProgram;
     /** Push placement and colour. Only the live prefix. */
     uploadInstanced(batch: InstancedBatch, data: MeshInstances): void;
     /** Draw every live instance, opaque. */
@@ -2724,6 +2816,43 @@ export declare class WebGL2Renderer implements RendererApi {
      */
     drawSceneCasters(casters: ShadowCasters): void;
     drawShadowCasters(casters: ShadowCasters): void;
+    /**
+     * Draws that do not change between frames, enumerated once and kept: what a stage, a set or any
+     * world that stands still draws, recorded so a frame replays it rather than issuing it.
+     *
+     * **The same enumeration `drawSceneCasters` takes**, called once, here: rigid meshes and instanced
+     * batches, each with its material. A skinned mesh or a scatter batch is refused by name, since
+     * both change every frame. What it captures is what the enumeration said at the time — the
+     * matrices and the instance counts are copied, so a caller's scratch is free to move on — while
+     * the meshes, batches, textures and materials stay the caller's: a list must be disposed, or made
+     * again, before anything it holds is, and made again when a material it holds is changed.
+     *
+     * **What it is for is the frame's processor time.** WebGPU records the list into a render bundle
+     * per view and replays it with one call, where a draw issued a frame at a time costs its encoding
+     * every frame and again for every view that draws it. This backend has no bundles and replays the
+     * entries through the scene-caster path every frame, at the cost a frame drawing them itself pays;
+     * the picture is the same.
+     *
+     * What a list gives up against drawing each frame is culling: every entry is drawn in every view,
+     * because a bundle cannot leave one out. A world split into lists by region culls by list.
+     */
+    createStaticDraws(casters: ShadowCasters): StaticDrawsHandle;
+    /**
+     * Draw a list into the open mesh pass, under the camera, the lights and the fog `bindMeshPass`
+     * set — the frame's, a mirror's, a capture's. Opaque draws, through each entry's material.
+     *
+     * **Its draws are rigid and wear no overlay**, so a skin palette, morph weights, cloth or a surface
+     * overlay set before it is put back to none, as `bindMeshPass` puts an overlay back; and no
+     * material is left set after it, which is what `setMaterial(null)` leaves. The state a pass set —
+     * the grain, the relief, the fog, the grade — is the list's to draw with, as it is any draw's, and
+     * a list drawn under a different one is recorded again for it on WebGPU.
+     */
+    drawStaticDraws(draws: StaticDrawsHandle): void;
+    /** Release a list. Its meshes, batches and materials are the caller's and are not released. */
+    disposeStaticDraws(draws: StaticDrawsHandle): void;
+    /** A disposed list drawn, said once: the frame loop does not throw. */
+    private warnStaticDisposed;
+    private warnedStaticDisposed;
     /**
      * Draw the pass's glass twice: where the nearest pane is, and what the panes let through.
      *
@@ -3015,8 +3144,17 @@ export declare class WebGL2Renderer implements RendererApi {
      * Set before `beginFrame` and held until changed, like `setSpeedRush`, which it sits
      * beside for the same reason: both describe how the finished image is presented rather
      * than anything in the world.
+     *
+     * `maxShare` is the longest smear, as a share of the frame (0.03 unless given, at most half): a
+     * fast turn softens the frame rather than erasing it. **Each drawn object's own motion is
+     * followed only under a reconstruction on WebGPU**, which draws the motion target it reads; here,
+     * and on WebGPU without one, the camera's motion alone smears the frame, and a draw that names
+     * where it was last frame is told so once.
      */
-    setCameraMotionBlur(scale: number): void;
+    setCameraMotionBlur(scale: number, maxShare?: number): void;
+    /** The longest smear, as a share of the frame. See `setCameraMotionBlur`. */
+    private motionBlurMax;
+    private warnedObjectBlur;
     /**
      * The camera has cut: this frame is a new shot, not the next moment of the last one.
      *
@@ -3178,6 +3316,30 @@ export declare class WebGL2Renderer implements RendererApi {
      * black frame with a sign error in it.
      */
     setOutputExposure(exposure: number): void;
+    /**
+     * The `filmic` curve this and every later frame is graded through, until it is set again: a
+     * grading volume's five numbers, solved once here into the constants the resolve reads. Ignored
+     * unless `outputTransform` is `filmic`. A number out of range is clamped into it and said once,
+     * since a frame loop must not throw. See `filmicCurve.ts`.
+     */
+    setFilmicCurve(curve: FilmicCurve): void;
+    private warnedFilmClamped;
+    /**
+     * The range the frame goes out in: `'high'` where the profile asked for `highDynamicRange`, the
+     * frame holds light past white and the display shows it — on WebGPU — and `'standard'` otherwise.
+     * **Always standard here**: this backend draws into a canvas of eight bits a channel, which has
+     * nothing above white to show. Typed as the question rather than this backend's answer, because
+     * the shared surface is derived from this class.
+     */
+    readonly displayRange: DisplayRange;
+    /** Why it is that range, in words, for a game choosing its look and for a bug report. */
+    get displayRangeReason(): string;
+    /**
+     * How bright paper white and the display's peak are, in one unit, held until changed: their
+     * ratio is how far above white the highlights may run where `displayRange` is `'high'`, and
+     * nothing changes where it is standard, which is always here.
+     */
+    setDisplayLuminance(paperWhite: number, peak: number): void;
     /**
      * Composite a flat colour over the finished frame — for a cut dipping to white or to black.
      *
@@ -3242,6 +3404,14 @@ export declare class WebGL2Renderer implements RendererApi {
      * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
      */
     setVignette(strength: number): void;
+    /**
+     * The lens's colour fringe, held until changed: `intensity` is a percentage, 0 is none, and red
+     * and green are pulled toward the centre by their wavelength's distance from blue, growing from
+     * `start` — a share of the half-frame, 0 the centre — to the whole of it at the edge. Applied to
+     * scene light at the composite's first read. Needs `screenEffects`, and says so once rather than
+     * doing nothing. See `shaders/fringe.ts`.
+     */
+    setChromaticAberration(intensity: number, start?: number): void;
     /**
      * Film grain, held until changed: an amplitude in display values (0 is none, 0.03 is a fine
      * grain) and this frame's seed. **The seed is the caller's**, because the engine takes time from
@@ -3517,12 +3687,18 @@ export declare class WebGL2Renderer implements RendererApi {
      * here, so there is no motion target for this to be written into, and a mover passed here is
      * neither read nor advanced.
      */
-    _previousModel?: ReadonlyMat4 | Mover | null): void;
+    previousModel?: ReadonlyMat4 | Mover | null): void;
     /**
      * Whether a skin draw now draws its two halves: the profile asked, the frame has not spread its
      * skin yet, this is the frame's own picture — not a mirror's or a probe's, nor an overlay after
      * the frame — and the blur's target can be had.
      */
+    /**
+     * Whether a draw now is the frame's own, opaque and lit, and so writes the two maps beside its
+     * colour: not a mirror's, a probe's or a capture's, whose framebuffers have no maps, and not after
+     * the frame. See `reflectionSurfaceTargets.ts`.
+     */
+    private reflectionKeeps;
     private skinSplits;
     /**
      * Spread the frame's skin and add it back: once, at the first blended draw or at the frame's end.