include/ktx.h File Reference

Declares the public functions and structures of the KTX API. More...

#include <stdio.h>
#include "KHR/khrplatform.h"

Data Structures
struct	KTX_texture_info_t
	structure used to pass information about the texture to ktxWriteKTX More...
struct	KTX_image_info
	Structure used to pass image data to ktxWriteKTX. More...
struct	KTX_dimensions
	Structure used to return texture dimensions. More...
Defines
#define	KTX_ORIENTATION_KEY   "KTXorientation"
	Key String for standard orientation value.
#define	KTX_ORIENTATION2_FMT   "S=%c,T=%c"
	Standard format for 2D orientation value.
#define	KTX_ORIENTATION3_FMT   "S=%c,T=%c,R=%c"
	Standard format for 3D orientation value.
#define	KTX_GL_UNPACK_ALIGNMENT   4
	Required unpack alignment.
Typedefs
typedef enum KTX_error_code_t	KTX_error_code
	Error codes returned by library functions.
typedef struct KTX_texture_info_t	KTX_texture_info
	structure used to pass information about the texture to ktxWriteKTX
typedef struct KTX_image_info	KTX_image_info
	Structure used to pass image data to ktxWriteKTX.
typedef struct KTX_dimensions	KTX_dimensions
	Structure used to return texture dimensions.
typedef void *	KTX_hash_table
	Opaque handle to a KTX_hash_table.
Enumerations
enum	KTX_error_code_t {   KTX_SUCCESS = 0, KTX_FILE_OPEN_FAILED, KTX_FILE_WRITE_ERROR, KTX_GL_ERROR,   KTX_INVALID_OPERATION, KTX_INVALID_VALUE, KTX_NOT_FOUND, KTX_OUT_OF_MEMORY,   KTX_UNEXPECTED_END_OF_FILE, KTX_UNKNOWN_FILE_FORMAT, KTX_UNSUPPORTED_TEXTURE_TYPE }
	Error codes returned by library functions. More...
Functions
KTX_error_code	ktxLoadTextureF (FILE *, GLuint *pTexture, GLenum *pTarget, KTX_dimensions *pDimensions, GLboolean *pIsMipmapped, GLenum *pGlerror, unsigned int *pKvdLen, unsigned char **ppKvd)
	Load a GL texture object from a stdio FILE stream.
KTX_error_code	ktxLoadTextureN (const char *const filename, GLuint *pTexture, GLenum *pTarget, KTX_dimensions *pDimensions, GLboolean *pIsMipmapped, GLenum *pGlerror, unsigned int *pKvdLen, unsigned char **ppKvd)
	Load a GL texture object from a named file on disk.
KTX_error_code	ktxLoadTextureM (const void *bytes, GLsizei size, GLuint *pTexture, GLenum *pTarget, KTX_dimensions *pDimensions, GLboolean *pIsMipmapped, GLenum *pGlerror, unsigned int *pKvdLen, unsigned char **ppKvd)
	Load a GL texture object from KTX formatted data in memory.
