KTX 2.0
editKTX 2.0 files (.ktx2, Khronos Texture) hold the textures of GPU applications and glTF models: images of one to three dimensions, arrays of them, cube maps and their mip levels, uncompressed or block-compressed, and often supercompressed. The library reads them: every level, layer, face and depth slice is an entry of an ImageCollection, and Image.Load gives the base level of the first face of the first layer. Ktx2Encoder writes them, with block compressors of its own for BCn, ETC2, EAC and ASTC.
What is read
| Reading | |
|---|---|
| Textures | 1D, 2D and 3D textures, arrays, cube maps and cube map arrays, with their mip levels |
| Uncompressed formats | 8-bit and 16-bit UNORM and sRGB, 16-bit and 32-bit floats, the packed formats (R5G6B5, R4G4B4A4, A2B10G10R10, B10G11R11, E5B9G9R9, ...) |
| Block-compressed formats | BC1 to BC7 (S3TC, RGTC and BPTC, with the block decoders of DDS), ETC2 (RGB, punchthrough alpha, RGBA), EAC (R11 and RG11, unsigned and signed), ASTC 2D of every block size (sRGB, UNORM, HDR) |
| Basis Universal | ETC1S (BasisLZ supercompression, P-frames of videos included) and UASTC, decoded straight to RGBA |
| Supercompression | Zstandard and ZLIB |
| Metadata | KTXswizzle applied, KTXorientation reported as the orientation, KTXanimData as an animation, the color labels of the data format descriptor, and every key reported |
PVRTC blocks, the YCbCr formats, 3D ASTC blocks and premultiplied alpha are rejected with an UnsupportedImageFeatureException. See Limitations.
Load a texture and its levels
public static IReadOnlyList<string> ExportKtx2Levels(string ktx2Path, string outputDirectory)
{
// Image.Load decodes the base level of the first face of the first layer (or the frames of an animation)
using (var texture = Image.Load(ktx2Path))
{
texture.Save(Path.Combine(outputDirectory, "base.png"));
}
// Every level, layer, face and depth slice is an entry of a collection, decoded on demand
var files = new List<string>();
using var collection = ImageCollection.Load(ktx2Path);
foreach (var entry in collection.Entries)
{
if (entry.TextureSurface is { ArrayIndex: 0, Face: null or CubeMapFace.PositiveX, DepthSlice: 0, MipLevel: var level })
{
using var image = entry.Decode();
var path = Path.Combine(outputDirectory, $"level-{level}.png");
image.Save(path);
files.Add(path);
}
}
return files;
}The entries of the collection are ordered by layer, then face, then level, then depth slice, and TextureSurface tells which one an entry is: its MipLevel, ArrayIndex, Face (a CubeMapFace of a cube map, null otherwise) and DepthSlice. Loading the collection reads the structure of the file only; the texels of an entry are read when it is decoded. ImageInfo.CollectionEntryCount gives the number of entries without loading a collection. An array texture with KTXanimData loads as an animation of its layers, with the duration and the loop count of the key.
Pixels and colors
- A format decodes to the pixel format that holds its samples: 8-bit formats, ETC2, ETC1S, UASTC and ASTC sRGB to 8-bit pixels, 16-bit formats and EAC to 16-bit pixels, floats and ASTC HDR to RgbaHalf or RgbaFloat (GrayHalf, LaHalf, GrayFloat or LaFloat when the swizzle makes them gray, such as
R16_SFLOATwithrrr1). ASTC UNORM textures decode to RgbaHalf, the default of KTX, or to 8-bit pixels when the file saysKTXastcDecodeModeisunorm8. - The channels a format lacks are 0, and alpha is 1, as a GPU samples them: an
R8texture loads red. A luminance texture says so with the swizzlerrr1, which the library applies, and loads gray. - The transfer function of the data format descriptor is the color label: sRGB formats are labeled sRGB, and UNORM formats usually linear (ColorTransferFunction.Linear). Other primaries are a CICP description.
KTXorientationis reported as ImageMetadata.Orientation:ru(the first row is the bottom one) is ExifOrientation.BottomLeft. Only AutoOrient applies it.- ImageMetadata.Ktx2Header reports the format, the sizes and the key/value data of the file.
Write a texture
public static void SaveKtx2Texture(string inputPath, string outputPath)
{
// ASTC 6x6 blocks (3.56 bits per texel); an image labeled sRGB (the default) gives ASTC_6x6_SRGB_BLOCK
using var image = Image.Load(inputPath);
image.Save(outputPath, new Ktx2Encoder
{
TextureFormat = Ktx2TextureFormat.Astc6x6,
Quality = TextureCompressionQuality.Fast,
GenerateMipmaps = true,
Supercompression = Ktx2Supercompression.Zlib,
});
}Save with a .ktx2 path gives a Ktx2Encoder with its default settings: the uncompressed format that keeps the pixels exactly (R8G8B8A8 for 8-bit pixels, R8 or R16 for gray, R16G16B16A16 for 16-bit pixels, the SFLOAT formats for floating-point pixels). TextureFormat chooses another Ktx2TextureFormat:
| Family | Formats |
|---|---|
| Uncompressed | R8, R8G8, R8G8B8A8, R16, R16G16B16A16, R16G16B16A16_SFLOAT, R32G32B32A32_SFLOAT |
| BCn | BC1 (RGB and RGBA), BC2, BC3, BC4 and BC5 (UNORM and SNORM), BC6H (UFLOAT and SFLOAT), BC7 |
| ETC2 and EAC | ETC2 RGB, RGB with 1-bit alpha and RGBA; EAC R11 and R11G11 (UNORM and SNORM) |
| ASTC | LDR blocks of every 2D size, from 4×4 to 12×12 |
A member names a family of VkFormat values: an image labeled linear (ColorTransferFunction.Linear) is written _UNORM with the linear transfer function, any other one _SRGB. The formats without an _SRGB variant carry the transfer function of the image in their data format descriptor. A one-channel format is written with the swizzle rrr1, so that it is read as gray. The descriptor has the samples and bounds that KTX-Software writes, and the primaries of the CICP description of the image when KTX has them; the orientation is written as KTXorientation.
The other settings are those of DdsEncoder (see DDS): Quality, GenerateMipmaps, AllowBitDepthReduction and AllowChannelReduction, and Supercompression compresses each level with ZLIB. Cube maps, array textures and arrays of cube maps are written from a collection of texture surfaces, as for DDS. The levels are stored from the smallest, as the specification orders them.
The block compressors are deterministic: the same pixels and settings give the same bytes on every platform.
| Format | Use it for | Solid colors |
|---|---|---|
| ETC2 RGB, RGBA | Colors for OpenGL ES and Vulkan on mobile GPUs | RGB within 2 (one modifier for the three channels); alpha exact |
| EAC R11, RG11 | One or two channels: masks, height maps, normal maps | Exact |
| ASTC 4×4 | Colors when quality matters more than size | Exact (void-extent blocks) |
| ASTC 6×6 to 12×12 | Colors at a smaller size: each larger block stores fewer bits per texel | Exact |
ASTC loses most on sharp edges between three colors or more in a block (its partitions share one endpoint mode), where Thorough gains the most. Use Thorough for assets built once and shipped, and Fast for previews and textures generated at run time. BCn reaches what it reaches in DDS (see DDS). ETC2 Thorough adds the T and H modes, which hold two hues in a block where the Fast level smears sharp edges. ASTC HDR blocks, 3D blocks and Basis Universal (ETC1S, UASTC) are read but not written.
Pitfalls
- UNORM textures are labeled linear, which PNG, JPEG and most formats cannot store: saving one follows MetadataHandling, which rejects it by default. A normal map or another data texture is not a color: set its TransferFunction to Srgb to save the samples as they are, or convert real colors with ConvertColorProfile.
- A UASTC texture with the sRGB transfer function is decoded as an ASTC sRGB decoder decodes it (section 25.7.2.8 of the Khronos Data Format Specification). KTX-Software and basisu decode UASTC with the linear expansion whatever the transfer function, so their samples can differ by 1.
- Illegal ASTC blocks, which the specification decodes to magenta, are rejected with an InvalidImageContentException, and so are HDR blocks in an LDR texture.
- Image.OpenReader rejects KTX 2.0: use ImageCollection or Image.Load. The asynchronous loads buffer the file.
- There is no lenient decoding for KTX 2.0: a truncated or malformed file is rejected.
- Writing: the floating-point and signed formats store linear light, BC6H finite halves, and the signed formats values in [-1, 1]; other samples are rejected, never clamped. Zstandard is read but not written.