279 lines
12 KiB
Groff
279 lines
12 KiB
Groff
.TH "ktxsc" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
|
.ad l
|
|
.nh
|
|
.SH NAME
|
|
ktxsc \- Supercompress the images in a KTX2 file\&.
|
|
.SH "SYNOPSIS"
|
|
.PP
|
|
ktxsc [options] [\fIinfile\fP \&.\&.\&.]
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fBktxsc\fP 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 \fR_BLOCK\fP 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 \fI--uastc_rdo_q\fP and, optionally, \fI--uastc_rdo_d\fP options\&.
|
|
|
|
.PP
|
|
\fBktxsc\fP reads each named \fIinfile\fP and compresses it in place\&. When \fIinfile\fP is not specified, a single file will be read from \fIstdin\fP and the output written to \fIstdout\fP\&. When one or more files is specified each will be compressed in place\&.
|
|
|
|
.PP
|
|
The following options are available:
|
|
|
|
.PP
|
|
.IP "\fB-o outfile, --output=outfile
|
|
.IP "" 1c
|
|
Write the output to \fIoutfile\fP\&. If \fIoutfile\fP is 'stdout', output will be written to stdout\&. Parent directories will be created, if necessary\&. If there is more than 1 \fIinfile\fP the command prints its usage message and exits\&.
|
|
|
|
.PP
|
|
.IP "\fB-f, --force
|
|
.IP "" 1c
|
|
If the destination file cannot be opened, remove it and create a new file, without prompting for confirmation regardless of its permissions\&.
|
|
|
|
.PP
|
|
.IP "\fB--t2
|
|
.IP "" 1c
|
|
Output a KTX version2 file\&. Always true\&.
|
|
|
|
.PP
|
|
|
|
.PP
|
|
.IP "\fB--encode <astc | etc1s | uastc>
|
|
.IP "" 1c
|
|
Compress the image data to ASTC, transcodable ETC1S / BasisLZ or high-quality transcodable UASTC format\&. Implies \fB--t2\fP\&. With each encoding option the following encoder specific options become valid, otherwise they are ignored\&.
|
|
|
|
.PP
|
|
.IP "\fBastc:
|
|
.IP "" 1c
|
|
Create a texture in high-quality ASTC format\&.
|
|
|
|
.PP
|
|
.IP "\fB--astc_blk_d <XxY | XxYxZ>
|
|
.IP "" 1c
|
|
Specify which block dimension to use for compressing the textures\&. e\&.g\&. \fB--astc_blk_d\fP 6x5 for 2D or \fB--astc_blk_d\fP 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 bppSupported 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
|
|
|
|
.PP
|
|
.IP "\fB--astc_mode <ldr | hdr>
|
|
.IP "" 1c
|
|
Specify which encoding mode to use\&. LDR is the default unless the input image is 16-bit in which case the default is HDR\&.
|
|
|
|
.PP
|
|
.IP "\fB--astc_quality <level>
|
|
.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
|
|
.IP "\fBetc1s:
|
|
.IP "" 1c
|
|
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\&.
|
|
|
|
.PP
|
|
.IP "\fB--no_multithreading
|
|
.IP "" 1c
|
|
Disable multithreading\&. Deprecated\&. For backward compatibility\&. Use \fB--threads\fP 1 instead\&.
|
|
|
|
.PP
|
|
.IP "\fB--clevel <level>
|
|
.IP "" 1c
|
|
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\&.
|
|
|
|
.PP
|
|
.IP "\fB--qlevel <level>
|
|
.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 both of \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 <arg>
|
|
.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 <arg>
|
|
.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 <arg>
|
|
.IP "" 1c
|
|
Manually set the maximum number of color selector clusters from [1,16128]\&. Default is 0, unset\&.
|
|
|
|
.PP
|
|
.IP "\fB--selector_rdo_threshold <arg>
|
|
.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
|
|
.IP "\fBuastc:
|
|
.IP "" 1c
|
|
Create a texture in high-quality transcodable UASTC format\&.
|
|
|
|
.PP
|
|
.IP "\fB--uastc_quality <level>
|
|
.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--zcmp\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_l [<lambda>]
|
|
.IP "" 1c
|
|
Enable UASTC RDO post-processing and optionally 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 <dictsize>
|
|
.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 <scale>
|
|
.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 <deviation>
|
|
.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
|
|
.IP "\fB--input_swizzle <swizzle>
|
|
.IP "" 1c
|
|
Swizzle the input components according to \fIswizzle\fP which is an alhpanumeric sequence matching the regular expression \fR^\fP[rgba01]{4}$\&.
|
|
|
|
.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 ASTC encoding, '\fB--encode\fP astc', encoder parameters are tuned for better quality on normal maps\&. For ETC1S encoding, \fB'--encode\fP etc1s', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality\&.
|
|
|
|
.PP
|
|
In \fItoktx\fP you can prevent conversion of the normal map to two components by specifying '\fB--input_swizzle\fP rgb1'\&.
|
|
|
|
.PP
|
|
.IP "\fB--normalize
|
|
.IP "" 1c
|
|
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\&.
|
|
|
|
.PP
|
|
.IP "\fB--no_sse
|
|
.IP "" 1c
|
|
Forbid use of the SSE instruction set\&. Ignored if CPU does not support SSE\&. Only the Basis Universal compressor uses SSE\&.
|
|
|
|
.PP
|
|
.IP "\fB--bcmp
|
|
.IP "" 1c
|
|
Deprecated\&. Use '\fB--encode\fP etc1s' instead\&.
|
|
|
|
.PP
|
|
.IP "\fB--uastc [<level>]
|
|
.IP "" 1c
|
|
Deprecated\&. Use '\fB--encode\fP uastc' instead\&.
|
|
|
|
.PP
|
|
.IP "\fB--zcmp [<compressionLevel>]
|
|
.IP "" 1c
|
|
Supercompress the data with Zstandard\&. Implies \fB--t2\fP\&. 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\&.
|
|
|
|
.PP
|
|
.IP "\fB--threads <count>
|
|
.IP "" 1c
|
|
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\&.
|
|
|
|
.PP
|
|
.IP "\fB--verbose
|
|
.IP "" 1c
|
|
Print encoder/compressor activity status to stdout\&. Currently only the astc, etc1s and uastc encoders emit status\&.
|
|
|
|
.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
|
|
|
|
.PP
|
|
.PP
|
|
.nf
|
|
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 @c KTXwriterScParams in the output file\&.
|
|
.fi
|
|
.PP
|
|
|
|
.SH "EXIT STATUS"
|
|
.PP
|
|
\fBktxsc\fP exits 0 on success, 1 on command line errors and 2 on functional errors\&.
|
|
.SH "HISTORY"
|
|
.PP
|
|
\fBVersion 4\&.0\fP
|
|
.RS 4
|
|
|
|
.IP "\(bu" 2
|
|
Initial version\&.
|
|
.PP
|
|
.RE
|
|
.PP
|
|
.SH "AUTHOR"
|
|
.PP
|
|
Mark Callow, github\&.com/MarkCallow
|