 |
KTX Tools Reference 4.3.2
Libraries and tools to create and read KTX image texture files.
|
|
KTX Tools Reference 4.3.2
Libraries and tools to create and read KTX image texture files.
|
Encode a KTX2 file.
ktx encode [option...] input-file output-file
ktx encode can encode the KTX file specified as the input-file argument, 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. The input file must be R8, RG8, RGB8 or RGBA8 (or their sRGB variant). 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.
The following options are available:
Target codec followed by the codec specific options. With each encoding option the following encoder specific options become valid, otherwise they are ignored. Case-insensitive.
Supercompress the image data with 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 following BasisLZ-related options become valid, otherwise they are ignored.
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.
Create a texture in high-quality transcodable UASTC format.
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:
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.
Common options.
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.
1.9.6