libktx is a small library of functions for creating and reading KTX (Khronos TeXture) files, version 1 and 2 and instantiating OpenGL® and OpenGL® ES textures and Vulkan images from them. KTX version 2 files can contain images supercompressed with zstd or zlib. They can also contain images in the Basis Universal formats. libktx can deflate and inflate zstd and zlib compressed images, can encode and transcode the Basis Universal formats and can encode ASTC formats.
For information about the KTX format see the formal specification.
- Authors
- Mark Callow, Edgewise Consulting, formerly at HI Corporation
Mátyás Császár and Daniel Rákos, RasterGrid
Wasim Abbas, Arm
Andreas Atteneder, Independent
Georg Kolling, Imagination Technology
Jacob Ström, Ericsson AB
- API Version
- v4.0
- Date
- Fri Mar 14 14:51:46 2025 +0300
Usage Overview
The following ktxTexture
examples work for both KTX and KTX2 textures. The texture type is determined from the file contents.
Reading a KTX file for non-GL and non-Vulkan Use
ktx_size_t offset;
ktx_uint8_t* image;
ktx_uint32_t level, layer, faceSlice;
result = ktxTexture_CreateFromNamedFile("mytex3d.ktx",
&texture);
ktx_bool_t isArray = texture->
isArray;
level = 1; layer = 0; faceSlice = 3;
image = ktxTexture_GetData(texture) + offset;
Declares the public functions and structures of the KTX API.
#define ktxTexture_Destroy(This)
Helper for calling the Destroy virtual method of a ktxTexture.
Definition ktx.h:533
@ KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT
Definition ktx.h:794
#define KTX_error_code
For backward compatibility.
Definition ktx.h:198
#define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset)
Helper for calling the GetImageOffset virtual method of a ktxTexture.
Definition ktx.h:541
Base class representing a texture.
Definition ktx.h:287
ktx_uint32_t baseWidth
Width of the texture's base level.
Definition ktx.h:288
ktx_uint32_t numLevels
Number of mip levels in the texture.
Definition ktx.h:288
ktx_bool_t isArray
Definition ktx.h:288
Creating a GL texture object from a KTX file.
ktx_size_t offset;
ktx_uint8_t* image;
ktx_uint32_t level, layer, faceSlice;
GLuint texture = 0;
GLenum target, glerror;
result = ktxTexture_CreateFromNamedFile("mytex3d.ktx",
KTX_TEXTURE_CREATE_NO_FLAGS,
&kTexture);
glGenTextures(1, &texture);
result = ktxTexture_GLUpload(kTexture, &texture, &target, &glerror);
KTX_API KTX_error_code KTX_APIENTRY ktxLoadOpenGL(PFNGLGETPROCADDRESS pfnGLGetProcAddress)
Load pointers for the GL functions used by the ktxTexture*_GLUpload functions.
Definition gl_funcs.c:216
PFNVOIDFUNCTION(KTX_APIENTRY * PFNGLGETPROCADDRESS)(const char *proc)
typedef of pointer to function for retrieving OpenGL function pointers.
Definition ktx.h:936
Creating a Vulkan image object from a KTX file.
#include <vulkan/vulkan.h>
#include <ktxvulkan.h>
ktx_size_t offset;
ktx_uint8_t* image;
ktx_uint32_t level, layer, faceSlice;
ktxVulkanDeviceInfo_Construct(&vdi, vkctx.gpu, vkctx.device,
vkctx.queue, vkctx.commandPool, nullptr);
ktxresult = ktxTexture_CreateFromNamedFile("mytex3d.ktx",
KTX_TEXTURE_CREATE_NO_FLAGS,
&kTexture);
ktxresult = ktxTexture_VkUploadEx(kTexture, &vdi, &texture,
VK_IMAGE_TILING_OPTIMAL,
VK_IMAGE_USAGE_SAMPLED_BIT,
VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
ktxVulkanDeviceInfo_Destruct(&vdi);
ktxVulkanTexture_Destruct(&texture, vkctx.device, nullptr);
Struct for passing information about the Vulkan device on which to create images to the texture image...
Definition ktxvulkan.h:188
Struct for returning information about the Vulkan texture image created by the ktxTexture_VkUpload* f...
Definition ktxvulkan.h:108
Extracting Metadata
Once a ktxTexture object has been created, metadata can be easily found and extracted. The following can be added to any of the above.
char* pValue;
uint32_t valueLen;
&valueLen, (void**)&pValue))
{
char s, t;
...
}
}
@ KTX_SUCCESS
Definition ktx.h:170
#define KTX_ORIENTATION_KEY
Key string for standard orientation metadata.
Definition ktx.h:124
#define KTX_ORIENTATION2_FMT
Standard KTX 1 format for 2D orientation value.
Definition ktx.h:149
ktxHashList kvDataHead
Head of the hash list of metadata.
Definition ktx.h:288
Writing a KTX or KTX2 file
#include <vkformat_enum.h>
ktx_uint32_t level, layer, faceSlice;
FILE* src;
ktx_size_t srcSize;
createInfo.
vkFormat = VK_FORMAT_R8G8B8_UNORM;
result = ktxTexture2_Create(&createInfo,
&texture);
src =
srcSize =
level = 0;
layer = 0;
faceSlice = 0;
level, layer, faceSlice,
src, srcSize);
#define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)
Helper for calling the SetImageFromMemory virtual method of a ktxTexture.
Definition ktx.h:609
@ KTX_TEXTURE_CREATE_ALLOC_STORAGE
Definition ktx.h:782
#define ktxTexture_WriteToNamedFile(This, dstname)
Helper for calling the WriteToNamedfile virtual method of a ktxTexture.
Definition ktx.h:639
Class representing a KTX version 2 format texture.
Definition ktx.h:706
Structure for passing texture information to ktxTexture1_Create() and ktxTexture2_Create().
Definition ktx.h:747
ktx_uint32_t glInternalformat
Definition ktx.h:748
ktx_uint32_t numFaces
Definition ktx.h:764
ktx_uint32_t numDimensions
Definition ktx.h:759
ktx_uint32_t baseWidth
Definition ktx.h:756
ktx_uint32_t baseDepth
Definition ktx.h:758
ktx_uint32_t numLevels
Definition ktx.h:761
ktx_bool_t isArray
Definition ktx.h:765
ktx_bool_t generateMipmaps
Definition ktx.h:768
ktx_uint32_t vkFormat
Definition ktx.h:751
ktx_uint32_t numLayers
Definition ktx.h:763
ktx_uint32_t baseHeight
Definition ktx.h:757
Modifying a KTX file
ktx_size_t offset;
ktx_uint8_t* image;
ktx_uint32_t level, layer, faceSlice;
result = ktxTexture_CreateFromNamedFile("mytex3d.ktx",
&texture);
ktx_bool_t generateMipmaps
Definition ktx.h:288
Writing a Basis-compressed Universal Texture
Basis compression supports two universal texture formats: BasisLZ/ETC1S and UASTC. The latter gives higher quality at a larger file size. Textures can be compressed to either format using ktxTexture2_CompressBasisEx
as shown in this example.
#include <vkformat_enum.h>
ktx_uint32_t level, layer, faceSlice;
FILE* src;
ktx_size_t srcSize;
createInfo.
vkFormat = VK_FORMAT_R8G8B8A8_UNORM;
result = ktxTexture2_Create(&createInfo,
&texture);
src =
srcSize =
level = 0;
layer = 0;
faceSlice = 0;
level, layer, faceSlice,
src, srcSize);
result = ktxtexture2_CompressBasisEx(texture, ¶ms);
Structure for passing extended parameters to ktxTexture2_CompressBasisEx().
Definition ktx.h:1376
ktx_uint32_t compressionLevel
Definition ktx.h:1395
ktx_uint32_t structSize
Definition ktx.h:1377
ktx_bool_t uastc
Definition ktx.h:1381
There is a shortcut that can be used when compressing to BasisLZ/ETC1S. Remove the declaration and initialization of params
in the previous example and replace ktxtexture2_CompressBasisEx
with
int quality = 0;
result = ktxTexture2_CompressBasis(texture, quality);
Transcoding a BasisLZ/ETC1S or UASTC-compressed Texture
result = ktxTexture_CreateFromNamedFile("mytex3d_basis.ktx2",
KTX_TEXTURE_CREATE_NO_FLAGS,
if (ktxTexture2_NeedsTranscoding(texture)) {
ktx_texture_transcode_fmt_e tf;
vk::PhysicalDeviceFeatures deviceFeatures;
vkctx.gpu.getFeatures(&deviceFeatures);
khr_df_model_e colorModel = ktxTexture2_GetColorModel_e(texture);
if (colorModel == KHR_DF_MODEL_UASTC
&& deviceFeatures.textureCompressionASTC_LDR) {
} else if (colorModel == KHR_DF_MODEL_ETC1S
&& deviceFeatures.textureCompressionETC2) {
} else if (deviceFeatures.textureCompressionASTC_LDR) {
} else if (deviceFeatures.textureCompressionETC2)
else if (deviceFeatures.textureCompressionBC)
else {
message << "Vulkan implementation does not support any available transcode target.";
throw std::runtime_error(message.str());
}
result = ktxTexture2_TranscodeBasis(texture, tf, 0);
}
@ KTX_TTF_ASTC_4x4_RGBA
Definition ktx.h:1590
@ KTX_TTF_BC3_RGBA
Definition ktx.h:1562
@ KTX_TTF_ETC2_RGBA
Definition ktx.h:1552
@ KTX_TTF_ETC
Definition ktx.h:1634
Writing an ASTC-Compressed Texture
#include <vkformat_enum.h>
ktx_uint32_t level, layer, faceSlice;
FILE* src;
ktx_size_t srcSize;
createInfo.
vkFormat = VK_FORMAT_R8G8B8A8_UNORM;
result = ktxTexture2_Create(&createInfo,
&texture);
src =
srcSize =
level = 0;
layer = 0;
faceSlice = 0;
level, layer, faceSlice,
src, srcSize);
params.
mode = KTX_PACK_ASTC_ENCODER_MODE_LDR;
result = ktxtexture2_CompressAstcEx(texture, ¶ms);
@ KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM
Definition ktx.h:1230
Structure for passing extended parameters to ktxTexture_CompressAstc.
Definition ktx.h:1299
ktx_uint32_t threadCount
Definition ktx.h:1310
ktx_uint32_t structSize
Definition ktx.h:1300
ktx_uint32_t blockDimension
Definition ktx.h:1315
ktx_uint32_t mode
Definition ktx.h:1320
ktx_uint32_t qualityLevel
Definition ktx.h:1324
There is a shortcut that can be used when the only params
field you want to modify is the qualityLevel
. Remove the declaration and initialization of params
in the previous example and replace ktxtexture2_CompressAstcEx
with
result = ktxTexture2_CompressAstc(texture, quality);