@driftengine/core 4.8.2 → 4.8.4

package/src/render/skinnedClothRun.ts

@@ -0,0 +1,128 @@
+/**
+ * A skinned cloth for a renderer: `@driftengine/physics`' solver, run as compute on WebGPU — the
+ * particles never leave the device — and as `SkinnedCloth` on the CPU under WebGL2, which has no
+ * compute. One schedule, `ClothControl`, and the same kernels either way; what a frame draws is
+ * `particles`, through `setCloth(binding, cloth.particles)`.
+ *
+ * **A function rather than renderer methods, so a game pays for it only by importing it.** See
+ * `backend/webgpu/computeHost.ts` for the door it reaches the device through, and why.
+ *
+ * **The CPU fallback's cost**, measured on a desktop part: a few hundred particles are a
+ * millisecond a frame on the main thread, and 4,500 are twenty — a garment that size wants the
+ * device. The device solver ran 4,500 particles in 0.65 ms a frame, most of it the dispatches
+ * rather than the particles (`demo/dev/skinnedCloth.html?bench=1`).
+ */
+import { SkinnedCloth } from '@driftengine/physics';
+import type { SkinnedClothSetup } from '@driftengine/physics';
+
+import type { ClothParticlesHandle, RendererApi } from './backend/api.ts';
+import { computeHostOf } from './backend/webgpu/computeHost.ts';
+import type { ComputeHost } from './backend/webgpu/computeHost.ts';
+import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.ts';
+
+/** A garment a renderer solves, from `createSkinnedCloth`. */
+export interface SkinnedClothSolver {
+  /** What `setCloth(binding, particles)` draws the garment's bound meshes by. */
+  readonly particles: ClothParticlesHandle;
+  /** Where the solver runs: on the device, or on the CPU beneath a backend without compute. */
+  readonly runsOn: 'device' | 'cpu';
+  /**
+   * One frame: the rig's pose — each joint's global matrix, model space, sixteen floats a joint,
+   * and the model matrix — and `dt` seconds, run as whole fixed steps; the particles at the frame's
+   * `alpha` are then what the frame draws. **Once a frame, before the draws**, as
+   * `updateClothParticles` is: a second in one frame would reach every draw of it on WebGPU.
+   */
+  step(globals: Float32Array, model: Float32Array, dt: number): void;
+  /**
+   * The air the cloth drags toward from the next step, world space, metres a second: the frame's
+   * sample of the scene's one `WindField`, so a garment moves with everything else in the air.
+   */
+  setWind(x: number, y: number, z: number): void;
+  /** Back to the skinned pose, settled, as a teleport resets it. */
+  reset(): void;
+  dispose(): void;
+}
+
+/** A garment for `renderer`, from a set-up checked by name. */
+export function createSkinnedCloth(
+  renderer: RendererApi,
+  setup: SkinnedClothSetup,
+): SkinnedClothSolver {
+  const host = computeHostOf(renderer);
+  return host === null ? new CpuCloth(renderer, setup) : new DeviceCloth(host, setup);
+}
+
+class DeviceCloth implements SkinnedClothSolver {
+  readonly runsOn = 'device';
+  readonly particles: ClothParticlesHandle;
+  private readonly cloth: GpuSkinnedCloth;
+
+  constructor(
+    private readonly host: ComputeHost,
+    setup: SkinnedClothSetup,
+  ) {
+    this.cloth = new GpuSkinnedCloth(host.device(), setup);
+    this.particles = this.cloth.particles;
+  }
+
+  step(globals: Float32Array, model: Float32Array, dt: number): void {
+    if (this.host.lost()) return;
+    this.cloth.advance(globals, model, dt, this.host.changeFrame());
+  }
+
+  setWind(x: number, y: number, z: number): void {
+    this.cloth.setWind(x, y, z);
+  }
+
+  reset(): void {
+    if (this.host.lost()) return;
+    this.cloth.reset();
+  }
+
+  /** Its buffers at once — its work is submitted — and its textures with the frame's. */
+  dispose(): void {
+    this.cloth.dispose();
+    this.host.retire(this.cloth.particles.textures);
+  }
+
+  /** The particles where the last step left them: the parity check's door, waits on the device. */
+  read(): Promise<Float32Array> {
+    return this.cloth.read();
+  }
+}
+
+class CpuCloth implements SkinnedClothSolver {
+  readonly runsOn = 'cpu';
+  readonly particles: ClothParticlesHandle;
+  private readonly cloth: SkinnedCloth;
+  /** The frame's particles at `alpha`, before they go up. */
+  private readonly staging: Float32Array;
+
+  constructor(
+    private readonly renderer: RendererApi,
+    setup: SkinnedClothSetup,
+  ) {
+    this.cloth = new SkinnedCloth(setup);
+    this.particles = renderer.createClothParticles(this.cloth.count);
+    this.staging = new Float32Array(this.cloth.count * 3);
+  }
+
+  step(globals: Float32Array, model: Float32Array, dt: number): void {
+    this.cloth.setPose(globals, model);
+    this.cloth.advance(dt);
+    this.cloth.interpolate(this.cloth.alpha, this.staging);
+    this.renderer.updateClothParticles(this.particles, this.staging);
+  }
+
+  setWind(x: number, y: number, z: number): void {
+    this.cloth.setWind(x, y, z);
+  }
+
+  reset(): void {
+    this.cloth.reset();
+  }
+
+  dispose(): void {
+    this.renderer.disposeClothParticles(this.particles);
+  }
+}

