gputex 0.3.4 → 0.4.0

package/README.md

@@ -46,14 +46,14 @@ alpha or a normal map.
 
 ## 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 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 two backends are not byte-identical (the WebGPU fast paths use projection assignment and f16 where available), but they implement the same algorithms at the same quality level and 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 two backends are not byte-identical (the WebGPU shaders use f16 where available), 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.
 
 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.
+- 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
@@ -67,38 +67,33 @@ 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 principal-axis endpoint seed (per-block
-  covariance power-iteration — unlike a bbox diagonal it follows
-  anti-correlated channels, worth **+2–4 dB on normal-map-like content**)
-  plus projection-based index assignment (each pixel is projected onto the
-  colinear endpoint line in O(1) instead of searching every palette entry),
-  and the block bits packed with straight-line constant shifts. The formats
-  with coarse 4-level palettes (BC1, ASTC) and BC5 add a least-squares
-  endpoint refit accepted per block only when it lowers the error; BC7's
-  16-level mode-6 palette makes the refit redundant on a principal-axis seed
-  (≤0.05 dB), so its fast path skips it and stays the cheapest per pixel. 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.35 dB on the test cards**
-  (BC7 within 0.1 dB of `'high'`; ASTC fast actually measures slightly above
-  it) and up to a few dB on adversarial high-frequency noise, where any
-  single-line seed trails `'high'`'s exhaustive search. See the benchmark
-  table below.
-- **`'high'`** — exhaustive endpoint search (farthest-pair seed, full nearest
-  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).
+#### The encoding algorithm
+
+There is a single encode mode, built to be both fast and high quality: a
+principal-axis endpoint seed (per-block covariance power-iteration — unlike
+a bbox diagonal it follows anti-correlated channels, worth **+2–4 dB on
+normal-map-like content**) plus projection-based index assignment (each
+pixel is projected onto the colinear endpoint line in O(1) instead of
+searching every palette entry), and the block bits packed with
+straight-line constant shifts. The formats with coarse 4-level palettes
+(BC1, ASTC) add up to two least-squares endpoint refit rounds accepted per
+block only when they lower the error, and BC5 one; BC7's 16-level mode-6
+palette makes the refit redundant on a principal-axis seed (≤0.05 dB), so
+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.
+
+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
+high-frequency noise, where any single-line seed loses to an exhaustive
+search — while encoding an order of magnitude faster. See the benchmark
+table below.
 
 #### SVG sources
 
@@ -265,20 +260,16 @@ buffers, bind group) across encodes, so repeated encodes — including mip
 chains — skip per-call allocation: in an interleaved A/B this cuts BC7
 end-to-end wall time by ~10% at 512², ~20% at 1024–2048² and ~35% at 4096².
 
-| Format   | Quality        | Shader | GPU pass    |
-| -------- | -------------- | ------ | ----------- |
-| BC1      | fast (default) | f16    | **0.26 ms** |
-| BC1      | fast           | f32    | 0.46 ms     |
-| BC5      | fast (default) | f16    | **0.26 ms** |
-| BC5      | fast           | f32    | 0.26 ms     |
-| BC7      | fast (default) | f16    | **0.26 ms** |
-| BC7      | fast           | f32    | 0.59 ms     |
-| ASTC 4×4 | fast (default) | f16    | **0.26 ms** |
-| ASTC 4×4 | fast           | f32    | 0.56 ms     |
-| BC1      | high           | f32    | 2.7 ms      |
-| BC5      | high           | f32    | 1.0 ms      |
-| BC7      | high           | f32    | 10.4 ms     |
-| ASTC 4×4 | high           | f32    | 1.6 ms      |
+| Format   | Shader        | GPU pass    |
+| -------- | ------------- | ----------- |
+| BC1      | f16 (default) | **0.26 ms** |
+| BC1      | f32           | 0.46 ms     |
+| BC5      | f16 (default) | **0.26 ms** |
+| BC5      | f32           | 0.26 ms     |
+| BC7      | f16 (default) | **0.26 ms** |
+| BC7      | f32           | 0.59 ms     |
+| ASTC 4×4 | f16 (default) | **0.26 ms** |
+| ASTC 4×4 | f32           | 0.56 ms     |
 
 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
