@driftengine/assets 4.8.7 → 4.10.0

package/dist/index.js

@@ -179,6 +179,15 @@ export { ddsBlocks } from './ddsBlocks.js';
 export { decodeBc } from './bcDecode.js';
 export { decodeBcImage } from './bcImage.js';
 export { flipBc5Green } from './bcFlip.js';
+/*
+ * Blocks a phone samples. `readKtx2` takes a texture compressed offline — ASTC, ETC2 or BC — as the
+ * blocks it carries, for `createSurfaceTexture`; `encodeEtc2Chain` makes ETC2 or EAC blocks and
+ * their chain from pixels a caller holds, which is what the loader's worker does with a BC texture
+ * on a device that samples ETC2 and not BC. A 2048² image is 262,144 blocks: call it in a worker.
+ */
+export { readKtx2 } from './ktx2.js';
+export { encodeEtc2 } from './etc2Encode.js';
+export { encodeEtc2Chain } from './etc2Chain.js';
 /*
  * **The offline half of the GPU-driven pipeline, which nothing outside this package could reach.**
  *

package/dist/ktx2.d.ts

@@ -0,0 +1,10 @@
+import type { CompressedTextureSource } from '@driftengine/core';
+/** A KTX2 file's blocks, and the colour space its format names. */
+export interface Ktx2Texture {
+    /** The blocks, for `createSurfaceTexture` where `uploadsCompressed` says the device takes them. */
+    readonly source: CompressedTextureSource;
+    /** Whether the file's format is an sRGB one: the `colorSpace` to create the texture in. */
+    readonly srgb: boolean;
+}
+/** `bytes` as a KTX2 file of one 2D block texture. Throws, naming the reason, on anything else. */
+export declare function readKtx2(bytes: Uint8Array): Ktx2Texture;

package/dist/ktx2.js

