libktx Reference 4.3.1
Libraries and tools to create and read KTX image texture files.
Loading...
Searching...
No Matches
ktx.h File Reference

Declares the public functions and structures of the KTX API. More...

#include <limits.h>
#include <stdio.h>
#include <stdbool.h>
#include <sys/types.h>
#include <KHR/khr_df.h>
#include <stdint.h>

Data Structures

struct  ktxOrientation
 Struct describing the logical orientation of an image. More...
 
class  ktxTexture
 Base class representing a texture. More...
 
struct  ktxTexture_vtbl
 Table of virtual ktxTexture methods. More...
 
class  ktxTexture1
 Class representing a KTX version 1 format texture. More...
 
class  ktxTexture2
 Class representing a KTX version 2 format texture. More...
 
struct  ktxTextureCreateInfo
 Structure for passing texture information to ktxTexture1_Create() and ktxTexture2_Create(). More...
 
struct  ktxStream
 Interface of ktxStream. More...
 
struct  ktxAstcParams
 Structure for passing extended parameters to ktxTexture_CompressAstc. More...
 
struct  ktxBasisParams
 Structure for passing extended parameters to ktxTexture2_CompressBasisEx(). More...
 

Macros

#define KTX_ANIMDATA_KEY   "KTXanimData"
 Key string for standard writer metadata.
 
#define KTX_ORIENTATION_KEY   "KTXorientation"
 Key string for standard orientation metadata.
 
#define KTX_SWIZZLE_KEY   "KTXswizzle"
 Key string for standard swizzle metadata.
 
#define KTX_WRITER_KEY   "KTXwriter"
 Key string for standard writer metadata.
 
#define KTX_WRITER_SCPARAMS_KEY   "KTXwriterScParams"
 Key string for standard writer supercompression parameter metadata.
 
#define KTX_ORIENTATION1_FMT   "S=%c"
 Standard KTX 1 format for 1D orientation value.
 
#define KTX_ORIENTATION2_FMT   "S=%c,T=%c"
 Standard KTX 1 format for 2D orientation value.
 
#define KTX_ORIENTATION3_FMT   "S=%c,T=%c,R=%c"
 Standard KTX 1 format for 3D orientation value.
 
#define KTX_GL_UNPACK_ALIGNMENT   4
 Required unpack alignment.
 
#define KTX_error_code   ktx_error_code_e
 For backward compatibility.
 
#define ktxTexture_Destroy(This)   (This)->vtbl->Destroy(This)
 Helper for calling the Destroy virtual method of a ktxTexture.
 
#define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset)    (This)->vtbl->GetImageOffset(This, level, layer, faceSlice, pOffset)
 Helper for calling the GetImageOffset virtual method of a ktxTexture.
 
#define ktxTexture_GetDataSizeUncompressed(This)    (This)->vtbl->GetDataSizeUncompressed(This)
 Helper for calling the GetDataSizeUncompressed virtual method of a ktxTexture.
 
#define ktxTexture_GetImageSize(This, level)    (This)->vtbl->GetImageSize(This, level)
 Helper for calling the GetImageSize virtual method of a ktxTexture.
 
#define ktxTexture_IterateLevels(This, iterCb, userdata)    (This)->vtbl->IterateLevels(This, iterCb, userdata)
 Helper for calling the IterateLevels virtual method of a ktxTexture.
 
#define ktxTexture_IterateLoadLevelFaces(This, iterCb, userdata)    (This)->vtbl->IterateLoadLevelFaces(This, iterCb, userdata)
 Helper for calling the IterateLoadLevelFaces virtual method of a ktxTexture.
 
#define ktxTexture_LoadImageData(This, pBuffer, bufSize)    (This)->vtbl->LoadImageData(This, pBuffer, bufSize)
 Helper for calling the LoadImageData virtual method of a ktxTexture.
 
#define ktxTexture_NeedsTranscoding(This)   (This)->vtbl->NeedsTranscoding(This)
 Helper for calling the NeedsTranscoding virtual method of a ktxTexture.
 
#define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)    (This)->vtbl->SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)
 Helper for calling the SetImageFromMemory virtual method of a ktxTexture.
 
#define ktxTexture_SetImageFromStdioStream(This, level, layer, faceSlice, src, srcSize)
 Helper for calling the SetImageFromStdioStream virtual method of a ktxTexture.
 
#define ktxTexture_WriteToStdioStream(This, dstsstr)    (This)->vtbl->WriteToStdioStream(This, dstsstr)
 Helper for calling the WriteToStdioStream virtual method of a ktxTexture.
 
#define ktxTexture_WriteToNamedFile(This, dstname)    (This)->vtbl->WriteToNamedFile(This, dstname)
 Helper for calling the WriteToNamedfile virtual method of a ktxTexture.
 
#define ktxTexture_WriteToMemory(This, ppDstBytes, pSize)    (This)->vtbl->WriteToMemory(This, ppDstBytes, pSize)
 Helper for calling the WriteToMemory virtual method of a ktxTexture.
 
#define ktxTexture_WriteToStream(This, dststr)    (This)->vtbl->WriteToStream(This, dststr)
 Helper for calling the WriteToStream virtual method of a ktxTexture.
 
#define ktxTexture(t)   ((ktxTexture*)t)
 Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.
 
#define ktx_texture_transcode_fmt_e   ktx_transcode_fmt_e
 
#define ktx_texture_decode_flags   ktx_transcode_flag_bits
 
#define ktxTexture_GetSize   ktxTexture_GetDatasize
 

Typedefs

typedef enum ktx_error_code_e ktx_error_code_e
 Error codes returned by library functions.
 
typedef enum ktx_error_code_e ktxResult
 Result codes returned by library functions.
 
typedef enum ktxSupercmpScheme ktxSupercmpScheme
 Enumerators identifying the supercompression scheme.
 
typedef KTX_error_code(* ktxStream_read) (ktxStream *str, void *dst, const ktx_size_t count)
 type for a pointer to a stream reading function
 
typedef KTX_error_code(* ktxStream_skip) (ktxStream *str, const ktx_size_t count)
 type for a pointer to a stream skipping function
 
typedef KTX_error_code(* ktxStream_write) (ktxStream *str, const void *src, const ktx_size_t size, const ktx_size_t count)
 type for a pointer to a stream writing function
 
typedef KTX_error_code(* ktxStream_getpos) (ktxStream *str, ktx_off_t *const offset)
 type for a pointer to a stream position query function
 
typedef KTX_error_code(* ktxStream_setpos) (ktxStream *str, const ktx_off_t offset)
 type for a pointer to a stream position query function
 
typedef KTX_error_code(* ktxStream_getsize) (ktxStream *str, ktx_size_t *const size)
 type for a pointer to a stream size query function
 
typedef void(* ktxStream_destruct) (ktxStream *str)
 Destruct a stream.
 
typedef enum ktx_pack_uastc_flag_bits_e ktx_pack_uastc_flag_bits_e
 Flags specifiying UASTC encoding options.
 
typedef enum ktx_pack_astc_quality_levels_e ktx_pack_astc_quality_levels_e
 Options specifiying ASTC encoding quality levels.
 
typedef enum ktx_pack_astc_block_dimension_e ktx_pack_astc_block_dimension_e
 Options specifiying ASTC encoding block dimensions.
 
typedef enum ktx_pack_astc_encoder_mode_e ktx_pack_astc_encoder_mode_e
 Options specifying ASTC encoder profile mode This and function is used later to derive the profile.
 
typedef struct ktxAstcParams ktxAstcParams
 Structure for passing extended parameters to ktxTexture_CompressAstc.
 
typedef struct ktxBasisParams ktxBasisParams
 Structure for passing extended parameters to ktxTexture2_CompressBasisEx().
 
typedef enum ktx_transcode_fmt_e ktx_transcode_fmt_e
 Enumerators for specifying the transcode target format.
 
typedef enum ktx_transcode_flag_bits_e ktx_transcode_flag_bits_e
 Flags guiding transcoding of Basis Universal compressed textures.
 

Enumerations

enum  ktx_error_code_e {
  KTX_SUCCESS = 0 , KTX_FILE_DATA_ERROR , KTX_FILE_ISPIPE , KTX_FILE_OPEN_FAILED ,
  KTX_FILE_OVERFLOW , KTX_FILE_READ_ERROR , KTX_FILE_SEEK_ERROR , KTX_FILE_UNEXPECTED_EOF ,
  KTX_FILE_WRITE_ERROR , KTX_GL_ERROR , KTX_INVALID_OPERATION , KTX_INVALID_VALUE ,
  KTX_NOT_FOUND , KTX_OUT_OF_MEMORY , KTX_TRANSCODE_FAILED , KTX_UNKNOWN_FILE_FORMAT ,
  KTX_UNSUPPORTED_TEXTURE_TYPE , KTX_UNSUPPORTED_FEATURE , KTX_LIBRARY_NOT_LINKED , KTX_DECOMPRESS_LENGTH_ERROR ,
  KTX_DECOMPRESS_CHECKSUM_ERROR , KTX_ERROR_MAX_ENUM = KTX_DECOMPRESS_CHECKSUM_ERROR
}
 Error codes returned by library functions. More...
 
enum  ktxSupercmpScheme {
  KTX_SS_NONE = 0 , KTX_SS_BASIS_LZ = 1 , KTX_SS_ZSTD = 2 , KTX_SS_ZLIB = 3 ,
  KTX_SS_BEGIN_RANGE = KTX_SS_NONE , KTX_SS_END_RANGE = KTX_SS_ZLIB , KTX_SS_BEGIN_VENDOR_RANGE = 0x10000 , KTX_SS_END_VENDOR_RANGE = 0x1ffff ,
  KTX_SS_BEGIN_RESERVED = 0x20000 , KTX_SUPERCOMPRESSION_BASIS = KTX_SS_BASIS_LZ , KTX_SUPERCOMPRESSION_ZSTD = KTX_SS_ZSTD
}
 Enumerators identifying the supercompression scheme. More...
 
enum  ktx_pack_uastc_flag_bits_e {
  KTX_PACK_UASTC_LEVEL_FASTEST = 0 , KTX_PACK_UASTC_LEVEL_FASTER = 1 , KTX_PACK_UASTC_LEVEL_DEFAULT = 2 , KTX_PACK_UASTC_LEVEL_SLOWER = 3 ,
  KTX_PACK_UASTC_LEVEL_VERYSLOW = 4 , KTX_PACK_UASTC_MAX_LEVEL = KTX_PACK_UASTC_LEVEL_VERYSLOW , KTX_PACK_UASTC_LEVEL_MASK = 0xF , KTX_PACK_UASTC_FAVOR_UASTC_ERROR = 8 ,
  KTX_PACK_UASTC_FAVOR_BC7_ERROR = 16 , KTX_PACK_UASTC_ETC1_FASTER_HINTS = 64 , KTX_PACK_UASTC_ETC1_FASTEST_HINTS = 128 , KTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL = 256
}
 Flags specifiying UASTC encoding options. More...
 
