gputex 0.5.0 → 0.7.0

package/README.md

@@ -83,13 +83,19 @@ 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.
+straight-line constant shifts. BC1's coarse 4-level palette adds up to two
+least-squares endpoint refit rounds, solved from per-pass projection
+moments and accepted per block only when they lower the error; its
+near-flat blocks skip the line fit and take the endpoint pair whose ⅔/⅓
+interpolant lands nearest the block colour (direct 565 rounding is up to 4
+levels off — worth up to +3.9 dB on maps with flat regions). BC5 refits
+once; BC7's 16-level mode-6 palette makes the refit redundant on a
+principal-axis seed (≤0.05 dB). ASTC spends every one of its 128 bits: a
+wide-span opaque block gets 16 weight levels with 192-level (trit-coded)
+endpoints, a small-span one exact 8-bit endpoints with 8 levels,
+exactly-grayscale blocks a luminance-only mode with 32 levels. On GPUs that
+report the `shader-f16` feature everything runs in f16 — the f32 shaders
+are the automatic fallback.
 
 ETC2 is the exception to the endpoint-line story: its blocks are per-subblock
 base colours shifted by scalar modifier tables. The encoder exploits the
@@ -109,12 +115,12 @@ stay f32 (they overflow f16), so the two modules produce byte-identical
 output — f16 buys register pressure on mobile GPUs, not different
 results.
 
-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.
+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
+several (BC5 matches exactly; BC1 on flat content, BC7 and ASTC on some
+maps measure above), 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
 
@@ -331,39 +337,46 @@ readback) rather than a round trip per level.
 
 ## Benchmarks
 
-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 ~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².
+Measured on an Apple Silicon GPU (`metal-3`, M3) in Chrome with the `/eval`
+dev page: per-dispatch compute time from timestamp queries over batches of
+back-to-back dispatches, all variants interleaved in one session, encoding
+the procedural 2048×2048 benchmark image. **GPU pass** is the compute
+shader alone.
 
 | 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     |
+| BC1      | f16 (default) | **0.33 ms** |
+| BC1      | f32           | 0.50 ms     |
+| BC5      | f16 (default) | **0.14 ms** |
+| BC5      | f32           | 0.15 ms     |
+| BC7      | f16 (default) | **0.19 ms** |
+| 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     |
 
-The ETC2 figure is the interleaved `/ab` harness measurement (batched
-dispatches, clock-stable). On a 100 GB/s part just reading the 2048² RGBA8
-source costs ~0.15 ms, so the entire selection algorithm adds ~30% on top
-of touching the bytes. Two faster variants live in git history and were
-deliberately not shipped: a two-pass 2 B/px prepared source (encode pass
+End-to-end `encodeToBytes()` wall time adds the upload and the readback.
+Each encoder caches its GPU resources (source texture, output/staging
+buffers, bind groups) across encodes, and outputs above ~3 MB are encoded
+in row bands — one submission and staging buffer per ~2 MB of output, so
+the readback of one band (a GPU-process copy that dominated large encodes)
+overlaps the compute of the next — with the result array pre-faulted while
+the GPU works. In an interleaved A/B against the single-submission
+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).
 
-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.
+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
+single session, interleaved (as `/eval` and `/ab` do).
 
 ## Testing
 
