libktx - The KTX Library
Reader

Read KTX-formatted data. More...

Functions

KTX_error_code ktxTexture::ktxTexture_CreateFromStdioStream (FILE *stdioStream, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
 Create a ktxTexture from a stdio stream reading from a KTX source. More...
 
KTX_error_code ktxTexture::ktxTexture_CreateFromNamedFile (const char *const filename, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
 Create a ktxTexture from a named KTX file. More...
 
KTX_error_code ktxTexture::ktxTexture_CreateFromMemory (const ktx_uint8_t *bytes, ktx_size_t size, ktxTextureCreateFlags createFlags, ktxTexture **newTex)
 Create a ktxTexture from KTX-formatted data in memory. More...
 
void ktxTexture::ktxTexture_Destroy (ktxTexture *This)
 Destroy a ktxTexture object. More...
 
ktx_uint8_t * ktxTexture::ktxTexture_GetData (ktxTexture *This)
 Return a pointer to the texture image data. More...
 
ktx_size_t ktxTexture::ktxTexture_GetSize (ktxTexture *This)
 Return the size of the texture image data in bytes. More...
 
KTX_error_code ktxTexture::ktxTexture_LoadImageData (ktxTexture *This, ktx_uint8_t *pBuffer, ktx_size_t bufSize)
 Load all the image data from the ktxTexture's source. More...
 
KTX_error_code ktxTexture::ktxTexture_IterateLevelFaces (ktxTexture *This, PFNKTXITERCB iterCb, void *userdata)
 Iterate over the images in a ktxTexture object. More...
 
KTX_error_code ktxTexture::ktxTexture_IterateLoadLevelFaces (ktxTexture *This, PFNKTXITERCB iterCb, void *userdata)
 Iterate over the images in a ktxTexture object while loading the image data. More...
 
KTX_error_code ktxTexture::ktxTexture_IterateLevels (ktxTexture *This, PFNKTXITERCB iterCb, void *userdata)
 Iterate over the mip levels in a ktxTexture object. More...
 
KTX_error_code ktxTexture::ktxTexture_GetImageOffset (ktxTexture *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, ktx_size_t *pOffset)
 Find the offset of an image within a ktxTexture's image data. More...
 

Detailed Description

Read KTX-formatted data.

Function Documentation

◆ ktxTexture_CreateFromMemory()

KTX_error_code ktxTexture_CreateFromMemory ( const ktx_uint8_t *  bytes,
ktx_size_t  size,
ktxTextureCreateFlags  createFlags,
ktxTexture **  newTex 
)

Create a ktxTexture from KTX-formatted data in memory.

The address of a newly created ktxTexture reflecting the contents of the serialized KTX data is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture 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.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters
[in]bytespointer to the memory containing the serialized KTX data.
[in]sizelength of the KTX data in bytes.
[in]createFlagsbitmask requesting specific actions during creation.
[in,out]newTexpointer to a location in which store the address of the newly created texture.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEEither bytes is NULL or size is 0.

For other exceptions, see ktxTexture_CreateFromStdioStream().

Examples:
glloader.c.

◆ ktxTexture_CreateFromNamedFile()

KTX_error_code ktxTexture_CreateFromNamedFile ( const char *const  filename,
ktxTextureCreateFlags  createFlags,
ktxTexture **  newTex 
)

Create a ktxTexture from a named KTX file.

The address of a newly created ktxTexture reflecting the contents of the file is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture 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.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters
[in]filenamepointer to a char array containing the file name.
[in]createFlagsbitmask requesting specific actions during creation.
[in,out]newTexpointer to a location in which store the address of the newly created texture.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_FILE_OPEN_FAILEDThe file could not be opened.
KTX_INVALID_VALUEfilename is NULL.

For other exceptions, see ktxTexture_CreateFromStdioStream().

Examples:
vkload.cpp.

◆ ktxTexture_CreateFromStdioStream()

KTX_error_code ktxTexture_CreateFromStdioStream ( FILE *  stdioStream,
ktxTextureCreateFlags  createFlags,
ktxTexture **  newTex 
)

Create a ktxTexture from a stdio stream reading from a KTX source.

The address of a newly created ktxTexture reflecting the contents of the stdio stream is written to the location pointed at by newTex.

The create flag KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT should not be set, if the ktxTexture 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.

The create flag KTX_TEXTURE_CREATE_RAW_KVDATA_BIT should not be used. It is provided solely to enable implementation of the libktx v1 API on top of ktxTexture.

Parameters
[in]stdioStreamstdio FILE pointer created from the desired file.
[in]createFlagsbitmask requesting specific actions during creation.
[in,out]newTexpointer to a location in which store the address of the newly created texture.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEnewTex is NULL.
KTX_FILE_DATA_ERRORSource data is inconsistent with the KTX specification.
KTX_FILE_READ_ERRORAn error occurred while reading the source.
KTX_FILE_UNEXPECTED_EOFNot enough data in the source.
KTX_OUT_OF_MEMORYNot enough memory to create the texture object, load the images or load the key-value data.
KTX_UNKNOWN_FILE_FORMATThe source is not in KTX format.
KTX_UNSUPPORTED_TEXTURE_TYPEThe source describes a texture type not supported by OpenGL or Vulkan, e.g, a 3D array.
Examples:
glloader.c.

◆ ktxTexture_Destroy()

void ktxTexture_Destroy ( ktxTexture This)

Destroy a ktxTexture object.

This frees the memory associated with the texture contents and the memory of the ktxTexture object. This does not delete any OpenGL or Vulkan texture objects created by ktxTexture_GLUpload or ktxTexture_VkUpload.

Parameters
[in]Thispointer to the ktxTexture object to destroy
Examples:
glloader.c, and vkload.cpp.

◆ ktxTexture_GetData()

ktx_uint8_t * ktxTexture_GetData ( ktxTexture This)

Return a pointer to the texture image data.

Parameters
[in]Thispointer to the ktxTexture object of interest.

◆ ktxTexture_GetImageOffset()

KTX_error_code ktxTexture_GetImageOffset ( ktxTexture This,
ktx_uint32_t  level,
ktx_uint32_t  layer,
ktx_uint32_t  faceSlice,
ktx_size_t *  pOffset 
)

Find the offset of an image within a ktxTexture's image data.

As there is no such thing as a 3D cubemap we make the 3rd location parameter do double duty.

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in]levelmip level of the image.
[in]layerarray layer of the image.
[in]faceSlicecube map face or depth slice of the image.
[in,out]pOffsetpointer to location to store the offset.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_OPERATIONlevel, layer or faceSlice exceed the dimensions of the texture.

◆ ktxTexture_GetSize()

ktx_size_t ktxTexture_GetSize ( ktxTexture This)

Return the size of the texture image data in bytes.

Parameters
[in]Thispointer to the ktxTexture object of interest.

◆ ktxTexture_IterateLevelFaces()

KTX_error_code ktxTexture_IterateLevelFaces ( ktxTexture This,
PFNKTXITERCB  iterCb,
void *  userdata 
)

Iterate over the images in a ktxTexture 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.

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

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in,out]iterCbthe address of a callback function which is called with the data for each image block.
[in,out]userdatathe address of application-specific data which is passed to the callback along with the image data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error. The following are returned directly by this function. iterCb may return these for other causes or may return additional errors.
Exceptions
KTX_FILE_DATA_ERRORMip level sizes are increasing not decreasing
KTX_INVALID_VALUEThis is NULL or iterCb is NULL.
Examples:
glloader.c.

