libktx - The KTX Library
Writer

Write KTX-formatted data. More...

Functions

KTX_error_code ktxWriteKTXF (FILE *file, const KTX_texture_info *textureInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
 Write image(s) in KTX format to a stdio FILE stream. More...
 
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) in KTX format to a file on disk. More...
 
KTX_error_code ktxWriteKTXM (unsigned char **ppDstBytes, GLsizei *pSize, const KTX_texture_info *textureInfo, GLsizei bytesOfKeyValueData, const void *keyValueData, GLuint numImages, KTX_image_info images[])
 Write image(s) in KTX format to memory. More...
 
KTX_error_code ktxTexture::ktxTexture_Create (ktxTextureCreateInfo *createInfo, ktxTextureCreateStorageEnum storageAllocation, ktxTexture **newTex)
 Create a new empty ktxTexture. More...
 
KTX_error_code ktxTexture::ktxTexture_SetImageFromStdioStream (ktxTexture *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE *src, ktx_size_t srcSize)
 Set image for level, layer, faceSlice from a stdio stream source. More...
 
KTX_error_code ktxTexture::ktxTexture_SetImageFromMemory (ktxTexture *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t *src, ktx_size_t srcSize)
 Set image for level, layer, faceSlice from an image in memory. More...
 
KTX_error_code ktxTexture::ktxTexture_WriteToStdioStream (ktxTexture *This, FILE *dstsstr)
 Write a ktxTexture object to a stdio stream in KTX format. More...
 
KTX_error_code ktxTexture::ktxTexture_WriteToNamedFile (ktxTexture *This, const char *const dstname)
 Write a ktxTexture object to a named file in KTX format. More...
 
KTX_error_code ktxTexture::ktxTexture_WriteToMemory (ktxTexture *This, ktx_uint8_t **ppDstBytes, ktx_size_t *pSize)
 Write a ktxTexture object to block of memory in KTX format. More...
 

Detailed Description

Write KTX-formatted data.

Function Documentation

◆ ktxTexture_Create()

KTX_error_code ktxTexture_Create ( ktxTextureCreateInfo createInfo,
ktxTextureCreateStorageEnum  storageAllocation,
ktxTexture **  newTex 
)

Create a new empty ktxTexture.

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

Parameters
[in]createInfopointer to a ktxTextureCreateInfo struct with information describing the texture.
[in]storageAllocationenum indicating whether or not to allocate storage for the texture images.
[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_VALUEglInternalFormat in createInfo is not a valid OpenGL internal format value.
KTX_INVALID_VALUEnumDimensions in createInfo is not 1, 2 or 3.
KTX_INVALID_VALUEOne of base{Width,Height,Depth} in createInfo is 0.
KTX_INVALID_VALUEnumFaces in createInfo is not 1 or 6.
KTX_INVALID_VALUEnumLevels in createInfo is 0.
KTX_INVALID_OPERATIONThe base{Width,Height,Depth} specified in createInfo are inconsistent with numDimensions.
KTX_INVALID_OPERATIONcreateInfo is requesting a 3D array or 3D cubemap texture.
KTX_INVALID_OPERATIONcreateInfo is requesting a cubemap with non-square or non-2D images.
KTX_INVALID_OPERATIONcreateInfo is requesting more mip levels than needed for the specified base{Width,Height,Depth}.
KTX_OUT_OF_MEMORYNot enough memory for the texture's images.

◆ ktxTexture_SetImageFromMemory()

KTX_error_code ktxTexture_SetImageFromMemory ( ktxTexture This,
ktx_uint32_t  level,
ktx_uint32_t  layer,
ktx_uint32_t  faceSlice,
const ktx_uint8_t *  src,
ktx_size_t  srcSize 
)

Set image for level, layer, faceSlice from an image in memory.

Uncompressed images in memory are expected to have their rows tightly packed as is the norm for most image file formats. The copied image is padded as necessary to achieve the KTX-specified row alignment. No padding is done if the ktxTexture's isCompressed field is KTX_TRUE.

Level, layer, faceSlice rather than offset are specified to enable some validation.

Warning
Do not use memcpy for this as it will not pad when necessary.
Parameters
[in]Thispointer to the target ktxTexture object.
[in]levelmip level of the image to set.
[in]layerarray layer of the image to set.
[in]faceSlicecube map face or depth slice of the image to set.
[in]srcpointer to the image source in memory.
[in]srcSizesize of the source image in bytes.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or src is NULL.
KTX_INVALID_VALUEsrcSize != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATIONNo storage was allocated when the texture was created.

◆ ktxTexture_SetImageFromStdioStream()

KTX_error_code ktxTexture_SetImageFromStdioStream ( ktxTexture This,
ktx_uint32_t  level,
ktx_uint32_t  layer,
ktx_uint32_t  faceSlice,
FILE *  src,
ktx_size_t  srcSize 
)

Set image for level, layer, faceSlice from a stdio stream source.

Uncompressed images read from the stream are expected to have their rows tightly packed as is the norm for most image file formats. The copied image is padded as necessary to achieve the KTX-specified row alignment. No padding is done if the ktxTexture's isCompressed field is KTX_TRUE.

Level, layer, faceSlice rather than offset are specified to enable some validation.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]levelmip level of the image to set.
[in]layerarray layer of the image to set.
[in]faceSlicecube map face or depth slice of the image to set.
[in]srcstdio stream pointer to the source.
[in]srcSizesize of the source image in bytes.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or src is NULL.
KTX_INVALID_VALUEsrcSize != the expected image size for the specified level, layer & faceSlice.
KTX_INVALID_OPERATIONNo storage was allocated when the texture was created.

