Encode a KTX2 file.

SYNOPSIS

ktx encode [option...] input-file output-file

DESCRIPTION

ktx encode can encode the KTX file specified as the input-file argument to a universal format or one of the ASTC formats, optionally supercompress the result, and save it as the output-file. If the input-file is '-' the file will be read from the stdin. If the output-path is '-' the output file will be written to the stdout.

For universal and ASTC LDR formats, the input file must be R8, R8G8, R8G8B8 or R8G8B8A8 (or their sRGB variants).

If the input file is invalid the first encountered validation error is displayed to the stderr and the command exits with the relevant non-zero status code.

OPTIONS

General Options

The following options are available:

--codec basis-lz | uastc

Target codec followed by the codec specific options. With each choice the specific and common encoder options listed below become valid, otherwise they are ignored. Case-insensitive.

basis-lz:: Supercompress the image data with transcodable ETC1S / BasisLZ. RED images will become RGB with RED in each component (RRR). RG images will have R in the RGB part and G in the alpha part of the compressed texture (RRRG). When set, the basis-lz options become valid.
uastc:: Create a texture in high-quality transcodable UASTC format. When set the uastc options become valid.

--format

KTX format enum that specifies the target ASTC format. Non-ASTC formats are invalid. When specified the ASTC-specific and common encoder options listed below become valid, otherwise they are ignored.

--zstd <level>: Supercompress the data with Zstandard. Cannot be used with ETC1S / BasisLZ format. Level range is [1,22]. Lower levels give faster but worse compression. Values above 20 should be used with caution as they require more memory.
--zlib <level>: Supercompress the data with ZLIB. Cannot be used with ETC1S / BasisLZ format. Level range is [1,9]. Lower levels give faster but worse compression.

-h, --help: Print this usage message and exit.
-v, --version: Print the version number of this program and exit.

Specific and Common Encoding Options

The following specific and common encoder options are available. Specific options become valid only if their encoder has been selected. Common encoder options become valid when an encoder they apply to has been selected. Otherwise they are ignored.

ASTC:

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

basis-lz:

--clevel <level>

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

--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 --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:

--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 --zstd 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

Enable UASTC RDO post-processing.

--uastc-rdo-l <lambda>

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

common:

--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 ETC1S / BasisLZ encoding, '--encode basis-lz', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality.

--threads <count>

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

--no-sse

Forbid use of the SSE instruction set. Ignored if CPU does not support SSE. SSE can only be disabled for the basis-lz and uastc encoders. Ignored for other encoders..

--compare-ssim: Calculate encoding structural similarity index measure (SSIM) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding.
--compare-psnr: Calculate encoding peak signal-to-noise ratio (PSNR) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding.

EXIT STATUS

0 - Success
1 - Command line error
2 - IO failure
3 - Invalid input file
4 - Runtime or library error
5 - Not supported state or operation
6 - Requested feature is not yet implemented

HISTORY

Version 4.0

Initial version.

Version 4.4

Reorganize encoding options.

AUTHOR

Mátyás Császár [Vader], RasterGrid www.rastergrid.com
Daniel Rákos, RasterGrid www.rastergrid.com