Write KTX-formatted data. More...

Functions
KTX_error_code	ktxTexture2_CompressAstcEx (ktxTexture2 This, ktxAstcParams params)
	Encode and compress a ktx texture with uncompressed images to astc.

KTX_error_code	ktxTexture2_CompressAstc (ktxTexture2 *This, ktx_uint32_t quality)
	Encode and compress a ktx texture with uncompressed images to astc.

KTX_error_code	ktxTexture2_CompressBasisEx (ktxTexture2 This, ktxBasisParams params)
	Encode and possibly Supercompress a KTX2 texture with uncompressed images.

KTX_error_code	ktxTexture2_CompressBasis (ktxTexture2 *This, ktx_uint32_t quality)
	Supercompress a KTX2 texture with uncompressed images.

KTX_error_code	ktxTexture1_Create (ktxTextureCreateInfo createInfo, ktxTextureCreateStorageEnum storageAllocation, ktxTexture1 *newTex)
	Create a new empty ktxTexture1.

KTX_error_code	ktxTexture2_Create (ktxTextureCreateInfo createInfo, ktxTextureCreateStorageEnum storageAllocation, ktxTexture2 *newTex)
	Create a new empty ktxTexture2.

KTX_error_code	ktxTexture2_CreateCopy (ktxTexture2 orig, ktxTexture2 *newTex)
	Create a ktxTexture2 by making a copy of a ktxTexture2.

KTX_error_code	ktxTexture1_SetImageFromStdioStream (ktxTexture1 This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE src, ktx_size_t srcSize)
	Set image for level, layer, faceSlice from a stdio stream source.

KTX_error_code	ktxTexture1_SetImageFromMemory (ktxTexture1 This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t src, ktx_size_t srcSize)
	Set image for level, layer, faceSlice from an image in memory.

KTX_error_code	ktxTexture1_WriteToStream (ktxTexture1 This, ktxStream dststr)
	Write a ktxTexture object to a ktxStream in KTX format.

KTX_error_code	ktxTexture1_WriteToStdioStream (ktxTexture1 This, FILE dstsstr)
	Write a ktxTexture object to a stdio stream in KTX format.

KTX_error_code	ktxTexture1_WriteToNamedFile (ktxTexture1 This, const char const dstname)
	Write a ktxTexture object to a named file in KTX format.

KTX_error_code	ktxTexture1_WriteToMemory (ktxTexture1 This, ktx_uint8_t ppDstBytes, ktx_size_t pSize)
	Write a ktxTexture object to block of memory in KTX format.

KTX_error_code	ktxTexture1_WriteKTX2ToStream (ktxTexture1 This, ktxStream dststr)
	Write a ktxTexture object to a ktxStream in KTX 2 format.

KTX_error_code	ktxTexture1_WriteKTX2ToStdioStream (ktxTexture1 This, FILE dstsstr)
	Write a ktxTexture object to a stdio stream in KTX2 format.

KTX_error_code	ktxTexture1_WriteKTX2ToNamedFile (ktxTexture1 This, const char const dstname)
	Write a ktxTexture object to a named file in KTX2 format.

KTX_error_code	ktxTexture1_WriteKTX2ToMemory (ktxTexture1 This, ktx_uint8_t ppDstBytes, ktx_size_t pSize)
	Write a ktxTexture object to block of memory in KTX2 format.

KTX_error_code	ktxTexture2_SetImageFromStdioStream (ktxTexture2 This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE src, ktx_size_t srcSize)
	Set image for level, layer, faceSlice from a stdio stream source.

KTX_error_code	ktxTexture2_SetImageFromMemory (ktxTexture2 This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t src, ktx_size_t srcSize)
	Set image for level, layer, faceSlice from an image in memory.

KTX_error_code	ktxTexture2_WriteToStream (ktxTexture2 This, ktxStream dststr)
	Write a ktxTexture object to a ktxStream in KTX format.

KTX_error_code	ktxTexture2_WriteToStdioStream (ktxTexture2 This, FILE dstsstr)
	Write a ktxTexture object to a stdio stream in KTX format.

