.TH "reader" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*-
.ad l
.nh
.SH NAME
reader \- Reader
.PP
 \- Read KTX-formatted data\&.  

.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_DecodeAstc\fP (\fBktxTexture2\fP *This)"
.br
.RI "Decodes a ktx2 texture object, if it is ASTC encoded\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_TranscodeBasis\fP (\fBktxTexture2\fP *This, \fBktx_transcode_fmt_e\fP outputFormat, ktx_transcode_flags transcodeFlags)"
.br
.RI "Transcode a KTX2 texture with BasisLZ/ETC1S or UASTC images\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture_CreateFromStream\fP (\fBktxStream\fP *pStream, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP **newTex)"
.br
.RI "Create a ktx1 or ktx2 texture according to the stream data\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture_CreateFromStdioStream\fP (FILE *stdioStream, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP or \fBktxTexture2\fP from a stdio stream according to the stream data\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture_CreateFromNamedFile\fP (const char *const filename, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP or \fBktxTexture2\fP from a named KTX file according to the file contents\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture_CreateFromMemory\fP (const ktx_uint8_t *bytes, ktx_size_t size, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP or \fBktxTexture2\fP from KTX-formatted data in memory according to the data contents\&. "
.ti -1c
.RI "ktx_uint8_t * \fBktxTexture_GetData\fP (\fBktxTexture\fP *This)"
.br
.RI "Return a pointer to the texture image data\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture_GetDataSize\fP (\fBktxTexture\fP *This)"
.br
.RI "Return the total size of the texture image data in bytes\&. "
.ti -1c
.RI "ktx_uint32_t \fBktxTexture_GetElementSize\fP (\fBktxTexture\fP *This)"
.br
.RI "Return the size in bytes of an elements of a texture's images\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture_IterateLevelFaces\fP (\fBktxTexture\fP *This, \fBPFNKTXITERCB\fP iterCb, void *userdata)"
.br
.RI "Iterate over the levels or faces in a \fBktxTexture\fP object\&. "
.ti -1c
.RI "ktx_uint32_t \fBktxTexture_GetRowPitch\fP (\fBktxTexture\fP *This, ktx_uint32_t level)"
.br
.RI "Return pitch between rows of a texture image level in bytes\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_CreateFromStdioStream\fP (FILE *stdioStream, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP from a stdio stream reading from a KTX source\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_CreateFromNamedFile\fP (const char *const filename, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP from a named KTX file\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_CreateFromMemory\fP (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP from KTX-formatted data in memory\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_CreateFromStream\fP (\fBktxStream\fP *pStream, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP **newTex)"
.br
.RI "Create a \fBktxTexture1\fP from KTX-formatted data from a \fR\fBktxStream\fP\fP\&. "
.ti -1c
.RI "void \fBktxTexture1_Destroy\fP (\fBktxTexture1\fP *This)"
.br
.RI "Destroy a \fBktxTexture1\fP object\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_GetImageOffset\fP (\fBktxTexture1\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t *pOffset)"
.br
.RI "Find the offset of an image within a \fBktxTexture\fP's image data\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture1_GetDataSizeUncompressed\fP (\fBktxTexture1\fP *This)"
.br
.RI "Return the total size in bytes of the uncompressed data of a \fBktxTexture1\fP\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture1_GetImageSize\fP (\fBktxTexture1\fP *This, ktx_uint32_t level)"
.br
.RI "Calculate & return the size in bytes of an image at the specified mip level\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture1_GetLevelSize\fP (\fBktxTexture1\fP *This, ktx_uint32_t level)"
.br
.RI "Calculate & return the size in bytes of all the images in the specified mip level\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_IterateLevels\fP (\fBktxTexture1\fP *This, PFNKTXITERCB iterCb, void *userdata)"
.br
.RI "Iterate over the mip levels in a \fBktxTexture1\fP object\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_IterateLoadLevelFaces\fP (\fBktxTexture1\fP *This, PFNKTXITERCB iterCb, void *userdata)"
.br
.RI "Iterate over the images in a \fBktxTexture1\fP object while loading the image data\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture1_LoadImageData\fP (\fBktxTexture1\fP *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)"
.br
.RI "Load all the image data from the \fBktxTexture1\fP's source\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_CreateFromStdioStream\fP (FILE *stdioStream, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP **newTex)"
.br
.RI "Create a \fBktxTexture2\fP from a stdio stream reading from a KTX source\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_CreateFromNamedFile\fP (const char *const filename, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP **newTex)"
.br
.RI "Create a \fBktxTexture2\fP from a named KTX file\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_CreateFromMemory\fP (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP **newTex)"
.br
.RI "Create a \fBktxTexture2\fP from KTX-formatted data in memory\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_CreateFromStream\fP (\fBktxStream\fP *stream, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP **newTex)"
.br
.RI "Create a \fBktxTexture2\fP from KTX-formatted data from a stream\&. "
.ti -1c
.RI "void \fBktxTexture2_Destroy\fP (\fBktxTexture2\fP *This)"
.br
.RI "Destroy a \fBktxTexture2\fP object\&. "
.ti -1c
.RI "void \fBktxTexture2_GetComponentInfo\fP (\fBktxTexture2\fP *This, uint32_t *pNumComponents, uint32_t *pComponentByteLength)"
.br
.RI "Return information about the components of an image in a texture\&. "
.ti -1c
.RI "ktx_uint32_t \fBktxTexture2_GetNumComponents\fP (\fBktxTexture2\fP *This)"
.br
.RI "Return the number of components in an image of the texture\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_GetImageOffset\fP (\fBktxTexture2\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t *pOffset)"
.br
.RI "Find the offset of an image within a \fBktxTexture\fP's image data\&. "
.ti -1c
.RI "khr_df_transfer_e \fBktxTexture2_GetTransferFunction_e\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve the transfer function of the images\&. "
.ti -1c
.RI "khr_df_transfer_e \fBktxTexture2_GetOETF_e\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve the transfer function of the images\&. "
.ti -1c
.RI "ktx_uint32_t \fBktxTexture2_GetOETF\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve the transfer function of the images\&. "
.ti -1c
.RI "khr_df_model_e \fBktxTexture2_GetColorModel_e\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve the DFD color model of the images\&. "
.ti -1c
.RI "ktx_bool_t \fBktxTexture2_GetPremultipliedAlpha\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve whether the RGB components have been premultiplied by the alpha component\&. "
.ti -1c
.RI "khr_df_primaries_e \fBktxTexture2_GetPrimaries_e\fP (\fBktxTexture2\fP *This)"
.br
.RI "Retrieve the color primaries of the images\&. "
.ti -1c
.RI "ktx_bool_t \fBktxTexture2_NeedsTranscoding\fP (\fBktxTexture2\fP *This)"
.br
.RI "Query if the images are in a transcodable format\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture2_GetDataSizeUncompressed\fP (\fBktxTexture2\fP *This)"
.br
.RI "Return the total size in bytes of the uncompressed data of a \fBktxTexture2\fP\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture2_GetImageSize\fP (\fBktxTexture2\fP *This, ktx_uint32_t level)"
.br
.RI "Calculate & return the size in bytes of an image at the specified mip level\&. "
.ti -1c
.RI "ktx_size_t \fBktxTexture2_GetLevelSize\fP (\fBktxTexture2\fP *This, ktx_uint32_t level)"
.br
.RI "Calculate & return the size in bytes of all the images in the specified mip level\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_IterateLevels\fP (\fBktxTexture2\fP *This, PFNKTXITERCB iterCb, void *userdata)"
.br
.RI "Iterate over the mip levels in a \fBktxTexture2\fP object\&. "
.ti -1c
.RI "\fBKTX_error_code\fP \fBktxTexture2_IterateLoadLevelFaces\fP (\fBktxTexture2\fP *This, PFNKTXITERCB iterCb, void *userdata)"
.br
.RI "Iterate over the images in a \fBktxTexture2\fP object while loading the image data\&. "
.ti -1c
.RI "\fBktx_error_code_e\fP \fBktxTexture2_LoadImageData\fP (\fBktxTexture2\fP *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)"
.br
.RI "Load all the image data from the \fBktxTexture2\fP's source\&. "
.ti -1c
.RI "\fBktx_error_code_e\fP \fBktxTexture2_LoadDeflatedImageData\fP (\fBktxTexture2\fP *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)"
.br
.RI "Load all the image data from the \fBktxTexture2\fP's source without inflatiion\&.\&. "
.in -1c
.SH "Detailed Description"
.PP 
Read KTX-formatted data\&. 


