gputex 0.1.2 → 0.3.0

package/README.md

@@ -1,8 +1,10 @@
-# GPUtex
+# GPUtex | On-the-fly GPU texture encoding
 
 Runtime GPU texture compression via WebGPU compute shaders, with a WebGL2 fragment-shader fallback. Feed it a PNG/JPG/WebP/AVIF and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, or BC1) ready for Three.js or React Three Fiber.
 
-⚠️: This is 100% vibe-coded. The code is completely unreviewed, under-tested, it will probably crash on many devices, and this library is very likely to go unmaintained. Do not use for anything important.
+⚠️ 100% vibe-coded. The code is completely unreviewed and under-tested. Do not use for anything important.
+
+🚀 Used in production on [Mana Blade](https://manablade.com).
 
 ## Install
 
@@ -14,7 +16,15 @@ pnpm add gputex
 bun add gputex
 ```
 
-`three` is a peer dependency (`>=0.180`).
+### Entry points
+
+`gputex` ships three entry points:
+
+- **`gputex`** — the engine-agnostic core: the `*Encoder` classes, capability / format detection, and mip helpers. Nothing here imports `three`, so it works with Babylon.js, raw WebGPU/WebGL, workers, etc. Encoders return raw compressed block bytes via `encodeToBytes()`.
+- **`gputex/three`** — the Three.js layer. Re-exports the entire core **plus** `compressTexture()`, `GputexLoader`, and `buildCompressedTexture()` / `encodeToTexture()`. This is the only entry that imports `three`.
+- **`gputex/testing`** — the CPU reference encoders/decoders the GPU shaders are validated against. Test-suite material, not runtime API (see [Testing](#testing)).
+
+`three` is an **optional** peer dependency (`>=0.170`): install it only if you import `gputex/three`. Pure-core consumers (e.g. Babylon.js) can skip it entirely.
 
 ## Formats
 
@@ -29,7 +39,7 @@ Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed
 
 ## WebGL fallback
 
-WebGPU is the primary path. When it's unavailable (older Safari, Firefox without WebGPU, locked-down environments) `compressTexture()` automatically falls back to a **WebGL2** path that runs the same block encoders as fragment shaders — each 4×4 block is computed in one fragment, written to an `RGBA32UI` render target, and read back. The output bytes are identical to the WebGPU encoders, so the resulting `CompressedTexture` looks the same under either renderer.
+WebGPU is the primary path. When it's unavailable (older Safari, Firefox without WebGPU, locked-down environments) `compressTexture()` automatically falls back to a **WebGL2** path that runs the same family of block encoders as fragment shaders — each 4×4 block is computed in one fragment, written to an `RGBA32UI` render target, and read back. The WebGPU fast paths have since been rewritten for speed (projection assignment, f16), so the two backends are no longer byte-identical, but they implement the same algorithms at the same quality level and the resulting `CompressedTexture` looks the same under either renderer.
 
 The fallback chain is **WebGPU → WebGL2 → uncompressed RGBA8**. The `backend` field on the result (`'webgpu' | 'webgl' | 'none'`) tells you which path ran.
 
@@ -44,7 +54,7 @@ Notes on the WebGL path:
 ### `compressTexture` — direct API
 
 ```ts
-import { compressTexture } from 'gputex'
+import { compressTexture } from 'gputex/three'
 
 const { texture, format } = await compressTexture('/cobblestone.avif', {
   hint: 'color', // 'color' | 'colorWithAlpha' | 'normal'
@@ -63,19 +73,23 @@ material.map = texture
 - **`'fast'` (default)** — a bounding-box endpoint seed plus projection-based
   index assignment (each pixel is projected onto the colinear endpoint line in
   O(1) instead of searching every palette entry) with a single fused
-  least-squares refit. On GPUs that report the `shader-f16` feature the whole
-  fast path runs in f16 (≈2× on Apple) — the f32 path is the automatic
-  fallback. Net vs `'high'` on an Apple GPU: **BC7 ~50×**, **ASTC ~9×**,
-  **BC5 ~5×** faster, for a PSNR cost of **≤0.45 dB** (imperceptible). BC1 is
-  single-pass and unaffected.
+  least-squares refit (accepted per block only when it lowers the error), and
+  the block bits packed with straight-line constant shifts. On GPUs that
+  report the `shader-f16` feature the whole fast path (all four formats, BC1
+  included) runs in f16 — the f32 path is the automatic fallback. Net vs
+  `'high'` on an Apple GPU: roughly **10–30× faster** depending on format,
+  for a PSNR cost of **≤0.65 dB on smooth/flat content** (imperceptible) and
+  up to a few dB on adversarial high-frequency noise, where the bbox seed
+  trails `'high'`'s exhaustive search. See the benchmark table below.
 - **`'high'`** — exhaustive endpoint search (farthest-pair seed, full nearest
-  search, p-bit search); output is byte-for-byte identical to the CPU reference
-  encoders.
+  search, p-bit search); matches the CPU reference encoders block-for-block
+  (byte-identical on >96% of blocks; the rest are equal-error FP tie-breaks,
+  enforced by the GPU test suite).
 
 ### `GputexLoader` — Three.js Loader
 
 ```ts
-import { GputexLoader } from 'gputex'
+import { GputexLoader } from 'gputex/three'
 
 const loader = new GputexLoader()
 loader.hint = 'normal'
@@ -90,7 +104,7 @@ The `GputexLoader` works with R3F's `useLoader`:
 
 ```tsx
 import { useLoader } from '@react-three/fiber'
-import { GputexLoader } from 'gputex'
+import { GputexLoader } from 'gputex/three'
 
 function Scene() {
   const texture = useLoader(GputexLoader, '/cobblestone.avif', loader => {
@@ -113,7 +127,7 @@ For a reusable hook with metadata access:
 ```tsx
 import { useLayoutEffect } from 'react'
 import { useLoader } from '@react-three/fiber'
-import { GputexLoader } from 'gputex'
+import { GputexLoader } from 'gputex/three'
 import type { TextureHint } from 'gputex'
 
 function useGputex(url: string, options?: { hint?: TextureHint; colorSpace?: 'srgb' | 'linear'; mipmaps?: boolean }) {
@@ -157,18 +171,35 @@ function Scene() {
 }
 ```
 
-### Low-level encoders
+### Low-level encoders (any engine)
 
-Individual encoder classes are exported for direct control:
+The individual encoder classes live in the engine-agnostic core (`gputex`). `encodeToBytes()` returns raw compressed block bytes with no Three.js involvement — feed them into whatever compressed-texture upload your engine exposes (Babylon.js, raw WebGPU/WebGL, …):
 
 ```ts
 import { BC7Encoder, BC5Encoder, ASTC4x4Encoder, BC1Encoder } from 'gputex'
 
 const encoder = await BC7Encoder.create()
-const { data, width, height } = await encoder.encodeToBytes(imageBitmap)
+const { data, width, height, paddedWidth, paddedHeight } = await encoder.encodeToBytes(imageBitmap)
+// `data` is a Uint8Array of BC7 blocks covering paddedWidth × paddedHeight.
 encoder.destroy()
 ```
 
+To turn an encoder's output into a Three.js `CompressedTexture` directly, use the helpers in `gputex/three`:
+
+```ts
+import { BC7Encoder, TextureFormat } from 'gputex'
+import { encodeToTexture, buildCompressedTexture } from 'gputex/three'
+
+const encoder = await BC7Encoder.create()
+
+// One-shot: image → CompressedTexture (plus the raw byte metadata)
+const { texture } = await encodeToTexture(encoder, imageBitmap, { colorSpace: 'srgb' })
+
+// …or assemble a texture from bytes you already have (e.g. a mip chain):
+const bytes = await encoder.encodeToBytes(imageBitmap)
+const tex = buildCompressedTexture([bytes], TextureFormat.BC7_SRGB)
+```
+
 ## Options
 
 ### `compressTexture` options
@@ -181,6 +212,77 @@ encoder.destroy()
 | `mipmaps`    | `boolean`            | `false`   | Generate full mip chain down to 1x1                     |
 | `device`     | `GPUDevice`          | —         | Reuse an existing WebGPU device instead of creating one |
 
+## Benchmarks
+
+Measured with the repo's GPU test suite (see below) on an Apple Silicon GPU
+(`metal-3`) in Chrome, encoding a 2048×2048 image. **GPU pass** is the compute
+shader alone (WebGPU timestamp queries, median of 20 runs); end-to-end wall
+time adds ~3–4 ms of image upload + result readback regardless of format.
+"Before" is the shader generation prior to the 2026-07 optimization pass
+(projection-based index assignment everywhere, on-the-fly bit packing, an f16
+BC1 fast shader, straight-line block assembly).
+
+| Format   | Quality        | Shader | GPU pass before | GPU pass after | Speedup   |
+| -------- | -------------- | ------ | --------------- | -------------- | --------- |
+| BC1      | fast (default) | f16    | — (had no f16)  | **0.26 ms**    | **2.8×**¹ |
+| BC1      | fast           | f32    | 0.72 ms         | 0.33 ms        | 2.2×      |
+| BC5      | fast (default) | f16    | 0.33 ms         | **0.20 ms**    | 1.7×      |
+| BC5      | fast           | f32    | 0.79 ms         | 0.39 ms        | 2.0×      |
+| BC7      | fast (default) | f16    | 1.38 ms         | **0.52 ms**    | 2.7×      |
+| BC7      | fast           | f32    | 2.65 ms         | 1.70 ms        | 1.6×      |
+| ASTC 4×4 | fast (default) | f16    | 0.33 ms         | **0.20 ms**    | 1.7×      |
+| ASTC 4×4 | fast           | f32    | 0.72 ms         | 0.66 ms        | 1.1×      |
+| BC1      | high           | f32    | 2.9 ms          | 3.0 ms         | unchanged |
+| BC5      | high           | f32    | 3.4 ms          | 3.4 ms         | unchanged |
+| BC7      | high           | f32    | 14.1 ms         | 14.1 ms        | unchanged |
+| ASTC 4×4 | high           | f32    | 2.6 ms          | 2.4 ms         | unchanged |
+
+¹ vs the old f32 fast shader, which was the only BC1 fast path before. The
+BC1 rows were measured with old and new pipelines interleaved in one session
+(the most noise-robust method); the others are cross-run suite medians.
+
+Per-quadrant PSNR on the committed 512² test card is equal to or better than
+the previous fast encoders everywhere (flat tiles bit-identical, gradients
++0.01 dB, noise −0.01 dB); the `high` paths still match the CPU reference
+encoders. Timestamps are quantised to 100 µs by Chrome, so sub-millisecond
+figures are ±0.05–0.1 ms.
+
+## Testing
+
+Unit tests (`bun test`) cover the CPU reference encoders and metadata, but the
+WGSL shaders can only be validated on a real GPU. The repo ships a browser
+test + benchmark suite at `example/pages/test.tsx` (logic in
+`example/lib/gpuTestSuite.ts`):
+
+```sh
+bun run --filter gputex build   # build the library the example consumes
+cd example && bunx next dev     # then open http://localhost:3000/test
+```
+
+The page runs three groups against the live WebGPU device and renders
+PASS/FAIL tables (machine-readable copy on `window.__GPUTEX_TESTS__`):
+
+- **Correctness** — `quality: 'high'` output is compared block-by-block
+  against the CPU reference encoders (`gputex/testing`), including a
+  non-multiple-of-4 image for the clamp-to-edge padding path. Differing blocks
+  must have equal decoded error (FP tie-break tolerance) and the aggregate
+  PSNR delta must be ≤0.05 dB. Plus determinism checks (same input twice →
+  identical bytes).
+- **Quality** — `'fast'` and `'high'` output is CPU-decoded and validated on
+  the FULL 512² test cards (every quadrant stresses a different failure mode)
+  with two gates, for both the f16 and (force-disabled-f16) f32 shaders:
+  aggregate PSNR must beat per-format thresholds pinned ~0.15 dB under the
+  measured baseline, and — because a handful of catastrophically wrong blocks
+  barely moves aggregate PSNR — the worst _easy_ block (one that `'high'`
+  encodes near-losslessly) must not exceed `'high'`'s error by more than a
+  small per-format limit.
+- **Performance** — the benchmark table above: wall + GPU-pass time per
+  format × quality × shader variant.
+
+The `gputex/testing` entry point exports the CPU reference
+encoders/decoders (`encodeBC7Mode6Block`, `decodeASTC4x4Block`, …) so any
+consumer can run the same validation.
+
 ## Requirements
 
 - WebGPU (primary) **or** WebGL2 (fallback) — almost every current browser has at least one
@@ -195,4 +297,4 @@ encoder.destroy()
 
 ## 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/), which is a much more robust solution for users who can afford its license. GPUtex is not derived from Spark and its encoders have been implemented from scratch using official references, which have been ported to TypeScript, and then converted to WGSL via AI. 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

@@ -1,5 +1,3 @@
-import { CompressedPixelFormat, CompressedTexture, Texture, Loader } from 'three';
-
 declare const TextureFormat: {
     readonly BC1: "BC1";
     readonly BC1_SRGB: "BC1_SRGB";
@@ -44,13 +42,19 @@ interface EncoderOptions {
     device: GPUDevice;
     adapter?: GPUAdapter;
     ownsDevice?: boolean;
+    /**
+     * Force the f32 'fast' shader even when the device supports shader-f16.
+     * For tests/benchmarks that need to exercise the f32 fallback path on
+     * f16-capable hardware. Default false.
+     */
+    disableF16?: boolean;
 }
 /**
- * Encoder quality level. 'fast' (default) uses the cheaper search paths in the
- * shaders — measured ~2–4× faster for ≤0.36 dB PSNR. 'high' runs the exhaustive
- * search, producing output byte-identical to the CPU reference encoders (BC5/
- * BC7/ASTC). BC1's 'high' adds a principal-axis endpoint seed and iterative
- * refit on top of the 'fast' bbox+refit path.
+ * Encoder quality level. 'fast' (default) uses the projection-based paths in
+ * the shaders — an order of magnitude faster for a ≤0.65 dB PSNR cost. 'high'
+ * runs the exhaustive search, matching the CPU reference encoders
+ * block-for-block (byte-identical up to FP tie-breaks with equal error).
+ * BC1's 'high' adds a principal-axis endpoint seed and iterative refit.
  */
 type EncodeQuality = 'fast' | 'high';
 interface EncodeCallOptions {
@@ -59,19 +63,11 @@ interface EncodeCallOptions {
     /** Encode quality / speed trade-off. Default 'fast'. */
     quality?: EncodeQuality;
 }
-interface EncodeResult {
-    width: number;
-    height: number;
-    paddedWidth: number;
-    paddedHeight: number;
-    data: Uint8Array;
-    texture: CompressedTexture;
-    encodeMs: number;
-}
 /**
- * Result of a raw bytes-only encode (no wrapping in a `CompressedTexture`).
- * Used by the mipped encode path to bundle multiple levels into a single
- * `CompressedTexture` at the end.
+ * 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`.
  */
 interface EncodeBytesResult {
     width: number;
@@ -80,6 +76,14 @@ interface EncodeBytesResult {
     paddedHeight: number;
     data: Uint8Array;
     encodeMs: number;
+    /**
+     * GPU-side compute-pass time in ms, measured with timestamp queries.
+     * Present only when the encode was called with `withGpuTime: true` and the
+     * device has the 'timestamp-query' feature (requested automatically by
+     * `create()` when available). Browsers quantise timestamps (Chrome: 100µs),
+     * so treat small values as approximate.
+     */
+    gpuMs?: number;
 }
 interface FormatVariant {
     colorSpace: 'srgb' | 'linear';
@@ -96,6 +100,8 @@ interface FormatVariant {
 type EncoderConstructor<T extends Encoder = Encoder> = {
     new (opts: EncoderOptions): T;
     requiredFeature: GPUFeatureName | null;
+    /** Logical formats this encoder can emit (linear first, then sRGB variant). */
+    readonly textureFormats: readonly TextureFormat[];
     create(): Promise<T>;
 };
 declare abstract class Encoder {
@@ -119,12 +125,13 @@ declare abstract class Encoder {
     readonly device: GPUDevice;
     readonly adapter?: GPUAdapter;
     readonly ownsDevice: boolean;
+    readonly disableF16: boolean;
     protected _module: GPUShaderModule;
     protected _moduleF16: GPUShaderModule | null;
     protected _pipelineF16: GPUComputePipeline | null;
     protected _pipeline: GPUComputePipeline;
     protected _pipelineCache: Map<EncodeQuality, GPUComputePipeline>;
-    constructor({ device, adapter, ownsDevice }: EncoderOptions);
+    constructor({ device, adapter, ownsDevice, disableF16 }: EncoderOptions);
     protected _buildPipeline(): void;
     /**
      * Pipeline for a given quality level. Encoders that don't declare a
@@ -150,7 +157,7 @@ declare abstract class Encoder {
     /**
      * Optional f16 WGSL for the 'fast' path. Used only when the device reports the
      * `shader-f16` feature; the format's f32 `wgslSource()` is the fallback and
-     * `'high'` always uses it. Returns null when there's no f16 variant (BC1).
+     * `'high'` always uses it. Returns null when there's no f16 variant.
      */
     wgslSourceFastF16(): string | null;
     /** Whether the f16 fast path is both available and supported on this device. */
@@ -159,40 +166,24 @@ declare abstract class Encoder {
     abstract wgslSource(): string;
     /** e.g. 'bc1-rgba-unorm-srgb'. */
     abstract gpuTextureFormat(opts: FormatVariant): GPUTextureFormat;
-    /** Three.js `CompressedPixelFormat` constant for `CompressedTexture`. */
-    abstract threeTextureFormat(opts: FormatVariant): CompressedPixelFormat;
     /**
      * True if the device reports the feature the output texture needs.
      * The encoder itself only writes to a storage buffer, so this is about
      * whether the result can actually be sampled.
      */
     get supportsSampling(): boolean;
-    encode(source: EncoderImageSource, { colorSpace, quality }?: EncodeCallOptions): Promise<EncodeResult>;
     /**
-     * Encode one image source to raw compressed bytes, skipping the
-     * `CompressedTexture` wrap. Used by the public `encode()` above and by
-     * the mipped encode path in `compressTexture()` so N mip levels end up
-     * in a single `CompressedTexture` instead of N throwaway wrappers.
-     *
-     * Public (not protected) because `compressTexture()` calls it across the
-     * encoder boundary. Still safe to call from outside — it just does
-     * less work than `encode()` and the caller assembles the texture.
+     * Encode one image source to raw compressed bytes. This is the encoder's
+     * native, engine-agnostic output. `compressTexture()` and
+     * `encodeToTexture()` (both in `gputex/three`) call it and then wrap the
+     * bytes into a `CompressedTexture`; callers targeting another engine feed
+     * `data` into that engine's compressed-texture upload directly.
      */
-    encodeToBytes(source: EncoderImageSource, { flipY, quality }?: {
+    encodeToBytes(source: EncoderImageSource, { flipY, quality, withGpuTime, }?: {
         flipY?: boolean;
         quality?: EncodeQuality;
+        withGpuTime?: boolean;
     }): Promise<EncodeBytesResult>;
-    /**
-     * Assemble a `CompressedTexture` from pre-encoded mip levels. Called
-     * by `compressTexture()` after it has run each level through
-     * `encodeToBytes()`. Centralised here so the single-level and mipped
-     * paths share the same format / colour-space / wrap settings.
-     *
-     * `levels[0]` is the base level; its padded dimensions become the
-     * texture's overall size. Filter setup assumes at least 2 levels →
-     * trilinear; 1 level → bilinear.
-     */
-    buildMippedTexture(levels: readonly EncodeBytesResult[], { colorSpace }?: EncodeCallOptions): CompressedTexture;
 }
 
 declare class BC1Encoder extends Encoder {
@@ -203,8 +194,8 @@ declare class BC1Encoder extends Encoder {
     get supportsSrgb(): boolean;
     get supportsQuality(): boolean;
     wgslSource(): string;
+    wgslSourceFastF16(): string | null;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC5Encoder extends Encoder {
@@ -217,7 +208,6 @@ declare class BC5Encoder extends Encoder {
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat(): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC7Encoder extends Encoder {
@@ -230,7 +220,6 @@ declare class BC7Encoder extends Encoder {
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class ASTC4x4Encoder extends Encoder {
@@ -243,18 +232,6 @@ declare class ASTC4x4Encoder extends Encoder {
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
-}
-
-/** One encoded mip level. The fields both encoder backends already produce. */
-interface EncodedLevel {
-    /** Logical (pre-padding) dimensions, surfaced on the texture's userData. */
-    width: number;
-    height: number;
-    /** Block-aligned dimensions the compressed `data` actually covers. */
-    paddedWidth: number;
-    paddedHeight: number;
-    data: Uint8Array;
 }
 
 /** Raw RGBA8 pixel data (e.g. a CPU-generated mip level). */
@@ -307,8 +284,6 @@ declare abstract class WebGLBlockEncoder {
     abstract get supportsSrgb(): boolean;
     /** GLSL ES 3.00 fragment-shader source. */
     abstract fragSource(): string;
-    /** Three.js `CompressedPixelFormat` constant; sRGB is carried by colorSpace. */
-    abstract threeTextureFormat(): CompressedPixelFormat;
     protected _buildProgram(): void;
     /** Release the GL program + VAO. The shared context itself is left intact. */
     destroy(): void;
@@ -328,10 +303,6 @@ declare abstract class WebGLBlockEncoder {
     encodeToBytes(source: WebGLEncoderImageSource, { flipY }?: {
         flipY?: boolean;
     }): WebGLEncodeBytesResult;
-    /** Wrap pre-encoded levels into a CompressedTexture. Shared with the WebGPU path. */
-    buildMippedTexture(levels: readonly EncodedLevel[], { colorSpace }?: {
-        colorSpace?: 'srgb' | 'linear';
-    }): CompressedTexture;
 }
 
 declare class BC1WebGLEncoder extends WebGLBlockEncoder {
@@ -339,7 +310,6 @@ declare class BC1WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC5WebGLEncoder extends WebGLBlockEncoder {
@@ -347,7 +317,6 @@ declare class BC5WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC7WebGLEncoder extends WebGLBlockEncoder {
@@ -355,7 +324,6 @@ declare class BC7WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
@@ -363,7 +331,6 @@ declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 /**
@@ -438,96 +405,6 @@ interface WebGLFormatSelection {
 }
 declare function selectWebGLFormat(caps: WebGLCapabilities, hint: TextureHint, options?: SelectFormatOptions): WebGLFormatSelection;
 
-/**
- * Everything `compressTexture()` can take as an image source. A superset
- * of `EncoderImageSource` (see Encoder.ts) that also accepts URL strings
- * and Blob / File objects — the common cases in a web app.
- */
-type CompressTextureSource = string | Blob | File | ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData;
-interface CompressOptions {
-    /** How the texture will be used. Drives format selection. Default 'color'. */
-    hint?: TextureHint;
-    /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
-    colorSpace?: 'srgb' | 'linear';
-    /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
-    flipY?: boolean;
-    /** Generate a full mip chain down to 1×1 on the CPU, encode every level. */
-    mipmaps?: boolean;
-    /**
-     * Encode quality / speed trade-off. 'fast' (default) is ~2–4× faster for a
-     * ≤0.36 dB PSNR cost; 'high' runs the exhaustive search (output identical to
-     * the CPU reference encoders; for BC1, a principal-axis seed + iterative
-     * refit). No effect on the WebGL fallback (which always uses the fast
-     * encoders).
-     */
-    quality?: EncodeQuality;
-    /** Reuse an existing device (e.g. Three.js's renderer device) instead
-     *  of creating a new one. WebGPU path only. When provided, the encoder
-     *  never destroys it. */
-    device?: GPUDevice;
-    adapter?: GPUAdapter;
-}
-interface CompressResult {
-    /** CompressedTexture on a compressed path; Texture on RGBA8 fallback. */
-    texture: Texture | CompressedTexture;
-    /** The compressed format selected, or null when we fell back to RGBA8. */
-    format: TextureFormat | null;
-    /** True iff we returned an uncompressed Texture because no encoder fit. */
-    fallbackUncompressed: boolean;
-    /**
-     * Which backend produced the result. 'webgpu' = compute path, 'webgl' =
-     * fragment-shader fallback, 'none' = uncompressed RGBA8.
-     */
-    backend: 'webgpu' | 'webgl' | 'none';
-    /**
-     * True iff the chosen format is ASTC and the hint was 'normal'. The
-     * caller must apply the (R, W) → (x, y) swizzle in the material — ASTC
-     * has no 2-channel mode, so normal maps ride the RGBA path.
-     */
-    astcNormalRemap: boolean;
-    width: number;
-    height: number;
-    mipLevels: number;
-    /** Wall-clock time of GPU encoding, summed across mip levels. */
-    encodeMs: number;
-    /** Release the encoder's internal GPU resources. No-op if `device` was
-     *  passed in by the caller. */
-    destroy(): void;
-}
-declare function compressTexture(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
-
-declare class GputexLoader extends Loader<Texture> {
-    /** Format-selection hint. Default 'color'. */
-    hint: TextureHint;
-    /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
-    colorSpace: 'srgb' | 'linear';
-    /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
-    flipY: boolean;
-    /** Generate + encode a full mip chain. Default false. */
-    mipmaps: boolean;
-    /** Encode quality / speed trade-off. Default 'fast' (~2–4× faster, ≤0.36 dB). */
-    quality: EncodeQuality;
-    /**
-     * Optional pre-existing WebGPU device. Reusing the renderer's device
-     * avoids spinning up a second WebGPU context for encoding.
-     */
-    device?: GPUDevice;
-    adapter?: GPUAdapter;
-    /**
-     * Most recent full encode result. Useful when the caller wants format
-     * / mipLevels / astcNormalRemap metadata without threading a separate
-     * callback through `load()`. Cleared when a new load starts.
-     */
-    lastResult: CompressResult | null;
-    /**
-     * THREE.Loader contract: returns void, drives callbacks. `loadAsync`
-     * (inherited from the base class) wraps this with Promise semantics.
-     * Errors routed through `manager.itemError` so the LoadingManager's
-     * aggregate state stays accurate.
-     */
-    load(url: string, onLoad?: (texture: Texture) => void, _onProgress?: (event: ProgressEvent) => void, onError?: (err: unknown) => void): void;
-}
-
 /** One level of a mip chain. 4 bytes per pixel (RGBA8). */
 interface MipLevel {
     data: Uint8ClampedArray;
@@ -553,4 +430,4 @@ declare function generateMipChain(level0: MipLevel): MipLevel[];
  */
 declare function padToBlockMultiple(level: MipLevel): MipLevel;
 
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, GputexLoader, type MipLevel, type RawPixelSource, type SelectFormatOptions, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, compressTexture, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat };
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, type Capabilities, type EncodeBytesResult, type EncodeCallOptions, type EncodeQuality, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatSelection, type FormatVariant, type MipLevel, type RawPixelSource, type SelectFormatOptions, TextureFormat, type TextureHint, WebGLBlockEncoder, type WebGLCapabilities, type WebGLEncodeBytesResult, type WebGLEncoderConstructor, type WebGLEncoderImageSource, type WebGLEncoderOptions, type WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat };