.TH "include/ktx.h" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*- .ad l .nh .SH NAME include/ktx.h \- Declares the public functions and structures of the KTX API\&. .SH SYNOPSIS .br .PP \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br \fR#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBktxOrientation\fP" .br .RI "Struct describing the logical orientation of an image\&. " .ti -1c .RI "class \fBktxTexture\fP" .br .RI "Base class representing a texture\&. " .ti -1c .RI "struct \fBktxTexture_vtbl\fP" .br .RI "Table of virtual \fBktxTexture\fP methods\&. " .ti -1c .RI "class \fBktxTexture1\fP" .br .RI "Class representing a KTX version 1 format texture\&. " .ti -1c .RI "class \fBktxTexture2\fP" .br .RI "Class representing a KTX version 2 format texture\&. " .ti -1c .RI "struct \fBktxTextureCreateInfo\fP" .br .RI "Structure for passing texture information to ktxTexture1_Create() and ktxTexture2_Create()\&. " .ti -1c .RI "struct \fBktxStream\fP" .br .RI "Interface of \fBktxStream\fP\&. " .ti -1c .RI "struct \fBktxAstcParams\fP" .br .RI "Structure for passing extended parameters to ktxTexture_CompressAstc\&. " .ti -1c .RI "struct \fBktxBasisParams\fP" .br .RI "Structure for passing extended parameters to ktxTexture2_CompressBasisEx()\&. " .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBKTX_ANIMDATA_KEY\fP 'KTXanimData'" .br .RI "Key string for standard writer metadata\&. " .ti -1c .RI "#define \fBKTX_ORIENTATION_KEY\fP 'KTXorientation'" .br .RI "Key string for standard orientation metadata\&. " .ti -1c .RI "#define \fBKTX_SWIZZLE_KEY\fP 'KTXswizzle'" .br .RI "Key string for standard swizzle metadata\&. " .ti -1c .RI "#define \fBKTX_WRITER_KEY\fP 'KTXwriter'" .br .RI "Key string for standard writer metadata\&. " .ti -1c .RI "#define \fBKTX_WRITER_SCPARAMS_KEY\fP 'KTXwriterScParams'" .br .RI "Key string for standard writer supercompression parameter metadata\&. " .ti -1c .RI "#define \fBKTX_ORIENTATION1_FMT\fP 'S=%c'" .br .RI "Standard KTX 1 format for 1D orientation value\&. " .ti -1c .RI "#define \fBKTX_ORIENTATION2_FMT\fP 'S=%c,T=%c'" .br .RI "Standard KTX 1 format for 2D orientation value\&. " .ti -1c .RI "#define \fBKTX_ORIENTATION3_FMT\fP 'S=%c,T=%c,R=%c'" .br .RI "Standard KTX 1 format for 3D orientation value\&. " .ti -1c .RI "#define \fBKTX_GL_UNPACK_ALIGNMENT\fP 4" .br .RI "Required unpack alignment\&. " .ti -1c .RI "#define \fBKTX_error_code\fP \fBktx_error_code_e\fP" .br .RI "For backward compatibility\&. " .ti -1c .RI "#define \fBktxTexture_Destroy\fP(This)" .br .RI "Helper for calling the Destroy virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_GetImageOffset\fP(This, level, layer, faceSlice, pOffset)" .br .RI "Helper for calling the GetImageOffset virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_GetDataSizeUncompressed\fP(This)" .br .RI "Helper for calling the GetDataSizeUncompressed virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_GetImageSize\fP(This, level)" .br .RI "Helper for calling the GetImageSize virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_GetLevelSize\fP(This, level)" .br .RI "Helper for calling the GetImageSize virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_IterateLevels\fP(This, iterCb, userdata)" .br .RI "Helper for calling the IterateLevels virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_IterateLoadLevelFaces\fP(This, iterCb, userdata)" .br .RI "Helper for calling the IterateLoadLevelFaces virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_LoadImageData\fP(This, pBuffer, bufSize)" .br .RI "Helper for calling the LoadImageData virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_NeedsTranscoding\fP(This)" .br .RI "Helper for calling the NeedsTranscoding virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_SetImageFromMemory\fP(This, level, layer, faceSlice, src, srcSize)" .br .RI "Helper for calling the SetImageFromMemory virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_SetImageFromStdioStream\fP(This, level, layer, faceSlice, src, srcSize)" .br .RI "Helper for calling the SetImageFromStdioStream virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_WriteToStdioStream\fP(This, dstsstr)" .br .RI "Helper for calling the WriteToStdioStream virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_WriteToNamedFile\fP(This, dstname)" .br .RI "Helper for calling the WriteToNamedfile virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_WriteToMemory\fP(This, ppDstBytes, pSize)" .br .RI "Helper for calling the WriteToMemory virtual method of a \fBktxTexture\fP\&. " .ti -1c .RI "#define \fBktxTexture_WriteToStream\fP(This, dststr)" .br .RI "Helper for calling the WriteToStream virtual method of a \fBktxTexture\fP\&. " .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef enum \fBktx_error_code_e\fP \fBktx_error_code_e\fP" .br .RI "Error codes returned by library functions\&. " .ti -1c .RI "typedef enum \fBktx_error_code_e\fP \fBktxResult\fP" .br .RI "Result codes returned by library functions\&. " .ti -1c .RI "typedef enum \fBktxSupercmpScheme\fP \fBktxSupercmpScheme\fP" .br .RI "Enumerators identifying the supercompression scheme\&. " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_read\fP) (\fBktxStream\fP *str, void *dst, const ktx_size_t count)" .br .RI "type for a pointer to a stream reading function " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_skip\fP) (\fBktxStream\fP *str, const ktx_size_t count)" .br .RI "type for a pointer to a stream skipping function " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_write\fP) (\fBktxStream\fP *str, const void *src, const ktx_size_t size, const ktx_size_t count)" .br .RI "type for a pointer to a stream writing function " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_getpos\fP) (\fBktxStream\fP *str, ktx_off_t *const offset)" .br .RI "type for a pointer to a stream position query function " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_setpos\fP) (\fBktxStream\fP *str, const ktx_off_t offset)" .br .RI "type for a pointer to a stream position query function " .ti -1c .RI "typedef \fBKTX_error_code\fP(* \fBktxStream_getsize\fP) (\fBktxStream\fP *str, ktx_size_t *const size)" .br .RI "type for a pointer to a stream size query function " .ti -1c .RI "typedef void(* \fBktxStream_destruct\fP) (\fBktxStream\fP *str)" .br .RI "Destruct a stream\&. " .ti -1c .RI "typedef void(KTX_APIENTRY * \fBPFNVOIDFUNCTION\fP) (void)" .br .RI "typedef of function pointer returned by GLGetProcAddress functions\&. " .ti -1c .RI "typedef \fBPFNVOIDFUNCTION\fP(KTX_APIENTRY * \fBPFNGLGETPROCADDRESS\fP) (const char *proc)" .br .RI "typedef of pointer to function for retrieving OpenGL function pointers\&. " .ti -1c .RI "typedef enum \fBktx_pack_uastc_flag_bits_e\fP \fBktx_pack_uastc_flag_bits_e\fP" .br .RI "Flags specifiying UASTC encoding options\&. " .ti -1c .RI "typedef enum \fBktx_pack_astc_quality_levels_e\fP \fBktx_pack_astc_quality_levels_e\fP" .br .RI "Options specifiying ASTC encoding quality levels\&. " .ti -1c .RI "typedef enum \fBktx_pack_astc_block_dimension_e\fP \fBktx_pack_astc_block_dimension_e\fP" .br .RI "Options specifiying ASTC encoding block dimensions\&. " .ti -1c .RI "typedef enum \fBktx_pack_astc_encoder_mode_e\fP \fBktx_pack_astc_encoder_mode_e\fP" .br .RI "Options specifying ASTC encoder mode\&. " .ti -1c .RI "typedef struct ktxAstcParams \fBktxAstcParams\fP" .br .RI "Structure for passing extended parameters to ktxTexture_CompressAstc\&. " .ti -1c .RI "typedef struct ktxBasisParams \fBktxBasisParams\fP" .br .RI "Structure for passing extended parameters to ktxTexture2_CompressBasisEx()\&. " .ti -1c .RI "typedef enum \fBktx_transcode_fmt_e\fP \fBktx_transcode_fmt_e\fP" .br .RI "Enumerators for specifying the transcode target format\&. " .ti -1c .RI "typedef enum \fBktx_transcode_flag_bits_e\fP \fBktx_transcode_flag_bits_e\fP" .br .RI "Flags guiding transcoding of Basis Universal compressed textures\&. " .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBktx_error_code_e\fP { \fBKTX_SUCCESS\fP = 0, \fBKTX_FILE_DATA_ERROR\fP, \fBKTX_FILE_ISPIPE\fP, \fBKTX_FILE_OPEN_FAILED\fP, \fBKTX_FILE_OVERFLOW\fP, \fBKTX_FILE_READ_ERROR\fP, \fBKTX_FILE_SEEK_ERROR\fP, \fBKTX_FILE_UNEXPECTED_EOF\fP, \fBKTX_FILE_WRITE_ERROR\fP, \fBKTX_GL_ERROR\fP, \fBKTX_INVALID_OPERATION\fP, \fBKTX_INVALID_VALUE\fP, \fBKTX_NOT_FOUND\fP, \fBKTX_OUT_OF_MEMORY\fP, \fBKTX_TRANSCODE_FAILED\fP, \fBKTX_UNKNOWN_FILE_FORMAT\fP, \fBKTX_UNSUPPORTED_TEXTURE_TYPE\fP, \fBKTX_UNSUPPORTED_FEATURE\fP, \fBKTX_LIBRARY_NOT_LINKED\fP, \fBKTX_DECOMPRESS_LENGTH_ERROR\fP, \fBKTX_DECOMPRESS_CHECKSUM_ERROR\fP, \fBKTX_ERROR_MAX_ENUM\fP = KTX_DECOMPRESS_CHECKSUM_ERROR }" .br .RI "Error codes returned by library functions\&. " .ti -1c .RI "enum \fBktxSupercmpScheme\fP { \fBKTX_SS_NONE\fP = 0, \fBKTX_SS_BASIS_LZ\fP = 1, \fBKTX_SS_ZSTD\fP = 2, \fBKTX_SS_ZLIB\fP = 3, \fBKTX_SS_BEGIN_RANGE\fP = KTX_SS_NONE, \fBKTX_SS_END_RANGE\fP = KTX_SS_ZLIB, \fBKTX_SS_BEGIN_VENDOR_RANGE\fP = 0x10000, \fBKTX_SS_END_VENDOR_RANGE\fP = 0x1ffff, \fBKTX_SS_BEGIN_RESERVED\fP = 0x20000 }" .br .RI "Enumerators identifying the supercompression scheme\&. " .ti -1c .RI "enum \fBktx_pack_uastc_flag_bits_e\fP { \fBKTX_PACK_UASTC_LEVEL_FASTEST\fP = 0, \fBKTX_PACK_UASTC_LEVEL_FASTER\fP = 1, \fBKTX_PACK_UASTC_LEVEL_DEFAULT\fP = 2, \fBKTX_PACK_UASTC_LEVEL_SLOWER\fP = 3, \fBKTX_PACK_UASTC_LEVEL_VERYSLOW\fP = 4, \fBKTX_PACK_UASTC_MAX_LEVEL\fP = KTX_PACK_UASTC_LEVEL_VERYSLOW, \fBKTX_PACK_UASTC_LEVEL_MASK\fP = 0xF, \fBKTX_PACK_UASTC_FAVOR_UASTC_ERROR\fP = 8, \fBKTX_PACK_UASTC_FAVOR_BC7_ERROR\fP = 16, \fBKTX_PACK_UASTC_ETC1_FASTER_HINTS\fP = 64, \fBKTX_PACK_UASTC_ETC1_FASTEST_HINTS\fP = 128, \fBKTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL\fP = 256 }" .br .RI "Flags specifiying UASTC encoding options\&. " .ti -1c .RI "enum \fBktx_pack_astc_quality_levels_e\fP { \fBKTX_PACK_ASTC_QUALITY_LEVEL_FASTEST\fP = 0, \fBKTX_PACK_ASTC_QUALITY_LEVEL_FAST\fP = 10, \fBKTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM\fP = 60, \fBKTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH\fP = 98, \fBKTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE\fP = 100, \fBKTX_PACK_ASTC_QUALITY_LEVEL_MAX\fP = KTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE }" .br .RI "Options specifiying ASTC encoding quality levels\&. " .ti -1c .RI "enum \fBktx_pack_astc_block_dimension_e\fP { }" .br .RI "Options specifiying ASTC encoding block dimensions\&. " .ti -1c .RI "enum \fBktx_pack_astc_encoder_mode_e\fP { \fBKTX_PACK_ASTC_ENCODER_MODE_DEFAULT\fP, \fBKTX_PACK_ASTC_ENCODER_MODE_LDR\fP, \fBKTX_PACK_ASTC_ENCODER_MODE_HDR\fP, \fBKTX_PACK_ASTC_ENCODER_MODE_MAX\fP = KTX_PACK_ASTC_ENCODER_MODE_HDR }" .br .RI "Options specifying ASTC encoder mode\&. " .ti -1c .RI "enum \fBktx_transcode_fmt_e\fP { \fBKTX_TTF_ETC1_RGB\fP = 0, \fBKTX_TTF_ETC2_RGBA\fP = 1, \fBKTX_TTF_BC1_RGB\fP = 2, \fBKTX_TTF_BC3_RGBA\fP = 3, \fBKTX_TTF_BC4_R\fP = 4, \fBKTX_TTF_BC5_RG\fP = 5, \fBKTX_TTF_BC7_RGBA\fP = 6, \fBKTX_TTF_PVRTC1_4_RGB\fP = 8, \fBKTX_TTF_PVRTC1_4_RGBA\fP = 9, \fBKTX_TTF_ASTC_4x4_RGBA\fP = 10, \fBKTX_TTF_PVRTC2_4_RGB\fP = 18, \fBKTX_TTF_PVRTC2_4_RGBA\fP = 19, \fBKTX_TTF_ETC2_EAC_R11\fP = 20, \fBKTX_TTF_ETC2_EAC_RG11\fP = 21, \fBKTX_TTF_RGBA32\fP = 13, \fBKTX_TTF_RGB565\fP = 14, \fBKTX_TTF_BGR565\fP = 15, \fBKTX_TTF_RGBA4444\fP = 16, \fBKTX_TTF_ETC\fP = 22, \fBKTX_TTF_BC1_OR_3\fP = 23, \fBKTX_TTF_NOSELECTION\fP = 0x7fffffff, \fBKTX_TF_ETC1\fP = KTX_TTF_ETC1_RGB, \fBKTX_TF_ETC2\fP = KTX_TTF_ETC, \fBKTX_TF_BC1\fP = KTX_TTF_BC1_RGB, \fBKTX_TF_BC3\fP = KTX_TTF_BC3_RGBA, \fBKTX_TF_BC4\fP = KTX_TTF_BC4_R, \fBKTX_TF_BC5\fP = KTX_TTF_BC5_RG, \fBKTX_TTF_BC7_M6_RGB\fP = KTX_TTF_BC7_RGBA, \fBKTX_TTF_BC7_M5_RGBA\fP = KTX_TTF_BC7_RGBA, \fBKTX_TF_BC7_M6_OPAQUE_ONLY\fP = KTX_TTF_BC7_RGBA, \fBKTX_TF_PVRTC1_4_OPAQUE_ONLY\fP = KTX_TTF_PVRTC1_4_RGB }" .br .RI "Enumerators for specifying the transcode target format\&. " .ti -1c .RI "enum \fBktx_transcode_flag_bits_e\fP { \fBKTX_TF_PVRTC_DECODE_TO_NEXT_POW2\fP = 2, \fBKTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS\fP = 4, \fBKTX_TF_HIGH_QUALITY\fP = 32 }" .br .RI "Flags guiding transcoding of Basis Universal compressed textures\&. " .in -1c .SS "Functions" .in +1c .ti -1c .RI "KTX_API \fBKTX_error_code\fP KTX_APIENTRY \fBktxLoadOpenGL\fP (\fBPFNGLGETPROCADDRESS\fP pfnGLGetProcAddress)" .br .RI "Load pointers for the GL functions used by the ktxTexture*_GLUpload functions\&. " .ti -1c .RI "KTX_API \fBKTX_error_code\fP KTX_APIENTRY \fBktxTexture2_DecodeAstc\fP (\fBktxTexture2\fP *This)" .br .RI "Decodes a ktx2 texture object, if it is ASTC encoded\&. " .ti -1c .RI "KTX_API const char *KTX_APIENTRY \fBktxErrorString\fP (\fBKTX_error_code\fP error)" .br .RI "Return a string corresponding to a KTX error code\&. " .ti -1c .RI "KTX_API const char *KTX_APIENTRY \fBktxSupercompressionSchemeString\fP (\fBktxSupercmpScheme\fP scheme)" .br .RI "Return a string corresponding to a supercompressionScheme enumeration\&. " .ti -1c .RI "KTX_API const char *KTX_APIENTRY \fBktxTranscodeFormatString\fP (\fBktx_transcode_fmt_e\fP format)" .br .RI "Return a string corresponding to a transcode format enumeration\&. " .in -1c .SH "Detailed Description" .PP Declares the public functions and structures of the KTX API\&. .PP \fBAuthor\fP .RS 4 Mark Callow, Edgewise Consulting and while at HI Corporation .PP Based on original work by Georg Kolling, Imagination Technology .RE .PP \fBAPI Version\fP .RS 4 v4\&.0 .RE .PP .SH "Macro Definition Documentation" .PP .SS "#define KTX_error_code \fBktx_error_code_e\fP" .PP For backward compatibility\&. .PP \fBDeprecated\fP .RS 4 Use \fBktx_error_code_e\fP\&. .RE .PP .PP \fBExamples\fP .in +1c \fBglloader\&.c\fP, and \fBvkload\&.cpp\fP\&. .SS "#define ktxTexture_Destroy( This)" \fBValue:\fP .nf (This)\->vtbl\->Destroy(This) .PP .fi .PP Helper for calling the Destroy virtual method of a \fBktxTexture\fP\&. Destroy a \fBktxTexture2\fP object\&. .PP This frees the memory associated with the texture contents and the memory of the \fBktxTexture2\fP object\&. This does \fInot\fP delete any OpenGL or Vulkan texture objects created by ktxTexture2_GLUpload or ktxTexture2_VkUpload\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture2\fP object to destroy .RE .PP .PP \fBExamples\fP .in +1c \fBvkload\&.cpp\fP\&. .SS "#define ktxTexture_GetDataSizeUncompressed( This)" \fBValue:\fP .nf (This)\->vtbl\->GetDataSizeUncompressed(This) .PP .fi .PP Helper for calling the GetDataSizeUncompressed virtual method of a \fBktxTexture\fP\&. For a \fBktxTexture1\fP this will always return the value of This->dataSize\&. .PP If supercompressionScheme == \fRKTX_SS_NONE\fP or \fRKTX_SS_BASIS_LZ\fP, returns the value of \fRThis->dataSize\fP else if supercompressionScheme == \fRKTX_SS_ZSTD\fP or \fRKTX_SS_ZLIB\fP, 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\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. .RE .PP .SS "#define ktxTexture_GetImageOffset( This, level, layer, faceSlice, pOffset)" \fBValue:\fP .nf (This)\->vtbl\->GetImageOffset(This, level, layer, faceSlice, pOffset) .PP .fi .PP Helper for calling the GetImageOffset virtual method of a \fBktxTexture\fP\&. Find the offset of an image within a \fBktxTexture\fP's image data\&. .PP 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\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. .br \fIlevel\fP mip level of the image\&. .br \fIlayer\fP array layer of the image\&. .br \fIfaceSlice\fP cube map face or depth slice of the image\&. .br \fIpOffset\fP pointer to location to store the offset\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_OPERATION\fP\fP \fRlevel\fP, \fRlayer\fP or \fRfaceSlice\fP exceed the dimensions of the texture\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP Texture is supercompressed\&. .br \fIKTX_INVALID_VALID\fP \fRThis\fP is NULL\&. .RE .PP .SS "#define ktxTexture_GetImageSize( This, level)" \fBValue:\fP .nf (This)\->vtbl\->GetImageSize(This, level) .PP .fi .PP Helper for calling the GetImageSize virtual method of a \fBktxTexture\fP\&. Calculate & return the size in bytes of an image at the specified mip level\&. .PP 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\&. .PP The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. .br \fIlevel\fP level of interest\&. * .RE .PP .SS "#define ktxTexture_GetLevelSize( This, level)" \fBValue:\fP .nf (This)\->vtbl\->GetLevelSize(This, level) .PP .fi .PP Helper for calling the GetImageSize virtual method of a \fBktxTexture\fP\&. Calculate & return the size in bytes of an image at the specified mip level\&. .PP 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\&. .PP The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. .br \fIlevel\fP level of interest\&. * .RE .PP .SS "#define ktxTexture_IterateLevels( This, iterCb, userdata)" \fBValue:\fP .nf (This)\->vtbl\->IterateLevels(This, iterCb, userdata) .PP .fi .PP Helper for calling the IterateLevels virtual method of a \fBktxTexture\fP\&. Iterate over the mip levels in a \fBktxTexture2\fP object\&. .PP 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\&. .PP This function works even if \fRThis->pData\fP == 0 so it can be used to obtain offsets and sizes for each level by callers who have loaded the data externally\&. .PP Intended for use only when supercompressionScheme == SUPERCOMPRESSION_NONE\&. .PP \fBParameters\fP .RS 4 \fIThis\fP handle of the \fBktxTexture\fP opened on the data\&. .br \fIiterCb\fP the address of a callback function which is called with the data for each image block\&. .br \fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_FILE_DATA_ERROR\fP\fP Mip level sizes are increasing not decreasing .br \fI\fBKTX_INVALID_OPERATION\fP\fP supercompressionScheme != SUPERCOMPRESSION_NONE\&. .br \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. .RE .PP .SS "#define ktxTexture_IterateLoadLevelFaces( This, iterCb, userdata)" \fBValue:\fP .nf (This)\->vtbl\->IterateLoadLevelFaces(This, iterCb, userdata) .PP .fi .PP Helper for calling the IterateLoadLevelFaces virtual method of a \fBktxTexture\fP\&. Iterate over the images in a \fBktxTexture2\fP object while loading the image data\&. .PP This operates similarly to ktxTexture_IterateLevelFaces() except that it loads the images from the \fBktxTexture2\fP'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\&. .PP This function is helpful for reducing memory usage when uploading the data to a graphics API\&. .PP Intended for use only when supercompressionScheme == KTX_SS_NONE, KTX_SS_ZSTD or KTX_SS_ZLIB\&. As there is no access to the \fBktxTexture\fP's data on conclusion of this function, destroying the texture on completion is recommended\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. .br \fIiterCb\fP the address of a callback function which is called with the data for each image\&. .br \fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_FILE_DATA_ERROR\fP\fP mip level sizes are increasing not decreasing .br \fI\fBKTX_INVALID_OPERATION\fP\fP the \fBktxTexture2\fP was not created from a stream, i\&.e there is no data to load, or this \fBktxTexture2\fP's images have already been loaded\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP supercompressionScheme != KTX_SS_NONE, supercompressionScheme != KTX_SS_ZSTD, and supercompressionScheme != KTX_SS_ZLIB\&. .br \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. .br \fI\fBKTX_OUT_OF_MEMORY\fP\fP not enough memory to allocate a block to hold the base level image\&. .RE .PP .PP \fBExamples\fP .in +1c \fBglloader\&.c\fP\&. .SS "#define ktxTexture_LoadImageData( This, pBuffer, bufSize)" \fBValue:\fP .nf (This)\->vtbl\->LoadImageData(This, pBuffer, bufSize) .PP .fi .PP Helper for calling the LoadImageData virtual method of a \fBktxTexture\fP\&. Load all the image data from the \fBktxTexture2\fP's source\&. .PP The data will be inflated if supercompressionScheme == \fRKTX_SS_ZSTD\fP or \fRKTX_SS_ZLIB\fP\&. The data is loaded into the provided buffer or to an internally allocated buffer, if \fRpBuffer\fP is \fRNULL\fP\&. 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()\&. .PP The texture's levelIndex, dataSize, DFD and supercompressionScheme will all be updated after successful inflation to reflect the inflated data\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. .br \fIpBuffer\fP pointer to the buffer in which to load the image data\&. .br \fIbufSize\fP size of the buffer pointed at by \fRpBuffer\fP\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is NULL\&. .br \fI\fBKTX_INVALID_VALUE\fP\fP \fRbufSize\fP is less than the the image data size\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP The data has already been loaded or the \fBktxTexture\fP was not created from a KTX source\&. .br \fI\fBKTX_OUT_OF_MEMORY\fP\fP Insufficient memory for the image data\&. .RE .PP .SS "#define ktxTexture_NeedsTranscoding( This)" \fBValue:\fP .nf (This)\->vtbl\->NeedsTranscoding(This) .PP .fi .PP Helper for calling the NeedsTranscoding virtual method of a \fBktxTexture\fP\&. Query if the images are in a transcodable format\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. .RE .PP .SS "#define ktxTexture_SetImageFromMemory( This, level, layer, faceSlice, src, srcSize)" \fBValue:\fP .nf (This)\->vtbl\->SetImageFromMemory(This, level, layer, faceSlice, src, srcSize) .PP .fi .PP Helper for calling the SetImageFromMemory virtual method of a \fBktxTexture\fP\&. Set image for level, layer, faceSlice from an image in memory\&. .PP 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\&. .PP Level, layer, faceSlice rather than offset are specified to enable some validation\&. .PP \fBNote\fP .RS 4 The caller is responsible for freeing the original image memory referred to by \fRsrc\fP\&. .RE .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIlevel\fP mip level of the image to set\&. .br \fIlayer\fP array layer of the image to set\&. .br \fIfaceSlice\fP cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level\&. .br \fIsrc\fP pointer to the image source in memory\&. .br \fIsrcSize\fP size of the source image in bytes\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP or \fRsrc\fP is NULL\&. .br \fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&. .RE .PP .SS "#define ktxTexture_SetImageFromStdioStream( This, level, layer, faceSlice, src, srcSize)" \fBValue:\fP .nf (This)\->vtbl\->SetImageFromStdioStream(This, level, layer, faceSlice, \\ src, srcSize) .PP .fi .PP Helper for calling the SetImageFromStdioStream virtual method of a \fBktxTexture\fP\&. Set image for level, layer, faceSlice from a stdio stream source\&. .PP 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\&. .PP Level, layer, faceSlice rather than offset are specified to enable some validation\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIlevel\fP mip level of the image to set\&. .br \fIlayer\fP array layer of the image to set\&. .br \fIfaceSlice\fP cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level\&. .br \fIsrc\fP stdio stream pointer to the source\&. .br \fIsrcSize\fP size of the source image in bytes\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP or \fRsrc\fP is NULL\&. .br \fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&. .RE .PP .SS "#define ktxTexture_WriteToMemory( This, ppDstBytes, pSize)" \fBValue:\fP .nf (This)\->vtbl\->WriteToMemory(This, ppDstBytes, pSize) .PP .fi .PP Helper for calling the WriteToMemory virtual method of a \fBktxTexture\fP\&. Write a \fBktxTexture\fP object to block of memory in KTX format\&. .PP Memory is allocated by the function and the caller is responsible for freeing it\&. .PP 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\&. .PP .nf 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); .fi .PP .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIppDstBytes\fP pointer to location to write the address of the destination memory\&. The Application is responsible for freeing this memory\&. .br \fIpSize\fP pointer to location to write the size in bytes of the KTX data\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP, \fRppDstBytes\fP or \fRpSize\fP is NULL\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP .br \fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&. .br \fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&. .RE .PP .SS "#define ktxTexture_WriteToNamedFile( This, dstname)" \fBValue:\fP .nf (This)\->vtbl\->WriteToNamedFile(This, dstname) .PP .fi .PP Helper for calling the WriteToNamedfile virtual method of a \fBktxTexture\fP\&. Write a \fBktxTexture\fP object to a named file in KTX format\&. .PP The file name must be encoded in utf-8\&. On Windows convert unicode names to utf-8 with \fRWideCharToMultiByte(CP_UTF8, \&.\&.\&.)\fP before calling\&. .PP 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\&. .PP .nf 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); .fi .PP .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIdstname\fP destination file name\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP or \fRdstname\fP is NULL\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP .br \fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&. .br \fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&. .RE .PP .SS "#define ktxTexture_WriteToStdioStream( This, dstsstr)" \fBValue:\fP .nf (This)\->vtbl\->WriteToStdioStream(This, dstsstr) .PP .fi .PP Helper for calling the WriteToStdioStream virtual method of a \fBktxTexture\fP\&. Write a \fBktxTexture\fP object to a stdio stream in KTX format\&. .PP 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\&. .PP .nf 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); .fi .PP .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIdstsstr\fP destination stdio stream\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP or \fRdstsstr\fP is NULL\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP .br \fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&. .br \fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&. .RE .PP .SS "#define ktxTexture_WriteToStream( This, dststr)" \fBValue:\fP .nf (This)\->vtbl\->WriteToStream(This, dststr) .PP .fi .PP Helper for calling the WriteToStream virtual method of a \fBktxTexture\fP\&. Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX format\&. .PP \fBParameters\fP .RS 4 \fIThis\fP pointer to the target \fBktxTexture\fP object\&. .br \fIdststr\fP destination \fBktxStream\fP\&. .RE .PP \fBReturns\fP .RS 4 KTX_SUCCESS on success, other KTX_* enum values on error\&. .RE .PP \fBExceptions\fP .RS 4 \fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP or \fRdststr\fP is NULL\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&. .br \fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP .br \fI\fBKTX_INVALID_OPERATION\fP\fP The length of the already set writerId metadata plus the library's version id exceeds the maximum allowed\&. .br \fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&. .br \fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&. .RE .PP .SH "Typedef Documentation" .PP .SS "typedef enum \fBktx_transcode_fmt_e\fP \fBktx_transcode_fmt_e\fP" .PP Enumerators for specifying the transcode target format\&. For BasisU/ETC1S format, \fIOpaque\fP and \fIalpha\fP 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\&. .PP \fBNote\fP .RS 4 You should not transcode sRGB encoded data to \fRKTX_TTF_BC4_R\fP, \fRKTX_TTF_BC5_RG\fP, \fRKTX_TTF_ETC2_EAC_R{\fP,G}11, \fRKTX_TTF_RGB565\fP, \fRKTX_TTF_BGR565\fP or \fRKTX_TTF_RGBA4444\fP 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\&. .RE .PP .SS "typedef struct ktxAstcParams ktxAstcParams" .PP 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\&. .SS "typedef struct ktxBasisParams ktxBasisParams" .PP 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: .PP .nf ktxBasisParams params = {0}; params\&.structSize = sizeof(params); params\&.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL; .fi .PP .PP \fIcompressionLevel\fP has to be explicitly set because 0 is a valid \fIcompressionLevel\fP 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\&. .SH "Enumeration Type Documentation" .PP .SS "enum \fBktx_error_code_e\fP" .PP Error codes returned by library functions\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_SUCCESS \fP Operation was successful\&. .TP \f(BIKTX_FILE_DATA_ERROR \fP The data in the file is inconsistent with the spec\&. .TP \f(BIKTX_FILE_ISPIPE \fP The file is a pipe or named pipe\&. .TP \f(BIKTX_FILE_OPEN_FAILED \fP The target file could not be opened\&. .TP \f(BIKTX_FILE_OVERFLOW \fP The operation would exceed the max file size\&. .TP \f(BIKTX_FILE_READ_ERROR \fP An error occurred while reading from the file\&. .TP \f(BIKTX_FILE_SEEK_ERROR \fP An error occurred while seeking in the file\&. .TP \f(BIKTX_FILE_UNEXPECTED_EOF \fP File does not have enough data to satisfy request\&. .TP \f(BIKTX_FILE_WRITE_ERROR \fP An error occurred while writing to the file\&. .TP \f(BIKTX_GL_ERROR \fP GL operations resulted in an error\&. .TP \f(BIKTX_INVALID_OPERATION \fP The operation is not allowed in the current state\&. .TP \f(BIKTX_INVALID_VALUE \fP A parameter value was not valid\&. .TP \f(BIKTX_NOT_FOUND \fP Requested metadata key or required dynamically loaded GPU function was not found\&. .TP \f(BIKTX_OUT_OF_MEMORY \fP Not enough memory to complete the operation\&. .TP \f(BIKTX_TRANSCODE_FAILED \fP Transcoding of block compressed texture failed\&. .TP \f(BIKTX_UNKNOWN_FILE_FORMAT \fP The file not a KTX file .TP \f(BIKTX_UNSUPPORTED_TEXTURE_TYPE \fP The KTX file specifies an unsupported texture type\&. .TP \f(BIKTX_UNSUPPORTED_FEATURE \fP Feature not included in in-use library or not yet implemented\&. .TP \f(BIKTX_LIBRARY_NOT_LINKED \fP Library dependency (OpenGL or Vulkan) not linked into application\&. .TP \f(BIKTX_DECOMPRESS_LENGTH_ERROR \fP Decompressed byte count does not match expected byte size .TP \f(BIKTX_DECOMPRESS_CHECKSUM_ERROR \fP Checksum mismatch when decompressing .TP \f(BIKTX_ERROR_MAX_ENUM \fP For safety checks\&. .PP \fBExamples\fP .in +1c \fBglloader\&.c\fP\&. .SS "enum \fBktx_pack_astc_block_dimension_e\fP" .PP Options specifiying ASTC encoding block dimensions\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_PACK_ASTC_BLOCK_DIMENSION_MAX \fP Maximum supported blocks\&. .SS "enum \fBktx_pack_astc_encoder_mode_e\fP" .PP Options specifying ASTC encoder mode\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_PACK_ASTC_ENCODER_MODE_DEFAULT \fP Selects LDR mode if component size is <= 8-bit, HDR otherwise\&. .TP \f(BIKTX_PACK_ASTC_ENCODER_MODE_LDR \fP Always encode in low dynamic range mode\&. .TP \f(BIKTX_PACK_ASTC_ENCODER_MODE_HDR \fP Always encode in high dynamic range mode\&. .TP \f(BIKTX_PACK_ASTC_ENCODER_MODE_MAX \fP Indicates the maximum permissible value\&. .SS "enum \fBktx_pack_astc_quality_levels_e\fP" .PP Options specifiying ASTC encoding quality levels\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_FASTEST \fP Fastest compression\&. .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_FAST \fP Fast compression\&. .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM \fP Medium compression\&. .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_THOROUGH \fP Slower compression\&. .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_EXHAUSTIVE \fP Very slow compression\&. .TP \f(BIKTX_PACK_ASTC_QUALITY_LEVEL_MAX \fP Maximum supported quality level\&. .SS "enum \fBktx_pack_uastc_flag_bits_e\fP" .PP Flags specifiying UASTC encoding options\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_PACK_UASTC_LEVEL_FASTEST \fP Fastest compression\&. 43\&.45dB\&. .TP \f(BIKTX_PACK_UASTC_LEVEL_FASTER \fP Faster compression\&. 46\&.49dB\&. .TP \f(BIKTX_PACK_UASTC_LEVEL_DEFAULT \fP Default compression\&. 47\&.47dB\&. .TP \f(BIKTX_PACK_UASTC_LEVEL_SLOWER \fP Slower compression\&. 48\&.01dB\&. .TP \f(BIKTX_PACK_UASTC_LEVEL_VERYSLOW \fP Very slow compression\&. 48\&.24dB\&. .TP \f(BIKTX_PACK_UASTC_MAX_LEVEL \fP Maximum supported quality level\&. .TP \f(BIKTX_PACK_UASTC_LEVEL_MASK \fP Mask to extract the level from the other bits\&. .TP \f(BIKTX_PACK_UASTC_FAVOR_UASTC_ERROR \fP Optimize for lowest UASTC error\&. .TP \f(BIKTX_PACK_UASTC_FAVOR_BC7_ERROR \fP Optimize for lowest BC7 error\&. .TP \f(BIKTX_PACK_UASTC_ETC1_FASTER_HINTS \fP Optimize for faster transcoding to ETC1\&. .TP \f(BIKTX_PACK_UASTC_ETC1_FASTEST_HINTS \fP Optimize for fastest transcoding to ETC1\&. .TP \f(BIKTX_PACK_UASTC__ETC1_DISABLE_FLIP_AND_INDIVIDUAL \fP Not documented in BasisU code\&. .SS "enum \fBktx_transcode_flag_bits_e\fP" .PP Flags guiding transcoding of Basis Universal compressed textures\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_TF_PVRTC_DECODE_TO_NEXT_POW2 \fP 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\&. .TP \f(BIKTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS \fP 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\&. .TP \f(BIKTX_TF_HIGH_QUALITY \fP Request higher quality transcode of UASTC to BC1, BC3, ETC2_EAC_R11 and ETC2_EAC_RG11\&. The flag is unused by other UASTC transcoders\&. .SS "enum \fBktx_transcode_fmt_e\fP" .PP Enumerators for specifying the transcode target format\&. For BasisU/ETC1S format, \fIOpaque\fP and \fIalpha\fP 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\&. .PP \fBNote\fP .RS 4 You should not transcode sRGB encoded data to \fRKTX_TTF_BC4_R\fP, \fRKTX_TTF_BC5_RG\fP, \fRKTX_TTF_ETC2_EAC_R{\fP,G}11, \fRKTX_TTF_RGB565\fP, \fRKTX_TTF_BGR565\fP or \fRKTX_TTF_RGBA4444\fP 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\&. .RE .PP .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_TTF_ETC1_RGB \fP Opaque only\&. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified\&. .TP \f(BIKTX_TTF_ETC2_RGBA \fP Opaque+alpha\&. EAC_A8 block followed by an ETC1 block\&. The alpha channel will be opaque for textures without an alpha channel\&. .TP \f(BIKTX_TTF_BC1_RGB \fP Opaque only, no punchthrough alpha support yet\&. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified\&. .TP \f(BIKTX_TTF_BC3_RGBA \fP Opaque+alpha\&. BC4 block with alpha followed by a BC1 block\&. The alpha channel will be opaque for textures without an alpha channel\&. .TP \f(BIKTX_TTF_BC4_R \fP One BC4 block\&. R = opaque\&.g or alpha\&.g, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified\&. .TP \f(BIKTX_TTF_BC5_RG \fP 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\&. .TP \f(BIKTX_TTF_BC7_RGBA \fP RGB or RGBA mode 5 for ETC1S, modes 1, 2, 3, 4, 5, 6, 7 for UASTC\&. .TP \f(BIKTX_TTF_PVRTC1_4_RGB \fP Opaque only\&. Returns RGB or alpha data, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified\&. .TP \f(BIKTX_TTF_PVRTC1_4_RGBA \fP 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\&. .TP \f(BIKTX_TTF_ASTC_4x4_RGBA \fP 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\&. .TP \f(BIKTX_TTF_PVRTC2_4_RGB \fP Opaque-only\&. Almost BC1 quality, much faster to transcode and supports arbitrary texture dimensions (unlike PVRTC1 RGB)\&. .TP \f(BIKTX_TTF_PVRTC2_4_RGBA \fP 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\&. .TP \f(BIKTX_TTF_ETC2_EAC_R11 \fP R only (ETC2 EAC R11 unsigned)\&. R = opaque\&.g or alpha\&.g, if KTX_TF_TRANSCODE_ALPHA_DATA_TO_OPAQUE_FORMATS flag is specified\&. .TP \f(BIKTX_TTF_ETC2_EAC_RG11 \fP 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\&. .TP \f(BIKTX_TTF_RGBA32 \fP 32bpp RGBA image stored in raster (not block) order in memory, R is first byte, A is last byte\&. .TP \f(BIKTX_TTF_RGB565 \fP 16bpp RGB image stored in raster (not block) order in memory, R at bit position 11\&. .TP \f(BIKTX_TTF_BGR565 \fP 16bpp RGB image stored in raster (not block) order in memory, R at bit position 0\&. .TP \f(BIKTX_TTF_RGBA4444 \fP 16bpp RGBA image stored in raster (not block) order in memory, R at bit position 12, A at bit position 0\&. .TP \f(BIKTX_TTF_ETC \fP Automatically selects \fRKTX_TTF_ETC1_RGB\fP or \fRKTX_TTF_ETC2_RGBA\fP according to presence of alpha\&. .TP \f(BIKTX_TTF_BC1_OR_3 \fP Automatically selects \fRKTX_TTF_BC1_RGB\fP or \fRKTX_TTF_BC3_RGBA\fP according to presence of alpha\&. .TP \f(BIKTX_TF_ETC1 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_ETC1_RGB\fP\&. .RE .PP .TP \f(BIKTX_TF_ETC2 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_ETC\fP\&. .RE .PP .TP \f(BIKTX_TF_BC1 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC1_RGB\fP\&. .RE .PP .TP \f(BIKTX_TF_BC3 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC3_RGBA\fP\&. .RE .PP .TP \f(BIKTX_TF_BC4 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC4_R\fP\&. .RE .PP .TP \f(BIKTX_TF_BC5 \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC5_RG\fP\&. .RE .PP .TP \f(BIKTX_TTF_BC7_M6_RGB \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC7_RGBA\fP\&. .RE .PP .TP \f(BIKTX_TTF_BC7_M5_RGBA \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC7_RGBA\fP\&. .RE .PP .TP \f(BIKTX_TF_BC7_M6_OPAQUE_ONLY \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_BC7_RGBA\fP .RE .PP .TP \f(BIKTX_TF_PVRTC1_4_OPAQUE_ONLY \fP .PP \fBDeprecated\fP .RS 4 Use \fBKTX_TTF_PVRTC1_4_RGB\fP\&. .RE .PP .SS "enum \fBktxSupercmpScheme\fP" .PP Enumerators identifying the supercompression scheme\&. .PP \fBEnumerator\fP .in +1c .TP \f(BIKTX_SS_NONE \fP No supercompression\&. .TP \f(BIKTX_SS_BASIS_LZ \fP Basis LZ supercompression\&. .TP \f(BIKTX_SS_ZSTD \fP ZStd supercompression\&. .TP \f(BIKTX_SS_ZLIB \fP ZLIB supercompression\&. .SH "Function Documentation" .PP .SS "KTX_API const char *KTX_APIENTRY ktxErrorString (\fBKTX_error_code\fP error)" .PP Return a string corresponding to a KTX error code\&. .PP \fBParameters\fP .RS 4 \fIerror\fP the error code for which to return a string .RE .PP \fBReturns\fP .RS 4 pointer to the message string\&. .RE .PP .PP \fBExamples\fP .in +1c \fBvkload\&.cpp\fP\&. .SS "KTX_API const char *KTX_APIENTRY ktxSupercompressionSchemeString (\fBktxSupercmpScheme\fP scheme)" .PP Return a string corresponding to a supercompressionScheme enumeration\&. .PP \fBParameters\fP .RS 4 \fIscheme\fP the supercompression scheme for which to return a string\&. .RE .PP \fBReturns\fP .RS 4 pointer to the message string\&. .RE .PP .SS "KTX_API const char *KTX_APIENTRY ktxTranscodeFormatString (\fBktx_transcode_fmt_e\fP format)" .PP Return a string corresponding to a transcode format enumeration\&. .PP \fBParameters\fP .RS 4 \fIformat\fP the transcode format for which to return a string\&. .RE .PP \fBReturns\fP .RS 4 pointer to the message string\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for libktx Reference from the source code\&.