API Reference

Core Functions

encodeToKTX2

The main function for converting images to KTX2 format.

// Browser
async function encodeToKTX2(
  imageBuffer: Uint8Array | CubeBufferData,
  options?: Partial<IEncodeOptions>
): Promise<Uint8Array>;

// Node.js
async function encodeToKTX2(imageBuffer: Uint8Array, options?: Partial<IEncodeOptions>): Promise<Uint8Array>;

Parameters

• imageBuffer: Encoded image data as a Uint8Array. In browsers, a tuple of exactly six image buffers creates a cubemap in the order [posx, negx, posy, negy, posz, negz].
• options: Optional configuration object (see IEncodeOptions below)

Example

import { encodeToKTX2 } from "ktx2-encoder";

const ktx2Data = await encodeToKTX2(imageBuffer, {
  isUASTC: true,
  generateMipmap: true,
  isNormalMap: false
});

Configuration Options

IEncodeOptions Interface

Complete configuration options for the encoder:

Option	Type	Default	Description
isUASTC	boolean	true	Use UASTC texture format instead of ETC1S
enableDebug	boolean	false	Enable debug output
isYFlip	boolean	false	If true, the source images will be Y flipped before compression
qualityLevel	number	150	Sets the ETC1S encoder's quality level (1-255). Controls file size vs. quality tradeoff
compressionLevel	number	2	Controls encoder performance vs. file size tradeoff for ETC1S files (0-6)
needSupercompression	boolean	true	Use UASTC Zstandard supercompression
uastcLDRQualityLevel	number	1	Controls UASTC LDR quality (0-3); higher values are slower and higher quality
enableRDO	boolean	false	Enable UASTC LDR rate-distortion optimization
rdoQualityLevel	number	1.0	Controls UASTC RDO quality (0.001-10); lower values favor quality
isNormalMap	boolean	false	Optimize compression parameters for normal maps
isPerceptual	boolean	encoder default	Treat input as perceptual/sRGB data; normally true for color textures and false for normal maps
isSetKTX2SRGBTransferFunc	boolean	true	Use the sRGB transfer function in the KTX2 DFD; normally matches isPerceptual
generateMipmap	boolean	true	Generate mipmaps from source images
isKTX2File	boolean	true	Create a KTX2 file instead of a Basis file
isHDR	boolean	false	Enable UASTC HDR encoding
imageType	"hdr" | "exr"	required for HDR	Supported HDR source container type
hdrQualityLevel	number	encoder default	Controls UASTC HDR quality (0-4)
kvData	Record<string, string | Uint8Array>	undefined	Custom key-value metadata for the KTX2 file
outputBufferSize	number	estimated	Initial output buffer capacity in bytes; encoding retries once at twice this size on failure
imageDecoder	Function	browser built-in	Function that decodes an image buffer to RGBA; required in Node.js for non-HDR images
jsUrl	string	undefined	Deprecated and ignored in browsers; the bundled JavaScript module is always used
wasmUrl	string	bundled asset	Browser-only URL overriding the bundled single-threaded WebAssembly module; also used when a useThreads request falls back to single-threaded
threadsWasmUrl	string	bundled asset	Browser-only URL overriding the bundled multithreaded WebAssembly module; used only when useThreads is active on a cross-origin isolated page
useThreads	boolean	false	Browser-only. Opt into multithreaded encoding; requires a cross-origin isolated page, falls back to single-threaded otherwise. Ignored in Node.js
numThreads	number	min(hardwareConcurrency - 1, 8)	Extra worker threads when useThreads is active (total = 1 + numThreads); clamped to [0, 8], 0 disables

Image Decoder Function Type

For Node.js usage, the imageDecoder function should match this signature:

type ImageDecoder = (buffer: Uint8Array) => Promise<{
  width: number;
  height: number;
  data: Uint8Array;
}>;

Examples

Basic Usage

const ktx2Data = await encodeToKTX2(imageBuffer, {
  isUASTC: true,
  generateMipmap: true,
  isNormalMap: false
});

Normal Map Compression

const normalMapData = await encodeToKTX2(normalMapBuffer, {
  isUASTC: true, // Recommended for normal maps
  isNormalMap: true,
  isSetKTX2SRGBTransferFunc: false // Important for normal maps
});

ETC1S with Quality Settings

const etc1sData = await encodeToKTX2(imageBuffer, {
  isUASTC: false,
  qualityLevel: 128,
  compressionLevel: 2
});

Cubemap Encoding

import { encodeToKTX2 } from "ktx2-encoder";

// Load your 6 cubemap face images
Promise.all([
  loadImage("posx.jpg"),
  loadImage("negx.jpg"),
  loadImage("posy.jpg"),
  loadImage("negy.jpg"),
  loadImage("posz.jpg"),
  loadImage("negz.jpg")
]).then((buffers) => {
  // Encode to KTX2 cubemap
  return encodeToKTX2(buffers, {
    isUASTC: true,
    generateMipmap: true,
    qualityLevel: 128
  });
});

Cubemap encoding through the package entry point is currently available in browser builds.

Face Order

The cubemap faces must be provided in this specific order:

• posx: Positive X face (+X)
• negx: Negative X face (-X)
• posy: Positive Y face (+Y)
• negy: Negative Y face (-Y)
• posz: Positive Z face (+Z)
• negz: Negative Z face (-Z)

With Custom Metadata

const ktx2Data = await encodeToKTX2(imageBuffer, {
  kvData: {
    myKey: "myValue",
    customData: new Uint8Array([1, 2, 3])
  }
});