enum  ktx_pack_astc_quality_levels_e {
  KTX_PACK_ASTC_QUALITY_LEVEL_FASTEST = 0 , KTX_PACK_ASTC_QUALITY_LEVEL_FAST = 10 , KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM = 60 , KTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH = 98 ,
  KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE = 100 , KTX_PACK_ASTC_QUALITY_LEVEL_MAX = KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE
}
 Options specifiying ASTC encoding quality levels. More...
 
enum  ktx_pack_astc_block_dimension_e { }
 Options specifiying ASTC encoding block dimensions. More...
 
enum  ktx_pack_astc_encoder_mode_e
 Options specifying ASTC encoder profile mode This and function is used later to derive the profile.
 
enum  ktx_transcode_fmt_e {
  KTX_TTF_ETC1_RGB = 0 , KTX_TTF_ETC2_RGBA = 1 , KTX_TTF_BC1_RGB = 2 , KTX_TTF_BC3_RGBA = 3 ,
  KTX_TTF_BC4_R = 4 , KTX_TTF_BC5_RG = 5 , KTX_TTF_BC7_RGBA = 6 , KTX_TTF_PVRTC1_4_RGB = 8 ,
  KTX_TTF_PVRTC1_4_RGBA = 9 , KTX_TTF_ASTC_4x4_RGBA = 10 , KTX_TTF_PVRTC2_4_RGB = 18 , KTX_TTF_PVRTC2_4_RGBA = 19 ,
  KTX_TTF_ETC2_EAC_R11 = 20 , KTX_TTF_ETC2_EAC_RG11 = 21 , KTX_TTF_RGBA32 = 13 , KTX_TTF_RGB565 = 14 ,
  KTX_TTF_BGR565 = 15 , KTX_TTF_RGBA4444 = 16 , KTX_TTF_ETC = 22 , KTX_TTF_BC1_OR_3 = 23 ,
  KTX_TTF_NOSELECTION = 0x7fffffff , KTX_TF_ETC1 = KTX_TTF_ETC1_RGB , KTX_TF_ETC2 = KTX_TTF_ETC , KTX_TF_BC1 = KTX_TTF_BC1_RGB ,
  KTX_TF_BC3 = KTX_TTF_BC3_RGBA , KTX_TF_BC4 = KTX_TTF_BC4_R , KTX_TF_BC5 = KTX_TTF_BC5_RG , KTX_TTF_BC7_M6_RGB = KTX_TTF_BC7_RGBA ,
  KTX_TTF_BC7_M5_RGBA = KTX_TTF_BC7_RGBA , KTX_TF_BC7_M6_OPAQUE_ONLY = KTX_TTF_BC7_RGBA , KTX_TF_PVRTC1_4_OPAQUE_ONLY = KTX_TTF_PVRTC1_4_RGB
}
 Enumerators for specifying the transcode target format. More...
 
enum  ktx_transcode_flag_bits_e { KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 = 2 , KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS = 4 , KTX_TF_HIGH_QUALITY = 32 }
 Flags guiding transcoding of Basis Universal compressed textures. More...
 

Functions

KTX_API const char *KTX_APIENTRY ktxErrorString (KTX_error_code error)
 Return a string corresponding to a KTX error code.
 
KTX_API const char *KTX_APIENTRY ktxSupercompressionSchemeString (ktxSupercmpScheme scheme)
 Return a string corresponding to a supercompressionScheme enumeration.
 
KTX_API const char *KTX_APIENTRY ktxTranscodeFormatString (ktx_transcode_fmt_e format)
 Return a string corresponding to a transcode format enumeration.
 

Detailed Description

Declares the public functions and structures of the KTX API.

Author
Mark Callow, Edgewise Consulting and while at HI Corporation
Based on original work by Georg Kolling, Imagination Technology

API Version
v4.0

Macro Definition Documentation

◆ KTX_error_code

#define KTX_error_code   ktx_error_code_e

For backward compatibility.

Deprecated:
Examples
glloader.c, and vkload.cpp.

◆ ktx_texture_decode_flags

#define ktx_texture_decode_flags   ktx_transcode_flag_bits
Deprecated:
Will be dropped before V4 release.

◆ ktx_texture_transcode_fmt_e

#define ktx_texture_transcode_fmt_e   ktx_transcode_fmt_e
Deprecated:
Will be dropped before V4 release.

◆ ktxTexture

#define ktxTexture (   t)    ((ktxTexture*)t)

Helper for casting ktxTexture1 and ktxTexture2 to ktxTexture.

Use with caution.

Examples
glloader.c.

◆ ktxTexture_Destroy

#define ktxTexture_Destroy (   This)    (This)->vtbl->Destroy(This)

Helper for calling the Destroy virtual method of a ktxTexture.

Destroy a ktxTexture2 object.

