gputex 0.3.3 → 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 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.
+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,31 +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 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 (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); 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
 
@@ -252,35 +254,26 @@ const tex = buildCompressedTexture([bytes], TextureFormat.BC7_SRGB)
 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.
+time adds ~2–4 ms of image upload + result readback regardless of format.
+Each encoder caches its GPU resources (source texture, output/staging
+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   | 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
+variants only within a single session.
 
 ## Testing
 
@@ -294,28 +287,32 @@ bun run --filter gputex build   # build the library the example consumes
 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²) — 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,19 +116,18 @@ declare abstract class Encoder {
     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>;
+    private _cachedSrcTex;
+    private _cachedSrcW;
+    private _cachedSrcH;
+    private _cachedDst;
+    private _cachedStaging;
+    private _cachedParams;
+    private _lastParams;
+    private _cachedBindGroup;
+    private _resourcesBusy;
     constructor({ device, adapter, ownsDevice, disableF16 }: 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;
@@ -149,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;
@@ -179,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>;
 }
@@ -192,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;
@@ -204,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;
@@ -216,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;
@@ -228,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;
@@ -463,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 };