Reader

Read KTX-formatted data. More...

Functions
KTX_error_code	ktxTexture2_TranscodeBasis (ktxTexture2 *This, ktx_transcode_fmt_e outputFormat, ktx_transcode_flags transcodeFlags)
	Transcode a KTX2 texture with BasisLZ/ETC1S or UASTC images.
KTX_error_code	ktxTexture_CreateFromStream (ktxStream *pStream, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
	Create a ktx1 or ktx2 texture according to the stream data.
KTX_error_code	ktxTexture_CreateFromStdioStream (FILE *stdioStream, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
	Create a ktxTexture1 or ktxTexture2 from a stdio stream according to the stream data.
KTX_error_code	ktxTexture_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
	Create a ktxTexture1 or ktxTexture2 from a named KTX file according to the file contents.
KTX_error_code	ktxTexture_CreateFromMemory (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
	Create a ktxTexture1 or ktxTexture2 from KTX-formatted data in memory according to the data contents.
ktx_uint8_t *	ktxTexture_GetData (ktxTexture *This)
	Return a pointer to the texture image data.
ktx_size_t	ktxTexture_GetDataSize (ktxTexture *This)
	Return the total size of the texture image data in bytes.
ktx_uint32_t	ktxTexture_GetElementSize (ktxTexture *This)
	Return the size in bytes of an elements of a texture's images.
KTX_error_code	ktxTexture_IterateLevelFaces (ktxTexture *This, PFNKTXITERCB iterCb, void *userdata)
	Iterate over the levels or faces in a ktxTexture object.
ktx_uint32_t	ktxTexture_GetRowPitch (ktxTexture *This, ktx_uint32_t level)
	Return pitch betweeb rows of a texture image level in bytes.
KTX_error_code	ktxTexture1_CreateFromStdioStream (FILE *stdioStream, ktxTextureCreateFlags createFlags, ktxTexture1 **newTex)
	Create a ktxTexture1 from a stdio stream reading from a KTX source.
KTX_error_code	ktxTexture1_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, ktxTexture1 **newTex)
	Create a ktxTexture1 from a named KTX file.
KTX_error_code	ktxTexture1_CreateFromMemory (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, ktxTexture1 **newTex)
	Create a ktxTexture1 from KTX-formatted data in memory.
KTX_error_code	ktxTexture1_CreateFromStream (ktxStream *pStream, ktxTextureCreateFlags createFlags, ktxTexture1 **newTex)
	Create a ktxTexture1 from KTX-formatted data from a ktxStream.
void	ktxTexture1_Destroy (ktxTexture1 *This)
	Destroy a ktxTexture1 object.
KTX_error_code	ktxTexture1_GetImageOffset (ktxTexture1 *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t *pOffset)
	Find the offset of an image within a ktxTexture's image data.
ktx_size_t	ktxTexture1_GetDataSizeUncompressed (ktxTexture1 *This)
	Return the total size in bytes of the uncompressed data of a ktxTexture1.
ktx_size_t	ktxTexture1_GetImageSize (ktxTexture1 *This, ktx_uint32_t level)
	Calculate & return the size in bytes of an image at the specified mip level.
KTX_error_code	ktxTexture1_IterateLevels (ktxTexture1 *This, PFNKTXITERCB iterCb, void *userdata)
	Iterate over the mip levels in a ktxTexture1 object.
KTX_error_code	ktxTexture1_IterateLoadLevelFaces (ktxTexture1 *This, PFNKTXITERCB iterCb, void *userdata)
	Iterate over the images in a ktxTexture1 object while loading the image data.
KTX_error_code	ktxTexture1_LoadImageData (ktxTexture1 *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)
	Load all the image data from the ktxTexture1's source.
KTX_error_code	ktxTexture2_CreateFromStdioStream (FILE *stdioStream, ktxTextureCreateFlags createFlags, ktxTexture2 **newTex)
	Create a ktxTexture2 from a stdio stream reading from a KTX source.
KTX_error_code	ktxTexture2_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, ktxTexture2 **newTex)
	Create a ktxTexture2 from a named KTX file.
KTX_error_code	ktxTexture2_CreateFromMemory (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, ktxTexture2 **newTex)
	Create a ktxTexture2 from KTX-formatted data in memory.
KTX_error_code	ktxTexture2_CreateFromStream (ktxStream *stream, ktxTextureCreateFlags createFlags, ktxTexture2 **newTex)
	Create a ktxTexture2 from KTX-formatted data from a stream.
void	ktxTexture2_Destroy (ktxTexture2 *This)
	Destroy a ktxTexture2 object.
void	ktxTexture2_GetComponentInfo (ktxTexture2 *This, uint32_t *pNumComponents, uint32_t *pComponentByteLength)
	Return information about the components of an image in a texture.
ktx_uint32_t	ktxTexture2_GetNumComponents (ktxTexture2 *This)
	Return the number of components in an image of the texture.
KTX_error_code	ktxTexture2_GetImageOffset (ktxTexture2 *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t *pOffset)
	Find the offset of an image within a ktxTexture's image data.
khr_df_transfer_e	ktxTexture2_GetOETF_e (ktxTexture2 *This)
	Retrieve the opto-electrical transfer function of the images.
ktx_uint32_t	ktxTexture2_GetOETF (ktxTexture2 *This)
	Retrieve the opto-electrical transfer function of the images.
khr_df_model_e	ktxTexture2_GetColorModel_e (ktxTexture2 *This)
	Retrieve the DFD color model of the images.
ktx_bool_t	ktxTexture2_GetPremultipliedAlpha (ktxTexture2 *This)
	Retrieve whether the RGB components have been premultiplied by the alpha component.
ktx_bool_t	ktxTexture2_NeedsTranscoding (ktxTexture2 *This)
	Query if the images are in a transcodable format.
ktx_size_t	ktxTexture2_GetDataSizeUncompressed (ktxTexture2 *This)
	Return the total size in bytes of the uncompressed data of a ktxTexture2.
ktx_size_t	ktxTexture2_GetImageSize (ktxTexture2 *This, ktx_uint32_t level)
	Calculate & return the size in bytes of an image at the specified mip level.
KTX_error_code	ktxTexture2_IterateLevels (ktxTexture2 *This, PFNKTXITERCB iterCb, void *userdata)
	Iterate over the mip levels in a ktxTexture2 object.
KTX_error_code	ktxTexture2_IterateLoadLevelFaces (ktxTexture2 *This, PFNKTXITERCB iterCb, void *userdata)
	Iterate over the images in a ktxTexture2 object while loading the image data.
KTX_error_code	ktxTexture2_LoadImageData (ktxTexture2 *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)
	Load all the image data from the ktxTexture2's source.

Detailed Description

Read KTX-formatted data.

Function Documentation

ktxTexture1_CreateFromMemory()

KTX_error_code ktxTexture1_CreateFromMemory	(	const ktx_uint8_t *	bytes,
		ktx_size_t	size,
		ktxTextureCreateFlags	createFlags,
		ktxTexture1 **	newTex
	)

Create a ktxTexture1 from KTX-formatted data in memory.

The address of a newly created texture reflecting the contents of the serialized KTX data is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture1 is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture1.

Parameters

[in]	bytes	pointer to the memory containing the serialized KTX data.
[in]	size	length of the KTX data in bytes.
[in]	createFlags	bitmask requesting specific actions during creation.
[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

Either bytes is NULL or size is 0.

For other exceptions, see ktxTexture1_CreateFromStdioStream().

ktxTexture1_CreateFromNamedFile()

KTX_error_code ktxTexture1_CreateFromNamedFile	(	const char *const	filename,
		ktxTextureCreateFlags	createFlags,
		ktxTexture1 **	newTex
	)

Create a ktxTexture1 from a named KTX file.

The address of a newly created texture reflecting the contents of the file is written to the location pointed at by newTex.

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

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture1 is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture1.

Parameters

[in]	filename	pointer to a char array containing the file name.
[in]	createFlags	bitmask requesting specific actions during creation.
[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_FILE_OPEN_FAILED	The file could not be opened.
KTX_INVALID_VALUE	filename is NULL.

For other exceptions, see ktxTexture1_CreateFromStdioStream().

ktxTexture1_CreateFromStdioStream()

KTX_error_code ktxTexture1_CreateFromStdioStream	(	FILE *	stdioStream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture1 **	newTex
	)

Create a ktxTexture1 from a stdio stream reading from a KTX source.

The address of a newly created texture reflecting the contents of the stdio stream is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture1 is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture1.

Parameters

[in]	stdioStream	stdio FILE pointer created from the desired file.
[in]	createFlags	bitmask requesting specific actions during creation.
[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	newTex is NULL.
KTX_FILE_DATA_ERROR	Source data is inconsistent with the KTX specification.
KTX_FILE_READ_ERROR	An error occurred while reading the source.
KTX_FILE_UNEXPECTED_EOF	Not enough data in the source.
KTX_OUT_OF_MEMORY	Not enough memory to create the texture object, load the images or load the key-value data.
KTX_UNKNOWN_FILE_FORMAT	The source is not in KTX format.
KTX_UNSUPPORTED_TEXTURE_TYPE	The source describes a texture type not supported by OpenGL or Vulkan, e.g, a 3D array.

ktxTexture1_CreateFromStream()

KTX_error_code ktxTexture1_CreateFromStream	(	ktxStream *	pStream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture1 **	newTex
	)

Create a ktxTexture1 from KTX-formatted data from a ktxStream.

The address of a newly created texture reflecting the contents of the serialized KTX data is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture1 is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture1.

Parameters

[in]	pStream	pointer to the stream to read KTX data from.
[in]	createFlags	bitmask requesting specific actions during creation.
[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.

For exceptions, see ktxTexture1_CreateFromStdioStream().

ktxTexture1_Destroy()

void ktxTexture1_Destroy

(

ktxTexture1 *

This

)

Destroy a ktxTexture1 object.

This frees the memory associated with the texture contents and the memory of the ktxTexture1 object. This does not delete any OpenGL or Vulkan texture objects created by ktxTexture1_GLUpload or ktxTexture1_VkUpload.

Parameters

[in]

This

pointer to the ktxTexture1 object to destroy

ktxTexture1_GetDataSizeUncompressed()

ktx_size_t ktxTexture1_GetDataSizeUncompressed

(

ktxTexture1 *

This

)

Return the total size in bytes of the uncompressed data of a ktxTexture1.

This always returns the value of This->dataSize. The function is provided for symmetry with ktxTexture2.

Parameters

[in]

This

pointer to the ktxTexture1 object of interest.

Returns

The size of the data in the texture.

ktxTexture1_GetImageOffset()

KTX_error_code ktxTexture1_GetImageOffset	(	ktxTexture1 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		ktx_size_t *	pOffset
	)

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.

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_VALID	This is NULL.

ktxTexture1_GetImageSize()

ktx_size_t ktxTexture1_GetImageSize	(	ktxTexture1 *	This,
		ktx_uint32_t	level
	)

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

For arrays, this is the size of 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 ktxTexture1 object of interest.
[in]	level	level of interest.

ktxTexture1_IterateLevels()

KTX_error_code ktxTexture1_IterateLevels	(	ktxTexture1 *	This,
		PFNKTXITERCB	iterCb,
		void *	userdata
	)

Iterate over the mip levels in a ktxTexture1 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.

Parameters

[in]	This	handle of the 1 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_VALUE	This is NULL or iterCb is NULL.

ktxTexture1_IterateLoadLevelFaces()

KTX_error_code ktxTexture1_IterateLoadLevelFaces	(	ktxTexture1 *	This,
		PFNKTXITERCB	iterCb,
		void *	userdata
	)

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

This operates similarly to ktxTexture_IterateLevelFaces except that it loads the images from the ktxTexture1's source to a temporary buffer while iterating. 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.

Parameters

[in]	This	pointer to the ktxTexture1 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 ktxTexture1 was not created from a stream, i.e there is no data to load, or this ktxTexture1's images have already been loaded.
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.

ktxTexture1_LoadImageData()

KTX_error_code ktxTexture1_LoadImageData	(	ktxTexture1 *	This,
		ktx_uint8_t *	pBuffer,
		ktx_size_t	bufSize
	)

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

The data is loaded into the provided buffer or to an internally allocated buffer, if pBuffer is NULL.

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.

ktxTexture2_CreateFromMemory()

KTX_error_code ktxTexture2_CreateFromMemory	(	const ktx_uint8_t *	bytes,
		ktx_size_t	size,
		ktxTextureCreateFlags	createFlags,
		ktxTexture2 **	newTex
	)

Create a ktxTexture2 from KTX-formatted data in memory.

The address of a newly created ktxTexture2 reflecting the contents of the serialized KTX data is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters

[in]	bytes	pointer to the memory containing the serialized KTX data.
[in]	size	length of the KTX data in bytes.
[in]	createFlags	bitmask requesting specific actions during creation.
[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

Either bytes is NULL or size is 0.

For other exceptions, see ktxTexture_CreateFromStdioStream().

ktxTexture2_CreateFromNamedFile()

KTX_error_code ktxTexture2_CreateFromNamedFile	(	const char *const	filename,
		ktxTextureCreateFlags	createFlags,
		ktxTexture2 **	newTex
	)

Create a ktxTexture2 from a named KTX file.

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

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

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters

[in]	filename	pointer to a char array containing the file name.
[in]	createFlags	bitmask requesting specific actions during creation.
[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_FILE_OPEN_FAILED	The file could not be opened.
KTX_INVALID_VALUE	filename is NULL.

For other exceptions, see ktxTexture_CreateFromStdioStream().

ktxTexture2_CreateFromStdioStream()

KTX_error_code ktxTexture2_CreateFromStdioStream	(	FILE *	stdioStream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture2 **	newTex
	)

Create a ktxTexture2 from a stdio stream reading from a KTX source.

The address of a newly created ktxTexture2 reflecting the contents of the stdio stream is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters

[in]	stdioStream	stdio FILE pointer created from the desired file.
[in]	createFlags	bitmask requesting specific actions during creation.
[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	newTex is NULL.
KTX_FILE_DATA_ERROR	Source data is inconsistent with the KTX specification.
KTX_FILE_READ_ERROR	An error occurred while reading the source.
KTX_FILE_UNEXPECTED_EOF	Not enough data in the source.
KTX_OUT_OF_MEMORY	Not enough memory to create the texture object, load the images or load the key-value data.
KTX_UNKNOWN_FILE_FORMAT	The source is not in KTX format.
KTX_UNSUPPORTED_TEXTURE_TYPE	The source describes a texture type not supported by OpenGL or Vulkan, e.g, a 3D array.

ktxTexture2_CreateFromStream()

KTX_error_code ktxTexture2_CreateFromStream	(	ktxStream *	stream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture2 **	newTex
	)

Create a ktxTexture2 from KTX-formatted data from a stream.

The address of a newly created ktxTexture2 reflecting the contents of the serialized KTX data is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture is ultimately to be uploaded to OpenGL or Vulkan. This will minimize memory usage by allowing, for example, loading the images directly from the source into a Vulkan staging buffer.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters

[in]	stream	pointer to the stream to read KTX data from.
[in]	createFlags	bitmask requesting specific actions during creation.
[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

Either bytes is NULL or size is 0.

For other exceptions, see ktxTexture_CreateFromStdioStream().

ktxTexture2_Destroy()

void ktxTexture2_Destroy

(

ktxTexture2 *

This

)

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

ktxTexture2_GetColorModel_e()

khr_df_model_e ktxTexture2_GetColorModel_e

(

ktxTexture2 *

This

)

Retrieve the DFD color model of the images.

Parameters

[in]

This

pointer to the ktxTexture2 object of interest.

Returns

A khr_df_transfer enum value specifying the color model.

ktxTexture2_GetComponentInfo()

void ktxTexture2_GetComponentInfo	(	ktxTexture2 *	This,
		uint32_t *	pNumComponents,
		uint32_t *	pComponentByteLength
	)

Return information about the components of an image in a texture.

Parameters

[in]	This	pointer to the ktxTexture object of interest.
[in,out]	pNumComponents	pointer to location in which to write the number of components in the textures images.
[in,out]	pComponentByteLength	pointer to the location in which to write byte length of a component.

ktxTexture2_GetDataSizeUncompressed()

ktx_size_t ktxTexture2_GetDataSizeUncompressed

(

ktxTexture2 *

This

)

Return the total size in bytes of the uncompressed data of a ktxTexture2.

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.

ktxTexture2_GetImageOffset()

KTX_error_code ktxTexture2_GetImageOffset	(	ktxTexture2 *	This,
		ktx_uint32_t	level,
		ktx_uint32_t	layer,
		ktx_uint32_t	faceSlice,
		ktx_size_t *	pOffset
	)

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.

ktxTexture2_GetImageSize()

ktx_size_t ktxTexture2_GetImageSize	(	ktxTexture2 *	This,
		ktx_uint32_t	level
	)

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

ktxTexture2_GetNumComponents()

ktx_uint32_t ktxTexture2_GetNumComponents

(

ktxTexture2 *

This

)

Return the number of components in an image of the texture.

Returns the number of components indicated by the DFD's sample information in accordance with the color model. For uncompressed formats it will be the actual number of components in the image. For block-compressed formats, it will be 1 or 2 according to the format's DFD color model. For Basis compressed textures, the function examines the ids of the channels indicated by the DFD and uses that information to determine and return the number of components in the image before encoding and deflation so it can be used to help choose a suitable transcode target format.

Parameters

[in]

This

pointer to the ktxTexture object of interest.

Returns

the number of components.

ktxTexture2_GetOETF()

ktx_uint32_t ktxTexture2_GetOETF

(

ktxTexture2 *

This

)

Retrieve the opto-electrical transfer function of the images.

Deprecated:

Retained for backward compatibility. Use ktxTexture2_GetOETF_e()

Parameters

[in]

This

pointer to the ktxTexture2 object of interest.

Returns

A khr_df_transfer enum value specifying the OETF, returned as ktx_uint32_t.

ktxTexture2_GetOETF_e()

khr_df_transfer_e ktxTexture2_GetOETF_e

(

ktxTexture2 *

This

)

Retrieve the opto-electrical transfer function of the images.

Parameters

[in]

This

pointer to the ktxTexture2 object of interest.

Returns

A khr_df_transfer enum value specifying the OETF.

ktxTexture2_GetPremultipliedAlpha()

ktx_bool_t ktxTexture2_GetPremultipliedAlpha

(

ktxTexture2 *

This

)

Retrieve whether the RGB components have been premultiplied by the alpha component.

Parameters

[in]

This

pointer to the ktxTexture2 object of interest.

Returns

KTX_TRUE if the components are premultiplied, KTX_FALSE otherwise.

ktxTexture2_IterateLevels()

KTX_error_code ktxTexture2_IterateLevels	(	ktxTexture2 *	This,
		PFNKTXITERCB	iterCb,
		void *	userdata
	)

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.

ktxTexture2_IterateLoadLevelFaces()

KTX_error_code ktxTexture2_IterateLoadLevelFaces	(	ktxTexture2 *	This,
		PFNKTXITERCB	iterCb,
		void *	userdata
	)

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.

ktxTexture2_LoadImageData()

KTX_error_code ktxTexture2_LoadImageData	(	ktxTexture2 *	This,
		ktx_uint8_t *	pBuffer,
		ktx_size_t	bufSize
	)

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.

ktxTexture2_NeedsTranscoding()

ktx_bool_t ktxTexture2_NeedsTranscoding

(

ktxTexture2 *

This

)

Query if the images are in a transcodable format.

Parameters

[in]

This

pointer to the ktxTexture2 object of interest.

ktxTexture2_TranscodeBasis()

KTX_error_code ktxTexture2_TranscodeBasis	(	ktxTexture2 *	This,
		ktx_transcode_fmt_e	outputFormat,
		ktx_transcode_flags	transcodeFlags
	)

Transcode a KTX2 texture with BasisLZ/ETC1S or UASTC images.

If the texture contains BasisLZ supercompressed images, Inflates them from back to ETC1S then transcodes them to the specified block-compressed format. If the texture contains UASTC images, inflates them, if they have been supercompressed with zstd, then transcodes then to the specified format, The transcoded images replace the original images and the texture's fields including the DFD are modified to reflect the new format.

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

The following block compressed transcode targets are available: KTX_TTF_ETC1_RGB, KTX_TTF_ETC2_RGBA, KTX_TTF_BC1_RGB, KTX_TTF_BC3_RGBA, KTX_TTF_BC4_R, KTX_TTF_BC5_RG, KTX_TTF_BC7_RGBA, KTX_TTF_PVRTC1_4_RGB, KTX_TTF_PVRTC1_4_RGBA, KTX_TTF_PVRTC2_4_RGB, KTX_TTF_PVRTC2_4_RGBA, KTX_TTF_ASTC_4x4_RGBA, KTX_TTF_ETC2_EAC_R11, KTX_TTF_ETC2_EAC_RG11, KTX_TTF_ETC and KTX_TTF_BC1_OR_3.

KTX_TTF_ETC automatically selects between KTX_TTF_ETC1_RGB and KTX_TTF_ETC2_RGBA according to whether an alpha channel is available. KTX_TTF_BC1_OR_3 does likewise between KTX_TTF_BC1_RGB and KTX_TTF_BC3_RGBA. Note that if KTX_TTF_PVRTC1_4_RGBA or KTX_TTF_PVRTC2_4_RGBA is specified and there is no alpha channel KTX_TTF_PVRTC1_4_RGB or KTX_TTF_PVRTC2_4_RGB respectively will be selected.

Transcoding to ATC & FXT1 formats is not supported by libktx as there are no equivalent Vulkan formats.

The following uncompressed transcode targets are also available: KTX_TTF_RGBA32, KTX_TTF_RGB565, KTX_TTF_BGR565 and KTX_TTF_RGBA4444.

The following transcodeFlags are available.

See also

ktxtexture2_CompressBasis().

Parameters

[in]	This	pointer to the ktxTexture2 object of interest.
[in]	outputFormat	a value from the ktx_texture_transcode_fmt_e enum specifying the target format.
[in]	transcodeFlags	bitfield of flags modifying the transcode operation.

See also

ktx_texture_decode_flags_e.

Returns

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

Exceptions

KTX_FILE_DATA_ERROR	Supercompression global data is corrupted.
KTX_INVALID_OPERATION	The texture's format is not transcodable (not ETC1S/BasisLZ or UASTC).
KTX_INVALID_OPERATION	Supercompression global data is missing, i.e., the texture object is invalid.
KTX_INVALID_OPERATION	Image data is missing, i.e., the texture object is invalid.
KTX_INVALID_OPERATION	outputFormat is PVRTC1 but the texture does does not have power-of-two dimensions.
KTX_INVALID_VALUE	outputFormat is invalid.
KTX_TRANSCODE_FAILED	Something went wrong during transcoding.
KTX_UNSUPPORTED_FEATURE	KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 was requested or the specified transcode target has not been included in the library being used.
KTX_OUT_OF_MEMORY	Not enough memory to carry out transcoding.

ktxTexture_CreateFromMemory()

KTX_error_code ktxTexture_CreateFromMemory	(	const ktx_uint8_t *	bytes,
		ktx_size_t	size,
		ktxTextureCreateFlags	createFlags,
		ktxTexture **	newTex
	)

Create a ktxTexture1 or ktxTexture2 from KTX-formatted data in memory according to the data contents.

See ktxTexture1_CreateFromMemory or ktxTexture2_CreateFromMemory for details.

ktxTexture_CreateFromNamedFile()

KTX_error_code ktxTexture_CreateFromNamedFile	(	const char *const	filename,
		ktxTextureCreateFlags	createFlags,
		ktxTexture **	newTex
	)

Create a ktxTexture1 or ktxTexture2 from a named KTX file according to the file contents.

See ktxTexture1_CreateFromNamedFile or ktxTexture2_CreateFromNamedFile for details.

ktxTexture_CreateFromStdioStream()

KTX_error_code ktxTexture_CreateFromStdioStream	(	FILE *	stdioStream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture **	newTex
	)

Create a ktxTexture1 or ktxTexture2 from a stdio stream according to the stream data.

See ktxTexture1_CreateFromStdioStream or ktxTexture2_CreateFromStdioStream for details.

ktxTexture_CreateFromStream()

KTX_error_code ktxTexture_CreateFromStream	(	ktxStream *	pStream,
		ktxTextureCreateFlags	createFlags,
		ktxTexture **	newTex
	)

Create a ktx1 or ktx2 texture according to the stream data.

See ktxTexture1_CreateFromStream or ktxTexture2_CreateFromStream for details.

ktxTexture_GetData()

ktx_uint8_t * ktxTexture_GetData

(

ktxTexture *

This

)

Return a pointer to the texture image data.

Parameters

[in]

This

pointer to the ktxTexture object of interest.

ktxTexture_GetDataSize()

ktx_size_t ktxTexture_GetDataSize

(

ktxTexture *

This

)

Return the total size of the texture image data in bytes.

For a ktxTexture2 with supercompressionScheme != KTX_SS_NONE this will return the deflated size of the data.

Parameters

[in]

This

pointer to the ktxTexture object of interest.

ktxTexture_GetElementSize()

ktx_uint32_t ktxTexture_GetElementSize

(

ktxTexture *

This

)

Return the size in bytes of an elements of a texture's images.

For uncompressed textures an element is one texel. For compressed textures it is one block.

Parameters

[in]

This

pointer to the ktxTexture object of interest.

ktxTexture_GetRowPitch()

ktx_uint32_t ktxTexture_GetRowPitch	(	ktxTexture *	This,
		ktx_uint32_t	level
	)

Return pitch betweeb rows of a texture image level in bytes.

For uncompressed textures the pitch is the number of bytes between rows of texels. For compressed textures it is the number of bytes between rows of blocks. The value is padded to GL_UNPACK_ALIGNMENT, if necessary. For all currently known compressed formats padding will not be necessary.

Parameters

[in]	This	pointer to the ktxTexture object of interest.
[in]	level	level of interest.

Returns

the row pitch in bytes.

ktxTexture_IterateLevelFaces()

KTX_error_code ktxTexture_IterateLevelFaces	(	ktxTexture *	This,
		PFNKTXITERCB	iterCb,
		void *	userdata
	)

Iterate over the levels or faces in a ktxTexture object.

Blocks of image data are passed to an application-supplied callback function. This is not a strict per-image iteration. Rather it reflects how OpenGL needs the images. For most textures the block of data includes all images of a mip level which implies all layers of an array. However, for non-array cube map textures the block is a single face of the mip level, i.e the callback is called once for each face.

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.

Parameters

[in]	This	pointer to the ktxTexture object of interest.
[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_VALUE	This is NULL or iterCb is NULL.