KTX_error_code	ktxTexture2_WriteToNamedFile (ktxTexture2 This, const char const dstname)
	Write a ktxTexture object to a named file in KTX format.

KTX_error_code	ktxTexture2_WriteToMemory (ktxTexture2 This, ktx_uint8_t ppDstBytes, ktx_size_t pSize)
	Write a ktxTexture object to block of memory in KTX format.

KTX_error_code	ktxTexture2_DeflateZstd (ktxTexture2 *This, ktx_uint32_t compressionLevel)
	Deflate the data in a ktxTexture2 object using Zstandard.

KTX_error_code	ktxTexture2_DeflateZLIB (ktxTexture2 *This, ktx_uint32_t compressionLevel)
	Deflate the data in a ktxTexture2 object using miniz (ZLIB).

Detailed Description

Write KTX-formatted data.

Function Documentation

◆ ktxTexture1_Create()

KTX_error_code ktxTexture1_Create	(	ktxTextureCreateInfo *	createInfo,
		ktxTextureCreateStorageEnum	storageAllocation,
		ktxTexture1 **	newTex
	)

Create a new empty ktxTexture1.

The address of the newly created ktxTexture1 is written to the location pointed at by newTex.

Parameters

[in]	createInfo	pointer to a ktxTextureCreateInfo struct with information describing the texture.
[in]	storageAllocation	enum indicating whether or not to allocate storage for the texture images.
[in,out]	newTex	pointer to a location in which store the address of the newly created texture.

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

Exceptions

KTX_INVALID_VALUE	`glInternalFormat` in `createInfo` is not a valid OpenGL internal format value.
KTX_INVALID_VALUE	`numDimensions` in `createInfo` is not 1, 2 or 3.
KTX_INVALID_VALUE	One of `base{Width,Height,Depth}` in `createInfo` is 0.
KTX_INVALID_VALUE	`numFaces` in `createInfo` is not 1 or 6.
KTX_INVALID_VALUE	`numLevels` in `createInfo` is 0.
KTX_INVALID_OPERATION	The `base{Width,Height,Depth}` specified in `createInfo` are inconsistent with `numDimensions`.
KTX_INVALID_OPERATION	`createInfo` is requesting a 3D array or 3D cubemap texture.
KTX_INVALID_OPERATION	`createInfo` is requesting a cubemap with non-square or non-2D images.
KTX_INVALID_OPERATION	`createInfo` is requesting more mip levels than needed for the specified `base{Width,Height,Depth}`.
KTX_OUT_OF_MEMORY	Not enough memory for the texture's images.

◆ ktxTexture1_SetImageFromMemory()

KTX_error_code ktxTexture1_SetImageFromMemory	(	ktxTexture1 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		const ktx_uint8_t *	src,
		ktx_size_t	srcSize
	)

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. The copied image is padded as necessary to achieve the KTX-specified row alignment. No padding is done if the ktxTexture's isCompressed field is KTX_TRUE.

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

