Add ktx
This commit is contained in:
@@ -0,0 +1,113 @@
|
||||
.TH "ktx" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx \- Unified CLI frontend for the KTX-Software library\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx <command> [command-option\&.\&.\&.]
|
||||
.br
|
||||
ktx [option\&.\&.\&.]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
Unified CLI frontend for the KTX-Software library with sub-commands for specific operations for the KTX File Format Specification https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html\&.
|
||||
|
||||
.PP
|
||||
The following commands are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBcreate\fP
|
||||
.IP "" 1c
|
||||
Create a KTX2 file from various input files\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBdeflate\fP
|
||||
.IP "" 1c
|
||||
Deflate (supercompress) a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBextract\fP
|
||||
.IP "" 1c
|
||||
Extract selected images from a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBencode\fP
|
||||
.IP "" 1c
|
||||
Encode a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBtranscode\fP
|
||||
.IP "" 1c
|
||||
Transcode a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBinfo\fP
|
||||
.IP "" 1c
|
||||
Print information about a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBvalidate\fP
|
||||
.IP "" 1c
|
||||
Validate a KTX2 file\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBcompare\fP
|
||||
.IP "" 1c
|
||||
Compare two KTX2 files\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB\fBhelp\fP
|
||||
.IP "" 1c
|
||||
Display help information about the ktx tool\&.
|
||||
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are also available without a command:
|
||||
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
.TH "ktx2check" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx2check \- Check the validity of a KTX 2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx2check [options] [\fIinfile\fP \&.\&.\&.]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx2check\fP validates Khronos texture format version 2 files (KTX2)\&. It reads each named \fIinfile\fP and validates it writing to stdout messages about any issues found\&. When \fBinfile\fP is not specified, it validates a single file from stdin\&.
|
||||
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB-q, --quiet
|
||||
.IP "" 1c
|
||||
Validate silently\&. Indicate valid or invalid via exit code\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-m <num>, --max-issues <num>
|
||||
.IP "" 1c
|
||||
Set the maximum number of issues to be reported per file provided -q is not set\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-w, --warn-as-error
|
||||
.IP "" 1c
|
||||
Treat warnings as errors\&. Changes exit code from success to error\&.
|
||||
|
||||
.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
|
||||
.SH "EXIT STATUS"
|
||||
.PP
|
||||
\fBktx2check\fP exits 0 on success, 1 on command line errors and 2 on validation 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
|
||||
@@ -0,0 +1,62 @@
|
||||
.TH "ktx2ktx2" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx2ktx2 \- Create a KTX 2 file from a KTX file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx2ktx2 [options] [\fIinfile\fP \&.\&.\&.]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx2ktx2\fP creates Khronos texture format version 2 files (KTX2) from Khronos texture format version 1 files\&. \fBktx2ktx2\fP reads each named \fIinfile\fP\&. Output files have the same name as the input but with the extension changed to \fR\fP\&.ktx2\&. When \fBinfile\fP is not specified, a single file will be read from stdin and the output written to standard out\&.
|
||||
|
||||
.PP
|
||||
If unrecognized metadata with keys beginning "KTX" or "ktx" is found in the input file, it is dropped and a warning is written to standard error\&.
|
||||
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB-b, --rewritebado
|
||||
.IP "" 1c
|
||||
Rewrite bad orientation metadata\&. Some in-the-wild KTX files have orientation metadata with the key "KTXOrientation" instead of KTXorientaion\&. This option will rewrite such bad metadata instead of dropping it\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-o outfile, --output=outfile
|
||||
.IP "" 1c
|
||||
Name the output file \fIoutfile\fP\&. If \fIoutfile\fP is 'stdout', output will be written to stdout\&. If there is more than 1 input file, the command prints its usage message and exits\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-f, --force
|
||||
.IP "" 1c
|
||||
If the destination file already exists, remove it and create a new file, without prompting for confirmation regardless of its permissions\&.
|
||||
|
||||
.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
|
||||
.SH "EXIT STATUS"
|
||||
.PP
|
||||
\fBktx2ktx2\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
|
||||
@@ -0,0 +1,249 @@
|
||||
.TH "ktx_compare" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_compare \- ktx compare
|
||||
.PP
|
||||
Compare two KTX2 files\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx compare [option\&.\&.\&.] \fIinput-file1\fP \fIinput-file2\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBcompare\fP compares the two KTX2 files specified as the \fIinput-file1\fP and \fIinput-file2\fP arguments and outputs any mismatch in texture information and/or image data\&. The command implicitly calls \fBvalidate\fP and prints any found errors and warnings to stdout\&. If any of the specified input files are invalid then comparison is done based on best effort and may be incomplete\&.
|
||||
|
||||
.PP
|
||||
The JSON output formats conform to the https://schema.khronos.org/ktx/compare_v0.json schema even if the input file is invalid and certain information cannot be parsed or displayed\&. Additionally, for JSON outputs the KTX file identifier is printed using "\\u001A" instead of "\\x1A" as an unescaped "\\x1A" sequence inside a JSON string breaks nearly every JSON tool\&. Note that this does not change the value of the string only its representation\&.
|
||||
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fBktx\fP \fBcompare\fP prints using UTF-8 encoding\&. If your console is not set for UTF-8 you will see incorrect characters in output of the file identifier on each side of the "KTX nn"\&.
|
||||
.RE
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--format text | json | mini-json
|
||||
.IP "" 1c
|
||||
Specifies the report output format\&. Possible options are:
|
||||
.br
|
||||
\fBtext\fP - Human readable text based format\&.
|
||||
.br
|
||||
\fBjson\fP - Formatted JSON\&.
|
||||
.br
|
||||
\fBmini-json\fP - Minified JSON\&.
|
||||
.br
|
||||
The default format is \fBtext\fP\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--content raw | image | ignore
|
||||
.IP "" 1c
|
||||
Controls how image content is compared\&. Possible options are:
|
||||
.br
|
||||
\fBraw\fP - Encoded image data is compared verbatim, as it appears in the file\&.
|
||||
.br
|
||||
\fBimage\fP - Effective image data is compared per texel block\&.
|
||||
.br
|
||||
\fBignore\fP - Ignore image contents\&.
|
||||
.br
|
||||
The default mode is \fBraw\fP, meaning that the encoded image data must match exactly\&. Note: When the mode is set to \fBimage\fP, the effective image data of individual mip levels, layers, and faces is compared texel block by texel block after applying one or more of the following transformations, if needed:
|
||||
.br
|
||||
- If the texture is supercompressed (e\&.g\&. using Zstandard or ZLIB), the images are deflated before comparison\&.
|
||||
.br
|
||||
- If the texture is encoded using BasisLZ, the images are transcoded to R8G8B8A_UNORM before comparison\&.
|
||||
.br
|
||||
For block compressed textures and textures encoded using UASTC the texel blocks are the individual compressed blocks, while for other formats the texel blocks are the individual pixels of the image\&.
|
||||
.br
|
||||
When comparing files that use different supercompression schemes, or otherwise different encoding, additional options may need to be used to avoid unexpected differences to be reported related to the meta information of the files\&. For example:
|
||||
.br
|
||||
- The supercompression scheme can be ignored with --ignore-supercomp\&.
|
||||
.br
|
||||
- Compressed byte length and other index section differences can be ignored with --ignore-index all or --ignore-index level\&.
|
||||
.br
|
||||
- DFD section differences can be ignored with --ignore-dfd all or --ignore-dfd all-except-color-space\&.
|
||||
.br
|
||||
- BDFD bytesPlane value differences can be ignored with --ignore-bdfd-bytesplane\&.
|
||||
.br
|
||||
- SGD section differences can be ignored with --ignore-sgd all or --ignore-sgd payload\&.
|
||||
.br
|
||||
|
||||
|
||||
.PP
|
||||
.IP "\fB--per-pixel-output all | <number> | none
|
||||
.IP "" 1c
|
||||
Controls whether per pixel / texel block difference output is generated when --content is set to \fBimage:\fP
|
||||
.br
|
||||
\fBall\fP - Every single difference is output (may result in a very large output)\&.
|
||||
.br
|
||||
\fB<number>\fP - At most the specified number of differences are output\&.
|
||||
.br
|
||||
\fBnone\fP - No per pixel / texel block differences are output\&.
|
||||
.br
|
||||
The default mode is \fBnone\fP to limit the verbosity of the output\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--allow-invalid-input
|
||||
.IP "" 1c
|
||||
Perform best effort comparison even if any of the input files are invalid\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-format-header
|
||||
.IP "" 1c
|
||||
|
||||
.PP
|
||||
.IP "\fB
|
||||
.IP "" 1c
|
||||
Ignore the vkFormat and typeSize fields in the file header\&.
|
||||
.br
|
||||
Note: useful when comparing textures with and without BasisLZ encoding, respectively\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-supercomp
|
||||
.IP "" 1c
|
||||
Ignore supercompression scheme in the file header\&.
|
||||
.br
|
||||
Note: use the --ignore-sgd option to also ignore the SGD section, if needed\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-index all | level | none
|
||||
.IP "" 1c
|
||||
Controls the comparison of index entries in the file headers\&. Possible options are:
|
||||
.br
|
||||
\fBall\fP - Ignore all index entries\&.
|
||||
.br
|
||||
\fBlevel\fP - Ignore level index entries only\&.
|
||||
.br
|
||||
\fBnone\fP - Do not ignore any index entries\&.
|
||||
.br
|
||||
The default mode is \fBnone\fP, meaning that all index entries will be compared\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-dfd all | all-except-color-space | unknown | extended | none
|
||||
.IP "" 1c
|
||||
Controls the comparison of DFD blocks\&. Possible options are:
|
||||
.br
|
||||
\fBall\fP - Ignore all DFD blocks\&.
|
||||
.br
|
||||
\fBall-except-color-space\fP: Ignore all DFD blocks except the color space information in the basic DFD block\&.
|
||||
.br
|
||||
\fBunknown\fP - Ignore any unrecognized DFD blocks\&.
|
||||
.br
|
||||
\fBextended\fP - Ignore all DFD blocks except the basic DFD block\&.
|
||||
.br
|
||||
\fBnone\fP - Do not ignore any DFD blocks\&.
|
||||
.br
|
||||
The default mode is \fBnone\fP, meaning that all DFD entries will be compared\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-bdfd-bytesplane
|
||||
.IP "" 1c
|
||||
Ignore BDFD bytesPlane values\&. Useful when comparing pre-spec-2\&.0\&.4 supercompressed files with 2\&.0\&.4+ supercompressed or non-supercompressed ones, as bytesPlane is set to zero in older supercompressed files\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-metadata all | <key>[,\&.\&.\&.] | none
|
||||
.IP "" 1c
|
||||
Controls the comparison of metadata (KVD) entries\&. Possible options are:
|
||||
.br
|
||||
\fBall\fP - Ignore all metadata entries\&.
|
||||
.br
|
||||
\fB<key>\fP[,\&.\&.\&.] - Ignore the specified comma separated list of metadata keys\&.
|
||||
.br
|
||||
\fBnone\fP - Do not ignore any metadata entries\&.
|
||||
.br
|
||||
The default mode is \fBnone\fP, meaning that all metadata entries will be compared\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--ignore-sgd all | unknown | payload | none
|
||||
.IP "" 1c
|
||||
Controls the comparison of the SGD section\&. Possible options are:
|
||||
.br
|
||||
\fBall\fP - Ignore the SGD section\&.
|
||||
.br
|
||||
\fBunknown\fP - Ignore any unrecognized SGD section\&.
|
||||
.br
|
||||
\fBpayload\fP - Ignore any unrecognized SGD section and the payload of any known SGD section\&.
|
||||
.br
|
||||
\fBnone\fP - Do not ignore the SGD section\&.
|
||||
.br
|
||||
The default mode is \fBnone\fP, meaning that SGD sections will be always compared\&. Note: --ignore-sgd payload can be used to compare BasisLZ SGD headers without expecting an exact match for the individual SGD payload sections\&.
|
||||
|
||||
.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
|
||||
@note Reports about image content mismatches when --content is set to @b raw or @b image
|
||||
include the following information: <br />
|
||||
- The level, layer, and face index of the image where the difference was found\&.
|
||||
|
||||
@note Reports about individual texel block differences when --content is set to @b image
|
||||
include the following additional information: <br />
|
||||
- The texel coordinates within the image where the difference was found\&. These
|
||||
coordinates are the raw coordinates of the image and are not affected by metadata
|
||||
such as @b KTXorientation\&.
|
||||
- The packed elements of the texel block output as an array of hexadecimal values\&.
|
||||
Each packed element has a byte size equal to the @b typeSize value of the image\&.
|
||||
- The channel values of the texel block output as an array of integer (for integer
|
||||
and normalized formats) or floating point (for floating point formats) values\&.
|
||||
In case of floating point formats @b NaN, @b +inf, and @b -inf are used to indicate
|
||||
values that are not a number or represent infinities, respectively\&.
|
||||
The output order of the channels always follow the order they appear in the BDFD\&.
|
||||
.fi
|
||||
.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
|
||||
|
||||
.PP
|
||||
.IP "\(bu" 2
|
||||
7 - Input files are different
|
||||
.PP
|
||||
.SH "HISTORY"
|
||||
.PP
|
||||
\fBVersion 4\&.0\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Initial version
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
.SH "AUTHOR"
|
||||
.PP
|
||||
.IP "\(bu" 2
|
||||
Daniel Rákos, RasterGrid www\&.rastergrid\&.com
|
||||
.PP
|
||||
|
||||
@@ -0,0 +1,614 @@
|
||||
.TH "ktx_create" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_create \- ktx create
|
||||
.PP
|
||||
Create a KTX2 file from various input files\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx create [option\&.\&.\&.] \fIinput-file\fP\&.\&.\&. \fIoutput-file\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBcreate\fP can create, encode and supercompress a KTX2 file from the input images specified as the \fIinput-file\fP\&.\&.\&. arguments and save it as the \fIoutput-file\fP\&. The last positional argument is treated 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
|
||||
Each \fIinput-file\fP must be a valid EXR (\&.exr), PNG (\&.png) or Raw (\&.raw) file\&. PNG files with luminance (L) or luminance + alpha (LA) data will be converted to RGB as LLL and RGBA as LLLA before processing further\&. The input file formats must be compatible with the requested KTX format enum and must have at least the same level of precision and number of channels\&. Any unused channel will be discarded silently\&.
|
||||
|
||||
.PP
|
||||
The number of input-files specified must match the expected number of input images based on the used options\&.
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
.SS "General Options"
|
||||
The following are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--format <enum>
|
||||
.IP "" 1c
|
||||
KTX format enum that specifies the data format for the images in the created texture\&. The enum names match the VkFormat names without the VK_FORMAT_ prefix\&. The VK_FORMAT_ prefix is ignored if present\&. Case insensitive\&. Required\&.
|
||||
.br
|
||||
|
||||
.br
|
||||
If the format is an ASTC format a texture object with the target format \fRR8G8B8_{SRGB\fP,UNORM} or \fRR8G8B8A8_{SRGB\fP,UNORM} is created then encoded to the specified ASTC format\&. The latter format is chosen if alpha is present in the input\&. \fRSRGB\fP or \fRUNORM\fP is chosen depending on the specified ASTC format\&. The ASTC-specific and common encoder options listed \fBbelow\fP become valid, otherwise they are ignored\&. This matches the functionality of the \fBktx encode\fP command when an ASTC format is specified\&.
|
||||
.br
|
||||
|
||||
.br
|
||||
When used with \fB--encode\fP it specifies the target format before the encoding step\&. In this case it must be one of:
|
||||
.PD 0
|
||||
.IP " \(bu" 6
|
||||
R8_UNORM
|
||||
.IP " \(bu" 6
|
||||
R8_SRGB
|
||||
.IP " \(bu" 6
|
||||
R8G8_UNORM
|
||||
.IP " \(bu" 6
|
||||
R8G8_SRGB
|
||||
.IP " \(bu" 6
|
||||
R8G8B8_UNORM
|
||||
.IP " \(bu" 6
|
||||
R8G8B8_SRGB
|
||||
.IP " \(bu" 6
|
||||
R8G8B8A8_UNORM
|
||||
.IP " \(bu" 6
|
||||
R8G8B8A8_SRGB
|
||||
.PP
|
||||
The format will be used to verify and load all input files into a texture before performing any specified encoding\&.
|
||||
.br
|
||||
|
||||
|
||||
.PP
|
||||
.IP "\fB--encode basis-lz | uastc
|
||||
.IP "" 1c
|
||||
Encode the texture with the specified codec before saving it\&. This option matches the functionality of the \fBktx encode\fP command\&. 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--1d
|
||||
.IP "" 1c
|
||||
Create a 1D texture\&. If not set the texture will be a 2D or 3D texture\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--cubemap
|
||||
.IP "" 1c
|
||||
Create a cubemap texture\&. If not set the texture will be a 2D or 3D texture\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--raw
|
||||
.IP "" 1c
|
||||
Create from raw image data\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--width
|
||||
.IP "" 1c
|
||||
Base level width in pixels\&. Required with \fB--raw\fP\&. For non-raw, if not set, the image width is used otherwise the image is resampled to this width and any provided mip levels are resampled proportionately\&. For non-raw it enables use of the 'Generate Mipmap' options listed under \fB--generate-mipmap\fP to tune the resampler\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--height
|
||||
.IP "" 1c
|
||||
Base level height in pixels\&. Required with \fB--raw\fP\&. For non-raw, if not set, the image height is used otherwise the image is resampled to this height and any provided mip levels are resampled proportionately\&. For non-raw it enables use of the 'Generate Mipmap' options listed under \fB--generate-mipmap\fP to tune the resampler\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--depth
|
||||
.IP "" 1c
|
||||
Base level depth in pixels\&. If set the texture will be a 3D texture\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--layers
|
||||
.IP "" 1c
|
||||
Number of layers\&. If set the texture will be an array texture\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--levels
|
||||
.IP "" 1c
|
||||
Number of mip levels\&. This is the number of level images to include in the texture being created\&. If \fB--generate-mipmap\fP is specified this number of level images will be generated otherwise this number of input images must be provided\&. Generates an error if the value is greater than the maximum possible for the specified dimensions of the texture or, for non-raw, the dimensions of the base level image as possibly modified by \fB--scale\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--runtime-mipmap
|
||||
.IP "" 1c
|
||||
Runtime mipmap generation mode\&. Sets up the texture to request the mipmaps to be generated by the client application at runtime\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--generate-mipmap
|
||||
.IP "" 1c
|
||||
Causes mipmaps to be generated during texture creation\&. If \fB--levels\fP is not specified the maximum possible mip level will be generated\&. This option is mutually exclusive with --runtime-mipmap and cannot be used with SINT, UINT or 3D textures or \fB--raw\fP\&. When set it enables the use of the following 'Generate Mipmap' options\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--mipmap-filter <filter>
|
||||
.IP "" 1c
|
||||
Specifies the filter to use when generating the mipmaps\&. Case insensitive\&. Ignored unless \fB--generate-mipmap\fP, \fB--scale\fP, \fB--width\fP or \fB--height\fP are specified for non-raw input\&.
|
||||
.br
|
||||
Possible options are: box | tent | bell | b-spline | mitchell | blackman | lanczos3 | lanczos4 | lanczos6 | lanczos12 | kaiser | gaussian | catmullrom | quadratic_interp | quadratic_approx | quadratic_mix\&. Defaults to lanczos4\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--mipmap-filter-scale <float>
|
||||
.IP "" 1c
|
||||
The filter scale to use\&. Defaults to 1\&.0\&. Ignored unless \fB--generate-mipmap\fP, \fB--scale\fP, \fB--width\fP or \fB--height\fP are specified for non-raw input\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--mipmap-wrap <mode>
|
||||
.IP "" 1c
|
||||
Specify how to sample pixels near the image boundaries\&. Case insensitive\&. Ignored unless \fB--generate-mipmap\fP, \fB--scale\fP, \fB--width\fP or \fB--height\fP are specified for non-raw input\&.
|
||||
.br
|
||||
Possible options are: wrap | reflect | clamp\&. Defaults to clamp\&.
|
||||
|
||||
.PP
|
||||
Avoid mipmap generation if the Output TF (see \fBTRANSFER FUNCTION HANDLING\fP below) is non-linear and is not sRGB\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--scale
|
||||
.IP "" 1c
|
||||
Scale images as they are loaded\&. Cannot be used with --raw\&. It enables use of the 'Generate Mipmap' options listed under --generate-mipmap to tune the resampler\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--normalize
|
||||
.IP "" 1c
|
||||
Normalize input normals to have a unit length\&. Only valid for linear normal 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 with \fB--normal-mode\fP\&. For 4-component inputs a 3D unit normal is calculated\&. 1\&.0 is used for the value of the 4th component\&. Cannot be used with \fB--raw\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--swizzle [rgba01]{4}
|
||||
.IP "" 1c
|
||||
KTX swizzle metadata\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--input-swizzle [rgba01]{4}
|
||||
.IP "" 1c
|
||||
Pre-swizzle input channels\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign-tf <transfer function>
|
||||
.IP "" 1c
|
||||
Force the created texture to have the specified transfer function, ignoring the transfer function of the input file(s)\&. Possible options match the khr_df_transfer_e enumerators without the KHR_DF_TRANSFER_ prefix\&. The KHR_DF_TRANSFER_ prefix is ignored if present\&. Case nsensitive\&. The options are: linear | srgb | srgb_eotf | scrgb | scrgb_eotf | itu | itu_oetf | bt601 | bt601_oetf | bt709 | bt709_oetf | bt2020 | bt2020_oetf | smpte170m | smpte170m_oetf | smpte170m_eotf | ntsc | ntsc_eotf | slog | slog_oetf | slog2 | slog2_oetf | bt1886 | bt1886_eotf | hlg_oetf | hlg_eotf | pq_oetf | pg_eotf | dcip3 | dcip3_eotf | pal_oetf | pal625_eotf | st240 | st240_oetf | st240_eotf | acescc | acescc_oetf | acescct | acescct_oetf | abobergb | adobergb_eotf See \fBTRANSFER FUNCTION HANDLING\fP below for important information\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign-oetf <transfer function>
|
||||
.IP "" 1c
|
||||
Deprecated and will be removed\&. Use \fB--assign-tf\fP instead\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign-primaries <primaries>
|
||||
.IP "" 1c
|
||||
Force the created texture to have the specified color primaries, ignoring the color primaries of the input file(s)\&. Possible options match the khr_df_primaries_e enumerators without the KHR_DF_PRIMARIES_ prefix\&. The KHR_DF_PRIMARIES_ prefix is ignored if present\&. Case insensitive\&. The options are: none | bt709 | srgb | bt601_ebu | bt601_smpte | bt2020 | ciexyz | aces | acescc | ntsc1953 | pal525 | displayp3 | adobergb\&.
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fRbt601-ebu\fP and \fRbt601-smpte\fP, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign-texcoord-origin <corner>
|
||||
.IP "" 1c
|
||||
Force the created texture to indicate that the texture coordinate origin s=0, t=0 is at the specified \fIcorner\fP of the logical image\&. Case insensitive\&. Possible options are top-left | bottom-left\&. -front | -back can be appended and one of these is required when \fB--depth\fP is specified\&. Must be top-left if \fB--cubemap\fP is specified\&. Absent \fB—convert-texcoord-origin\fP, the effect of this option is to cause \fIKTXorientation\fP metadata indicating the specified origin to be written to the output file\&. Example values are "rd" (top-left) and "ru" (bottom-left) or, when \fB--depth\fP is specified, "rdi" (top-left-front) and "rui" (bottom-left-front)\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert-tf <transfer function>
|
||||
.IP "" 1c
|
||||
Convert the input image(s) to the specified transfer function, if different from the transfer function of the input file(s)\&. If both this and \fB--assign-tf\fP are specified, conversion will be performed from the assigned transfer function to the transfer function specified by this option, if different\&. Cannot be used with \fB--raw\fP\&. Case insensitive\&. The options are: linear | srgb\&. The following srgb aliases are also supported: srgb_eotf | scrgb | scrgb_eotf\&. See \fBTRANSFER FUNCTION HANDLING\fP below for more information\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert-oetf <transfer function>
|
||||
.IP "" 1c
|
||||
Deprecated and will be removed\&. Use \fB--convert-tf\fP instead\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert-primaries <primaries>
|
||||
.IP "" 1c
|
||||
Convert the input image(s) to the specified color primaries, if different from the color primaries of the input file(s) or the one specified by \fB--assign-primaries\fP\&. If both this and \fB--assign-primaries\fP are specified, conversion will be performed from the assigned primaries to the primaries specified by this option, if different\&. This option is not allowed to be specified when \fB--assign-primaries\fP is set to 'none'\&. Cannot be used with \fB--raw\fP\&. Possible options match the khr_df_primaries_e enumerators without the KHR_DF_PRIMARIES_ prefix\&. The KHR_DF_PRIMARIES_ prefix is ignored if present\&. Case insensitive\&. The options are: bt709 | srgb | bt601_ebu | bt601_smpte | bt2020 | ciexyz | aces | acescc | ntsc1953 | pal525 | displayp3 | adobergb
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fRbt601-ebu\fP and \fRbt601-smpte\fP, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert-texcoord-origin <corner>
|
||||
.IP "" 1c
|
||||
Convert the input image(s) so the texture coordinate origin s=0, t=0, is at the specified \fIcorner\fP of the logical image\&. If both this and \fB--assign-texcoord-origin\fP are specified, conversion will be performed from the assigned origin to the origin specified by this option, if different\&. The default for images in KTX files is top-left which corresponds to the origin in most image file formats\&. Cannot be used with \fB--raw\fP\&. Case insensitive\&. Possible options are: top-left | bottom-left\&. -front | -back can be appended and one of these is required when \fB--depth\fP is specified\&. Must be top-left if \fB--cubemap\fP is specified\&.
|
||||
.br
|
||||
|
||||
.br
|
||||
Input images whose origin does not match \fIcorner\fP will be flipped vertically\&. \fIKTXorientation\fP metadata indicating the the specified origin is written to the output file\&. Example values are "rd" (top-left) and "ru" (bottom-left) or, when \fB--depth\fP is specified, "rdi" (top-left-front) and "rui" (bottom-left-back)\&. Generates an error if the input image origin is unknown as is the case with raw image data\&. Use \fB--assign-texcoord-origin\fP to specify the orientation\&.
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
ktx create cannot rotate or flip incoming images, except for a y-flip, so use an an image processing tool to reorient images whose first data stream pixel is not at the logical top-left or bottom-left of the image before using as input here\&. Such images may be indicated by Exif-style orientation metadata in the file\&.
|
||||
.RE
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--fail-on-color-conversions
|
||||
.IP "" 1c
|
||||
Generates an error if any input images would need to be color converted\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--warn-on-color-conversions
|
||||
.IP "" 1c
|
||||
Generates a warning if any input images are color converted\&. Adds warnings for explicitly requested and visually lossless implicit conversions to that generated for visually lossy conversions\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--no-warn-on-color-conversions
|
||||
.IP "" 1c
|
||||
Disable all warnings about color conversions including that for visually lossy conversions\&. Overrides \fB--warn-on-color-conversions\fP should both be specified\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--fail-on-origin-changes
|
||||
.IP "" 1c
|
||||
Generates an error if any of the input images would need to have their origin changed\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--warn-on-origin-changes
|
||||
.IP "" 1c
|
||||
Generates a warning if any of the input images have their origin changed\&.\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--zstd <level>
|
||||
.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 <level>
|
||||
.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 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 <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
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fBbasis-lz:
|
||||
.IP "" 1c
|
||||
|
||||
.PP
|
||||
.IP "\fB--clevel <level>
|
||||
.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 <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 \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
|
||||
|
||||
.PP
|
||||
.IP "\fBuastc:
|
||||
.IP "" 1c
|
||||
|
||||
.PP
|
||||
|
||||
.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--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 <lambda>
|
||||
.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 <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
|
||||
|
||||
.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 <count>
|
||||
.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 "TRANSFER FUNCTION HANDLING"
|
||||
.PP
|
||||
The diagram below shows all assignments and conversions that can take place\&.
|
||||
|
||||
.PP
|
||||
.PP
|
||||
.nf
|
||||
┌──────────┐ ┌─────────┐
|
||||
│ ├──────────────────1─────────────────►│ │
|
||||
│ │ ┌───────────┐ │ │
|
||||
│ Input │ │ │ │ │
|
||||
│ Transfer │ │ --assign- ├──────────2──────────►│Output │
|
||||
│ function │ │ tf │ ┌────────────┐ │Transfer │
|
||||
│ from │ │ ├─3─►│ │ │Function │
|
||||
│ file │ │ │ │ --convert- │ │ │
|
||||
│ metadata │ └───────────┘ │ tf ├3,4►│ │
|
||||
│ │ │ │ │ │
|
||||
│ ├────────4─────────►│ │ │ │
|
||||
└──────────┘ └────────────┘ └─────────┘
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.SS "Processing Paths"
|
||||
|
||||
.PP
|
||||
.PD 0
|
||||
.IP "1." 4
|
||||
Pass through\&. No options specified\&.
|
||||
.IP "2." 4
|
||||
\fB--assign-tf\fP specified\&.
|
||||
.IP "3." 4
|
||||
\fB--assign-tf\fP and \fB--convert-tf\fP specified\&.
|
||||
.IP "4." 4
|
||||
\fB--convert-tf\fP specified\&.
|
||||
.PP
|
||||
.SS "Details"
|
||||
Transfer function handling proceeds as follows:
|
||||
.PD 0
|
||||
.IP "\(bu" 2
|
||||
If \fB--format\fP specifies one of the \fR*_SRGB{\fP,_*} formats and Output Transfer Function is not sRGB (a\&.k\&.a scRGB) an error is generated\&.
|
||||
.IP "\(bu" 2
|
||||
If \fB--format\fP does not specify one of the \fR*_SRGB{\fP,_*} formats, an sRGB variant exists and Output Transfer Function is sRGB (a\&.k\&.a scRGB), an error is generated\&.
|
||||
.IP "\(bu" 2
|
||||
Otherwise, the transfer function of the output KTX file is set to Output Transfer Function\&.
|
||||
.IP "\(bu" 2
|
||||
If neither \fB--assign-tf\fP nor \fB--convert-tf\fP is specified:
|
||||
.PD 0
|
||||
.IP " \(bu" 4
|
||||
If the Input Transfer Function is not sRGB (a\&.k\&.a scRGB) for \fR*_SRGB{\fP,_*} formats an implicit conversion to sRGB is done, equivalent to \fB--convert-tf\fP srgb\&.
|
||||
.IP " \(bu" 4
|
||||
If the Input Transfer Function is not linear for formats that are not one of the \fR*_SRGB{\fP,_*} formats, an implicit conversion to linear is done equivalent to \fB--convert-tf\fP linear\&.
|
||||
.PP
|
||||
|
||||
.IP "\(bu" 2
|
||||
Supported inputs for implicit or explicit conversion are linear, sRGB, ITU (a\&.k\&.a BT601, BT\&.709, BT\&.2020 and SMPTE170M) and PQ EOTF\&. An error is generated if an unsupported conversion is required\&.
|
||||
.IP "\(bu" 2
|
||||
Supported outputs for implicit or explicit conversion are linear and sRGB, An error is generated if an unsupported conversion is required\&.
|
||||
.IP "\(bu" 2
|
||||
Output Transfer Function for a format that is not one of the \fR*_SRGB{\fP,_*} formats can be set to a non-linear transfer function via \fB--assign-tf\fP\&.
|
||||
.IP "\(bu" 2
|
||||
A warning is generated if a visually lossy color-conversion is performed\&. sRGB to linear is considered visually lossy because there is a high chance it will introduce artifacts visible to the human eye such as banding\&. The warning can be suppressed with \fB--no-warn-on-color-conversions\fP\&. A warning or an error on any color conversion can be requested with \fB--warn-on-color-conversions\fP or \fB--fail-on-color-conversions\fP \&.
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
When \fB--format\fP does not specify one of the \fI\fISRGB{,\fP\fP} formats and Output Transfer Function is not linear:
|
||||
.PD 0
|
||||
.IP "\(bu" 1
|
||||
the KTX file may be much less portable due to limited hardware support of such inputs\&.
|
||||
.IP "\(bu" 1
|
||||
avoid using \fB--generate-mipmap\fP as the filters can only decode sRGB\&.
|
||||
.IP "\(bu" 1
|
||||
avoid encoding to ASTC, BasisLz/ETC1S or UASTC\&. The encoders' quality metrics are designed for linear and sRGB\&.
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
.SS "Changes since last Release"
|
||||
.PD 0
|
||||
.IP "1." 4
|
||||
\fB--assign-oetf\fP and \fB--convert-oetf\fP are deprecated and will be removed\&. Use \fB--assign-tf\fP and \fB--convert-tf\fP instead\&.
|
||||
.IP "2." 4
|
||||
The parameter value for \fB--assign-tf\fP can now be any of the transfer functions known to the Khronos Data Format Specification\&.
|
||||
.IP "3." 4
|
||||
A warning is now generated if a visually lossy color conversion will be performed\&. The warning can be suppressed with \fB--no-warn-on-color-conversions\fP\&.
|
||||
.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\&.3\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Initial version
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
\fBVersion 4\&.4\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Reorganize encoding options\&.
|
||||
.IP "\(bu" 2
|
||||
Improve explanation of use of \fB--format\fP with \fB--encode\fP\&.
|
||||
.IP "\(bu" 2
|
||||
Improve explanation of ASTC encoding\&.
|
||||
.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
|
||||
.IP "\(bu" 2
|
||||
Mark Callow
|
||||
.PP
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
.TH "ktx_deflate" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_deflate \- ktx deflate
|
||||
.PP
|
||||
Deflate (supercompress) a KTX2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx deflate [option\&.\&.\&.] \fIinput-file\fP \fIoutput-file\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBdeflate\fP deflates (supercompresses) the KTX file specified as the \fIinput-file\fP and saves 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\&. If the input file is already supercompressed it will be inflated then supercompressed again using the options specified here and a warning will be issued\&. 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\&.
|
||||
|
||||
.PP
|
||||
\fBktx\fP \fBdeflate\fP cannot be applied to KTX files that have been supercompressed with BasisLZ\&.
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--zstd <level>
|
||||
.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 <level>
|
||||
.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-q, --quiet
|
||||
.IP "" 1c
|
||||
Silence warning about already supercompressed input fiile\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-e, --warnings-as-errors
|
||||
.IP "" 1c
|
||||
Treat warnings as errors\&.
|
||||
|
||||
.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
|
||||
.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
|
||||
.SH "AUTHOR"
|
||||
.PP
|
||||
.IP "\(bu" 2
|
||||
Mark Callow [@MarkCallow]
|
||||
.PP
|
||||
|
||||
@@ -0,0 +1,315 @@
|
||||
.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 <level>
|
||||
.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 <level>
|
||||
.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 <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
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fBbasis-lz:
|
||||
.IP "" 1c
|
||||
|
||||
.PP
|
||||
.IP "\fB--clevel <level>
|
||||
.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 <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 \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
|
||||
|
||||
.PP
|
||||
.IP "\fBuastc:
|
||||
.IP "" 1c
|
||||
|
||||
.PP
|
||||
|
||||
.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--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 <lambda>
|
||||
.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 <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
|
||||
|
||||
.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 <count>
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,144 @@
|
||||
.TH "ktx_extract" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_extract \- ktx extract
|
||||
.PP
|
||||
Extract selected images from a KTX2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx extract [option\&.\&.\&.] \fIinput-file\fP \fIoutput-path\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBextract\fP can extract one or multiple images from the KTX2 file specified as the \fIinput-file\fP argument and, based on the format, save them as Raw, EXR or PNG image files to the \fIoutput-path\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\&. 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\&.
|
||||
|
||||
.PP
|
||||
The \fIoutput-path\fP is interpreted as output filepath for single and output directory for multi-image extracts\&. When extracting multiple images with either '--all' or any of the 'all' args the following naming is used for each output file:
|
||||
.PP
|
||||
.nf
|
||||
output-path/output_level{}_face{}_layer{}_depth{}\&.extension
|
||||
.fi
|
||||
.PP
|
||||
.IP "\(bu" 2
|
||||
Where the \fI_level{}\fP part is only present if the source texture has more than 1 level
|
||||
.IP "\(bu" 2
|
||||
Where the \fI_face{}\fP part is only present if the source texture is cubemap or cubemap array (Cubemap)
|
||||
.IP "\(bu" 2
|
||||
Where the \fI_layer{}\fP part is only present if the source texture is an array texture (Array)
|
||||
.IP "\(bu" 2
|
||||
Where the \fI_depth{}\fP part is only present if the source texture baseDepth is more than 1 (3D)
|
||||
.IP "\(bu" 2
|
||||
Where the \fI{}\fP is replaced with the numeric index of the given component starting from 0
|
||||
.IP "\(bu" 2
|
||||
Where the \fIextension\fP part is "raw", "png" or "exr" based on the export format
|
||||
.br
|
||||
Note: The inclusion of the optional parts are determined by the source texture regardless of which images are requested\&.
|
||||
.PP
|
||||
|
||||
.PP
|
||||
For non-raw exports the output image format is chosen to be the smallest related lossless format:
|
||||
.IP "\(bu" 2
|
||||
_UNORM formats exported as PNG with RGB/RGBA 8/16 bit
|
||||
.IP "\(bu" 2
|
||||
_SINT/_UINT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
|
||||
.IP "\(bu" 2
|
||||
_SFLOAT/_UFLOAT formats exported as EXR with R/RG/RGB/RGBA Half/Float/UInt
|
||||
.IP "\(bu" 2
|
||||
D16_UNORM exported as PNG with luminance (Gray) 16 bit
|
||||
.IP "\(bu" 2
|
||||
Other Depth/Stencil formats exported as EXR with D/S/DS Half/Float
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--transcode <target>
|
||||
.IP "" 1c
|
||||
Transcode the texture to the target format before executing the extract\&. Requires the input file to be transcodable (it must be either BasisLZ supercompressed or has UASTC color model in the DFD)\&. This option matches the functionality of the \fBktx transcode\fP command\&. If the target option is not set the r8, rg8, rgb8 or rgba8 target will be selected based on the number of channels in the input texture\&. Block compressed transcode targets can only be saved in raw format\&. Case-insensitive\&. Possible options are: etc-rgb | etc-rgba | eac-r11 | eac-rg11 | bc1 | bc3 | bc4 | bc5 | bc7 | astc | r8 | rg8 | rgb8 | rgba8\&. etc-rgb is ETC1; etc-rgba, eac-r11 and eac-rg11 are ETC2\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--uri <uri>
|
||||
.IP "" 1c
|
||||
KTX Fragment URI\&. https://registry.khronos.org/KTX/specs/2.0/ktx-frag.html
|
||||
|
||||
.PP
|
||||
.IP "\fB--level [0-9]+ | all
|
||||
.IP "" 1c
|
||||
Level to extract\&. When 'all' is used every level is exported\&. Defaults to 0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--layer [0-9]+ | all
|
||||
.IP "" 1c
|
||||
Layer to extract\&. When 'all' is used every layer is exported\&. Defaults to 0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--face [0-9]+ | all
|
||||
.IP "" 1c
|
||||
Face to extract\&. When 'all' is used every face is exported\&. Defaults to 0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--depth [0-9]+ | all
|
||||
.IP "" 1c
|
||||
Depth slice to extract\&. When 'all' is used every depth is exported\&. Defaults to 0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--all
|
||||
.IP "" 1c
|
||||
Extract every image slice from the texture\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--raw
|
||||
.IP "" 1c
|
||||
Extract the raw image data without any conversion\&.
|
||||
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
.TH "ktx_help" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_help \- ktx help
|
||||
.PP
|
||||
Display help information about the ktx tool\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx help [option\&.\&.\&.] [\fIcommand\fP]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBhelp\fP displays the man page of a specific ktx command specified as the \fIcommand\fP argument\&. On windows systems the man pages are opened with the system default browser in html format\&. On systems derived from Unix the man pages are opened with the man command\&.
|
||||
|
||||
.PP
|
||||
To support custom install locations the tool first tries to use the man files relative to the executable and falls back to the system man pages\&.
|
||||
|
||||
.PP
|
||||
\fIcommand\fP specifies which command's man page will be displayed\&. If \fIcommand\fP is s missing the main ktx tool man page will be displayed\&. Possible choices are:
|
||||
.br
|
||||
.IP "\(bu" 2
|
||||
\fBcompare\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBcreate\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBdeflate\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBencode\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBextract\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBinfo\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBtranscode\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBvalidate\fP
|
||||
.br
|
||||
|
||||
.IP "\(bu" 2
|
||||
\fBhelp\fP
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
.TH "ktx_info" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_info \- ktx info
|
||||
.PP
|
||||
Print information about a KTX2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx info [option\&.\&.\&.] \fIinput-file\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBinfo\fP prints information about the KTX v1 or v2 file specified as the \fIinput-file\fP argument\&. If the \fIinput-file\fP is '-' the file will be read from the stdin\&. The command implicitly calls \fBvalidate\fP for KTX v2 files and prints any found errors and warnings to stdout\&. If the specified input file is invalid the information is displayed based on best effort and may be incomplete\&.
|
||||
|
||||
.PP
|
||||
The JSON output formats conform to the https://schema.khronos.org/ktx/info_v0.json schema even if the input file is invalid and certain information cannot be parsed or displayed\&. Additionally, for JSON outputs the KTX file identifier is printed using "\\u001A" instead of "\\x1A" as an unescaped "\\x1A" sequence inside a JSON string breaks nearly every JSON tool\&. Note that this does not change the value of the string only its representation\&. JSON output is only supported for KTX v2 files\&. If requested for a KTX v1 file, an error is generated\&.
|
||||
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fBktx\fP \fBinfo\fP prints using UTF-8 encoding\&. If your console is not set for UTF-8 you will see incorrect characters in output of the file identifier on each side of the "KTX nn"\&.
|
||||
.RE
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--format text | json | mini-json
|
||||
.IP "" 1c
|
||||
Specifies the report output format\&. Possible options are:
|
||||
.br
|
||||
\fBtext\fP - Human readable text based format\&.
|
||||
.br
|
||||
\fBjson\fP - Formatted JSON\&.
|
||||
.br
|
||||
\fBmini-json\fP - Minified JSON\&.
|
||||
.br
|
||||
The default format is \fBtext\fP\&.
|
||||
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
.TH "ktx_transcode" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_transcode \- ktx transcode
|
||||
.PP
|
||||
Transcode a KTX2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx transcode [option\&.\&.\&.] \fIinput-file\fP \fIoutput-file\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBtranscode\fP can transcode the KTX file specified as the \fIinput-file\fP argument, 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\&. The input file must be transcodable (it must be either BasisLZ supercompressed or has UASTC color model in the DFD)\&. 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
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--target <target>
|
||||
.IP "" 1c
|
||||
Target transcode format\&. If the target option is not set the r8, rg8, rgb8 or rgba8 target will be selected based on the number of channels in the input texture\&. Block compressed transcode targets can only be saved in raw format\&. Case-insensitive\&. Possible options are: etc-rgb | etc-rgba | eac-r11 | eac-rg11 | bc1 | bc3 | bc4 | bc5 | bc7 | astc | r8 | rg8 | rgb8 | rgba8\&. etc-rgb is ETC1; etc-rgba, eac-r11 and eac-rg11 are ETC2\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--zstd <level>
|
||||
.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 <level>
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,105 @@
|
||||
.TH "ktx_validate" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktx_validate \- ktx validate
|
||||
.PP
|
||||
Validate a KTX2 file\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktx validate [option\&.\&.\&.] \fIinput-file\fP
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktx\fP \fBvalidate\fP validates the Khronos texture format version 2 (KTX2) file specified as the \fIinput-file\fP argument\&. It prints any found errors and warnings to stdout\&. If the \fIinput-file\fP is '-' the file will be read from the stdin\&.
|
||||
|
||||
.PP
|
||||
The validation rules and checks are based on the official specification: KTX File Format Specification - https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html
|
||||
|
||||
.PP
|
||||
The JSON output formats conform to the https://schema.khronos.org/ktx/validate_v0.json schema\&.
|
||||
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fBktx\fP \fBvalidate\fP prints using UTF-8 encoding\&. If your console is not set for UTF-8 you will see incorrect characters in output of the file identifier on each side of the "KTX nn"\&.
|
||||
.RE
|
||||
.PP
|
||||
.SH "OPTIONS"
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--format text | json | mini-json
|
||||
.IP "" 1c
|
||||
Specifies the report output format\&. Possible options are:
|
||||
.br
|
||||
\fBtext\fP - Human readable text based format\&.
|
||||
.br
|
||||
\fBjson\fP - Formatted JSON\&.
|
||||
.br
|
||||
\fBmini-json\fP - Minified JSON\&.
|
||||
.br
|
||||
The default format is \fBtext\fP\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB-g, --gltf-basisu
|
||||
.IP "" 1c
|
||||
Check compatibility with KHR_texture_basisu glTF extension\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB-e, --warnings-as-errors
|
||||
.IP "" 1c
|
||||
Treat warnings as errors\&.
|
||||
|
||||
.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
|
||||
.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
|
||||
.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
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
.TH "ktxinfo" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
ktxinfo \- Print information about KTX or KTX2 files\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
ktxinfo [options] [\fIinfile\fP \&.\&.\&.]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
\fBktxinfo\fP prints information about the KTX files provided as arguments\&. If no arguments are given, it prints information about a single file read from standard input\&.
|
||||
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
\fBktxinfo\fP prints using UTF-8 encoding\&. If your console is not set for UTF-8 you will see incorrect characters in output of the file identifier on each side of the "KTX nn"\&.
|
||||
.RE
|
||||
.PP
|
||||
The following options are available:
|
||||
|
||||
.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
|
||||
.SH "EXIT STATUS"
|
||||
.PP
|
||||
\fBktxinfo\fP exits 0 on success, 1 on command line errors and 2 if one of the input files is not a KTX file\&.
|
||||
.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
|
||||
@@ -0,0 +1,278 @@
|
||||
.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
|
||||
@@ -0,0 +1,488 @@
|
||||
.TH "toktx" 1 "Sun Jun 14 2026 18:00:57" "Version 0.0.0" "KTX Tools Reference" \" -*- nroff -*-
|
||||
.ad l
|
||||
.nh
|
||||
.SH NAME
|
||||
toktx \- Create a KTX file from JPEG, PNG or netpbm format files\&.
|
||||
.SH "SYNOPSIS"
|
||||
.PP
|
||||
toktx [options] \fIoutfile\fP [\fIinfile\fP\&.{jpg,png,pam,pgm,ppm} \&.\&.\&.]
|
||||
.SH "DESCRIPTION"
|
||||
.PP
|
||||
Create a Khronos format texture file (KTX) from a set of JPEG (\&.jpg), PNG (\&.png) or Netpbm format (\&.pam, \&.pgm, \&.ppm) images\&. It writes the destination ktx file to \fIoutfile\fP, creating parent directories and appending "\&.ktx{,2}" if necessary\&. If \fIoutfile\fP is '-' the output will be written to stdout\&.
|
||||
|
||||
.PP
|
||||
\fBtoktx\fP reads each named \fIinfile\fP\&. which must be in \&.jpg, \&.png, \&.pam, \&.ppm or \&.pgm format\&. \fIinfiles\fP prefixed with '@' are read as text files listing actual file names to process with one file path per line\&. Paths must be absolute or relative to the current directory when \fBtoktx\fP is run\&. If '@@' is used instead, paths must be absolute or relative to the location of the list file\&. File paths must be encoded in UTF-8\&.
|
||||
|
||||
.PP
|
||||
The target texture type (number of components in the output texture) is chosen via \fB--target_type\fP\&. Swizzling of the components of the input file is specified with \fB--input_swizzle\fP and swizzzle metadata can be specified with \fB--swizzle\fP\&. Defaults, shown in the following table, are based on the components of the input file and whether the target texture format is uncompressed or block-compressed including the universal formats\&. Input components are arbitrarily labeled r, g, b & a\&.
|
||||
|
||||
.PP
|
||||
Uncompressed Formats Block-compressed formats Input components 1 (greyscale) 2 (greyscale alpha) 3 4 1 2 3 4 Target type R RG RGB RGBA RGB RGBA RGB RGBA Input swizzle - - - - rrr1 rrrg - - Swizzle rrr1 rrrg - - - - - -
|
||||
|
||||
.PP
|
||||
As can be seen from the table one- and two-component inputs are treated as luminance{,-alpha} in accordance with the JPEG and PNG specifications\&. For consistency Netpbm inputs are handled the same way\&. Use of R & RG types for uncompressed formats saves space but note that the sRGB versions of these formats are not widely supported so a warning will be issued prompting you to convert the input to linear\&.
|
||||
|
||||
.PP
|
||||
The primaries, transfer function (OETF) and the texture's sRGB-ness is set based on the input file unless \fB--assign_oetf\fP linear or \fB--assign_oetf\fP srgb is specified\&. For \&.jpg files \fBtoktx\fP always sets BT709/sRGB primaries and the sRGB OETF in the output file and creates sRGB format textures\&. Netpbm files always use BT\&.709/sRGB primaries and the BT\&.709 OETF\&. \fBtoktx\fP tranforms these images to the sRGB OETF, sets BT709/sRGB primaries and the sRGB OETF in the output file and creates sRGB format textures\&.
|
||||
|
||||
.PP
|
||||
For \&.png files the OETF is set as follows:
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fBNo color-info chunks or sRGB chunk present:
|
||||
.IP "" 1c
|
||||
primaries are set to BT\&.709 and OETF to sRGB\&.
|
||||
|
||||
.PP
|
||||
.IP "\fBsRGB chunk present:
|
||||
.IP "" 1c
|
||||
primaries are set to BT\&.709 and OETF to sRGB\&. gAMA and cHRM chunks are ignored\&.
|
||||
|
||||
.PP
|
||||
.IP "\fBiCCP chunk present:
|
||||
.IP "" 1c
|
||||
General ICC profiles are not yet supported by toktx or the KTX2 format\&. In future these images may be transformed to linear or sRGB OETF as appropriate for the profile\&. sRGB chunk must not be present\&.
|
||||
|
||||
.PP
|
||||
.IP "\fBgAMA and/or cHRM chunks present without sRGB or iCCP:
|
||||
.IP "" 1c
|
||||
If gAMA is < 60000 the image is transformed to and the OETF is set to sRGB\&. otherwise the image is transformed to and the OETF is set to linear\&. The color primaries in cHRM are matched to one of the standard sets listed in the Khronos Data Format Specification (the KHR_DF_PRIMARIES values from khr_df\&.h) and the primaries field of the output file's DFD is set to the matched value\&. If no match is found the primaries field is set to UNSPECIFIED\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
The following options are always available:
|
||||
|
||||
.PP
|
||||
.IP "\fB--2d
|
||||
.IP "" 1c
|
||||
If the image height is 1, by default a KTX file for a 1D texture is created\&. With this option one for a 2D texture is created instead\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--automipmap
|
||||
.IP "" 1c
|
||||
Causes the KTX file to be marked to request generation of a mipmap pyramid when the file is loaded\&. This option is mutually exclusive with \fB--genmipmap\fP, \fB--levels\fP and \fB--mipmap\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--cubemap
|
||||
.IP "" 1c
|
||||
KTX file is for a cubemap\&. At least 6 \fIinfiles\fP must be provided, more if \fB--mipmap\fP or \fB--layers\fP is also specified\&. Provide the images in the order +X, -X, +Y, -Y, +Z, -Z where the arrangement is a left-handed coordinate system with +Y up\&. So if you're facing +Z, -X will be on your left and +X on your right\&. If \fB--layers\fP > 1 is specified, provide the faces for layer 0 first then for layer 1, etc\&. Images must have an upper left origin so --lower_left_maps_to_s0t0 is ignored with this option\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--depth <number>
|
||||
.IP "" 1c
|
||||
KTX file is for a 3D texture with a depth of \fInumber\fP where \fInumber\fP > 0\&. Provide the file(s) for z=0 first then those for z=1, etc\&. It is an error to specify this together with \fB--layers\fP or \fB--cubemap\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--genmipmap
|
||||
.IP "" 1c
|
||||
Causes mipmaps to be generated for each input file\&. This option is mutually exclusive with \fB--automipmap\fP and \fB--mipmap\fP\&. When set, the following mipmap-generation related options become valid, otherwise they are ignored\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--filter <name>
|
||||
.IP "" 1c
|
||||
Specifies the filter to use when generating the mipmaps\&. \fIname\fP is a string\&. The default is \fIlanczos4\fP\&. The following names are recognized: \fIbox\fP, \fItent\fP, \fIbell\fP, \fIb-spline\fP, \fImitchell\fP, \fIlanczos3\fP, \fIlanczos4\fP, \fIlanczos6\fP, \fIlanczos12\fP, \fIblackman\fP, \fIkaiser\fP, \fIgaussian\fP, \fIcatmullrom\fP, \fIquadratic_interp\fP, \fIquadratic_approx\fP and \fIquadratic_mix\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--fscale <floatVal>
|
||||
.IP "" 1c
|
||||
The filter scale to use\&. The default is 1\&.0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--wmode <mode>
|
||||
.IP "" 1c
|
||||
Specify how to sample pixels near the image boundaries\&. Values are \fIwrap\fP, \fIreflect\fP and \fIclamp\fP\&. The default is \fIclamp\fP\&.
|
||||
|
||||
.PP
|
||||
|
||||
.PP
|
||||
.IP "\fB--layers <number>
|
||||
.IP "" 1c
|
||||
KTX file is for an array texture with \fInumber\fP of layers where \fInumber\fP > 0\&. Provide the file(s) for layer 0 first then those for layer 1, etc\&. It is an error to specify this together with \fB--depth\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--levels <number>
|
||||
.IP "" 1c
|
||||
KTX file is for a mipmap pyramid with \fInumber\fP of levels rather than a full pyramid\&. \fInumber\fP must be > 1 and <= the maximum number of levels determined from the size of the base level image\&. Provide the base level image first, if using \fB--mipmap\fP\&. This option is mutually exclusive with \fB--automipmap\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--mipmap
|
||||
.IP "" 1c
|
||||
KTX file is for a mipmap pyramid with one \fBinfile\fP being explicitly provided for each level\&. Provide the images in the order of layer then face or depth slice then level with the base-level image first then in order down to the 1x1 image or the level specified by \fB--levels\fP\&.
|
||||
.PP
|
||||
\fBNote\fP
|
||||
.RS 4
|
||||
This ordering differs from that in the created texture as it is felt to be more user-friendly\&.
|
||||
.RE
|
||||
.PP
|
||||
This option is mutually exclusive with \fB--automipmap\fP and \fB--genmipmap\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--nometadata
|
||||
.IP "" 1c
|
||||
Do not write KTXorientation metadata into the output file\&. Metadata is written by default\&. Use of this option is not recommended\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--nowarn
|
||||
.IP "" 1c
|
||||
Silence warnings which are issued when certain transformations are performed on input images\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--upper_left_maps_to_s0t0
|
||||
.IP "" 1c
|
||||
Map the logical upper left corner of the image to s0,t0\&. Although opposite to the OpenGL convention, this is the DEFAULT BEHAVIOUR\&. netpbm and PNG files have an upper left origin so this option does not flip the input images\&. When this option is in effect, toktx writes a KTXorientation value of S=r,T=d into the output file to inform loaders of the logical orientation\&. If an OpenGL {,ES} loader ignores the orientation value, the image will appear upside down\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--lower_left_maps_to_s0t0
|
||||
.IP "" 1c
|
||||
Map the logical lower left corner of the image to s0,t0\&. This causes the input netpbm and PNG images to be flipped vertically to a lower-left origin\&. When this option is in effect, toktx writes a KTXorientation value of S=r,T=u into the output file to inform loaders of the logical orientation\&. If a Vulkan loader ignores the orientation value, the image will appear upside down\&. This option is ignored with \fB--cubemap\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign_oetf <linear|srgb>
|
||||
.IP "" 1c
|
||||
Force the created texture to have the specified transfer function\&. If this is specified, implicit or explicit color space information from the input file(s) will be ignored and no color transformation will be performed\&. USE WITH CAUTION preferably only when you know the file format information is wrong\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--assign_primaries <bt709|none|srgb>
|
||||
.IP "" 1c
|
||||
Force the created texture to have the specified primaries\&. If this is specified, implicit or explicit color space information from the input file(s) will be ignored and no color transformation will be performed\&. USE WITH CAUTION preferably only when you know the file format information is wrong\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert_oetf <linear|srgb>
|
||||
.IP "" 1c
|
||||
Convert the input images to the specified transfer function, if the current transfer function is different\&. If both this and \fB--assign_oetf\fP are specified, conversion will be performed from the assigned transfer function to the transfer function specified by this option, if different\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--convert_primaries <primaries>
|
||||
.IP "" 1c
|
||||
Convert the image images to the specified color primaries, if different from the color primaries of the input file(s) or the one specified by --assign-primaries\&. If both this and --assign-primaries are specified, conversion will be performed from the assigned primaries to the primaries specified by this option, if different\&. This option is not allowed to be specified when --assign-primaries is set to 'none'\&. Case insensitive\&. Possible options are: bt709 | srgb | bt601-ebu | bt601-smpte | bt2020 | ciexyz | aces | acescc | ntsc1953 | pal525 | displayp3 | adobergb
|
||||
|
||||
.PP
|
||||
.IP "\fB--linear
|
||||
.IP "" 1c
|
||||
Deprecated\&. Use \fB--assign_oetf\fP linear\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--srgb
|
||||
.IP "" 1c
|
||||
Deprecated\&. Use \fB--assign_oetf\fP srgb\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--resize <width>x<height>
|
||||
.IP "" 1c
|
||||
Resize images to \fIwidth\fP X \fIheight\fP\&. This should not be used with \fB--mipmap\fP as it would resize all the images to the same size\&. Resampler options can be set via \fB--filter\fP and \fB--fscale\fP\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--scale <value>
|
||||
.IP "" 1c
|
||||
Scale images by \fIvalue\fP as they are read\&. Resampler options can be set via \fB--filter\fP and \fB--fscale\fP\&. \&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--swizzle <swizzle>
|
||||
.IP "" 1c
|
||||
Add swizzle metadata to the file being created\&. \fIswizzle\fP has the same syntax as the parameter for \fB--input_swizzle\fP\&. Not recommended for use with block-cmpressed textures, including Basis Universal formats, because something like \fRrabb\fP may yield drastically different error metrics if done after compression\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--target_type <type>
|
||||
.IP "" 1c
|
||||
Specify the number of components in the created texture\&. \fItype\fP is one of the following strings: \fRR\fP, \fRRG\fP, \fRRGB\fP or \fRRGBA\fP\&. Excess input components will be dropped\&. Output components with no mapping from the input will be set to 0 or, if the alpha component, 1\&.0\&.
|
||||
|
||||
.PP
|
||||
.IP "\fB--t2
|
||||
.IP "" 1c
|
||||
Output in KTX2 format\&. Default is KTX\&.
|
||||
|
||||
.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\&.
|
||||
|
||||
Options can also be set in the environment variable TOKTX_OPTIONS\&.
|
||||
TOKTX_OPTIONS is parsed first\&. If conflicting options appear in
|
||||
TOKTX_OPTIONS or the command line, the last one seen wins\&. However if both
|
||||
@b --automipmap and @b --mipmap are seen, it is always flagged as an error\&.
|
||||
You can, for example, set TOKTX_OPTIONS=--lower_left_maps_to_s0t0 to change
|
||||
the default mapping of the logical image origin to match the GL convention\&.
|
||||
.fi
|
||||
.PP
|
||||
|
||||
.SH "EXIT STATUS"
|
||||
.PP
|
||||
\fBtoktx\fP exits 0 on success, 1 on command line errors and 2 on functional errors\&.
|
||||
.SH "HISTORY"
|
||||
.PP
|
||||
\fBVersion 4\&.0 (using new version numbering system)\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Add KTX version 2 support including Basis Universal encoding\&.
|
||||
.IP "\(bu" 2
|
||||
Add \&.png and \&.jpg readers\&.
|
||||
.IP "\(bu" 2
|
||||
Transform NetPBM input files to sRGB OETF\&.
|
||||
.IP "\(bu" 2
|
||||
Add mipmap generation\&.
|
||||
.IP "\(bu" 2
|
||||
Remove legacy items\&.
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
\fBVersion 1\&.3\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Switch to ktxTexture API\&.
|
||||
.IP "\(bu" 2
|
||||
Add --levels option\&.
|
||||
.IP "\(bu" 2
|
||||
Add --2d option\&.
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
\fBVersion 1\&.2\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Remove --sized; always create sized format\&.
|
||||
.IP "\(bu" 2
|
||||
Write metadata by default\&.
|
||||
.IP "\(bu" 2
|
||||
Bug fixes\&.
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
\fBVersion 1\&.1\fP
|
||||
.RS 4
|
||||
|
||||
.IP "\(bu" 2
|
||||
Moved --alpha and --luminance to legacy\&.
|
||||
.PP
|
||||
.RE
|
||||
.PP
|
||||
.SH "AUTHOR"
|
||||
.PP
|
||||
Mark Callow, github\&.com/MarkCallow
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/memstream.c.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
@@ -0,0 +1 @@
|
||||
.so man3/ktx.h.3
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user