◆ ktxTexture_WriteToMemory()

KTX_error_code ktxTexture_WriteToMemory ( ktxTexture This,
ktx_uint8_t **  ppDstBytes,
ktx_size_t *  pSize 
)

Write a ktxTexture object to block of memory in KTX format.

Memory is allocated by the function and the caller is responsible for freeing it.

Parameters
[in]Thispointer to the target ktxTexture object.
[in,out]ppDstBytespointer to location to write the address of the destination memory. The Application is responsible for freeing this memory.
[in,out]pSizepointer to location to write the size in bytes of the KTX data.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis, ppDstBytes or pSize is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxTexture_WriteToNamedFile()

KTX_error_code ktxTexture_WriteToNamedFile ( ktxTexture This,
const char *const  dstname 
)

Write a ktxTexture object to a named file in KTX format.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]dstnamedestination file name.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or dstname is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxTexture_WriteToStdioStream()

KTX_error_code ktxTexture_WriteToStdioStream ( ktxTexture This,
FILE *  dstsstr 
)

Write a ktxTexture object to a stdio stream in KTX format.

Parameters
[in]Thispointer to the target ktxTexture object.
[in]dstsstrdestination stdio stream.
Returns
KTX_SUCCESS on success, other KTX_* enum values on error.
Exceptions
KTX_INVALID_VALUEThis or dstsstr is NULL.
KTX_INVALID_OPERATIONThe ktxTexture does not contain any image data.
KTX_FILE_OVERFLOWThe file exceeded the maximum size supported by the system.
KTX_FILE_WRITE_ERRORAn error occurred while writing the file.

◆ ktxWriteKTXF()

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

Write image(s) in KTX format to a stdio FILE stream.

Deprecated:
Use ktxTexture_WriteToStdioStream().
Note
textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.
Parameters
[in]filepointer to the FILE stream to write to.
[in]textureInfopointer to a KTX_texture_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_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_VALUEIn textureInfo, numberOfFaces != 1 or numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_VALUEglType in textureInfo is an unrecognized type.
KTX_INVALID_OPERATIONIn textureInfo, numberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATIONnumImages 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_INVALID_OPERATIONglType and glFormat in textureInfo are mismatched. See OpenGL 4.4 specification section 8.4.4 and table 8.5.
KTX_FILE_WRITE_ERRORA system error occurred while writing the file.
KTX_OUT_OF_MEMORYSystem failed to allocate sufficient memory.

◆ ktxWriteKTXM()

KTX_error_code ktxWriteKTXM ( unsigned char **  ppDstBytes,
GLsizei *  pSize,
const KTX_texture_info textureInfo,
GLsizei  bytesOfKeyValueData,
const void *  keyValueData,
GLuint  numImages,
KTX_image_info  images[] 
)

Write image(s) in KTX format to memory.

Deprecated:
Use ktxTexture_WriteToMemory().

Memory is allocated by the function and the caller is responsible for freeing it.

Note
textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.
Parameters
[out]ppDstBytespointer to location to write the address of the destination memory. The Application is responsible for freeing this memory.
[out]pSizepointer to location to write the size in bytes of the KTX data.
[in]textureInfopointer to a KTX_texture_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 size is 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_VALUEIn textureInfo, numberOfFaces != 1 or numberOfFaces != 6 or numberOfArrayElements or numberOfMipmapLevels are < 0.
KTX_INVALID_VALUEglType in textureInfo is an unrecognized type.
KTX_INVALID_OPERATIONIn textureInfo, numberOfFaces == 6 and images are either not 2D or are not square.
KTX_INVALID_OPERATIONnumImages 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_INVALID_OPERATIONglType and glFormat in textureInfo are mismatched. See OpenGL 4.4 specification section 8.4.4 and table 8.5.
KTX_FILE_WRITE_ERRORA system error occurred while writing the file.
KTX_OUT_OF_MEMORYSystem failed to allocate sufficient memory.

◆ ktxWriteKTXN()

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

Deprecated:
Use ktxTexture_WriteToNamedFile().
Note
textureInfo directly reflects what is written to the KTX file header. That is numberOfArrayElements should be 0 for non arrays; numMipmapLevels should be 0 to request generateMipmaps and type, format & typesize should be 0 for compressed textures.
Parameters
[in]dstnamepointer to a C string that contains the path of the file to load.
[in]textureInfopointer to a KTX_texture_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().