@@ -382,6 +395,19 @@ 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__`).
 
+For shader work, `/eval` compares WGSL variants on speed AND quality in one
+session: `example/scripts/ab-sync.sh` snapshots the working-tree shaders
+(`<fmt>_work`) and git HEAD's (`<fmt>_head`) into `example/public/ab/`, and
+`/eval?shaders=bc7_f16_head,bc7_f16_work` times them interleaved and scores
+each image through the GPU's own hardware decoder (the encoded blocks are
+copied into a real compressed texture and sampled), reporting PSNR, blocks
+that got worse/better, the worst regression on blocks the first variant
+encodes near-losslessly, and byte-identical coverage — over the full
+1K/2K/4K texture corpus in seconds (`window.__GPUTEX_EVAL__`). For host-side
+changes, `example/scripts/ab-lib.sh` builds git HEAD's library and the
+working tree side by side (`/ab/gputex_head.js`, `/ab/gputex_work.js`) so
+both can be driven in one page with alternating calls.
+
 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

@@ -165,10 +165,10 @@ declare abstract class Encoder {
     private _cachedSrcSource;
     private _cachedSrcFlipY;
     private _cachedDst;
-    private _cachedStaging;
+    private _cachedStagings;
     private _cachedParams;
-    private _lastParams;
-    private _cachedBindGroup;
+    private _lastParamsKey;
+    private _cachedBindGroups;
     private _cachedPrepPlanes;
     private _cachedPrepBindGroup;
     private _resourcesBusy;
@@ -182,8 +182,9 @@ declare abstract class Encoder {
     private _chainPrepBindGroups;
     private _chainParams;
     private _chainBindGroups;
+    private _chainBandBindGroups;
     private _chainDst;
-    private _chainStaging;
+    private _chainStagings;
     private _chainBusy;
     constructor({ device, adapter, ownsDevice, disableF16 }: EncoderOptions);
     protected _buildPipeline(): void;
@@ -295,10 +296,17 @@ declare abstract class Encoder {
     /** Block-grid geometry + packed output offsets for a chain of levels.
      *  `byteSpan` is both the dst buffer size and the readback copy size (a
      *  multiple of 4: byteLen is a multiple of bytesPerBlock ≥ 8, offsets are
-     *  CHAIN_ALIGN-ed). */
+     *  CHAIN_ALIGN-ed). `bands` splits the base level into row bands. */
     private _chainGeometry;
-    /** Shared chain-encode tail: one compute pass with a dispatch per level,
-     *  one submit, one staging readback sliced into per-level byte arrays. */
+    /** One uniform buffer, one write: level i's { blocksX, blocksY, width,
+     *  height, y0 = 0 } at slot i, then base-level band b at slot
+     *  levels + b (y0 = the band's first block row). Slots are CHAIN_ALIGN
+     *  apart. */
+    private _createChainParams;
+    /** Shared chain-encode tail: one submission per base-level row band —
+     *  band b dispatches its rows of level 0, the last band also every tail
+     *  level — each read back through its own staging buffer as it lands,
+     *  then sliced into per-level byte arrays. */
     private _submitChainAndRead;
     /** Create the query set + resolve/staging buffers for one timed
      *  submission, or null when the device lacks 'timestamp-query'. */
@@ -605,4 +613,141 @@ interface RasterizeSvgOptions {
  */
 declare function rasterizeSvg(source: string | Blob, options?: RasterizeSvgOptions): Promise<ImageBitmap>;
 
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, type BC7EncoderOptions, BC7WebGLEncoder, type Capabilities, 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, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, selectFormat, selectWebGLFormat };
+/**
+ * Everything `compressTexture()` can take as an image source. A superset
+ * of `EncoderImageSource` (see Encoder.ts) that also accepts URL strings
+ * and Blob / File objects — the common cases in a web app.
+ *
+ * SVG works through all of these: a URL to an `.svg` file, a string of
+ * inline SVG markup (detected by a leading `<`), an SVG Blob/File, or an
+ * HTMLImageElement whose src is SVG. Vector sources are rasterised to RGBA
+ * before encoding — see the `svgSize` option.
+ */
+type CompressTextureSource = string | Blob | File | ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageData;
+interface CompressOptions {
+    /** How the texture will be used. Drives format selection. Default 'color'. */
+    hint?: TextureHint;
+    /**
+     * Prefer a specific format over the default choice when the device
+     * supports it; falls back to the normal selection (BC7 → ASTC → ETC2 →
+     * RGBA8) when it doesn't. Currently only 'bc1': half the memory of BC7
+     * for opaque colour textures, at lower quality. Only honoured with
+     * `hint: 'color'` — BC1 can't carry real alpha or normal maps.
+     */
+    preferredFormat?: PreferredFormat;
+    /**
+     * Memory/fidelity trade-off for opaque colour textures. Default 'high'
+     * (BC7 / ASTC 4×4, 1 byte/pixel). 'low' picks the 4-bpp formats when the
+     * 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'.
+     */
+    quality?: FormatQuality;
+    /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
+    colorSpace?: 'srgb' | 'linear';
+    /**
+     * Rasterisation size for SVG sources. A number scales the SVG so its
+     * longest side matches (aspect ratio preserved); `{ width, height }`
+     * rasterises at exactly that size. Default: the SVG's intrinsic size
+     * (absolute width/height attributes, else the viewBox dimensions).
+     * Ignored for non-SVG sources.
+     */
+    svgSize?: SvgRasterSize;
+    /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
+    flipY?: boolean;
+    /** Generate a full mip chain down to 1×1 on the CPU, encode every level. */
+    mipmaps?: boolean;
+    /** Reuse an existing device (e.g. Three.js's renderer device) instead
+     *  of creating a new one. WebGPU path only. When provided, the encoder
+     *  never destroys it. */
+    device?: GPUDevice;
+    adapter?: GPUAdapter;
+    /**
+     * 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 —
+     * the dominant costs. Re-loading a texture later in the session (e.g.
+     * two worlds sharing an atlas) becomes a few ms. Keyed by source
+     * identity + selected format + encode options; capped at 256 MiB of
+     * compressed bytes by default (`setTranscodeCacheLimit()` to tune) and
+     * never touches persistent storage. Default false.
+     *
+     * URL and Blob/File sources get an identity automatically (URL string or
+     * content hash). Pixel sources (ImageBitmap, canvas, ImageData) are only
+     * cached when `cacheKey` is provided.
+     */
+    cache?: boolean;
+    /**
+     * Explicit cache identity for the source, overriding the derived one.
+     * Use when you already know a stable name (e.g. an asset path) and want
+     * to skip content hashing, or to make pixel sources cacheable.
+     */
+    cacheKey?: string;
+}
+interface CompressResult {
+    /**
+     * Encoded compressed mip levels (`levels[0]` is the base level), ready to
+     * upload to a compressed texture. Null on the RGBA8 fallback path — use
+     * `fallbackBitmap` instead.
+     */
+    levels: EncodedLevelBytes[] | null;
+    /**
+     * Decoded RGBA8 bitmap, set only when `fallbackUncompressed` (no compressed
+     * format was available on either backend). Upload it as a plain RGBA8
+     * texture; the caller applies colour space / flipY at the texture level.
+     */
+    fallbackBitmap: ImageBitmap | null;
+    /** The compressed format selected, or null when we fell back to RGBA8. */
+    format: TextureFormat | null;
+    /** True iff we fell back to an uncompressed RGBA8 bitmap 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
+     * has no 2-channel mode, so normal maps ride the RGBA path.
+     */
+    astcNormalRemap: boolean;
+    width: number;
+    height: number;
+    mipLevels: number;
+    /** Wall-clock time of GPU encoding, summed across mip levels. */
+    encodeMs: number;
+    /**
+     * Wall-clock time to turn the source into decoded RGBA pixels: fetch /
+     * base64 decode, image decode, SVG rasterisation. Usually the dominant
+     * cost for large images — when a load feels slower than `encodeMs`
+     * suggests, this is where the time went.
+     */
+    decodeMs: number;
+    /** Wall-clock time of the whole `compressTexture()` call: decode + CPU
+     *  mip generation + encode + texture assembly. */
+    totalMs: number;
+    /** True when the result came from the in-memory transcode cache (the
+     *  `cache` option) — no decode or encode ran; decodeMs/encodeMs are 0. */
+    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.
+ */
+declare function releaseSharedGpuResources(): void;
+declare function compressTextureToBytes(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
+
+/**
+ * Cap the cache's total compressed payload in bytes (default 256 MiB).
+ * Lower it to evict immediately; 0 disables caching entirely.
+ */
+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 };