Read KTX-formatted data. More...

Functions
KTX_error_code	ktxTexture::ktxTexture_CreateFromStdioStream (FILE stdioStream, ktxTextureCreateFlags createFlags, ktxTexture *newTex)
	Create a ktxTexture from a stdio stream reading from a KTX source. More...

KTX_error_code	ktxTexture::ktxTexture_CreateFromNamedFile (const char const filename, ktxTextureCreateFlags createFlags, ktxTexture *newTex)
	Create a ktxTexture from a named KTX file. More...

KTX_error_code	ktxTexture::ktxTexture_CreateFromMemory (const ktx_uint8_t bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, ktxTexture *newTex)
	Create a ktxTexture from KTX-formatted data in memory. More...

void	ktxTexture::ktxTexture_Destroy (ktxTexture *This)
	Destroy a ktxTexture object. More...

ktx_uint8_t *	ktxTexture::ktxTexture_GetData (ktxTexture *This)
	Return a pointer to the texture image data. More...

ktx_size_t	ktxTexture::ktxTexture_GetSize (ktxTexture *This)
	Return the size of the texture image data in bytes. More...

KTX_error_code	ktxTexture::ktxTexture_LoadImageData (ktxTexture This, ktx_uint8_t pBuffer, ktx_size_t bufSize)
	Load all the image data from the ktxTexture's source. More...

KTX_error_code	ktxTexture::ktxTexture_IterateLevelFaces (ktxTexture This, PFNKTXITERCB iterCb, void userdata)
	Iterate over the images in a ktxTexture object. More...

KTX_error_code	ktxTexture::ktxTexture_IterateLoadLevelFaces (ktxTexture This, PFNKTXITERCB iterCb, void userdata)
	Iterate over the images in a ktxTexture object while loading the image data. More...

KTX_error_code	ktxTexture::ktxTexture_IterateLevels (ktxTexture This, PFNKTXITERCB iterCb, void userdata)
	Iterate over the mip levels in a ktxTexture object. More...

KTX_error_code	ktxTexture::ktxTexture_GetImageOffset (ktxTexture 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. More...

Detailed Description

Read KTX-formatted data.

Function Documentation

§ ktxTexture_CreateFromMemory()

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

Create a ktxTexture from KTX-formatted data in memory.

The address of a newly created ktxTexture 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().

§ ktxTexture_CreateFromNamedFile()

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

Create a ktxTexture from a named KTX file.

The address of a newly created ktxTexture reflecting the contents of the file 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]	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().

§ ktxTexture_CreateFromStdioStream()

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

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

The address of a newly created ktxTexture 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.

§ ktxTexture_Destroy()

void ktxTexture_Destroy ( ktxTexture * This )

Destroy a ktxTexture object.

This frees the memory associated with the texture contents and the memory of the ktxTexture object. This does not delete any OpenGL or Vulkan texture objects created by ktxTexture_GLUpload or ktxTexture_VkUpload.

Parameters

[in] This pointer to the ktxTexture object to destroy

§ 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_GetImageOffset()

KTX_error_code ktxTexture_GetImageOffset	(	ktxTexture *	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.

§ ktxTexture_GetSize()

ktx_size_t ktxTexture_GetSize ( ktxTexture * This )

Return the size of the texture image data in bytes.

Parameters

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

§ ktxTexture_IterateLevelFaces()

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

Iterate over the images 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`.

Examples:: glloader.c.

§ ktxTexture_IterateLevels()

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

Iterate over the mip levels in a ktxTexture 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 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_VALUE	`This` is `NULL` or `iterCb` is `NULL`.

§ ktxTexture_IterateLoadLevelFaces()

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

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

This operates similarly to ktxTexture_IterateLevelFaces() except that it loads the images from the ktxTexture'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 ktxTexture 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 ktxTexture was not created from a stream, i.e there is no data to load, or this ktxTexture'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.

Examples:: glloader.c.

§ ktxTexture_LoadImageData()

KTX_error_code ktxTexture_LoadImageData	(	ktxTexture *	This,
		ktx_uint8_t *	pBuffer,
		ktx_size_t	bufSize
	)

Load all the image data from the ktxTexture'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.

Functions

Detailed Description

Function Documentation

§ ktxTexture_CreateFromMemory()

§ ktxTexture_CreateFromNamedFile()

§ ktxTexture_CreateFromStdioStream()

§ ktxTexture_Destroy()

§ ktxTexture_GetData()

§ ktxTexture_GetImageOffset()

§ ktxTexture_GetSize()

§ ktxTexture_IterateLevelFaces()

§ ktxTexture_IterateLevels()

§ ktxTexture_IterateLoadLevelFaces()

§ ktxTexture_LoadImageData()