gputex 0.0.5 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # GPUtex
 
-Runtime GPU texture compression via WebGPU compute shaders. 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.
+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.
 
@@ -27,6 +27,18 @@ bun add gputex
 
 Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed RGBA8 fallback otherwise.
 
+## 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.
+
+The fallback chain is **WebGPU → WebGL2 → uncompressed RGBA8**. The `backend` field on the result (`'webgpu' | 'webgl' | 'none'`) tells you which path ran.
+
+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 always uses the **fast** encoders — the `quality: 'high'` option and 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.
+
 ## Usage
 
 ### `compressTexture` — direct API
@@ -38,11 +50,28 @@ const { texture, format } = await compressTexture('/cobblestone.avif', {
   hint: 'color', // 'color' | 'colorWithAlpha' | 'normal'
   colorSpace: 'srgb',
   mipmaps: true,
+  quality: 'fast', // 'fast' (default) | 'high'
 })
 
 material.map = texture
 ```
 
+#### Quality
+
+`quality` trades encode speed against compression accuracy:
+
+- **`'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.
+- **`'high'`** — exhaustive endpoint search (farthest-pair seed, full nearest
+  search, p-bit search); output is byte-for-byte identical to the CPU reference
+  encoders.
+
 ### `GputexLoader` — Three.js Loader
 
 ```ts
@@ -154,9 +183,11 @@ encoder.destroy()
 
 ## Requirements
 
-- A browser with WebGPU support
-- `texture-compression-bc` (desktop) or `texture-compression-astc` (mobile) for compressed output
-- Falls back to uncompressed RGBA8 when neither is available
+- 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)
+  - 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
 
 ## Device-specific workarounds
 

package/dist/index.d.ts

@@ -45,9 +45,18 @@ interface EncoderOptions {
     adapter?: GPUAdapter;
     ownsDevice?: 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.
+ * No effect on BC1 (already single-pass; both levels are identical).
+ */
+type EncodeQuality = 'fast' | 'high';
 interface EncodeCallOptions {
     /** Tags the output color space. Forced 'linear' for encoders with supportsSrgb=false. */
     colorSpace?: 'srgb' | 'linear';
+    /** Encode quality / speed trade-off. Default 'fast'. */
+    quality?: EncodeQuality;
 }
 interface EncodeResult {
     width: number;
@@ -110,9 +119,18 @@ declare abstract class Encoder {
     readonly adapter?: GPUAdapter;
     readonly ownsDevice: 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);
     protected _buildPipeline(): void;
+    /**
+     * Pipeline for a given quality level. Encoders that don't declare a
+     * `QUALITY_HIGH` override (`supportsQuality === false`, e.g. BC1) ignore the
+     * argument and reuse the single pipeline. Specialised pipelines are cached.
+     */
+    protected _getPipeline(quality: EncodeQuality): GPUComputePipeline;
     destroy(): void;
     /** Short lowercase identifier used in GPU object labels and errors. */
     abstract get label(): string;
@@ -122,6 +140,20 @@ declare abstract class Encoder {
     get workgroupSize(): readonly [number, number, number];
     /** Whether this format has an sRGB variant. Default true. */
     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.
+     */
+    get supportsQuality(): boolean;
+    /**
+     * 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).
+     */
+    wgslSourceFastF16(): string | null;
+    /** Whether the f16 fast path is both available and supported on this device. */
+    protected get _useF16(): boolean;
     /** WGSL compute-shader source. */
     abstract wgslSource(): string;
     /** e.g. 'bc1-rgba-unorm-srgb'. */
@@ -134,7 +166,7 @@ declare abstract class Encoder {
      * whether the result can actually be sampled.
      */
     get supportsSampling(): boolean;
-    encode(source: EncoderImageSource, { colorSpace }?: EncodeCallOptions): Promise<EncodeResult>;
+    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
@@ -145,8 +177,9 @@ declare abstract class Encoder {
      * encoder boundary. Still safe to call from outside — it just does
      * less work than `encode()` and the caller assembles the texture.
      */
-    encodeToBytes(source: EncoderImageSource, { flipY }?: {
+    encodeToBytes(source: EncoderImageSource, { flipY, quality }?: {
         flipY?: boolean;
+        quality?: EncodeQuality;
     }): Promise<EncodeBytesResult>;
     /**
      * Assemble a `CompressedTexture` from pre-encoded mip levels. Called
@@ -178,7 +211,9 @@ declare class BC5Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    get supportsQuality(): boolean;
     wgslSource(): string;
+    wgslSourceFastF16(): string;
     gpuTextureFormat(): GPUTextureFormat;
     threeTextureFormat(): CompressedPixelFormat;
 }
@@ -189,7 +224,9 @@ declare class BC7Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    get supportsQuality(): boolean;
     wgslSource(): string;
+    wgslSourceFastF16(): string;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
     threeTextureFormat(): CompressedPixelFormat;
 }
@@ -200,11 +237,170 @@ declare class ASTC4x4Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
+    get supportsQuality(): boolean;
     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). */
+interface RawPixelSource {
+    data: ArrayBufferView;
+    width: number;
+    height: number;
+}
+/** Anything the WebGL encoders can upload as the source image. */
+type WebGLEncoderImageSource = ImageBitmap | ImageData | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | RawPixelSource;
+interface WebGLEncodeBytesResult {
+    width: number;
+    height: number;
+    paddedWidth: number;
+    paddedHeight: number;
+    data: Uint8Array;
+    encodeMs: number;
+}
+interface WebGLEncoderOptions {
+    gl: WebGL2RenderingContext;
+}
+/**
+ * Constructor shape for the concrete subclasses; lets the static `create()`
+ * narrow its return type to the subclass (as the WebGPU `EncoderConstructor`
+ * does).
+ */
+type WebGLEncoderConstructor<T extends WebGLBlockEncoder = WebGLBlockEncoder> = {
+    new (opts: WebGLEncoderOptions): T;
+    create(gl?: WebGL2RenderingContext | null): T;
+};
+declare abstract class WebGLBlockEncoder {
+    /**
+     * Create an encoder on the shared process-wide context (or a caller-supplied
+     * one). Throws when WebGL2 is unavailable. The `this:` annotation lets
+     * `BC7WebGLEncoder.create()` return `BC7WebGLEncoder`.
+     */
+    static create<T extends WebGLBlockEncoder>(this: WebGLEncoderConstructor<T>, gl?: WebGL2RenderingContext | null): T;
+    readonly gl: WebGL2RenderingContext;
+    protected _program: WebGLProgram;
+    protected _vao: WebGLVertexArrayObject;
+    protected _uSrc: WebGLUniformLocation | null;
+    protected _uSrcSize: WebGLUniformLocation | null;
+    protected _uFlipY: WebGLUniformLocation | null;
+    constructor({ gl }: WebGLEncoderOptions);
+    /** Short lowercase identifier for labels / errors. */
+    abstract get label(): string;
+    /** 8 for BC1, 16 for BC5/BC7/ASTC 4×4. */
+    abstract get bytesPerBlock(): number;
+    /** Whether this format has an sRGB variant (false for BC5). */
+    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;
+    /**
+     * Upload the source image to a freshly created RGBA8 texture bound on unit 0.
+     * Raw pixel sources (ImageData / mip levels) go through the typed-array
+     * overload; DOM sources (ImageBitmap / canvas / image) through the element
+     * overload. No flip / premultiply / colour conversion — flipY is applied in
+     * the shader so each mip level flips by its own height.
+     */
+    protected _uploadSource(source: WebGLEncoderImageSource, width: number, height: number): WebGLTexture;
+    /**
+     * Encode one image source to raw compressed bytes. `flipY` samples the source
+     * bottom-up (matching Three.js's convention) and is applied in the shader;
+     * the high-level mipped path bakes the flip into level 0 and passes false.
+     */
+    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 {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class BC5WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class BC7WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+    threeTextureFormat(): CompressedPixelFormat;
+}
+
+/**
+ * Create a fresh WebGL2 context backed by an off-screen 1×1 canvas. Returns
+ * null when neither `OffscreenCanvas` nor `document` is available (e.g. a
+ * non-DOM worker without OffscreenCanvas) or when the platform has no WebGL2.
+ */
+declare function createWebGLContext(): WebGL2RenderingContext | null;
+/**
+ * Lazily-created context shared across the high-level fallback path. Re-created
+ * if the previous one was lost (tab backgrounding, GPU reset). Returns null
+ * when WebGL2 is unavailable on this platform.
+ */
+declare function getSharedWebGLContext(): WebGL2RenderingContext | null;
+/** True when a WebGL2 context can be created on this platform. */
+declare function isWebGLAvailable(): boolean;
+
+/**
+ * Minimal structural type for the extension source: only `getExtension` is
+ * touched, so tests can pass a `{ getExtension }` stub instead of a real
+ * `WebGL2RenderingContext`.
+ */
+interface ExtensionProvider {
+    getExtension(name: string): unknown;
+}
+interface WebGLCapabilities {
+    /** EXT_texture_compression_bptc → BC7 (BPTC). */
+    bptc: boolean;
+    /** EXT_texture_compression_rgtc → BC5 (RGTC2). */
+    rgtc: boolean;
+    /** WEBGL_compressed_texture_s3tc → BC1 (DXT1). */
+    s3tc: boolean;
+    /** WEBGL_compressed_texture_s3tc_srgb → sRGB DXT1 (separate extension). */
+    s3tcSrgb: boolean;
+    /** WEBGL_compressed_texture_astc → ASTC 4×4 (and other footprints). */
+    astc: boolean;
+}
+declare function detectWebGLCapabilities(gl: ExtensionProvider): WebGLCapabilities;
+
 /**
  * How the texture will be used in the renderer. Drives format choice.
  *   • 'color'          — RGB albedo-like data (alpha optional / ignored).
@@ -230,6 +426,16 @@ interface FormatSelection {
 }
 declare function selectFormat(adapter: FeatureProvider, hint: TextureHint, options?: SelectFormatOptions): FormatSelection;
 
+interface WebGLFormatSelection {
+    /** null = no compressed path available on this WebGL context. */
+    format: TextureFormat | null;
+    /** null when `format` is null. */
+    encoderClass: WebGLEncoderConstructor | null;
+    /** True when the chosen path is ASTC *and* the hint is 'normal' (caller must pre-swizzle). */
+    astcNormalRemap: boolean;
+}
+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
@@ -245,18 +451,31 @@ interface CompressOptions {
     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. When provided, the encoder never destroys it. */
+     *  of creating a new one. WebGPU path only. When provided, the encoder
+     *  never destroys it. */
     device?: GPUDevice;
     adapter?: GPUAdapter;
 }
 interface CompressResult {
-    /** CompressedTexture on the compressed path; Texture on RGBA8 fallback. */
+    /** 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
@@ -283,6 +502,8 @@ declare class GputexLoader extends Loader<Texture> {
     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.
@@ -329,4 +550,4 @@ declare function generateMipChain(level0: MipLevel): MipLevel[];
  */
 declare function padToBlockMultiple(level: MipLevel): MipLevel;
 
-export { ASTC4x4Encoder, BC1Encoder, BC5Encoder, BC7Encoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type FeatureProvider, type FormatSelection, type FormatVariant, GputexLoader, type MipLevel, type SelectFormatOptions, TextureFormat, type TextureHint, WebGPUFeature, compressTexture, detectCapabilities, generateMipChain, padToBlockMultiple, selectFormat };
+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 };