@@ -0,0 +1,134 @@
+/**
+ * KTX2 textures read as the blocks they carry, for `createSurfaceTexture`: a texture compressed
+ * offline for the devices a game ships to — ASTC or ETC2 for a phone, BC for a desktop — goes up as
+ * it was made, with its own chain, and nothing is decoded or encoded on the way. A game carrying a
+ * phone's textures in the file is the answer to a device that cannot hold them all as RGBA even
+ * for the moment `etc2Load.ts` re-encodes them in.
+ *
+ * **Uncompressed containers of 2D block textures only.** Refused, each by name: a supercompressed
+ * file, since BasisLZ needs a transcoder and Zstandard or zlib an inflater, and this engine ships
+ * neither — a texture tool writes the same blocks with supercompression off; a format no device
+ * here samples as blocks — HDR BC6H, the signed BC4, BC5 and EAC, anything that is not blocks; and a
+ * cube, an array or a volume, which a surface texture is none of.
+ *
+ * **BC1 with and without alpha are one format here**, as they are to WebGPU, so a texel a file
+ * marked opaque stores in BC1's three-colour mode comes out transparent black rather than black.
+ * What would make that wrong is a colour map leaning on that texel being opaque.
+ *
+ * The levels are views over `bytes`, not copies: the file lives as long as the source does, which is
+ * until `createSurfaceTexture` has uploaded it.
+ */
+import { levelBytes } from '@driftengine/core';
+const IDENTIFIER = [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a];
+const ASTC_SIZES = [
+    '4x4',
+    '5x4',
+    '5x5',
+    '6x5',
+    '6x6',
+    '8x5',
+    '8x6',
+    '8x8',
+    '10x5',
+    '10x6',
+    '10x8',
+    '10x10',
+    '12x10',
+    '12x12',
+];
+/** Each Vulkan block format this engine samples, as its own format and whether it is sRGB. */
+const VK_FORMATS = new Map([
+    [131, ['bc1', false]],
+    [132, ['bc1', true]],
+    [133, ['bc1', false]],
+    [134, ['bc1', true]],
+    [135, ['bc2', false]],
+    [136, ['bc2', true]],
+    [137, ['bc3', false]],
+    [138, ['bc3', true]],
+    [139, ['bc4', false]],
+    [141, ['bc5', false]],
+    [145, ['bc7', false]],
+    [146, ['bc7', true]],
+    [147, ['etc2-rgb8', false]],
+    [148, ['etc2-rgb8', true]],
+    [149, ['etc2-rgb8a1', false]],
+    [150, ['etc2-rgb8a1', true]],
+    [151, ['etc2-rgba8', false]],
+    [152, ['etc2-rgba8', true]],
+    [153, ['eac-r11', false]],
+    [155, ['eac-rg11', false]],
+    ...ASTC_SIZES.flatMap((size, i) => [
+        [157 + i * 2, [`astc-${size}`, false]],
+        [158 + i * 2, [`astc-${size}`, true]],
+    ]),
+]);
+/** The block formats a file may name that this engine does not sample, and why. */
+const REFUSED = new Map([
+    [140, 'signed BC4'],
+    [142, 'signed BC5'],
+    [143, 'HDR BC6H'],
+    [144, 'signed HDR BC6H'],
+    [154, 'signed EAC R11'],
+    [156, 'signed EAC RG11'],
+]);
+const SUPERCOMPRESSION = ['', 'BasisLZ', 'Zstandard', 'zlib'];
+/** `bytes` as a KTX2 file of one 2D block texture. Throws, naming the reason, on anything else. */
+export function readKtx2(bytes) {
+    if (bytes.length < 80 || IDENTIFIER.some((byte, i) => bytes[i] !== byte)) {
+        throw new Error('readKtx2: not a KTX2 file (its first twelve bytes are not the identifier)');
+    }
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const u32 = (at) => view.getUint32(at, true);
+    const u64 = (at) => {
+        if (u32(at + 4) !== 0)
+            throw new Error('readKtx2: an offset past four gigabytes');
+        return u32(at);
+    };
+    const vkFormat = u32(12);
+    const width = u32(20);
+    const height = u32(24);
+    const depth = u32(28);
+    const layers = u32(32);
+    const faces = u32(36);
+    const levelCount = Math.max(1, u32(40));
+    const scheme = u32(44);
+    if (scheme !== 0) {
+        throw new Error(`readKtx2: the file is supercompressed with ${SUPERCOMPRESSION[scheme] ?? `scheme ${scheme}`}, ` +
+            'which this engine does not undo; write it with supercompression off');
+    }
+    const known = VK_FORMATS.get(vkFormat);
+    if (known === undefined) {
+        const named = REFUSED.get(vkFormat);
+        throw new Error(named !== undefined
+            ? `readKtx2: ${named} is not a format this engine samples`
+            : `readKtx2: vkFormat ${vkFormat} is not a block format this engine samples`);
+    }
+    if (faces !== 1)
+        throw new Error(`readKtx2: a cube of ${faces} faces, not a 2D texture`);
+    if (layers > 1)
+        throw new Error(`readKtx2: an array of ${layers} layers, not a 2D texture`);
+    if (depth > 0)
+        throw new Error(`readKtx2: a volume ${depth} deep, not a 2D texture`);
+    if (width === 0 || height === 0)
+        throw new Error('readKtx2: a texture with no height is 1D');
+    const [format, srgb] = known;
+    const levels = [];
+    for (let level = 0; level < levelCount; level++) {
+        const entry = 80 + level * 24;
+        if (entry + 24 > bytes.length)
+            throw new Error('readKtx2: the level index runs past the file');
+        const offset = u64(entry);
+        const length = u64(entry + 8);
+        const expected = levelBytes(format, width, height, level);
+        if (length !== expected) {
+            throw new Error(`readKtx2: level ${level} of a ${width}x${height} ${format} texture is ${expected} bytes, ` +
+                `and the file gives it ${length}`);
+        }
+        if (offset + length > bytes.length) {
+            throw new Error(`readKtx2: level ${level} runs past the end of the file`);
+        }
+        levels.push(bytes.subarray(offset, offset + length));
+    }
+    return { source: { format, width, height, levels }, srgb };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/assets",
-  "version": "4.8.7",
+  "version": "4.10.0",
   "description": "Model readers and the streaming loader for the .drft container",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,6 +12,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./bcWorkers": {
+      "drift-source": "./src/bcWorkers.ts",
+      "types": "./dist/bcWorkers.d.ts",
+      "default": "./dist/bcWorkers.js"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },
@@ -27,11 +32,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.8.7",
-    "@driftengine/texture": "4.8.7"
+    "@driftengine/drft": "4.10.0",
+    "@driftengine/texture": "4.10.0"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.8.7"
+    "@driftengine/core": "4.10.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/bcLoad.ts

