ktx create

Create a KTX2 file from various input files.

SYNOPSIS

ktx create [option...] input-file... output-file

DESCRIPTION

ktx create can create, encode and supercompress a KTX2 file from the input images specified as the input-file... arguments and save it as the output-file. The last positional argument is treated as the output-file. If the input-file is '-' the file will be read from the stdin. If the output-path is '-' the output file will be written to the stdout.

Each input-file 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.

The number of input-files specified must match the expected number of input images based on the used options.

The following options are available:

--format <enum>

KTX format enum that specifies the image data format. The enum names are matching the VkFormats without the VK_FORMAT_ prefix. The VK_FORMAT_ prefix is ignored if present.
When used with –encode it specifies the format of the input files before the encoding step. In this case it must be one of:

• R8_UNORM
• R8_SRGB
• R8G8_UNORM
• R8G8_SRGB
• R8G8B8_UNORM
• R8G8B8_SRGB
• R8G8B8A8_UNORM
• R8G8B8A8_SRGB

If the format is an ASTC format the ASTC encoder specific options become valid, otherwise they are ignored.
The format will be used to verify and load all input files into a texture before encoding.
Case insensitive. Required.

--astc-quality <level>

The quality level configures the quality-performance tradeoff for the compressor; more complete searches of the search space improve image quality at the expense of compression time. Default is 'medium'. The quality level can be set between fastest (0) and exhaustive (100) via the following fixed quality presets:

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)

--astc-perceptual

The codec should optimize for perceptual error, instead of direct RMS error. This aims to improve perceived image quality, but typically lowers the measured PSNR score. Perceptual methods are currently only available for normal maps and RGB color data.

--1d

Create a 1D texture. If not set the texture will be a 2D or 3D texture.

--cubemap

Create a cubemap texture. If not set the texture will be a 2D or 3D texture.

--raw

Create from raw image data.

--width

Base level width in pixels.

--height

Base level height in pixels.

--depth

Base level depth in pixels. If set the texture will be a 3D texture.

--layers

Number of layers. If set the texture will be an array texture.

--runtime-mipmap

Runtime mipmap generation mode. Sets up the texture to request the mipmaps to be generated by the client application at runtime.

--generate-mipmap

Causes mipmaps to be generated during texture creation. If the –levels 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. When set it enables the use of the following \'Generate Mipmap\' options.

--mipmap-filter <filter>

Specifies the filter to use when generating the mipmaps. Case insensitive.
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.

--mipmap-filter-scale <float>

The filter scale to use. Defaults to 1.0.

--mipmap-wrap <mode>

Specify how to sample pixels near the image boundaries. Case insensitive.
Possible options are: wrap | reflect | clamp. Defaults to clamp.

--encode basis-lz | uastc<

Encode the texture with the specified codec before saving it. This option matches the functionality of the ktx encode command. With each encoding option the following encoder specific options become valid, otherwise they are ignored. Case-insensitive.

basis-lz:

Supercompress the image data with ETC1S / BasisLZ. RED images will become RGB with RED in each component (RRR). RG images will have R in the RGB part and G in the alpha part of the compressed texture (RRRG). When set, the following BasisLZ-related options become valid, otherwise they are ignored.

--clevel <level>

ETC1S / BasisLZ compression level, an encoding speed vs. quality tradeoff. Range is [0,5], default is 1. Higher values are slower but give higher quality.

--qlevel <level>

ETC1S / BasisLZ quality level. Range is [1,255]. Lower gives better compression/lower quality/faster. Higher gives less compression/higher quality/slower. --qlevel automatically determines values for --max-endpoints, --max-selectors, --endpoint-rdo-threshold and --selector-rdo-threshold for the target quality level. Setting these options overrides the values determined by -qlevel which defaults to 128 if neither it nor --max-endpoints and --max-selectors have been set.

Note that both of --max-endpoints and --max-selectors must be set for them to have any effect. If all three options are set, a warning will be issued that --qlevel will be ignored.

Note also that --qlevel will only determine values for --endpoint-rdo-threshold and --selector-rdo-threshold when its value exceeds 128, otherwise their defaults will be used.

--max-endpoints <arg>

Manually set the maximum number of color endpoint clusters. Range is [1,16128]. Default is 0, unset.

--endpoint-rdo-threshold <arg>

Set endpoint RDO quality threshold. The default is 1.25. Lower is higher quality but less quality per output bit (try [1.0,3.0]). This will override the value chosen by --qlevel.

--max-selectors <arg>

Manually set the maximum number of color selector clusters from [1,16128]. Default is 0, unset.

--selector-rdo-threshold <arg>

Set selector RDO quality threshold. The default is 1.25. Lower is higher quality but less quality per output bit (try [1.0,3.0]). This will override the value chosen by --qlevel.

--no-endpoint-rdo

Disable endpoint rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do endpoint RDO.

--no-selector-rdo

Disable selector rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do selector RDO.

uastc:

Create a texture in high-quality transcodable UASTC format.

--uastc-quality <level>