package/src/render/ssrPass.ts

@@ -8,6 +8,7 @@ import { compileProgram, uniformLocations } from './shader.ts';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
 import { SSR_RESOLVE_FRAG } from './shaders/ssrResolve.ts';
 import { SSR_TRACE_FRAG } from './shaders/ssrTrace.ts';
+import { blendKeeping } from './sceneCoverage.ts';
 
 /**
  * Screen-space reflection on WebGL2: a scissored trace per surface, then one composite.
@@ -202,7 +203,7 @@ export class SsrPass {
     gl.disable(gl.CULL_FACE);
     gl.enable(gl.BLEND);
     /* Premultiplied `over`: the trace already multiplied its colour by the coverage it found. */
-    gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+    blendKeeping(gl, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
 
     gl.useProgram(this.resolve);
     gl.activeTexture(gl.TEXTURE0);

package/src/render/surfaceModel.ts

@@ -0,0 +1,274 @@
+/**
+ * A material's shading model: how its surface answers light, when the standard model is not what
+ * it is made of — brushed metal, hair, skin, an eye.
+ *
+ * **A frozen descriptor, made once by a factory, carrying a kind and that model's numbers.** The
+ * standard model is `null`, exactly today's shader, and a scene that never names a model compiles
+ * nothing of any of them: each is a pipeline constant of its own (`MODEL_ANISOTROPIC` and the rest
+ * in `shaders/flat/models.ts`), off in every pipeline but the ones a material asks for.
+ *
+ * **Two vectors of numbers a material, and no more.** The lit stage's eight-light build is 254 of
+ * the 256 uniform vectors an Adreno 740 offers, so a model's numbers are packed into
+ * `uModelParams[2]` — the last component of the second says whether a model map is bound — and
+ * every model fits. See `packModel` for each layout.
+ *
+ * **The eye's axis is the one number that moves.** It is the eye's forward direction in the world,
+ * which a turning head or a glance changes every frame; the lit stage has no room left for another
+ * varying (sixteen, WebGPU's ceiling), so the renderer turns the descriptor's mesh-local axis by
+ * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
+ */
+import type { Vec3 } from '../math/color.ts';
+
+/** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
+export interface AnisotropicModel {
+  readonly kind: 'anisotropic';
+  /** 0 to 1: how far the highlight is stretched along the tangent. */
+  readonly strength: number;
+  /** Radians, turning the stretch's direction from the tangent toward the bitangent. */
+  readonly rotation: number;
+}
+
+/**
+ * Hair: three lobes along the strand, which is the mesh's tangent, running from root to tip
+ * (`hairLobes.ts`). A model map's green turns each strand's tilt by up to half of it either way and
+ * its blue is occlusion.
+ */
+export interface HairModel {
+  readonly kind: 'hair';
+  /**
+   * Radians the cuticle's scales tilt the strand's surface: positive moves the white highlight
+   * toward the root and the coloured one toward the tip. A card whose tangent runs tip to root
+   * takes it negative.
+   */
+  readonly shift: number;
+  /** 0 to 1: the light scattered through many strands, tinted by their colour. */
+  readonly scatter: number;
+  /** How strongly light from behind glows through: the transmitted lobe. */
+  readonly backlit: number;
+}
+
+/** Skin: light scattered beneath the surface, reddening its terminator and its thin parts. */
+export interface SkinModel {
+  readonly kind: 'skin';
+  /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
+  readonly scatterColor: Vec3;
+  /** Metres: how far light travels beneath it before it leaves. */
+  readonly radius: number;
+  /** 0 to 1: how much a light behind a thin part shows through it. */
+  readonly transmission: number;
+  /** Which of up to eight profiles the screen-space scattering blurs this skin by. */
+  readonly profile: number;
+}
+
+/** An eye: an iris seen through a cornea, which refracts it, under a mirror-smooth highlight. */
+export interface EyeModel {
+  readonly kind: 'eye';
+  /** The iris's radius, in texture coordinates from the centre of the eye's map. */
+  readonly irisRadius: number;
+  /** Metres from the cornea down to the iris. */
+  readonly irisDepth: number;
+  /** The cornea's index of refraction. */
+  readonly ior: number;
+  /** How smooth the cornea's highlight is. */
+  readonly corneaRoughness: number;
+  /** The eye's forward direction, in the mesh's own space at its bind pose. */
+  readonly axis: Vec3;
+  /** The joint the eye turns with, or -1 for an eye placed by its model matrix alone. */
+  readonly joint: number;
+}
+
+/** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+/** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
+export type SurfaceModelKind = SurfaceModel['kind'];
+
+/** Every kind, in the order the lit stage declares their switches. */
+export const SURFACE_MODEL_KINDS: readonly SurfaceModelKind[] = [
+  'anisotropic',
+  'hair',
+  'skin',
+  'eye',
+];
+
+/** The lit stage's switch for each kind. */
+export const SURFACE_MODEL_SWITCH: Readonly<Record<SurfaceModelKind, string>> = {
+  anisotropic: 'MODEL_ANISOTROPIC',
+  hair: 'MODEL_HAIR',
+  skin: 'MODEL_SKIN',
+  eye: 'MODEL_EYE',
+};
+
+/** Floats a material's model takes: `uModelParams[2]`. */
+export const MODEL_PARAM_FLOATS = 8;
+
+function check(model: string, name: string, value: number, low: number, high: number): number {
+  if (!Number.isFinite(value) || value < low || value > high) {
+    throw new Error(`${model}: ${name} must be from ${low} to ${high}, not ${String(value)}`);
+  }
+  return value;
+}
+
+function unit(model: string, name: string, v: Vec3): Vec3 {
+  const length = Math.hypot(v[0], v[1], v[2]);
+  if (!(length > 1e-6))
+    throw new Error(`${model}: ${name} must be a direction, not [${v.join(', ')}]`);
+  return [v[0] / length, v[1] / length, v[2] / length];
+}
+
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export function anisotropicModel(
+  options: { strength?: number; rotation?: number } = {},
+): AnisotropicModel {
+  return Object.freeze({
+    kind: 'anisotropic',
+    strength: check('anisotropicModel', 'strength', options.strength ?? 1, 0, 1),
+    rotation: check(
+      'anisotropicModel',
+      'rotation',
+      options.rotation ?? 0,
+      -2 * Math.PI,
+      2 * Math.PI,
+    ),
+  });
+}
+
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export function hairModel(
+  options: { shift?: number; scatter?: number; backlit?: number } = {},
+): HairModel {
+  return Object.freeze({
+    kind: 'hair',
+    shift: check('hairModel', 'shift', options.shift ?? (3 * Math.PI) / 180, -0.5, 0.5),
+    scatter: check('hairModel', 'scatter', options.scatter ?? 0.7, 0, 1),
+    backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
+  });
+}
+
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export function skinModel(
+  options: { scatterColor?: Vec3; radius?: number; transmission?: number; profile?: number } = {},
+): SkinModel {
+  const color = options.scatterColor ?? [0.85, 0.35, 0.22];
+  for (let c = 0; c < 3; c++) check('skinModel', 'scatterColor', color[c] as number, 0, 1);
+  const profile = check('skinModel', 'profile', options.profile ?? 0, 0, 7);
+  if (!Number.isInteger(profile))
+    throw new Error(`skinModel: profile must be a whole number, not ${profile}`);
+  return Object.freeze({
+    kind: 'skin',
+    scatterColor: Object.freeze([color[0], color[1], color[2]]) as unknown as Vec3,
+    radius: check('skinModel', 'radius', options.radius ?? 0.012, 0, 0.1),
+    transmission: check('skinModel', 'transmission', options.transmission ?? 0.5, 0, 1),
+    profile,
+  });
+}
+
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export function eyeModel(
+  options: {
+    irisRadius?: number;
+    irisDepth?: number;
+    ior?: number;
+    corneaRoughness?: number;
+    axis?: Vec3;
+    joint?: number;
+  } = {},
+): EyeModel {
+  const joint = options.joint ?? -1;
+  if (!Number.isInteger(joint) || joint < -1) {
+    throw new Error(`eyeModel: joint must be a joint index or -1, not ${String(joint)}`);
+  }
+  return Object.freeze({
+    kind: 'eye',
+    irisRadius: check('eyeModel', 'irisRadius', options.irisRadius ?? 0.15, 0.001, 0.5),
+    irisDepth: check('eyeModel', 'irisDepth', options.irisDepth ?? 0.003, 0, 0.02),
+    ior: check('eyeModel', 'ior', options.ior ?? 1.336, 1, 2),
+    corneaRoughness: check('eyeModel', 'corneaRoughness', options.corneaRoughness ?? 0.02, 0, 1),
+    axis: Object.freeze(unit('eyeModel', 'axis', options.axis ?? [0, 0, 1])) as unknown as Vec3,
+    joint,
+  });
+}
+
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void {
+  out.fill(0);
+  if (model === null) return;
+  out[7] = mapped ? 1 : 0;
+  switch (model.kind) {
+    case 'anisotropic':
+      out[0] = model.strength;
+      out[1] = Math.cos(model.rotation);
+      out[2] = Math.sin(model.rotation);
+      return;
+    case 'hair':
+      out[0] = model.shift;
+      out[1] = model.scatter;
+      out[2] = model.backlit;
+      return;
+    case 'skin':
+      out[0] = model.scatterColor[0];
+      out[1] = model.scatterColor[1];
+      out[2] = model.scatterColor[2];
+      out[3] = model.radius;
+      out[4] = model.transmission;
+      out[5] = model.profile;
+      return;
+    case 'eye':
+      out[0] = model.irisRadius;
+      out[1] = model.irisDepth;
+      out[2] = model.ior;
+      out[3] = model.corneaRoughness;
+      out[4] = model.axis[0];
+      out[5] = model.axis[1];
+      out[6] = model.axis[2];
+      return;
+  }
+}
+
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export function eyeAxisInWorld(
+  model: EyeModel,
+  placement: ArrayLike<number>,
+  palette: ArrayLike<number> | null,
+  out: Float32Array,
+  at: number,
+): void {
+  let [x, y, z] = model.axis;
+  const j = model.joint * 16;
+  if (palette !== null && model.joint >= 0 && j + 16 <= palette.length) {
+    const px =
+      (palette[j] as number) * x + (palette[j + 4] as number) * y + (palette[j + 8] as number) * z;
+    const py =
+      (palette[j + 1] as number) * x +
+      (palette[j + 5] as number) * y +
+      (palette[j + 9] as number) * z;
+    const pz =
+      (palette[j + 2] as number) * x +
+      (palette[j + 6] as number) * y +
+      (palette[j + 10] as number) * z;
+    x = px;
+    y = py;
+    z = pz;
+  }
+  const m = placement;
+  const wx = (m[0] as number) * x + (m[4] as number) * y + (m[8] as number) * z;
+  const wy = (m[1] as number) * x + (m[5] as number) * y + (m[9] as number) * z;
+  const wz = (m[2] as number) * x + (m[6] as number) * y + (m[10] as number) * z;
+  const length = Math.hypot(wx, wy, wz) || 1;
+  out[at] = wx / length;
+  out[at + 1] = wy / length;
+  out[at + 2] = wz / length;
+}

