1108 lines
39 KiB
Plaintext
1108 lines
39 KiB
Plaintext
.TH "writer" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
writer \- Writer
|
|
.PP
|
|
\- Write KTX-formatted data\&.
|
|
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.SS "Functions"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_CompressAstcEx\fP (\fBktxTexture2\fP *This, \fBktxAstcParams\fP *params)"
|
|
.br
|
|
.RI "Encode and compress a ktx texture with uncompressed images to astc\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_CompressAstc\fP (\fBktxTexture2\fP *This, ktx_uint32_t quality)"
|
|
.br
|
|
.RI "Encode and compress a ktx texture with uncompressed images to astc\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_CompressBasisEx\fP (\fBktxTexture2\fP *This, \fBktxBasisParams\fP *params)"
|
|
.br
|
|
.RI "Encode and possibly Supercompress a KTX2 texture with uncompressed images\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_CompressBasis\fP (\fBktxTexture2\fP *This, ktx_uint32_t quality)"
|
|
.br
|
|
.RI "Supercompress a KTX2 texture with uncompressed images\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_Create\fP (const \fBktxTextureCreateInfo\fP *const createInfo, ktxTextureCreateStorageEnum storageAllocation, \fBktxTexture1\fP **newTex)"
|
|
.br
|
|
.RI "Create a new empty \fBktxTexture1\fP\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_Create\fP (const \fBktxTextureCreateInfo\fP *const createInfo, ktxTextureCreateStorageEnum storageAllocation, \fBktxTexture2\fP **newTex)"
|
|
.br
|
|
.RI "Create a new empty \fBktxTexture2\fP\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_CreateCopy\fP (\fBktxTexture2\fP *orig, \fBktxTexture2\fP **newTex)"
|
|
.br
|
|
.RI "Create a \fBktxTexture2\fP by making a copy of a \fBktxTexture2\fP\&. "
|
|
.ti -1c
|
|
.RI "\fBktx_error_code_e\fP \fBktxTexture2_SetOETF\fP (\fBktxTexture2\fP *This, khr_df_transfer_e tf)"
|
|
.br
|
|
.RI "Set the transfer function for the images in a texture\&. "
|
|
.ti -1c
|
|
.RI "\fBktx_error_code_e\fP \fBktxTexture2_SetPrimaries\fP (\fBktxTexture2\fP *This, khr_df_primaries_e primaries)"
|
|
.br
|
|
.RI "Set the primaries for the images in a texture\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_SetImageFromStdioStream\fP (\fBktxTexture1\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE *src, ktx_size_t srcSize)"
|
|
.br
|
|
.RI "Set image for level, layer, faceSlice from a stdio stream source\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_SetImageFromMemory\fP (\fBktxTexture1\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t *src, ktx_size_t srcSize)"
|
|
.br
|
|
.RI "Set image for level, layer, faceSlice from an image in memory\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteToStream\fP (\fBktxTexture1\fP *This, \fBktxStream\fP *dststr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteToStdioStream\fP (\fBktxTexture1\fP *This, FILE *dstsstr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a stdio stream in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteToNamedFile\fP (\fBktxTexture1\fP *This, const char *const dstname)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a named file in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteToMemory\fP (\fBktxTexture1\fP *This, ktx_uint8_t **ppDstBytes, ktx_size_t *pSize)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to block of memory in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteKTX2ToStream\fP (\fBktxTexture1\fP *This, \fBktxStream\fP *dststr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX 2 format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteKTX2ToStdioStream\fP (\fBktxTexture1\fP *This, FILE *dstsstr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a stdio stream in KTX2 format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteKTX2ToNamedFile\fP (\fBktxTexture1\fP *This, const char *const dstname)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a named file in KTX2 format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture1_WriteKTX2ToMemory\fP (\fBktxTexture1\fP *This, ktx_uint8_t **ppDstBytes, ktx_size_t *pSize)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to block of memory in KTX2 format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_SetImageFromStdioStream\fP (\fBktxTexture2\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE *src, ktx_size_t srcSize)"
|
|
.br
|
|
.RI "Set image for level, layer, faceSlice from a stdio stream source\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_SetImageFromMemory\fP (\fBktxTexture2\fP *This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t *src, ktx_size_t srcSize)"
|
|
.br
|
|
.RI "Set image for level, layer, faceSlice from an image in memory\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_WriteToStream\fP (\fBktxTexture2\fP *This, \fBktxStream\fP *dststr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_WriteToStdioStream\fP (\fBktxTexture2\fP *This, FILE *dstsstr)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a stdio stream in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_WriteToNamedFile\fP (\fBktxTexture2\fP *This, const char *const dstname)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to a named file in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_WriteToMemory\fP (\fBktxTexture2\fP *This, ktx_uint8_t **ppDstBytes, ktx_size_t *pSize)"
|
|
.br
|
|
.RI "Write a \fBktxTexture\fP object to block of memory in KTX format\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_DeflateZstd\fP (\fBktxTexture2\fP *This, ktx_uint32_t compressionLevel)"
|
|
.br
|
|
.RI "Deflate the data in a \fBktxTexture2\fP object using Zstandard\&. "
|
|
.ti -1c
|
|
.RI "\fBKTX_error_code\fP \fBktxTexture2_DeflateZLIB\fP (\fBktxTexture2\fP *This, ktx_uint32_t compressionLevel)"
|
|
.br
|
|
.RI "Deflate the data in a \fBktxTexture2\fP object using miniz (ZLIB)\&. "
|
|
.in -1c
|
|
.SH "Detailed Description"
|
|
.PP
|
|
Write KTX-formatted data\&.
|
|
|
|
|
|
.SH "Function Documentation"
|
|
.PP
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_Create (const \fBktxTextureCreateInfo\fP *const createInfo, ktxTextureCreateStorageEnum storageAllocation, \fBktxTexture1\fP ** newTex)"
|
|
|
|
.PP
|
|
Create a new empty \fBktxTexture1\fP\&. The address of the newly created \fBktxTexture1\fP is written to the location pointed at by \fRnewTex\fP\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIcreateInfo\fP pointer to a \fBktxTextureCreateInfo\fP struct with information describing the texture\&.
|
|
.br
|
|
\fIstorageAllocation\fP enum indicating whether or not to allocate storage for the texture images\&.
|
|
.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 \fRglInternalFormat\fP in \fRcreateInfo\fP is not a valid OpenGL internal format value\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumDimensions\fP in \fRcreateInfo\fP is not 1, 2 or 3\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP One of \fRbase{Width,Height,Depth}\fP in \fRcreateInfo\fP is 0\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumFaces\fP in \fRcreateInfo\fP is not 1 or 6\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumLevels\fP in \fRcreateInfo\fP is 0\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fRbase{Width,Height,Depth}\fP specified in \fRcreateInfo\fP are inconsistent with \fRnumDimensions\fP\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting a 3D array or 3D cubemap texture\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting a cubemap with non-square or non-2D images\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting more mip levels than needed for the specified \fRbase{Width,Height,Depth}\fP\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory for the texture's images\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_SetImageFromMemory (\fBktxTexture1\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t * src, ktx_size_t srcSize)"
|
|
|
|
.PP
|
|
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 \fBktxTexture\fP's \fRisCompressed\fP field is \fRKTX_TRUE\fP\&.
|
|
|
|
.PP
|
|
Level, layer, faceSlice rather than offset are specified to enable some validation\&.
|
|
|
|
.PP
|
|
\fBWarning\fP
|
|
.RS 4
|
|
Do not use \fRmemcpy\fP for this as it will not pad when necessary\&.
|
|
.RE
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
The caller is responsible for freeing the original image memory referred to by \fRsrc\fP\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIlevel\fP mip level of the image to set\&.
|
|
.br
|
|
\fIlayer\fP array layer of the image to set\&.
|
|
.br
|
|
\fIfaceSlice\fP cube map face or depth slice of the image to set\&.
|
|
.br
|
|
\fIsrc\fP pointer to the image source in memory\&.
|
|
.br
|
|
\fIsrcSize\fP size of the source image in bytes\&.
|
|
.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 or \fRsrc\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_SetImageFromStdioStream (\fBktxTexture1\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE * src, ktx_size_t srcSize)"
|
|
|
|
.PP
|
|
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 \fBktxTexture\fP's \fRisCompressed\fP field is \fRKTX_TRUE\fP\&.
|
|
|
|
.PP
|
|
Level, layer, faceSlice rather than offset are specified to enable some validation\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIlevel\fP mip level of the image to set\&.
|
|
.br
|
|
\fIlayer\fP array layer of the image to set\&.
|
|
.br
|
|
\fIfaceSlice\fP cube map face or depth slice of the image to set\&.
|
|
.br
|
|
\fIsrc\fP stdio stream pointer to the source\&.
|
|
.br
|
|
\fIsrcSize\fP size of the source image in bytes\&.
|
|
.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 or \fRsrc\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteKTX2ToMemory (\fBktxTexture1\fP * This, ktx_uint8_t ** ppDstBytes, ktx_size_t * pSize)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to block of memory in KTX2 format\&. Memory is allocated by the function and the caller is responsible for freeing it\&.
|
|
|
|
.PP
|
|
Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIppDstBytes\fP pointer to location to write the address of the destination memory\&. The Application is responsible for freeing this memory\&.
|
|
.br
|
|
\fIpSize\fP pointer to location to write the size in bytes of the KTX data\&.
|
|
.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, \fRppDstBytes\fP or \fRpSize\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains unknownY KTX- or ktx- prefixed metadata keys\&.
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteKTX2ToNamedFile (\fBktxTexture1\fP * This, const char *const dstname)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a named file in KTX2 format\&. 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
|
|
Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstname\fP destination file name\&.
|
|
.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 or \fRdstname\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains unknownY KTX- or ktx- prefixed metadata keys\&.
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteKTX2ToStdioStream (\fBktxTexture1\fP * This, FILE * dstsstr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a stdio stream in KTX2 format\&. Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstsstr\fP destination stdio stream\&.
|
|
.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 or \fRdstsstr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains unknownY KTX- or ktx- prefixed metadata keys\&.
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteKTX2ToStream (\fBktxTexture1\fP * This, \fBktxStream\fP * dststr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX 2 format\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdststr\fP destination \fBktxStream\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 or \fRdststr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP contains unknownY KTX- or ktx- prefixed metadata keys\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The length of the already set writerId metadata plus the library's version id exceeds the maximum allowed\&.
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteToMemory (\fBktxTexture1\fP * This, ktx_uint8_t ** ppDstBytes, ktx_size_t * pSize)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to block of memory in KTX format\&. Memory is allocated by the function and the caller is responsible for freeing it\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIppDstBytes\fP pointer to location to write the address of the destination memory\&. The Application is responsible for freeing this memory\&.
|
|
.br
|
|
\fIpSize\fP pointer to location to write the size in bytes of the KTX data\&.
|
|
.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, \fRppDstBytes\fP or \fRpSize\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteToNamedFile (\fBktxTexture1\fP * This, const char *const dstname)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a named file in KTX format\&. 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
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstname\fP destination file name\&.
|
|
.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 or \fRdstname\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteToStdioStream (\fBktxTexture1\fP * This, FILE * dstsstr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a stdio stream in KTX format\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstsstr\fP destination stdio stream\&.
|
|
.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 or \fRdstsstr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture1_WriteToStream (\fBktxTexture1\fP * This, \fBktxStream\fP * dststr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX format\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdststr\fP destination \fBktxStream\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 or \fRdststr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_CompressAstc (\fBktxTexture2\fP * This, ktx_uint32_t quality)"
|
|
|
|
.PP
|
|
Encode and compress a ktx texture with uncompressed images to astc\&. The images are either encoded to ASTC block-compressed format\&. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state\&.
|
|
|
|
.PP
|
|
Such textures can be directly uploaded to a GPU via a graphics API\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIquality\fP Compression quality, a value from 0 - 100\&. Higher=higher quality/slower speed\&. Lower=lower quality/faster speed\&. Negative values for quality are considered > 100\&.
|
|
.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 The texture's images are supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's image are in a block compressed format\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image's format is a packed format (e\&.g\&. RGB565)\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image format's component size is not 8-bits\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's images are 1D\&. Only 2D images can be supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out supercompression\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_CompressAstcEx (\fBktxTexture2\fP * This, \fBktxAstcParams\fP * params)"
|
|
|
|
.PP
|
|
Encode and compress a ktx texture with uncompressed images to astc\&. The images are encoded to ASTC block-compressed format\&. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state\&.
|
|
|
|
.PP
|
|
Such textures can be directly uploaded to a GPU via a graphics API\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIparams\fP pointer to ASTC params object\&.
|
|
.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 The texture's images are supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's images are in a block compressed format\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image's format is a packed format (e\&.g\&. RGB565)\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image format's component size is not 8-bits\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's images are 1D\&. Only 2D images can be supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Transfer function of \fRThis\fP is not sRGB or Linear\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRparams->mode\fP is HDR but transfer function of \fRThis\fP is sRGB\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP ASTC encoder failed to compress image\&. Possibly due to incorrect floating point compilation settings\&. Should not happen in release package\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP This->generateMipmaps is set\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out compression\&.
|
|
.br
|
|
\fI\fBKTX_UNSUPPORTED_FEATURE\fP\fP \fRparams->mode\fP is HDR mode which is not yet implemented\&.
|
|
.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 "\fBKTX_error_code\fP ktxTexture2_CompressBasis (\fBktxTexture2\fP * This, ktx_uint32_t quality)"
|
|
|
|
.PP
|
|
Supercompress a KTX2 texture with uncompressed images\&. The images are encoded to ETC1S block-compressed format and supercompressed with Basis Universal\&. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state\&.
|
|
|
|
.PP
|
|
Such textures must be transcoded to a desired target block compressed format before they can be uploaded to a GPU via a graphics API\&.
|
|
|
|
.PP
|
|
\fBSee also\fP
|
|
.RS 4
|
|
\fBktxTexture2_CompressBasisEx()\fP\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIquality\fP Compression quality, a value from 1 - 255\&. Default is 128 which is selected if \fRquality\fP is 0\&. Lower=better compression/lower quality/faster\&. Higher=less compression/higher quality/slower\&.
|
|
.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 The texture is already supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's image are in a block compressed format\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out supercompression\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_CompressBasisEx (\fBktxTexture2\fP * This, \fBktxBasisParams\fP * params)"
|
|
|
|
.PP
|
|
Encode and possibly Supercompress a KTX2 texture with uncompressed images\&. The images are either encoded to ETC1S block-compressed format and supercompressed with Basis LZ or they are encoded to UASTC block-compressed format\&. UASTC format is selected by setting the \fRuastc\fP field of \fIparams\fP to \fRKTX_TRUE\fP\&. The encoded images replace the original images and the texture's fields including the DFD are modified to reflect the new state\&.
|
|
|
|
.PP
|
|
Such textures must be transcoded to a desired target block compressed format before they can be uploaded to a GPU via a graphics API\&.
|
|
|
|
.PP
|
|
\fBSee also\fP
|
|
.RS 4
|
|
\fBktxTexture2_TranscodeBasis()\fP\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIparams\fP pointer to Basis params object\&.
|
|
.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 The texture's images are supercompressed\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture's images are in a block compressed format\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image's format is a packed format (e\&.g\&. RGB565)\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The texture image format's component size is not 8-bits\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRnormalMode\fP is specified but the texture has only one component\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both preSwizzle and and inputSwizzle are specified in \fIparams\fP\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP This->generateMipmaps is set\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory to carry out compression\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_Create (const \fBktxTextureCreateInfo\fP *const createInfo, ktxTextureCreateStorageEnum storageAllocation, \fBktxTexture2\fP ** newTex)"
|
|
|
|
.PP
|
|
Create a new empty \fBktxTexture2\fP\&. The address of the newly created \fBktxTexture2\fP is written to the location pointed at by \fRnewTex\fP\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIcreateInfo\fP pointer to a \fBktxTextureCreateInfo\fP struct with information describing the texture\&.
|
|
.br
|
|
\fIstorageAllocation\fP enum indicating whether or not to allocate storage for the texture images\&.
|
|
.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 \fRglInternalFormat\fP in \fRcreateInfo\fP is not a valid OpenGL internal format value\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumDimensions\fP in \fRcreateInfo\fP is not 1, 2 or 3\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP One of \fRbase{Width,Height,Depth}\fP in \fRcreateInfo\fP is 0\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumFaces\fP in \fRcreateInfo\fP is not 1 or 6\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRnumLevels\fP in \fRcreateInfo\fP is 0\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fRbase{Width,Height,Depth}\fP specified in \fRcreateInfo\fP are inconsistent with \fRnumDimensions\fP\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting a 3D array or 3D cubemap texture\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting a cubemap with non-square or non-2D images\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP \fRcreateInfo\fP is requesting more mip levels than needed for the specified \fRbase{Width,Height,Depth}\fP\&.
|
|
.br
|
|
\fI\fBKTX_OUT_OF_MEMORY\fP\fP Not enough memory for the texture's images\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_CreateCopy (\fBktxTexture2\fP * orig, \fBktxTexture2\fP ** newTex)"
|
|
|
|
.PP
|
|
Create a \fBktxTexture2\fP by making a copy of a \fBktxTexture2\fP\&. The address of the newly created \fBktxTexture2\fP is written to the location pointed at by \fRnewTex\fP\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIorig\fP pointer to the texture to copy\&.
|
|
.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_OUT_OF_MEMORY\fP\fP Not enough memory for the texture data\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_DeflateZLIB (\fBktxTexture2\fP * This, ktx_uint32_t compressionLevel)"
|
|
|
|
.PP
|
|
Deflate the data in a \fBktxTexture2\fP object using miniz (ZLIB)\&. The texture's levelIndex, dataSize, DFD, data pointer, and supercompressionScheme will all be updated after successful deflation to reflect the deflated data\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIcompressionLevel\fP set speed vs compression ratio trade-off\&. Values between 1 and 9 are accepted\&. The lower the level the faster\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_DeflateZstd (\fBktxTexture2\fP * This, ktx_uint32_t compressionLevel)"
|
|
|
|
.PP
|
|
Deflate the data in a \fBktxTexture2\fP object using Zstandard\&. The texture's levelIndex, dataSize, DFD, data pointer, and supercompressionScheme will all be updated after successful deflation to reflect the deflated data\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP object of interest\&.
|
|
.br
|
|
\fIcompressionLevel\fP set speed vs compression ratio trade-off\&. Values between 1 and 22 are accepted\&. The lower the level the faster\&. Values above 20 should be used with caution as they require more memory\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_SetImageFromMemory (\fBktxTexture2\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, const ktx_uint8_t * src, ktx_size_t srcSize)"
|
|
|
|
.PP
|
|
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\&. KTX 2 also requires tight packing this function does not add any padding\&.
|
|
|
|
.PP
|
|
Level, layer, faceSlice rather than offset are specified to enable some validation\&.
|
|
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
The caller is responsible for freeing the original image memory referred to by \fRsrc\fP\&.
|
|
.RE
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIlevel\fP mip level of the image to set\&.
|
|
.br
|
|
\fIlayer\fP array layer of the image to set\&.
|
|
.br
|
|
\fIfaceSlice\fP cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level\&.
|
|
.br
|
|
\fIsrc\fP pointer to the image source in memory\&.
|
|
.br
|
|
\fIsrcSize\fP size of the source image in bytes\&.
|
|
.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 or \fRsrc\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_SetImageFromStdioStream (\fBktxTexture2\fP * This, ktx_uint32_t level, ktx_uint32_t layer, ktx_uint32_t faceSlice, FILE * src, ktx_size_t srcSize)"
|
|
|
|
.PP
|
|
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\&. KTX 2 also requires tight packing this function does not add any padding\&.
|
|
|
|
.PP
|
|
Level, layer, faceSlice rather than offset are specified to enable some validation\&.
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIlevel\fP mip level of the image to set\&.
|
|
.br
|
|
\fIlayer\fP array layer of the image to set\&.
|
|
.br
|
|
\fIfaceSlice\fP cube map face or depth slice of the image to set or KTX_FACESLICE_WHOLE_LEVEL to set the entire level\&.
|
|
.br
|
|
\fIsrc\fP stdio stream pointer to the source\&.
|
|
.br
|
|
\fIsrcSize\fP size of the source image in bytes\&.
|
|
.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 or \fRsrc\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_VALUE\fP\fP \fRsrcSize\fP != the expected image size for the specified level, layer & faceSlice\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP No storage was allocated when the texture was created\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBktx_error_code_e\fP ktxTexture2_SetOETF (\fBktxTexture2\fP * This, khr_df_transfer_e tf)"
|
|
|
|
.PP
|
|
Set the transfer function for the images in a texture\&.
|
|
.PP
|
|
\fBDeprecated\fP
|
|
.RS 4
|
|
Use ktxTexture2_SetTransferFunction\&.
|
|
.RE
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP
|
|
.br
|
|
\fItf\fP enumerator of the transfer function to set
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBktx_error_code_e\fP ktxTexture2_SetPrimaries (\fBktxTexture2\fP * This, khr_df_primaries_e primaries)"
|
|
|
|
.PP
|
|
Set the primaries for the images in a texture\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the \fBktxTexture2\fP
|
|
.br
|
|
\fIprimaries\fP enumerator of the primaries to set
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_WriteToMemory (\fBktxTexture2\fP * This, ktx_uint8_t ** ppDstBytes, ktx_size_t * pSize)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to block of memory in KTX format\&. Memory is allocated by the function and the caller is responsible for freeing it\&.
|
|
|
|
.PP
|
|
Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIppDstBytes\fP pointer to location to write the address of the destination memory\&. The Application is responsible for freeing this memory\&.
|
|
.br
|
|
\fIpSize\fP pointer to location to write the size in bytes of the KTX data\&.
|
|
.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, \fRppDstBytes\fP or \fRpSize\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_WriteToNamedFile (\fBktxTexture2\fP * This, const char *const dstname)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a named file in KTX format\&. 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
|
|
Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstname\fP destination file name\&.
|
|
.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 or \fRdstname\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_WriteToStdioStream (\fBktxTexture2\fP * This, FILE * dstsstr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a stdio stream in KTX format\&. Callers are strongly urged to include a KTXwriter item in the texture's metadata\&. It can be added by code, similar to the following, prior to calling this function\&.
|
|
.PP
|
|
.nf
|
|
char writer[100];
|
|
snprintf(writer, sizeof(writer), "%s version %s", appName, appVer);
|
|
ktxHashList_AddKVPair(&texture\->kvDataHead, KTX_WRITER_KEY,
|
|
(ktx_uint32_t)strlen(writer) + 1,
|
|
writer);
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdstsstr\fP destination stdio stream\&.
|
|
.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 or \fRdstsstr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "\fBKTX_error_code\fP ktxTexture2_WriteToStream (\fBktxTexture2\fP * This, \fBktxStream\fP * dststr)"
|
|
|
|
.PP
|
|
Write a \fBktxTexture\fP object to a \fBktxStream\fP in KTX format\&.
|
|
.PP
|
|
\fBParameters\fP
|
|
.RS 4
|
|
\fIThis\fP pointer to the target \fBktxTexture\fP object\&.
|
|
.br
|
|
\fIdststr\fP destination \fBktxStream\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 or \fRdststr\fP is NULL\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The \fBktxTexture\fP does not contain any image data\&.
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP Both kvDataHead and kvData are set in the \fBktxTexture\fP
|
|
.br
|
|
\fI\fBKTX_INVALID_OPERATION\fP\fP The length of the already set writerId metadata plus the library's version id exceeds the maximum allowed\&.
|
|
.br
|
|
\fI\fBKTX_FILE_OVERFLOW\fP\fP The file exceeded the maximum size supported by the system\&.
|
|
.br
|
|
\fI\fBKTX_FILE_WRITE_ERROR\fP\fP An error occurred while writing the file\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for libktx Reference from the source code\&.
|