gputex 0.4.0 → 0.5.0

package/README.md

@@ -1,8 +1,6 @@
-# GPUtex | On-the-fly GPU texture encoding
+# gputex | GPU texture encoding
 
-Runtime GPU texture compression via WebGPU compute shaders, with a WebGL2 fragment-shader fallback. Feed it a PNG/JPG/WebP/AVIF — or an SVG, rasterised on the fly — and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, or BC1) ready for Three.js or React Three Fiber.
-
-⚠️ 100% vibe-coded. The code is completely unreviewed and under-tested. Do not use for anything important.
+Runtime GPU texture compression via WebGPU compute shaders, with a WebGL2 fragment-shader fallback. Feed it a PNG/JPG/WebP/AVIF — or an SVG, rasterised on the fly — and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, BC1, or ETC2) ready for Three.js or React Three Fiber.
 
 🚀 Used in production on [Mana Blade](https://manablade.com).
 
@@ -28,21 +26,26 @@ bun add gputex
 
 ## Formats
 
-| Format       | Bytes / 4x4 block | Use case                                                  |
-| ------------ | ----------------- | --------------------------------------------------------- |
-| **BC7**      | 16 (8 bpp)        | Color / RGBA on desktop (`texture-compression-bc`)        |
-| **BC5**      | 16 (8 bpp)        | Normal maps — RG only (`texture-compression-bc`)          |
-| **ASTC 4x4** | 16 (8 bpp)        | Color / RGBA on mobile / iOS (`texture-compression-astc`) |
-| **BC1**      | 8 (4 bpp)         | Opaque color at half BC7's size (opt-in)                  |
-
-Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed RGBA8 fallback otherwise.
-
-BC1 is never picked by default — it's half the memory of BC7 but visibly lower
-quality, a trade-off only the application can make. Opt in per-texture with
-`preferredFormat: 'bc1'`: on BC-capable devices the texture encodes as BC1;
-everywhere else (e.g. ASTC-only mobile) selection proceeds as normal. The
-preference is only honoured with `hint: 'color'`, since BC1 can't carry real
-alpha or a normal map.
+| Format        | Bytes / 4x4 block | Use case                                                                        |
+| ------------- | ----------------- | ------------------------------------------------------------------------------- |
+| **BC7**       | 16 (8 bpp)        | Color / RGBA on desktop (`texture-compression-bc`)                              |
+| **BC5**       | 16 (8 bpp)        | Normal maps — RG only (`texture-compression-bc`)                                |
+| **ASTC 4x4**  | 16 (8 bpp)        | Color / RGBA on mobile / iOS (`texture-compression-astc`)                       |
+| **BC1**       | 8 (4 bpp)         | Opaque color at half BC7's size (`quality: 'low'`)                              |
+| **ETC2 RGB8** | 8 (4 bpp)         | Opaque color at half ASTC's size (`texture-compression-etc2`, `quality: 'low'`) |
+
+Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, ETC2 as the
+last-resort compressed format for opaque colour, uncompressed RGBA8 fallback
+otherwise.
+
+The 4-bpp formats are never picked by default — half the memory of BC7/ASTC
+but visibly lower quality, a trade-off only the application can make. Opt in
+with `quality: 'low'`: opaque colour textures then encode as BC1 on BC-capable
+devices and as ETC2 RGB8 on ETC2-capable ones (most mobile GPUs), while
+`'colorWithAlpha'` and `'normal'` hints keep the high-quality formats (the
+4-bpp formats can't carry them). Per-texture, `preferredFormat: 'bc1'` forces
+BC1 on BC hardware the same way; both knobs fall back to the normal selection
+when unsupported, and both apply to `hint: 'color'` only.
 
 ## WebGL fallback
 
@@ -52,7 +55,7 @@ The fallback chain is **WebGPU → WebGL2 → uncompressed RGBA8**. The `backend
 
 Notes on the WebGL path:
 
-- It needs the matching WebGL2 compressed-texture extension to be sampleable: `EXT_texture_compression_bptc` (BC7), `EXT_texture_compression_rgtc` (BC5), `WEBGL_compressed_texture_astc` (ASTC), or `WEBGL_compressed_texture_s3tc` (BC1). Selection mirrors the WebGPU side, with BC1 added as a broadly-available last resort for **opaque** colour when neither BPTC nor ASTC is present.
+- It needs the matching WebGL2 compressed-texture extension to be sampleable: `EXT_texture_compression_bptc` (BC7), `EXT_texture_compression_rgtc` (BC5), `WEBGL_compressed_texture_astc` (ASTC), or `WEBGL_compressed_texture_s3tc` (BC1). Selection mirrors the WebGPU side, with BC1 added as a broadly-available last resort for **opaque** colour when neither BPTC nor ASTC is present. ETC2 is WebGPU-only (no WebGL fragment encoder), so `quality: 'low'` on the WebGL tier can only deliver BC1.
 - The `device` / `adapter` options apply to the WebGPU path only.
 - All encoding happens on one shared, off-screen WebGL2 context; nothing is drawn to a visible canvas.
 
@@ -88,6 +91,24 @@ it skips it and stays the cheapest per pixel. On GPUs that report the
 `shader-f16` feature everything runs in f16 — the f32 shaders are the
 automatic fallback.
 
+ETC2 is the exception to the endpoint-line story: its blocks are per-subblock
+base colours shifted by scalar modifier tables. The encoder exploits the
+algebra of that scalar shift — table and index selection depend only on each
+texel's luma-sum difference from the base, exactly (modulo decode clamping) —
+so the whole 8-table × 4-modifier search collapses to a handful of scalar
+threshold tests against a two-candidate table shortlist, with subblock error
+constants and the flip preselect computed O(1) from quadrant sums. A gated
+base-colour refit and a closed-form least-squares fit of ETC2's planar mode
+(which rescues the smooth gradients ETC1-style blocks band on) complete the
+block, all driven by the same estimates. The rewrite took the GPU pass
+from 6.0 ms to ~0.2 ms at 2048² (30×, within ~0.2 dB of the exhaustive
+search on photographic content — only the base refit was traded for
+speed). Its f16 module is EXACT-VALUE: lumas, D values and thresholds
+are integers f16 represents exactly, while the sums-of-squares estimates
+stay f32 (they overflow f16), so the two modules produce byte-identical
+output — f16 buys register pressure on mobile GPUs, not different
+results.
+
 On the repo's test cards this lands within **≤0.1 dB** of the exhaustive
 per-block reference encoders (BC5 matches the reference exactly; ASTC and
 BC1-on-normal-maps measure slightly above it), trailing only on adversarial
@@ -219,6 +240,38 @@ const { data, width, height, paddedWidth, paddedHeight } = await encoder.encodeT
 encoder.destroy()
 ```
 
+For mip chains, `encodeMipChainToBytes()` encodes every level in a **single
+GPU submission** — one compute pass and one readback instead of a full
+CPU↔GPU round trip per level (an 11-level 1024² chain is one `mapAsync`
+wait instead of eleven):
+
+```ts
+import { BC7Encoder, generateMipChain } from 'gputex'
+
+const encoder = await BC7Encoder.create()
+// level0 = { data: Uint8ClampedArray (RGBA8), width, height }
+const { levels, encodeMs } = await encoder.encodeMipChainToBytes(generateMipChain(level0))
+// levels[i] = { data, width, height, paddedWidth, paddedHeight }
+```
+
+When the source is an image (not raw pixels), skip the CPU entirely:
+`generateGpuMipChain()` uploads it once and box-filters the whole chain on
+the GPU in one compute pass, and `encodeMipChainFromTexture()` encodes
+straight from the texture's mip views — no `getImageData` readback, no JS
+filter, no per-level uploads. This is what `compressTexture()` uses for
+`mipmaps: true` (mipped BC7: 28 → 7.5 ms at 2048², 110 → 23 ms at 4096²),
+and its box filter is integer-exact against the CPU one, so both paths emit
+identical bytes:
+
+```ts
+import { BC7Encoder, generateGpuMipChain } from 'gputex'
+
+const encoder = await BC7Encoder.create()
+const chainTex = await generateGpuMipChain(encoder.device, imageBitmap, { flipY: true })
+const { levels, encodeMs } = await encoder.encodeMipChainFromTexture(chainTex)
+chainTex.destroy()
+```
+
 To turn an encoder's output into a Three.js `CompressedTexture` directly, use the helpers in `gputex/three`:
 
 ```ts
@@ -239,15 +292,42 @@ const tex = buildCompressedTexture([bytes], TextureFormat.BC7_SRGB)
 
 ### `compressTexture` options
 
-| Option            | Type                          | Default   | Description                                                                                      |
-| ----------------- | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------ |
-| `hint`            | `TextureHint`                 | `'color'` | `'color'`, `'colorWithAlpha'`, or `'normal'`                                                     |
-| `preferredFormat` | `'bc1'`                       | —         | Prefer BC1 (half of BC7's size) when supported; normal selection otherwise. `hint: 'color'` only |
-| `colorSpace`      | `'srgb' \| 'linear'`          | `'srgb'`  | Use the sRGB or linear variant of the chosen format                                              |
-| `svgSize`         | `number \| { width, height }` | intrinsic | Raster size for SVG sources: longest side (aspect preserved) or exact size                       |
-| `flipY`           | `boolean`                     | `true`    | Flip vertically (matches Three.js convention)                                                    |
-| `mipmaps`         | `boolean`                     | `false`   | Generate full mip chain down to 1x1                                                              |
-| `device`          | `GPUDevice`                   | —         | Reuse an existing WebGPU device instead of creating one                                          |
+| Option            | Type                          | Default   | Description                                                                                                              |
+| ----------------- | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `hint`            | `TextureHint`                 | `'color'` | `'color'`, `'colorWithAlpha'`, or `'normal'`                                                                             |
+| `quality`         | `'high' \| 'low'`             | `'high'`  | `'low'` picks the 4-bpp formats (BC1 on desktop, ETC2 RGB8 on mobile) for opaque colour — half the memory, lower quality |
+| `preferredFormat` | `'bc1'`                       | —         | Prefer BC1 (half of BC7's size) when supported; normal selection otherwise. `hint: 'color'` only                         |
+| `colorSpace`      | `'srgb' \| 'linear'`          | `'srgb'`  | Use the sRGB or linear variant of the chosen format                                                                      |
+| `svgSize`         | `number \| { width, height }` | intrinsic | Raster size for SVG sources: longest side (aspect preserved) or exact size                                               |
+| `flipY`           | `boolean`                     | `true`    | Flip vertically (matches Three.js convention)                                                                            |
+| `mipmaps`         | `boolean`                     | `false`   | Generate full mip chain down to 1x1                                                                                      |
+| `cache`           | `boolean`                     | `false`   | Session-scoped in-memory cache; repeat calls skip decode + encode (see below)                                            |
+| `cacheKey`        | `string`                      | derived   | Explicit cache identity (skips content hashing; makes pixel sources cacheable)                                           |
+| `device`          | `GPUDevice`                   | —         | Reuse an existing WebGPU device instead of creating one                                                                  |
+
+#### In-memory transcode cache
+
+With `cache: true`, the compressed bytes are kept in a session-scoped
+in-memory LRU keyed by source identity (URL, or a content hash for
+Blobs/Files/data URLs) plus the selected format and encode options. Loading
+the same texture again later in the session — say, two worlds sharing an
+atlas — skips **both** the image decode and the encode, the two dominant
+costs: a 4K PNG that takes ~220 ms to decode + encode comes back in ~30 ms
+(content-hashed) or ~2 ms (URL-keyed). Nothing touches persistent storage;
+the cache dies with the page. Total compressed payload is capped at 256 MiB
+with LRU eviction — `setTranscodeCacheLimit(bytes)` tunes it (0 disables),
+`clearTranscodeCache()` empties it (e.g. on world unload). Pixel sources
+(ImageBitmap, canvas, ImageData) are only cached when you pass a `cacheKey`.
+
+When neither `device` nor `adapter` is passed, `compressTexture()` shares one
+WebGPU device and one encoder per format across calls: the first call pays the
+adapter/device request and pipeline compile, subsequent calls skip straight to
+the encode and reuse the encoder's cached GPU resources. The result's
+`destroy()` only disposes that call's texture; call `releaseSharedGpuResources()`
+(also exported from `gputex/three`) to tear down the shared device — the next
+`compressTexture()` call transparently recreates it. With `mipmaps: true` the
+whole chain is encoded in a single GPU submission (one compute pass, one
+readback) rather than a round trip per level.
 
 ## Benchmarks
 
@@ -270,6 +350,16 @@ end-to-end wall time by ~10% at 512², ~20% at 1024–2048² and ~35% at 4096².
 | BC7      | f32           | 0.59 ms     |
 | ASTC 4×4 | f16 (default) | **0.26 ms** |
 | ASTC 4×4 | f32           | 0.56 ms     |
+| ETC2     | f16 + f32     | 0.20 ms     |
+
+The ETC2 figure is the interleaved `/ab` harness measurement (batched
+dispatches, clock-stable). On a 100 GB/s part just reading the 2048² RGBA8
+source costs ~0.15 ms, so the entire selection algorithm adds ~30% on top
+of touching the bytes. Two faster variants live in git history and were
+deliberately not shipped: a two-pass 2 B/px prepared source (encode pass
+0.115 ms, but the prep pass is also bandwidth-bound and cannot overlap, so
+the per-texture total regressed) and an O(1) hedged table pick (−3% for
+−0.5 dB — a poor trade against the scored search).
 
 Timestamps are quantised to 100 µs by Chrome and Apple GPU clock states swing
 timings by ~2×, so sub-millisecond figures are indicative (±0.1 ms); compare
@@ -319,7 +409,7 @@ consumer can run the same validation.
 
 - WebGPU (primary) **or** WebGL2 (fallback) — almost every current browser has at least one
 - A compressed-texture capability for compressed output:
-  - WebGPU: `texture-compression-bc` (desktop) or `texture-compression-astc` (mobile)
+  - WebGPU: `texture-compression-bc` (desktop), `texture-compression-astc` (mobile), or `texture-compression-etc2` (mobile)
   - WebGL2: `EXT_texture_compression_bptc` / `_rgtc`, `WEBGL_compressed_texture_astc`, or `WEBGL_compressed_texture_s3tc`
 - Falls back to uncompressed RGBA8 when no compressed format is available on either backend
 
@@ -329,4 +419,4 @@ consumer can run the same validation.
 
 ## Acknowledgements
 
-The concept of encoding images on the GPU on the fly via compute shaders was first introduced by [spark.js](https://ludicon.com/sparkjs/). GPUtex is not derived from Spark. Its encoders have been implemented from scratch using official references, which have been ported to TypeScript, and then converted to WGSL and GLSL via AI. Spark was never mentioned or used as reference at any point of the implementation, and multiple reviews have found the implementations to be completely independent. For any serious production use of GPU-compressed textures, Spark is the recommended choice over GPUtex.
+The concept of encoding images on the GPU on the fly via compute shaders was first introduced by [spark.js](https://ludicon.com/sparkjs/). gputex is not derived from Spark. Its encoders have been implemented from scratch using official references, which have been ported to TypeScript, and then converted to WGSL and GLSL via AI. Spark was never mentioned or used as reference at any point of the implementation, and multiple reviews have found the implementations to be completely independent. For any serious production use of GPU-compressed textures, Spark is the recommended choice over gputex.

package/dist/index.d.ts

@@ -6,6 +6,8 @@ declare const TextureFormat: {
     readonly BC7_SRGB: "BC7_SRGB";
     readonly ASTC_4x4: "ASTC_4x4";
     readonly ASTC_4x4_SRGB: "ASTC_4x4_SRGB";
+    readonly ETC2_RGB8: "ETC2_RGB8";
+    readonly ETC2_RGB8_SRGB: "ETC2_RGB8_SRGB";
 };
 type TextureFormat = (typeof TextureFormat)[keyof typeof TextureFormat];
 declare const WebGPUFeature: {
@@ -33,6 +35,31 @@ interface Capabilities {
 }
 declare function detectCapabilities(adapter: FeatureProvider): Capabilities;
 
+/** One level of a mip chain. 4 bytes per pixel (RGBA8). */
+interface MipLevel {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+/**
+ * Produce the full mip chain from a level-0 image. The chain goes down
+ * to a 1×1 level — the standard OpenGL / WebGPU convention — so the
+ * caller gets `floor(log2(max(w, h))) + 1` levels total.
+ *
+ * Levels whose logical dimensions are below the encoder's 4×4 block
+ * grid are still produced here at their true logical size; padding up
+ * to a single block is the encoder's job, not ours.
+ */
+declare function generateMipChain(level0: MipLevel): MipLevel[];
+/**
+ * Pad a mip level up to a multiple of 4 in each dimension using clamp-
+ * to-edge sampling. Used before handing sub-4×4 levels to a block-
+ * compression encoder, which requires at least one full block per level.
+ *
+ * If the input is already block-aligned this returns the input unchanged.
+ */
+declare function padToBlockMultiple(level: MipLevel): MipLevel;
+
 /**
  * Anything `GPUQueue.copyExternalImageToTexture` accepts. Matches the
  * WebGPU spec's CopyExternalImageSource set.
@@ -54,17 +81,21 @@ interface EncodeCallOptions {
     colorSpace?: 'srgb' | 'linear';
 }
 /**
- * Result of a raw bytes-only encode. This is the encoder's native output: the
- * compressed block bytes plus dimensions, with no Three.js (or any engine)
- * involvement. Feed `data` into whatever renderer's compressed-texture upload
- * you like, or use `buildCompressedTexture()` from `gputex/three`.
+ * One level of encoded output: the compressed block bytes plus logical and
+ * block-aligned dimensions. This is the encoder's native output shape, with
+ * no Three.js (or any engine) involvement — feed `data` into whatever
+ * renderer's compressed-texture upload you like, or use
+ * `buildCompressedTexture()` from `gputex/three`.
  */
-interface EncodeBytesResult {
+interface EncodedLevelBytes {
     width: number;
     height: number;
     paddedWidth: number;
     paddedHeight: number;
     data: Uint8Array;
+}
+/** Result of a raw bytes-only single-image encode. */
+interface EncodeBytesResult extends EncodedLevelBytes {
     encodeMs: number;
     /**
      * GPU-side compute-pass time in ms, measured with timestamp queries.
@@ -75,6 +106,16 @@ interface EncodeBytesResult {
      */
     gpuMs?: number;
 }
+/** Result of a whole-chain encode — see `Encoder.encodeMipChainToBytes()`. */
+interface EncodeMipChainResult {
+    /** Encoded levels in the order given; `levels[0]` is the base level. */
+    levels: EncodedLevelBytes[];
+    /** Wall-clock time for the whole chain: uploads → dispatches → readback. */
+    encodeMs: number;
+    /** GPU compute time for the whole chain's single compute pass (see
+     *  `EncodeBytesResult.gpuMs` for caveats). */
+    gpuMs?: number;
+}
 interface FormatVariant {
     colorSpace: 'srgb' | 'linear';
 }
@@ -116,16 +157,34 @@ declare abstract class Encoder {
     readonly adapter?: GPUAdapter;
     readonly ownsDevice: boolean;
     readonly disableF16: boolean;
-    protected _pipeline: GPUComputePipeline;
+    protected _pipelineReady: Promise<GPUComputePipeline>;
+    protected _prepPipelineReady: Promise<GPUComputePipeline> | null;
     private _cachedSrcTex;
     private _cachedSrcW;
     private _cachedSrcH;
+    private _cachedSrcSource;
+    private _cachedSrcFlipY;
     private _cachedDst;
     private _cachedStaging;
     private _cachedParams;
     private _lastParams;
     private _cachedBindGroup;
+    private _cachedPrepPlanes;
+    private _cachedPrepBindGroup;
     private _resourcesBusy;
+    /** Set when the active shader declares a @binding(3) sampler (the BC5
+     * kernels read texels through textureGather + clamp-to-edge). */
+    private _usesSampler;
+    private _sampler;
+    private _chainSig;
+    private _chainTextures;
+    private _chainPrepPlanes;
+    private _chainPrepBindGroups;
+    private _chainParams;
+    private _chainBindGroups;
+    private _chainDst;
+    private _chainStaging;
+    private _chainBusy;
     constructor({ device, adapter, ownsDevice, disableF16 }: EncoderOptions);
     protected _buildPipeline(): void;
     destroy(): void;
@@ -133,10 +192,27 @@ declare abstract class Encoder {
     abstract get label(): string;
     /** 8 for BC1/BC4, 16 for BC5/BC7/ASTC 4×4. */
     abstract get bytesPerBlock(): number;
+    /**
+     * Pipeline-creation override constants for the active shader, or
+     * undefined for none. Subclasses expose quality/behaviour toggles this
+     * way so the OFF state is dead-coded by the shader compiler instead of
+     * branched at runtime.
+     */
+    protected pipelineConstants(): Record<string, number> | undefined;
     /** WGSL `@workgroup_size` dimensions. Default 8×8×1. */
     get workgroupSize(): readonly [number, number, number];
     /** Whether this format has an sRGB variant. Default true. */
     get supportsSrgb(): boolean;
+    /**
+     * Format of the single-shot source texture the encode pass samples.
+     * Encoders that read only a channel subset can narrow it to cut DRAM
+     * traffic on the bandwidth-bound compute pass (BC5 reads rg8unorm — half
+     * the bytes of rgba8). Must be valid as a copyExternalImageToTexture
+     * destination and renderable. Chain encodes keep rgba8unorm regardless
+     * (their inputs are RGBA mip levels / texture views); the WGSL is
+     * format-agnostic (`texture_2d<f32>`), so mixing is byte-identical.
+     */
+    protected get srcTextureFormat(): GPUTextureFormat;
     /**
      * Optional f16 WGSL variant. Used only when the device reports the
      * `shader-f16` feature; the format's f32 `wgslSource()` is the automatic
@@ -147,6 +223,21 @@ declare abstract class Encoder {
     protected get _useF16(): boolean;
     /** WGSL compute-shader source (f32; the fallback when f16 is unavailable). */
     abstract wgslSource(): string;
+    /** WGSL for the preparation pass, or null when the encoder reads the
+     *  RGBA8 source directly. */
+    protected wgslPrepSource(): string | null;
+    /** Formats and sizes of the prepared planes for a padded source size. */
+    protected prepPlanes(paddedWidth: number, paddedHeight: number): {
+        format: GPUTextureFormat;
+        width: number;
+        height: number;
+    }[];
+    /** Workgroup counts for the prep dispatch. */
+    protected prepDispatch(blocksX: number, blocksY: number): [number, number];
+    /** Create the prepared-plane textures for one padded source size. */
+    private _createPrepPlanes;
+    /** Bind group for one prep dispatch. */
+    private _createPrepBindGroup;
     /** e.g. 'bc1-rgba-unorm-srgb'. */
     abstract gpuTextureFormat(opts: FormatVariant): GPUTextureFormat;
     /**
@@ -166,6 +257,55 @@ declare abstract class Encoder {
         flipY?: boolean;
         withGpuTime?: boolean;
     }): Promise<EncodeBytesResult>;
+    /**
+     * Encode a whole mip chain in ONE GPU submission. A per-level
+     * `encodeToBytes()` loop costs a full CPU↔GPU round trip per level (a
+     * 1024² chain is 11 levels → 11 `mapAsync` waits with the GPU idle in
+     * between); this path uploads every level, records one dispatch per level
+     * into a single compute pass, copies all outputs into one staging buffer
+     * and maps it once.
+     *
+     * `levels` are raw RGBA8 pixels in base-to-tail order; sizes don't have to
+     * halve level-to-level (each level is padded and clamped independently,
+     * exactly like `encodeToBytes`). Uploads use `writeTexture` — the direct
+     * raw-bytes path, which also sidesteps the broken
+     * `copyExternalImageToTexture` devices (see workarounds.ts). There is no
+     * flip option: bake any vertical flip into level 0 before generating the
+     * chain, as `compressTexture()` does.
+     */
+    encodeMipChainToBytes(levels: readonly MipLevel[], { withGpuTime }?: {
+        withGpuTime?: boolean;
+    }): Promise<EncodeMipChainResult>;
+    /**
+     * Encode every mip level of a GPU-resident texture in one submission —
+     * the zero-CPU-pixels counterpart of `encodeMipChainToBytes()`. Pair it
+     * with `generateGpuMipChain()` (gpuMipgen.ts): upload the image once,
+     * box-filter the chain on the GPU, then encode straight from the
+     * texture's mip views. Pixels never transit the CPU between the source
+     * image and the compressed-bytes readback.
+     *
+     * `srcTex` must be `rgba8unorm` with TEXTURE_BINDING usage; level 0's
+     * dimensions are taken from the texture and lower levels follow the
+     * standard floor-halving chain. Encoded output is identical to feeding
+     * the equivalent CPU chain to `encodeMipChainToBytes()`.
+     */
+    encodeMipChainFromTexture(srcTex: GPUTexture, { withGpuTime }?: {
+        withGpuTime?: boolean;
+    }): Promise<EncodeMipChainResult>;
+    /** Block-grid geometry + packed output offsets for a chain of levels.
+     *  `byteSpan` is both the dst buffer size and the readback copy size (a
+     *  multiple of 4: byteLen is a multiple of bytesPerBlock ≥ 8, offsets are
+     *  CHAIN_ALIGN-ed). */
+    private _chainGeometry;
+    /** Shared chain-encode tail: one compute pass with a dispatch per level,
+     *  one submit, one staging readback sliced into per-level byte arrays. */
+    private _submitChainAndRead;
+    /** Create the query set + resolve/staging buffers for one timed
+     *  submission, or null when the device lacks 'timestamp-query'. */
+    private _createTiming;
+    /** Read back a timed submission's pass duration (ms) and destroy the
+     *  timing objects. Timestamps are u64 nanoseconds. */
+    private _readTimingMs;
 }
 
 declare class BC1Encoder extends Encoder {
@@ -185,14 +325,26 @@ declare class BC5Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    protected get srcTextureFormat(): GPUTextureFormat;
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat(): GPUTextureFormat;
 }
 
+interface BC7EncoderOptions extends EncoderOptions {
+    /**
+     * Emit BC7 mode 4 on decorrelated blocks (normal maps, channel-packed
+     * atlases): a large quality win there, at up to ~1.5× encode time on
+     * exactly that content. See the header note for the measurements.
+     */
+    adaptiveMode4?: boolean;
+}
 declare class BC7Encoder extends Encoder {
     static readonly requiredFeature: GPUFeatureName;
     static readonly textureFormats: readonly TextureFormat[];
+    private readonly adaptiveMode4;
+    constructor(opts: BC7EncoderOptions);
+    protected pipelineConstants(): Record<string, number> | undefined;
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
@@ -212,6 +364,17 @@ declare class ASTC4x4Encoder extends Encoder {
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
 }
 
+declare class ETC2Encoder extends Encoder {
+    static readonly requiredFeature: GPUFeatureName;
+    static readonly textureFormats: readonly TextureFormat[];
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    wgslSource(): string;
+    wgslSourceFastF16(): string;
+    gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
+}
+
 /** Raw RGBA8 pixel data (e.g. a CPU-generated mip level). */
 interface RawPixelSource {
     data: ArrayBufferView;
@@ -358,16 +521,26 @@ type TextureHint = 'color' | 'colorWithAlpha' | 'normal';
 /**
  * Optional format preference — a wish, not a demand. Applied when the
  * device supports the format and the hint is compatible; otherwise
- * selection proceeds normally (BC7 → ASTC → null). Currently only
+ * selection proceeds normally (BC7 → ASTC → ETC2 → null). Currently only
  * 'bc1': half the memory of BC7 (0.5 vs 1 byte/pixel) for opaque
  * colour, at visibly lower quality on smooth content.
  */
 type PreferredFormat = 'bc1';
+/**
+ * Memory/fidelity trade-off for opaque colour textures. 'high' (default)
+ * picks the 8-bpp formats (BC7 / ASTC 4×4); 'low' picks the 4-bpp ones
+ * (BC1 / ETC2 RGB8) when the adapter supports one. Hints that the 4-bpp
+ * formats can't carry ('colorWithAlpha', 'normal') ignore this and keep
+ * the 'high' selection.
+ */
+type FormatQuality = 'high' | 'low';
 interface SelectFormatOptions {
     /** Pick the sRGB variant when the format has one. Default 'srgb'. */
     colorSpace?: 'srgb' | 'linear';
     /** Prefer a specific format when supported. See `PreferredFormat`. */
     preferredFormat?: PreferredFormat;
+    /** Memory/fidelity trade-off. See `FormatQuality`. Default 'high'. */
+    quality?: FormatQuality;
 }
 interface FormatSelection {
     /** null = no compressed path on this adapter; caller should fall back. */
@@ -393,30 +566,21 @@ interface WebGLFormatSelection {
 }
 declare function selectWebGLFormat(caps: WebGLCapabilities, hint: TextureHint, options?: SelectFormatOptions): WebGLFormatSelection;
 
-/** One level of a mip chain. 4 bytes per pixel (RGBA8). */
-interface MipLevel {
-    data: Uint8ClampedArray;
-    width: number;
-    height: number;
-}
+/** Matches mipgen's chain length: floor(log2(max(w, h))) + 1 levels. */
+declare function gpuMipLevelCount(width: number, height: number): number;
 /**
- * Produce the full mip chain from a level-0 image. The chain goes down
- * to a 1×1 level — the standard OpenGL / WebGPU convention — so the
- * caller gets `floor(log2(max(w, h))) + 1` levels total.
+ * Upload `source` and generate its full mip chain on the GPU. Returns an
+ * `rgba8unorm` texture with `gpuMipLevelCount` levels whose dimensions
+ * follow the standard floor-halving chain; feed it to
+ * `Encoder.encodeMipChainFromTexture()`. The caller owns the texture —
+ * destroy it after encoding.
  *
- * Levels whose logical dimensions are below the encoder's 4×4 block
- * grid are still produced here at their true logical size; padding up
- * to a single block is the encoder's job, not ours.
+ * The returned promise resolves once the work is submitted (not completed);
+ * queue ordering makes the levels visible to any later submission.
  */
-declare function generateMipChain(level0: MipLevel): MipLevel[];
-/**
- * Pad a mip level up to a multiple of 4 in each dimension using clamp-
- * to-edge sampling. Used before handing sub-4×4 levels to a block-
- * compression encoder, which requires at least one full block per level.
- *
- * If the input is already block-aligned this returns the input unchanged.
- */
-declare function padToBlockMultiple(level: MipLevel): MipLevel;
+declare function generateGpuMipChain(device: GPUDevice, source: ImageBitmap | ImageData | HTMLCanvasElement | OffscreenCanvas, { flipY }?: {
+    flipY?: boolean;
+}): Promise<GPUTexture>;
 
 /**
  * Target raster size for an SVG source. A number scales the SVG so its
@@ -441,4 +605,4 @@ interface RasterizeSvgOptions {
  */
 declare function rasterizeSvg(source: string | Blob, options?: RasterizeSvgOptions): Promise<ImageBitmap>;
 
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type EncodeBytesResult, type EncodeCallOptions, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, type MipLevel, type PreferredFormat, type RasterizeSvgOptions, type RawPixelSource, type SelectFormatOptions, type SvgRasterSize, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, selectFormat, selectWebGLFormat };
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, type BC7EncoderOptions, BC7WebGLEncoder, type Capabilities, ETC2Encoder, type EncodeBytesResult, type EncodeCallOptions, type EncodeMipChainResult, type EncodedLevelBytes, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatQuality, type FormatSelection, type FormatVariant, type MipLevel, type PreferredFormat, type RasterizeSvgOptions, type RawPixelSource, type SelectFormatOptions, type SvgRasterSize, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, selectFormat, selectWebGLFormat };