@driftengine/assets 4.8.7 → 4.10.0

package/README.md

@@ -1,9 +1,27 @@
 # @driftengine/assets
 
-Model readers for nine formats — `.blend` among them, read from the file's own DNA — and the streaming loader that uploads them.
+Model readers, the loader that streams a `.drft` file onto the screen, and the textures a phone
+samples.
 
-**Cost: 26.3 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
-3% — the number is a fact about the build rather than a claim in a document.
+**Cost: 27.6 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+drifts more than 3% — the number is a fact about the build rather than a claim in a document.
+
+- **Readers.** glTF and GLB, OBJ, STL, USD and 3MF, and experimentally FBX and Blender's `.blend`,
+  read from the file's own DNA. `readModel` picks the reader by extension and `MODEL_FORMATS` lists
+  what each one promises.
+- **`DrftLoader`** streams a container nearest first: an outline, then parts within a frame budget,
+  then images decoded off the main thread, with progress that reaches ready only once the picture is
+  right. A BC texture goes up as its blocks wherever the device samples BC.
+- **Phones.** On a device that samples ETC2 and not BC, a BC texture is shown decoded first and then
+  re-encoded as ETC2 or EAC in a worker and swapped in behind the handle it was drawn with — half a
+  byte a texel for colour, where the decoded image holds four. Pass `bcWorker: spawnBcWorker`, from
+  `@driftengine/assets/bcWorkers`; without a worker nothing is encoded and the textures stay RGBA.
+  The encode costs about 0.7 s for a 2048² image on a desktop processor, and several times that on a
+  phone's, on a core of its own.
+- **Textures compressed offline.** `readKtx2` takes an uncompressed KTX2 file — ASTC, ETC2, EAC or
+  BC — as the blocks it carries, for `createSurfaceTexture`. `encodeEtc2Chain` makes an ETC2 or EAC
+  chain from pixels a caller holds; run it in a worker.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)
-for how the packages divide, and why some features are compiled into core on demand instead.
+for how the packages divide, and [`docs/HANDBOOK.md`](../../docs/HANDBOOK.md) for working with
+imported models.

package/dist/bcLoad.d.ts

@@ -1,15 +1,19 @@
 import type { CompressedTextureFormat } from '@driftengine/core';
 import type { BcImage } from '@driftengine/drft';
 import type { BcRequest } from './bcAnswer.ts';
+import type { Etc2Request } from './etc2Answer.ts';
 export type { BcReply, BcRequest } from './bcAnswer.ts';
 export { answerBcRequest } from './bcAnswer.ts';
 /** What happens to one BC texture. */
 export type BcPlan = 'blocks' | 'decode';
 /** Blocks where this device takes the format in the colour space the slot reads, with a chain. */
 export declare function bcPlan(image: BcImage, srgb: boolean, available: readonly CompressedTextureFormat[]): BcPlan;
-/** 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;
@@ -25,6 +29,7 @@ export interface BcDecoder {
 }
 /**
  * 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 declare function createBcDecoder(spawn?: (() => BcWorker) | null): BcDecoder;

package/dist/bcLoad.js

@@ -38,7 +38,8 @@ function settle(reply, pending) {
 }
 /**
  * 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 = null) {
     let worker = null;
@@ -56,7 +57,8 @@ export function createBcDecoder(spawn = null) {
     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 {

package/dist/bcWorker.js

@@ -1,14 +1,22 @@
 /**
- * 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.js';
+import { answerEtc2Request } from './etc2Answer.js';
 const scope = globalThis;
 scope.onmessage = (event) => {
-    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);
     scope.postMessage(reply, reply.rgba === undefined ? [] : [reply.rgba]);
 };

package/dist/bcWorkers.d.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,15 +15,21 @@
  *
  * ```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 declare function spawnBcWorker(): BcWorker;

package/dist/bcWorkers.js

@@ -1,4 +1,4 @@
-/** 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() {
     // platform: browser default — `DrftLoaderOptions.bcWorker` is the seam a host supplies
     return new Worker(new URL('./bcWorker.js', import.meta.url), {

package/dist/drftLoader.d.ts

@@ -51,9 +51,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;
     /**
@@ -276,6 +282,11 @@ export declare class DrftLoader {
     /** Started at the first BC texture that has to be decoded, and only then. See `bcLoad.ts`. */
     private bcDecoder;
     private warnedBc;
+    /** Started at the first BC texture this device takes better as ETC2. See `etc2Load.ts`. */
+    private etc2Encoder;
+    private warnedEtc2;
+    /** Encoded chains whose image has not gone up yet, swapped in by `update` once it has. */
+    private readonly swaps;
     private readonly chunks;
     private materials;
     /**
@@ -530,6 +541,20 @@ export declare class DrftLoader {
      * Like every image, a BC texture fails on its own and its surfaces draw untextured.
      */
     private acceptBc;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
      * 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/dist/drftLoader.js

@@ -3,6 +3,7 @@ import { MeshBuilder, concatMeshes, placeMesh } from '@driftengine/core';
 import { placeFields } from './fieldPlacement.js';
 import { TextureSet, textureColorSpaces } from './drftTextures.js';
 import { bcPlan, createBcDecoder } from './bcLoad.js';
+import { createEtc2Encoder, etc2Plan } from './etc2Load.js';
 import { decodeBc } from './bcDecode.js';
 import { isCompressedSource, uploadsCompressed } from '@driftengine/core';
 import { CODEC_BC, codecName, readBcPayload } from '@driftengine/drft';
