Supercompress the images in a KTX2 file.

SYNOPSIS

ktxsc [options] [infile ...]

DESCRIPTION

ktxsc can encode and supercompress the images in Khronos texture format version 2 files (KTX2). Uncompressed files, i.e those whose vkFormat name does not end in _BLOCK can be encoded to ASTC, Basis Universal (encoded to ETC1S then supercompressed with an integrated LZ step) or UASTC and optionally supercompressed with Zstandard (zstd). Any image format, except Basis Universal, can be supercompressed with zstd. For best results with UASTC, the data should be conditioned for zstd by using the --uastc_rdo_q and, optionally, --uastc_rdo_d options.

ktxsc reads each named infile and compresses it in place. When infile is not specified, a single file will be read from stdin and the output written to stdout. When one or more files is specified each will be compressed in place.

The following options are available:

-o outfile, –output=outfile

Write the output to outfile. If outfile is 'stdout', output will be written to stdout. Parent directories will be created, if necessary. If there is more than 1 infile the command prints its usage message and exits.

-f, --force

If the destination file cannot be opened, remove it and create a new file, without prompting for confirmation regardless of its permissions.

--t2

Output a KTX version2 file. Always true.

--encode <astc | etc1s | uastc>

Compress the image data to ASTC, transcodable ETC1S / BasisLZ or high-quality transcodable UASTC format. Implies --t2. With each encoding option the following encoder specific options become valid, otherwise they are ignored.

astc:

Create a texture in high-quality ASTC format.

--astc_blk_d <XxY | XxYxZ>

Specify which block dimension to use for compressing the textures. e.g. --astc_blk_d 6x5 for 2D or --astc_blk_d 6x6x6 for 3D. 6x6 is the default for 2D.

Supported 2D block dimensions are:
4x4	8.00 bpp
5x4	6.40 bpp
5x5	5.12 bpp
6x5	4.27 bpp
6x6	3.56 bpp
8x5	3.20 bpp
8x6	2.67 bpp
10x5	2.56 bpp
10x6	2.13 bpp
8x8	2.00 bpp
10x8	1.60 bpp
10x10	1.28 bpp
12x10	1.07 bpp
12x12	0.89 bpp
Supported 3D block dimensions are:
3x3x3	4.74 bpp
4x3x3	3.56 bpp
4x4x3	2.67 bpp
4x4x4	2.00 bpp
5x4x4	1.60 bpp
5x5x4	1.28 bpp
5x5x5	1.02 bpp
6x5x5	0.85 bpp
6x6x5	0.71 bpp
6x6x6	0.59 bpp

--astc_mode <ldr | hdr>

Specify which encoding mode to use. LDR is the default unless the input image is 16-bit in which case the default is HDR.

--astc_quality <level>

The quality level configures the quality-performance tradeoff for the compressor; more complete searches of the search space improve image quality at the expense of compression time. Default is 'medium'. The quality level can be set between fastest (0) and exhaustive (100) via the following fixed quality presets:

Level	Quality
fastest	(equivalent to quality = 0)
fast	(equivalent to quality = 10)
medium	(equivalent to quality = 60)
thorough	(equivalent to quality = 98)
exhaustive	(equivalent to quality = 100)

--astc_perceptual

The codec should optimize for perceptual error, instead of direct RMS error. This aims to improve perceived image quality, but typically lowers the measured PSNR score. Perceptual methods are currently only available for normal maps and RGB color data.

etc1s:

Supercompress the image data with ETC1S / BasisLZ. RED images will become RGB with RED in each component. RG images will have R in the RGB part and G in the alpha part of the compressed texture. When set, the following BasisLZ-related options become valid, otherwise they are ignored.

--no_multithreading

Disable multithreading. Deprecated. For backward compatibility. Use --threads 1 instead.

--clevel <level>

ETC1S / BasisLZ compression level, an encoding speed vs. quality tradeoff. Range is [0,5], default is 1. Higher values are slower but give higher quality.

--qlevel <level>

ETC1S / BasisLZ quality level. Range is [1,255]. Lower gives better compression/lower quality/faster. Higher gives less compression/higher quality/slower. --qlevel automatically determines values for --max_endpoints, --max-selectors, --endpoint_rdo_threshold and --selector_rdo_threshold for the target quality level. Setting these options overrides the values determined by -qlevel which defaults to 128 if neither it nor both of --max_endpoints and --max_selectors have been set.

Note that both of --max_endpoints and --max_selectors must be set for them to have any effect. If all three options are set, a warning will be issued that --qlevel will be ignored.

Note also that --qlevel will only determine values for --endpoint_rdo_threshold and --selector_rdo_threshold when its value exceeds 128, otherwise their defaults will be used.

--max_endpoints <arg>

Manually set the maximum number of color endpoint clusters. Range is [1,16128]. Default is 0, unset.