This frees the memory associated with the texture contents and the memory of the ktxTexture2 object. This does not delete any OpenGL or Vulkan texture objects created by ktxTexture2_GLUpload or ktxTexture2_VkUpload.

Parameters
[in]Thispointer to the ktxTexture2 object to destroy
Examples
vkload.cpp.

◆ ktxTexture_GetDataSizeUncompressed

#define ktxTexture_GetDataSizeUncompressed (   This)     (This)->vtbl->GetDataSizeUncompressed(This)

Helper for calling the GetDataSizeUncompressed virtual method of a ktxTexture.

For a ktxTexture1 this will always return the value of This->dataSize.

If supercompressionScheme == KTX_SS_NONE or KTX_SS_BASIS_LZ, returns the value of This->dataSize else if supercompressionScheme == KTX_SS_ZSTD or KTX_SS_ZLIB, it returns the sum of the uncompressed sizes of each mip level plus space for the level padding. With no supercompression the data size and uncompressed data size are the same. For Basis supercompression the uncompressed size cannot be known until the data is transcoded so the compressed size is returned.

Parameters
[in]Thispointer to the ktxTexture1 object of interest.

◆ ktxTexture_GetImageOffset

#define ktxTexture_GetImageOffset (   This,
  level,
  layer,
  faceSlice,
  pOffset 
)     (This)->vtbl->GetImageOffset(This, level, layer, faceSlice, pOffset)

Helper for calling the GetImageOffset virtual method of a ktxTexture.

Find the offset of an image within a ktxTexture's image data.

As there is no such thing as a 3D cubemap we make the 3rd location parameter do double duty. Only works for non-supercompressed textures as there is no way to tell where an image is for a supercompressed one.

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in]levelmip level of the image.
[in]layerarray layer of the image.
[in]faceSlicecube map face or depth slice of the image.
[in,out]pOffsetpointer to location to store the offset.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_OPERATIONlevel, layer or faceSlice exceed the dimensions of the texture.
KTX_INVALID_OPERATIONTexture is supercompressed.
KTX_INVALID_VALIDThis is NULL.

◆ ktxTexture_GetImageSize

#define ktxTexture_GetImageSize (   This,
  level 
)     (This)->vtbl->GetImageSize(This, level)

Helper for calling the GetImageSize virtual method of a ktxTexture.

Calculate & return the size in bytes of an image at the specified mip level.

For arrays, this is the size of a layer, for cubemaps, the size of a face and for 3D textures, the size of a depth slice.

The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT.

Parameters
[in]Thispointer to the ktxTexture2 object of interest.
[in]levellevel of interest. *

◆ ktxTexture_GetSize

#define ktxTexture_GetSize   ktxTexture_GetDatasize
Deprecated:
Will be dropped before V4 release.

◆ ktxTexture_IterateLevels

#define ktxTexture_IterateLevels (   This,
  iterCb,
  userdata 
)     (This)->vtbl->IterateLevels(This, iterCb, userdata)

Helper for calling the IterateLevels virtual method of a ktxTexture.

Iterate over the mip levels in a ktxTexture2 object.

This is almost identical to ktxTexture_IterateLevelFaces(). The difference is that the blocks of image data for non-array cube maps include all faces of a mip level.

This function works even if This->pData == 0 so it can be used to obtain offsets and sizes for each level by callers who have loaded the data externally.

Intended for use only when supercompressionScheme == SUPERCOMPRESSION_NONE.

Parameters
[in]Thishandle of the ktxTexture opened on the data.
[in,out]iterCbthe address of a callback function which is called with the data for each image block.
[in,out]userdatathe address of application-specific data which is passed to the callback along with the image data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error. The following are returned directly by this function. iterCb may return these for other causes or may return additional errors.
Exceptions
KTX_FILE_DATA_ERRORMip level sizes are increasing not decreasing
KTX_INVALID_OPERATIONsupercompressionScheme != SUPERCOMPRESSION_NONE.
KTX_INVALID_VALUEThis is NULL or iterCb is NULL.

◆ ktxTexture_IterateLoadLevelFaces

#define ktxTexture_IterateLoadLevelFaces (   This,
  iterCb,
  userdata 
)     (This)->vtbl->IterateLoadLevelFaces(This, iterCb, userdata)

Helper for calling the IterateLoadLevelFaces virtual method of a ktxTexture.

Iterate over the images in a ktxTexture2 object while loading the image data.

This operates similarly to ktxTexture_IterateLevelFaces() except that it loads the images from the ktxTexture2's source to a temporary buffer while iterating. If supercompressionScheme == KTX_SS_ZSTD or KTX_SS_ZLIB, it will inflate the data before passing it to the callback. The callback function must copy the image data if it wishes to preserve it as the temporary buffer is reused for each level and is freed when this function exits.

This function is helpful for reducing memory usage when uploading the data to a graphics API.

Intended for use only when supercompressionScheme == KTX_SS_NONE, KTX_SS_ZSTD or KTX_SS_ZLIB. As there is no access to the ktxTexture's data on conclusion of this function, destroying the texture on completion is recommended.

