KTX 2.0

edit

KTX 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
Textures1D, 2D and 3D textures, arrays, cube maps and cube map arrays, with their mip levels
Uncompressed formats8-bit and 16-bit UNORM and sRGB, 16-bit and 32-bit floats, the packed formats (R5G6B5, R4G4B4A4, A2B10G10R10, B10G11R11, E5B9G9R9, ...)
Block-compressed formatsBC1 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 UniversalETC1S (BasisLZ supercompression, P-frames of videos included) and UASTC, decoded straight to RGBA
SupercompressionZstandard and ZLIB
MetadataKTXswizzle 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_SFLOAT with rrr1). ASTC UNORM textures decode to RgbaHalf, the default of KTX, or to 8-bit pixels when the file says KTXastcDecodeMode is unorm8.
  • The channels a format lacks are 0, and alpha is 1, as a GPU samples them: an R8 texture loads red. A luminance texture says so with the swizzle rrr1, 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.
  • KTXorientation is 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:

FamilyFormats
UncompressedR8, R8G8, R8G8B8A8, R16, R16G16B16A16, R16G16B16A16_SFLOAT, R32G32B32A32_SFLOAT
BCnBC1 (RGB and RGBA), BC2, BC3, BC4 and BC5 (UNORM and SNORM), BC6H (UFLOAT and SFLOAT), BC7
ETC2 and EACETC2 RGB, RGB with 1-bit alpha and RGBA; EAC R11 and R11G11 (UNORM and SNORM)
ASTCLDR 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.

FormatUse it forSolid colors
ETC2 RGB, RGBAColors for OpenGL ES and Vulkan on mobile GPUsRGB within 2 (one modifier for the three channels); alpha exact
EAC R11, RG11One or two channels: masks, height maps, normal mapsExact
ASTC 4×4Colors when quality matters more than sizeExact (void-extent blocks)
ASTC 6×6 to 12×12Colors at a smaller size: each larger block stores fewer bits per texelExact

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.