ktx_encode(1)

🌸 NAME 🌸

This is ktx_encode(1) — the manual page for ktx encode, and it is literally here to encode a KTX2 file. Bestie, this is your go-to for turning a KTX file into a universal format or one of the ASTC formats, optionally supercompressing it, and saving the result. 💖

🦋 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. slay ✨

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

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. vibe check failed, bestie 😭

✨ 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. highkey watch that memory, bestie 🫶
• --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. iykyk 💅

⭐ 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:
  • 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 0 — Fastest — 43.45dB
  • Level 1 — Faster — 46.49dB
  • Level 2 — Default — 47.47dB
  • Level 3 — Slower — 48.01dB
  • Level 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. iconic behavior, honestly 🎀

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

🫶 That’s the whole manual, bestie. This page is ktx_encode(1) from KTX Tools Reference, version 0.0.0, dated Tue Jan 1 1980 00:00:00. Slay. 💖