Warning: Do not use memcpy for this as it will not pad when necessary.

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.
[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.

◆ ktxTexture1_SetImageFromStdioStream()

KTX_error_code ktxTexture1_SetImageFromStdioStream	(	ktxTexture1 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		FILE *	src,
		ktx_size_t	srcSize
	)

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. The copied image is padded as necessary to achieve the KTX-specified row alignment. No padding is done if the ktxTexture's isCompressed field is KTX_TRUE.

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.
[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.

◆ ktxTexture1_WriteKTX2ToMemory()

KTX_error_code ktxTexture1_WriteKTX2ToMemory	(	ktxTexture1 *	This,
		ktx_uint8_t **	ppDstBytes,
		ktx_size_t *	pSize
	)

Write a ktxTexture object to block of memory in KTX2 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	The ktxTexture contains unknownY KTX- or ktx- prefixed metadata keys.
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An error occurred while writing the file.

◆ ktxTexture1_WriteKTX2ToNamedFile()

KTX_error_code ktxTexture1_WriteKTX2ToNamedFile	(	ktxTexture1 *	This,
		const char *const	dstname
	)

Write a ktxTexture object to a named file in KTX2 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	The ktxTexture contains unknownY KTX- or ktx- prefixed metadata keys.
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An error occurred while writing the file.

◆ ktxTexture1_WriteKTX2ToStdioStream()

KTX_error_code ktxTexture1_WriteKTX2ToStdioStream	(	ktxTexture1 *	This,
		FILE *	dstsstr
	)

Write a ktxTexture object to a stdio stream in KTX2 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	The ktxTexture contains unknownY KTX- or ktx- prefixed metadata keys.
KTX_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An error occurred while writing the file.

◆ ktxTexture1_WriteKTX2ToStream()

KTX_error_code ktxTexture1_WriteKTX2ToStream	(	ktxTexture1 *	This,
		ktxStream *	dststr
	)

Write a ktxTexture object to a ktxStream in KTX 2 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	The ktxTexture contains unknownY KTX- or ktx- prefixed metadata keys.
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.

◆ ktxTexture1_WriteToMemory()

KTX_error_code ktxTexture1_WriteToMemory	(	ktxTexture1 *	This,
		ktx_uint8_t **	ppDstBytes,
		ktx_size_t *	pSize
	)

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.

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.

◆ ktxTexture1_WriteToNamedFile()

KTX_error_code ktxTexture1_WriteToNamedFile	(	ktxTexture1 *	This,
		const char *const	dstname
	)

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.

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.

◆ ktxTexture1_WriteToStdioStream()

KTX_error_code ktxTexture1_WriteToStdioStream	(	ktxTexture1 *	This,
		FILE *	dstsstr
	)

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

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.

◆ ktxTexture1_WriteToStream()

KTX_error_code ktxTexture1_WriteToStream	(	ktxTexture1 *	This,
		ktxStream *	dststr
	)

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_FILE_OVERFLOW	The file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERROR	An error occurred while writing the file.

◆ ktxTexture2_CompressAstc()

KTX_error_code ktxTexture2_CompressAstc	(	ktxTexture2 *	This,
		ktx_uint32_t	quality
	)

Encode and compress a ktx texture with uncompressed images to astc.

The images are either encoded to ASTC block-compressed format. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state.

Such textures can be directly uploaded to a GPU via a graphics API.

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	quality	Compression quality, a value from 0 - 100. Higher=higher quality/slower speed. Lower=lower quality/faster speed. Negative values for quality are considered > 100.

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

Exceptions

KTX_INVALID_OPERATION	The texture is already supercompressed.
KTX_INVALID_OPERATION	The texture's image are in a block compressed format.
KTX_INVALID_OPERATION	The texture image's format is a packed format (e.g. RGB565).
KTX_INVALID_OPERATION	The texture image format's component size is not 8-bits.
KTX_INVALID_OPERATION	The texture's images are 1D. Only 2D images can be supercompressed.
KTX_OUT_OF_MEMORY	Not enough memory to carry out supercompression.

◆ ktxTexture2_CompressAstcEx()

KTX_error_code ktxTexture2_CompressAstcEx	(	ktxTexture2 *	This,
		ktxAstcParams *	params
	)

Encode and compress a ktx texture with uncompressed images to astc.

The images are encoded to ASTC block-compressed format. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state.

Such textures can be directly uploaded to a GPU via a graphics API.

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	params	pointer to ASTC params object.

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

Exceptions

KTX_INVALID_OPERATION	The texture's images are supercompressed.
KTX_INVALID_OPERATION	The texture's images are in a block compressed format.
KTX_INVALID_OPERATION	The texture image's format is a packed format (e.g. RGB565).
KTX_INVALID_OPERATION	The texture image format's component size is not 8-bits.
KTX_INVALID_OPERATION	The texture's images are 1D. Only 2D images can be supercompressed.
KTX_INVALID_OPERATION	ASTC compressor failed to compress image for any reason.
KTX_OUT_OF_MEMORY	Not enough memory to carry out compression.

◆ ktxTexture2_CompressBasis()

KTX_error_code ktxTexture2_CompressBasis	(	ktxTexture2 *	This,
		ktx_uint32_t	quality
	)

Supercompress a KTX2 texture with uncompressed images.

The images are encoded to ETC1S block-compressed format and supercompressed with Basis Universal. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state.

Such textures must be transcoded to a desired target block compressed format before they can be uploaded to a GPU via a graphics API.

See also: ktxTexture2_CompressBasisEx().

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	quality	Compression quality, a value from 1 - 255. Default is 128 which is selected if `quality` is 0. Lower=better compression/lower quality/faster. Higher=less compression/higher quality/slower.

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

Exceptions

KTX_INVALID_OPERATION	The texture is already supercompressed.
KTX_INVALID_OPERATION	The texture's image are in a block compressed format.
KTX_OUT_OF_MEMORY	Not enough memory to carry out supercompression.

◆ ktxTexture2_CompressBasisEx()

KTX_error_code ktxTexture2_CompressBasisEx	(	ktxTexture2 *	This,
		ktxBasisParams *	params
	)

Encode and possibly Supercompress a KTX2 texture with uncompressed images.

The images are either encoded to ETC1S block-compressed format and supercompressed with Basis LZ or they are encoded to UASTC block-compressed format. UASTC format is selected by setting the uastc field of params to KTX_TRUE. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state.

Such textures must be transcoded to a desired target block compressed format before they can be uploaded to a GPU via a graphics API.

See also: ktxTexture2_TranscodeBasis().

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	params	pointer to Basis params object.

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

Exceptions

KTX_INVALID_OPERATION	The texture's images are supercompressed.
KTX_INVALID_OPERATION	The texture's images are in a block compressed format.
KTX_INVALID_OPERATION	The texture image's format is a packed format (e.g. RGB565).
KTX_INVALID_OPERATION	The texture image format's component size is not 8-bits.
KTX_INVALID_OPERATION	`normalMode` is specified but the texture has only one component.
KTX_INVALID_OPERATION	Both preSwizzle and and inputSwizzle are specified in params.
KTX_OUT_OF_MEMORY	Not enough memory to carry out compression.

◆ ktxTexture2_Create()

KTX_error_code ktxTexture2_Create	(	ktxTextureCreateInfo *	createInfo,
		ktxTextureCreateStorageEnum	storageAllocation,
		ktxTexture2 **	newTex
	)

Create a new empty ktxTexture2.

The address of the newly created ktxTexture2 is written to the location pointed at by newTex.

Parameters

[in]	createInfo	pointer to a ktxTextureCreateInfo struct with information describing the texture.
[in]	storageAllocation	enum indicating whether or not to allocate storage for the texture images.
[in,out]	newTex	pointer to a location in which store the address of the newly created texture.

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

Exceptions

KTX_INVALID_VALUE	`glInternalFormat` in `createInfo` is not a valid OpenGL internal format value.
KTX_INVALID_VALUE	`numDimensions` in `createInfo` is not 1, 2 or 3.
KTX_INVALID_VALUE	One of `base{Width,Height,Depth}` in `createInfo` is 0.
KTX_INVALID_VALUE	`numFaces` in `createInfo` is not 1 or 6.
KTX_INVALID_VALUE	`numLevels` in `createInfo` is 0.
KTX_INVALID_OPERATION	The `base{Width,Height,Depth}` specified in `createInfo` are inconsistent with `numDimensions`.
KTX_INVALID_OPERATION	`createInfo` is requesting a 3D array or 3D cubemap texture.
KTX_INVALID_OPERATION	`createInfo` is requesting a cubemap with non-square or non-2D images.
KTX_INVALID_OPERATION	`createInfo` is requesting more mip levels than needed for the specified `base{Width,Height,Depth}`.
KTX_OUT_OF_MEMORY	Not enough memory for the texture's images.

◆ ktxTexture2_CreateCopy()

KTX_error_code ktxTexture2_CreateCopy	(	ktxTexture2 *	orig,
		ktxTexture2 **	newTex
	)

Create a ktxTexture2 by making a copy of a ktxTexture2.

The address of the newly created ktxTexture2 is written to the location pointed at by newTex.

Parameters

[in]	orig	pointer to the texture to copy.
[in,out]	newTex	pointer to a location in which store the address of the newly created texture.

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

Exceptions

KTX_OUT_OF_MEMORY Not enough memory for the texture data.

◆ ktxTexture2_DeflateZLIB()

KTX_error_code ktxTexture2_DeflateZLIB	(	ktxTexture2 *	This,
		ktx_uint32_t	compressionLevel
	)

Deflate the data in a ktxTexture2 object using miniz (ZLIB).

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

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	compressionLevel	set speed vs compression ratio trade-off. Values between 1 and 9 are accepted. The lower the level the faster.

◆ ktxTexture2_DeflateZstd()

KTX_error_code ktxTexture2_DeflateZstd	(	ktxTexture2 *	This,
		ktx_uint32_t	compressionLevel
	)

Deflate the data in a ktxTexture2 object using Zstandard.

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

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	compressionLevel	set speed vs compression ratio trade-off. Values between 1 and 22 are accepted. The lower the level the faster. Values above 20 should be used with caution as they require more memory.

◆ ktxTexture2_SetImageFromMemory()

KTX_error_code ktxTexture2_SetImageFromMemory	(	ktxTexture2 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		const ktx_uint8_t *	src,
		ktx_size_t	srcSize
	)

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.

◆ ktxTexture2_SetImageFromStdioStream()

KTX_error_code ktxTexture2_SetImageFromStdioStream	(	ktxTexture2 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		FILE *	src,
		ktx_size_t	srcSize
	)

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.

◆ ktxTexture2_WriteToMemory()

KTX_error_code ktxTexture2_WriteToMemory	(	ktxTexture2 *	This,
		ktx_uint8_t **	ppDstBytes,
		ktx_size_t *	pSize
	)

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.

◆ ktxTexture2_WriteToNamedFile()

KTX_error_code ktxTexture2_WriteToNamedFile	(	ktxTexture2 *	This,
		const char *const	dstname
	)

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.

◆ ktxTexture2_WriteToStdioStream()

KTX_error_code ktxTexture2_WriteToStdioStream	(	ktxTexture2 *	This,
		FILE *	dstsstr
	)

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.

◆ ktxTexture2_WriteToStream()

KTX_error_code ktxTexture2_WriteToStream	(	ktxTexture2 *	This,
		ktxStream *	dststr
	)

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.

Functions

Detailed Description

Function Documentation

◆ ktxTexture1_Create()

◆ ktxTexture1_SetImageFromMemory()

◆ ktxTexture1_SetImageFromStdioStream()

◆ ktxTexture1_WriteKTX2ToMemory()

◆ ktxTexture1_WriteKTX2ToNamedFile()

◆ ktxTexture1_WriteKTX2ToStdioStream()

◆ ktxTexture1_WriteKTX2ToStream()

◆ ktxTexture1_WriteToMemory()

◆ ktxTexture1_WriteToNamedFile()

◆ ktxTexture1_WriteToStdioStream()

◆ ktxTexture1_WriteToStream()

◆ ktxTexture2_CompressAstc()

◆ ktxTexture2_CompressAstcEx()

◆ ktxTexture2_CompressBasis()

◆ ktxTexture2_CompressBasisEx()

◆ ktxTexture2_Create()

◆ ktxTexture2_CreateCopy()

◆ ktxTexture2_DeflateZLIB()

◆ ktxTexture2_DeflateZstd()

◆ ktxTexture2_SetImageFromMemory()

◆ ktxTexture2_SetImageFromStdioStream()

◆ ktxTexture2_WriteToMemory()

◆ ktxTexture2_WriteToNamedFile()

◆ ktxTexture2_WriteToStdioStream()

◆ ktxTexture2_WriteToStream()