gputex 0.3.4 → 0.5.0

package/dist/three.d.ts

@@ -1,5 +1,5 @@
-import { TextureHint, PreferredFormat, SvgRasterSize, EncodeQuality, TextureFormat, Encoder, EncoderImageSource } from './index.js';
-export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7WebGLEncoder, Capabilities, EncodeBytesResult, EncodeCallOptions, EncoderConstructor, EncoderOptions, ExtensionProvider, FeatureProvider, FormatSelection, FormatVariant, MipLevel, RasterizeSvgOptions, RawPixelSource, SelectFormatOptions, WebGLBlockEncoder, WebGLCapabilities, WebGLEncodeBytesResult, WebGLEncoderConstructor, WebGLEncoderImageSource, WebGLEncoderOptions, WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, selectFormat, selectWebGLFormat } from './index.js';
+import { TextureHint, PreferredFormat, FormatQuality, SvgRasterSize, TextureFormat, Encoder, EncoderImageSource } from './index.js';
+export { ASTC4x4Encoder, ASTC4x4WebGLEncoder, BC1Encoder, BC1WebGLEncoder, BC5Encoder, BC5WebGLEncoder, BC7Encoder, BC7EncoderOptions, BC7WebGLEncoder, Capabilities, ETC2Encoder, EncodeBytesResult, EncodeCallOptions, EncodeMipChainResult, EncodedLevelBytes, EncoderConstructor, EncoderOptions, ExtensionProvider, FeatureProvider, FormatSelection, FormatVariant, MipLevel, RasterizeSvgOptions, RawPixelSource, SelectFormatOptions, WebGLBlockEncoder, WebGLCapabilities, WebGLEncodeBytesResult, WebGLEncoderConstructor, WebGLEncoderImageSource, WebGLEncoderOptions, WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, selectFormat, selectWebGLFormat } from './index.js';
 import { Texture, CompressedTexture, Loader, CompressedPixelFormat } from 'three';
 
 /**
@@ -18,12 +18,22 @@ interface CompressOptions {
     hint?: TextureHint;
     /**
      * Prefer a specific format over the default choice when the device
-     * supports it; falls back to the normal selection (BC7 → ASTC → RGBA8)
-     * when it doesn't. Currently only 'bc1': half the memory of BC7 for
-     * opaque colour textures, at lower quality. Only honoured with
+     * 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';
     /**
@@ -38,19 +48,31 @@ interface CompressOptions {
     flipY?: boolean;
     /** Generate a full mip chain down to 1×1 on the CPU, encode every level. */
     mipmaps?: boolean;
-    /**
-     * Encode quality / speed trade-off. 'fast' (default) is ~2–4× faster for a
-     * ≤0.36 dB PSNR cost; 'high' runs the exhaustive search (output identical to
-     * the CPU reference encoders; for BC1, a principal-axis seed + iterative
-     * refit). No effect on the WebGL fallback (which always uses the fast
-     * encoders).
-     */
-    quality?: EncodeQuality;
     /** 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 {
     /** CompressedTexture on a compressed path; Texture on RGBA8 fallback. */
@@ -75,12 +97,43 @@ interface CompressResult {
     mipLevels: number;
     /** Wall-clock time of GPU encoding, summed across mip levels. */
     encodeMs: number;
-    /** Release the encoder's internal GPU resources. No-op if `device` was
-     *  passed in by the caller. */
+    /**
+     * 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;
+    /** Dispose the texture and release GPU resources owned by this call.
+     *  On the default path (no `device`/`adapter` option) the encoder and
+     *  device are shared across `compressTexture()` calls and survive this —
+     *  release those with `releaseSharedGpuResources()`. */
     destroy(): void;
 }
+/**
+ * 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 compressTexture(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;
+
 declare class GputexLoader extends Loader<Texture> {
     /** Format-selection hint. Default 'color'. */
     hint: TextureHint;
@@ -90,6 +143,12 @@ declare class GputexLoader extends Loader<Texture> {
      * `CompressOptions.preferredFormat`.
      */
     preferredFormat?: PreferredFormat;
+    /**
+     * Memory/fidelity trade-off: 'high' (default, BC7 / ASTC) or 'low'
+     * (BC1 / ETC2 RGB8 at half the memory, opaque colour only). See
+     * `CompressOptions.quality`.
+     */
+    quality: FormatQuality;
     /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
     colorSpace: 'srgb' | 'linear';
     /**
@@ -102,8 +161,10 @@ declare class GputexLoader extends Loader<Texture> {
     flipY: boolean;
     /** Generate + encode a full mip chain. Default false. */
     mipmaps: boolean;
-    /** Encode quality / speed trade-off. Default 'fast' (~2–4× faster, ≤0.36 dB). */
-    quality: EncodeQuality;
+    /** Reuse compressed bytes from the session's in-memory transcode cache,
+     *  skipping decode + encode on repeat loads. See `CompressOptions.cache`.
+     *  Default false. */
+    cache: boolean;
     /**
      * Optional pre-existing WebGPU device. Reusing the renderer's device
      * avoids spinning up a second WebGPU context for encoding.
@@ -158,8 +219,6 @@ interface EncodeResult {
 interface EncodeToTextureOptions {
     /** Pick the sRGB or linear variant of the encoder's format. Default 'srgb'. */
     colorSpace?: 'srgb' | 'linear';
-    /** Encode quality / speed trade-off. Default 'fast'. */
-    quality?: EncodeQuality;
     /** Flip the image vertically before encoding. Default false. */
     flipY?: boolean;
 }
@@ -169,6 +228,6 @@ interface EncodeToTextureOptions {
  * `encoder.encodeToBytes()` + `buildCompressedTexture()` for callers that want
  * a ready-to-use Three.js texture from one call.
  */
-declare function encodeToTexture(encoder: Encoder, source: EncoderImageSource, { colorSpace, quality, flipY }?: EncodeToTextureOptions): Promise<EncodeResult>;
+declare function encodeToTexture(encoder: Encoder, source: EncoderImageSource, { colorSpace, flipY }?: EncodeToTextureOptions): Promise<EncodeResult>;
 
-export { type CompressOptions, type CompressResult, type CompressTextureSource, EncodeQuality, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };
+export { type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, FormatQuality, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, clearTranscodeCache, compressTexture, encodeToTexture, releaseSharedGpuResources, setTranscodeCacheLimit, threeFormatFor };