GPUtex

Runtime GPU texture compression via WebGPU compute shaders. Feed it a PNG/JPG/WebP/AVIF and get back a GPU-compressed texture (BC7, BC5, ASTC 4x4, or BC1) ready for Three.js or React Three Fiber.

⚠️: This is 100% vibe-coded. The code is completely unreviewed, under-tested, it will probably crash on many devices, and this library is very likely to go unmaintained. Do not use for anything important.

Install

npm install gputex
# or
pnpm add gputex
# or
bun add gputex

three is a peer dependency (>=0.180).

Formats

| Format | Bytes / 4x4 block | Use case | | ------------ | ----------------- | --------------------------------------------------------- | | BC7 | 16 (8 bpp) | Color / RGBA on desktop (texture-compression-bc) | | BC5 | 16 (8 bpp) | Normal maps — RG only (texture-compression-bc) | | ASTC 4x4 | 16 (8 bpp) | Color / RGBA on mobile / iOS (texture-compression-astc) | | BC1 | 8 (4 bpp) | Legacy (never auto-selected) |

Format selection is automatic: BC7/BC5 on desktop, ASTC on mobile, uncompressed RGBA8 fallback otherwise.

Usage

compressTexture — direct API

import { compressTexture } from 'gputex'

const { texture, format } = await compressTexture('/cobblestone.avif', {
  hint: 'color', // 'color' | 'colorWithAlpha' | 'normal'
  colorSpace: 'srgb',
  mipmaps: true,
})

material.map = texture

GputexLoader — Three.js Loader

import { GputexLoader } from 'gputex'

const loader = new GputexLoader()
loader.hint = 'normal'
loader.mipmaps = true
const normalMap = await loader.loadAsync('/brick_normal.png')
material.normalMap = normalMap

React Three Fiber

The GputexLoader works with R3F's useLoader:

import { useLoader } from '@react-three/fiber'
import { GputexLoader } from 'gputex'

function Scene() {
  const texture = useLoader(GputexLoader, '/cobblestone.avif', loader => {
    loader.hint = 'color'
    loader.colorSpace = 'srgb'
    loader.mipmaps = true
  })

  return (
    <mesh>
      <sphereGeometry args={[1, 64, 32]} />
      <meshStandardMaterial map={texture} />
    </mesh>
  )
}

For a reusable hook with metadata access:

import { useLayoutEffect } from 'react'
import { useLoader } from '@react-three/fiber'
import { GputexLoader } from 'gputex'
import type { TextureHint } from 'gputex'

function useGputex(url: string, options?: { hint?: TextureHint; colorSpace?: 'srgb' | 'linear'; mipmaps?: boolean }) {
  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
  })

  return texture
}

// Preload textures outside of components
useGputex.preload = (
  url: string,
  options?: { hint?: TextureHint; colorSpace?: 'srgb' | 'linear'; mipmaps?: boolean },
) => {
  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
  })
}

Usage:

// Preload outside the component tree
useGputex.preload('/cobblestone.avif', { hint: 'color', colorSpace: 'srgb', mipmaps: true })

function Scene() {
  const texture = useGputex('/cobblestone.avif', { hint: 'color', colorSpace: 'srgb', mipmaps: true })

  return (
    <mesh>
      <sphereGeometry args={[1, 64, 32]} />
      <meshStandardMaterial map={texture} />
    </mesh>
  )
}

Low-level encoders

Individual encoder classes are exported for direct control:

import { BC7Encoder, BC5Encoder, ASTC4x4Encoder, BC1Encoder } from 'gputex'

const encoder = await BC7Encoder.create()
const { data, width, height } = await encoder.encodeToBytes(imageBitmap)
encoder.destroy()

Options

compressTexture options

| Option | Type | Default | Description | | ------------ | -------------------- | --------- | ------------------------------------------------------- | | hint | TextureHint | 'color' | 'color', 'colorWithAlpha', or 'normal' | | colorSpace | 'srgb' \| 'linear' | 'srgb' | Use the sRGB or linear variant of the chosen format | | flipY | boolean | true | Flip vertically (matches Three.js convention) | | mipmaps | boolean | false | Generate full mip chain down to 1x1 | | device | GPUDevice | — | Reuse an existing WebGPU device instead of creating one |

Requirements

• A browser with WebGPU support
• 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, 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.