.SH "Function Documentation"
.PP 
.SS "\fBKTX_error_code\fP ktxTexture1_CreateFromMemory (const ktx_uint8_t * bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP from KTX-formatted data in memory\&. The address of a newly created texture reflecting the contents of the serialized KTX data is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture1\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture1\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIbytes\fP pointer to the memory containing the serialized KTX data\&. 
.br
\fIsize\fP length of the KTX data in bytes\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP Either \fRbytes\fP is NULL or \fRsize\fP is 0\&.
.RE
.PP
For other exceptions, see \fBktxTexture1_CreateFromStdioStream()\fP\&. 
.SS "\fBKTX_error_code\fP ktxTexture1_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP from a named KTX file\&. The address of a newly created texture reflecting the contents of the file is written to the location pointed at by \fRnewTex\fP\&.

.PP
The file name must be encoded in utf-8\&. On Windows convert unicode names to utf-8 with \fRWideCharToMultiByte(CP_UTF8, \&.\&.\&.)\fP before calling\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture1\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture1\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIfilename\fP pointer to a char array containing the file name\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_OPEN_FAILED\fP\fP The file could not be opened\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRfilename\fP is \fRNULL\fP\&.
.RE
.PP
For other exceptions, see \fBktxTexture1_CreateFromStdioStream()\fP\&. 
.SS "\fBKTX_error_code\fP ktxTexture1_CreateFromStdioStream (FILE * stdioStream, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP from a stdio stream reading from a KTX source\&. The address of a newly created texture reflecting the contents of the stdio stream is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture1\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture1\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIstdioStream\fP stdio FILE pointer created from the desired file\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnewTex\fP is \fRNULL\fP\&. 
.br
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Source data is inconsistent with the KTX specification\&. 
.br
\fI\fBKTX_FILE_READ_ERROR\fP\fP An error occurred while reading the source\&. 
.br
\fI\fBKTX_FILE_UNEXPECTED_EOF\fP\fP Not enough data in the source\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to create the texture object, load the images or load the key-value data\&. 
.br
\fI\fBKTX_UNKNOWN_FILE_FORMAT\fP\fP The source is not in KTX format\&. 
.br
\fI\fBKTX_UNSUPPORTED_TEXTURE_TYPE\fP\fP The source describes a texture type not supported by OpenGL or Vulkan, e\&.g, a 3D array\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture1_CreateFromStream (\fBktxStream\fP * pStream, ktxTextureCreateFlags createFlags, \fBktxTexture1\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP from KTX-formatted data from a \fR\fBktxStream\fP\fP\&. The address of a newly created texture reflecting the contents of the serialized KTX data is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture1\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture1\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIpStream\fP pointer to the stream to read KTX data from\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
For exceptions, see \fBktxTexture1_CreateFromStdioStream()\fP\&. 
.SS "void ktxTexture1_Destroy (\fBktxTexture1\fP * This)"

.PP
Destroy a \fBktxTexture1\fP object\&. This frees the memory associated with the texture contents and the memory of the \fBktxTexture1\fP object\&. This does \fInot\fP delete any OpenGL or Vulkan texture objects created by ktxTexture1_GLUpload or ktxTexture1_VkUpload\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object to destroy 
.RE
.PP

.SS "ktx_size_t ktxTexture1_GetDataSizeUncompressed (\fBktxTexture1\fP * This)"

.PP
Return the total size in bytes of the uncompressed data of a \fBktxTexture1\fP\&. This always returns the value of \fRThis->dataSize\fP\&. The function is provided for symmetry with \fBktxTexture2\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. 
.RE
.PP
\fBReturns\fP
.RS 4
The size of the data in the texture\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture1_GetImageOffset (\fBktxTexture1\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t * pOffset)"

.PP
Find the offset of an image within a \fBktxTexture\fP's image data\&. As there is no such thing as a 3D cubemap we make the 3rd location parameter do double duty\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIlevel\fP mip level of the image\&. 
.br
\fIlayer\fP array layer of the image\&. 
.br
\fIfaceSlice\fP cube map face or depth slice of the image\&. 
.br
\fIpOffset\fP pointer to location to store the offset\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRlevel\fP, \fRlayer\fP or \fRfaceSlice\fP exceed the dimensions of the texture\&. 
.br
\fIKTX_INVALID_VALID\fP \fRThis\fP is NULL\&. 
.RE
.PP

.SS "ktx_size_t ktxTexture1_GetImageSize (\fBktxTexture1\fP * This, ktx_uint32_t level)"

.PP
Calculate & return the size in bytes of an image at the specified mip level\&. For arrays, this is the size of a layer, for cubemaps, the size of a face and for 3D textures, the size of a depth slice\&.

.PP
The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. 
.br
\fIlevel\fP level of interest\&. 
.RE
.PP

.SS "ktx_size_t ktxTexture1_GetLevelSize (\fBktxTexture1\fP * This, ktx_uint32_t level)"

.PP
Calculate & return the size in bytes of all the images in the specified mip level\&. For arrays, this is the size of all layers in the level, for cubemaps, the size of all faces in the level and for 3D textures, the size of all depth slices in the level\&.

.PP
The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. 
.br
\fIlevel\fP level of interest\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture1_IterateLevels (\fBktxTexture1\fP * This, PFNKTXITERCB iterCb, void * userdata)"

.PP
Iterate over the mip levels in a \fBktxTexture1\fP object\&. This is almost identical to \fBktxTexture_IterateLevelFaces\fP\&. The difference is that the blocks of image data for non-array cube maps include all faces of a mip level\&.

.PP
This function works even if \fRThis->pData\fP == 0 so it can be used to obtain offsets and sizes for each level by callers who have loaded the data externally\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP handle of the 1 opened on the data\&. 
.br
\fIiterCb\fP the address of a callback function which is called with the data for each image block\&. 
.br
\fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Mip level sizes are increasing not decreasing 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture1_IterateLoadLevelFaces (\fBktxTexture1\fP * This, PFNKTXITERCB iterCb, void * userdata)"

.PP
Iterate over the images in a \fBktxTexture1\fP object while loading the image data\&. This operates similarly to \fBktxTexture_IterateLevelFaces\fP except that it loads the images from the \fBktxTexture1\fP'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\&.

.PP
This function is helpful for reducing memory usage when uploading the data to a graphics API\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. 
.br
\fIiterCb\fP the address of a callback function which is called with the data for each image\&. 
.br
\fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP mip level sizes are increasing not decreasing 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP the \fBktxTexture1\fP was not created from a stream, i\&.e there is no data to load, or this \fBktxTexture1\fP's images have already been loaded\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP not enough memory to allocate a block to hold the base level image\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture1_LoadImageData (\fBktxTexture1\fP * This, ktx_uint8_t * pBuffer, ktx_size_t bufSize)"

.PP
Load all the image data from the \fBktxTexture1\fP's source\&. The data is loaded into the provided buffer or to an internally allocated buffer, if \fRpBuffer\fP is \fRNULL\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIpBuffer\fP pointer to the buffer in which to load the image data\&. 
.br
\fIbufSize\fP size of the buffer pointed at by \fRpBuffer\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is NULL\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRbufSize\fP is less than the the image data size\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The data has already been loaded or the \fBktxTexture\fP was not created from a KTX source\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Insufficient memory for the image data\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_CreateFromMemory (const ktx_uint8_t * bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP ** newTex)"

.PP
Create a \fBktxTexture2\fP from KTX-formatted data in memory\&. The address of a newly created \fBktxTexture2\fP reflecting the contents of the serialized KTX data is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIbytes\fP pointer to the memory containing the serialized KTX data\&. 
.br
\fIsize\fP length of the KTX data in bytes\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP Either \fRbytes\fP is NULL or \fRsize\fP is 0\&.
.RE
.PP
For other exceptions, see \fBktxTexture2_CreateFromStdioStream()\fP\&. 
.SS "\fBKTX_error_code\fP ktxTexture2_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP ** newTex)"

.PP
Create a \fBktxTexture2\fP from a named KTX file\&. The address of a newly created \fBktxTexture2\fP reflecting the contents of the file is written to the location pointed at by \fRnewTex\fP\&.

.PP
The file name must be encoded in utf-8\&. On Windows convert unicode names to utf-8 with \fRWideCharToMultiByte(CP_UTF8, \&.\&.\&.)\fP before calling\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIfilename\fP pointer to a char array containing the file name\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_OPEN_FAILED\fP\fP The file could not be opened\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRfilename\fP is \fRNULL\fP\&.
.RE
.PP
For other exceptions, see \fBktxTexture2_CreateFromStdioStream()\fP\&. 
.SS "\fBKTX_error_code\fP ktxTexture2_CreateFromStdioStream (FILE * stdioStream, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP ** newTex)"

.PP
Create a \fBktxTexture2\fP from a stdio stream reading from a KTX source\&. The address of a newly created \fBktxTexture2\fP reflecting the contents of the stdio stream is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIstdioStream\fP stdio FILE pointer created from the desired file\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnewTex\fP is \fRNULL\fP\&. 
.br
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Source data is inconsistent with the KTX specification\&. 
.br
\fI\fBKTX_FILE_READ_ERROR\fP\fP An error occurred while reading the source\&. 
.br
\fI\fBKTX_FILE_UNEXPECTED_EOF\fP\fP Not enough data in the source\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to create the texture object, load the images or load the key-value data\&. 
.br
\fI\fBKTX_UNKNOWN_FILE_FORMAT\fP\fP The source is not in KTX format\&. 
.br
\fI\fBKTX_UNSUPPORTED_TEXTURE_TYPE\fP\fP The source describes a texture type not supported by OpenGL or Vulkan, e\&.g, a 3D array\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_CreateFromStream (\fBktxStream\fP * stream, ktxTextureCreateFlags createFlags, \fBktxTexture2\fP ** newTex)"

.PP
Create a \fBktxTexture2\fP from KTX-formatted data from a stream\&. The address of a newly created \fBktxTexture2\fP reflecting the contents of the serialized KTX data is written to the location pointed at by \fRnewTex\fP\&.

.PP
The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the \fBktxTexture\fP 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\&.

.PP
The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used\&. It is provided solely to enable implementation of the \fIlibktx\fP v1 API on top of \fBktxTexture\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIstream\fP pointer to the stream to read KTX data from\&. 
.br
\fIcreateFlags\fP bitmask requesting specific actions during creation\&. 
.br
\fInewTex\fP pointer to a location in which store the address of the newly created texture\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP Either \fRbytes\fP is NULL or \fRsize\fP is 0\&.
.RE
.PP
For other exceptions, see \fBktxTexture2_CreateFromStdioStream()\fP\&. 
.SS "\fBKTX_error_code\fP ktxTexture2_DecodeAstc (\fBktxTexture2\fP * This)"

.PP
Decodes a ktx2 texture object, if it is ASTC encoded\&. The decompressed format is calculated from corresponding ASTC format\&. There are only 3 possible options currently supported\&. RGBA8, SRGBA8 and RGBA32\&. 
.PP
\fBNote\fP
.RS 4
3d textures are decoded to a multi-slice 3d texture\&.
.RE
.PP
Updates \fRThis\fP with the decoded image\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP The texture to decode
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP DFD is incorrect: supercompression scheme or sample's channelId do not match ASTC colorModel\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's images are not in ASTC format\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture object does not contain any data\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP ASTC decoder failed to decompress image\&. Possibly due to incorrect floating point compilation settings\&. Should not happen in release package\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out decoding\&. 
.br
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP The texture's images are supercompressed with an unsupported scheme\&. 
.br
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP ASTC encoder not compiled with enough capacity for requested block size\&. Should not happen in release package\&. 
.RE
.PP

.SS "void ktxTexture2_Destroy (\fBktxTexture2\fP * This)"

.PP
Destroy a \fBktxTexture2\fP object\&. This frees the memory associated with the texture contents and the memory of the \fBktxTexture2\fP object\&. This does \fInot\fP delete any OpenGL or Vulkan texture objects created by ktxTexture2_GLUpload or ktxTexture2_VkUpload\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object to destroy 
.RE
.PP

.SS "khr_df_model_e ktxTexture2_GetColorModel_e (\fBktxTexture2\fP * This)"

.PP
Retrieve the DFD color model of the images\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
A \fRkhr_df_transfer\fP enum value specifying the color model\&. 
.RE
.PP

.SS "void ktxTexture2_GetComponentInfo (\fBktxTexture2\fP * This, uint32_t * pNumComponents, uint32_t * pComponentByteLength)"

.PP
Return information about the components of an image in a texture\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIpNumComponents\fP pointer to location in which to write the number of components in the textures images\&. 
.br
\fIpComponentByteLength\fP pointer to the location in which to write byte length of a component\&. 
.RE
.PP

.SS "ktx_size_t ktxTexture2_GetDataSizeUncompressed (\fBktxTexture2\fP * This)"

.PP
Return the total size in bytes of the uncompressed data of a \fBktxTexture2\fP\&. If supercompressionScheme == \fRKTX_SS_NONE\fP or \fRKTX_SS_BASIS_LZ\fP, returns the value of \fRThis->dataSize\fP else if supercompressionScheme == \fRKTX_SS_ZSTD\fP or \fRKTX_SS_ZLIB\fP, it returns the sum of the uncompressed sizes of each mip level plus space for the level padding\&. With no supercompression the data size and uncompressed data size are the same\&. For Basis supercompression the uncompressed size cannot be known until the data is transcoded so the compressed size is returned\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture1\fP object of interest\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_GetImageOffset (\fBktxTexture2\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t * pOffset)"

.PP
Find the offset of an image within a \fBktxTexture\fP's image data\&. As there is no such thing as a 3D cubemap we make the 3rd location parameter do double duty\&. Only works for non-supercompressed textures as there is no way to tell where an image is for a supercompressed one\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIlevel\fP mip level of the image\&. 
.br
\fIlayer\fP array layer of the image\&. 
.br
\fIfaceSlice\fP cube map face or depth slice of the image\&. 
.br
\fIpOffset\fP pointer to location to store the offset\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRlevel\fP, \fRlayer\fP or \fRfaceSlice\fP exceed the dimensions of the texture\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP Texture is supercompressed\&. 
.br
\fIKTX_INVALID_VALID\fP \fRThis\fP is NULL\&. 
.RE
.PP

.SS "ktx_size_t ktxTexture2_GetImageSize (\fBktxTexture2\fP * This, ktx_uint32_t level)"

.PP
Calculate & return the size in bytes of an image at the specified mip level\&. For arrays, this is the size of a layer, for cubemaps, the size of a face and for 3D textures, the size of a depth slice\&.

.PP
The size reflects the padding of each row to KTX_GL_UNPACK_ALIGNMENT\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. 
.br
\fIlevel\fP level of interest\&. * 
.RE
.PP

.SS "ktx_size_t ktxTexture2_GetLevelSize (\fBktxTexture2\fP * This, ktx_uint32_t level)"

.PP
Calculate & return the size in bytes of all the images in the specified mip level\&. For arrays, this is the size of all layers in the level, for cubemaps, the size of all faces in the level and for 3D textures, the size of all depth slices in the level\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. 
.br
\fIlevel\fP level of interest\&. * 
.RE
.PP

.SS "ktx_uint32_t ktxTexture2_GetNumComponents (\fBktxTexture2\fP * This)"

.PP
Return the number of components in an image of the texture\&. Returns the number of components indicated by the DFD's sample information in accordance with the color model\&. For uncompressed formats it will be the actual number of components in the image\&. For block-compressed formats, it will be 1 or 2 according to the format's DFD color model\&. For Basis compressed textures, the function examines the ids of the channels indicated by the DFD and uses that information to determine and return the number of components in the image \fIbefore\fP encoding and deflation so it can be used to help choose a suitable transcode target format\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
the number of components\&. 
.RE
.PP

.SS "ktx_uint32_t ktxTexture2_GetOETF (\fBktxTexture2\fP * This)"

.PP
Retrieve the transfer function of the images\&. 
.PP
\fBDeprecated\fP
.RS 4
Use ktxTexture2_GetTransferFunction_e\&.
.RE
.PP

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
A \fRkhr_df_transfer\fP enum value specifying the transfer function, returned as \fRktx_uint32_t\fP\&. 
.RE
.PP

.SS "khr_df_transfer_e ktxTexture2_GetOETF_e (\fBktxTexture2\fP * This)"

.PP
Retrieve the transfer function of the images\&. 
.PP
\fBDeprecated\fP
.RS 4
Use ktxTexture2_GetTransferFunction_e\&. Now that the KTX specification allows setting of non-linear transfer functions other than sRGB, it is possible for the transfer function to be an EOTF so this name is no longer appropriate\&.
.RE
.PP

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
A \fRkhr_df_transfer\fP enum value specifying the transfer function\&. 
.RE
.PP

.SS "ktx_bool_t ktxTexture2_GetPremultipliedAlpha (\fBktxTexture2\fP * This)"

.PP
Retrieve whether the RGB components have been premultiplied by the alpha component\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_TRUE if the components are premultiplied, KTX_FALSE otherwise\&. 
.RE
.PP

.SS "khr_df_primaries_e ktxTexture2_GetPrimaries_e (\fBktxTexture2\fP * This)"

.PP
Retrieve the color primaries of the images\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
A \fRkhr_df_primaries\fP enum value specifying the primaries\&. 
.RE
.PP

.SS "khr_df_transfer_e ktxTexture2_GetTransferFunction_e (\fBktxTexture2\fP * This)"

.PP
Retrieve the transfer function of the images\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
A \fRkhr_df_transfer\fP enum value specifying the transfer function\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_IterateLevels (\fBktxTexture2\fP * This, PFNKTXITERCB iterCb, void * userdata)"

.PP
Iterate over the mip levels in a \fBktxTexture2\fP 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\&.

.PP
This function works even if \fRThis->pData\fP == 0 so it can be used to obtain offsets and sizes for each level by callers who have loaded the data externally\&.

.PP
Intended for use only when supercompressionScheme == SUPERCOMPRESSION_NONE\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP handle of the \fBktxTexture\fP opened on the data\&. 
.br
\fIiterCb\fP the address of a callback function which is called with the data for each image block\&. 
.br
\fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Mip level sizes are increasing not decreasing 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP supercompressionScheme != SUPERCOMPRESSION_NONE\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_IterateLoadLevelFaces (\fBktxTexture2\fP * This, PFNKTXITERCB iterCb, void * userdata)"

.PP
Iterate over the images in a \fBktxTexture2\fP object while loading the image data\&. This operates similarly to ktxTexture_IterateLevelFaces() except that it loads the images from the \fBktxTexture2\fP's source to a temporary buffer while iterating\&. If supercompressionScheme == KTX_SS_ZSTD or KTX_SS_ZLIB, it will inflate the data before passing it to the callback\&. 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\&.

.PP
This function is helpful for reducing memory usage when uploading the data to a graphics API\&.

.PP
Intended for use only when supercompressionScheme == KTX_SS_NONE, KTX_SS_ZSTD or KTX_SS_ZLIB\&. As there is no access to the \fBktxTexture\fP's data on conclusion of this function, destroying the texture on completion is recommended\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. 
.br
\fIiterCb\fP the address of a callback function which is called with the data for each image\&. 
.br
\fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP mip level sizes are increasing not decreasing 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP the \fBktxTexture2\fP was not created from a stream, i\&.e there is no data to load, or this \fBktxTexture2\fP's images have already been loaded\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP supercompressionScheme != KTX_SS_NONE, supercompressionScheme != KTX_SS_ZSTD, and supercompressionScheme != KTX_SS_ZLIB\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP not enough memory to allocate a block to hold the base level image\&. 
.RE
.PP

.SS "\fBktx_error_code_e\fP ktxTexture2_LoadDeflatedImageData (\fBktxTexture2\fP * This, ktx_uint8_t * pBuffer, ktx_size_t bufSize)"

.PP
Load all the image data from the \fBktxTexture2\fP's source without inflatiion\&.\&. The data will be not be inflated if supercompressionScheme == \fRKTX_SS_ZSTD\fP or \fRKTX_SS_ZLIB\fP\&. This function is provided to support some rare testing scenarios\&. Generally use of ktxTexture2_LoadImageData is highly recommended\&. For supercompressionScheme values other than those mentioned, the result of this function is the same as ktxTexture2_LoadImageData\&.

.PP
The data is loaded into the provided buffer or to an internally allocated buffer, if \fRpBuffer\fP is \fRNULL\fP\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIpBuffer\fP pointer to the buffer in which to load the image data\&. 
.br
\fIbufSize\fP size of the buffer pointed at by \fRpBuffer\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is NULL\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRbufSize\fP is less than the the image data size\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The data has already been loaded or the \fBktxTexture\fP was not created from a KTX source\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Insufficient memory for the image data\&. 
.RE
.PP

.SS "\fBktx_error_code_e\fP ktxTexture2_LoadImageData (\fBktxTexture2\fP * This, ktx_uint8_t * pBuffer, ktx_size_t bufSize)"

.PP
Load all the image data from the \fBktxTexture2\fP's source\&. The data will be inflated if supercompressionScheme == \fRKTX_SS_ZSTD\fP or \fRKTX_SS_ZLIB\fP\&. The data is loaded into the provided buffer or to an internally allocated buffer, if \fRpBuffer\fP is \fRNULL\fP\&. Callers providing their own buffer must ensure the buffer large enough to hold the inflated data for files deflated with Zstd or ZLIB\&. See \fBktxTexture2_GetDataSizeUncompressed()\fP\&.

.PP
The texture's levelIndex, dataSize, DFD and supercompressionScheme will all be updated after successful inflation to reflect the inflated data\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIpBuffer\fP pointer to the buffer in which to load the image data\&. 
.br
\fIbufSize\fP size of the buffer pointed at by \fRpBuffer\fP\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is NULL\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRbufSize\fP is less than the the image data size\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The data has already been loaded or the \fBktxTexture\fP was not created from a KTX source\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Insufficient memory for the image data\&. 
.RE
.PP

.SS "ktx_bool_t ktxTexture2_NeedsTranscoding (\fBktxTexture2\fP * This)"

.PP
Query if the images are in a transcodable format\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture2_TranscodeBasis (\fBktxTexture2\fP * This, \fBktx_transcode_fmt_e\fP outputFormat, ktx_transcode_flags transcodeFlags)"

.PP
Transcode a KTX2 texture with BasisLZ/ETC1S or UASTC images\&. If the texture contains BasisLZ supercompressed images, Inflates them from back to ETC1S then transcodes them to the specified block-compressed format\&. If the texture contains UASTC images, inflates them, if they have been supercompressed with zstd, then transcodes then to the specified format, The transcoded images replace the original images and the texture's fields including the DFD are modified to reflect the new format\&.

.PP
These types of textures must be transcoded to a desired target block-compressed format before they can be uploaded to a GPU via a graphics API\&.

.PP
The following block compressed transcode targets are available: \fRKTX_TTF_ETC1_RGB\fP, \fRKTX_TTF_ETC2_RGBA\fP, \fRKTX_TTF_BC1_RGB\fP, \fRKTX_TTF_BC3_RGBA\fP, \fRKTX_TTF_BC4_R\fP, \fRKTX_TTF_BC5_RG\fP, \fRKTX_TTF_BC7_RGBA\fP, \fR\fRKTX_TTF_PVRTC1_4_RGB\fP,\fP \fRKTX_TTF_PVRTC1_4_RGBA\fP, \fRKTX_TTF_PVRTC2_4_RGB\fP, \fRKTX_TTF_PVRTC2_4_RGBA\fP, \fRKTX_TTF_ASTC_4x4_RGBA\fP, \fRKTX_TTF_ETC2_EAC_R11\fP, \fRKTX_TTF_ETC2_EAC_RG11\fP, \fRKTX_TTF_ETC\fP and \fRKTX_TTF_BC1_OR_3\fP\&.

.PP
\fRKTX_TTF_ETC\fP automatically selects between \fRKTX_TTF_ETC1_RGB\fP and \fRKTX_TTF_ETC2_RGBA\fP according to whether an alpha channel is available\&. \fRKTX_TTF_BC1_OR_3\fP does likewise between \fRKTX_TTF_BC1_RGB\fP and \fRKTX_TTF_BC3_RGBA\fP\&. Note that if \fRKTX_TTF_PVRTC1_4_RGBA\fP or \fRKTX_TTF_PVRTC2_4_RGBA\fP is specified and there is no alpha channel \fRKTX_TTF_PVRTC1_4_RGB\fP or \fRKTX_TTF_PVRTC2_4_RGB\fP respectively will be selected\&.

.PP
Transcoding to ATC & FXT1 formats is not supported by libktx as there are no equivalent Vulkan formats\&.

.PP
The following uncompressed transcode targets are also available: \fRKTX_TTF_RGBA32\fP, \fRKTX_TTF_RGB565\fP, KTX_TTF_BGR565 and KTX_TTF_RGBA4444\&.

.PP
The following \fRtranscodeFlags\fP are available\&.

.PP
\fBSee also\fP
.RS 4
ktxtexture2_CompressBasis()\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&. 
.br
\fIoutputFormat\fP a value from the ktx_texture_transcode_fmt_e enum specifying the target format\&. 
.br
\fItranscodeFlags\fP bitfield of flags modifying the transcode operation\&. 
.RE
.PP
\fBSee also\fP
.RS 4
ktx_texture_decode_flags_e\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Supercompression global data is corrupted\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's format is not transcodable (not ETC1S/BasisLZ or UASTC)\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP Supercompression global data is missing, i\&.e\&., the texture object is invalid\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP Image data is missing, i\&.e\&., the texture object is invalid\&. 
.br
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRoutputFormat\fP is PVRTC1 but the texture does does not have power-of-two dimensions\&. 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRoutputFormat\fP is invalid\&. 
.br
\fI\fBKTX_TRANSCODE_FAILED\fP\fP Something went wrong during transcoding\&. 
.br
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP KTX_TF_PVRTC_DECODE_TO_NEXT_POW2 was requested or the specified transcode target has not been included in the library being used\&. 
.br
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out transcoding\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture_CreateFromMemory (const ktx_uint8_t * bytes, ktx_size_t size, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP or \fBktxTexture2\fP from KTX-formatted data in memory according to the data contents\&. See \fBktxTexture1_CreateFromMemory\fP or \fBktxTexture2_CreateFromMemory\fP for details\&. 
.SS "\fBKTX_error_code\fP ktxTexture_CreateFromNamedFile (const char *const filename, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP or \fBktxTexture2\fP from a named KTX file according to the file contents\&. See \fBktxTexture1_CreateFromNamedFile\fP or \fBktxTexture2_CreateFromNamedFile\fP for details\&. 
.SS "\fBKTX_error_code\fP ktxTexture_CreateFromStdioStream (FILE * stdioStream, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP ** newTex)"

.PP
Create a \fBktxTexture1\fP or \fBktxTexture2\fP from a stdio stream according to the stream data\&. See \fBktxTexture1_CreateFromStdioStream\fP or \fBktxTexture2_CreateFromStdioStream\fP for details\&. 
.SS "\fBKTX_error_code\fP ktxTexture_CreateFromStream (\fBktxStream\fP * pStream, \fBktxTextureCreateFlags\fP createFlags, \fBktxTexture\fP ** newTex)"

.PP
Create a ktx1 or ktx2 texture according to the stream data\&. See \fBktxTexture1_CreateFromStream\fP or \fBktxTexture2_CreateFromStream\fP for details\&. 
.SS "ktx_uint8_t * ktxTexture_GetData (\fBktxTexture\fP * This)"

.PP
Return a pointer to the texture image data\&. 
.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.RE
.PP

.SS "ktx_size_t ktxTexture_GetDataSize (\fBktxTexture\fP * This)"

.PP
Return the total size of the texture image data in bytes\&. For a \fBktxTexture2\fP with supercompressionScheme != KTX_SS_NONE this will return the deflated size of the data\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.RE
.PP

.SS "ktx_uint32_t ktxTexture_GetElementSize (\fBktxTexture\fP * This)"

.PP
Return the size in bytes of an elements of a texture's images\&. For uncompressed textures an element is one texel\&. For compressed textures it is one block\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.RE
.PP

.SS "ktx_uint32_t ktxTexture_GetRowPitch (\fBktxTexture\fP * This, ktx_uint32_t level)"

.PP
Return pitch between rows of a texture image level in bytes\&. For uncompressed textures the pitch is the number of bytes between rows of texels\&. For compressed textures it is the number of bytes between rows of blocks\&. The value is padded to GL_UNPACK_ALIGNMENT, if necessary\&. For all currently known compressed formats padding will not be necessary\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIlevel\fP level of interest\&.
.RE
.PP
\fBReturns\fP
.RS 4
the row pitch in bytes\&. 
.RE
.PP

.SS "\fBKTX_error_code\fP ktxTexture_IterateLevelFaces (\fBktxTexture\fP * This, \fBPFNKTXITERCB\fP iterCb, void * userdata)"

.PP
Iterate over the levels or faces in a \fBktxTexture\fP 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\&.

.PP
This function works even if \fRThis->pData\fP == 0 so it can be used to obtain offsets and sizes for each level by callers who have loaded the data externally\&.

.PP
\fBParameters\fP
.RS 4
\fIThis\fP pointer to the \fBktxTexture\fP object of interest\&. 
.br
\fIiterCb\fP the address of a callback function which is called with the data for each image block\&. 
.br
\fIuserdata\fP the address of application-specific data which is passed to the callback along with the image data\&.
.RE
.PP
\fBReturns\fP
.RS 4
KTX_SUCCESS on success, other KTX_* enum values on error\&. The following are returned directly by this function\&. \fRiterCb\fP may return these for other causes or may return additional errors\&.
.RE
.PP
\fBExceptions\fP
.RS 4
\fI\fBKTX_FILE_DATA_ERROR\fP\fP Mip level sizes are increasing not decreasing 
.br
\fI\fBKTX_INVALID_VALUE\fP\fP \fRThis\fP is \fRNULL\fP or \fRiterCb\fP is \fRNULL\fP\&. 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for libktx Reference from the source code\&.