@@ -297,32 +288,31 @@ cd example && bunx next dev     # then open http://localhost:3000/test
 ```
 
 A second page, `/bench`, measures median end-to-end `encodeToBytes()` wall
-time per format across image sizes (256²–4096²) at fast quality — the
-numbers that matter for runtime streaming, where host overhead dominates
-small textures (results on `window.__GPUTEX_BENCH__`).
+time per format across image sizes (256²–4096²) — the numbers that matter
+for runtime streaming, where host overhead dominates small textures
+(results on `window.__GPUTEX_BENCH__`).
 
 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.
+- **Correctness** — determinism (same input twice → identical bytes) and the
+  clamp-to-edge padding path: a non-multiple-of-4 image must land within a
+  couple of dB of the exhaustive CPU reference encode (`gputex/testing`) — a
+  padding bug craters it.
+- **Quality** — GPU output is CPU-decoded and validated on the FULL 1024²
+  test cards (every tile 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 the exhaustive CPU reference
+  encodes near-losslessly) must not exceed the reference's error by more
+  than a small per-format limit.
 - **Performance** — the benchmark table above: wall + GPU-pass time per
-  format × quality × shader variant.
+  format × shader variant.
 
 The `gputex/testing` entry point exports the CPU reference
-encoders/decoders (`encodeBC7Mode6Block`, `decodeASTC4x4Block`, …) so any
+encoders/decoders (`encodeBC7Mode6Block`, `decodeASTC4x4Block`, …) — the
+exhaustive per-block yardstick the GPU shaders are gated against — so any
 consumer can run the same validation.
 
 ## Requirements

package/dist/index.d.ts

@@ -49,19 +49,9 @@ interface EncoderOptions {
      */
     disableF16?: boolean;
 }
-/**
- * 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 {
     /** Tags the output color space. Forced 'linear' for encoders with supportsSrgb=false. */
     colorSpace?: 'srgb' | 'linear';
-    /** Encode quality / speed trade-off. Default 'fast'. */
-    quality?: EncodeQuality;
 }
 /**
  * Result of a raw bytes-only encode. This is the encoder's native output: the
@@ -126,11 +116,7 @@ declare abstract class Encoder {
     readonly adapter?: GPUAdapter;
     readonly ownsDevice: boolean;
     readonly disableF16: boolean;
-    protected _module: GPUShaderModule | null;
-    protected _moduleF16: GPUShaderModule | null;
-    protected _pipelineF16: GPUComputePipeline | null;
     protected _pipeline: GPUComputePipeline;
-    protected _pipelineCache: Map<EncodeQuality, GPUComputePipeline>;
     private _cachedSrcTex;
     private _cachedSrcW;
     private _cachedSrcH;
@@ -138,18 +124,10 @@ declare abstract class Encoder {
     private _cachedStaging;
     private _cachedParams;
     private _lastParams;
-    private _bindGroupCache;
+    private _cachedBindGroup;
     private _resourcesBusy;
     constructor({ device, adapter, ownsDevice, disableF16 }: EncoderOptions);
     protected _buildPipeline(): void;
-    /** The f32 module, parsed on first use (see `_module`). */
-    protected _ensureModule(): GPUShaderModule;
-    /**
-     * 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;
@@ -160,20 +138,14 @@ declare abstract class Encoder {
     /** 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). Default false (e.g. a stub or a
-     * format with a single path); BC1/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.
+     * Optional f16 WGSL variant. Used only when the device reports the
+     * `shader-f16` feature; the format's f32 `wgslSource()` is the automatic
+     * fallback. Returns null when there's no f16 variant.
      */
     wgslSourceFastF16(): string | null;
-    /** Whether the f16 fast path is both available and supported on this device. */
+    /** Whether the f16 shader is both available and supported on this device. */
     protected get _useF16(): boolean;
-    /** WGSL compute-shader source. */
+    /** WGSL compute-shader source (f32; the fallback when f16 is unavailable). */
     abstract wgslSource(): string;
     /** e.g. 'bc1-rgba-unorm-srgb'. */
     abstract gpuTextureFormat(opts: FormatVariant): GPUTextureFormat;
@@ -190,9 +162,8 @@ declare abstract class Encoder {
      * bytes into a `CompressedTexture`; callers targeting another engine feed
      * `data` into that engine's compressed-texture upload directly.
      */
-    encodeToBytes(source: EncoderImageSource, { flipY, quality, withGpuTime, }?: {
+    encodeToBytes(source: EncoderImageSource, { flipY, withGpuTime }?: {
         flipY?: boolean;
-        quality?: EncodeQuality;
         withGpuTime?: boolean;
     }): Promise<EncodeBytesResult>;
 }
@@ -203,7 +174,6 @@ declare class BC1Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
-    get supportsQuality(): boolean;
     wgslSource(): string;
     wgslSourceFastF16(): string | null;
     gpuTextureFormat({ colorSpace }: FormatVariant): GPUTextureFormat;
@@ -215,7 +185,6 @@ declare class BC5Encoder extends Encoder {
     get label(): string;
     get bytesPerBlock(): number;
     get supportsSrgb(): boolean;
-    get supportsQuality(): boolean;
     wgslSource(): string;
     wgslSourceFastF16(): string;
     gpuTextureFormat(): GPUTextureFormat;
@@ -227,7 +196,6 @@ 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;
@@ -239,7 +207,6 @@ 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;
@@ -474,4 +441,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, type EncodeQuality, 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, 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 };