gputex 0.7.0 → 0.9.0

package/README.md

@@ -49,15 +49,16 @@ when unsupported, and both apply to `hint: 'color'` only.
 
 ## 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 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.
+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. Each fragment shader is a line-for-line port of the WebGPU f32 shader and produces the same bytes as it (verified on Apple M3); the default WebGPU path runs the f16 variants where `shader-f16` is available, which can differ from f32 on rounding ties only, so the resulting `CompressedTexture` looks the same under either renderer. The WebGL encoders also reuse their textures across encodes and skip re-uploading an `ImageBitmap` they already hold.
 
 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. ETC2 is WebGPU-only (no WebGL fragment encoder), so `quality: 'low'` on the WebGL tier can only deliver BC1.
+- 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), `WEBGL_compressed_texture_s3tc` (BC1), or `WEBGL_compressed_texture_etc` (ETC2). Selection mirrors the WebGPU side, with BC1 added as a broadly-available last resort for **opaque** colour when neither BPTC nor ASTC is present; ETC2 RGB8 (`WEBGL_compressed_texture_etc`) is the `quality: 'low'` pick on devices without s3tc and the final opaque-colour fallback.
 - 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.
+- All encoding happens on one shared, off-screen WebGL2 context; nothing is drawn to a visible canvas. `compressTexture()` keeps one compiled encoder per format on it across calls (released by `releaseSharedGpuResources()`).
+- `forceWebGL: true` (or `loader.forceWebGL = true`) takes this path on WebGPU-capable browsers too — handy for testing it. In the example app, add `?forcewebgl=1` to any page to encode and render through WebGL2.
 
 ## Usage
 
@@ -103,17 +104,19 @@ algebra of that scalar shift — table and index selection depend only on each
 texel's luma-sum difference from the base, exactly (modulo decode clamping) —
 so the whole 8-table × 4-modifier search collapses to a handful of scalar
 threshold tests against a two-candidate table shortlist, with subblock error
-constants and the flip preselect computed O(1) from quadrant sums. A gated
-base-colour refit and a closed-form least-squares fit of ETC2's planar mode
-(which rescues the smooth gradients ETC1-style blocks band on) complete the
-block, all driven by the same estimates. The rewrite took the GPU pass
-from 6.0 ms to ~0.2 ms at 2048² (30×, within ~0.2 dB of the exhaustive
-search on photographic content — only the base refit was traded for
-speed). Its f16 module is EXACT-VALUE: lumas, D values and thresholds
-are integers f16 represents exactly, while the sums-of-squares estimates
-stay f32 (they overflow f16), so the two modules produce byte-identical
-output — f16 buys register pressure on mobile GPUs, not different
-results.
+constants and the flip preselect computed O(1) from quadrant sums (exactly
+gray blocks, which give the preselect nothing to go on, score both flips on
+a one-channel path). A closed-form least-squares fit of ETC2's planar mode
+(which rescues the smooth gradients ETC1-style blocks band on) completes
+the block, driven by the same estimates. There is no base-colour refit
+(~0.2 dB on photographic content for ≥13% GPU). The kernel reads the source
+through `textureGather` and keeps every per-texel quantity in registers
+with constant indexing (numbers below). Its f16 module is EXACT-VALUE: lumas,
+D values and thresholds are integers (or halves) f16 represents exactly,
+while the sums and estimates stay f32 (they overflow f16), so the two
+modules produce byte-identical output wherever the sampler's unorm
+conversion is exact (verified on Apple) — f16 buys register space, not
+different results.
 
 On the repo's test textures this lands within a few tenths of a dB of the
 per-block CPU reference encoders (`gputex/testing`) and above them on
@@ -310,6 +313,7 @@ const tex = buildCompressedTexture([bytes], TextureFormat.BC7_SRGB)
 | `cache`           | `boolean`                     | `false`   | Session-scoped in-memory cache; repeat calls skip decode + encode (see below)                                            |
 | `cacheKey`        | `string`                      | derived   | Explicit cache identity (skips content hashing; makes pixel sources cacheable)                                           |
 | `device`          | `GPUDevice`                   | —         | Reuse an existing WebGPU device instead of creating one                                                                  |
+| `forceWebGL`      | `boolean`                     | `false`   | Skip WebGPU and encode on the WebGL2 fallback (testing); pair with `new WebGPURenderer({ forceWebGL: true })`            |
 
 #### In-memory transcode cache
 