KTX_error_code	ktxWriteKTXF (FILE *, const KTX_texture_info *imageInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
	Write image(s) in a KTX-formatted stdio FILE stream.
KTX_error_code	ktxWriteKTXN (const char *dstname, const KTX_texture_info *imageInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
	Write image(s) to a KTX file on disk.
const char *const	ktxErrorString (KTX_error_code error)
	Return a string corresponding to a KTX error code.
KTX_hash_table	ktxHashTable_Create ()
	Create an empty hash table for storying key-value pairs.
void	ktxHashTable_Destroy (KTX_hash_table This)
	Destroy a hash table.
KTX_error_code	ktxHashTable_AddKVPair (KTX_hash_table This, const char *key, unsigned int valueLen, const void *value)
	Adds a key value pair to a hash table.
KTX_error_code	ktxHashTable_FindValue (KTX_hash_table This, const char *key, unsigned int *pValueLen, void **pValue)
	Looks up a key a hash table and returns the value.
KTX_error_code	ktxHashTable_Serialize (KTX_hash_table This, unsigned int *kvdLen, unsigned char **kvd)
	Serialize a hash table to a block of data suitable for writing to a file.
KTX_error_code	ktxHashTable_Deserialize (unsigned int kvdLen, void *kvd, KTX_hash_table *pKvt)
	Create a hash table from a block of serialized key-value data read from a file.

---

Detailed Description

Declares the public functions and structures of the KTX API.

Author:

Georg Kolling, Imagination Technology

with modifications by Mark Callow, HI Corporation

Revision:

21695

Date:

2013-05-23 12:45:33 +0900 #

Todo:

Find a way so that applications do not have to define KTX_OPENGL{,_ES*} when using the library.

---

Enumeration Type Documentation

enum KTX_error_code_t

Error codes returned by library functions.

Enumerator:

KTX_SUCCESS	Operation was successful.
KTX_FILE_OPEN_FAILED	The target file could not be opened.
KTX_FILE_WRITE_ERROR	An error occurred while writing to the file.
KTX_GL_ERROR	GL operations resulted in an error.
KTX_INVALID_OPERATION	The operation is not allowed in the current state.
KTX_INVALID_VALUE	A parameter value was not valid
KTX_NOT_FOUND	Requested key was not found
KTX_OUT_OF_MEMORY	Not enough memory to complete the operation.
KTX_UNEXPECTED_END_OF_FILE	The file did not contain enough data
KTX_UNKNOWN_FILE_FORMAT	The file not a KTX file
KTX_UNSUPPORTED_TEXTURE_TYPE	The KTX file specifies an unsupported texture type.

---

Function Documentation

const char* const ktxErrorString

(

KTX_error_code

error

)

Return a string corresponding to a KTX error code.

Parameters:

error

the error code for which to return a string

Returns:

pointer to the message string.

Use UTF-8 for translated message strings.

Author:

Mark Callow, HI Corporation

KTX_error_code ktxHashTable_AddKVPair	(	KTX_hash_table	This,
		const char *	key,
		unsigned int	valueLen,
		const void *	value
	)

Adds a key value pair to a hash table.

Parameters:

[in]	This	pointer to the target hash table.
[in]	key	pointer to the UTF8 NUL-terminated string to be used as the key.
[in]	valueLen	the number of bytes of data in value.
[in]	value	pointer to the bytes of data constituting the value.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE

if This, key or value are NULL, key is an empty string or valueLen == 0.

KTX_hash_table ktxHashTable_Create

(

)

Create an empty hash table for storying key-value pairs.

Returns:

pointer to the newly created hash table or NULL if there is not enough memory.

KTX_error_code ktxHashTable_Deserialize	(	unsigned int	kvdLen,
		void *	pKvd,
		KTX_hash_table *	pHt
	)

Create a hash table from a block of serialized key-value data read from a file.

The caller is responsible for freeing the returned hash table.

Parameters:

[in]	kvdLen	the length of the serialized key-value data.
[in]	pKvd	pointer to the serialized key-value data.
[in,out]	pHt	*pHt is set to point to the created hash table.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if pKvd or pHt is NULL or kvdLen == 0.
KTX_OUT_OF_MEMORY	there was not enough memory to create the hash table.

void ktxHashTable_Destroy

(

KTX_hash_table

This

)

Destroy a hash table.

All memory associated with the hash table and its keys and values is freed.

Parameters:

[in]

This

pointer to the hash table to be destroyed.

KTX_error_code ktxHashTable_FindValue	(	KTX_hash_table	This,
		const char *	key,
		unsigned int *	pValueLen,
		void **	ppValue
	)

Looks up a key a hash table and returns the value.

Parameters:

[in]	This	pointer to the target hash table.
[in]	key	pointer to a UTF8 NUL-terminated string to find.
[in,out]	pValueLen	*pValueLen is set to the number of bytes of data in the returned value.
[in,out]	ppValue	*ppValue is set to the point to the value for key.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if This, key or pValueLen or ppValue is NULL.
KTX_NOT_FOUND	an entry matching key was not found.

KTX_error_code ktxHashTable_Serialize	(	KTX_hash_table	This,
		unsigned int *	pKvdLen,
		unsigned char **	ppKvd
	)

Serialize a hash table to a block of data suitable for writing to a file.

The caller is responsible for freeing the data block returned by this function.

Parameters:

[in]	This	pointer to the target hash table.
[in,out]	pKvdLen	*pKvdLen is set to the number of bytes of data in the returned data block.
[in,out]	ppKvd	*ppKvd is set to the point to the block of memory containing the serialized data.

Returns:

KTX_SUCCESS or one of the following error codes.

Exceptions:

KTX_INVALID_VALUE	if This, pKvdLen or ppKvd is NULL.
KTX_OUT_OF_MEMORY	there was not enough memory to serialize the data.

KTX_error_code ktxLoadTextureF	(	FILE *	file,
		GLuint *	pTexture,
		GLenum *	pTarget,
		KTX_dimensions *	pDimensions,
		GLboolean *	pIsMipmapped,
		GLenum *	pGlerror,
		unsigned int *	pKvdLen,
		unsigned char **	ppKvd
	)

Load a GL texture object from a stdio FILE stream.

This function will unpack compressed GL_ETC1_RGB8_OES and GL_ETC2_* format textures in software when the format is not supported by the GL context, provided the library has been compiled with SUPPORT_SOFTWARE_ETC_UNPACK defined as 1.

It will also convert texture with legacy formats to their modern equivalents when the format is not supported by the GL context, provided that the library has been compiled with SUPPORT_LEGACY_FORMAT_CONVERSION defined as 1.

Parameters:

[in]	file	pointer to the stdio FILE stream from which to load.
[in,out]	pTexture	name of the GL texture to load. If NULL or if *pTexture == 0 the function will generate a texture name. The function binds either the generated name or the name given in *pTexture to the texture target returned in *pTarget, before loading the texture data. If pTexture is not NULL and a name was generated, the generated name will be returned in *pTexture.
[out]	pTarget	*pTarget is set to the texture target used. The target is chosen based on the file contents.
[out]	pDimensions	If pDimensions is not NULL, the width, height and depth of the texture's base level are returned in the fields of the KTX_dimensions structure to which it points.
[out]	pIsMipmapped	If pIsMipmapped is not NULL, *pIsMipmapped is set to GL_TRUE if the KTX texture is mipmapped, GL_FALSE otherwise.
[out]	pGlerror	*pGlerror is set to the value returned by glGetError when this function returns the error KTX_GL_ERROR. glerror can be NULL.
[in,out]	pKvdLen	If not NULL, *pKvdLen is set to the number of bytes of key-value data pointed at by *ppKvd. Must not be NULL, if ppKvd is not NULL.
[in,out]	ppKvd	If not NULL, *ppKvd is set to the point to a block of memory containing key-value data read from the file. The application is responsible for freeing the memory.

Returns:

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

Exceptions:

KTX_INVALID_VALUE	target is NULL or the size of a mip level is greater than the size of the preceding level.
KTX_INVALID_OPERATION	ppKvd is not NULL but pKvdLen is NULL.
KTX_UNEXPECTED_END_OF_FILE	the file does not contain the expected amount of data.
KTX_OUT_OF_MEMORY	Sufficient memory could not be allocated to store the requested key-value data.
KTX_GL_ERROR	A GL error was raised by glBindTexture, glGenTextures or gl*TexImage*. The GL error will be returned in *glerror, if glerror is not NULL.

KTX_error_code ktxLoadTextureM	(	const void *	bytes,
		GLsizei	size,
		GLuint *	pTexture,
		GLenum *	pTarget,
		KTX_dimensions *	pDimensions,
		GLboolean *	pIsMipmapped,
		GLenum *	pGlerror,
		unsigned int *	pKvdLen,
		unsigned char **	ppKvd
	)

Load a GL texture object from KTX formatted data in memory.

Parameters:

[in]	bytes	pointer to the array of bytes containing the KTX format data to load.
[in]	size	size of the memory array containing the KTX format data.
[in,out]	pTexture	name of the GL texture to load. See ktxLoadTextureF() for details.
[out]	pTarget	pTarget is set to the texture target used. See ktxLoadTextureF() for details.
[out]	pDimensions	the texture's base level width depth and height are returned in structure to which this points. See ktxLoadTextureF() for details.
[out]	pIsMipmapped	*pIsMipMapped is set to indicate if the loaded texture is mipmapped. See ktxLoadTextureF() for details.
[out]	pGlerror	*pGlerror is set to the value returned by glGetError when this function returns the error KTX_GL_ERROR. glerror can be NULL.
[in,out]	pKvdLen	If not NULL, *pKvdLen is set to the number of bytes of key-value data pointed at by *ppKvd. Must not be NULL, if ppKvd is not NULL.
[in,out]	ppKvd	If not NULL, *ppKvd is set to the point to a block of memory containing key-value data read from the file. The application is responsible for freeing the memory.

Returns:

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

Exceptions:

KTX_FILE_OPEN_FAILED	The specified memory could not be opened as a file.
KTX_INVALID_VALUE	See ktxLoadTextureF() for causes.
KTX_INVALID_OPERATION	See ktxLoadTextureF() for causes.
KTX_UNEXPECTED_END_OF_FILE	See ktxLoadTextureF() for causes.
KTX_GL_ERROR	See ktxLoadTextureF() for causes.

KTX_error_code ktxLoadTextureN	(	const char *const	filename,
		GLuint *	pTexture,
		GLenum *	pTarget,
		KTX_dimensions *	pDimensions,
		GLboolean *	pIsMipmapped,
		GLenum *	pGlerror,
		unsigned int *	pKvdLen,
		unsigned char **	ppKvd
	)

Load a GL texture object from a named file on disk.

Parameters:

[in]	filename	pointer to a C string that contains the path of the file to load.
[in,out]	pTexture	name of the GL texture to load. See ktxLoadTextureF() for details.
[out]	pTarget	pTarget is set to the texture target used. See ktxLoadTextureF() for details.
[out]	pDimensions	the texture's base level width depth and height are returned in structure to which this points. See ktxLoadTextureF() for details.
[out]	pIsMipmapped	pIsMipMapped is set to indicate if the loaded texture is mipmapped. See ktxLoadTextureF() for details.
[out]	pGlerror	*pGlerror is set to the value returned by glGetError when this function returns the error KTX_GL_ERROR. glerror can be NULL.
[in,out]	pKvdLen	If not NULL, *pKvdLen is set to the number of bytes of key-value data pointed at by *ppKvd. Must not be NULL, if ppKvd is not NULL.
[in,out]	ppKvd	If not NULL, *ppKvd is set to the point to a block of memory containing key-value data read from the file. The application is responsible for freeing the memory.

Returns:

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

Exceptions:

KTX_FILE_OPEN_FAILED	The specified file could not be opened.
KTX_INVALID_VALUE	See ktxLoadTextureF() for causes.
KTX_INVALID_OPERATION	See ktxLoadTextureF() for causes.
KTX_UNEXPECTED_END_OF_FILE	See ktxLoadTextureF() for causes.
KTX_GL_ERROR	See ktxLoadTextureF() for causes.

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

Write image(s) in a KTX-formatted stdio FILE stream.

Parameters:

[in]	dst	pointer to the FILE stream to write to.
[in]	textureInfo	pointer to a KTX_image_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 target are 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	numberOfFaces != 1 || numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_OPERATION	numberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATION	number of images 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_FILE_WRITE_ERROR	a system error occurred while writing the file.

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) to a KTX file on disk.

Parameters:

[in]	dstname	pointer to a C string that contains the path of the file to load.
[in]	textureInfo	pointer to a KTX_image_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().