--endpoint_rdo_threshold <arg>

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 --qlevel.

--max_selectors <arg>

Manually set the maximum number of color selector clusters from [1,16128]. Default is 0, unset.

--selector_rdo_threshold <arg>

Set selector 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 --qlevel.

--no_endpoint_rdo

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

--no_selector_rdo

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

uastc:

Create a texture in high-quality transcodable UASTC format.

--uastc_quality <level>

This optional parameter selects a speed vs quality tradeoff as shown in the following table:

Level	Speed	Quality
0	Fastest	43.45dB
1	Faster	46.49dB
2	Default	47.47dB
3	Slower	48.01dB
4	Very slow	48.24dB

You are strongly encouraged to also specify --zcmp to losslessly compress the UASTC data. This and any LZ-style compression can be made more effective by conditioning the UASTC texture data using the Rate Distortion Optimization (RDO) post-process stage. When uastc encoding is set the following options become available for controlling RDO:

--uastc_rdo_l [<lambda>]

Enable UASTC RDO post-processing and optionally set UASTC RDO quality scalar (lambda) to 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 [.25,10]. For normal maps a good range is [.25,.75]. The full range is [.001,10.0]. Default is 1.0.

Note that previous versions used the --uastc_rdo_q option which was removed because the RDO algorithm changed.

--uastc_rdo_d <dictsize>

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

--uastc_rdo_b <scale>

Set UASTC RDO max smooth block error scale. Range is [1.0,300.0]. Default is 10.0, 1.0 is disabled. Larger values suppress more artifacts (and allocate more bits) on smooth blocks.

--uastc_rdo_s <deviation>

Set 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.

--uastc_rdo_f

Do not favor simpler UASTC modes in RDO mode.

--uastc_rdo_m

Disable RDO multithreading (slightly higher compression, deterministic).

--input_swizzle <swizzle>

Swizzle the input components according to swizzle which is an alhpanumeric sequence matching the regular expression ^[rgba01]{4}$.

--normal_mode

Only valid for linear textures with two or more components. If the input texture has three or four linear components it is assumed to be a three component linear normal map storing unit length normals as (R=X, G=Y, B=Z). A fourth component will be ignored. The map will be converted to a two component X+Y normal map stored as (RGB=X, A=Y) prior to encoding. If unsure that your normals are unit length, use --normalize. If the input has 2 linear components it is assumed to be an X+Y map of unit normals.

The Z component can be recovered programmatically in shader code by using the equations:

    nml.xy = texture(...).ga;              // Load in [0,1]
    nml.xy = nml.xy * 2.0 - 1.0;           // Unpack to [-1,1]
    nml.z = sqrt(1 - dot(nml.xy, nml.xy)); // Compute Z
               

For ASTC encoding, '--encode astc', encoder parameters are tuned for better quality on normal maps. For ETC1S encoding, '--encode etc1s', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality.

In toktx you can prevent conversion of the normal map to two components by specifying '--input_swizzle rgb1'.

--normalize

Normalize input normals to have a unit length. Only valid for linear textures with 2 or more components. For 2-component inputs 2D unit normals are calculated. Do not use these 2D unit normals to generate X+Y normals for –normal_mode. For 4-component inputs a 3D unit normal is calculated. 1.0 is used for the value of the 4th component.

--no_sse

Forbid use of the SSE instruction set. Ignored if CPU does not support SSE. Only the Basis Universal compressor uses SSE.

--bcmp

Deprecated. Use '--encode etc1s' instead.

--uastc [<level>]

Deprecated. Use '--encode uastc' instead.

--zcmp [<compressionLevel>]

Supercompress the data with Zstandard. Implies --t2. Can be used with data in any format except ETC1S / BasisLZ. Most effective with RDO-conditioned UASTC or uncompressed formats. The optional compressionLevel range is 1 - 22 and the default is 3. Lower values=faster but give less compression. Values above 20 should be used with caution as they require more memory.

--threads <count>

Explicitly set the number of threads to use during compression. By default, ETC1S / BasisLZ and ASTC compression will use the number of threads reported by thread::hardware_concurrency or 1 if value returned is 0.

--verbose

Print encoder/compressor activity status to stdout. Currently only the astc, etc1s and uastc encoders emit status.

-h, --help

Print this usage message and exit.

-v, --version

Print the version number of this program and exit.

In case of ambiguity, such as when the last option is one with an optional parameter, separate options from file names with " -- ".Any specified ASTC, ETC1S / BasisLZ, UASTC and supercompression options are recorded in the metadata item KTXwriterScParams in the output file.

EXIT STATUS

ktxsc exits 0 on success, 1 on command line errors and 2 on functional errors.

HISTORY

Version 4.0

• Initial version.

AUTHOR

Mark Callow, Edgewise Consulting www.edgewise-consulting.com