Add ktx
This commit is contained in:
@@ -0,0 +1,323 @@
|
||||
<!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: ktxsc</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"> 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('ktxsc.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">ktxsc </div></div>
|
||||
</div><!--header-->
|
||||
<div class="contents">
|
||||
<div class="textblock"><p>Supercompress the images in a KTX2 file.</p>
|
||||
<h1 class="doxsection"><a class="anchor" id="ktxsc_synopsis"></a>
|
||||
SYNOPSIS</h1>
|
||||
<p>ktxsc [options] [<em>infile</em> ...]</p>
|
||||
<h1 class="doxsection"><a class="anchor" id="ktxsc_description"></a>
|
||||
DESCRIPTION</h1>
|
||||
<p><b>ktxsc</b> 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 <code>_BLOCK</code> 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 <em>--uastc_rdo_q</em> and, optionally, <em>--uastc_rdo_d</em> options.</p>
|
||||
<p><b>ktxsc</b> reads each named <em>infile</em> and compresses it in place. When <em>infile</em> is not specified, a single file will be read from <em>stdin</em> and the output written to <em>stdout</em>. When one or more files is specified each will be compressed in place.</p>
|
||||
<p>The following options are available: </p><dl>
|
||||
<dt>-o outfile, –output=outfile </dt>
|
||||
<dd>Write the output to <em>outfile</em>. If <em>outfile</em> is 'stdout', output will be written to stdout. Parent directories will be created, if necessary. If there is more than 1 <em>infile</em> the command prints its usage message and exits. </dd>
|
||||
<dt>-f, --force </dt>
|
||||
<dd>If the destination file cannot be opened, remove it and create a new file, without prompting for confirmation regardless of its permissions. </dd>
|
||||
<dt>--t2 </dt>
|
||||
<dd>Output a KTX version2 file. Always true. </dd>
|
||||
</dl>
|
||||
<dl>
|
||||
<dt>--encode <astc | etc1s | uastc> </dt>
|
||||
<dd>Compress the image data to ASTC, transcodable ETC1S / BasisLZ or high-quality transcodable UASTC format. Implies <b>--t2</b>. With each encoding option the following encoder specific options become valid, otherwise they are ignored. <dl>
|
||||
<dt>astc: </dt>
|
||||
<dd>Create a texture in high-quality ASTC format. </dd>
|
||||
<dt>--astc_blk_d <XxY | XxYxZ> </dt>
|
||||
<dd>Specify which block dimension to use for compressing the textures. e.g. <b>--astc_blk_d</b> 6x5 for 2D or <b>--astc_blk_d</b> 6x6x6 for 3D. 6x6 is the default for 2D. <table class="doxtable">
|
||||
<tr>
|
||||
<th>Supported 2D block dimensions are:</th></tr>
|
||||
<tr>
|
||||
<td>4x4</td><td>8.00 bpp</td></tr>
|
||||
<tr>
|
||||
<td>5x4</td><td>6.40 bpp</td></tr>
|
||||
<tr>
|
||||
<td>5x5</td><td>5.12 bpp</td></tr>
|
||||
<tr>
|
||||
<td>6x5</td><td>4.27 bpp</td></tr>
|
||||
<tr>
|
||||
<td>6x6</td><td>3.56 bpp</td></tr>
|
||||
<tr>
|
||||
<td>8x5</td><td>3.20 bpp</td></tr>
|
||||
<tr>
|
||||
<td>8x6</td><td>2.67 bpp</td></tr>
|
||||
<tr>
|
||||
<td>10x5</td><td>2.56 bpp</td></tr>
|
||||
<tr>
|
||||
<td>10x6</td><td>2.13 bpp</td></tr>
|
||||
<tr>
|
||||
<td>8x8</td><td>2.00 bpp</td></tr>
|
||||
<tr>
|
||||
<td>10x8</td><td>1.60 bpp</td></tr>
|
||||
<tr>
|
||||
<td>10x10</td><td>1.28 bpp</td></tr>
|
||||
<tr>
|
||||
<td>12x10</td><td>1.07 bpp</td></tr>
|
||||
<tr>
|
||||
<td>12x12</td><td>0.89 bpp</td></tr>
|
||||
<tr>
|
||||
<th>Supported 3D block dimensions are:</th></tr>
|
||||
<tr>
|
||||
<td>3x3x3</td><td>4.74 bpp</td></tr>
|
||||
<tr>
|
||||
<td>4x3x3</td><td>3.56 bpp</td></tr>
|
||||
<tr>
|
||||
<td>4x4x3</td><td>2.67 bpp</td></tr>
|
||||
<tr>
|
||||
<td>4x4x4</td><td>2.00 bpp</td></tr>
|
||||
<tr>
|
||||
<td>5x4x4</td><td>1.60 bpp</td></tr>
|
||||
<tr>
|
||||
<td>5x5x4</td><td>1.28 bpp</td></tr>
|
||||
<tr>
|
||||
<td>5x5x5</td><td>1.02 bpp</td></tr>
|
||||
<tr>
|
||||
<td>6x5x5</td><td>0.85 bpp</td></tr>
|
||||
<tr>
|
||||
<td>6x6x5</td><td>0.71 bpp</td></tr>
|
||||
<tr>
|
||||
<td>6x6x6</td><td>0.59 bpp</td></tr>
|
||||
</table>
|
||||
</dd>
|
||||
<dt>--astc_mode <ldr | hdr> </dt>
|
||||
<dd>Specify which encoding mode to use. LDR is the default unless the input image is 16-bit in which case the default is HDR. </dd>
|
||||
<dt>--astc_quality <level> </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>
|
||||
<dl>
|
||||
<dt>etc1s: </dt>
|
||||
<dd>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. </dd>
|
||||
<dt>--no_multithreading </dt>
|
||||
<dd>Disable multithreading. Deprecated. For backward compatibility. Use <b>--threads</b> 1 instead. </dd>
|
||||
<dt>--clevel <level> </dt>
|
||||
<dd>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. </dd>
|
||||
<dt>--qlevel <level> </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 both of <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 <arg> </dt>
|
||||
<dd>Manually set the maximum number of color endpoint clusters. Range is [1,16128]. Default is 0, unset. </dd>
|
||||
<dt>--endpoint_rdo_threshold <arg> </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 <arg> </dt>
|
||||
<dd>Manually set the maximum number of color selector clusters from [1,16128]. Default is 0, unset. </dd>
|
||||
<dt>--selector_rdo_threshold <arg> </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>
|
||||
<dl>
|
||||
<dt>uastc: </dt>
|
||||
<dd>Create a texture in high-quality transcodable UASTC format. </dd>
|
||||
<dt>--uastc_quality <level> </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>--zcmp</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_l [<lambda>] </dt>
|
||||
<dd><p class="startdd">Enable UASTC RDO post-processing and optionally 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 <dictsize> </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 <scale> </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 <deviation> </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>
|
||||
<dt>--input_swizzle <swizzle> </dt>
|
||||
<dd>Swizzle the input components according to <em>swizzle</em> which is an alhpanumeric sequence matching the regular expression <code>^</code>[rgba01]{4}$. </dd>
|
||||
<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="interdd">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 ASTC encoding, '<b>--encode</b> astc', encoder parameters are tuned for better quality on normal maps. For ETC1S encoding, <b>'--encode</b> etc1s', RDO is disabled (no selector RDO, no endpoint RDO) to provide better quality.</p>
|
||||
<p class="enddd">In <em>toktx</em> you can prevent conversion of the normal map to two components by specifying '<b>--input_swizzle</b> rgb1'. </p>
|
||||
</dd>
|
||||
<dt>--normalize </dt>
|
||||
<dd>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. </dd>
|
||||
<dt>--no_sse </dt>
|
||||
<dd>Forbid use of the SSE instruction set. Ignored if CPU does not support SSE. Only the Basis Universal compressor uses SSE. </dd>
|
||||
<dt>--bcmp </dt>
|
||||
<dd>Deprecated. Use '<b>--encode</b> etc1s' instead. </dd>
|
||||
<dt>--uastc [<level>] </dt>
|
||||
<dd>Deprecated. Use '<b>--encode</b> uastc' instead. </dd>
|
||||
<dt>--zcmp [<compressionLevel>] </dt>
|
||||
<dd>Supercompress the data with Zstandard. Implies <b>--t2</b>. 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. </dd>
|
||||
<dt>--threads <count> </dt>
|
||||
<dd>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. </dd>
|
||||
<dt>--verbose </dt>
|
||||
<dd>Print encoder/compressor activity status to stdout. Currently only the astc, etc1s and uastc encoders emit status. </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>
|
||||
<pre class="fragment"> 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.
|
||||
</pre> <h1 class="doxsection"><a class="anchor" id="ktxsc_exitstatus"></a>
|
||||
EXIT STATUS</h1>
|
||||
<p><b>ktxsc</b> exits 0 on success, 1 on command line errors and 2 on functional errors.</p>
|
||||
<h1 class="doxsection"><a class="anchor" id="ktxsc_history"></a>
|
||||
HISTORY</h1>
|
||||
<dl class="section user"><dt>Version 4.0</dt><dd><ul>
|
||||
<li>Initial version.</li>
|
||||
</ul>
|
||||
</dd></dl>
|
||||
<h1 class="doxsection"><a class="anchor" id="ktxsc_author"></a>
|
||||
AUTHOR</h1>
|
||||
<p>Mark Callow, github.com/MarkCallow </p>
|
||||
</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>
|
||||
Reference in New Issue
Block a user