@driftengine/core 4.9.0 → 4.10.0

package/dist/render/shaders/outputTransform.d.ts

@@ -48,3 +48,10 @@ export declare const HIGHLIGHT_SHOULDER_GLSL = "\nvec3 highlightShoulder(vec3 c)
  * a branch that costs one compare.
  */
 export declare const OUTPUT_TRANSFORM_GLSL = "\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform;\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure;\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n";
+/**
+ * The same, for the lit stage, whose two uniforms live in its material block: a draw that opts out
+ * of the grade sets them, so they change with the material and not with the pass. See
+ * `hoistUniformBlock` in `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs
+ * the same program it always has.
+ */
+export declare const LIT_OUTPUT_TRANSFORM_GLSL = "\n/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */\nuniform int uOutputTransform; // wgsl:material\n/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */\nuniform float uOutputExposure; // wgsl:material\n\n/*\n * ACES: the reference fit, not the cheap one.\n *\n * This was Narkowicz's single rational function, on the argument that the difference from\n * the reference curve is invisible next to the gain. That argument holds for a look and\n * fails for a *match*, which is what this option is for \u2014 aces exists so a world ported\n * from three.js reads the same, and three.js applies the full fit: into AP1 through\n * ACESInputMat, the RRT and ODT together, then back out through ACESOutputMat.\n *\n * The two curves are not a shade apart. Narkowicz is markedly brighter through the\n * midtones, which is exactly where an interior scene lives, and it is a large part of a\n * measured ~1.7x that survived correcting the colour space and the missing Lambert pi.\n * An approximation of a standard is the wrong thing to hold when the standard is the\n * specification.\n */\nvec3 rrtAndOdtFit(vec3 v) {\n  vec3 a = v * (v + 0.0245786) - 0.000090537;\n  vec3 b = v * (0.983729 * v + 0.4329510) + 0.238081;\n  return a / b;\n}\n\nvec3 acesFilmic(vec3 x) {\n  /*\n   * Exposure first, because a tone curve is only defined relative to one.\n   *\n   * The reference RRT and ODT are graded for a dark cinema. Every renderer that ships ACES\n   * scales its input to suit whatever it is actually shown on, and the factor each one\n   * picks is a *look*, not a standard - so this engine takes no position and reads it from\n   * the caller. Neutral by default, which is the reference grade unmodified. three.js's own\n   * pick is 1 / 0.6, for a consumer matching one.\n   */\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: sRGB -> XYZ -> D65_2_D60 -> AP1 -> RRT_SAT.\n  const mat3 ACES_INPUT = mat3(\n    0.59719, 0.07600, 0.02840,\n    0.35458, 0.90834, 0.13383,\n    0.04823, 0.01566, 0.83777\n  );\n  // ODT_SAT -> XYZ -> D60_2_D65 -> sRGB.\n  const mat3 ACES_OUTPUT = mat3(\n     1.60475, -0.10208, -0.00327,\n    -0.53108,  1.10813, -0.07276,\n    -0.07367, -0.00605,  1.07602\n  );\n  return clamp(ACES_OUTPUT * rrtAndOdtFit(ACES_INPUT * x), 0.0, 1.0);\n}\n\n/*\n * Linear to sRGB. The piecewise form rather than a plain pow: the linear toe near black\n * is where banding lives in an 8-bit buffer, and the cheap approximation puts it in the\n * wrong place.\n */\nvec3 linearToSrgb(vec3 c) {\n  vec3 low = c * 12.92;\n  vec3 high = 1.055 * pow(max(c, vec3(0.0)), vec3(1.0 / 2.4)) - 0.055;\n  return mix(high, low, step(c, vec3(0.0031308)));\n}\n\n\nvec3 highlightShoulder(vec3 c) {\n  float m = max(c.r, max(c.g, c.b));\n  if (m <= 0.8) return c;\n  float e = m - 0.8;\n  return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);\n}\n\nvec3 applyOutputTransform(vec3 c) {\n  if (uOutputTransform == 0) return c;\n  if (uOutputTransform == 2) c = acesFilmic(c);\n  if (uOutputTransform == 3) c = highlightShoulder(c * uOutputExposure);\n  return linearToSrgb(c);\n}\n";

