gputex 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+⚠️: This is 100% vibe-coded. The code is completely unreviewed and under-tested. Do not use for anything important.
 
 ## Install
 
@@ -14,7 +14,14 @@ pnpm add gputex
 bun add gputex
 ```
 
-`three` is a peer dependency (`>=0.180`).
+### Entry points
+
+`gputex` ships two 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`.
+
+`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
 
@@ -44,7 +51,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'
@@ -75,7 +82,7 @@ material.map = texture
 ### `GputexLoader` — Three.js Loader
 
 ```ts
-import { GputexLoader } from 'gputex'
+import { GputexLoader } from 'gputex/three'
 
 const loader = new GputexLoader()
 loader.hint = 'normal'
@@ -90,7 +97,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 +120,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 +164,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

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";
@@ -48,8 +46,9 @@ interface EncoderOptions {
 /**
  * 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.
- * No effect on BC1 (already single-pass; both levels are identical).
+ * 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.
  */
 type EncodeQuality = 'fast' | 'high';
 interface EncodeCallOptions {
@@ -58,19 +57,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;
@@ -95,6 +86,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 {
@@ -142,8 +135,8 @@ declare abstract class Encoder {
     get supportsSrgb(): boolean;
     /**
      * Whether the shader declares a `QUALITY_HIGH` pipeline-overridable constant
-     * (i.e. has distinct fast/high search paths). BC1 is already single-pass and
-     * leaves this false; BC5/BC7/ASTC override it to true.
+     * (i.e. has distinct fast/high search paths). Default false (e.g. a stub or a
+     * format with a single path); BC1/BC5/BC7/ASTC override it to true.
      */
     get supportsQuality(): boolean;
     /**
@@ -158,40 +151,23 @@ 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 }?: {
         flipY?: boolean;
         quality?: EncodeQuality;
     }): 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 {
@@ -200,9 +176,9 @@ declare class BC1Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    get supportsQuality(): boolean;
     wgslSource(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC5Encoder extends Encoder {
@@ -215,7 +191,6 @@ declare class BC5Encoder extends Encoder {
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat(): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC7Encoder extends Encoder {
@@ -228,7 +203,6 @@ declare class BC7Encoder extends Encoder {
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class ASTC4x4Encoder extends Encoder {
@@ -241,18 +215,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). */
@@ -305,8 +267,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;
@@ -326,10 +286,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 {
@@ -337,7 +293,6 @@ declare class BC1WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC5WebGLEncoder extends WebGLBlockEncoder {
@@ -345,7 +300,6 @@ declare class BC5WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class BC7WebGLEncoder extends WebGLBlockEncoder {
@@ -353,7 +307,6 @@ declare class BC7WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
@@ -361,7 +314,6 @@ declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
     fragSource(): string;
-    threeTextureFormat(): CompressedPixelFormat;
 }
 
 /**
@@ -436,95 +388,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). No effect on BC1 or 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;
@@ -550,4 +413,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 };