gputex 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -605,4 +605,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 };

package/dist/index.js

@@ -44,6 +44,10 @@ function detectCapabilities(adapter) {
 }
 
 // src/workarounds.ts
+function needsWriteTextureWorkaround(adapter) {
+  const { vendor, architecture } = adapter.info ?? {};
+  return vendor === "img-tec" && architecture === "d-series";
+}
 function uploadSourceTexture(device, srcTex, source, width, height, flipY) {
   if (source instanceof ImageData && !flipY) {
     if (srcTex.format === "rg8unorm") {
@@ -460,25 +464,25 @@ var Encoder = class {
       if (useCache && (srcTexIsNew || dstIsNew || prepPlanesNew)) this._cachedBindGroup = null;
       let bindGroup = useCache ? this._cachedBindGroup : null;
       if (!bindGroup) {
-        const entries = [
+        const entries2 = [
           { binding: 0, resource: prepPlanes ? prepPlanes[0].createView() : srcTex.createView() },
           { binding: 1, resource: { buffer: dstBuffer } },
           { binding: 2, resource: { buffer: paramsBuffer } }
         ];
         if (prepPlanes) {
-          entries.push({ binding: 3, resource: prepPlanes[1].createView() });
+          entries2.push({ binding: 3, resource: prepPlanes[1].createView() });
         } else if (this._usesSampler) {
           this._sampler ??= device.createSampler({
             label: `${this.label}-clamp-sampler`,
             addressModeU: "clamp-to-edge",
             addressModeV: "clamp-to-edge"
           });
-          entries.push({ binding: 3, resource: this._sampler });
+          entries2.push({ binding: 3, resource: this._sampler });
         }
         bindGroup = device.createBindGroup({
           label: `${this.label}-bg`,
           layout: pipeline.getBindGroupLayout(0),
-          entries
+          entries: entries2
         });
         if (useCache) this._cachedBindGroup = bindGroup;
       }
@@ -646,7 +650,7 @@ var Encoder = class {
           (g, i) => this._createPrepBindGroup(prepPipeline, texs[i].createView(), planeSets[i], paramsBuf, i * CHAIN_ALIGN)
         ) : [];
         bindGroups = geoms.map((g, i) => {
-          const entries = [
+          const entries2 = [
             {
               binding: 0,
               resource: prepPipeline ? planeSets[i][0].createView() : texs[i].createView()
@@ -655,14 +659,14 @@ var Encoder = class {
             { binding: 2, resource: { buffer: paramsBuf, offset: i * CHAIN_ALIGN, size: 16 } }
           ];
           if (prepPipeline) {
-            entries.push({ binding: 3, resource: planeSets[i][1].createView() });
+            entries2.push({ binding: 3, resource: planeSets[i][1].createView() });
           } else if (this._usesSampler) {
-            entries.push({ binding: 3, resource: this._sampler });
+            entries2.push({ binding: 3, resource: this._sampler });
           }
           return device.createBindGroup({
             label: `${this.label}-chain-bg-${i}`,
             layout: pipeline.getBindGroupLayout(0),
-            entries
+            entries: entries2
           });
         });
         if (useCache) {
@@ -813,7 +817,7 @@ var Encoder = class {
         )
       ) : null;
       const bindGroups = geoms.map((g, i) => {
-        const entries = [
+        const entries2 = [
           {
             binding: 0,
             resource: planes ? planes[i][0].createView() : srcTex.createView({ baseMipLevel: i, mipLevelCount: 1 })
@@ -822,14 +826,14 @@ var Encoder = class {
           { binding: 2, resource: { buffer: paramsBuf, offset: i * CHAIN_ALIGN, size: 16 } }
         ];
         if (planes) {
-          entries.push({ binding: 3, resource: planes[i][1].createView() });
+          entries2.push({ binding: 3, resource: planes[i][1].createView() });
         } else if (this._usesSampler) {
-          entries.push({ binding: 3, resource: this._sampler });
+          entries2.push({ binding: 3, resource: this._sampler });
         }
         return device.createBindGroup({
           label: `${this.label}-chain-bg-${i}`,
           layout: pipeline.getBindGroupLayout(0),
-          entries
+          entries: entries2
         });
       });
       return await this._submitChainAndRead(
@@ -2492,6 +2496,18 @@ async function generateGpuMipChain(device, source, { flipY = false } = {}) {
 }
 
 // src/svg.ts
+function isSvgMarkup(source) {
+  return source.trimStart().startsWith("<");
+}
+function hasSvgExtension(url) {
+  return /\.svg$/i.test(url.split(/[?#]/, 1)[0]);
+}
+function isSvgBlob(blob) {
+  if (blob.type) {
+    return blob.type.split(";", 1)[0].trim().toLowerCase() === "image/svg+xml";
+  }
+  return typeof File !== "undefined" && blob instanceof File && hasSvgExtension(blob.name);
+}
 var ROOT_TAG_RE = /<svg(?=[\s/>])[^>]*>/;
 function getAttr(tag, name) {
   const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`).exec(tag);
@@ -2612,6 +2628,482 @@ async function rasterizeSvg(source, options = {}) {
     URL.revokeObjectURL(url);
   }
 }
+
+// src/transcodeCache.ts
+var DEFAULT_LIMIT = 256 * 1024 * 1024;
+var maxBytes = DEFAULT_LIMIT;
+var totalBytes = 0;
+var entries = /* @__PURE__ */ new Map();
+async function sha256Hex(data) {
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  let hex = "";
+  for (const b of new Uint8Array(digest)) hex += b.toString(16).padStart(2, "0");
+  return hex;
+}
+async function sourceIdentity(source, cacheKey) {
+  if (cacheKey) return `k:${cacheKey}`;
+  const canHash = typeof crypto !== "undefined" && !!crypto.subtle;
+  if (typeof source === "string") {
+    if (source.length > 1024 || /^data:/i.test(source) || /^\s*</.test(source)) {
+      return canHash ? `s:${await sha256Hex(new TextEncoder().encode(source))}` : null;
+    }
+    return `u:${source}`;
+  }
+  if (typeof Blob !== "undefined" && source instanceof Blob) {
+    return canHash ? `b:${await sha256Hex(await source.arrayBuffer())}` : null;
+  }
+  return null;
+}
+async function buildTranscodeKey(source, cacheKey, fp) {
+  if (maxBytes <= 0) return null;
+  const id = await sourceIdentity(source, cacheKey);
+  if (!id) return null;
+  const fingerprint = [
+    fp.format,
+    fp.colorSpace,
+    fp.flipY ? "flip" : "noflip",
+    fp.mipmaps ? "mips" : "nomips",
+    fp.svgSize === void 0 ? "" : JSON.stringify(fp.svgSize)
+  ].join("|");
+  return `${fingerprint}\0${id}`;
+}
+function readTranscodeCache(key) {
+  const hit = entries.get(key);
+  if (!hit) return null;
+  entries.delete(key);
+  entries.set(key, hit);
+  return hit.entry;
+}
+function writeTranscodeCache(key, entry) {
+  const bytes = entry.levels.reduce((sum, l) => sum + l.data.byteLength, 0);
+  if (bytes > maxBytes) return;
+  const prev = entries.get(key);
+  if (prev) {
+    totalBytes -= prev.bytes;
+    entries.delete(key);
+  }
+  entries.set(key, { entry, bytes });
+  totalBytes += bytes;
+  evictToLimit();
+}
+function evictToLimit() {
+  for (const [key, value] of entries) {
+    if (totalBytes <= maxBytes) break;
+    entries.delete(key);
+    totalBytes -= value.bytes;
+  }
+}
+function setTranscodeCacheLimit(bytes) {
+  maxBytes = Math.max(0, bytes);
+  evictToLimit();
+}
+function clearTranscodeCache() {
+  entries.clear();
+  totalBytes = 0;
+}
+
+// src/compressTexture.ts
+var sharedGpuPromise = null;
+var SHARED_DEVICE_FEATURES = [
+  "texture-compression-bc",
+  "texture-compression-astc",
+  "texture-compression-etc2",
+  "shader-f16",
+  "timestamp-query"
+];
+async function createSharedGpu() {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) return null;
+  const requiredFeatures = SHARED_DEVICE_FEATURES.filter((f) => adapter.features.has(f));
+  const device = await adapter.requestDevice({ requiredFeatures });
+  return { adapter, device, encoders: /* @__PURE__ */ new Map() };
+}
+function getSharedGpu() {
+  if (!sharedGpuPromise) {
+    const p = createSharedGpu();
+    sharedGpuPromise = p;
+    p.then((shared) => {
+      if (!shared) return;
+      void shared.device.lost.then(() => {
+        shared.encoders.forEach((encoder) => encoder.destroy());
+        shared.encoders.clear();
+        if (sharedGpuPromise === p) sharedGpuPromise = null;
+      });
+    }).catch(() => {
+      if (sharedGpuPromise === p) sharedGpuPromise = null;
+    });
+  }
+  return sharedGpuPromise;
+}
+function releaseSharedGpuResources() {
+  const p = sharedGpuPromise;
+  sharedGpuPromise = null;
+  void p?.then((shared) => {
+    if (!shared) return;
+    shared.encoders.forEach((encoder) => encoder.destroy());
+    shared.encoders.clear();
+    shared.device.destroy();
+  }).catch(() => {
+  });
+}
+async function sourceToBitmap(source, svgSize) {
+  const opts = {
+    colorSpaceConversion: "none",
+    premultiplyAlpha: "none"
+  };
+  if (typeof source === "string") {
+    if (isSvgMarkup(source)) {
+      return rasterizeSvg(source, { size: svgSize });
+    }
+    if (/^data:/i.test(source)) {
+      const blob2 = dataUrlToBlob(source);
+      if (isSvgBlob(blob2)) {
+        return rasterizeSvg(blob2, { size: svgSize });
+      }
+      return createImageBitmap(blob2, opts);
+    }
+    const resp = await fetch(source);
+    if (!resp.ok) {
+      throw new Error(`compressTexture: fetch ${source} failed (${resp.status})`);
+    }
+    const blob = await resp.blob();
+    if (isSvgBlob(blob) || !isImageMimeType(blob.type) && hasSvgExtension(source)) {
+      return rasterizeSvg(blob, { size: svgSize });
+    }
+    return createImageBitmap(blob, opts);
+  }
+  if (source instanceof Blob) {
+    if (isSvgBlob(source)) {
+      return rasterizeSvg(source, { size: svgSize });
+    }
+    return createImageBitmap(source, opts);
+  }
+  if (source instanceof ImageBitmap) {
+    return source;
+  }
+  if (typeof HTMLImageElement !== "undefined" && source instanceof HTMLImageElement) {
+    const src = source.currentSrc || source.src;
+    if (src && (hasSvgExtension(src) || /^data:image\/svg\+xml/i.test(src))) {
+      const resp = await fetch(src);
+      if (!resp.ok) {
+        throw new Error(`compressTexture: fetch ${src} failed (${resp.status})`);
+      }
+      return rasterizeSvg(await resp.blob(), { size: svgSize });
+    }
+  }
+  return createImageBitmap(source, opts);
+}
+function isImageMimeType(type) {
+  return /^image\//i.test(type) && !/svg/i.test(type);
+}
+function dataUrlToBlob(url) {
+  const comma = url.indexOf(",");
+  if (comma < 0) {
+    throw new Error("compressTexture: malformed data: URL (no comma)");
+  }
+  const header = url.slice(5, comma);
+  const isBase64 = /;base64$/i.test(header);
+  const type = header.replace(/;base64$/i, "");
+  if (!isBase64) {
+    return new Blob([decodeURIComponent(url.slice(comma + 1))], { type });
+  }
+  const payload = url.slice(comma + 1);
+  const fromBase64 = Uint8Array.fromBase64;
+  if (fromBase64) {
+    return new Blob([fromBase64(payload)], { type });
+  }
+  const bin = atob(payload);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return new Blob([bytes], { type });
+}
+function bitmapToMipLevel(bitmap, flipY) {
+  const w = bitmap.width, h = bitmap.height;
+  const canvas = typeof OffscreenCanvas !== "undefined" ? new OffscreenCanvas(w, h) : Object.assign(document.createElement("canvas"), { width: w, height: h });
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  if (!ctx) {
+    throw new Error("compressTexture: no 2D context available for mip generation");
+  }
+  if (flipY) {
+    ctx.translate(0, h);
+    ctx.scale(1, -1);
+  }
+  ctx.drawImage(bitmap, 0, 0);
+  const imageData = ctx.getImageData(0, 0, w, h);
+  return { data: imageData.data, width: w, height: h };
+}
+function mipLevelToImageData(level) {
+  return new ImageData(level.data, level.width, level.height);
+}
+async function compressTextureToBytes(source, options = {}) {
+  const {
+    hint = "color",
+    preferredFormat,
+    quality = "high",
+    colorSpace = "srgb",
+    svgSize,
+    flipY = true,
+    mipmaps = false,
+    cache = false,
+    cacheKey,
+    device: providedDevice,
+    adapter: providedAdapter
+  } = options;
+  const t0 = performance.now();
+  const gpu = await resolveWebGPU();
+  const gl = gpu ? null : resolveWebGL();
+  const activeFormat = gpu?.selection.format ?? gl?.selection.format ?? null;
+  let transcodeKey = null;
+  if (cache && activeFormat) {
+    transcodeKey = await buildTranscodeKey(source, cacheKey, {
+      format: activeFormat,
+      colorSpace,
+      flipY,
+      mipmaps,
+      svgSize
+    });
+    if (transcodeKey) {
+      const hit = readTranscodeCache(transcodeKey);
+      if (hit) {
+        return {
+          levels: hit.levels,
+          fallbackBitmap: null,
+          format: hit.format,
+          fallbackUncompressed: false,
+          backend: gpu ? "webgpu" : "webgl",
+          astcNormalRemap: (gpu ?? gl).selection.astcNormalRemap,
+          width: hit.width,
+          height: hit.height,
+          mipLevels: hit.levels.length,
+          encodeMs: 0,
+          decodeMs: 0,
+          totalMs: performance.now() - t0,
+          cacheHit: true
+        };
+      }
+    }
+  }
+  const tDecode = performance.now();
+  const bitmap = await sourceToBitmap(source, svgSize);
+  const decodeMs = performance.now() - tDecode;
+  if (gpu) return encodeViaWebGPU(gpu);
+  const viaWebGL = gl ? encodeViaWebGL(gl) : null;
+  if (viaWebGL) return viaWebGL;
+  console.warn(
+    "[compressTextureToBytes] No compressed path available (WebGPU and WebGL2 both lack a usable compressed-texture format); returning uncompressed RGBA8."
+  );
+  return {
+    levels: null,
+    fallbackBitmap: bitmap,
+    format: null,
+    fallbackUncompressed: true,
+    backend: "none",
+    astcNormalRemap: false,
+    width: bitmap.width,
+    height: bitmap.height,
+    mipLevels: 1,
+    encodeMs: 0,
+    decodeMs,
+    totalMs: performance.now() - t0,
+    cacheHit: false
+  };
+  async function resolveWebGPU() {
+    if (!("gpu" in navigator)) return null;
+    let shared = null;
+    let adapter;
+    if (providedAdapter) {
+      adapter = providedAdapter;
+    } else if (providedDevice) {
+      adapter = await navigator.gpu.requestAdapter();
+    } else {
+      shared = await getSharedGpu();
+      adapter = shared?.adapter ?? null;
+    }
+    if (!adapter) return null;
+    const selection = selectFormat(adapter, hint, { colorSpace, preferredFormat, quality });
+    if (!selection.format || !selection.encoderClass) return null;
+    return {
+      adapter,
+      shared,
+      selection: { ...selection, format: selection.format, encoderClass: selection.encoderClass }
+    };
+  }
+  async function encodeViaWebGPU({ adapter, shared, selection }) {
+    const EncoderCtor = selection.encoderClass;
+    let encoder;
+    let sharedEncoder = false;
+    if (providedDevice) {
+      encoder = new EncoderCtor({ device: providedDevice, adapter, ownsDevice: false });
+    } else if (shared) {
+      sharedEncoder = true;
+      let cached = shared.encoders.get(EncoderCtor);
+      if (!cached) {
+        cached = new EncoderCtor({ device: shared.device, adapter: shared.adapter, ownsDevice: false });
+        shared.encoders.set(EncoderCtor, cached);
+      }
+      encoder = cached;
+    } else {
+      encoder = await EncoderCtor.create();
+    }
+    const destroyEncoder = sharedEncoder ? () => {
+    } : () => encoder.destroy();
+    try {
+      const needsWriteTexture = needsWriteTextureWorkaround(adapter);
+      if (!mipmaps) {
+        let bytes;
+        if (needsWriteTexture) {
+          const level0 = bitmapToMipLevel(bitmap, flipY);
+          const imageData = mipLevelToImageData(level0);
+          bytes = await encoder.encodeToBytes(imageData);
+        } else {
+          bytes = await encoder.encodeToBytes(bitmap, { flipY });
+        }
+        if (transcodeKey) {
+          writeTranscodeCache(transcodeKey, {
+            format: selection.format,
+            width: bytes.width,
+            height: bytes.height,
+            levels: [bytes]
+          });
+        }
+        destroyEncoder();
+        return {
+          levels: [bytes],
+          fallbackBitmap: null,
+          format: selection.format,
+          fallbackUncompressed: false,
+          backend: "webgpu",
+          astcNormalRemap: selection.astcNormalRemap,
+          width: bytes.width,
+          height: bytes.height,
+          mipLevels: 1,
+          encodeMs: bytes.encodeMs,
+          decodeMs,
+          totalMs: performance.now() - t0,
+          cacheHit: false
+        };
+      }
+      let chainResult;
+      if (needsWriteTexture) {
+        const level0 = bitmapToMipLevel(bitmap, flipY);
+        chainResult = await encoder.encodeMipChainToBytes(generateMipChain(level0).map(padToBlockMultiple));
+      } else {
+        const chainTex = await generateGpuMipChain(encoder.device, bitmap, { flipY });
+        try {
+          chainResult = await encoder.encodeMipChainFromTexture(chainTex);
+        } finally {
+          chainTex.destroy();
+        }
+      }
+      const { levels, encodeMs } = chainResult;
+      if (transcodeKey) {
+        writeTranscodeCache(transcodeKey, {
+          format: selection.format,
+          width: bitmap.width,
+          height: bitmap.height,
+          levels
+        });
+      }
+      destroyEncoder();
+      return {
+        levels,
+        fallbackBitmap: null,
+        format: selection.format,
+        fallbackUncompressed: false,
+        backend: "webgpu",
+        astcNormalRemap: selection.astcNormalRemap,
+        width: bitmap.width,
+        height: bitmap.height,
+        mipLevels: levels.length,
+        encodeMs,
+        decodeMs,
+        totalMs: performance.now() - t0,
+        cacheHit: false
+      };
+    } catch (e) {
+      destroyEncoder();
+      throw e;
+    }
+  }
+  function resolveWebGL() {
+    const gl2 = getSharedWebGLContext();
+    if (!gl2) return null;
+    const caps = detectWebGLCapabilities(gl2);
+    const selection = selectWebGLFormat(caps, hint, { colorSpace, preferredFormat, quality });
+    if (!selection.format || !selection.encoderClass) return null;
+    return { gl: gl2, selection: { ...selection, format: selection.format, encoderClass: selection.encoderClass } };
+  }
+  function encodeViaWebGL({ gl: gl2, selection }) {
+    const encoder = selection.encoderClass.create(gl2);
+    try {
+      if (!mipmaps) {
+        const bytes = encoder.encodeToBytes(bitmap, { flipY });
+        if (transcodeKey) {
+          writeTranscodeCache(transcodeKey, {
+            format: selection.format,
+            width: bytes.width,
+            height: bytes.height,
+            levels: [bytes]
+          });
+        }
+        encoder.destroy();
+        return {
+          levels: [bytes],
+          fallbackBitmap: null,
+          format: selection.format,
+          fallbackUncompressed: false,
+          backend: "webgl",
+          astcNormalRemap: selection.astcNormalRemap,
+          width: bytes.width,
+          height: bytes.height,
+          mipLevels: 1,
+          encodeMs: bytes.encodeMs,
+          decodeMs,
+          totalMs: performance.now() - t0,
+          cacheHit: false
+        };
+      }
+      const level0 = bitmapToMipLevel(bitmap, flipY);
+      const chain = generateMipChain(level0);
+      const encodedLevels = [];
+      let totalEncodeMs = 0;
+      for (const level of chain) {
+        const padded = padToBlockMultiple(level);
+        const bytes = encoder.encodeToBytes(padded);
+        encodedLevels.push(bytes);
+        totalEncodeMs += bytes.encodeMs;
+      }
+      if (transcodeKey) {
+        writeTranscodeCache(transcodeKey, {
+          format: selection.format,
+          width: level0.width,
+          height: level0.height,
+          levels: encodedLevels
+        });
+      }
+      encoder.destroy();
+      return {
+        levels: encodedLevels,
+        fallbackBitmap: null,
+        format: selection.format,
+        fallbackUncompressed: false,
+        backend: "webgl",
+        astcNormalRemap: selection.astcNormalRemap,
+        width: level0.width,
+        height: level0.height,
+        mipLevels: encodedLevels.length,
+        encodeMs: totalEncodeMs,
+        decodeMs,
+        totalMs: performance.now() - t0,
+        cacheHit: false
+      };
+    } catch (e) {
+      encoder.destroy();
+      console.warn("[compressTextureToBytes] WebGL fallback encode failed; returning uncompressed RGBA8.", e);
+      return null;
+    }
+  }
+}
 export {
   ASTC4x4Encoder,
   ASTC4x4WebGLEncoder,
@@ -2626,6 +3118,8 @@ export {
   TextureFormat,
   WebGLBlockEncoder,
   WebGPUFeature,
+  clearTranscodeCache,
+  compressTextureToBytes,
   createWebGLContext,
   detectCapabilities,
   detectWebGLCapabilities,
@@ -2636,6 +3130,8 @@ export {
   isWebGLAvailable,
   padToBlockMultiple,
   rasterizeSvg,
+  releaseSharedGpuResources,
   selectFormat,
-  selectWebGLFormat
+  selectWebGLFormat,
+  setTranscodeCacheLimit
 };

package/dist/three.d.ts

@@ -1,139 +1,18 @@
-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 { 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 → 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 {
-    /** 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;
-    /**
-     * 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()`. */
+    /** Dispose the texture. The shared encoder/device survive — 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;
@@ -230,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, FormatQuality, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, clearTranscodeCache, compressTexture, encodeToTexture, releaseSharedGpuResources, setTranscodeCacheLimit, threeFormatFor };
+export { CompressOptions, type CompressResult, CompressTextureSource, type EncodeResult, type EncodeToTextureOptions, Encoder, EncoderImageSource, FormatQuality, GputexLoader, PreferredFormat, SvgRasterSize, TextureFormat, TextureHint, buildCompressedTexture, compressTexture, encodeToTexture, threeFormatFor };

package/dist/three.js

@@ -2629,87 +2629,7 @@ async function rasterizeSvg(source, options = {}) {
   }
 }
 
-// src/three/compressTexture.ts
-import { ClampToEdgeWrapping as ClampToEdgeWrapping2, LinearFilter as LinearFilter2, LinearSRGBColorSpace as LinearSRGBColorSpace2, SRGBColorSpace as SRGBColorSpace2, Texture } from "three";
-
-// src/three/buildTexture.ts
-import {
-  RED_GREEN_RGTC2_Format,
-  RGB_ETC2_Format,
-  RGBA_ASTC_4x4_Format,
-  RGBA_BPTC_Format,
-  RGBA_S3TC_DXT1_Format
-} from "three";
-
-// src/three/textureAssembly.ts
-import {
-  ClampToEdgeWrapping,
-  CompressedTexture,
-  LinearFilter,
-  LinearMipmapLinearFilter,
-  LinearSRGBColorSpace,
-  SRGBColorSpace
-} from "three";
-function assembleCompressedTexture(levels, threeFormat, effectiveSrgb) {
-  if (levels.length === 0) {
-    throw new Error("assembleCompressedTexture: no levels provided");
-  }
-  const mipmaps = levels.map((l) => ({
-    data: l.data,
-    width: l.paddedWidth,
-    height: l.paddedHeight
-  }));
-  const base = levels[0];
-  const texture = new CompressedTexture(mipmaps, base.paddedWidth, base.paddedHeight, threeFormat);
-  texture.colorSpace = effectiveSrgb ? SRGBColorSpace : LinearSRGBColorSpace;
-  texture.magFilter = LinearFilter;
-  texture.minFilter = levels.length > 1 ? LinearMipmapLinearFilter : LinearFilter;
-  texture.generateMipmaps = false;
-  texture.wrapS = texture.wrapT = ClampToEdgeWrapping;
-  texture.needsUpdate = true;
-  texture.userData.logicalWidth = base.width;
-  texture.userData.logicalHeight = base.height;
-  texture.userData.mipLevels = levels.length;
-  return texture;
-}
-
-// src/three/buildTexture.ts
-var THREE_FORMAT = {
-  [TextureFormat.BC1]: RGBA_S3TC_DXT1_Format,
-  [TextureFormat.BC1_SRGB]: RGBA_S3TC_DXT1_Format,
-  [TextureFormat.BC5]: RED_GREEN_RGTC2_Format,
-  [TextureFormat.BC7]: RGBA_BPTC_Format,
-  [TextureFormat.BC7_SRGB]: RGBA_BPTC_Format,
-  [TextureFormat.ASTC_4x4]: RGBA_ASTC_4x4_Format,
-  [TextureFormat.ASTC_4x4_SRGB]: RGBA_ASTC_4x4_Format,
-  [TextureFormat.ETC2_RGB8]: RGB_ETC2_Format,
-  [TextureFormat.ETC2_RGB8_SRGB]: RGB_ETC2_Format
-};
-var SRGB_FORMATS = /* @__PURE__ */ new Set([
-  TextureFormat.BC1_SRGB,
-  TextureFormat.BC7_SRGB,
-  TextureFormat.ASTC_4x4_SRGB,
-  TextureFormat.ETC2_RGB8_SRGB
-]);
-function isSrgbFormat(format) {
-  return SRGB_FORMATS.has(format);
-}
-function threeFormatFor(format) {
-  return THREE_FORMAT[format];
-}
-function buildCompressedTexture(levels, format) {
-  return assembleCompressedTexture(levels, threeFormatFor(format), isSrgbFormat(format));
-}
-async function encodeToTexture(encoder, source, { colorSpace = "srgb", flipY = false } = {}) {
-  const formats = encoder.constructor.textureFormats;
-  const wantSrgb = colorSpace === "srgb" && encoder.supportsSrgb;
-  const format = formats.find((f) => isSrgbFormat(f) === wantSrgb) ?? formats[0];
-  const bytes = await encoder.encodeToBytes(source, { flipY });
-  const texture = buildCompressedTexture([bytes], format);
-  return { ...bytes, texture };
-}
-
-// src/three/transcodeCache.ts
+// src/transcodeCache.ts
 var DEFAULT_LIMIT = 256 * 1024 * 1024;
 var maxBytes = DEFAULT_LIMIT;
 var totalBytes = 0;
@@ -2782,7 +2702,7 @@ function clearTranscodeCache() {
   totalBytes = 0;
 }
 
-// src/three/compressTexture.ts
+// src/compressTexture.ts
 var sharedGpuPromise = null;
 var SHARED_DEVICE_FEATURES = [
   "texture-compression-bc",
@@ -2915,18 +2835,7 @@ function bitmapToMipLevel(bitmap, flipY) {
 function mipLevelToImageData(level) {
   return new ImageData(level.data, level.width, level.height);
 }
-function wrapUncompressed(bitmap, srgb, flipY) {
-  const tex = new Texture(bitmap);
-  tex.colorSpace = srgb ? SRGBColorSpace2 : LinearSRGBColorSpace2;
-  tex.magFilter = LinearFilter2;
-  tex.minFilter = LinearFilter2;
-  tex.wrapS = tex.wrapT = ClampToEdgeWrapping2;
-  tex.generateMipmaps = false;
-  tex.flipY = flipY;
-  tex.needsUpdate = true;
-  return tex;
-}
-async function compressTexture(source, options = {}) {
+async function compressTextureToBytes(source, options = {}) {
   const {
     hint = "color",
     preferredFormat,
@@ -2940,7 +2849,6 @@ async function compressTexture(source, options = {}) {
     device: providedDevice,
     adapter: providedAdapter
   } = options;
-  const srgb = colorSpace === "srgb";
   const t0 = performance.now();
   const gpu = await resolveWebGPU();
   const gl = gpu ? null : resolveWebGL();
@@ -2957,9 +2865,9 @@ async function compressTexture(source, options = {}) {
     if (transcodeKey) {
       const hit = readTranscodeCache(transcodeKey);
       if (hit) {
-        const tex2 = buildCompressedTexture(hit.levels, hit.format);
         return {
-          texture: tex2,
+          levels: hit.levels,
+          fallbackBitmap: null,
           format: hit.format,
           fallbackUncompressed: false,
           backend: gpu ? "webgpu" : "webgl",
@@ -2970,10 +2878,7 @@ async function compressTexture(source, options = {}) {
           encodeMs: 0,
           decodeMs: 0,
           totalMs: performance.now() - t0,
-          cacheHit: true,
-          destroy: () => {
-            tex2.dispose();
-          }
+          cacheHit: true
         };
       }
     }
@@ -2985,11 +2890,11 @@ async function compressTexture(source, options = {}) {
   const viaWebGL = gl ? encodeViaWebGL(gl) : null;
   if (viaWebGL) return viaWebGL;
   console.warn(
-    "[compressTexture] No compressed path available (WebGPU and WebGL2 both lack a usable compressed-texture format); returning uncompressed RGBA8."
+    "[compressTextureToBytes] No compressed path available (WebGPU and WebGL2 both lack a usable compressed-texture format); returning uncompressed RGBA8."
   );
-  const tex = wrapUncompressed(bitmap, srgb, flipY);
   return {
-    texture: tex,
+    levels: null,
+    fallbackBitmap: bitmap,
     format: null,
     fallbackUncompressed: true,
     backend: "none",
@@ -3000,10 +2905,7 @@ async function compressTexture(source, options = {}) {
     encodeMs: 0,
     decodeMs,
     totalMs: performance.now() - t0,
-    cacheHit: false,
-    destroy: () => {
-      tex.dispose();
-    }
+    cacheHit: false
   };
   async function resolveWebGPU() {
     if (!("gpu" in navigator)) return null;
@@ -3056,7 +2958,6 @@ async function compressTexture(source, options = {}) {
         } else {
           bytes = await encoder.encodeToBytes(bitmap, { flipY });
         }
-        const tex3 = buildCompressedTexture([bytes], selection.format);
         if (transcodeKey) {
           writeTranscodeCache(transcodeKey, {
             format: selection.format,
@@ -3065,8 +2966,10 @@ async function compressTexture(source, options = {}) {
             levels: [bytes]
           });
         }
+        destroyEncoder();
         return {
-          texture: tex3,
+          levels: [bytes],
+          fallbackBitmap: null,
           format: selection.format,
           fallbackUncompressed: false,
           backend: "webgpu",
@@ -3077,11 +2980,7 @@ async function compressTexture(source, options = {}) {
           encodeMs: bytes.encodeMs,
           decodeMs,
           totalMs: performance.now() - t0,
-          cacheHit: false,
-          destroy: () => {
-            tex3.dispose();
-            destroyEncoder();
-          }
+          cacheHit: false
         };
       }
       let chainResult;
@@ -3097,7 +2996,6 @@ async function compressTexture(source, options = {}) {
         }
       }
       const { levels, encodeMs } = chainResult;
-      const tex2 = buildCompressedTexture(levels, selection.format);
       if (transcodeKey) {
         writeTranscodeCache(transcodeKey, {
           format: selection.format,
@@ -3106,8 +3004,10 @@ async function compressTexture(source, options = {}) {
           levels
         });
       }
+      destroyEncoder();
       return {
-        texture: tex2,
+        levels,
+        fallbackBitmap: null,
         format: selection.format,
         fallbackUncompressed: false,
         backend: "webgpu",
@@ -3118,11 +3018,7 @@ async function compressTexture(source, options = {}) {
         encodeMs,
         decodeMs,
         totalMs: performance.now() - t0,
-        cacheHit: false,
-        destroy: () => {
-          tex2.dispose();
-          destroyEncoder();
-        }
+        cacheHit: false
       };
     } catch (e) {
       destroyEncoder();
@@ -3142,7 +3038,6 @@ async function compressTexture(source, options = {}) {
     try {
       if (!mipmaps) {
         const bytes = encoder.encodeToBytes(bitmap, { flipY });
-        const tex3 = buildCompressedTexture([bytes], selection.format);
         if (transcodeKey) {
           writeTranscodeCache(transcodeKey, {
             format: selection.format,
@@ -3151,8 +3046,10 @@ async function compressTexture(source, options = {}) {
             levels: [bytes]
           });
         }
+        encoder.destroy();
         return {
-          texture: tex3,
+          levels: [bytes],
+          fallbackBitmap: null,
           format: selection.format,
           fallbackUncompressed: false,
           backend: "webgl",
@@ -3163,11 +3060,7 @@ async function compressTexture(source, options = {}) {
           encodeMs: bytes.encodeMs,
           decodeMs,
           totalMs: performance.now() - t0,
-          cacheHit: false,
-          destroy: () => {
-            tex3.dispose();
-            encoder.destroy();
-          }
+          cacheHit: false
         };
       }
       const level0 = bitmapToMipLevel(bitmap, flipY);
@@ -3180,7 +3073,6 @@ async function compressTexture(source, options = {}) {
         encodedLevels.push(bytes);
         totalEncodeMs += bytes.encodeMs;
       }
-      const tex2 = buildCompressedTexture(encodedLevels, selection.format);
       if (transcodeKey) {
         writeTranscodeCache(transcodeKey, {
           format: selection.format,
@@ -3189,8 +3081,10 @@ async function compressTexture(source, options = {}) {
           levels: encodedLevels
         });
       }
+      encoder.destroy();
       return {
-        texture: tex2,
+        levels: encodedLevels,
+        fallbackBitmap: null,
         format: selection.format,
         fallbackUncompressed: false,
         backend: "webgl",
@@ -3201,20 +3095,114 @@ async function compressTexture(source, options = {}) {
         encodeMs: totalEncodeMs,
         decodeMs,
         totalMs: performance.now() - t0,
-        cacheHit: false,
-        destroy: () => {
-          tex2.dispose();
-          encoder.destroy();
-        }
+        cacheHit: false
       };
     } catch (e) {
       encoder.destroy();
-      console.warn("[compressTexture] WebGL fallback encode failed; returning uncompressed RGBA8.", e);
+      console.warn("[compressTextureToBytes] WebGL fallback encode failed; returning uncompressed RGBA8.", e);
       return null;
     }
   }
 }
 
+// src/three/compressTexture.ts
+import { ClampToEdgeWrapping as ClampToEdgeWrapping2, LinearFilter as LinearFilter2, LinearSRGBColorSpace as LinearSRGBColorSpace2, SRGBColorSpace as SRGBColorSpace2, Texture } from "three";
+
+// src/three/buildTexture.ts
+import {
+  RED_GREEN_RGTC2_Format,
+  RGB_ETC2_Format,
+  RGBA_ASTC_4x4_Format,
+  RGBA_BPTC_Format,
+  RGBA_S3TC_DXT1_Format
+} from "three";
+
+// src/three/textureAssembly.ts
+import {
+  ClampToEdgeWrapping,
+  CompressedTexture,
+  LinearFilter,
+  LinearMipmapLinearFilter,
+  LinearSRGBColorSpace,
+  SRGBColorSpace
+} from "three";
+function assembleCompressedTexture(levels, threeFormat, effectiveSrgb) {
+  if (levels.length === 0) {
+    throw new Error("assembleCompressedTexture: no levels provided");
+  }
+  const mipmaps = levels.map((l) => ({
+    data: l.data,
+    width: l.paddedWidth,
+    height: l.paddedHeight
+  }));
+  const base = levels[0];
+  const texture = new CompressedTexture(mipmaps, base.paddedWidth, base.paddedHeight, threeFormat);
+  texture.colorSpace = effectiveSrgb ? SRGBColorSpace : LinearSRGBColorSpace;
+  texture.magFilter = LinearFilter;
+  texture.minFilter = levels.length > 1 ? LinearMipmapLinearFilter : LinearFilter;
+  texture.generateMipmaps = false;
+  texture.wrapS = texture.wrapT = ClampToEdgeWrapping;
+  texture.needsUpdate = true;
+  texture.userData.logicalWidth = base.width;
+  texture.userData.logicalHeight = base.height;
+  texture.userData.mipLevels = levels.length;
+  return texture;
+}
+
+// src/three/buildTexture.ts
+var THREE_FORMAT = {
+  [TextureFormat.BC1]: RGBA_S3TC_DXT1_Format,
+  [TextureFormat.BC1_SRGB]: RGBA_S3TC_DXT1_Format,
+  [TextureFormat.BC5]: RED_GREEN_RGTC2_Format,
+  [TextureFormat.BC7]: RGBA_BPTC_Format,
+  [TextureFormat.BC7_SRGB]: RGBA_BPTC_Format,
+  [TextureFormat.ASTC_4x4]: RGBA_ASTC_4x4_Format,
+  [TextureFormat.ASTC_4x4_SRGB]: RGBA_ASTC_4x4_Format,
+  [TextureFormat.ETC2_RGB8]: RGB_ETC2_Format,
+  [TextureFormat.ETC2_RGB8_SRGB]: RGB_ETC2_Format
+};
+var SRGB_FORMATS = /* @__PURE__ */ new Set([
+  TextureFormat.BC1_SRGB,
+  TextureFormat.BC7_SRGB,
+  TextureFormat.ASTC_4x4_SRGB,
+  TextureFormat.ETC2_RGB8_SRGB
+]);
+function isSrgbFormat(format) {
+  return SRGB_FORMATS.has(format);
+}
+function threeFormatFor(format) {
+  return THREE_FORMAT[format];
+}
+function buildCompressedTexture(levels, format) {
+  return assembleCompressedTexture(levels, threeFormatFor(format), isSrgbFormat(format));
+}
+async function encodeToTexture(encoder, source, { colorSpace = "srgb", flipY = false } = {}) {
+  const formats = encoder.constructor.textureFormats;
+  const wantSrgb = colorSpace === "srgb" && encoder.supportsSrgb;
+  const format = formats.find((f) => isSrgbFormat(f) === wantSrgb) ?? formats[0];
+  const bytes = await encoder.encodeToBytes(source, { flipY });
+  const texture = buildCompressedTexture([bytes], format);
+  return { ...bytes, texture };
+}
+
+// src/three/compressTexture.ts
+function wrapUncompressed(bitmap, srgb, flipY) {
+  const tex = new Texture(bitmap);
+  tex.colorSpace = srgb ? SRGBColorSpace2 : LinearSRGBColorSpace2;
+  tex.magFilter = LinearFilter2;
+  tex.minFilter = LinearFilter2;
+  tex.wrapS = tex.wrapT = ClampToEdgeWrapping2;
+  tex.generateMipmaps = false;
+  tex.flipY = flipY;
+  tex.needsUpdate = true;
+  return tex;
+}
+async function compressTexture(source, options = {}) {
+  const { levels, fallbackBitmap, ...rest } = await compressTextureToBytes(source, options);
+  const texture = fallbackBitmap !== null ? wrapUncompressed(fallbackBitmap, options.colorSpace !== "linear", options.flipY ?? true) : buildCompressedTexture(levels, rest.format);
+  return { ...rest, texture, destroy: () => texture.dispose() };
+}
+
 // src/three/GputexLoader.ts
 import { Loader } from "three";
 var GputexLoader = class extends Loader {
@@ -3327,6 +3315,7 @@ export {
   buildCompressedTexture,
   clearTranscodeCache,
   compressTexture,
+  compressTextureToBytes,
   createWebGLContext,
   detectCapabilities,
   detectWebGLCapabilities,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gputex",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "files": [
     "dist"