.TH "ktx_encode" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*- .ad l .nh .SH NAME ktx_encode \- ktx encode .PP Encode a KTX2 file\&. .SH "SYNOPSIS" .PP ktx encode [option\&.\&.\&.] \fIinput-file\fP \fIoutput-file\fP .SH "DESCRIPTION" .PP \fBktx\fP \fBencode\fP can encode the KTX file specified as the \fIinput-file\fP argument to a universal format or one of the ASTC formats, optionally supercompress the result, and save it as the \fIoutput-file\fP\&. If the \fIinput-file\fP is '-' the file will be read from the stdin\&. If the \fIoutput-path\fP is '-' the output file will be written to the stdout\&. .PP For universal and ASTC LDR formats, the input file must be R8, R8G8, R8G8B8 or R8G8B8A8 (or their sRGB variants)\&. .PP 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\&. .SH "OPTIONS" .PP .SS "General Options" The following options are available: .PP .IP "\fB--codec basis-lz | uastc .IP "" 1c Target codec followed by the codec specific options\&. With each choice the specific and common encoder options listed \fBbelow\fP become valid, otherwise they are ignored\&. Case-insensitive\&. .PP .PP .IP "\fBbasis-lz: .IP "" 1c 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 \fIbasis-lz\fP options become valid\&. .PP .IP "\fBuastc: .IP "" 1c Create a texture in high-quality transcodable UASTC format\&. When set the \fIuastc\fP options become valid\&. .PP .PP .PP .IP "\fB--format .IP "" 1c KTX format enum that specifies the target ASTC format\&. Non-ASTC formats are invalid\&. When specified the ASTC-specific and common encoder options listed \fBbelow\fP become valid, otherwise they are ignored\&. .PP .PP .IP "\fB--zstd .IP "" 1c 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\&. .PP .IP "\fB--zlib .IP "" 1c Supercompress the data with ZLIB\&. Cannot be used with ETC1S / BasisLZ format\&. Level range is [1,9]\&. Lower levels give faster but worse compression\&. .PP .PP .PP .IP "\fB-h, --help .IP "" 1c Print this usage message and exit\&. .PP .IP "\fB-v, --version .IP "" 1c Print the version number of this program and exit\&. .PP .SS "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\&. .PP .IP "\fBASTC: .IP "" 1c .PP .PP .IP "\fB--astc-quality .IP "" 1c 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) .PP .IP "\fB--astc-perceptual .IP "" 1c 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\&. .PP .PP .PP .PP .IP "\fBbasis-lz: .IP "" 1c .PP .IP "\fB--clevel .IP "" 1c 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 \fB--qlevel\fP first\&. .PP .IP "\fB--qlevel .IP "" 1c ETC1S / BasisLZ quality level\&. Range is [1,255]\&. Lower gives better compression/lower quality/faster\&. Higher gives less compression/higher quality/slower\&. \fB--qlevel\fP automatically determines values for \fB--max-endpoints\fP, \fB--max-selectors\fP, \fB--endpoint-rdo-threshold\fP and \fB--selector-rdo-threshold\fP for the target quality level\&. Setting these options overrides the values determined by -qlevel which defaults to 128 if neither it nor \fB--max-endpoints\fP and \fB--max-selectors\fP have been set\&. .PP Note that both of \fB--max-endpoints\fP and \fB--max-selectors\fP must be set for them to have any effect\&. If all three options are set, a warning will be issued that \fB--qlevel\fP will be ignored\&. .PP Note also that \fB--qlevel\fP will only determine values for \fB--endpoint-rdo-threshold\fP and \fB--selector-rdo-threshold\fP when its value exceeds 128, otherwise their defaults will be used\&. .PP .IP "\fB--max-endpoints .IP "" 1c Manually set the maximum number of color endpoint clusters\&. Range is [1,16128]\&. Default is 0, unset\&. .PP .IP "\fB--endpoint-rdo-threshold .IP "" 1c 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 \fB--qlevel\fP\&. .PP .IP "\fB--max-selectors .IP "" 1c Manually set the maximum number of color selector clusters from [1,16128]\&. Default is 0, unset\&. .PP .IP "\fB--selector-rdo-threshold .IP "" 1c 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 \fB--qlevel\fP\&. .PP .IP "\fB--no-endpoint-rdo .IP "" 1c Disable endpoint rate distortion optimizations\&. Slightly faster, less noisy output, but lower quality per output bit\&. Default is to do endpoint RDO\&. .PP .IP "\fB--no-selector-rdo .IP "" 1c Disable selector rate distortion optimizations\&. Slightly faster, less noisy output, but lower quality per output bit\&. Default is to do selector RDO\&. .PP .PP .PP .IP "\fBuastc: .IP "" 1c .PP .PP .IP "\fB--uastc-quality .IP "" 1c This optional parameter selects a speed vs quality tradeoff as shown in the following table: .PP LevelSpeedQuality0 Fastest 43\&.45dB1 Faster 46\&.49dB2 Default 47\&.47dB3 Slower 48\&.01dB4 Very slow 48\&.24dB .PP You are strongly encouraged to also specify \fB--zstd\fP 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: .PP .IP "\fB--uastc-rdo .IP "" 1c Enable UASTC RDO post-processing\&. .PP .IP "\fB--uastc-rdo-l .IP "" 1c Set UASTC RDO quality scalar (lambda) to \fIlambda\fP\&. 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\&. .PP Note that previous versions used the \fB--uastc-rdo-q\fP option which was removed because the RDO algorithm changed\&. .PP .IP "\fB--uastc-rdo-d .IP "" 1c Set UASTC RDO dictionary size in bytes\&. Default is 4096\&. Lower values=faster, but give less compression\&. Range is [64,65536]\&. .PP .IP "\fB--uastc-rdo-b .IP "" 1c 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\&. .PP .IP "\fB--uastc-rdo-s .IP "" 1c 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\&. .PP .IP "\fB--uastc-rdo-f .IP "" 1c Do not favor simpler UASTC modes in RDO mode\&. .PP .IP "\fB--uastc-rdo-m .IP "" 1c Disable RDO multithreading (slightly higher compression, deterministic)\&. .PP .PP .PP .PP .IP "\fBcommon: .IP "" 1c .PP .IP "\fB--normal-mode .IP "" 1c 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 \fB--normalize\fP\&. If the input has 2 linear components it is assumed to be an X+Y map of unit normals\&. .PP The Z component can be recovered programmatically in shader code by using the equations: .PP .nf 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 .fi .PP For ETC1S / BasisLZ encoding, \fB'--encode\fP basis-lz', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality\&. .PP .IP "\fB--threads .IP "" 1c Explicitly set the number of threads to use during compression\&. By default, ETC1S / BasisLZ will use the number of threads reported by \fRthread::hardware_concurrency\fP or 1 if value returned is 0\&. .PP .IP "\fB--no-sse .IP "" 1c 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\&.\&. .PP .PP .PP .PP .IP "\fB .IP "" 1c .PP .IP "\fB--compare-ssim .IP "" 1c Calculate encoding structural similarity index measure (SSIM) and print it to stdout\&. Requires Basis-LZ, UASTC or ASTC encoding\&. .PP .IP "\fB--compare-psnr .IP "" 1c Calculate encoding peak signal-to-noise ratio (PSNR) and print it to stdout\&. Requires Basis-LZ, UASTC or ASTC encoding\&. .PP .PP .SH "EXIT STATUS" .PP .IP "\(bu" 2 0 - Success .IP "\(bu" 2 1 - Command line error .IP "\(bu" 2 2 - IO failure .IP "\(bu" 2 3 - Invalid input file .IP "\(bu" 2 4 - Runtime or library error .IP "\(bu" 2 5 - Not supported state or operation .IP "\(bu" 2 6 - Requested feature is not yet implemented .PP .SH "HISTORY" .PP \fBVersion 4\&.0\fP .RS 4 .IP "\(bu" 2 Initial version\&. .PP .RE .PP \fBVersion 4\&.4\fP .RS 4 .IP "\(bu" 2 Reorganize encoding options\&. .PP .RE .PP .SH "AUTHOR" .PP .IP "\(bu" 2 Mátyás Császár [Vader], RasterGrid www\&.rastergrid\&.com .IP "\(bu" 2 Daniel Rákos, RasterGrid www\&.rastergrid\&.com .PP