@@ -335,6 +339,34 @@ the encode and reuse the encoder's cached GPU resources. The result's
 whole chain is encoded in a single GPU submission (one compute pass, one
 readback) rather than a round trip per level.
 
+#### Prewarming shaders
+
+A cold shader cache (first visit, browser or driver update) costs ~120–160 ms
+of pipeline compilation per WebGPU encoder, ~60–90 ms per WebGL2 program,
+paid by the first texture that needs it. `prewarmCompressTexture()` compiles
+ahead of time exactly what `compressTexture()` will use on this client for
+the option sets you pass — the same capability-based selection (BC on
+desktop, ASTC/ETC2 on mobile, the WebGL2 tier when WebGPU is missing or
+`forceWebGL` is set), so nothing unused compiles:
+
+```ts
+import { prewarmCompressTexture } from 'gputex'
+
+// At app boot — pass your texture option presets as-is.
+prewarmCompressTexture([{ hint: 'color', quality: 'low', mipmaps: true }, { hint: 'normal' }])
+```
+
+It creates the shared device (or WebGL2 context) and the per-format encoders
+later `compressTexture()` calls reuse, plus the mip-generation pipeline when
+a target sets `mipmaps`, and resolves with the chosen backend/format per
+target once everything compiled. Compilation runs off the main thread
+(`createComputePipelineAsync`; `KHR_parallel_shader_compile` on WebGL2), and
+it never rejects — compile errors surface on the first encode. Calls that
+pass their own `device`/`adapter` build their own encoders and aren't
+warmed. Independently of prewarming, every `compressTexture()` call starts
+its encoder's compile before decoding the image, so compile and decode
+overlap.
+
 ## Benchmarks
 
 Measured on an Apple Silicon GPU (`metal-3`, M3) in Chrome with the `/eval`
@@ -353,7 +385,8 @@ shader alone.
 | BC7      | f32           | 0.52 ms     |
 | ASTC 4×4 | f16 (default) | **0.17 ms** |
 | ASTC 4×4 | f32           | 0.28 ms     |
-| ETC2     | f16 + f32     | 0.20 ms     |
+| ETC2     | f16 (default) | **0.14 ms** |
+| ETC2     | f32           | 0.15 ms     |
 
 End-to-end `encodeToBytes()` wall time adds the upload and the readback.
 Each encoder caches its GPU resources (source texture, output/staging
@@ -366,13 +399,15 @@ readback this cuts wall time by 23–33% at 4096² and 5–25% at 2048²
 (bytes identical); a fresh 4096² encode is then dominated by the ~8 ms
 `copyExternalImageToTexture` upload.
 
-On a 100 GB/s part just reading the 2048² RGBA8 source costs ~0.15 ms, so
-BC5/BC7/ASTC/ETC2 sit within ~1.3× of simply touching the bytes; BC1's
-refit rounds keep it ALU-bound. Two faster ETC2 variants live in git
-history and were deliberately not shipped: a two-pass 2 B/px prepared source (encode pass
-0.115 ms, but the prep pass is also bandwidth-bound and cannot overlap, so
-the per-texture total regressed) and an O(1) hedged table pick (−3% for
-−0.5 dB — a poor trade against the scored search).
+On a 100 GB/s part just reading the 2048² RGBA8 source costs ~0.14 ms, so
+BC5/BC7/ASTC sit within ~1.3× of simply touching the bytes and ETC2 at it;
+BC1's refit rounds keep it ALU-bound. On real textures (which Apple's
+lossless framebuffer compression makes cheaper to read) and at 1024², where
+the source stays cached, the ETC2 kernel is ALU-exposed again: 0.035–0.04 ms
+at 1024², 0.13–0.15 ms at 2048² and 0.49–0.57 ms at 4096² across the corpus.
+A two-pass 2 B/px prepared-source ETC2 variant lives in git history and was
+not shipped: its prep pass is also bandwidth-bound and cannot overlap, so
+the per-texture total regressed.
 
 Single-dispatch timestamps are coarse and Apple GPU clock states swing
 timings by up to ~2× across page loads, so compare variants only within a
@@ -436,7 +471,7 @@ consumer can run the same validation.
 - 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), `texture-compression-astc` (mobile), or `texture-compression-etc2` (mobile)