@@ -106,6 +107,11 @@ export class DrftLoader {
     /** Started at the first BC texture that has to be decoded, and only then. See `bcLoad.ts`. */
     bcDecoder = null;
     warnedBc = false;
+    /** Started at the first BC texture this device takes better as ETC2. See `etc2Load.ts`. */
+    etc2Encoder = null;
+    warnedEtc2 = false;
+    /** Encoded chains whose image has not gone up yet, swapped in by `update` once it has. */
+    swaps = [];
     chunks = [];
     materials = [];
     /**
@@ -745,6 +751,18 @@ export class DrftLoader {
             changed = true;
             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];
+                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)
@@ -802,6 +820,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.
          *
@@ -1264,9 +1285,62 @@ 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`.
+     */
+    encodeLater(image, ordinal, srgb) {
+        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) => {
+            /* 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.
+     */
+    swapIn(ordinal, blocks, source) {
+        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/dist/etc2Answer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 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 declare function answerEtc2Request(request: Etc2Request): Etc2Reply;

package/dist/etc2Answer.js

@@ -0,0 +1,15 @@
+import { decodeBc } from './bcDecode.js';
+import { encodeEtc2Chain, etc2FormatFor } from './etc2Chain.js';
+export function answerEtc2Request(request) {
+    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) };
+    }
+    catch (error) {
+        return { id: request.id, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/etc2Chain.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 type { Etc2Format } from './etc2Encode.ts';
+/** The ETC2 or EAC format a BC texture decoded to `rgba` becomes. */
+export declare function etc2FormatFor(source: BcFormat, rgba: Uint8Array): Etc2Format;
+/** `rgba` at `width` by `height`, and each level below it to 1x1, as `format` blocks. */
+export declare function encodeEtc2Chain(format: Etc2Format, rgba: Uint8Array, width: number, height: number, srgb: boolean): Uint8Array[];
+/**
+ * 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 declare function halve(rgba: Uint8Array, width: number, height: number, srgb: boolean): Uint8Array;

package/dist/etc2Chain.js

@@ -0,0 +1,84 @@
+import { encodeEtc2 } from './etc2Encode.js';
+/** The ETC2 or EAC format a BC texture decoded to `rgba` becomes. */
+export function etc2FormatFor(source, rgba) {
+    if (source === 'bc4')
+        return 'eac-r11';
+    if (source === 'bc5')
+        return 'eac-rg11';
+    for (let at = 3; at < rgba.length; at += 4) {
+        if (rgba[at] < 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, rgba, width, height, srgb) {
+    const levels = [];
+    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) {
+    let lo = 0;
+    let hi = 255;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (LINEAR[mid] <= light)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return light - LINEAR[lo] <= LINEAR[hi] - 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, width, height, srgb) {
+    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];
+                const pb = rgba[b + channel];
+                const pc = rgba[c + channel];
+                const pd = rgba[d + channel];
+                out[to + channel] =
+                    srgb && channel < 3
+                        ? fromLinear((LINEAR[pa] +
+                            LINEAR[pb] +
+                            LINEAR[pc] +
+                            LINEAR[pd]) /
+                            4)
+                        : (pa + pb + pc + pd + 2) >> 2;
+            }
+        }
+    }
+    return out;
+}

package/dist/etc2Encode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ETC2 and EAC blocks made from pixels: what a phone samples, at half a byte a texel for colour and
+ * a byte with alpha, where RGBA costs four. The loader encodes a texture this way where the device
+ * takes ETC2 and not the BC its file holds (`etc2Plan`), and a caller holding pixels of its own can
+ * call `encodeEtc2` directly — off the main thread, since a 2048² image is 262,144 blocks.
+ *
+ * **ETC2's colour, through the modes it shares with ETC1**: each 4x4 block split in two halves,
+ * side by side or one above the other, each half a base colour and one of eight tables of
+ * brightness steps, each texel the step nearest its own colour. Both splits and both ways of storing
+ * the two bases — each on its own at four bits, or the second as a small difference from the first
+ * at five — are tried, and the least error kept. **What it gives up** is ETC2's three further modes,
+ * T, H and planar, which every ETC2 device decodes and this encoder never chooses: a smooth gradient
+ * across a block and a sharp edge between two colours come out a little coarser than a full search
+ * would make them. What would make that worth changing is a texture whose banding shows at the size
+ * it is seen.
+ *
+ * **EAC for everything that is not colour**: an alpha channel beside ETC2's colour, and one or two
+ * channels of data on their own (`eac-r11`, `eac-rg11`) — a roughness map, a normal map's x and y.
+ * Each block a base, a step size and one of sixteen tables of eight steps, searched per table.
+ *
+ * Texels past the edge of a level smaller than a block repeat the last row and column, so a 2x2 or
+ * 1x1 level is one block whose other texels match. Allocates the blocks it returns, once a level.
+ */
+/** The formats this encodes: colour, colour with alpha, and one or two channels of data. */
+export type Etc2Format = 'etc2-rgb8' | 'etc2-rgba8' | 'eac-r11' | 'eac-rg11';
+/** `rgba` at `width` by `height` as `format` blocks, row of blocks after row of blocks. */
+export declare function encodeEtc2(format: Etc2Format, rgba: Uint8Array, width: number, height: number): Uint8Array;
+/**
+ * One level of a block back to RGBA, for the modes this encoder writes and EAC: what a device
+ * decodes, stated here so the encoder can be held to a number. A block in T, H or planar mode is
+ * refused by name, since nothing here writes one.
+ */
+export declare function decodeEtc2(format: Etc2Format, blocks: Uint8Array, width: number, height: number): Uint8Array;