package/dist/render/shaders/outputTransform.js

@@ -46,20 +46,8 @@ vec3 highlightShoulder(vec3 c) {
   return c * ((0.8 + 0.2 * e / (e + 0.2)) / m);
 }
 `;
-/**
- * `uOutputTransform` and `uOutputExposure`, the fit, and `applyOutputTransform`.
- *
- * Declares its own two uniforms, so including it is the whole of what a fragment stage has to
- * do besides calling it. Both are ints and floats rather than defines because the choice is a
- * caller's, per draw, and a permutation per output transform would double a pipeline count for
- * a branch that costs one compare.
- */
-export const OUTPUT_TRANSFORM_GLSL = `
-/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
-uniform int uOutputTransform;
-/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
-uniform float uOutputExposure;
-
+/** The fit and `applyOutputTransform`, below whichever declaration of the two uniforms. */
+const OUTPUT_TRANSFORM_BODY_GLSL = `
 /*
  * ACES: the reference fit, not the cheap one.
  *
@@ -126,3 +114,29 @@ vec3 applyOutputTransform(vec3 c) {
   return linearToSrgb(c);
 }
 `;
+/**
+ * `uOutputTransform` and `uOutputExposure`, the fit, and `applyOutputTransform`.
+ *
+ * Declares its own two uniforms, so including it is the whole of what a fragment stage has to
+ * do besides calling it. Both are ints and floats rather than defines because the choice is a
+ * caller's, per draw, and a permutation per output transform would double a pipeline count for
+ * a branch that costs one compare.
+ */
+export const OUTPUT_TRANSFORM_GLSL = `
+/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
+uniform int uOutputTransform;
+/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
+uniform float uOutputExposure;
+${OUTPUT_TRANSFORM_BODY_GLSL}`;
+/**
+ * The same, for the lit stage, whose two uniforms live in its material block: a draw that opts out
+ * of the grade sets them, so they change with the material and not with the pass. See
+ * `hoistUniformBlock` in `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs
+ * the same program it always has.
+ */
+export const LIT_OUTPUT_TRANSFORM_GLSL = `
+/** 0 none, 1 sRGB, 2 ACES then sRGB, 3 the highlight shoulder then sRGB. See renderQuality.ts. */
+uniform int uOutputTransform; // wgsl:material
+/** Scales the scene into the tone curve. 1 is the reference grade. See renderQuality.ts. */
+uniform float uOutputExposure; // wgsl:material
+${OUTPUT_TRANSFORM_BODY_GLSL}`;

package/dist/render/shaders/vertexChannel.d.ts

@@ -18,6 +18,13 @@
  * 4.1 KB across five, so a `#if` here would buy nothing measurable and cost a variant axis.
  */
 export declare const CHANNEL_ATTRIBUTE = "\nlayout(location = 13) in vec4 aChannel;\n\n/*\n * The frame's wind, already converted by `resolveScatterDeform` \u2014 a normalised direction, metres\n * of bend, a gust amplitude and a scaled clock.\n *\n * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A\n * second conversion here would be a second wind however identical its inputs, and the failure is\n * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the\n * grass beneath it leans another, with no single element looking wrong. See \"One wind, sampled\n * once\" in AGENTS.md.\n */\nuniform vec2 uWindDirection;\nuniform float uWindSpeed;\nuniform float uWindGust;\nuniform float uWindTime;\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase;\n";
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export declare const LIT_CHANNEL_ATTRIBUTE = "\nlayout(location = 13) in vec4 aChannel;\n\n/*\n * The frame's wind, already converted by `resolveScatterDeform` \u2014 a normalised direction, metres\n * of bend, a gust amplitude and a scaled clock.\n *\n * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A\n * second conversion here would be a second wind however identical its inputs, and the failure is\n * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the\n * grass beneath it leans another, with no single element looking wrong. See \"One wind, sampled\n * once\" in AGENTS.md.\n */\nuniform vec2 uWindDirection; // wgsl:view\nuniform float uWindSpeed; // wgsl:view\nuniform float uWindGust; // wgsl:view\nuniform float uWindTime; // wgsl:view\n/* Spatial frequency of the travelling gust, per metre. */\nuniform vec2 uWindSpatialPhase; // wgsl:view\n";
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/dist/render/shaders/vertexChannel.js

