Declares the public functions and structures of the KTX API. More...
#include <stdio.h>#include "KHR/khrplatform.h"#include <GLES2/gl2.h>#include <GLES2/gl2ext.h>Go to the source code of this file.
Classes | |
| 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... | |
Macros | |
| #define | KTX_OPENGL_ES2 1 |
| #define | KTX_GLFUNCPTRS "gles2_funcptrs.h" |
| #define | KTX_SUPPORT_SIZEDINTERNALFORMATS 0 |
| #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. | |
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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| KTX_hash_table | ktxHashTable_Create () |
| Create an empty hash table for storying key-value pairs. More... | |
| void | ktxHashTable_Destroy (KTX_hash_table This) |
| Destroy a hash table. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
| 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. More... | |
Declares the public functions and structures of the KTX API.
Find a way so that applications do not have to define KTX_OPENGL{,_ES*} when using the library. Use runtime checks for sized internalformat and ETC support.
| #define KTX_OPENGL_ES2 1 |
Licensing
LibKTX contains code
A specific copyright is given in each source file.
default Default License
With the exception of the files listed explicitly below, the source files are made available under the following BSD-like license.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included unaltered in all copies or substantial portions of the Materials. Any additions, deletions, or changes to the original source files must be clearly indicated in accompanying documentation.
If only executable code is distributed, then the accompanying documentation must state that "this software is based in part on the work of the Khronos Group."
THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
uthash.h is made available under the following revised BSD license.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The KTX Library
libktx is a small library of functions for creating KTX (Khronos TeXture) files and instantiating OpenGL® and OpenGL® ES textures from them.
For information about the KTX format see the formal specification.
The library is open source software. Most of the code is licensed under a modified BSD license. The code for unpacking ETC1 compressed textures has a separate license that restricts it to uses associated with Khronos Group APIs. See the licensing for more details.
See history for the list of changes.
| enum KTX_error_code_t |
Error codes returned by library functions.
| 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.
| [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. |
| 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.
| 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.
| [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. |
| 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.
| [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.
| [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. |
| 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.
| [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. |
| 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 GL_ETC1_RGB8_OES format compressed textures in software when the format is not supported by the GL implementation, provided the library has been compiled with SUPPORT_SOFTWARE_ETC_UNPACK defined as 1.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| 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.
| [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. |
| KTX_FILE_OPEN_FAILED | unable to open the specified file for writing. |
For other exceptions, see ktxWriteKTXF().
1.8.3.1