@@ -20,6 +20,7 @@ import type { BcImage } from '@driftengine/drft';
 
 import { answerBcRequest } from './bcAnswer.ts';
 import type { BcReply, BcRequest } from './bcAnswer.ts';
+import type { Etc2Request } from './etc2Answer.ts';
 
 export type { BcReply, BcRequest } from './bcAnswer.ts';
 export { answerBcRequest } from './bcAnswer.ts';
@@ -39,9 +40,12 @@ export function bcPlan(
     : 'decode';
 }
 
-/** The part of a worker the decoder uses. A browser `Worker` satisfies it. */
+/**
+ * The part of a worker the decoder and the ETC2 encoder use (`etc2Load.ts`), each starting one of
+ * its own from the same factory. A browser `Worker` satisfies it.
+ */
 export interface BcWorker {
-  postMessage(request: BcRequest, transfer?: Transferable[]): void;
+  postMessage(request: BcRequest | Etc2Request, transfer?: Transferable[]): void;
   terminate(): void;
   onmessage: ((event: { data: unknown }) => void) | null;
   onerror?: ((event: unknown) => void) | null;
@@ -76,7 +80,8 @@ function settle(reply: BcReply, pending: Pending): void {
 
 /**
  * A decoder over a worker `spawn` starts, or on the main thread where it is null — the default, since
- * the worker's factory lives behind its own specifier (`bcWorkers.ts`) and a caller names it.
+ * the worker's factory lives behind its own specifier (`@driftengine/assets/bcWorkers`) and a caller
+ * names it.
  */
 export function createBcDecoder(spawn: (() => BcWorker) | null = null): BcDecoder {
   let worker: BcWorker | null = null;
@@ -96,7 +101,8 @@ export function createBcDecoder(spawn: (() => BcWorker) | null = null): BcDecode
   if (spawn === null) {
     reason =
       'BC textures decode on the main thread: no worker was named. Pass `bcWorker: spawnBcWorker`, ' +
-      'exported by @driftengine/assets/src/bcWorkers.ts, to decode them off it';
+      "exported by '@driftengine/assets/bcWorkers', to decode them off it — and, on a device " +
+      'that samples ETC2 and not BC, to re-encode them as ETC2 rather than hold them as RGBA';
   } else {
     try {
       worker = spawn();

package/src/bcWorker.ts

@@ -1,20 +1,29 @@
 /**
- * The worker `bcLoad.ts` starts: decodes BC blocks off the main thread, one request at a time, and
- * hands each image back rather than copying it. Imports `bcAnswer.ts` alone, so its bundle is the
- * decoders and nothing else.
+ * The worker `bcLoad.ts` and `etc2Load.ts` each start one of: decodes BC blocks off the main
+ * thread, or re-encodes them as an ETC2 chain, one request at a time, and hands each answer back
+ * rather than copying it. Imports the two answers alone, so its bundle is the codecs and nothing
+ * else.
  *
  * No top-level await, for the reason `islandWorker.ts` gives: a consumer's bundler compiles every
  * `new Worker(new URL(…))` it finds, and an IIFE worker cannot carry one.
  */
 import { answerBcRequest } from './bcAnswer.ts';
 import type { BcRequest } from './bcAnswer.ts';
+import { answerEtc2Request } from './etc2Answer.ts';
+import type { Etc2Request } from './etc2Answer.ts';
 
 const scope = globalThis as unknown as {
-  onmessage: ((event: { data: BcRequest }) => void) | null;
+  onmessage: ((event: { data: BcRequest | Etc2Request }) => void) | null;
   postMessage(reply: unknown, transfer: ArrayBuffer[]): void;
 };
 
 scope.onmessage = (event): void => {
-  const reply = answerBcRequest(event.data);
+  const request = event.data;
+  if ('kind' in request && request.kind === 'etc2') {
+    const reply = answerEtc2Request(request);
+    scope.postMessage(reply, reply.levels ?? []);
+    return;
+  }
+  const reply = answerBcRequest(request as BcRequest);
   scope.postMessage(reply, reply.rgba === undefined ? [] : [reply.rgba]);
 };

package/src/bcWorkers.ts

@@ -1,5 +1,7 @@
 /**
- * The BC decode worker, behind its own specifier, for the reason `physics/src/workers.ts` gives.
+ * The BC worker — the decode, and on a device that samples ETC2 and not BC the re-encode as ETC2
+ * (`etc2Load.ts`), each in a worker of its own from this factory — behind its own specifier, for
+ * the reason `physics/src/workers.ts` gives.
  *
  * **A bundler emits a worker before it decides the code reaching it is unreachable.** The loader's
  * decoder built its worker with `new Worker(new URL('./bcWorker.ts', import.meta.url))` inside the
@@ -13,18 +15,24 @@
  *
  * ```ts
  * import { DrftLoader } from '@driftengine/assets';
- * import { spawnBcWorker } from '@driftengine/assets/src/bcWorkers.ts';
+ * import { spawnBcWorker } from '@driftengine/assets/bcWorkers';
  *
  * const loader = new DrftLoader(renderer, { bcWorker: spawnBcWorker });
  * ```
  *
+ * **A declared subpath, so it resolves the way the barrel does**: to the build by default and to
+ * this file under `drift-source`. The path into `src/` that 4.8.7 documented still resolves, through
+ * the manifest's `./*` passthrough, and hands every consumer TypeScript inside `node_modules`, which
+ * is the default the 2026-09-13 flip took away from the barrels; a resolver that maps a package's
+ * subpaths into `src/` also doubled it, to `src/src/bcWorkers.ts`.
+ *
  * Without it BC textures decode on the main thread, and the loader says so once. **What that costs**
  * is the decode of a texture the device cannot take as blocks, which on a phone is every BC texture:
  * a 2048² BC7 image is 262,144 blocks.
  */
 import type { BcWorker } from './bcLoad.ts';
 
-/** A BC decode worker, as a bundler understands one. Throws where the runtime has no `Worker`. */
+/** A BC worker, as a bundler understands one. Throws where the runtime has no `Worker`. */
 export function spawnBcWorker(): BcWorker {
   // platform: browser default — `DrftLoaderOptions.bcWorker` is the seam a host supplies
   return new Worker(new URL('./bcWorker.ts', import.meta.url), {

package/src/drftLoader.ts

@@ -2,7 +2,11 @@
 
 import type { MeshData } from '@driftengine/drft';
 import type { MeshHandle, RendererApi } from '@driftengine/core';
-import type { GlassOptions, SurfaceTextureHandle } from '@driftengine/core';
+import type {
+  CompressedTextureSource,
+  GlassOptions,
+  SurfaceTextureHandle,
+} from '@driftengine/core';
 import { MeshBuilder, concatMeshes, placeMesh } from '@driftengine/core';
 import type { DrftMaterial } from '@driftengine/drft';
 import type { DrftSdfvEntry } from '@driftengine/drft';
@@ -11,6 +15,8 @@ import type { DrftFieldPlacement } from './fieldPlacement.ts';
 import type { DrftTexture } from '@driftengine/drft';
 import { TextureSet, textureColorSpaces } from './drftTextures.ts';
 import { bcPlan, createBcDecoder } from './bcLoad.ts';
+import { createEtc2Encoder, etc2Plan } from './etc2Load.ts';
+import type { Etc2Encoder } from './etc2Load.ts';
 import type { BcDecoder, BcWorker } from './bcLoad.ts';
 import { decodeBc } from './bcDecode.ts';
 import { isCompressedSource, uploadsCompressed } from '@driftengine/core';
@@ -84,9 +90,15 @@ export interface DrftLoaderOptions {
   readonly fetchImpl?: FetchLike;
   /**
    * What starts the worker a BC texture the device cannot take as blocks is decoded in:
-   * `spawnBcWorker`, from `@driftengine/assets/src/bcWorkers.ts`. Absent, they decode on the main
+   * `spawnBcWorker`, from `@driftengine/assets/bcWorkers`. Absent, they decode on the main
    * thread and the loader says so once — the factory is behind its own specifier so a consumer that
    * never names it has no worker in its build. See `bcWorkers.ts`.
+   *
+   * **On a device that samples ETC2 and not BC**, which is a phone, a second worker from the same
+   * factory then re-encodes each such texture as ETC2 or EAC and swaps the chain in behind the
+   * handle its decoded image went up under, at half a byte a texel, or a byte with alpha, where the
+   * image holds four. Nothing arrives later for it; see `etc2Load.ts` for what it costs. Without a worker
+   * the textures stay RGBA.
    */
   readonly bcWorker?: () => BcWorker;
   /**
@@ -340,6 +352,15 @@ export class DrftLoader {
   /** Started at the first BC texture that has to be decoded, and only then. See `bcLoad.ts`. */
   private bcDecoder: BcDecoder | null = null;
   private warnedBc = false;
+  /** Started at the first BC texture this device takes better as ETC2. See `etc2Load.ts`. */
+  private etc2Encoder: Etc2Encoder | null = null;
+  private warnedEtc2 = false;
+  /** Encoded chains whose image has not gone up yet, swapped in by `update` once it has. */
+  private readonly swaps: {
+    readonly ordinal: number;
+    readonly blocks: CompressedTextureSource;
+    readonly source: BcImage;
+  }[] = [];
   private readonly chunks: DrftTexture[] = [];
   private materials: readonly DrftMaterial[] = [];
   /**
@@ -1008,6 +1029,18 @@ export class DrftLoader {
       begun++;
     }
 
+    /* An encoded chain whose image has gone up since it arrived; one a frame, as images go. */
+    if (this.swaps.length > 0 && mayBeginMore(begun, performance.now() - startedMs, msBudget)) {
+      for (let at = 0; at < this.swaps.length; at++) {
+        const swap = this.swaps[at] as (typeof this.swaps)[number];
+        if (!this.swapIn(swap.ordinal, swap.blocks, swap.source)) continue;
+        this.swaps.splice(at, 1);
+        changed = true;
+        begun++;
+        break;
+      }
+    }
+
     const revealSec = this.options.revealSec ?? DEFAULT_REVEAL_SEC;
     for (const part of this.revealed) {
       if (part.reveal >= 1) continue;
@@ -1069,6 +1102,9 @@ export class DrftLoader {
     this.regionStore.dispose();
     this.bcDecoder?.dispose();
     this.bcDecoder = null;
+    this.etc2Encoder?.dispose();
+    this.etc2Encoder = null;
+    this.swaps.length = 0;
     /*
      * Everything this class ever made, each disposed once.
      *
@@ -1543,10 +1579,61 @@ export class DrftLoader {
         }
         const pixels = imageDataOf(rgba, image.width, image.height);
         done(asImage ? await createImageBitmap(pixels, AS_AUTHORED) : pixels);
+        if (!asImage) this.encodeLater(image, ordinal, srgb);
       })
       .catch(failed);
   }
 
+  /**
+   * A BC texture just decoded for the picture, re-encoded as ETC2 or EAC where this device samples
+   * that and not BC, and swapped in behind its handle when the chain comes back — at once where the
+   * image has gone up, and from `update` where it is still queued. See `etc2Load.ts`.
+   */
+  private encodeLater(image: BcImage, ordinal: number, srgb: boolean): void {
+    const spawn = this.options.bcWorker;
+    if (spawn === undefined || !etc2Plan(image, srgb, this.renderer.compressedFormats)) return;
+    if (this.etc2Encoder === null) this.etc2Encoder = createEtc2Encoder(spawn);
+    const encoder = this.etc2Encoder;
+    encoder
+      .encode(image, srgb)
+      .then((blocks) => {
+        if (this.disposed) return;
+        if (!this.swapIn(ordinal, blocks, image))
+          this.swaps.push({ ordinal, blocks, source: image });
+      })
+      .catch((error: unknown) => {
+        /* Said once: the texture stays the image it already is, which is a cost and not a fault. */
+        if (this.disposed || this.warnedEtc2) return;
+        this.warnedEtc2 = true;
+        console.warn(
+          `DrftLoader: ${encoder.reason !== '' ? encoder.reason : `image ${ordinal} did not re-encode as ETC2 and stays RGBA`}`,
+          error,
+        );
+      });
+  }
+
+  /**
+   * An encoded chain into the texture its image went up as: false where that texture is not made
+   * yet. **The decoded image is let go**, and the BC blocks it came from held in its place — a
+   * view over the file the loader keeps anyway — so a texture made again from them later decodes
+   * as it first did. A chain the texture refuses, where the slot came to read a colour space the
+   * blocks have no twin in, leaves the image where it is.
+   */
+  private swapIn(ordinal: number, blocks: CompressedTextureSource, source: BcImage): boolean {
+    const held = this.textureSet?.at(ordinal) ?? null;
+    if (held === null) return false;
+    try {
+      this.renderer.updateSurfaceTexture(held, blocks);
+      this.images[ordinal] = source;
+    } catch (error) {
+      if (!this.warnedEtc2) {
+        this.warnedEtc2 = true;
+        console.warn(`DrftLoader: image ${ordinal} stays RGBA`, error);
+      }
+    }
+    return true;
+  }
+
   /**
    * What goes to `createSurfaceTexture`: the image as it is, unless it is blocks this device cannot
    * take in the colour space the slot reads — a material read after its texture arrived can change

package/src/etc2Answer.ts

@@ -0,0 +1,48 @@
+/**
+ * The encode worker's whole job, as a function: one BC texture's level 0 decoded as a GPU samples
+ * it and made into an ETC2 or EAC chain (`etc2Chain.ts`), or the reason it could not be. Its own
+ * module beside `bcAnswer.ts`, which the same worker answers decode requests with.
+ *
+ * **The blocks cross, not the pixels**: the loader has already decoded this texture once, for the
+ * picture it shows while this runs, and hands its blocks over again rather than a copy of that
+ * image — a quarter to an eighth of the bytes, decoded a second time here at about a fifth of the
+ * encode's cost. An error is answered rather than thrown, so one bad texture fails on its own.
+ */
+import type { BcFormat } from '@driftengine/drft';
+
+import { decodeBc } from './bcDecode.ts';
+import { encodeEtc2Chain, etc2FormatFor } from './etc2Chain.ts';
+import type { Etc2Format } from './etc2Encode.ts';
+
+/** What the loader asks the encode worker: one level's BC blocks, and how the texture is read. */
+export interface Etc2Request {
+  readonly kind: 'etc2';
+  readonly id: number;
+  readonly format: BcFormat;
+  readonly width: number;
+  readonly height: number;
+  readonly blocks: ArrayBuffer;
+  /** Whether the slot reads colour, so the chain is averaged in light. */
+  readonly srgb: boolean;
+}
+
+/** The answer: every level of the chain in one format, or why not. */
+export interface Etc2Reply {
+  readonly id: number;
+  readonly format?: Etc2Format;
+  readonly levels?: ArrayBuffer[];
+  readonly error?: string;
+}
+
+export function answerEtc2Request(request: Etc2Request): Etc2Reply {
+  try {
+    const { width, height } = request;
+    const rgba = decodeBc(request.format, width, height, new Uint8Array(request.blocks));
+    const format = etc2FormatFor(request.format, rgba);
+    const colour = format === 'etc2-rgb8' || format === 'etc2-rgba8';
+    const levels = encodeEtc2Chain(format, rgba, width, height, colour && request.srgb);
+    return { id: request.id, format, levels: levels.map((level) => level.buffer as ArrayBuffer) };
+  } catch (error) {
+    return { id: request.id, error: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/etc2Chain.ts

@@ -0,0 +1,113 @@
+/**
+ * A decoded texture as ETC2 or EAC blocks with its whole chain, down to 1x1: what the loader's
+ * encode worker makes of a BC texture on a device that samples ETC2 and not BC.
+ *
+ * **The format follows what the BC format stores**: BC4's one channel as `eac-r11` and BC5's two as
+ * `eac-rg11`, so a roughness or normal map keeps eleven bits a channel where colour would round it
+ * to a brightness step; every colour format as `etc2-rgb8`, or `etc2-rgba8` where any texel is less
+ * than opaque. **Opaque is 254 and above**, because a BC7 encoder storing an opaque image in its
+ * mode with a seven-bit alpha and a shared low bit can land every texel on 254, and that is no
+ * reason to spend twice the memory: what it gives up is an alpha of 254 read as 255, a 0.4% change
+ * no blend or cutout can show. **And what the choice gives up** is `etc2-rgb8a1`, half the size of
+ * `etc2-rgba8` for a cutout whose alpha is only ever 0 or 255, which needs ETC2's punch-through
+ * modes and this encoder writes none of them.
+ *
+ * **Each level is a box average of the one above, colour in linear light where the texture is
+ * colour**, as a GPU builds a chain for an sRGB image: averaged as stored, a fine bright detail on
+ * a dark ground fades darker with distance than it should. Alpha and data are averaged as stored.
+ * Allocates every level, once; this runs in a worker, once a texture.
+ */
+import type { BcFormat } from '@driftengine/drft';
+
+import { encodeEtc2 } from './etc2Encode.ts';
+import type { Etc2Format } from './etc2Encode.ts';
+
+/** The ETC2 or EAC format a BC texture decoded to `rgba` becomes. */
+export function etc2FormatFor(source: BcFormat, rgba: Uint8Array): Etc2Format {
+  if (source === 'bc4') return 'eac-r11';
+  if (source === 'bc5') return 'eac-rg11';
+  for (let at = 3; at < rgba.length; at += 4) {
+    if ((rgba[at] as number) < 254) return 'etc2-rgba8';
+  }
+  return 'etc2-rgb8';
+}
+
+/** `rgba` at `width` by `height`, and each level below it to 1x1, as `format` blocks. */
+export function encodeEtc2Chain(
+  format: Etc2Format,
+  rgba: Uint8Array,
+  width: number,
+  height: number,
+  srgb: boolean,
+): Uint8Array[] {
+  const levels: Uint8Array[] = [];
+  let level = rgba;
+  let w = width;
+  let h = height;
+  for (;;) {
+    levels.push(encodeEtc2(format, level, w, h));
+    if (w === 1 && h === 1) return levels;
+    level = halve(level, w, h, srgb);
+    w = Math.max(1, w >> 1);
+    h = Math.max(1, h >> 1);
+  }
+}
+
+/** Each eight-bit sRGB value in linear light. */
+const LINEAR = new Float64Array(256);
+for (let v = 0; v < 256; v++) {
+  const c = v / 255;
+  LINEAR[v] = c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+/** The eight-bit sRGB value whose light is nearest `light`, found in `LINEAR` and not by a power. */
+function fromLinear(light: number): number {
+  let lo = 0;
+  let hi = 255;
+  while (hi - lo > 1) {
+    const mid = (lo + hi) >> 1;
+    if ((LINEAR[mid] as number) <= light) lo = mid;
+    else hi = mid;
+  }
+  return light - (LINEAR[lo] as number) <= (LINEAR[hi] as number) - light ? lo : hi;
+}
+
+/**
+ * The next level down: each texel the average of the two by two above it, or of the one or two an
+ * odd edge leaves. Colour in linear light where `srgb`; alpha, and every channel of data, as stored.
+ */
+export function halve(rgba: Uint8Array, width: number, height: number, srgb: boolean): Uint8Array {
+  const w = Math.max(1, width >> 1);
+  const h = Math.max(1, height >> 1);
+  const out = new Uint8Array(w * h * 4);
+  for (let y = 0; y < h; y++) {
+    const y0 = Math.min(y * 2, height - 1);
+    const y1 = Math.min(y * 2 + 1, height - 1);
+    for (let x = 0; x < w; x++) {
+      const x0 = Math.min(x * 2, width - 1);
+      const x1 = Math.min(x * 2 + 1, width - 1);
+      const a = (y0 * width + x0) * 4;
+      const b = (y0 * width + x1) * 4;
+      const c = (y1 * width + x0) * 4;
+      const d = (y1 * width + x1) * 4;
+      const to = (y * w + x) * 4;
+      for (let channel = 0; channel < 4; channel++) {
+        const pa = rgba[a + channel] as number;
+        const pb = rgba[b + channel] as number;
+        const pc = rgba[c + channel] as number;
+        const pd = rgba[d + channel] as number;
+        out[to + channel] =
+          srgb && channel < 3
+            ? fromLinear(
+                ((LINEAR[pa] as number) +
+                  (LINEAR[pb] as number) +
+                  (LINEAR[pc] as number) +
+                  (LINEAR[pd] as number)) /
+                  4,
+              )
+            : (pa + pb + pc + pd + 2) >> 2;
+      }
+    }
+  }
+  return out;
+}