gputex 0.0.3 → 0.0.5

package/README.md

@@ -14,7 +14,7 @@ pnpm add gputex
 bun add gputex
 ```
 
-`three` is a peer dependency (`>=0.170`).
+`three` is a peer dependency (`>=0.180`).
 
 ## Formats
 
@@ -43,12 +43,12 @@ const { texture, format } = await compressTexture('/cobblestone.avif', {
 material.map = texture
 ```
 
-### `WebGPUCompressedTextureLoader` — Three.js Loader
+### `GputexLoader` — Three.js Loader
 
 ```ts
-import { WebGPUCompressedTextureLoader } from 'gputex'
+import { GputexLoader } from 'gputex'
 
-const loader = new WebGPUCompressedTextureLoader()
+const loader = new GputexLoader()
 loader.hint = 'normal'
 loader.mipmaps = true
 const normalMap = await loader.loadAsync('/brick_normal.png')
@@ -57,14 +57,14 @@ material.normalMap = normalMap
 
 ### React Three Fiber
 
-The `WebGPUCompressedTextureLoader` works with R3F's `useLoader`:
+The `GputexLoader` works with R3F's `useLoader`:
 
 ```tsx
 import { useLoader } from '@react-three/fiber'
-import { WebGPUCompressedTextureLoader } from 'gputex'
+import { GputexLoader } from 'gputex'
 
 function Scene() {
-  const texture = useLoader(WebGPUCompressedTextureLoader, '/cobblestone.avif', loader => {
+  const texture = useLoader(GputexLoader, '/cobblestone.avif', loader => {
     loader.hint = 'color'
     loader.colorSpace = 'srgb'
     loader.mipmaps = true
@@ -84,11 +84,11 @@ For a reusable hook with metadata access:
 ```tsx
 import { useLayoutEffect } from 'react'
 import { useLoader } from '@react-three/fiber'
-import { WebGPUCompressedTextureLoader } from 'gputex'
+import { GputexLoader } from 'gputex'
 import type { TextureHint } from 'gputex'
 
 function useGputex(url: string, options?: { hint?: TextureHint; colorSpace?: 'srgb' | 'linear'; mipmaps?: boolean }) {
-  const texture = useLoader(WebGPUCompressedTextureLoader, url, loader => {
+  const texture = useLoader(GputexLoader, url, loader => {
     if (options?.hint !== undefined) loader.hint = options.hint
     if (options?.colorSpace !== undefined) loader.colorSpace = options.colorSpace
     if (options?.mipmaps !== undefined) loader.mipmaps = options.mipmaps
@@ -102,7 +102,7 @@ useGputex.preload = (
   url: string,
   options?: { hint?: TextureHint; colorSpace?: 'srgb' | 'linear'; mipmaps?: boolean },
 ) => {
-  useLoader.preload(WebGPUCompressedTextureLoader, url, loader => {
+  useLoader.preload(GputexLoader, url, loader => {
     if (options?.hint !== undefined) loader.hint = options.hint
     if (options?.colorSpace !== undefined) loader.colorSpace = options.colorSpace
     if (options?.mipmaps !== undefined) loader.mipmaps = options.mipmaps
@@ -158,6 +158,10 @@ encoder.destroy()
 - `texture-compression-bc` (desktop) or `texture-compression-astc` (mobile) for compressed output
 - Falls back to uncompressed RGBA8 when neither is available
 
+## Device-specific workarounds
+
+- Black texture on Google Pixel 10: `copyExternalImageToTexture` produces black textures on the Pixel 10's PowerVR DXT GPU (vendor `img-tec`, architecture `d-series`). Worked around by uploading via `writeTexture` with rasterised pixel data instead.
+
 ## Acknowledgements
 
 The concept of encoding images on the GPU on the fly via compute shaders was first introduced by [spark.js](https://ludicon.com/sparkjs/), which is a much more robust solution for users who can afford its license. GPUtex is not derived from Spark and its encoders have been implemented from scratch using official references, which have been ported to TypeScript, and then converted to WGSL via AI. For any serious production use of GPU-compressed textures, Spark is the recommended choice over GPUtex.

package/dist/index.d.ts

@@ -274,7 +274,7 @@ interface CompressResult {
 }
 declare function compressTexture(source: CompressTextureSource, options?: CompressOptions): Promise<CompressResult>;
 
-declare class WebGPUCompressedTextureLoader extends Loader<Texture> {
+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'. */
@@ -329,4 +329,4 @@ declare function generateMipChain(level0: MipLevel): MipLevel[];
  */
 declare function padToBlockMultiple(level: MipLevel): MipLevel;
 
-export { ASTC4x4Encoder, BC1Encoder, BC5Encoder, BC7Encoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type FeatureProvider, type FormatSelection, type FormatVariant, type MipLevel, type SelectFormatOptions, TextureFormat, type TextureHint, WebGPUCompressedTextureLoader, WebGPUFeature, compressTexture, detectCapabilities, generateMipChain, padToBlockMultiple, selectFormat };
+export { ASTC4x4Encoder, BC1Encoder, BC5Encoder, BC7Encoder, type Capabilities, type CompressOptions, type CompressResult, type CompressTextureSource, type EncodeBytesResult, type EncodeCallOptions, type EncodeResult, Encoder, type EncoderConstructor, type EncoderImageSource, type EncoderOptions, type FeatureProvider, type FormatSelection, type FormatVariant, GputexLoader, type MipLevel, type SelectFormatOptions, TextureFormat, type TextureHint, WebGPUFeature, compressTexture, detectCapabilities, generateMipChain, padToBlockMultiple, selectFormat };

package/dist/index.js

@@ -50,6 +50,25 @@ import {
   SRGBColorSpace,
   RepeatWrapping
 } from "three";
+
+// 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, useWriteTexture) {
+  if (useWriteTexture && source instanceof ImageData) {
+    device.queue.writeTexture({ texture: srcTex }, source.data, { bytesPerRow: width * 4 }, [width, height, 1]);
+  } else {
+    device.queue.copyExternalImageToTexture({ source, flipY }, { texture: srcTex }, [
+      width,
+      height,
+      1
+    ]);
+  }
+}
+
+// src/Encoder.ts
 var Encoder = class {
   /**
    * Subclasses set this to the WebGPU feature string the output texture
@@ -184,9 +203,11 @@ var Encoder = class {
       label: `${this.label}-src`,
       size: [paddedWidth, paddedHeight, 1],
       format: "rgba8unorm",
+      // RENDER_ATTACHMENT is required by copyExternalImageToTexture
+      // (internally a blit) even though we never render into this texture.
       usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
     });
-    device.queue.copyExternalImageToTexture({ source, flipY }, { texture: srcTex }, [width, height, 1]);
+    uploadSourceTexture(device, srcTex, source, width, height, flipY, source instanceof ImageData);
     const dstBuffer = device.createBuffer({
       label: `${this.label}-dst`,
       size: outByteLen,
@@ -608,8 +629,16 @@ async function compressTexture(source, options = {}) {
     encoder = await selection.encoderClass.create();
   }
   try {
+    const needsWriteTexture = needsWriteTextureWorkaround(adapter);
     if (!mipmaps) {
-      const bytes = await encoder.encodeToBytes(bitmap, { flipY });
+      let bytes;
+      if (needsWriteTexture) {
+        const level02 = bitmapToMipLevel(bitmap, flipY);
+        const imageData = mipLevelToImageData(level02);
+        bytes = await encoder.encodeToBytes(imageData);
+      } else {
+        bytes = await encoder.encodeToBytes(bitmap, { flipY });
+      }
       const tex2 = encoder.buildMippedTexture([bytes], { colorSpace });
       return {
         texture: tex2,
@@ -658,9 +687,9 @@ async function compressTexture(source, options = {}) {
   }
 }
 
-// src/CompressedTextureLoader.ts
+// src/GputexLoader.ts
 import { Loader } from "three";
-var WebGPUCompressedTextureLoader = class extends Loader {
+var GputexLoader = class extends Loader {
   /** Format-selection hint. Default 'color'. */
   hint = "color";
   /** Pick the sRGB or linear variant of the chosen format. Default 'srgb'. */
@@ -728,8 +757,8 @@ export {
   BC5Encoder,
   BC7Encoder,
   Encoder,
+  GputexLoader,
   TextureFormat,
-  WebGPUCompressedTextureLoader,
   WebGPUFeature,
   compressTexture,
   detectCapabilities,

package/package.json

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