API Reference

Core Functions

encodeToKTX2

The main function for converting images to KTX2 format.

async function encodeToKTX2(
  imageBuffer: Uint8Array | Uint8Array[],
  options?: Partial<IEncodeOptions>
): Promise<Uint8Array>;

Parameters

• imageBuffer: Raw image data as Uint8Array / Array of exactly 6 image buffers for each cubemap face 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	-1(unused)	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	false	Use UASTC Zstandard supercompression
isNormalMap	boolean	false	Optimize compression parameters for normal maps
isSetKTX2SRGBTransferFunc	boolean	false	Input source is sRGB. Should match the "perceptual" setting
generateMipmap	boolean	false	Generate mipmaps from source images
isKTX2File	boolean	false	Create .KTX2 files instead of .basis files
kvData	Record<string, string | Uint8Array>	{}	Custom key-value metadata for the KTX2 file
type	SourceType	-	Type of input source (RAW = 0, PNG = 1)
imageDecoder	Function	undefined	Function to decode compressed image buffer to RGBA (Required for Node.js)
jsUrl	string	undefined	URL to the JavaScript module
wasmUrl	string	undefined	URL to the WebAssembly module

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;
}>;

Source Type Enum

enum SourceType {
  RAW = 0,
  PNG = 1
}

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 { encode } 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 encode(buffers, {
    isUASTC: true,
    generateMipmap: true,
    qualityLevel: 128
  });
});

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])
  }
});