Parameters
[in]Thispointer to the ktxTexture2 object of interest.
[in,out]iterCbthe address of a callback function which is called with the data for each image.
[in,out]userdatathe address of application-specific data which is passed to the callback along with the image data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error. The following are returned directly by this function. iterCb may return these for other causes or may return additional errors.
Exceptions
KTX_FILE_DATA_ERRORmip level sizes are increasing not decreasing
KTX_INVALID_OPERATIONthe ktxTexture2 was not created from a stream, i.e there is no data to load, or this ktxTexture2's images have already been loaded.
KTX_INVALID_OPERATIONsupercompressionScheme != KTX_SS_NONE, supercompressionScheme != KTX_SS_ZSTD, and supercompressionScheme != KTX_SS_ZLIB.
KTX_INVALID_VALUEThis is NULL or iterCb is NULL.
KTX_OUT_OF_MEMORYnot enough memory to allocate a block to hold the base level image.
Examples
glloader.c.

◆ ktxTexture_LoadImageData

#define ktxTexture_LoadImageData (   This,
  pBuffer,
  bufSize 
)     (This)->vtbl->LoadImageData(This, pBuffer, bufSize)

Helper for calling the LoadImageData virtual method of a ktxTexture.

Load all the image data from the ktxTexture2's source.

The data will be inflated if supercompressionScheme == KTX_SS_ZSTD or KTX_SS_ZLIB. The data is loaded into the provided buffer or to an internally allocated buffer, if pBuffer is NULL. Callers providing their own buffer must ensure the buffer large enough to hold the inflated data for files deflated with Zstd or ZLIB. See ktxTexture2_GetDataSizeUncompressed().

The texture's levelIndex, dataSize, DFD and supercompressionScheme will all be updated after successful inflation to reflect the inflated data.

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in]pBufferpointer to the buffer in which to load the image data.
[in]bufSizesize of the buffer pointed at by pBuffer.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis is NULL.
KTX_INVALID_VALUEbufSize is less than the the image data size.
KTX_INVALID_OPERATIONThe data has already been loaded or the ktxTexture was not created from a KTX source.
KTX_OUT_OF_MEMORYInsufficient memory for the image data.

◆ ktxTexture_NeedsTranscoding

#define ktxTexture_NeedsTranscoding (   This)    (This)->vtbl->NeedsTranscoding(This)

Helper for calling the NeedsTranscoding virtual method of a ktxTexture.

Query if the images are in a transcodable format.

Parameters
[in]Thispointer to the ktxTexture2 object of interest.

◆ ktxTexture_SetImageFromMemory

#define ktxTexture_SetImageFromMemory (   This,
  level,
  layer,
  faceSlice,
  src,
  srcSize 
)     (This)->vtbl->SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)

Helper for calling the SetImageFromMemory virtual method of a ktxTexture.

Set image for level, layer, faceSlice from an image in memory.

Uncompressed images in memory are expected to have their rows tightly packed as is the norm for most image file formats. KTX 2 also requires tight packing this function does not add any padding.

Level, layer, faceSlice rather than offset are specified to enable some validation.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]levelmip level of the image to set.
[in]layerarray layer of the image to set.
[in]faceSlicecube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level.
[in]srcpointer to the image source in memory.
[in]srcSizesize of the source image in bytes.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or src is NULL.
KTX_INVALID_VALUEsrcSize != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATIONNo storage was allocated when the texture was created.

◆ ktxTexture_SetImageFromStdioStream

#define ktxTexture_SetImageFromStdioStream (   This,
  level,
  layer,
  faceSlice,
  src,
  srcSize 
)
Value:
(This)->vtbl->SetImageFromStdioStream(This, level, layer, faceSlice, \
src, srcSize)

Helper for calling the SetImageFromStdioStream virtual method of a ktxTexture.

Set image for level, layer, faceSlice from a stdio stream source.

Uncompressed images read from the stream are expected to have their rows tightly packed as is the norm for most image file formats. KTX 2 also requires tight packing this function does not add any padding.

Level, layer, faceSlice rather than offset are specified to enable some validation.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]levelmip level of the image to set.
[in]layerarray layer of the image to set.
[in]faceSlicecube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level.
[in]srcstdio stream pointer to the source.
[in]srcSizesize of the source image in bytes.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or src is NULL.
KTX_INVALID_VALUEsrcSize != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATIONNo storage was allocated when the texture was created.

◆ ktxTexture_WriteToMemory

#define ktxTexture_WriteToMemory (   This,
  ppDstBytes,
  pSize 
)     (This)->vtbl->WriteToMemory(This, ppDstBytes, pSize)

Helper for calling the WriteToMemory virtual method of a ktxTexture.

Write a ktxTexture object to block of memory in KTX format.

Memory is allocated by the function and the caller is responsible for freeing it.

Callers are strongly urged to include a KTXwriter item in the texture's metadata. It can be added by code, similar to the following, prior to calling this function.

char writer[100];
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
ktxHashList_AddKVPair(&texture->kvDataHead, KTX_WRITER_KEY,
(ktx_uint32_t)strlen(writer) + 1,
writer);
#define KTX_WRITER_KEY
Key string for standard writer metadata.
Definition: ktx.h:134
Parameters
[in]Thispointer to the target ktxTexture object.
[in,out]ppDstBytespointer to location to write the address of the destination memory. The Application is responsible for freeing this memory.
[in,out]pSizepointer to location to write the size in bytes of the KTX data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis, ppDstBytes or pSize is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_INVALID_OPERATIONBoth kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxTexture_WriteToNamedFile