@@ -37,6 +37,32 @@ uniform float uWindTime;
 /* Spatial frequency of the travelling gust, per metre. */
 uniform vec2 uWindSpatialPhase;
 `;
+/**
+ * The same, for the lit stage, whose wind lives in its view block: the frame's and not the draw's,
+ * so a draw's own block does not change when the wind does. See `hoistUniformBlock` in
+ * `scripts/wgsl/transform.mjs`. Text otherwise identical, so WebGL2 runs the same program it always
+ * has; the depth stage keeps the unmarked chunk, having no view block.
+ */
+export const LIT_CHANNEL_ATTRIBUTE = `
+layout(location = 13) in vec4 aChannel;
+
+/*
+ * The frame's wind, already converted by \`resolveScatterDeform\` — a normalised direction, metres
+ * of bend, a gust amplitude and a scaled clock.
+ *
+ * **The same numbers the scatter batch reads, and that is the rule rather than an economy.** A
+ * second conversion here would be a second wind however identical its inputs, and the failure is
+ * not localised: it shows up as a scene that does not cohere, a canopy leaning one way while the
+ * grass beneath it leans another, with no single element looking wrong. See "One wind, sampled
+ * once" in AGENTS.md.
+ */
+uniform vec2 uWindDirection; // wgsl:view
+uniform float uWindSpeed; // wgsl:view
+uniform float uWindGust; // wgsl:view
+uniform float uWindTime; // wgsl:view
+/* Spatial frequency of the travelling gust, per metre. */
+uniform vec2 uWindSpatialPhase; // wgsl:view
+`;
 /**
  * Where the wind puts a vertex, given how much of it that vertex takes.
  *

package/dist/render/staticDraws.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Draws that do not change between frames, captured once from an enumeration and replayed into any
+ * colour pass: what `createStaticDraws` keeps, and the one rule both backends replay it by.
+ *
+ * **Captured, not referenced.** An enumeration is a closure over the caller's state, written to
+ * allocate nothing, so it hands a sink its scratch: the matrix it fills for every entry and the
+ * count it rewrites for the next batch. A list kept across frames copies both when it is made, so
+ * what it draws is what the enumeration said then. Meshes, batches and materials are held by
+ * reference: they are the caller's, and disposing one a list still holds is the caller's error.
+ *
+ * **Rigid meshes and instanced batches only.** A skinned mesh is posed every frame and a scatter
+ * batch bends with every frame's wind, so neither can be kept, and both are refused by name rather
+ * than captured in the pose they happened to have. A caller draws them each frame as it always has.
+ *
+ * What a backend does with the list is its own: WebGL2 replays the entries every frame through
+ * the scene-caster path, and WebGPU records them once into a render bundle per view. See
+ * `RendererApi.createStaticDraws` for what a caller is promised, which is the same on both.
+ */
+import type { InstancedHandle, MeshHandle } from './backend/api.ts';
+import type { MeshInstances } from './instances.ts';
+import type { SceneCasterMaterial, ShadowCasterSink, ShadowCasters } from './shadowCasters.ts';
+/** A list from `createStaticDraws`. Opaque but for its size. */
+export interface StaticDrawsHandle {
+    /** How many entries it holds: meshes and batches, a batch counting once. */
+    readonly draws: number;
+}
+/** One captured entry. */
+export type StaticEntry = {
+    readonly kind: 'mesh';
+    readonly mesh: MeshHandle;
+    readonly model: Float32Array;
+    readonly material: SceneCasterMaterial;
+} | {
+    readonly kind: 'instanced';
+    readonly batch: InstancedHandle;
+    readonly data: MeshInstances;
+    readonly material: SceneCasterMaterial;
+};
+/** What both backends hold: the entries, and whether the list has been disposed. */
+export interface StaticDrawsList extends StaticDrawsHandle {
+    readonly entries: readonly StaticEntry[];
+    disposed: boolean;
+}
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export declare function captureStaticDraws(casters: ShadowCasters): StaticDrawsList;
+/** Hand every entry to `sink`, in the order it was captured. */
+export declare function replayStaticDraws(list: StaticDrawsList, sink: ShadowCasterSink): void;

package/dist/render/staticDraws.js

@@ -0,0 +1,43 @@
+/** Enumerate `casters` once into a list. Allocates: it runs when the list is made, not per frame. */
+export function captureStaticDraws(casters) {
+    const entries = [];
+    const sink = {
+        mesh: (mesh, model, material) => {
+            entries.push({
+                kind: 'mesh',
+                mesh,
+                model: new Float32Array(model),
+                material: material ?? null,
+            });
+        },
+        instanced: (batch, data, material) => {
+            /* The batch's placements are on the device already; the count is the caller's scratch. */
+            entries.push({ kind: 'instanced', batch, data: { ...data }, material: material ?? null });
+        },
+        skinnedMesh: () => {
+            throw new Error('createStaticDraws: a skinned mesh is posed every frame, so a list kept across frames ' +
+                'cannot hold one. Draw it each frame, with drawMesh or drawSceneCasters.');
+        },
+        scatter: () => {
+            throw new Error('createStaticDraws: a scatter batch bends with every frame’s wind, so a list kept across ' +
+                'frames cannot hold one. Draw it each frame with drawScatter.');
+        },
+    };
+    casters(sink);
+    return {
+        entries,
+        get draws() {
+            return entries.length;
+        },
+        disposed: false,
+    };
+}
+/** Hand every entry to `sink`, in the order it was captured. */
+export function replayStaticDraws(list, sink) {
+    for (const entry of list.entries) {
+        if (entry.kind === 'mesh')
+            sink.mesh(entry.mesh, entry.model, entry.material);
+        else
+            sink.instanced?.(entry.batch, entry.data, entry.material);
+    }
+}

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,9 @@ 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;
@@ -303,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.

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,8 @@ 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;
@@ -101,23 +103,14 @@ export class SurfaceTexture {
             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. */
@@ -155,10 +148,14 @@ 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;
@@ -171,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.9.0",
+  "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.9.0",
-    "@driftengine/physics": "4.9.0",
+    "@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.9.0",
-    "@driftengine/network": "4.9.0",
-    "@driftengine/texture": "4.9.0"
+    "@driftengine/nav": "4.10.0",
+    "@driftengine/network": "4.10.0",
+    "@driftengine/texture": "4.10.0"
   }
 }

package/src/index.ts

@@ -568,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.
@@ -660,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/backend/api.ts

@@ -8,7 +8,7 @@ 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 { CompressedTextureSource, SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
 import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
@@ -415,12 +415,22 @@ export type RendererApi = Omit<
   ): 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;
 

package/src/render/backend/select.ts

@@ -248,12 +248,17 @@ async function acquireWebGpu(
       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',
+    ] as const) {
+      if (adapter.features?.has(family) === true) features.push(family);
     }
     const descriptor: GPUDeviceDescriptor = {};
     if (Object.keys(required).length > 0) descriptor.requiredLimits = required;