abdelrahman/how-to-vulkan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add ktx

Browse Source
This commit is contained in:
Abdelrahman Said
2026-06-14 19:09:18 +01:00
parent 14bd1a9271
commit 13fa90a0e9
3958 changed files with 999286 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ktx/build/docs/html/ktxtools/ktx_create.html
+463
View File
@@ -0,0 +1,463 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.16.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>KTX Tools Reference: ktx create</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectlogo"><img alt="Logo" src="ktx_logo_200.png"/></td>
<td id="projectalign">
<div id="projectname">KTX Tools Reference<span id="projectnumber">&#160;0.0.0</span>
</div>
<div id="projectbrief">Libraries and tools to create and read KTX image texture files.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.16.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('ktx_create.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">ktx create </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Create a KTX2 file from various input files.</p>
<h1 class="doxsection"><a class="anchor" id="ktx_create_synopsis"></a>
SYNOPSIS</h1>
<p>ktx create [option...] <em>input-file</em>... <em>output-file</em> </p>
<h1 class="doxsection"><a class="anchor" id="ktx_create_description"></a>
DESCRIPTION</h1>
<p><b>ktx</b> <b>create</b> can create, encode and supercompress a KTX2 file from the input images specified as the <em>input-file</em>... arguments and save it as the <em>output-file</em>. The last positional argument is treated as the <em>output-file</em>. If the <em>input-file</em> is '-' the file will be read from the stdin. If the <em>output-path</em> is '-' the output file will be written to the stdout.</p>
<p>Each <em>input-file</em> 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.</p>
<p>The number of input-files specified must match the expected number of input images based on the used options.</p>
<h1 class="doxsection"><a class="anchor" id="ktx_create_options"></a>
OPTIONS</h1>
<h2 class="doxsection"><a class="anchor" id="ktx_create_options_general"></a>
General Options</h2>
<p>The following are available: </p><dl>
<dt>--format &lt;enum&gt; </dt>
<dd>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 <code>R8G8B8_{SRGB</code>,UNORM} or <code>R8G8B8A8_{SRGB</code>,UNORM} is created then encoded to the specified ASTC format. The latter format is chosen if alpha is present in the input. <code>SRGB</code> or <code>UNORM</code> is chosen depending on the specified ASTC format. The ASTC-specific and common encoder options listed <a class="el" href="#ktx_create_options_encoding" title="Specific and Common Encoding Options">below</a> become valid, otherwise they are ignored. This matches the functionality of the <a class="el" href="ktx_encode.html" title="ktx encode">ktx encode</a> command when an ASTC format is specified.<br />
<br />
When used with <b>--encode</b> it specifies the target format before the encoding step. In this case it must be one of: <ul>
<li>
R8_UNORM </li>
<li>
R8_SRGB </li>
<li>
R8G8_UNORM </li>
<li>
R8G8_SRGB </li>
<li>
R8G8B8_UNORM </li>
<li>
R8G8B8_SRGB </li>
<li>
R8G8B8A8_UNORM </li>
<li>
R8G8B8A8_SRGB </li>
</ul>
The format will be used to verify and load all input files into a texture before performing any specified encoding.<br />
</dd>
<dt>--encode basis-lz | uastc </dt>
<dd><p class="startdd">Encode the texture with the specified codec before saving it. This option matches the functionality of the <a class="el" href="ktx_encode.html" title="ktx encode">ktx encode</a> command. With each choice, the specific and common encoder options listed <a class="el" href="#ktx_create_options_encoding" title="Specific and Common Encoding Options">below</a> become valid, otherwise they are ignored. Case-insensitive.</p>
<dl>
<dt>basis-lz: </dt>
<dd>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 <em>basis-lz</em> options become valid. </dd>
<dt>uastc: </dt>
<dd>Create a texture in high-quality transcodable UASTC format. When set the <em>uastc</em> options become valid. </dd>
</dl>
<p class="enddd"></p>
</dd>
<dt>--1d </dt>
<dd>Create a 1D texture. If not set the texture will be a 2D or 3D texture. </dd>
<dt>--cubemap </dt>
<dd>Create a cubemap texture. If not set the texture will be a 2D or 3D texture. </dd>
<dt>--raw </dt>
<dd>Create from raw image data. </dd>
<dt>--width </dt>
<dd>Base level width in pixels. Required with <b>--raw</b>. 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 <b>--generate-mipmap</b> to tune the resampler. </dd>
<dt>--height </dt>
<dd>Base level height in pixels. Required with <b>--raw</b>. 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 <b>--generate-mipmap</b> to tune the resampler. </dd>
<dt>--depth </dt>
<dd>Base level depth in pixels. If set the texture will be a 3D texture. </dd>
<dt>--layers </dt>
<dd>Number of layers. If set the texture will be an array texture. </dd>
<dt>--levels </dt>
<dd>Number of mip levels. This is the number of level images to include in the texture being created. If <b>--generate-mipmap</b> 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 <b>--scale</b>. </dd>
<dt>--runtime-mipmap </dt>
<dd>Runtime mipmap generation mode. Sets up the texture to request the mipmaps to be generated by the client application at runtime. </dd>
<dt>--generate-mipmap </dt>
<dd>Causes mipmaps to be generated during texture creation. If <b>--levels</b> is not specified the maximum possible mip level will be generated. This option is mutually exclusive with &ndash;runtime-mipmap and cannot be used with SINT, UINT or 3D textures or <b>--raw</b>. When set it enables the use of the following 'Generate Mipmap' options. <dl>
<dt>--mipmap-filter &lt;filter&gt; </dt>
<dd>Specifies the filter to use when generating the mipmaps. Case insensitive. Ignored unless <b>--generate-mipmap</b>, <b>--scale</b>, <b>--width</b> or <b>--height</b> 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. </dd>
<dt>--mipmap-filter-scale &lt;float&gt; </dt>
<dd>The filter scale to use. Defaults to 1.0. Ignored unless <b>--generate-mipmap</b>, <b>--scale</b>, <b>--width</b> or <b>--height</b> are specified for non-raw input. </dd>
<dt>--mipmap-wrap &lt;mode&gt; </dt>
<dd>Specify how to sample pixels near the image boundaries. Case insensitive. Ignored unless <b>--generate-mipmap</b>, <b>--scale</b>, <b>--width</b> or <b>--height</b> are specified for non-raw input.<br />
Possible options are: wrap | reflect | clamp. Defaults to clamp. </dd>
</dl>
Avoid mipmap generation if the Output TF (see <a class="el" href="#ktx_create_tf_handling" title="TRANSFER FUNCTION HANDLING">TRANSFER FUNCTION HANDLING</a> below) is non-linear and is not sRGB. </dd>
<dt>--scale </dt>
<dd>Scale images as they are loaded. Cannot be used with &ndash;raw. It enables use of the 'Generate Mipmap' options listed under --generate-mipmap to tune the resampler. </dd>
<dt>--normalize </dt>
<dd>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 <b>--normal-mode</b>. 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 <b>--raw</b>. </dd>
<dt>--swizzle [rgba01]{4} </dt>
<dd>KTX swizzle metadata. </dd>
<dt>--input-swizzle [rgba01]{4} </dt>
<dd>Pre-swizzle input channels. </dd>
<dt>--assign-tf &lt;transfer function&gt; </dt>
<dd>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 <a class="el" href="#ktx_create_tf_handling" title="TRANSFER FUNCTION HANDLING">TRANSFER FUNCTION HANDLING</a> below for important information. </dd>
<dt>--assign-oetf &lt;transfer function&gt; </dt>
<dd>Deprecated and will be removed. Use <b>--assign-tf</b> instead. </dd>
<dt>--assign-primaries &lt;primaries&gt; </dt>
<dd>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. <dl class="section note"><dt>Note</dt><dd><code>bt601-ebu</code> and <code>bt601-smpte</code>, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e. </dd></dl>
</dd>
<dt>--assign-texcoord-origin &lt;corner&gt; </dt>
<dd>Force the created texture to indicate that the texture coordinate origin s=0, t=0 is at the specified <em>corner</em> 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 <b>--depth</b> is specified. Must be top-left if <b>--cubemap</b> is specified. Absent <b>—convert-texcoord-origin</b>, the effect of this option is to cause <em>KTXorientation</em> metadata indicating the specified origin to be written to the output file. Example values are "rd" (top-left) and "ru" (bottom-left) or, when <b>--depth</b> is specified, "rdi" (top-left-front) and "rui" (bottom-left-front). </dd>
<dt>--convert-tf &lt;transfer function&gt; </dt>
<dd>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 <b>--assign-tf</b> 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 <b>--raw</b>. Case insensitive. The options are: linear | srgb. The following srgb aliases are also supported: srgb_eotf | scrgb | scrgb_eotf. See <a class="el" href="#ktx_create_tf_handling" title="TRANSFER FUNCTION HANDLING">TRANSFER FUNCTION HANDLING</a> below for more information. </dd>
<dt>--convert-oetf &lt;transfer function&gt; </dt>
<dd>Deprecated and will be removed. Use <b>--convert-tf</b> instead. </dd>
<dt>--convert-primaries &lt;primaries&gt; </dt>
<dd>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 <b>--assign-primaries</b>. If both this and <b>--assign-primaries</b> 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 <b>--assign-primaries</b> is set to 'none'. Cannot be used with <b>--raw</b>. 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 <dl class="section note"><dt>Note</dt><dd><code>bt601-ebu</code> and <code>bt601-smpte</code>, supported in previous releases, have been replaced with names consistent with khr_df_primaries_e. </dd></dl>
</dd>
<dt>--convert-texcoord-origin &lt;corner&gt; </dt>
<dd>Convert the input image(s) so the texture coordinate origin s=0, t=0, is at the specified <em>corner</em> of the logical image. If both this and <b>--assign-texcoord-origin</b> 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 <b>--raw</b>. Case insensitive. Possible options are: top-left | bottom-left. -front | -back can be appended and one of these is required when <b>--depth</b> is specified. Must be top-left if <b>--cubemap</b> is specified.<br />
<br />
Input images whose origin does not match <em>corner</em> will be flipped vertically. <em>KTXorientation</em> metadata indicating the the specified origin is written to the output file. Example values are "rd" (top-left) and "ru" (bottom-left) or, when <b>--depth</b> 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 <b>--assign-texcoord-origin</b> to specify the orientation. <dl class="section note"><dt>Note</dt><dd>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. </dd></dl>
</dd>
<dt>--fail-on-color-conversions </dt>
<dd>Generates an error if any input images would need to be color converted. </dd>
<dt>--warn-on-color-conversions </dt>
<dd>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. </dd>
<dt>--no-warn-on-color-conversions </dt>
<dd>Disable all warnings about color conversions including that for visually lossy conversions. Overrides <b>--warn-on-color-conversions</b> should both be specified. </dd>
<dt>--fail-on-origin-changes </dt>
<dd>Generates an error if any of the input images would need to have their origin changed. </dd>
<dt>--warn-on-origin-changes </dt>
<dd>Generates a warning if any of the input images have their origin changed.. </dd>
</dl>
<dl>
<dt>--zstd &lt;level&gt; </dt>
<dd>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. </dd>
<dt>--zlib &lt;level&gt; </dt>
<dd>Supercompress the data with ZLIB. Cannot be used with ETC1S / BasisLZ format. Level range is [1,9]. Lower levels give faster but worse compression. </dd>
</dl>
<dl>
<dt>-h, --help </dt>
<dd>Print this usage message and exit. </dd>
<dt>-v, --version </dt>
<dd>Print the version number of this program and exit. </dd>
</dl>
<h2 class="doxsection"><a class="anchor" id="ktx_create_options_encoding"></a>
Specific and Common Encoding Options</h2>
<p>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. </p><dl>
<dt>ASTC: </dt>
<dd><p class="startdd"></p>
<dl>
<dt>--astc-quality &lt;level&gt; </dt>
<dd>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: <table class="doxtable">
<tr>
<th>Level </th><th>Quality </th></tr>
<tr>
<td>fastest </td><td>(equivalent to quality = 0) </td></tr>
<tr>
<td>fast </td><td>(equivalent to quality = 10) </td></tr>
<tr>
<td>medium </td><td>(equivalent to quality = 60) </td></tr>
<tr>
<td>thorough </td><td>(equivalent to quality = 98) </td></tr>
<tr>
<td>exhaustive </td><td>(equivalent to quality = 100) </td></tr>
</table>
</dd>
<dt>--astc-perceptual </dt>
<dd>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. </dd>
</dl>
</dd>
</dl>
<dl>
<dt>basis-lz: </dt>
<dd><dl>
<dt>--clevel &lt;level&gt; </dt>
<dd>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 <b>--qlevel</b> first. </dd>
<dt>--qlevel &lt;level&gt; </dt>
<dd><p class="startdd">ETC1S / BasisLZ quality level. Range is [1,255]. Lower gives better compression/lower quality/faster. Higher gives less compression/higher quality/slower. <b>--qlevel</b> automatically determines values for <b>--max-endpoints</b>, <b>--max-selectors</b>, <b>--endpoint-rdo-threshold</b> and <b>--selector-rdo-threshold</b> for the target quality level. Setting these options overrides the values determined by -qlevel which defaults to 128 if neither it nor <b>--max-endpoints</b> and <b>--max-selectors</b> have been set.</p>
<p class="interdd">Note that both of <b>--max-endpoints</b> and <b>--max-selectors</b> must be set for them to have any effect. If all three options are set, a warning will be issued that <b>--qlevel</b> will be ignored.</p>
<p class="enddd">Note also that <b>--qlevel</b> will only determine values for <b>--endpoint-rdo-threshold</b> and <b>--selector-rdo-threshold</b> when its value exceeds 128, otherwise their defaults will be used. </p>
</dd>
<dt>--max-endpoints &lt;arg&gt; </dt>
<dd>Manually set the maximum number of color endpoint clusters. Range is [1,16128]. Default is 0, unset. </dd>
<dt>--endpoint-rdo-threshold &lt;arg&gt; </dt>
<dd>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 <b>--qlevel</b>. </dd>
<dt>--max-selectors &lt;arg&gt; </dt>
<dd>Manually set the maximum number of color selector clusters from [1,16128]. Default is 0, unset. </dd>
<dt>--selector-rdo-threshold &lt;arg&gt; </dt>
<dd>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 <b>--qlevel</b>. </dd>
<dt>--no-endpoint-rdo </dt>
<dd>Disable endpoint rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do endpoint RDO. </dd>
<dt>--no-selector-rdo </dt>
<dd>Disable selector rate distortion optimizations. Slightly faster, less noisy output, but lower quality per output bit. Default is to do selector RDO. </dd>
</dl>
<p class="enddd"></p>
</dd>
<dt>uastc: </dt>
<dd><p class="startdd"></p>
<dl>
<dt>--uastc-quality &lt;level&gt; </dt>
<dd><p class="startdd">This optional parameter selects a speed vs quality tradeoff as shown in the following table:</p>
<table class="doxtable">
<tr>
<th>Level</th><th>Speed</th><th>Quality</th></tr>
<tr>
<td>0 </td><td>Fastest </td><td>43.45dB</td></tr>
<tr>
<td>1 </td><td>Faster </td><td>46.49dB</td></tr>
<tr>
<td>2 </td><td>Default </td><td>47.47dB</td></tr>
<tr>
<td>3 </td><td>Slower </td><td>48.01dB</td></tr>
<tr>
<td>4 </td><td>Very slow </td><td>48.24dB</td></tr>
</table>
<p class="enddd">You are strongly encouraged to also specify <b>--zstd</b> 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: </p>
</dd>
<dt>--uastc-rdo </dt>
<dd>Enable UASTC RDO post-processing. </dd>
<dt>--uastc-rdo-l &lt;lambda&gt; </dt>
<dd><p class="startdd">Set UASTC RDO quality scalar (lambda) to <em>lambda</em>. 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.</p>
<p class="enddd">Note that previous versions used the <b>--uastc-rdo-q</b> option which was removed because the RDO algorithm changed. </p>
</dd>
<dt>--uastc-rdo-d &lt;dictsize&gt; </dt>
<dd>Set UASTC RDO dictionary size in bytes. Default is 4096. Lower values=faster, but give less compression. Range is [64,65536]. </dd>
<dt>--uastc-rdo-b &lt;scale&gt; </dt>
<dd>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. </dd>
<dt>--uastc-rdo-s &lt;deviation&gt; </dt>
<dd>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. </dd>
<dt>--uastc-rdo-f </dt>
<dd>Do not favor simpler UASTC modes in RDO mode. </dd>
<dt>--uastc-rdo-m </dt>
<dd>Disable RDO multithreading (slightly higher compression, deterministic). </dd>
</dl>
</dd>
</dl>
<dl>
<dt>common: </dt>
<dd><dl>
<dt>--normal-mode </dt>
<dd><p class="startdd">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 <b>--normalize</b>. If the input has 2 linear components it is assumed to be an X+Y map of unit normals.</p>
<p class="enddd">The Z component can be recovered programmatically in shader code by using the equations: </p><pre>
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
</pre><p> For ETC1S / BasisLZ encoding, <b>'--encode</b> basis-lz', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality. </p>
</dd>
<dt>--threads &lt;count&gt; </dt>
<dd>Explicitly set the number of threads to use during compression. By default, ETC1S / BasisLZ will use the number of threads reported by <code>thread::hardware_concurrency</code> or 1 if value returned is 0. </dd>
<dt>--no-sse </dt>
<dd>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.. </dd>
</dl>
</dd>
</dl>
<dl>
<dt></dt>
<dd><dl>
<dt>--compare-ssim </dt>
<dd>Calculate encoding structural similarity index measure (SSIM) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding. </dd>
<dt>--compare-psnr </dt>
<dd>Calculate encoding peak signal-to-noise ratio (PSNR) and print it to stdout. Requires Basis-LZ, UASTC or ASTC encoding. </dd>
</dl>
</dd>
</dl>
<h1 class="doxsection"><a class="anchor" id="ktx_create_tf_handling"></a>
TRANSFER FUNCTION HANDLING</h1>
<p>The diagram below shows all assignments and conversions that can take place.</p>
<pre class="fragment">┌──────────┐ ┌─────────┐
│ ├──────────────────1─────────────────►│ │
│ │ ┌───────────┐ │ │
│ Input │ │ │ │ │
│ Transfer │ │ --assign- ├──────────2──────────►│Output │
│ function │ │ tf │ ┌────────────┐ │Transfer │
│ from │ │ ├─3─►│ │ │Function │
│ file │ │ │ │ --convert- │ │ │
│ metadata │ └───────────┘ │ tf ├3,4►│ │
│ │ │ │ │ │
│ ├────────4─────────►│ │ │ │
└──────────┘ └────────────┘ └─────────┘
</pre><h4>Processing Paths</h4>
<ol>
<li>
Pass through. No options specified. </li>
<li>
<b>--assign-tf</b> specified. </li>
<li>
<b>--assign-tf</b> and <b>--convert-tf</b> specified. </li>
<li>
<b>--convert-tf</b> specified. </li>
</ol>
<h2 class="doxsection"><a class="anchor" id="ktx_create_tf_handling_details"></a>
Details</h2>
<p>Transfer function handling proceeds as follows: </p><ul>
<li>
If <b>--format</b> specifies one of the <code>*_SRGB{</code>,_*} formats and Output Transfer Function is not sRGB (a.k.a scRGB) an error is generated. </li>
<li>
If <b>--format</b> does not specify one of the <code>*_SRGB{</code>,_*} formats, an sRGB variant exists and Output Transfer Function is sRGB (a.k.a scRGB), an error is generated. </li>
<li>
Otherwise, the transfer function of the output KTX file is set to Output Transfer Function. </li>
<li>
If neither <b>--assign-tf</b> nor <b>--convert-tf</b> is specified: <ul>
<li>
If the Input Transfer Function is not sRGB (a.k.a scRGB) for <code>*_SRGB{</code>,_*} formats an implicit conversion to sRGB is done, equivalent to <b>--convert-tf</b> srgb. </li>
<li>
If the Input Transfer Function is not linear for formats that are not one of the <code>*_SRGB{</code>,_*} formats, an implicit conversion to linear is done equivalent to <b>--convert-tf</b> linear. </li>
</ul>
</li>
<li>
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. </li>
<li>
Supported outputs for implicit or explicit conversion are linear and sRGB, An error is generated if an unsupported conversion is required. </li>
<li>
Output Transfer Function for a format that is not one of the <code>*_SRGB{</code>,_*} formats can be set to a non-linear transfer function via <b>--assign-tf</b>. </li>
<li>
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 <b>--no-warn-on-color-conversions</b>. A warning or an error on any color conversion can be requested with <b>--warn-on-color-conversions</b> or <b>--fail-on-color-conversions</b> . </li>
</ul>
<dl class="section note"><dt>Note</dt><dd>When <b>--format</b> does not specify one of the <em><em>SRGB{,</em></em>} formats and Output Transfer Function is not linear: <ul>
<li>the KTX file may be much less portable due to limited hardware support of such inputs. </li>
<li>avoid using <b>--generate-mipmap</b> as the filters can only decode sRGB. </li>
<li>avoid encoding to ASTC, BasisLz/ETC1S or UASTC. The encoders' quality metrics are designed for linear and sRGB.</li>
</ul>
</dd></dl>
<h2 class="doxsection"><a class="anchor" id="ktx_create_tf_handling_changes"></a>
Changes since last Release</h2>
<ol>
<li>
<b>--assign-oetf</b> and <b>--convert-oetf</b> are deprecated and will be removed. Use <b>--assign-tf</b> and <b>--convert-tf</b> instead. </li>
<li>
The parameter value for <b>--assign-tf</b> can now be any of the transfer functions known to the Khronos Data Format Specification. </li>
<li>
A warning is now generated if a visually lossy color conversion will be performed. The warning can be suppressed with <b>--no-warn-on-color-conversions</b>. </li>
</ol>
<h1 class="doxsection"><a class="anchor" id="ktx_create_exitstatus"></a>
EXIT STATUS</h1>
<ul>
<li>0 - Success</li>
<li>1 - Command line error</li>
<li>2 - IO failure</li>
<li>3 - Invalid input file</li>
<li>4 - Runtime or library error</li>
<li>5 - Not supported state or operation</li>
<li>6 - Requested feature is not yet implemented </li>
</ul>
<h1 class="doxsection"><a class="anchor" id="ktx_create_history"></a>
HISTORY</h1>
<dl class="section user"><dt>Version 4.3</dt><dd><ul>
<li>Initial version</li>
</ul>
</dd></dl>
<dl class="section user"><dt>Version 4.4</dt><dd><ul>
<li>Reorganize encoding options.</li>
<li>Improve explanation of use of <b>--format</b> with <b>--encode</b>.</li>
<li>Improve explanation of ASTC encoding.</li>
</ul>
</dd></dl>
<h1 class="doxsection"><a class="anchor" id="ktx_create_author"></a>
AUTHOR</h1>
<ul>
<li>Mátyás Császár [Vader], RasterGrid www.rastergrid.com</li>
<li>Daniel Rákos, RasterGrid www.rastergrid.com</li>
<li>Mark Callow </li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated on <span class="timestamp"></span> for KTX Tools Reference by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.16.1 </li>
</ul>
</div>
</body>
</html>