#define ktxTexture_WriteToNamedFile (   This,
  dstname 
)     (This)->vtbl->WriteToNamedFile(This, dstname)

Helper for calling the WriteToNamedfile virtual method of a ktxTexture.

Write a ktxTexture object to a named file in KTX format.

The file name must be encoded in utf-8. On Windows convert unicode names to utf-8 with WideCharToMultiByte(CP_UTF8, ...) before calling.

Callers are strongly urged to include a KTXwriter item in the texture's metadata. It can be added by code, similar to the following, prior to calling this function.

char writer[100];
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
ktxHashList_AddKVPair(&texture->kvDataHead, KTX_WRITER_KEY,
(ktx_uint32_t)strlen(writer) + 1,
writer);
Parameters
[in]Thispointer to the target ktxTexture object.
[in]dstnamedestination file name.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or dstname is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_INVALID_OPERATIONBoth kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxTexture_WriteToStdioStream

#define ktxTexture_WriteToStdioStream (   This,
  dstsstr 
)     (This)->vtbl->WriteToStdioStream(This, dstsstr)

Helper for calling the WriteToStdioStream virtual method of a ktxTexture.

Write a ktxTexture object to a stdio stream in KTX format.

Callers are strongly urged to include a KTXwriter item in the texture's metadata. It can be added by code, similar to the following, prior to calling this function.

char writer[100];
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
ktxHashList_AddKVPair(&texture->kvDataHead, KTX_WRITER_KEY,
(ktx_uint32_t)strlen(writer) + 1,
writer);
Parameters
[in]Thispointer to the target ktxTexture object.
[in]dstsstrdestination stdio stream.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or dstsstr is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_INVALID_OPERATIONBoth kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxTexture_WriteToStream

#define ktxTexture_WriteToStream (   This,
  dststr 
)     (This)->vtbl->WriteToStream(This, dststr)

Helper for calling the WriteToStream virtual method of a ktxTexture.

Write a ktxTexture object to a ktxStream in KTX format.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]dststrdestination ktxStream.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or dststr is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_INVALID_OPERATIONBoth kvDataHead and kvData are set in the ktxTexture
KTX_INVALID_OPERATIONThe length of the already set writerId metadata plus the library's version id exceeds the maximum allowed.
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

Typedef Documentation

◆ ktx_transcode_fmt_e

Enumerators for specifying the transcode target format.

For BasisU/ETC1S format, Opaque and alpha here refer to 2 separate RGB images, a.k.a slices within the BasisU compressed data. For UASTC format they refer to the RGB and the alpha components of the UASTC data. If the original image had only 2 components, R will be in the opaque portion and G in the alpha portion. The R value will be replicated in the RGB components. In the case of BasisU the G value will be replicated in all 3 components of the alpha slice. If the original image had only 1 component it's value is replicated in all 3 components of the opaque portion and there is no alpha.

Note
You should not transcode sRGB encoded data to KTX_TTF_BC4_R, KTX_TTF_BC5_RG, KTX_TTF_ETC2_EAC_R{,G}11, KTX_TTF_RGB565, KTX_TTF_BGR565 or KTX_TTF_RGBA4444 formats as neither OpenGL nor Vulkan support sRGB variants of these. Doing sRGB decoding in the shader will not produce correct results if any texture filtering is being used.

◆ ktxAstcParams

typedef struct ktxAstcParams ktxAstcParams

Structure for passing extended parameters to ktxTexture_CompressAstc.

Passing a struct initialized to 0 (e.g. " = {0};") will use blockDimension 4x4, mode LDR and qualityLevel FASTEST. Setting qualityLevel to KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM is recommended.

◆ ktxBasisParams

Structure for passing extended parameters to ktxTexture2_CompressBasisEx().

If you only want default values, use ktxTexture2_CompressBasis(). Here, at a minimum you must initialize the structure as follows:

ktxBasisParams params = {0};
params.structSize = sizeof(params);
params.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;
Structure for passing extended parameters to ktxTexture2_CompressBasisEx().
Definition: ktx.h:1279
ktx_uint32_t compressionLevel
Definition: ktx.h:1298
ktx_uint32_t structSize
Definition: ktx.h:1280

compressionLevel has to be explicitly set because 0 is a valid compressionLevel but is not the default used by the BasisU encoder when no value is set. Only the other settings that are to be non-default must be non-zero.

Enumeration Type Documentation

◆ ktx_error_code_e

Error codes returned by library functions.

Enumerator
KTX_SUCCESS 

Operation was successful.

KTX_FILE_DATA_ERROR 

The data in the file is inconsistent with the spec.

KTX_FILE_ISPIPE 

The file is a pipe or named pipe.

KTX_FILE_OPEN_FAILED 

The target file could not be opened.

KTX_FILE_OVERFLOW 

The operation would exceed the max file size.

KTX_FILE_READ_ERROR 

An error occurred while reading from the file.

KTX_FILE_SEEK_ERROR 

An error occurred while seeking in the file.

KTX_FILE_UNEXPECTED_EOF 

File does not have enough data to satisfy request.

KTX_FILE_WRITE_ERROR 

An error occurred while writing to the file.

KTX_GL_ERROR 

GL operations resulted in an error.

KTX_INVALID_OPERATION 

The operation is not allowed in the current state.

KTX_INVALID_VALUE 

A parameter value was not valid.