-  - WebGL2: `EXT_texture_compression_bptc` / `_rgtc`, `WEBGL_compressed_texture_astc`, or `WEBGL_compressed_texture_s3tc`
+  - WebGL2: `EXT_texture_compression_bptc` / `_rgtc`, `WEBGL_compressed_texture_astc`, `WEBGL_compressed_texture_s3tc`, or `WEBGL_compressed_texture_etc`
 - Falls back to uncompressed RGBA8 when no compressed format is available on either backend
 
 ## Device-specific workarounds

package/dist/index.d.ts

@@ -188,6 +188,12 @@ declare abstract class Encoder {
     private _chainBusy;
     constructor({ device, adapter, ownsDevice, disableF16 }: EncoderOptions);
     protected _buildPipeline(): void;
+    /**
+     * Resolves once the encoder's compute pipeline(s) have compiled. Encodes
+     * await this themselves; call it to compile ahead of first use (see
+     * `prewarmCompressTexture()`). Rejects with the compile error, if any.
+     */
+    ready(): Promise<void>;
     destroy(): void;
     /** Short lowercase identifier used in GPU object labels and errors. */
     abstract get label(): string;
@@ -424,6 +430,17 @@ declare abstract class WebGLBlockEncoder {
     protected _uSrc: WebGLUniformLocation | null;
     protected _uSrcSize: WebGLUniformLocation | null;
     protected _uFlipY: WebGLUniformLocation | null;
+    private _parallel;
+    private _shaders;
+    private _linked;
+    private _srcTex;
+    private _srcW;
+    private _srcH;
+    private _srcBitmap;
+    private _outTex;
+    private _fbo;
+    private _outBX;
+    private _outBY;
     constructor({ gl }: WebGLEncoderOptions);
     /** Short lowercase identifier for labels / errors. */
     abstract get label(): string;
@@ -434,14 +451,27 @@ declare abstract class WebGLBlockEncoder {
     /** GLSL ES 3.00 fragment-shader source. */
     abstract fragSource(): string;
     protected _buildProgram(): void;
-    /** Release the GL program + VAO. The shared context itself is left intact. */
+    /** Check the link (blocking until it completes), then look up uniforms. */
+    private _ensureLinked;
+    /**
+     * Resolves once the fragment program has compiled and linked, without
+     * blocking the main thread where the driver exposes
+     * KHR_parallel_shader_compile (elsewhere the final status check waits for
+     * the driver). Encodes check this themselves; call it to compile ahead of
+     * first use (see `prewarmCompressTexture()`). Rejects on a compile/link
+     * error.
+     */
+    ready(): Promise<void>;
+    /** Release the GL program, VAO and cached textures. 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.
+     * Upload the source image to the cached RGBA8 texture (recreated when the
+     * image size changes), 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. Re-encoding the ImageBitmap already held by the
+     * texture skips the upload.
      */
     protected _uploadSource(source: WebGLEncoderImageSource, width: number, height: number): WebGLTexture;
     /**
@@ -482,6 +512,13 @@ declare class ASTC4x4WebGLEncoder extends WebGLBlockEncoder {
     fragSource(): string;
 }
 
+declare class ETC2WebGLEncoder extends WebGLBlockEncoder {
+    get label(): string;
+    get bytesPerBlock(): number;
+    get supportsSrgb(): boolean;
+    fragSource(): string;
+}
+
 /**
  * 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
@@ -516,6 +553,8 @@ interface WebGLCapabilities {
     s3tcSrgb: boolean;
     /** WEBGL_compressed_texture_astc → ASTC 4×4 (and other footprints). */
     astc: boolean;
+    /** WEBGL_compressed_texture_etc → ETC2 RGB8 (and the other ETC2/EAC formats). */
+    etc: boolean;
 }
 declare function detectWebGLCapabilities(gl: ExtensionProvider): WebGLCapabilities;
 
@@ -641,8 +680,8 @@ interface CompressOptions {
      * device has one — BC1 on desktop-class GPUs, ETC2 RGB8 on mobile-class
      * ones — halving GPU memory at visibly lower quality on smooth content.
      * Ignored for `hint: 'colorWithAlpha'` and `hint: 'normal'` (the 4-bpp
-     * formats can't carry them). On the WebGL fallback tier only BC1 is
-     * available at 'low'.
+     * formats can't carry them). The WebGL fallback tier makes the same
+     * choice (BC1 where s3tc is exposed, else ETC2 RGB8).
      */
     quality?: FormatQuality;
     /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
@@ -664,6 +703,14 @@ interface CompressOptions {
      *  never destroys it. */
     device?: GPUDevice;
     adapter?: GPUAdapter;
+    /**
+     * Skip the WebGPU tier and encode on the WebGL2 fallback even when WebGPU
+     * is available — for testing the fallback path on WebGPU-capable
+     * browsers (pair it with three's `new WebGPURenderer({ forceWebGL: true })`
+     * to render through WebGL2 as well). `device`/`adapter` are ignored.
+     * Default false.
+     */
+    forceWebGL?: boolean;
     /**
      * Keep the compressed bytes in a session-scoped in-memory LRU and reuse
      * them on repeat calls, skipping BOTH the image decode and the encode —
@@ -733,13 +780,42 @@ interface CompressResult {
     cacheHit: boolean;
 }
 /**
- * Destroy the WebGPU device and encoders that `compressTexture()` shares
- * across calls (created lazily when neither the `device` nor the `adapter`
- * option is passed). Safe to call at any time — in-flight encodes on the
- * shared device will fail, and the next `compressTexture()` call recreates
- * everything. No-op when nothing is cached.
+ * Destroy the WebGPU device and the WebGPU/WebGL2 encoders that
+ * `compressTexture()` shares across calls (the WebGPU ones are created
+ * lazily when neither the `device` nor the `adapter` option is passed).
+ * Safe to call at any time — in-flight encodes on the shared device will
+ * fail, and the next `compressTexture()` call recreates everything. No-op
+ * when nothing is cached.
  */
 declare function releaseSharedGpuResources(): void;
+/** The `compressTexture()` options that decide which encoder runs. */
+type PrewarmTarget = Pick<CompressOptions, 'hint' | 'quality' | 'preferredFormat' | 'colorSpace' | 'mipmaps' | 'forceWebGL'>;
+interface PrewarmResult {
+    /** Per target, in order: the backend and format `compressTexture()` will use for it on this client. */
+    targets: {
+        backend: 'webgpu' | 'webgl' | 'none';
+        format: TextureFormat | null;
+    }[];
+    /** Wall time until every selected pipeline finished compiling. */
+    ms: number;
+}
+/**
+ * Compile, ahead of first use, exactly the shaders `compressTexture()` will
+ * need on this client for the given option sets — the same capability-based
+ * selection (BC on desktop, ASTC/ETC2 on mobile, the WebGL2 tier when
+ * WebGPU is missing or `forceWebGL` is set), so nothing unused compiles.
+ * Creates the shared WebGPU device (or WebGL2 context) and the per-format
+ * encoders that later `compressTexture()` calls reuse, plus the GPU
+ * mip-generation pipeline when a target sets `mipmaps`. Pass your texture
+ * option presets as-is; unrelated keys are ignored.
+ *
+ * Call it as early as possible (app boot); textures requested before it
+ * settles simply wait for the same in-flight compiles. Never rejects:
+ * compile errors surface on the first encode that needs the pipeline. Only
+ * the default shared path is warmed — calls passing their own `device` or
+ * `adapter` build their own encoders.
+ */
+declare function prewarmCompressTexture(targets?: PrewarmTarget | readonly PrewarmTarget[]): Promise<PrewarmResult>;
 declare function compressTextureToBytes(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
 
 /**
@@ -750,4 +826,4 @@ declare function setTranscodeCacheLimit(bytes: number): void;
 /** Drop every cached transcode. Textures already built from entries are unaffected. */
 declare function clearTranscodeCache(): void;
 
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, type BC7EncoderOptions, BC7WebGLEncoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, ETC2Encoder, type EncodeBytesResult, type EncodeCallOptions, type EncodeMipChainResult, type EncodedLevelBytes, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatQuality, 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, clearTranscodeCache, compressTextureToBytes, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, releaseSharedGpuResources, selectFormat, selectWebGLFormat, setTranscodeCacheLimit };
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, type BC7EncoderOptions, BC7WebGLEncoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, ETC2Encoder, ETC2WebGLEncoder, type EncodeBytesResult, type EncodeCallOptions, type EncodeMipChainResult, type EncodedLevelBytes, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type ExtensionProvider, type FeatureProvider, type FormatQuality, type FormatSelection, type FormatVariant, type MipLevel, type PreferredFormat, type PrewarmResult, type PrewarmTarget, 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, clearTranscodeCache, compressTextureToBytes, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, prewarmCompressTexture, rasterizeSvg, releaseSharedGpuResources, selectFormat, selectWebGLFormat, setTranscodeCacheLimit };