Write KTX-formatted data. More...

Functions
KTX_error_code	ktxWriteKTXF (FILE file, const KTX_texture_info textureInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
	Write image(s) in KTX format to a stdio FILE stream. More...

KTX_error_code	ktxWriteKTXN (const char dstname, const KTX_texture_info textureInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
	Write image(s) in KTX format to a file on disk. More...

KTX_error_code	ktxWriteKTXM (unsigned char *ppDstBytes, GLsizei pSize, const KTX_texture_info textureInfo, GLsizei bytesOfKeyValueData, const void keyValueData, GLuint numImages, KTX_image_info images[])
	Write image(s) in KTX format to memory. More...

KTX_error_code	ktxTexture::ktxTexture_Create (ktxTextureCreateInfo createInfo, ktxTextureCreateStorageEnum storageAllocation, ktxTexture *newTex)
	Create a new empty ktxTexture. More...

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

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

KTX_error_code	ktxTexture::ktxTexture_WriteToStdioStream (ktxTexture This, FILE dstsstr)
	Write a ktxTexture object to a stdio stream in KTX format. More...

KTX_error_code	ktxTexture::ktxTexture_WriteToNamedFile (ktxTexture This, const char const dstname)
	Write a ktxTexture object to a named file in KTX format. More...

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

Detailed Description

Write KTX-formatted data.

Function Documentation

§ ktxTexture_Create()

KTX_error_code ktxTexture_Create	(	ktxTextureCreateInfo *	createInfo,
		ktxTextureCreateStorageEnum	storageAllocation,
		ktxTexture **	newTex
	)

Create a new empty ktxTexture.

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

§ ktxTexture_SetImageFromMemory()

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

§ ktxTexture_SetImageFromStdioStream()

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

§ ktxTexture_WriteToMemory()

KTX_error_code ktxTexture_WriteToMemory	(	ktxTexture *	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_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()

KTX_error_code ktxTexture_WriteToNamedFile	(	ktxTexture *	This,
		const char *const	dstname
	)

Write a ktxTexture object to a named file in KTX format.

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_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()

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

§ ktxWriteKTXF()

KTX_error_code ktxWriteKTXF	(	FILE *	file,
		const KTX_texture_info *	textureInfo,
		GLsizei	bytesOfKeyValueData,
		const void *	keyValueData,
		GLuint	numImages,
		KTX_image_info	images[]
	)

Write image(s) in KTX format to a stdio FILE stream.

Deprecated:: Use ktxTexture_WriteToStdioStream().

Note: textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.

Parameters

[in]	file	pointer to the FILE stream to write to.
[in]	textureInfo	pointer to a KTX_texture_info structure providing information about the images to be included in the KTX file.
[in]	bytesOfKeyValueData	specifies the number of bytes of key-value data.
[in]	keyValueData	a pointer to the keyValue data.
[in]	numImages	number of images in the following array
[in]	images	array of KTX_image_info providing image size and data.

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

Exceptions

KTX_INVALID_VALUE	`glTypeSize` in `textureInfo` is not 1, 2, or 4 or is different from the size of the type specified in `glType`.
KTX_INVALID_VALUE	`pixelWidth` in `textureInfo` is 0 or pixelDepth != 0 && pixelHeight == 0.
KTX_INVALID_VALUE	In `textureInfo`, `numberOfFaces` != 1 or numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_VALUE	`glType` in `textureInfo` is an unrecognized type.
KTX_INVALID_OPERATION	In `textureInfo`, numberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATION	`numImages` is insufficient for the specified number of mipmap levels and faces.
KTX_INVALID_OPERATION	The size of a provided image is different than that required for the specified width, height or depth or for the mipmap level being processed.
KTX_INVALID_OPERATION	`glType` and `glFormat` in `textureInfo` are mismatched. See OpenGL 4.4 specification section 8.4.4 and table 8.5.
KTX_FILE_WRITE_ERROR	A system error occurred while writing the file.
KTX_OUT_OF_MEMORY	System failed to allocate sufficient memory.

§ ktxWriteKTXM()

KTX_error_code ktxWriteKTXM	(	unsigned char **	ppDstBytes,
		GLsizei *	pSize,
		const KTX_texture_info *	textureInfo,
		GLsizei	bytesOfKeyValueData,
		const void *	keyValueData,
		GLuint	numImages,
		KTX_image_info	images[]
	)

Write image(s) in KTX format to memory.

Deprecated:: Use ktxTexture_WriteToMemory().

Memory is allocated by the function and the caller is responsible for freeing it.

Note: textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.

Parameters

[out]	ppDstBytes	pointer to location to write the address of the destination memory. The Application is responsible for freeing this memory.
[out]	pSize	pointer to location to write the size in bytes of the KTX data.
[in]	textureInfo	pointer to a KTX_texture_info structure providing information about the images to be included in the KTX file.
[in]	bytesOfKeyValueData	specifies the number of bytes of key-value data.
[in]	keyValueData	a pointer to the keyValue data.
[in]	numImages	number of images in the following array.
[in]	images	array of KTX_image_info providing image size and data.

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

Exceptions

KTX_INVALID_VALUE	`dst` or `size` is NULL.
KTX_INVALID_VALUE	`glTypeSize` in `textureInfo` is not 1, 2, or 4 or is different from the size of the type specified in `glType`.
KTX_INVALID_VALUE	`pixelWidth` in `textureInfo` is 0 or pixelDepth != 0 && pixelHeight == 0.
KTX_INVALID_VALUE	In `textureInfo`, `numberOfFaces` != 1 or numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_VALUE	`glType` in `textureInfo` is an unrecognized type.
KTX_INVALID_OPERATION	In `textureInfo`, numberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATION	`numImages` is insufficient for the specified number of mipmap levels and faces.
KTX_INVALID_OPERATION	The size of a provided image is different than that required for the specified width, height or depth or for the mipmap level being processed.
KTX_INVALID_OPERATION	`glType` and `glFormat` in `textureInfo` are mismatched. See OpenGL 4.4 specification section 8.4.4 and table 8.5.
KTX_FILE_WRITE_ERROR	A system error occurred while writing the file.
KTX_OUT_OF_MEMORY	System failed to allocate sufficient memory.

§ ktxWriteKTXN()

KTX_error_code ktxWriteKTXN	(	const char *	dstname,
		const KTX_texture_info *	textureInfo,
		GLsizei	bytesOfKeyValueData,
		const void *	keyValueData,
		GLuint	numImages,
		KTX_image_info	images[]
	)

Write image(s) in KTX format to a file on disk.

Deprecated:: Use ktxTexture_WriteToNamedFile().

Note: textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.

Parameters

[in]	dstname	pointer to a C string that contains the path of the file to load.
[in]	textureInfo	pointer to a KTX_texture_info structure providing information about the images to be included in the KTX file.
[in]	bytesOfKeyValueData	specifies the number of bytes of key-value data.
[in]	keyValueData	a pointer to the keyValue data.
[in]	numImages	number of images in the following array.
[in]	images	array of KTX_image_info providing image size and data.

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

Exceptions

KTX_FILE_OPEN_FAILED Unable to open the specified file for writing.

For other exceptions, see ktxWriteKTXF().

Functions

Detailed Description

Function Documentation

§ ktxTexture_Create()

§ ktxTexture_SetImageFromMemory()

§ ktxTexture_SetImageFromStdioStream()

§ ktxTexture_WriteToMemory()

§ ktxTexture_WriteToNamedFile()

§ ktxTexture_WriteToStdioStream()

§ ktxWriteKTXF()

§ ktxWriteKTXM()

§ ktxWriteKTXN()