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] This pointer 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] This pointer 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]	This	pointer to the ktxTexture object of interest.
[in]	level	mip level of the image.
[in]	layer	array layer of the image.
[in]	faceSlice	cube map face or depth slice of the image.
[in,out]	pOffset	pointer to location to store the offset.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_OPERATION	`level`, `layer` or `faceSlice` exceed the dimensions of the texture.
KTX_INVALID_OPERATION	Texture is supercompressed.
KTX_INVALID_VALID	`This` 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]	This	pointer to the ktxTexture2 object of interest.
[in]	level	level 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]	This	handle of the ktxTexture opened on the data.
[in,out]	iterCb	the address of a callback function which is called with the data for each image block.
[in,out]	userdata	the 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_ERROR	Mip level sizes are increasing not decreasing
KTX_INVALID_OPERATION	supercompressionScheme != SUPERCOMPRESSION_NONE.
KTX_INVALID_VALUE	`This` 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]	This	pointer to the ktxTexture2 object of interest.
[in,out]	iterCb	the address of a callback function which is called with the data for each image.
[in,out]	userdata	the 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_ERROR	mip level sizes are increasing not decreasing
KTX_INVALID_OPERATION	the 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_OPERATION	supercompressionScheme != KTX_SS_NONE, supercompressionScheme != KTX_SS_ZSTD, and supercompressionScheme != KTX_SS_ZLIB.
KTX_INVALID_VALUE	`This` is `NULL` or `iterCb` is `NULL`.
KTX_OUT_OF_MEMORY	not 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]	This	pointer to the ktxTexture object of interest.
[in]	pBuffer	pointer to the buffer in which to load the image data.
[in]	bufSize	size of the buffer pointed at by `pBuffer`.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` is NULL.
KTX_INVALID_VALUE	`bufSize` is less than the the image data size.
KTX_INVALID_OPERATION	The data has already been loaded or the ktxTexture was not created from a KTX source.
KTX_OUT_OF_MEMORY	Insufficient 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] This pointer 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]	This	pointer to the target ktxTexture object.
[in]	level	mip level of the image to set.
[in]	layer	array layer of the image to set.
[in]	faceSlice	cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level.
[in]	src	pointer to the image source in memory.
[in]	srcSize	size of the source image in bytes.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` or `src` is NULL.
KTX_INVALID_VALUE	`srcSize` != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATION	No 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]	This	pointer to the target ktxTexture object.
[in]	level	mip level of the image to set.
[in]	layer	array layer of the image to set.
[in]	faceSlice	cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level.
[in]	src	stdio stream pointer to the source.
[in]	srcSize	size of the source image in bytes.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` or `src` is NULL.
KTX_INVALID_VALUE	`srcSize` != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATION	No 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);

Parameters

[in]	This	pointer to the target ktxTexture object.
[in,out]	ppDstBytes	pointer to location to write the address of the destination memory. The Application is responsible for freeing this memory.
[in,out]	pSize	pointer 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_VALUE	`This`, `ppDstBytes` or `pSize` is NULL.
KTX_INVALID_OPERATION	The ktxTexture does not contain any image data.
KTX_INVALID_OPERATION	Both kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An 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]	This	pointer to the target ktxTexture object.
[in]	dstname	destination file name.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` or `dstname` is NULL.
KTX_INVALID_OPERATION	The ktxTexture does not contain any image data.
KTX_INVALID_OPERATION	Both kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An 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]	This	pointer to the target ktxTexture object.
[in]	dstsstr	destination stdio stream.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` or `dstsstr` is NULL.
KTX_INVALID_OPERATION	The ktxTexture does not contain any image data.
KTX_INVALID_OPERATION	Both kvDataHead and kvData are set in the ktxTexture
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An 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]	This	pointer to the target ktxTexture object.
[in]	dststr	destination ktxStream.

Returns: KTX_SUCCESS on success, other KTX_* enum values on error.

Exceptions

KTX_INVALID_VALUE	`This` or `dststr` is NULL.
KTX_INVALID_OPERATION	The ktxTexture does not contain any image data.
KTX_INVALID_OPERATION	Both kvDataHead and kvData are set in the ktxTexture
KTX_INVALID_OPERATION	The length of the already set writerId metadata plus the library's version id exceeds the maximum allowed.
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An error occurred while writing the file.

Typedef Documentation

◆ ktx_transcode_fmt_e

typedef enum ktx_transcode_fmt_e 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

typedef struct ktxBasisParams 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;

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

enum 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

enum 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

enum 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

enum 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

enum 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

enum 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

enum 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

error the 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

scheme the 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

format the transcode format for which to return a string.

Returns: pointer to the message string.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ KTX_error_code

◆ ktx_texture_decode_flags

◆ ktx_texture_transcode_fmt_e

◆ ktxTexture

◆ ktxTexture_Destroy

◆ ktxTexture_GetDataSizeUncompressed

◆ ktxTexture_GetImageOffset

◆ ktxTexture_GetImageSize

◆ ktxTexture_GetSize

◆ ktxTexture_IterateLevels

◆ ktxTexture_IterateLoadLevelFaces

◆ ktxTexture_LoadImageData

◆ ktxTexture_NeedsTranscoding

◆ ktxTexture_SetImageFromMemory

◆ ktxTexture_SetImageFromStdioStream

◆ ktxTexture_WriteToMemory

◆ ktxTexture_WriteToNamedFile

◆ ktxTexture_WriteToStdioStream

◆ ktxTexture_WriteToStream

Typedef Documentation

◆ ktx_transcode_fmt_e

◆ ktxAstcParams

◆ ktxBasisParams

Enumeration Type Documentation

◆ ktx_error_code_e

◆ ktx_pack_astc_block_dimension_e

◆ ktx_pack_astc_quality_levels_e

◆ ktx_pack_uastc_flag_bits_e

◆ ktx_transcode_flag_bits_e

◆ ktx_transcode_fmt_e

◆ ktxSupercmpScheme

Function Documentation

◆ ktxErrorString()

◆ ktxSupercompressionSchemeString()

◆ ktxTranscodeFormatString()