ktxBasisParams Struct Reference

Structure for passing extended parameters to ktxTexture2_CompressBasisEx(). More...

#include <ktx.h>

Data Fields
ktx_uint32_t	structSize
ktx_bool_t	uastc
ktx_bool_t	verbose
ktx_bool_t	noSSE
ktx_uint32_t	threadCount
ktx_uint32_t	compressionLevel
ktx_uint32_t	qualityLevel
ktx_uint32_t	maxEndpoints
float	endpointRDOThreshold
ktx_uint32_t	maxSelectors
float	selectorRDOThreshold
char	inputSwizzle [4]
ktx_bool_t	normalMap
ktx_bool_t	separateRGToRGB_A
ktx_bool_t	preSwizzle
ktx_bool_t	noEndpointRDO
ktx_bool_t	noSelectorRDO
ktx_pack_uastc_flags	uastcFlags
ktx_bool_t	uastcRDO
float	uastcRDOQualityScalar
ktx_uint32_t	uastcRDODictSize
float	uastcRDOMaxSmoothBlockErrorScale
float	uastcRDOMaxSmoothBlockStdDev
ktx_bool_t	uastcRDODontFavorSimplerModes
ktx_bool_t	uastcRDONoMultithreading

Detailed Description

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:

ktxBasisParams params = {0};
params.structSize = sizeof(params);
params.compressionLevel = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;

compressionLevel has to be explicitly set because 0 is a valid compressionLevel 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.

Field Documentation

compressionLevel

ktx_uint32_t ktxBasisParams::compressionLevel

Encoding speed vs. quality tradeoff. Range is [0,5]. Higher values are slower, but give higher quality. 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.

endpointRDOThreshold

float ktxBasisParams::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 qualityLevel.

inputSwizzle

char ktxBasisParams::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.

maxEndpoints

ktx_uint32_t ktxBasisParams::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.

maxSelectors

ktx_uint32_t ktxBasisParams::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.

noEndpointRDO

ktx_bool_t ktxBasisParams::noEndpointRDO

Disable endpoint rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is KTX_FALSE.

normalMap

ktx_bool_t ktxBasisParams::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.

noSelectorRDO

ktx_bool_t ktxBasisParams::noSelectorRDO

Disable selector rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is KTX_FALSE.

noSSE

ktx_bool_t ktxBasisParams::noSSE

True to forbid use of the SSE instruction set. Ignored if CPU does not support SSE.

preSwizzle

ktx_bool_t ktxBasisParams::preSwizzle

If the texture has KTXswizzle metadata, apply it before compressing. Swizzling, like rabb may yield drastically different error metrics if done after supercompression.

qualityLevel

ktx_uint32_t ktxBasisParams::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 maxEndpoints, maxSelectors, endpointRDOThreshold and selectorRDOThreshold for the target quality level. Setting these parameters overrides the values determined by qualityLevel which defaults to 128 if neither it nor both of maxEndpoints and maxSelectors have been set.

Note

Both of maxEndpoints and maxSelectors must be set for them to have any effect.

qualityLevel will only determine values for endpointRDOThreshold and selectorRDOThreshold when its value exceeds 128, otherwise their defaults will be used.

selectorRDOThreshold

float ktxBasisParams::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 qualityLevel.

separateRGToRGB_A

ktx_bool_t ktxBasisParams::separateRGToRGB_A

Deprecated:

. This was and is a no-op. 2-component inputs have always been automatically separated using an "rrrg" inputSwizzle.

See also

inputSwizzle and normalMode.

structSize

ktx_uint32_t ktxBasisParams::structSize

Size of this struct. Used so library can tell which version of struct is being passed.

threadCount

ktx_uint32_t ktxBasisParams::threadCount

Number of threads used for compression. Default is 1.

uastc

ktx_bool_t ktxBasisParams::uastc

True to use UASTC base, false to use ETC1S base.

uastcFlags

ktx_pack_uastc_flags ktxBasisParams::uastcFlags

A set of ktx_pack_uastc_flag_bits_e 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:

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

uastcRDO

ktx_bool_t ktxBasisParams::uastcRDO

Enable Rate Distortion Optimization (RDO) post-processing.

uastcRDODictSize

ktx_uint32_t ktxBasisParams::uastcRDODictSize

UASTC RDO dictionary size in bytes. Default is 4096. Lower values=faster, but give less compression. Range is [64,65536].

uastcRDODontFavorSimplerModes

ktx_bool_t ktxBasisParams::uastcRDODontFavorSimplerModes

Do not favor simpler UASTC modes in RDO mode.

uastcRDOMaxSmoothBlockErrorScale

float ktxBasisParams::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.

uastcRDOMaxSmoothBlockStdDev

float ktxBasisParams::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.

uastcRDONoMultithreading

ktx_bool_t ktxBasisParams::uastcRDONoMultithreading

Disable RDO multithreading (slightly higher compression, deterministic).

uastcRDOQualityScalar

float ktxBasisParams::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.

verbose

ktx_bool_t ktxBasisParams::verbose

If true, prints Basis Universal encoder operation details to stdout. Not recommended for GUI apps.