libktx
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Data Structures | Defines | Typedefs | Enumerations | Functions
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

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:
errorthe 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]Thispointer to the target hash table.
[in]keypointer to the UTF8 NUL-terminated string to be used as the key.
[in]valueLenthe number of bytes of data in value.
[in]valuepointer to the bytes of data constituting the value.
Returns:
KTX_SUCCESS or one of the following error codes.
Exceptions:
KTX_INVALID_VALUEif This, key or value are NULL, key is an empty string or valueLen == 0.

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]kvdLenthe length of the serialized key-value data.
[in]pKvdpointer 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_VALUEif pKvd or pHt is NULL or kvdLen == 0.
KTX_OUT_OF_MEMORYthere was not enough memory to create the hash table.

Destroy a hash table.

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

Parameters:
[in]Thispointer 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]Thispointer to the target hash table.
[in]keypointer 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_VALUEif This, key or pValueLen or ppValue is NULL.
KTX_NOT_FOUNDan 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]Thispointer 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_VALUEif This, pKvdLen or ppKvd is NULL.
KTX_OUT_OF_MEMORYthere 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]filepointer to the stdio FILE stream from which to load.
[in,out]pTexturename 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]pDimensionsIf 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]pIsMipmappedIf 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]pKvdLenIf 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]ppKvdIf 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_VALUEtarget is NULL or the size of a mip level is greater than the size of the preceding level.
KTX_INVALID_OPERATIONppKvd is not NULL but pKvdLen is NULL.
KTX_UNEXPECTED_END_OF_FILEthe file does not contain the expected amount of data.
KTX_OUT_OF_MEMORYSufficient memory could not be allocated to store the requested key-value data.
KTX_GL_ERRORA 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]bytespointer to the array of bytes containing the KTX format data to load.
[in]sizesize of the memory array containing the KTX format data.
[in,out]pTexturename of the GL texture to load. See ktxLoadTextureF() for details.
[out]pTargetpTarget is set to the texture target used. See ktxLoadTextureF() for details.
[out]pDimensionsthe 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_FAILEDThe specified memory could not be opened as a file.
KTX_INVALID_VALUESee ktxLoadTextureF() for causes.
KTX_INVALID_OPERATIONSee ktxLoadTextureF() for causes.
KTX_UNEXPECTED_END_OF_FILESee ktxLoadTextureF() for causes.
KTX_GL_ERRORSee 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]filenamepointer to a C string that contains the path of the file to load.
[in,out]pTexturename of the GL texture to load. See ktxLoadTextureF() for details.
[out]pTargetpTarget is set to the texture target used. See ktxLoadTextureF() for details.
[out]pDimensionsthe texture's base level width depth and height are returned in structure to which this points. See ktxLoadTextureF() for details.
[out]pIsMipmappedpIsMipMapped 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_FAILEDThe specified file could not be opened.
KTX_INVALID_VALUESee ktxLoadTextureF() for causes.
KTX_INVALID_OPERATIONSee ktxLoadTextureF() for causes.
KTX_UNEXPECTED_END_OF_FILESee ktxLoadTextureF() for causes.
KTX_GL_ERRORSee 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]dstpointer to the FILE stream to write to.
[in]textureInfopointer to a KTX_image_info structure providing information about the images to be included in the KTX file.
[in]bytesOfKeyValueDataspecifies the number of bytes of key-value data.
[in]keyValueDataa pointer to the keyValue data.
[in]numImagesnumber of images in the following array
[in]imagesarray of KTX_image_info providing image size and data.
Returns:
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions:
KTX_INVALID_VALUEdst or target are NULL
KTX_INVALID_VALUEglTypeSize in textureInfo is not 1, 2, or 4 or is different from the size of the type specified in glType.
KTX_INVALID_VALUEpixelWidth in textureInfo is 0 or pixelDepth != 0 && pixelHeight == 0.
KTX_INVALID_VALUEnumberOfFaces != 1 || numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_OPERATIONnumberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATIONnumber of images is insufficient for the specified number of mipmap levels and faces.
KTX_INVALID_OPERATIONthe 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_ERRORa 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]dstnamepointer to a C string that contains the path of the file to load.
[in]textureInfopointer to a KTX_image_info structure providing information about the images to be included in the KTX file.
[in]bytesOfKeyValueDataspecifies the number of bytes of key-value data.
[in]keyValueDataa pointer to the keyValue data.
[in]numImagesnumber of images in the following array.
[in]imagesarray of KTX_image_info providing image size and data.
Returns:
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions:
KTX_FILE_OPEN_FAILEDunable to open the specified file for writing.

For other exceptions, see ktxWriteKTXF().