This optional parameter selects a speed vs quality tradeoff as shown in the following table:

Level	Speed	Quality
0	Fastest	43.45dB
1	Faster	46.49dB
2	Default	47.47dB
3	Slower	48.01dB
4	Very slow	48.24dB

You are strongly encouraged to also specify --zstd to losslessly compress the UASTC data. This and any LZ-style compression can be made more effective by conditioning the UASTC texture data using the Rate Distortion Optimization (RDO) post-process stage. When uastc encoding is set the following options become available for controlling RDO:

--uastc-rdo

Enable UASTC RDO post-processing.

--uastc-rdo-l <lambda>

Set UASTC RDO quality scalar (lambda) to lambda. Lower values yield higher quality/larger LZ compressed files, higher values yield lower quality/smaller LZ compressed files. A good range to try is [.25,10]. For normal maps a good range is [.25,.75]. The full range is [.001,10.0]. Default is 1.0.

Note that previous versions used the --uastc-rdo-q option which was removed because the RDO algorithm changed.

--uastc-rdo-d <dictsize>

Set UASTC RDO dictionary size in bytes. Default is 4096. Lower values=faster, but give less compression. Range is [64,65536].

--uastc-rdo-b <scale>

Set UASTC RDO max smooth block error scale. Range is [1.0,300.0]. Default is 10.0, 1.0 is disabled. Larger values suppress more artifacts (and allocate more bits) on smooth blocks.

--uastc-rdo-s <deviation>

Set UASTC RDO max smooth block standard deviation. Range is [.01,65536.0]. Default is 18.0. Larger values expand the range of blocks considered smooth.

--uastc-rdo-f

Do not favor simpler UASTC modes in RDO mode.

--uastc-rdo-m

Disable RDO multithreading (slightly higher compression, deterministic).

common:

Common options.

--normal-mode

Only valid for linear textures with two or more components. If the input texture has three or four linear components it is assumed to be a three component linear normal map storing unit length normals as (R=X, G=Y, B=Z). A fourth component will be ignored. The map will be converted to a two component X+Y normal map stored as (RGB=X, A=Y) prior to encoding. If unsure that your normals are unit length, use --normalize. If the input has 2 linear components it is assumed to be an X+Y map of unit normals.

The Z component can be recovered programmatically in shader code by using the equations:

    nml.xy = texture(...).ga;              // Load in [0,1]
    nml.xy = nml.xy * 2.0 - 1.0;           // Unpack to [-1,1]
    nml.z = sqrt(1 - dot(nml.xy, nml.xy)); // Compute Z
            

For ETC1S / BasisLZ encoding, '--encode basis-lz', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality.

--threads <count>

Explicitly set the number of threads to use during compression. By default, ETC1S / BasisLZ will use the number of threads reported by thread::hardware_concurrency or 1 if value returned is 0.

--no-sse

Forbid use of the SSE instruction set. Ignored if CPU does not support SSE. SSE can only be disabled on the basis-lz and uastc compressors.

--compare-ssim

Calculate encoding structural similarity index measure (SSIM) and print it to stdout. Requires Basis-LZ or UASTC encoding.

--compare-psnr

Calculate encoding peak signal-to-noise ratio (PSNR) and print it to stdout. Requires Basis-LZ or UASTC encoding.

--swizzle [rgba01]{4}

KTX swizzle metadata.

--input-swizzle [rgba01]{4}

Pre-swizzle input channels.

--assign-oetf <oetf>

Force the created texture to have the specified transfer function, ignoring the transfer function of the input file(s). Case insensitive. Possible options are: linear | srgb

--assign-primaries <primaries>

Force the created texture to have the specified color primaries, ignoring the color primaries of the input file(s). Case insensitive. Possible options are: none | bt709 | srgb | bt601-ebu | bt601-smpte | bt2020 | ciexyz | aces | acescc | ntsc1953 | pal525 | displayp3 | adobergb

--convert-oetf <oetf>

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 –assign-oetf are specified, conversion will be performed from the assigned transfer function to the transfer function specified by this option, if different. Case insensitive. Possible options are: linear | srgb

--convert-primaries <primaries>

Convert the image image(s) 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

--fail-on-color-conversions

Generates an error if any of the input images would need to be color converted.

--warn-on-color-conversions

Generates a warning if any of the input images are color converted.

--zstd <level>

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.

--zlib <level>

Supercompress the data with ZLIB. Cannot be used with ETC1S / BasisLZ format. Level range is [1,9]. Lower levels give faster but worse compression.

-h, --help

Print this usage message and exit.

-v, --version

Print the version number of this program and exit.

EXIT STATUS

• 0 - Success
• 1 - Command line error
• 2 - IO failure
• 3 - Invalid input file
• 4 - Runtime or library error
• 5 - Not supported state or operation
• 6 - Requested feature is not yet implemented

HISTORY

Version 4.0

• Initial version

AUTHOR

• Mátyás Császár [Vader], RasterGrid www.rastergrid.com
• Daniel Rákos, RasterGrid www.rastergrid.com