KTX_NOT_FOUND 

Requested metadata key or required dynamically loaded GPU function was not found.

KTX_OUT_OF_MEMORY 

Not enough memory to complete the operation.

KTX_TRANSCODE_FAILED 

Transcoding of block compressed texture failed.

KTX_UNKNOWN_FILE_FORMAT 

The file not a KTX file

KTX_UNSUPPORTED_TEXTURE_TYPE 

The KTX file specifies an unsupported texture type.

KTX_UNSUPPORTED_FEATURE 

Feature not included in in-use library or not yet implemented.

KTX_LIBRARY_NOT_LINKED 

Library dependency (OpenGL or Vulkan) not linked into application.

KTX_DECOMPRESS_LENGTH_ERROR 

Decompressed byte count does not match expected byte size

KTX_DECOMPRESS_CHECKSUM_ERROR 

Checksum mismatch when decompressing

KTX_ERROR_MAX_ENUM 

For safety checks.

◆ ktx_pack_astc_block_dimension_e

Options specifiying ASTC encoding block dimensions.

Enumerator
KTX_PACK_ASTC_BLOCK_DIMENSION_MAX 

Maximum supported blocks.

◆ ktx_pack_astc_quality_levels_e

Options specifiying ASTC encoding quality levels.

Enumerator
KTX_PACK_ASTC_QUALITY_LEVEL_FASTEST 

Fastest compression.

KTX_PACK_ASTC_QUALITY_LEVEL_FAST 

Fast compression.

KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM 

Medium compression.

KTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH 

Slower compression.

KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE 

Very slow compression.

KTX_PACK_ASTC_QUALITY_LEVEL_MAX 

Maximum supported quality level.

◆ ktx_pack_uastc_flag_bits_e

Flags specifiying UASTC encoding options.

Enumerator
KTX_PACK_UASTC_LEVEL_FASTEST 

Fastest compression. 43.45dB.

KTX_PACK_UASTC_LEVEL_FASTER 

Faster compression. 46.49dB.

KTX_PACK_UASTC_LEVEL_DEFAULT 

Default compression. 47.47dB.

KTX_PACK_UASTC_LEVEL_SLOWER 

Slower compression. 48.01dB.

KTX_PACK_UASTC_LEVEL_VERYSLOW 

Very slow compression. 48.24dB.

KTX_PACK_UASTC_MAX_LEVEL 

Maximum supported quality level.

KTX_PACK_UASTC_LEVEL_MASK 

Mask to extract the level from the other bits.

KTX_PACK_UASTC_FAVOR_UASTC_ERROR 

Optimize for lowest UASTC error.

KTX_PACK_UASTC_FAVOR_BC7_ERROR 

Optimize for lowest BC7 error.

KTX_PACK_UASTC_ETC1_FASTER_HINTS 

Optimize for faster transcoding to ETC1.

KTX_PACK_UASTC_ETC1_FASTEST_HINTS 

Optimize for fastest transcoding to ETC1.

KTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL 

Not documented in BasisU code.

◆ ktx_transcode_flag_bits_e

Flags guiding transcoding of Basis Universal compressed textures.

Enumerator
KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 

