gputex 0.3.2 → 0.3.4

package/README.md

@@ -46,7 +46,7 @@ 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 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.
 
 The fallback chain is **WebGPU → WebGL2 → uncompressed RGBA8**. The `backend` field on the result (`'webgpu' | 'webgl' | 'none'`) tells you which path ran.
 
@@ -77,17 +77,24 @@ material.map = texture
 
 `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.
+- **`'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,
@@ -252,35 +259,30 @@ 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   | 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      |
+
+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,6 +296,11 @@ 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²) at fast quality — 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__`):
 

package/dist/index.d.ts

@@ -126,13 +126,24 @@ declare abstract class Encoder {
     readonly adapter?: GPUAdapter;
     readonly ownsDevice: boolean;
     readonly disableF16: boolean;
-    protected _module: GPUShaderModule;
+    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;
+    private _cachedDst;
+    private _cachedStaging;
+    private _cachedParams;
+    private _lastParams;
+    private _bindGroupCache;
+    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