@driftengine/core 4.9.0 → 4.11.0

package/dist/render/surfaceTexture.d.ts

@@ -8,8 +8,10 @@
  * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
  * so a merged block wearing forty facades is one draw.
  */
+import type { SurfaceLayers } from './surfaceLayers.ts';
+import type { SurfaceProjection } from './surfaceProjection.ts';
 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 +109,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 +143,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 +182,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.
      *
@@ -180,6 +198,34 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * and an 8-bit frame clips the brighter peak without `hdrScene`.
      */
     physicalSpecular?: boolean;
+    /**
+     * Texture coordinates from where a point is in the world rather than from the mesh: `'planar'`
+     * across the horizontal axes for ground, `'triplanar'` on three planes for walls and rock, at so
+     * many repeats a metre. Absent, the mesh's, as every material's were. **A lit switch**, compiled in
+     * the first time a material asks, so a scene that never asks pays nothing. See
+     * `surfaceProjection.ts` for what it gives up.
+     */
+    projection?: SurfaceProjection | null;
+    /**
+     * How much light from behind a thin surface lets through, 0 to 1: a banner lit from behind, a
+     * leaf against the sun, a lampshade. The light falling on the far side — the sun, lamps, area
+     * lights, DriftLight — reaches the eye through the surface, coloured by its own colour; a metal
+     * lets none through. 0, the default, is every material as it was. Two-sided or not: a one-sided
+     * surface seen from its front shows the light behind it as well.
+     *
+     * **What it gives up**: a thin surface, not a volume, so a thick one lets through as much as a
+     * sheet; the light behind is not blurred by the surface; and none of it on glass, which lets
+     * light through by its own rule (`TranslucentMeshOptions.glass`).
+     */
+    diffuseTransmission?: number;
+    /**
+     * Up to five layers blended by a mask, each at its own repeat: `albedo`, `normal` and `orm` arrays
+     * whose layers are the material's, and a mask laying each over the ones before it. Absent, the
+     * material is one layer, as every material was. **A lit switch**, compiled in the first time a
+     * material asks. The mask is read where `modelMap` goes, so a material carries one or the other.
+     * See `surfaceLayers.ts` for what it gives up.
+     */
+    layers?: SurfaceLayers<Texture> | null;
 }
 export interface SurfaceTextureOptions {
     /**
@@ -275,7 +321,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 +351,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/dist/render/vertexPacking.d.ts

@@ -0,0 +1,48 @@
+import type { MeshData } from '@driftengine/drft';
+/**
+ * How each of a mesh's vertex attributes travels to the device, decided once from its data and
+ * bound by each backend: as floats, as sixteen-bit fixed point, or as one value every vertex
+ * shares.
+ *
+ * **Only what reads back as it went, or near enough that no picture can tell.** One value every
+ * vertex shares is exact, and is a constant rather than a stream: a colour or an emissive naming
+ * no difference between vertices costs nothing a vertex, where both were always stored per vertex.
+ * A unit direction — a normal, a tangent and its handedness — in sixteen-bit signed fixed point is
+ * within 1/32767 a component, a few thousandths of a degree: measured against floats, 12 pixels of
+ * 921,600 moved in one published scene, by 2 of 255 on average, and none in the other eight.
+ * Colours and skin weights inside [0, 1] in sixteen-bit unsigned fixed point are within 1/65535. A
+ * textured vertex with a tangent frame, white and not glowing, goes from 64 bytes to 36 on WebGPU.
+ *
+ * **What it gives up.** Eight-bit normals would save four bytes more and are not taken: a normal in
+ * steps of 1/127 can band a highlight. **Texture coordinates stay floats**, in any range: a
+ * coordinate on a tile's far edge rounds past it in sixteen-bit fixed point, by 1/131,070, and a
+ * pixel there samples the neighbouring tile of an atlas — measured as 29 pixels moved by 62 of 255
+ * in the voxel scene, every one at a face's edge — and a half float, which steps by a 2048th near
+ * 1.0, is worse. A dynamic mesh's normals stay floats, because each rewrite would have to be packed
+ * on the CPU. What would make this wrong is a value outside its range, which the range check sends
+ * to floats rather than clamping, or a shader reading an attribute as something other than the
+ * value it carries.
+ */
+/** Floats; sixteen-bit fixed point, signed or not; or one value for every vertex. */
+export type AttributePacking = 'float' | 'snorm16' | 'unorm16' | 'constant';
+/** The attributes this decides for. Every other one travels as floats. */
+export declare const PACKED_ATTRIBUTES: readonly ['normals', 'tangents', 'colors', 'emissive', 'weights', 'weights2'];
+export type PackedAttribute = (typeof PACKED_ATTRIBUTES)[number];
+export type VertexPacking = Readonly<Record<PackedAttribute, AttributePacking>>;
+/** The choice for this mesh. `dynamic` is a mesh whose positions and normals are rewritten. */
+export declare function vertexPackingOf(data: MeshData, dynamic: boolean): VertexPacking;
+/**
+ * What 1 is in each fixed point, the values WebGPU's `snorm16` and `unorm16` and WebGL2's
+ * normalised `SHORT` and `UNSIGNED_SHORT` divide by. A value is stored rounded to nearest, so 1, 0
+ * and -1 come back exactly.
+ */
+export declare const SNORM16_ONE = 32767;
+export declare const UNORM16_ONE = 65535;
+/** One value in the fixed point whose 1 is `one`, rounded to nearest: the only place it is. */
+export declare function toFixed16(value: number, one: number): number;
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export declare function fixedArray(values: Float32Array, packing: 'snorm16' | 'unorm16'): Int16Array | Uint16Array;
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export declare function packingFor(packing: VertexPacking, name: string): AttributePacking;
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export declare function sharedValue(values: Float32Array, width: number): number[];

package/dist/render/vertexPacking.js

@@ -0,0 +1,68 @@
+/** The attributes this decides for. Every other one travels as floats. */
+export const PACKED_ATTRIBUTES = [
+    'normals',
+    'tangents',
+    'colors',
+    'emissive',
+    'weights',
+    'weights2',
+];
+/** The choice for this mesh. `dynamic` is a mesh whose positions and normals are rewritten. */
+export function vertexPackingOf(data, dynamic) {
+    return {
+        normals: dynamic ? 'float' : fixedOrFloat(data.normals, -1),
+        tangents: fixedOrFloat(data.tangents, -1),
+        colors: shared(data.colors, 3) ? 'constant' : fixedOrFloat(data.colors, 0),
+        emissive: shared(data.emissive, 1) ? 'constant' : 'float',
+        weights: fixedOrFloat(data.weights, 0),
+        weights2: fixedOrFloat(data.weights2, 0),
+    };
+}
+/**
+ * What 1 is in each fixed point, the values WebGPU's `snorm16` and `unorm16` and WebGL2's
+ * normalised `SHORT` and `UNSIGNED_SHORT` divide by. A value is stored rounded to nearest, so 1, 0
+ * and -1 come back exactly.
+ */
+export const SNORM16_ONE = 32767;
+export const UNORM16_ONE = 65535;
+/** One value in the fixed point whose 1 is `one`, rounded to nearest: the only place it is. */
+export function toFixed16(value, one) {
+    return Math.round(value * one);
+}
+/** An attribute's values in its fixed point, tightly, for a backend reading separate arrays. */
+export function fixedArray(values, packing) {
+    const out = packing === 'snorm16' ? new Int16Array(values.length) : new Uint16Array(values.length);
+    const one = packing === 'snorm16' ? SNORM16_ONE : UNORM16_ONE;
+    for (let at = 0; at < values.length; at++)
+        out[at] = toFixed16(values[at], one);
+    return out;
+}
+/** How `name` travels under this packing: floats for an attribute it does not decide for. */
+export function packingFor(packing, name) {
+    return packing[name] ?? 'float';
+}
+/** The value every vertex shares, for an attribute packed as `'constant'`. */
+export function sharedValue(values, width) {
+    return Array.from(values.subarray(0, width));
+}
+/** Fixed point where every value lies in [low, 1]; floats otherwise, and for a NaN. */
+function fixedOrFloat(values, low) {
+    if (values === undefined)
+        return 'float';
+    for (let at = 0; at < values.length; at++) {
+        const value = values[at];
+        if (!(value >= low && value <= 1))
+            return 'float';
+    }
+    return low < 0 ? 'snorm16' : 'unorm16';
+}
+/** Whether every vertex holds the first vertex's value. Not for a mesh of none. */
+function shared(values, width) {
+    if (values.length < width)
+        return false;
+    for (let at = width; at < values.length; at++) {
+        if (values[at] !== values[at % width])
+            return false;
+    }
+    return true;
+}

package/package.json

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

package/src/index.ts

@@ -539,8 +539,8 @@ export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
  * A skinned cloth solved where the renderer can: compute on WebGPU, the CPU under WebGL2. A function
  * rather than a renderer method so only a game that imports it carries the solver.
  */
-export { createSkinnedCloth } from './render/skinnedClothRun.ts';
-export type { SkinnedClothSolver } from './render/skinnedClothRun.ts';
+export { createSkinnedCloth, createSkinnedClothSet } from './render/skinnedClothRun.ts';
+export type { SkinnedClothSet, SkinnedClothSolver } from './render/skinnedClothRun.ts';
 
 /**
  * What a frame asked of a backend, against the ceilings that backend imposes.
@@ -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.
@@ -648,6 +652,7 @@ export type {
   DirectionalShadowDepthLayers,
   GlassShadows,
   OutputTransform,
+  PipelineCompile,
   RenderQuality,
   RenderQualityOptions,
   ShadowFilterTaps,
@@ -659,13 +664,16 @@ export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.ts'
 export { MAX_CLUSTERED_LIGHTS } from './render/clusteredLights.ts';
 export { SurfaceTexture } from './render/surfaceTexture.ts';
 export type { SurfaceMaterial, SurfaceTextureOptions } from './render/surfaceTexture.ts';
+export type { SurfaceProjection } from './render/surfaceProjection.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;

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

@@ -0,0 +1,105 @@
+/**
+ * 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,
+  type BoneAnimationHandle,
+  type BoneAnimationTexels,
+} from '../../boneAnimation.ts';
+
+/**
+ * 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: WebGL2RenderingContext,
+  internal: number,
+  width: number,
+  height: number,
+): WebGLTexture {
+  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 implements BoneAnimationHandle {
+  readonly bones: number;
+  readonly frames: number;
+  readonly framesPerSecond: number;
+  readonly boneScale: number;
+  readonly places: WebGLTexture;
+  readonly turns: WebGLTexture;
+  disposed = false;
+
+  constructor(gl: WebGL2RenderingContext, texels: BoneAnimationTexels) {
+    this.bones = texels.bones;
+    this.frames = texels.frames;
+    this.framesPerSecond = texels.framesPerSecond;
+    this.boneScale = texels.boneScale;
+    const make = (data: Float32Array): WebGLTexture => {
+      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: WebGL2RenderingContext): void {
+    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 {
+  readonly texture: WebGLTexture;
+  readonly staging: Float32Array;
+  private readonly width: number;
+
+  constructor(gl: WebGL2RenderingContext, capacity: number) {
+    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: WebGL2RenderingContext, count: number): void {
+    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: WebGL2RenderingContext): void {
+    gl.deleteTexture(this.texture);
+  }
+}