PVRTC1: decode non-pow2 ETC1S texture level to the next larger power of 2 (not implemented yet, but we're going to support it). Ignored if the slice's dimensions are already a power of 2.

KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS 

When decoding to an opaque texture format, if the Basis data has alpha, decode the alpha slice instead of the color slice to the output texture format. Has no effect if there is no alpha data.

KTX_TF_HIGH_QUALITY 

Request higher quality transcode of UASTC to BC1, BC3, ETC2_EAC_R11 and ETC2_EAC_RG11. The flag is unused by other UASTC transcoders.

◆ ktx_transcode_fmt_e

Enumerators for specifying the transcode target format.

For BasisU/ETC1S format, Opaque and alpha here refer to 2 separate RGB images, a.k.a slices within the BasisU compressed data. For UASTC format they refer to the RGB and the alpha components of the UASTC data. If the original image had only 2 components, R will be in the opaque portion and G in the alpha portion. The R value will be replicated in the RGB components. In the case of BasisU the G value will be replicated in all 3 components of the alpha slice. If the original image had only 1 component it's value is replicated in all 3 components of the opaque portion and there is no alpha.

Note
You should not transcode sRGB encoded data to KTX_TTF_BC4_R, KTX_TTF_BC5_RG, KTX_TTF_ETC2_EAC_R{,G}11, KTX_TTF_RGB565, KTX_TTF_BGR565 or KTX_TTF_RGBA4444 formats as neither OpenGL nor Vulkan support sRGB variants of these. Doing sRGB decoding in the shader will not produce correct results if any texture filtering is being used.
Enumerator
KTX_TTF_ETC1_RGB 

Opaque only. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified.

KTX_TTF_ETC2_RGBA 

Opaque+alpha. EAC_A8 block followed by an ETC1 block. The alpha channel will be opaque for textures without an alpha channel.

KTX_TTF_BC1_RGB 

Opaque only, no punchthrough alpha support yet. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified.

KTX_TTF_BC3_RGBA 

Opaque+alpha. BC4 block with alpha followed by a BC1 block. The alpha channel will be opaque for textures without an alpha channel.

KTX_TTF_BC4_R 

One BC4 block. R = opaque.g or alpha.g, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified.

KTX_TTF_BC5_RG 

Two BC4 blocks, R=opaque.g and G=alpha.g The texture should have an alpha channel (if not G will be all 255's. For tangent space normal maps.

KTX_TTF_BC7_RGBA 

RGB or RGBA mode 5 for ETC1S, modes 1, 2, 3, 4, 5, 6, 7 for UASTC.

KTX_TTF_PVRTC1_4_RGB 

Opaque only. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified.

KTX_TTF_PVRTC1_4_RGBA 

Opaque+alpha. Most useful for simple opacity maps. If the texture doesn't have an alpha channel KTX_TTF_PVRTC1_4_RGB will be used instead. Lowest quality of any supported texture format.

KTX_TTF_ASTC_4x4_RGBA 

Opaque+alpha, ASTC 4x4. The alpha channel will be opaque for textures without an alpha channel. The transcoder uses RGB/RGBA/L/LA modes, void extent, and up to two ([0,47] and [0,255]) endpoint precisions.

KTX_TTF_PVRTC2_4_RGB 

Opaque-only. Almost BC1 quality, much faster to transcode and supports arbitrary texture dimensions (unlike PVRTC1 RGB).

KTX_TTF_PVRTC2_4_RGBA 

Opaque+alpha. Slower to transcode than cTFPVRTC2_4_RGB. Premultiplied alpha is highly recommended, otherwise the color channel can leak into the alpha channel on transparent blocks.

KTX_TTF_ETC2_EAC_R11 

R only (ETC2 EAC R11 unsigned). R = opaque.g or alpha.g, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified.

KTX_TTF_ETC2_EAC_RG11 

RG only (ETC2 EAC RG11 unsigned), R=opaque.g, G=alpha.g. The texture should have an alpha channel (if not G will be all 255's. For tangent space normal maps.

KTX_TTF_RGBA32 

32bpp RGBA image stored in raster (not block) order in memory, R is first byte, A is last byte.

KTX_TTF_RGB565 

16bpp RGB image stored in raster (not block) order in memory, R at bit position 11.

KTX_TTF_BGR565 

16bpp RGB image stored in raster (not block) order in memory, R at bit position 0.

KTX_TTF_RGBA4444 

16bpp RGBA image stored in raster (not block) order in memory, R at bit position 12, A at bit position 0.

KTX_TTF_ETC 

Automatically selects KTX_TTF_ETC1_RGB or KTX_TTF_ETC2_RGBA according to presence of alpha.

KTX_TTF_BC1_OR_3 

Automatically selects KTX_TTF_BC1_RGB or KTX_TTF_BC3_RGBA according to presence of alpha.

KTX_TF_ETC1 
Deprecated:
. Use KTX_TTF_ETC1_RGB.
KTX_TF_ETC2 
Deprecated:
. Use KTX_TTF_ETC.
KTX_TF_BC1 
Deprecated:
. Use KTX_TTF_BC1_RGB.
KTX_TF_BC3 
Deprecated:
. Use KTX_TTF_BC3_RGBA.
KTX_TF_BC4 
Deprecated:
. Use KTX_TTF_BC4_R.
KTX_TF_BC5 
Deprecated:
. Use KTX_TTF_BC5_RG.
KTX_TTF_BC7_M6_RGB 
Deprecated:
. Use KTX_TTF_BC7_RGBA.
KTX_TTF_BC7_M5_RGBA 
Deprecated:
. Use KTX_TTF_BC7_RGBA.
KTX_TF_BC7_M6_OPAQUE_ONLY 
Deprecated:
. Use KTX_TTF_BC7_RGBA
KTX_TF_PVRTC1_4_OPAQUE_ONLY 
Deprecated:
. Use KTX_TTF_PVRTC1_4_RGB.

◆ ktxSupercmpScheme

Enumerators identifying the supercompression scheme.

Enumerator
KTX_SS_NONE 

No supercompression.

KTX_SS_BASIS_LZ 

Basis LZ supercompression.

KTX_SS_ZSTD 

ZStd supercompression.

KTX_SS_ZLIB 

ZLIB supercompression.

KTX_SUPERCOMPRESSION_BASIS 
Deprecated:
Will be removed before v4 release. Use KTX_SS_BASIS_LZ instead.
KTX_SUPERCOMPRESSION_ZSTD 
Deprecated:
Will be removed before v4 release. Use KTX_SS_ZSTD instead.

Function Documentation

◆ ktxErrorString()

KTX_API const char *KTX_APIENTRY ktxErrorString ( KTX_error_code  error)

Return a string corresponding to a KTX error code.

Parameters
errorthe error code for which to return a string
Returns
pointer to the message string.
Examples
vkload.cpp.

◆ ktxSupercompressionSchemeString()

KTX_API const char *KTX_APIENTRY ktxSupercompressionSchemeString ( ktxSupercmpScheme  scheme)

Return a string corresponding to a supercompressionScheme enumeration.

Parameters
schemethe supercompression scheme for which to return a string.
Returns
pointer to the message string.

◆ ktxTranscodeFormatString()

KTX_API const char *KTX_APIENTRY ktxTranscodeFormatString ( ktx_transcode_fmt_e  format)

Return a string corresponding to a transcode format enumeration.

Parameters
formatthe transcode format for which to return a string.
Returns
pointer to the message string.