spark.js⚡️

Real-time texture compression library for the Web.

spark.js is a standalone JavaScript library that exposes a subset of the Spark codecs through a simple and lightweight API.

It enables the use of standard image formats in WebGL and WebGPU applications transcoding them at load-time to native GPU formats like BC7, ASTC, and ETC2, using fast, high-quality GPU encoders.

Try the image viewer, the gltf demo, or checkout the examples:

---

Installation

npm install @ludicon/spark.js

WebGPU Usage Example

import { Spark } from "@ludicon/spark.js"

// Initialize a WebGPU device with required features
const adapter = await navigator.gpu.requestAdapter()
const requiredFeatures = Spark.getRequiredFeatures(adapter)
const device = await adapter.requestDevice({ requiredFeatures })

// Create spark instance for the WebGPU device
const spark = await Spark.create(device)

// Load and encode an image into a GPU texture
const texture = await spark.encodeTexture("image.avif")

The main entry point is spark.encodeTexture(), which loads an image and transcodes it into a compressed GPUTexture using the selected format and options. The example above uses default settings, but encodeTexture supports additional parameters for mipmap generation, sRGB encoding, normal map processing, and more.

If the input image dimensions are not multiples of the block size, it will be resized to meet GPU format requirements. For best results, use images with dimensions that are multiples of 4.

WebGL Usage Example

import { SparkGL } from "@ludicon/spark.js"

// Initialize a WebGL2 context with required extensions
const canvas = document.createElement("canvas")
const gl = canvas.getContext("webgl2", { preserveDrawingBuffer: true })

// Create spark instance for the WebGL2 context
const spark = await SparkGL.create(gl)

// Load and encode an image into a WebGL texture
const texture = await spark.encodeTexture("image.avif").texture

The main difference is the use of the SparkGL class instead of Spark. The API of the spark object is the same, but spark.encodeTexture() returns an object with a texture property with resulting WebGL texture handle.

Development

# Install dependencies
npm install

# Build for production
npm run build

# Development mode with watch
npm run watch

Examples

Live examples are available at: https://ludicon.github.io/spark.js/

To run examples locally with hot reload:

npm run dev

This will open http://localhost:5174/examples/index.thml where you can browse the examples.

Note

Browsers treat http://localhost as a secure context, so HTTPS is not required when testing locally on the same machine. However, to access the dev server from another device you must enable HTTPS for WebGPU features to work.

To run the server with HTTPS, set the environment variable HTTPS to true before starting the server:

HTTPS=true npm run serve

Documentation

For full documentation, see the API reference.

encodeTexture(source, options)

Load an image and encode it to a compressed GPU texture.

Parameters

• source (string | Blob | HTMLImageElement | ImageBitmap | HTMLCanvasElement | OffscreenCanvas | VideoFrame | GPUTexture | WebGLTexture)
  The image to encode.

• options (optional object) Configuration options for encoding:

  • format (string) Desired block compression format. The format can be specified in several different ways:

    • A channel mask indicating the number of channels in your input: "rgba", "rgb", "rg" or "r", the actual format is selected based on the device capabilities.

    • An explicit WebGPU BC, ETC or ASTC format name, or an abbreviated form such as "bc7" or "astc". Note: only 4x4 LDR formats are supported.

    • If you specify auto, the input texture is analyzed to detect the necessary number of channels. This has some overhead, it's always recommended to specify the format through one of the other methods.

    Default: rgb.

  • preferLowQuality Hint for the automatic format selector. When the input format is "rgb" it chooses 8 bit per block formats like "bc1" or "etc2" instead of "bc7" or "astc".

  • mips or generateMipmaps (boolean) Whether to generate mipmaps. Default: false.

  • mipmapFilter (string) The filter to use for mipmap generation. Can be "box" for a simple box filter, or "magic" for a higher-quality 4-tap filter with sharpening properties. Default: "magic".

  • mipsAlphaScale (number[]) Optional array of alpha scale values to apply to each generated mipmap level. The array should contain one value per mipmap level (starting with mip level 1, since level 0 is the base image). Each value multiplies the alpha channel of the corresponding mipmap level. Values greater than 1.0 increase opacity, while values less than 1.0 increase transparency. This is useful for techniques like alpha-tested mipmaps where you want to compensate for alpha loss at lower mip levels. If the array is shorter than the number of mipmap levels, the last value is used for remaining levels. Only applies when mips is true. Default: undefined (no scaling applied).

  • srgb (boolean) Whether to encode the image using an as sRGB format. This also affects mipmap generation. The srgb mode can also be inferred from the format. Default: false.

  • normal (boolean) Whether to interpret the image as a normal map. This affects automatic format selection favoring the use of "bc5" and "eac-rg" formats. Default: false.

  • flipY (boolean) Whether to vertically flip the image before encoding. Default: false.

  • outputTexture (GPUTexture for Spark, result object for SparkGL) A previously-returned texture to reuse as the output, avoiding reallocation when re-encoding into the same shape repeatedly. Reused only when its width, height, mipmap count, and format match the resolved output; otherwise a fresh texture is allocated and returned. Default: undefined.

Returns

• Spark (WebGPU): Promise<GPUTexture> - A promise resolving to the encoded WebGPU texture.
• SparkGL (WebGL2): Promise<Object> - A promise resolving to an object containing the compressed WebGL texture.

Integration with three.js

Using spark.js with three.js is straightforward. You can encode textures with Spark and expose them to three.js as external textures:

// Load and encode texture using spark:
const gpuTexture = await spark.encodeTexture(textureUrl, { srgb: true, flipY: true });

// Wrap the GPUTexture for three.js
const externalTex = new THREE.ExternalTexture(gpuTexture);

// Then use as any other texture:
const material = new THREE.MeshBasicMaterial({ map: externalTex });

To facilitate the use of Spark when loading GLTF assets, import the provided helper:

import { registerSparkLoader } from "@ludicon/spark.js/three-gltf";

Then register Spark with an existing GLTFLoader instance:

const loader = new GLTFLoader()
registerSparkLoader(loader, spark)

After registration, the loader will automatically encode textures with Spark whenever applicable.

To use the Spark plugins with the three.js 3DTilesRenderer, you can pass them to the renderer's GLTFExtensionsPlugin as follows:

import { createSparkPlugins } from "@ludicon/spark.js/three-gltf";

tiles = new TilesRenderer();
tiles.registerPlugin( new GLTFExtensionsPlugin( {
	plugins: createSparkPlugins( spark, { generateMipmaps: false } )
} ) );

License

spark.js is free for non-commercial use, or until your product reaches $100,000 in lifetime revenue.

• The JavaScript code is released under the MIT license.
• Use of the Spark shaders is covered under the spark.js EULA.

See ludicon.com/sparkjs#licensing for the full licensing details.