gputex 0.4.0 → 0.6.0

package/dist/three.d.ts

@@ -1,74 +1,14 @@
-import { TextureHint, PreferredFormat, SvgRasterSize, 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 { CompressResult as CompressResult$1, CompressTextureSource, CompressOptions, 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, clearTranscodeCache, compressTextureToBytes, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateGpuMipChain, generateMipChain, getSharedWebGLContext, gpuMipLevelCount, isWebGLAvailable, padToBlockMultiple, rasterizeSvg, releaseSharedGpuResources, selectFormat, selectWebGLFormat, setTranscodeCacheLimit } from './index.js';
 import { Texture, CompressedTexture, Loader, CompressedPixelFormat } from 'three';
 
-/**
- * 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 → 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;
-    /** 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;
-}
-interface CompressResult {
-    /** CompressedTexture on a compressed path; Texture on RGBA8 fallback. */
+/** A `compressTexture()` result: a ready-to-use texture plus the same encode
+ *  metadata `compressTextureToBytes()` returns (minus the raw `levels`). */
+interface CompressResult extends Omit<CompressResult$1, 'levels' | 'fallbackBitmap'> {
+    /** `CompressedTexture` on a compressed path; a plain `Texture` on the RGBA8 fallback. */
     texture: Texture | CompressedTexture;
-    /** The compressed format selected, or null when we fell back to RGBA8. */
-    format: TextureFormat | null;
-    /** True iff we returned an uncompressed Texture 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;
-    /** Release the encoder's internal GPU resources. No-op if `device` was
-     *  passed in by the caller. */
+    /** Dispose the texture. The shared encoder/device survive — release those
+     *  with `releaseSharedGpuResources()`. */
     destroy(): void;
 }
 declare function compressTexture(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
@@ -82,6 +22,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';
     /**
@@ -94,6 +40,10 @@ declare class GputexLoader extends Loader<Texture> {
     flipY: boolean;
     /** Generate + encode a full mip chain. Default false. */
     mipmaps: boolean;
+    /** 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.
@@ -159,4 +109,4 @@ interface EncodeToTextureOptions {
  */
 declare function encodeToTexture(encoder: Encoder, source: EncoderImageSource, { colorSpace, flipY }?: EncodeToTextureOptions): Promise<EncodeResult>;
 
-export { type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };
+export { CompressOptions, type CompressResult, CompressTextureSource, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, FormatQuality, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };