188 lines
7.8 KiB
Plaintext
188 lines
7.8 KiB
Plaintext
.TH "ktxBasisParams" 3 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "libktx Reference" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
ktxBasisParams \- Structure for passing extended parameters to ktxTexture2_CompressBasisEx()\&.
|
|
|
|
.SH SYNOPSIS
|
|
.br
|
|
.PP
|
|
.PP
|
|
\fR#include <ktx\&.h>\fP
|
|
.SS "Data Fields"
|
|
|
|
.in +1c
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBstructSize\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBuastc\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBverbose\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBnoSSE\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBthreadCount\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBcompressionLevel\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBqualityLevel\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBmaxEndpoints\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "float \fBendpointRDOThreshold\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBmaxSelectors\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "float \fBselectorRDOThreshold\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "char \fBinputSwizzle\fP [4]"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBnormalMap\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBseparateRGToRGB_A\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBpreSwizzle\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBnoEndpointRDO\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBnoSelectorRDO\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_pack_uastc_flags \fBuastcFlags\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBuastcRDO\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "float \fBuastcRDOQualityScalar\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_uint32_t \fBuastcRDODictSize\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "float \fBuastcRDOMaxSmoothBlockErrorScale\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "float \fBuastcRDOMaxSmoothBlockStdDev\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBuastcRDODontFavorSimplerModes\fP"
|
|
.br
|
|
.ti -1c
|
|
.RI "ktx_bool_t \fBuastcRDONoMultithreading\fP"
|
|
.br
|
|
.in -1c
|
|
.SH "Detailed Description"
|
|
.PP
|
|
Structure for passing extended parameters to ktxTexture2_CompressBasisEx()\&.
|
|
|
|
If you only want default values, use ktxTexture2_CompressBasis()\&. Here, at a minimum you must initialize the structure as follows:
|
|
.PP
|
|
.nf
|
|
ktxBasisParams params = {0};
|
|
params\&.structSize = sizeof(params);
|
|
params\&.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;
|
|
|
|
.fi
|
|
.PP
|
|
|
|
.PP
|
|
\fIcompressionLevel\fP has to be explicitly set because 0 is a valid \fIcompressionLevel\fP but is not the default used by the BasisU encoder when no value is set\&. Only the other settings that are to be non-default must be non-zero\&.
|
|
.SH "Field Documentation"
|
|
.PP
|
|
.SS "ktx_uint32_t compressionLevel"
|
|
Encoding speed vs\&. quality tradeoff\&. Range is [0,6]\&. Higher values are much slower, but give slightly higher quality\&. Higher levels are intended for video\&. There is no default\&. Callers must explicitly set this value\&. Callers can use KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL as a default value\&. Currently this is 2\&.
|
|
.SS "float endpointRDOThreshold"
|
|
Set endpoint RDO quality threshold\&. The default is 1\&.25\&. Lower is higher quality but less quality per output bit (try [1\&.0,3\&.0]\&. This will override the value chosen by \fRqualityLevel\fP\&.
|
|
.SS "char inputSwizzle[4]"
|
|
A swizzle to apply before encoding\&. It must match the regular expression /^[rgba01]{4}$/\&. If both this and preSwizzle are specified ktxTexture_CompressBasisEx will raise KTX_INVALID_OPERATION\&. Usable with both ETC1S and UASTC\&.
|
|
.SS "ktx_uint32_t maxEndpoints"
|
|
Manually set the max number of color endpoint clusters\&. Range is [1,16128]\&. Default is 0, unset\&. If this is set, maxSelectors must also be set, otherwise the value will be ignored\&.
|
|
.SS "ktx_uint32_t maxSelectors"
|
|
Manually set the max number of color selector clusters\&. Range is [1,16128]\&. Default is 0, unset\&. If this is set, maxEndpoints must also be set, otherwise the value will be ignored\&.
|
|
.SS "ktx_bool_t noEndpointRDO"
|
|
Disable endpoint rate distortion optimizations\&. Slightly faster, less noisy output, but lower quality per output bit\&. Default is KTX_FALSE\&.
|
|
.SS "ktx_bool_t normalMap"
|
|
Tunes codec parameters for better quality on normal maps (no selector RDO, no endpoint RDO) and sets the texture's DFD appropriately\&. Only valid for linear textures\&.
|
|
.SS "ktx_bool_t noSelectorRDO"
|
|
Disable selector rate distortion optimizations\&. Slightly faster, less noisy output, but lower quality per output bit\&. Default is KTX_FALSE\&.
|
|
.SS "ktx_bool_t noSSE"
|
|
True to forbid use of the SSE instruction set\&. Ignored if CPU does not support SSE\&.
|
|
.SS "ktx_bool_t preSwizzle"
|
|
If the texture has \fRKTXswizzle\fP metadata, apply it before compressing\&. Swizzling, like \fRrabb\fP may yield drastically different error metrics if done after supercompression\&. Usable for both ETC1S and UASTC\&.
|
|
.SS "ktx_uint32_t qualityLevel"
|
|
Compression quality\&. Range is [1,255]\&. Lower gives better compression/lower quality/faster\&. Higher gives less compression /higher quality/slower\&. This automatically determines values for \fRmaxEndpoints\fP, \fRmaxSelectors\fP, \fRendpointRDOThreshold\fP and \fRselectorRDOThreshold\fP for the target quality level\&. Setting these parameters overrides the values determined by \fRqualityLevel\fP which defaults to 128 if neither it nor both of \fRmaxEndpoints\fP and \fRmaxSelectors\fP have been set\&.
|
|
.PP
|
|
\fBNote\fP
|
|
.RS 4
|
|
\fIBoth\fP of \fRmaxEndpoints\fP and \fRmaxSelectors\fP must be set for them to have any effect\&.
|
|
|
|
.PP
|
|
qualityLevel will only determine values for \fRendpointRDOThreshold\fP and \fRselectorRDOThreshold\fP when its value exceeds 128, otherwise their defaults will be used\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "float selectorRDOThreshold"
|
|
Set selector RDO quality threshold\&. The default is 1\&.5\&. Lower is higher quality but less quality per output bit (try [1\&.0,3\&.0])\&. This will override the value chosen by \fRqualityLevel\fP\&.
|
|
.SS "ktx_bool_t separateRGToRGB_A"
|
|
|
|
.PP
|
|
\fBDeprecated\fP
|
|
.RS 4
|
|
This was and is a no-op\&. 2-component inputs have always been automatically separated using an "rrrg" inputSwizzle\&.
|
|
.RE
|
|
.PP
|
|
\fBSee also\fP
|
|
.RS 4
|
|
\fBinputSwizzle\fP and normalMode\&.
|
|
.RE
|
|
.PP
|
|
|
|
.SS "ktx_uint32_t structSize"
|
|
Size of this struct\&. Used so library can tell which version of struct is being passed\&.
|
|
.SS "ktx_uint32_t threadCount"
|
|
Number of threads used for compression\&. Default is 1\&.
|
|
.SS "ktx_bool_t uastc"
|
|
True to use UASTC base, false to use ETC1S base\&.
|
|
.SS "ktx_pack_uastc_flags uastcFlags"
|
|
A set of \fBktx_pack_uastc_flag_bits_e\fP controlling UASTC encoding\&. The most important value is the level given in the least-significant 4 bits which selects a speed vs quality tradeoff as shown in the following table:
|
|
|
|
.PP
|
|
Level/Speed Quality KTX_PACK_UASTC_LEVEL_FASTEST 43\&.45dB KTX_PACK_UASTC_LEVEL_FASTER 46\&.49dB KTX_PACK_UASTC_LEVEL_DEFAULT 47\&.47dB KTX_PACK_UASTC_LEVEL_SLOWER 48\&.01dB KTX_PACK_UASTC_LEVEL_VERYSLOW 48\&.24dB
|
|
.SS "ktx_bool_t uastcRDO"
|
|
Enable Rate Distortion Optimization (RDO) post-processing\&.
|
|
.SS "ktx_uint32_t uastcRDODictSize"
|
|
UASTC RDO dictionary size in bytes\&. Default is 4096\&. Lower values=faster, but give less compression\&. Range is [64,65536]\&.
|
|
.SS "ktx_bool_t uastcRDODontFavorSimplerModes"
|
|
Do not favor simpler UASTC modes in RDO mode\&.
|
|
.SS "float uastcRDOMaxSmoothBlockErrorScale"
|
|
UASTC RDO max smooth block error scale\&. Range is [1,300]\&. Default is 10\&.0, 1\&.0 is disabled\&. Larger values suppress more artifacts (and allocate more bits) on smooth blocks\&.
|
|
.SS "float uastcRDOMaxSmoothBlockStdDev"
|
|
UASTC RDO max smooth block standard deviation\&. Range is [\&.01,65536\&.0]\&. Default is 18\&.0\&. Larger values expand the range of blocks considered smooth\&.
|
|
.SS "ktx_bool_t uastcRDONoMultithreading"
|
|
Disable RDO multithreading (slightly higher compression, deterministic)\&.
|
|
.SS "float uastcRDOQualityScalar"
|
|
UASTC RDO quality scalar (lambda)\&. Lower values yield higher quality/larger LZ compressed files, higher values yield lower quality/smaller LZ compressed files\&. A good range to try is [\&.2,4]\&. Full range is [\&.001,50\&.0]\&. Default is 1\&.0\&.
|
|
.SS "ktx_bool_t verbose"
|
|
If true, prints Basis Universal encoder operation details to \fRstdout\fP\&. Not recommended for GUI apps\&.
|
|
|
|
.SH "Author"
|
|
.PP
|
|
Generated automatically by Doxygen for libktx Reference from the source code\&.
|