◆ ktxTexture_IterateLevels()

KTX_error_code ktxTexture_IterateLevels ( ktxTexture This,
PFNKTXITERCB  iterCb,
void *  userdata 
)

Iterate over the mip levels in a ktxTexture 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.

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

Parameters
[in]Thishandle of the ktxTexture opened on the data.
[in,out]iterCbthe address of a callback function which is called with the data for each image block.
[in,out]userdatathe address of application-specific data which is passed to the callback along with the image data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error. The following are returned directly by this function. iterCb may return these for other causes or may return additional errors.
Exceptions
KTX_FILE_DATA_ERRORMip level sizes are increasing not decreasing
KTX_INVALID_VALUEThis is NULL or iterCb is NULL.

◆ ktxTexture_IterateLoadLevelFaces()

KTX_error_code ktxTexture_IterateLoadLevelFaces ( ktxTexture This,
PFNKTXITERCB  iterCb,
void *  userdata 
)

Iterate over the images in a ktxTexture object while loading the image data.

This operates similarly to ktxTexture_IterateLevelFaces() except that it loads the images from the ktxTexture'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.

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

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in,out]iterCbthe address of a callback function which is called with the data for each image.
[in,out]userdatathe address of application-specific data which is passed to the callback along with the image data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error. The following are returned directly by this function. iterCb may return these for other causes or may return additional errors.
Exceptions
KTX_FILE_DATA_ERRORmip level sizes are increasing not decreasing
KTX_INVALID_OPERATIONthe ktxTexture was not created from a stream, i.e there is no data to load, or this ktxTexture's images have already been loaded.
KTX_INVALID_VALUEThis is NULL or iterCb is NULL.
KTX_OUT_OF_MEMORYnot enough memory to allocate a block to hold the base level image.
Examples:
glloader.c.

◆ ktxTexture_LoadImageData()

KTX_error_code ktxTexture_LoadImageData ( ktxTexture This,
ktx_uint8_t *  pBuffer,
ktx_size_t  bufSize 
)

Load all the image data from the ktxTexture's source.

The data is loaded into the provided buffer or to an internally allocated buffer, if pBuffer is NULL.

Parameters
[in]Thispointer to the ktxTexture object of interest.
[in]pBufferpointer to the buffer in which to load the image data.
[in]bufSizesize of the buffer pointed at by pBuffer.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis is NULL.
KTX_INVALID_VALUEbufSize is less than the the image data size.
KTX_INVALID_OPERATIONThe data has already been loaded or the ktxTexture was not created from a KTX source.
KTX_OUT_OF_MEMORYInsufficient memory for the image data.