package/src/render/surfaceTexture.ts

@@ -8,9 +8,19 @@
  * 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 { isSourceList, layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
+import type { SurfaceModel } from './surfaceModel.ts';
+import { layerSize, refuseArrayUpdate, sourceSize } from './textureSource.ts';
+import { compressedLayers, planBlocks, refuseBlockUpdate } from './compressedSource.ts';
+import type {
+  BlockFormat,
+  CompressedTextureFormat,
+  CompressedTextureSource,
+  SurfaceSource,
+} from './compressedSource.ts';
+import { uploadCompressedArray } from './glCompressed.ts';
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from './surfaceEffects.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
+import type { CutoutMode } from './cutoutDither.ts';
 
 /**
  * How a texture behaves past its edges and between its texels.
@@ -70,8 +80,31 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
   /** Repeats across the mesh's own UV range, per axis. Applies to every map the material holds. */
   uScale?: number;
   vScale?: number;
-  /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
+  /**
+   * Where the texture starts, per axis, added after the scale: a surface samples
+   * `uv · scale + offset`. Applies to every map, and to a cutout's shadow and depth as well.
+   *
+   * **What picks a cell of a flipbook or an atlas through the material**, so one quad draws any
+   * cell: a strip of four frames is `uScale: 0.25` and `uOffset: frame * 0.25`. Without it a
+   * consumer built one quad mesh per cell — 106 meshes for four strips — because the only way to
+   * move a texture was to move the geometry's own coordinates.
+   */
+  uOffset?: number;
+  vOffset?: number;
+  /** Alpha below which a fragment is discarded. See `uCutout`. */
   cutout?: number;
+  /**
+   * How the cutout's edge is drawn: `'hard'`, the default and every cutout before 4.8.4, or
+   * `'dithered'`, which keeps a pixel by the share of it the texture covers so a strand of hair, a
+   * lash or a fringe of leaves has a soft edge instead of a stair of pixels.
+   *
+   * **The frame decides how a dithered edge is resolved**, because the material cannot know: under a
+   * temporal resolve (TAA or DriftTR) the pattern moves every frame and the resolve averages it;
+   * multisampled, the share goes to the GPU as alpha-to-coverage; with neither, the test is hard,
+   * since a dither nothing averages is grain. A translucent draw tests hard whatever this says. See
+   * `cutoutDither.ts`.
+   */
+  cutoutMode?: CutoutMode;
   /**
    * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
    * without culling, and a back face is lit as its front, with the normal turned to the viewer.
@@ -112,6 +145,19 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
    * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
    */
   emissiveScale?: readonly [number, number, number];
+  /**
+   * How the surface answers light, when the standard model is not what it is made of: brushed
+   * metal, hair, skin, an eye — `anisotropicModel`, `hairModel`, `skinModel`, `eyeModel`. Null or
+   * absent is the standard model, exactly as before. **A pipeline of its own**, compiled the first
+   * time a draw asks, so a scene that names no model pays for none. See `surfaceModel.ts`.
+   */
+  model?: SurfaceModel | null;
+  /**
+   * The model's own channels, in the albedo's coordinates and layers; what each channel means is
+   * the model's to say. Absent, each model takes its own neutral. Sampled linear, like any map
+   * that is not a colour.
+   */
+  modelMap?: Texture | null;
 }
 
 export interface SurfaceTextureOptions {
@@ -211,79 +257,45 @@ export class SurfaceTexture {
   readonly layers: number;
   /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
   private effectsTable: WebGLTexture | null = null;
+  /** The block format a compressed texture holds, or null for one uploaded from images. */
+  private readonly blockFormat: BlockFormat | null;
 
   /**
    * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
-   * Uploaded unflipped either way; see the constructor body for why.
+   * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
+   * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
    */
   constructor(
     gl: WebGL2RenderingContext,
-    source: TexImageSource | readonly TexImageSource[],
+    source: SurfaceSource | readonly SurfaceSource[],
     options: SurfaceTextureOptions = {},
+    compressed: readonly CompressedTextureFormat[] = [],
   ) {
-    const sources: readonly TexImageSource[] = isSourceList(source) ? source : [source];
-    const { width, height } = layerSize(sources);
-    this.layers = sources.length;
+    const listed = (Array.isArray(source) ? source : [source]) as readonly SurfaceSource[];
+    const blocks = compressedLayers(listed);
+    this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
+    /* Refused before anything is allocated, so a refusal leaves no texture behind. */
+    const plan = blocks === null ? null : planBlocks(blocks, this.srgb, compressed);
     const texture = gl.createTexture();
     if (texture === null) throw new Error('SurfaceTexture: createTexture failed');
     this.texture = texture;
-    this.mipmapped = options.mipmap ?? true;
-    this.srgb = (options.colorSpace ?? 'linear') === 'srgb';
-
     const wrap = (options.wrap ?? 'repeat') === 'repeat' ? gl.REPEAT : gl.CLAMP_TO_EDGE;
-
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
-    /*
-     * **Not flipped, and this used to be, which is the bug it is written down for.**
-     *
-     * The flip was here with a comment saying every source is a 2D drawing surface whose Y
-     * runs down from the top-left, so without it "every texture arrives mirrored". That is
-     * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
-     * `ImageBitmap`**, which carries its own orientation. So the two source types the same
-     * method accepts arrived the opposite way up from each other, and nothing caught it
-     * because every canvas-sourced texture in this repository was symmetric under a vertical
-     * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
-     * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
-     * upside down.
-     *
-     * **Made to agree by dropping the flip rather than by extending it**, and the direction
-     * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
-     * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
-     * turn over every painted surface on every loaded model. Dropping it changes only
-     * canvas-sourced textures, and every one of those that exists today is symmetric.
-     *
-     * A caller that was mirroring its own canvas to cancel this must stop.
-     */
-    /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
-       new size, as texImage2D always could. Each layer is then written in place. */
-    gl.texImage3D(
-      gl.TEXTURE_2D_ARRAY,
-      0,
-      this.srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
-      width,
-      height,
-      sources.length,
-      0,
-      gl.RGBA,
-      gl.UNSIGNED_BYTE,
-      null,
-    );
-    for (let layer = 0; layer < sources.length; layer++) {
-      gl.texSubImage3D(
-        gl.TEXTURE_2D_ARRAY,
-        0,
-        0,
-        0,
-        layer,
-        width,
-        height,
-        1,
-        gl.RGBA,
-        gl.UNSIGNED_BYTE,
-        sources[layer] as TexImageSource,
-      );
-    }
 
+    if (blocks !== null && plan !== null) {
+      /* The stored chain, or level 0 alone where no chain was asked for. Nothing is generated:
+         `generateMipmap` cannot write a compressed format. */
+      this.layers = blocks.length;
+      this.blockFormat = (blocks[0] as CompressedTextureSource).format;
+      this.mipmapped = (options.mipmap ?? true) && plan.levels > 1;
+      uploadCompressedArray(gl, plan.name, blocks, this.mipmapped ? plan.levels : 1);
+    } else {
+      const sources = listed as readonly TexImageSource[];
+      this.layers = sources.length;
+      this.blockFormat = null;
+      this.mipmapped = options.mipmap ?? true;
+      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
@@ -303,7 +315,7 @@ export class SurfaceTexture {
           : gl.LINEAR,
     );
 
-    if (this.mipmapped) gl.generateMipmap(gl.TEXTURE_2D_ARRAY);
+    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);
 
@@ -334,7 +346,6 @@ export class SurfaceTexture {
     }
   }
 
-  /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
   /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
   get hasEffects(): boolean {
     return this.effectsTable !== null;
@@ -359,6 +370,7 @@ export class SurfaceTexture {
   update(gl: WebGL2RenderingContext, source: TexImageSource): void {
     if (this.texture === null) return;
     refuseArrayUpdate(this.layers);
+    refuseBlockUpdate(this.blockFormat);
     const { width, height } = sourceSize(source);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.texture);
     /* Unflipped, matching the constructor. See it for why, and for what it cost. */
@@ -393,6 +405,65 @@ export class SurfaceTexture {
   }
 }
 
+/** Images into the bound array, level 0 of each layer; the chain, if any, is generated after. */
+function uploadImages(
+  gl: WebGL2RenderingContext,
+  sources: readonly TexImageSource[],
+  srgb: boolean,
+): void {
+  const { width, height } = layerSize(sources);
+  /*
+   * **Not flipped, and this used to be, which is the bug it is written down for.**
+   *
+   * The flip was here with a comment saying every source is a 2D drawing surface whose Y
+   * runs down from the top-left, so without it "every texture arrives mirrored". That is
+   * true of a canvas and **WebGL ignores `UNPACK_FLIP_Y_WEBGL` entirely for an
+   * `ImageBitmap`**, which carries its own orientation. So the two source types the same
+   * method accepts arrived the opposite way up from each other, and nothing caught it
+   * because every canvas-sourced texture in this repository was symmetric under a vertical
+   * flip: eroded noise, a radial halo, a sleeve blurred to 24 pixels and back. One consumer
+   * painted lettering to a canvas beside a sleeve decoded as a bitmap and the text was
+   * upside down.
+   *
+   * **Made to agree by dropping the flip rather than by extending it**, and the direction
+   * is a deliberate choice about blast radius rather than a coin toss: `drftLoader` builds
+   * every model texture from an `ImageBitmap`, so flipping bitmaps to match canvases would
+   * turn over every painted surface on every loaded model. Dropping it changes only
+   * canvas-sourced textures, and every one of those that exists today is symmetric.
+   *
+   * A caller that was mirroring its own canvas to cancel this must stop.
+   */
+  /* Allocated mutable rather than with texStorage3D, so `update` can hand a one-layer texture a
+       new size, as texImage2D always could. Each layer is then written in place. */
+  gl.texImage3D(
+    gl.TEXTURE_2D_ARRAY,
+    0,
+    srgb ? gl.SRGB8_ALPHA8 : gl.RGBA,
+    width,
+    height,
+    sources.length,
+    0,
+    gl.RGBA,
+    gl.UNSIGNED_BYTE,
+    null,
+  );
+  for (let layer = 0; layer < sources.length; layer++) {
+    gl.texSubImage3D(
+      gl.TEXTURE_2D_ARRAY,
+      0,
+      0,
+      0,
+      layer,
+      width,
+      height,
+      1,
+      gl.RGBA,
+      gl.UNSIGNED_BYTE,
+      sources[layer] as TexImageSource,
+    );
+  }
+}
+
 /**
  * Set anisotropic filtering when the driver offers it, and stay silent when it does not.
  *