gputex 0.1.2 → 0.2.0

package/dist/three.d.ts

@@ -0,0 +1,141 @@
+import { TextureHint, 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, RawPixelSource, SelectFormatOptions, WebGLBlockEncoder, WebGLCapabilities, WebGLEncodeBytesResult, WebGLEncoderConstructor, WebGLEncoderImageSource, WebGLEncoderOptions, WebGLFormatSelection, WebGPUFeature, createWebGLContext, detectCapabilities, detectWebGLCapabilities, generateMipChain, getSharedWebGLContext, isWebGLAvailable, padToBlockMultiple, selectFormat, selectWebGLFormat } 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.
+ */
+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;
+    /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
+    colorSpace?: 'srgb' | 'linear';
+    /** 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;
+    /**
+     * 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;
+}
+interface CompressResult {
+    /** CompressedTexture on a compressed path; Texture on 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. */
+    destroy(): void;
+}
+declare function compressTexture(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
+
+declare class GputexLoader extends Loader<Texture> {
+    /** Format-selection hint. Default 'color'. */
+    hint: TextureHint;
+    /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
+    colorSpace: 'srgb' | 'linear';
+    /** Flip the image vertically before encoding. Default true (matches Three.js convention). */
+    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;
+    /**
+     * Optional pre-existing WebGPU device. Reusing the renderer's device
+     * avoids spinning up a second WebGPU context for encoding.
+     */
+    device?: GPUDevice;
+    adapter?: GPUAdapter;
+    /**
+     * Most recent full encode result. Useful when the caller wants format
+     * / mipLevels / astcNormalRemap metadata without threading a separate
+     * callback through `load()`. Cleared when a new load starts.
+     */
+    lastResult: CompressResult | null;
+    /**
+     * THREE.Loader contract: returns void, drives callbacks. `loadAsync`
+     * (inherited from the base class) wraps this with Promise semantics.
+     * Errors routed through `manager.itemError` so the LoadingManager's
+     * aggregate state stays accurate.
+     */
+    load(url: string, onLoad?: (texture: Texture) => void, _onProgress?: (event: ProgressEvent) => void, onError?: (err: unknown) => void): void;
+}
+
+/** One encoded mip level. The fields both encoder backends already produce. */
+interface EncodedLevel {
+    /** Logical (pre-padding) dimensions, surfaced on the texture's userData. */
+    width: number;
+    height: number;
+    /** Block-aligned dimensions the compressed `data` actually covers. */
+    paddedWidth: number;
+    paddedHeight: number;
+    data: Uint8Array;
+}
+
+/** The Three.js `CompressedPixelFormat` constant for a logical `TextureFormat`. */
+declare function threeFormatFor(format: TextureFormat): CompressedPixelFormat;
+/**
+ * Wrap pre-encoded mip levels into a `CompressedTexture` for the given logical
+ * format. `levels[0]` is the base level. The texture's colour space is taken
+ * from the format variant (sRGB families tag sRGB, everything else linear), so
+ * no separate colour-space argument is needed — pick the format variant you
+ * want (e.g. `BC7_SRGB` vs `BC7`).
+ */
+declare function buildCompressedTexture(levels: readonly EncodedLevel[], format: TextureFormat): CompressedTexture;
+interface EncodeResult {
+    width: number;
+    height: number;
+    paddedWidth: number;
+    paddedHeight: number;
+    data: Uint8Array;
+    texture: CompressedTexture;
+    encodeMs: number;
+}
+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;
+}
+/**
+ * One-shot: encode a single image with a WebGPU `Encoder` straight to a
+ * `CompressedTexture`, plus the raw byte metadata. Convenience wrapper over
+ * `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>;
+
+export { type CompressOptions, type CompressResult, type CompressTextureSource, EncodeQuality, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, GputexLoader, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };