ktxsc(1)

🌸 NAME 🌸

ktxsc — supercompress the images in a KTX2 file. This is ktxsc(1) from the KTX Tools Reference, and bestie, it’s lowkey iconic.

✨ SYNOPSIS ✨

ktxsc [options] [infile ...]

💖 DESCRIPTION 💖

okay so ktxsc can encode and supercompress the images in Khronos texture format version 2 files (KTX2). Uncompressed files — like, the ones 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:

4x48.00 bpp5x46.40 bpp5x55.12 bpp6x54.27 bpp6x63.56 bpp8x53.20 bpp8x62.67 bpp10x52.56 bpp10x62.13 bpp8x82.00 bpp10x81.60 bpp10x101.28 bpp12x101.07 bpp12x120.89 bpp

Supported 3D block dimensions are:

3x3x34.74 bpp4x3x33.56 bpp4x4x32.67 bpp4x4x42.00 bpp5x4x41.60 bpp5x5x41.28 bpp5x5x51.02 bpp6x5x50.85 bpp6x6x50.71 bpp6x6x60.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:
  • 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:
  • 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 — (no description given in this part of the page.)
• the activity-status one — prints encoder/compressor activity status to stdout. Right now only the astc, etc1s and uastc encoders actually emit status, so don't be shook if the others stay silent 💀
• -h, --help — prints this usage message and dips. that's it, that's the whole vibe 🫶
• -v, --version — prints the version number of this program and exits. short, sweet, iconic ✨

🚨 okay bestie, important little trap here: in case of ambiguity — like when the last option is one that takes an optional parameter — you separate the options from the file names with " -- ". do not skip this, it's giving "my file got eaten by the parser" energy 😭

---

🌸 also, lowkey a fun fact: any ASTC, ETC1S / BasisLZ, UASTC and supercompression options you specify get recorded in the metadata item KTXwriterScParams inside the output file. so the file literally remembers what you did to it. no cap, receipts kept 👑

💅 EXIT STATUS 💅

ktxsc exits 0 on success, 1 on command line errors and 2 on functional errors. three numbers, three moods — memorize them, bestie 🎀

🌈 HISTORY 🌈

Version 4.0

• Initial version. everybody starts somewhere, and she started here ⭐

🎀 AUTHOR 🎀

Mark Callow, github.com/MarkCallow — absolute legend, go say hi 🫶

---

and that's the whole page, bestie!! you ate this 💅 this lil doc came from version 0.0.0 and is dated Tue Jan 1 1980 00:00:00, served fresh as ktxsc(1). go compress something gorgeous 🦋✨