abdelrahman/how-to-vulkan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
13fa90a0e94b17ef2c88ac895a9d2368241a6eab
how-to-vulkan/ktx/build/docs/html/libktx/index.html
T
abdelrahman 13fa90a0e9 Add ktx
2026-06-14 19:09:18 +01:00

509 lines
57 KiB
HTML
Raw Blame History

<!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>libktx Reference: libktx Reference</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">libktx 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('index.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">libktx Reference </div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>libktx is a small library of functions for creating and reading KTX (Khronos TeXture) files, version 1 and 2 and instantiating OpenGL&reg; and OpenGL&reg; ES textures and Vulkan images from them. KTX version 2 files can contain images supercompressed with <em>zstd</em> or <em>zlib</em>. They can also contain images in the Basis Universal formats. libktx can deflate and inflate zstd and zlib compressed images, can encode and transcode the Basis Universal formats and can encode ASTC formats.</p>
<p>For information about the KTX format see the <a href="https://registry.khronos.org/KTX/specs/2.0/ktxspec.v2.html">formal specification.</a></p>
<dl class="section author"><dt>Authors</dt><dd><a href="http://github.com/MarkCallow">Mark Callow</a>, formerly at <a href="http://www.hicorp.co.jp">HI Corporation</a><br />
Mátyás Császár and Daniel Rákos, <a href="https://www.rastergrid.com/">RasterGrid</a><br />
Wasim Abbas, <a href="https://www.arm.com/">Arm</a><br />
Andreas Atteneder, Independent<br />
Georg Kolling, <a href="http://www.imgtec.com">Imagination Technology</a><br />
Jacob Str&ouml;m, <a href="http://www.ericsson.com">Ericsson AB</a></dd></dl>
<dl class="section user"><dt>API Version</dt><dd>v4.0 </dd></dl>
<p>$Date$</p>
<h1 class="doxsection"><a class="anchor" id="overview"></a>
Usage Overview</h1>
<p>The following <span class="tt"><a class="el" href="structktxTexture.html" title="Base class representing a texture.">ktxTexture</a></span> examples work for both KTX and KTX2 textures. The texture type is determined from the file contents.</p>
<h2 class="doxsection"><a class="anchor" id="readktx"></a>
Reading a KTX file for non-GL and non-Vulkan Use</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture.html">ktxTexture</a>* texture;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_size_t offset;</div>
<div class="line">ktx_uint8_t* image;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture_CreateFromNamedFile(<span class="stringliteral">&quot;mytex3d.ktx&quot;</span>,</div>
<div class="line"> <a class="code hl_enumvalue" href="ktx_8h.html#a5d741f48293002f70546881d2394b6f6">KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT</a>,</div>
<div class="line"> &amp;texture);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Retrieve information about the texture from fields in the ktxTexture</span></div>
<div class="line"><span class="comment">// such as:</span></div>
<div class="line">ktx_uint32_t numLevels = texture-&gt;<a class="code hl_variable" href="structktxTexture.html#a782126a62c27ee8660a14565b906694c">numLevels</a>;</div>
<div class="line">ktx_uint32_t baseWidth = texture-&gt;<a class="code hl_variable" href="structktxTexture.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a>;</div>
<div class="line">ktx_bool_t isArray = texture-&gt;<a class="code hl_variable" href="structktxTexture.html#a9b5ca8c2e3fd76d8b427928775289078">isArray</a>;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Retrieve a pointer to the image for a specific mip level, array layer</span></div>
<div class="line"><span class="comment">// &amp; face or depth slice.</span></div>
<div class="line">level = 1; layer = 0; faceSlice = 3;</div>
<div class="line">result = <a class="code hl_define" href="ktx_8h.html#afdb41471bee56cef8241060de72d6735">ktxTexture_GetImageOffset</a>(texture, level, layer, faceSlice, &amp;offset);</div>
<div class="line">image = ktxTexture_GetData(texture) + offset;</div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line"><span class="comment">// Do something with the texture image.</span></div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(texture);</div>
<div class="ttc" id="aktx_8h_html"><div class="ttname"><a href="ktx_8h.html">ktx.h</a></div><div class="ttdoc">Declares the public functions and structures of the KTX API.</div></div>
<div class="ttc" id="aktx_8h_html_a0becd37ccf729eed8723b969bb93df3d"><div class="ttname"><a href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a></div><div class="ttdeci">#define ktxTexture_Destroy(This)</div><div class="ttdoc">Helper for calling the Destroy virtual method of a ktxTexture.</div><div class="ttdef"><b>Definition</b> ktx.h:533</div></div>
<div class="ttc" id="aktx_8h_html_a5d741f48293002f70546881d2394b6f6"><div class="ttname"><a href="ktx_8h.html#a5d741f48293002f70546881d2394b6f6">KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT</a></div><div class="ttdeci">@ KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT</div><div class="ttdef"><b>Definition</b> ktx.h:794</div></div>
<div class="ttc" id="aktx_8h_html_ad2efa40e38ebae48371375db92d34eaa"><div class="ttname"><a href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a></div><div class="ttdeci">#define KTX_error_code</div><div class="ttdoc">For backward compatibility.</div><div class="ttdef"><b>Definition</b> ktx.h:198</div></div>
<div class="ttc" id="aktx_8h_html_afdb41471bee56cef8241060de72d6735"><div class="ttname"><a href="ktx_8h.html#afdb41471bee56cef8241060de72d6735">ktxTexture_GetImageOffset</a></div><div class="ttdeci">#define ktxTexture_GetImageOffset(This, level, layer, faceSlice, pOffset)</div><div class="ttdoc">Helper for calling the GetImageOffset virtual method of a ktxTexture.</div><div class="ttdef"><b>Definition</b> ktx.h:541</div></div>
<div class="ttc" id="astructktxTexture_html"><div class="ttname"><a href="structktxTexture.html">ktxTexture</a></div><div class="ttdoc">Base class representing a texture.</div><div class="ttdef"><b>Definition</b> ktx.h:287</div></div>
<div class="ttc" id="astructktxTexture_html_a3fa51cc9001702e3f1d5a69cee65adf8"><div class="ttname"><a href="structktxTexture.html#a3fa51cc9001702e3f1d5a69cee65adf8">ktxTexture::baseWidth</a></div><div class="ttdeci">ktx_uint32_t baseWidth</div><div class="ttdoc">Width of the texture&#39;s base level.</div><div class="ttdef"><b>Definition</b> ktx.h:288</div></div>
<div class="ttc" id="astructktxTexture_html_a782126a62c27ee8660a14565b906694c"><div class="ttname"><a href="structktxTexture.html#a782126a62c27ee8660a14565b906694c">ktxTexture::numLevels</a></div><div class="ttdeci">ktx_uint32_t numLevels</div><div class="ttdoc">Number of mip levels in the texture.</div><div class="ttdef"><b>Definition</b> ktx.h:288</div></div>
<div class="ttc" id="astructktxTexture_html_a9b5ca8c2e3fd76d8b427928775289078"><div class="ttname"><a href="structktxTexture.html#a9b5ca8c2e3fd76d8b427928775289078">ktxTexture::isArray</a></div><div class="ttdeci">ktx_bool_t isArray</div><div class="ttdef"><b>Definition</b> ktx.h:288</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="createGL"></a>
Creating a GL texture object from a KTX file.</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture.html">ktxTexture</a>* kTexture;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_size_t offset;</div>
<div class="line">ktx_uint8_t* image;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line">GLuint texture = 0;</div>
<div class="line">GLenum target, glerror;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture_CreateFromNamedFile(<span class="stringliteral">&quot;mytex3d.ktx&quot;</span>,</div>
<div class="line"> KTX_TEXTURE_CREATE_NO_FLAGS,</div>
<div class="line"> &amp;kTexture);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Before the first call to ktxTexture_GLUpload make libktx load its</span></div>
<div class="line"><span class="comment">// function pointers for the GL functions it uses. The parameter is a</span></div>
<div class="line"><span class="comment">// pointer to the GLGetProcAddress function provided by whatever OpenGL</span></div>
<div class="line"><span class="comment">// framework the application is using. The example shown is for SDL.</span></div>
<div class="line"><span class="comment">//</span></div>
<div class="line"><span class="comment">// Note 1: This is unrelated to any GL function pointers the app may be</span></div>
<div class="line"><span class="comment">// using.</span></div>
<div class="line"><span class="comment">// Note 2: When this is not called, libktx has fallback mechanisms to</span></div>
<div class="line"><span class="comment">// find the pointers which work on the vast majority of</span></div>
<div class="line"><span class="comment">// platforms. The only known failures have occurred on Fedora.</span></div>
<div class="line">result = <a class="code hl_function" href="group__ktx__glloader.html#gada67f60796793d1ed9eb1f3f2d61d4a6">ktxLoadOpenGL</a>((<a class="code hl_typedef" href="ktx_8h.html#aa823ce7b0db0aaefb942c4b5a07504be">PFNGLGETPROCADDRESS</a>)SDL_GL_GetProcAddress);</div>
<div class="line"> </div>
<div class="line">glGenTextures(1, &amp;texture); <span class="comment">// Optional. GLUpload can generate a texture.</span></div>
<div class="line">result = ktxTexture_GLUpload(kTexture, &amp;texture, &amp;target, &amp;glerror);</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(kTexture);</div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line"><span class="comment">// GL rendering using the texture</span></div>
<div class="line"><span class="comment">// ...</span></div>
<div class="ttc" id="agroup__ktx__glloader_html_gada67f60796793d1ed9eb1f3f2d61d4a6"><div class="ttname"><a href="group__ktx__glloader.html#gada67f60796793d1ed9eb1f3f2d61d4a6">ktxLoadOpenGL</a></div><div class="ttdeci">KTX_API KTX_error_code KTX_APIENTRY ktxLoadOpenGL(PFNGLGETPROCADDRESS pfnGLGetProcAddress)</div><div class="ttdoc">Load pointers for the GL functions used by the ktxTexture*_GLUpload functions.</div><div class="ttdef"><b>Definition</b> gl_funcs.c:216</div></div>
<div class="ttc" id="aktx_8h_html_aa823ce7b0db0aaefb942c4b5a07504be"><div class="ttname"><a href="ktx_8h.html#aa823ce7b0db0aaefb942c4b5a07504be">PFNGLGETPROCADDRESS</a></div><div class="ttdeci">PFNVOIDFUNCTION(KTX_APIENTRY * PFNGLGETPROCADDRESS)(const char *proc)</div><div class="ttdoc">typedef of pointer to function for retrieving OpenGL function pointers.</div><div class="ttdef"><b>Definition</b> ktx.h:936</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="createVulkan"></a>
Creating a Vulkan image object from a KTX file.</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;vulkan/vulkan.h&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;ktxvulkan.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture.html">ktxTexture</a>* kTexture;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_size_t offset;</div>
<div class="line">ktx_uint8_t* image;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line"><a class="code hl_class" href="structktxVulkanDeviceInfo.html">ktxVulkanDeviceInfo</a> vdi;</div>
<div class="line"><a class="code hl_class" href="structktxVulkanTexture.html">ktxVulkanTexture</a> texture;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Set up Vulkan physical device (gpu), logical device (device), queue</span></div>
<div class="line"><span class="comment">// and command pool. Save the handles to these in a struct called vkctx.</span></div>
<div class="line"><span class="comment">// ktx VulkanDeviceInfo is used to pass these with the expectation that</span></div>
<div class="line"><span class="comment">// apps are likely to upload a large number of textures.</span></div>
<div class="line">ktxVulkanDeviceInfo_Construct(&amp;vdi, vkctx.gpu, vkctx.device,</div>
<div class="line"> vkctx.queue, vkctx.commandPool, <span class="keyword">nullptr</span>);</div>
<div class="line"> </div>
<div class="line">ktxresult = ktxTexture_CreateFromNamedFile(<span class="stringliteral">&quot;mytex3d.ktx&quot;</span>,</div>
<div class="line"> KTX_TEXTURE_CREATE_NO_FLAGS,</div>
<div class="line"> &amp;kTexture);</div>
<div class="line"> </div>
<div class="line">ktxresult = ktxTexture_VkUploadEx(kTexture, &amp;vdi, &amp;texture,</div>
<div class="line"> VK_IMAGE_TILING_OPTIMAL,</div>
<div class="line"> VK_IMAGE_USAGE_SAMPLED_BIT,</div>
<div class="line"> VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);</div>
<div class="line"> </div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(kTexture);</div>
<div class="line">ktxVulkanDeviceInfo_Destruct(&amp;vdi);</div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line"><span class="comment">// Vulkan rendering using the texture</span></div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line"><span class="comment">// When done using the image in Vulkan...</span></div>
<div class="line">ktxVulkanTexture_Destruct(&amp;texture, vkctx.device, <span class="keyword">nullptr</span>);</div>
<div class="ttc" id="astructktxVulkanDeviceInfo_html"><div class="ttname"><a href="structktxVulkanDeviceInfo.html">ktxVulkanDeviceInfo</a></div><div class="ttdoc">Struct for passing information about the Vulkan device on which to create images to the texture image...</div><div class="ttdef"><b>Definition</b> ktxvulkan.h:188</div></div>
<div class="ttc" id="astructktxVulkanTexture_html"><div class="ttname"><a href="structktxVulkanTexture.html">ktxVulkanTexture</a></div><div class="ttdoc">Struct for returning information about the Vulkan texture image created by the ktxTexture_VkUpload* f...</div><div class="ttdef"><b>Definition</b> ktxvulkan.h:108</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="subsection"></a>
Extracting Metadata</h2>
<p>Once a <a class="el" href="structktxTexture.html" title="Base class representing a texture.">ktxTexture</a> object has been created, metadata can be easily found and extracted. The following can be added to any of the above.</p>
<div class="fragment"><div class="line"><span class="keywordtype">char</span>* pValue;</div>
<div class="line">uint32_t valueLen;</div>
<div class="line"><span class="keywordflow">if</span> (<a class="code hl_enumvalue" href="ktx_8h.html#a7780d97ec4de6aa30c4726fb71e3116cafdb7a07b23399df43e1ecf161963cf98">KTX_SUCCESS</a> == ktxHashList_FindValue(&amp;kTexture-&gt;<a class="code hl_variable" href="structktxTexture.html#a57141753cd2eb0967c9c071d853c5d32">kvDataHead</a>,</div>
<div class="line"> <a class="code hl_define" href="ktx_8h.html#a7eebf850576083e740cf1f418eed39a0">KTX_ORIENTATION_KEY</a>,</div>
<div class="line"> &amp;valueLen, (<span class="keywordtype">void</span>**)&amp;pValue))</div>
<div class="line"> {</div>
<div class="line"> <span class="keywordtype">char</span> s, t;</div>
<div class="line"> </div>
<div class="line"> <span class="keywordflow">if</span> (sscanf(pValue, <a class="code hl_define" href="ktx_8h.html#ad235113b0090e64ad23a0cf7097e1b7a">KTX_ORIENTATION2_FMT</a>, &amp;s, &amp;t) == 2) {</div>
<div class="line"> ...</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="ttc" id="aktx_8h_html_a7780d97ec4de6aa30c4726fb71e3116cafdb7a07b23399df43e1ecf161963cf98"><div class="ttname"><a href="ktx_8h.html#a7780d97ec4de6aa30c4726fb71e3116cafdb7a07b23399df43e1ecf161963cf98">KTX_SUCCESS</a></div><div class="ttdeci">@ KTX_SUCCESS</div><div class="ttdef"><b>Definition</b> ktx.h:170</div></div>
<div class="ttc" id="aktx_8h_html_a7eebf850576083e740cf1f418eed39a0"><div class="ttname"><a href="ktx_8h.html#a7eebf850576083e740cf1f418eed39a0">KTX_ORIENTATION_KEY</a></div><div class="ttdeci">#define KTX_ORIENTATION_KEY</div><div class="ttdoc">Key string for standard orientation metadata.</div><div class="ttdef"><b>Definition</b> ktx.h:124</div></div>
<div class="ttc" id="aktx_8h_html_ad235113b0090e64ad23a0cf7097e1b7a"><div class="ttname"><a href="ktx_8h.html#ad235113b0090e64ad23a0cf7097e1b7a">KTX_ORIENTATION2_FMT</a></div><div class="ttdeci">#define KTX_ORIENTATION2_FMT</div><div class="ttdoc">Standard KTX 1 format for 2D orientation value.</div><div class="ttdef"><b>Definition</b> ktx.h:149</div></div>
<div class="ttc" id="astructktxTexture_html_a57141753cd2eb0967c9c071d853c5d32"><div class="ttname"><a href="structktxTexture.html#a57141753cd2eb0967c9c071d853c5d32">ktxTexture::kvDataHead</a></div><div class="ttdeci">ktxHashList kvDataHead</div><div class="ttdoc">Head of the hash list of metadata.</div><div class="ttdef"><b>Definition</b> ktx.h:288</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="writektx"></a>
Writing a KTX or KTX2 file</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;vkformat_enum.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture2.html">ktxTexture2</a>* texture; <span class="comment">// For KTX2</span></div>
<div class="line"><span class="comment">//ktxTexture1* texture; // For KTX</span></div>
<div class="line"><a class="code hl_struct" href="structktxTextureCreateInfo.html">ktxTextureCreateInfo</a> createInfo;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line">FILE* src;</div>
<div class="line">ktx_size_t srcSize;</div>
<div class="line"> </div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a1318d73f800ff61d045b740331939596">glInternalformat</a> = GL_RGB8; <span class="comment">// Ignored if creating a ktxTexture2.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#abc50403eebde1f027704eadc05d304c7">vkFormat</a> = VK_FORMAT_R8G8B8_UNORM; <span class="comment">// Ignored if creating a ktxTexture1.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a> = 2048;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#afe7371a26104de3e131e82cf5cc39e9c">baseHeight</a> = 1024;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a71d7762f2b0dd61d57c0a7ec31ee46ac">baseDepth</a> = 16;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3c48573960eb90b1e38cc70457d2cda1">numDimensions</a> = 3.</div>
<div class="line"><span class="comment">// Note: it is not necessary to provide a full mipmap pyramid.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a782126a62c27ee8660a14565b906694c">numLevels</a> = log2(createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a>) + 1</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#ae1412e2bd82ef1baa7cb1479735d9c86">numLayers</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3a4bc2fa2e41bcec0bdb265505af0068">numFaces</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9b5ca8c2e3fd76d8b427928775289078">isArray</a> = KTX_FALSE;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9c26601222e6a037f7dbae7b61b18fd0">generateMipmaps</a> = KTX_FALSE;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Call ktxTexture1_Create to create a KTX texture.</span></div>
<div class="line">result = ktxTexture2_Create(&amp;createInfo,</div>
<div class="line"> <a class="code hl_enumvalue" href="ktx_8h.html#a2ab4b656d36abc318aed17a5f73c505c">KTX_TEXTURE_CREATE_ALLOC_STORAGE</a>,</div>
<div class="line"> &amp;texture);</div>
<div class="line"> </div>
<div class="line">src = <span class="comment">// Open a stdio FILE* on the baseLevel image, slice 0.</span></div>
<div class="line">srcSize = <span class="comment">// Query size of the file.</span></div>
<div class="line">level = 0;</div>
<div class="line">layer = 0;</div>
<div class="line">faceSlice = 0; </div>
<div class="line">result = <a class="code hl_define" href="ktx_8h.html#a11077712b020a97507c1e22a4c9c45b6">ktxTexture_SetImageFromMemory</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture),</div>
<div class="line"> level, layer, faceSlice,</div>
<div class="line"> src, srcSize);</div>
<div class="line"><span class="comment">// Repeat for the other 15 slices of the base level and all other levels</span></div>
<div class="line"><span class="comment">// up to createInfo.numLevels.</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a5a338703d7be18ef6cc97a83d5fad8fe">ktxTexture_WriteToNamedFile</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture), <span class="stringliteral">&quot;mytex3d.ktx&quot;</span>);</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture));</div>
<div class="ttc" id="aktx_8h_html_a11077712b020a97507c1e22a4c9c45b6"><div class="ttname"><a href="ktx_8h.html#a11077712b020a97507c1e22a4c9c45b6">ktxTexture_SetImageFromMemory</a></div><div class="ttdeci">#define ktxTexture_SetImageFromMemory(This, level, layer, faceSlice, src, srcSize)</div><div class="ttdoc">Helper for calling the SetImageFromMemory virtual method of a ktxTexture.</div><div class="ttdef"><b>Definition</b> ktx.h:609</div></div>
<div class="ttc" id="aktx_8h_html_a2ab4b656d36abc318aed17a5f73c505c"><div class="ttname"><a href="ktx_8h.html#a2ab4b656d36abc318aed17a5f73c505c">KTX_TEXTURE_CREATE_ALLOC_STORAGE</a></div><div class="ttdeci">@ KTX_TEXTURE_CREATE_ALLOC_STORAGE</div><div class="ttdef"><b>Definition</b> ktx.h:782</div></div>
<div class="ttc" id="aktx_8h_html_a5a338703d7be18ef6cc97a83d5fad8fe"><div class="ttname"><a href="ktx_8h.html#a5a338703d7be18ef6cc97a83d5fad8fe">ktxTexture_WriteToNamedFile</a></div><div class="ttdeci">#define ktxTexture_WriteToNamedFile(This, dstname)</div><div class="ttdoc">Helper for calling the WriteToNamedfile virtual method of a ktxTexture.</div><div class="ttdef"><b>Definition</b> ktx.h:639</div></div>
<div class="ttc" id="astructktxTexture2_html"><div class="ttname"><a href="structktxTexture2.html">ktxTexture2</a></div><div class="ttdoc">Class representing a KTX version 2 format texture.</div><div class="ttdef"><b>Definition</b> ktx.h:706</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html"><div class="ttname"><a href="structktxTextureCreateInfo.html">ktxTextureCreateInfo</a></div><div class="ttdoc">Structure for passing texture information to ktxTexture1_Create() and ktxTexture2_Create().</div><div class="ttdef"><b>Definition</b> ktx.h:747</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a1318d73f800ff61d045b740331939596"><div class="ttname"><a href="structktxTextureCreateInfo.html#a1318d73f800ff61d045b740331939596">ktxTextureCreateInfo::glInternalformat</a></div><div class="ttdeci">ktx_uint32_t glInternalformat</div><div class="ttdef"><b>Definition</b> ktx.h:748</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a3a4bc2fa2e41bcec0bdb265505af0068"><div class="ttname"><a href="structktxTextureCreateInfo.html#a3a4bc2fa2e41bcec0bdb265505af0068">ktxTextureCreateInfo::numFaces</a></div><div class="ttdeci">ktx_uint32_t numFaces</div><div class="ttdef"><b>Definition</b> ktx.h:764</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a3c48573960eb90b1e38cc70457d2cda1"><div class="ttname"><a href="structktxTextureCreateInfo.html#a3c48573960eb90b1e38cc70457d2cda1">ktxTextureCreateInfo::numDimensions</a></div><div class="ttdeci">ktx_uint32_t numDimensions</div><div class="ttdef"><b>Definition</b> ktx.h:759</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a3fa51cc9001702e3f1d5a69cee65adf8"><div class="ttname"><a href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">ktxTextureCreateInfo::baseWidth</a></div><div class="ttdeci">ktx_uint32_t baseWidth</div><div class="ttdef"><b>Definition</b> ktx.h:756</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a71d7762f2b0dd61d57c0a7ec31ee46ac"><div class="ttname"><a href="structktxTextureCreateInfo.html#a71d7762f2b0dd61d57c0a7ec31ee46ac">ktxTextureCreateInfo::baseDepth</a></div><div class="ttdeci">ktx_uint32_t baseDepth</div><div class="ttdef"><b>Definition</b> ktx.h:758</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a782126a62c27ee8660a14565b906694c"><div class="ttname"><a href="structktxTextureCreateInfo.html#a782126a62c27ee8660a14565b906694c">ktxTextureCreateInfo::numLevels</a></div><div class="ttdeci">ktx_uint32_t numLevels</div><div class="ttdef"><b>Definition</b> ktx.h:761</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a9b5ca8c2e3fd76d8b427928775289078"><div class="ttname"><a href="structktxTextureCreateInfo.html#a9b5ca8c2e3fd76d8b427928775289078">ktxTextureCreateInfo::isArray</a></div><div class="ttdeci">ktx_bool_t isArray</div><div class="ttdef"><b>Definition</b> ktx.h:765</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_a9c26601222e6a037f7dbae7b61b18fd0"><div class="ttname"><a href="structktxTextureCreateInfo.html#a9c26601222e6a037f7dbae7b61b18fd0">ktxTextureCreateInfo::generateMipmaps</a></div><div class="ttdeci">ktx_bool_t generateMipmaps</div><div class="ttdef"><b>Definition</b> ktx.h:768</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_abc50403eebde1f027704eadc05d304c7"><div class="ttname"><a href="structktxTextureCreateInfo.html#abc50403eebde1f027704eadc05d304c7">ktxTextureCreateInfo::vkFormat</a></div><div class="ttdeci">ktx_uint32_t vkFormat</div><div class="ttdef"><b>Definition</b> ktx.h:751</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_ae1412e2bd82ef1baa7cb1479735d9c86"><div class="ttname"><a href="structktxTextureCreateInfo.html#ae1412e2bd82ef1baa7cb1479735d9c86">ktxTextureCreateInfo::numLayers</a></div><div class="ttdeci">ktx_uint32_t numLayers</div><div class="ttdef"><b>Definition</b> ktx.h:763</div></div>
<div class="ttc" id="astructktxTextureCreateInfo_html_afe7371a26104de3e131e82cf5cc39e9c"><div class="ttname"><a href="structktxTextureCreateInfo.html#afe7371a26104de3e131e82cf5cc39e9c">ktxTextureCreateInfo::baseHeight</a></div><div class="ttdeci">ktx_uint32_t baseHeight</div><div class="ttdef"><b>Definition</b> ktx.h:757</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="modifyktx"></a>
Modifying a KTX file</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture.html">ktxTexture</a>* texture;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_size_t offset;</div>
<div class="line">ktx_uint8_t* image;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture_CreateFromNamedFile(<span class="stringliteral">&quot;mytex3d.ktx&quot;</span>,</div>
<div class="line"> <a class="code hl_enumvalue" href="ktx_8h.html#a5d741f48293002f70546881d2394b6f6">KTX_TEXTURE_CREATE_LOAD_IMAGE_DATA_BIT</a>,</div>
<div class="line"> &amp;texture);</div>
<div class="line"><span class="comment">// The file is closed after all the data has been read.</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// It is the responsibilty of the application to make sure its</span></div>
<div class="line"><span class="comment">// modifications are valid.</span></div>
<div class="line">texture-&gt;<a class="code hl_variable" href="structktxTexture.html#a9c26601222e6a037f7dbae7b61b18fd0">generateMipmaps</a> = KTX_TRUE;</div>
<div class="line"> </div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a5a338703d7be18ef6cc97a83d5fad8fe">ktxTexture_WriteToNamedFile</a>(texture, <span class="stringliteral">&quot;mytex3d.ktx&quot;</span>);</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(texture);</div>
<div class="ttc" id="astructktxTexture_html_a9c26601222e6a037f7dbae7b61b18fd0"><div class="ttname"><a href="structktxTexture.html#a9c26601222e6a037f7dbae7b61b18fd0">ktxTexture::generateMipmaps</a></div><div class="ttdeci">ktx_bool_t generateMipmaps</div><div class="ttdef"><b>Definition</b> ktx.h:288</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="autotoc_md0"></a>
Writing a Basis-compressed Universal Texture</h2>
<p>Basis compression supports two universal texture formats: <em>BasisLZ/ETC1S</em> and <em>UASTC</em>. The latter gives higher quality at a larger file size. Textures can be compressed to either format using <span class="tt">ktxTexture2_CompressBasisEx</span> as shown in this example.</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;vkformat_enum.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture2.html">ktxTexture2</a>* texture;</div>
<div class="line"><a class="code hl_struct" href="structktxTextureCreateInfo.html">ktxTextureCreateInfo</a> createInfo;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line">FILE* src;</div>
<div class="line">ktx_size_t srcSize;</div>
<div class="line"><a class="code hl_struct" href="structktxBasisParams.html">ktxBasisParams</a> params = {0};</div>
<div class="line">params.<a class="code hl_variable" href="structktxBasisParams.html#a51fe881fb2eae346ba017f7f55a1d642">structSize</a> = <span class="keyword">sizeof</span>(params);</div>
<div class="line"> </div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a1318d73f800ff61d045b740331939596">glInternalformat</a> = 0; <span class="comment">//Ignored as we&#39;ll create a KTX2 texture.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#abc50403eebde1f027704eadc05d304c7">vkFormat</a> = VK_FORMAT_R8G8B8A8_UNORM;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a> = 2048;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#afe7371a26104de3e131e82cf5cc39e9c">baseHeight</a> = 1024;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a71d7762f2b0dd61d57c0a7ec31ee46ac">baseDepth</a> = 16;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3c48573960eb90b1e38cc70457d2cda1">numDimensions</a> = 3.</div>
<div class="line"><span class="comment">// Note: it is not necessary to provide a full mipmap pyramid.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a782126a62c27ee8660a14565b906694c">numLevels</a> = log2(createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a>) + 1</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#ae1412e2bd82ef1baa7cb1479735d9c86">numLayers</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3a4bc2fa2e41bcec0bdb265505af0068">numFaces</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9b5ca8c2e3fd76d8b427928775289078">isArray</a> = KTX_FALSE;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9c26601222e6a037f7dbae7b61b18fd0">generateMipmaps</a> = KTX_FALSE;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture2_Create(&amp;createInfo,</div>
<div class="line"> <a class="code hl_enumvalue" href="ktx_8h.html#a2ab4b656d36abc318aed17a5f73c505c">KTX_TEXTURE_CREATE_ALLOC_STORAGE</a>,</div>
<div class="line"> &amp;texture);</div>
<div class="line"> </div>
<div class="line">src = <span class="comment">// Open the file for the baseLevel image, slice 0 and</span></div>
<div class="line"> <span class="comment">// read it into memory.</span></div>
<div class="line">srcSize = <span class="comment">// Query size of the file.</span></div>
<div class="line">level = 0;</div>
<div class="line">layer = 0;</div>
<div class="line">faceSlice = 0; </div>
<div class="line">result = <a class="code hl_define" href="ktx_8h.html#a11077712b020a97507c1e22a4c9c45b6">ktxTexture_SetImageFromMemory</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture),</div>
<div class="line"> level, layer, faceSlice,</div>
<div class="line"> src, srcSize);</div>
<div class="line"><span class="comment">// Repeat for the other 15 slices of the base level and all other levels</span></div>
<div class="line"><span class="comment">// up to createInfo.numLevels.</span></div>
<div class="line"> </div>
<div class="line"><span class="comment">// For BasisLZ/ETC1S</span></div>
<div class="line">params.<a class="code hl_variable" href="structktxBasisParams.html#a27652d35542830750e195ab57dd1f3b1">compressionLevel</a> = KTX_ETC1S_DEFAULT_COMPRESSION_LEVEL;</div>
<div class="line"><span class="comment">// For UASTC</span></div>
<div class="line">params.<a class="code hl_variable" href="structktxBasisParams.html#ac9363a20b43cebc11ab690aec5fbd38d">uastc</a> = KTX_TRUE;</div>
<div class="line"><span class="comment">// Set other BasisLZ/ETC1S or UASTC params to change default quality settings.</span></div>
<div class="line">result = ktxtexture2_CompressBasisEx(texture, &amp;params);</div>
<div class="line"> </div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a5a338703d7be18ef6cc97a83d5fad8fe">ktxTexture_WriteToNamedFile</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture), <span class="stringliteral">&quot;mytex3d.ktx2&quot;</span>);</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture));</div>
<div class="ttc" id="astructktxBasisParams_html"><div class="ttname"><a href="structktxBasisParams.html">ktxBasisParams</a></div><div class="ttdoc">Structure for passing extended parameters to ktxTexture2_CompressBasisEx().</div><div class="ttdef"><b>Definition</b> ktx.h:1379</div></div>
<div class="ttc" id="astructktxBasisParams_html_a27652d35542830750e195ab57dd1f3b1"><div class="ttname"><a href="structktxBasisParams.html#a27652d35542830750e195ab57dd1f3b1">ktxBasisParams::compressionLevel</a></div><div class="ttdeci">ktx_uint32_t compressionLevel</div><div class="ttdef"><b>Definition</b> ktx.h:1398</div></div>
<div class="ttc" id="astructktxBasisParams_html_a51fe881fb2eae346ba017f7f55a1d642"><div class="ttname"><a href="structktxBasisParams.html#a51fe881fb2eae346ba017f7f55a1d642">ktxBasisParams::structSize</a></div><div class="ttdeci">ktx_uint32_t structSize</div><div class="ttdef"><b>Definition</b> ktx.h:1380</div></div>
<div class="ttc" id="astructktxBasisParams_html_ac9363a20b43cebc11ab690aec5fbd38d"><div class="ttname"><a href="structktxBasisParams.html#ac9363a20b43cebc11ab690aec5fbd38d">ktxBasisParams::uastc</a></div><div class="ttdeci">ktx_bool_t uastc</div><div class="ttdef"><b>Definition</b> ktx.h:1384</div></div>
</div><!-- fragment --><p>There is a shortcut that can be used when compressing to BasisLZ/ETC1S. Remove the declaration and initialization of <span class="tt">params</span> in the previous example and replace <span class="tt">ktxtexture2_CompressBasisEx</span> with</p>
<div class="fragment"><div class="line"><span class="comment">// Quality range is 1 - 255. 0 gets the default quality, currently 128.</span></div>
<div class="line"><span class="comment">// The qualityLevel field in ktxBasisParams is set from this.</span></div>
<div class="line"><span class="keywordtype">int</span> quality = 0;</div>
<div class="line">result = ktxTexture2_CompressBasis(texture, quality);</div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="autotoc_md1"></a>
Transcoding a BasisLZ/ETC1S or UASTC-compressed Texture</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture2.html">ktxTexture2</a>* texture;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture_CreateFromNamedFile(<span class="stringliteral">&quot;mytex3d_basis.ktx2&quot;</span>,</div>
<div class="line"> KTX_TEXTURE_CREATE_NO_FLAGS,</div>
<div class="line"> (<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>**)&amp;kTexture);</div>
<div class="line"><span class="comment">// or</span></div>
<div class="line"><span class="comment">//result = ktxTexture2_CreateFromNamedFile(&quot;mytex3d_basis.ktx2&quot;,</span></div>
<div class="line"><span class="comment">// KTX_TEXTURE_CREATE_NO_FLAGS,</span></div>
<div class="line"><span class="comment">// &amp;kTexture);</span></div>
<div class="line"> </div>
<div class="line"><span class="keywordflow">if</span> (ktxTexture2_NeedsTranscoding(texture)) {</div>
<div class="line"> ktx_texture_transcode_fmt_e tf;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Using VkGetPhysicalDeviceFeatures or GL_COMPRESSED_TEXTURE_FORMATS or</span></div>
<div class="line"> <span class="comment">// extension queries, determine what compressed texture formats are</span></div>
<div class="line"> <span class="comment">// supported and pick a format. For example</span></div>
<div class="line"> vk::PhysicalDeviceFeatures deviceFeatures;</div>
<div class="line"> vkctx.gpu.getFeatures(&amp;deviceFeatures);</div>
<div class="line"> khr_df_model_e colorModel = ktxTexture2_GetColorModel_e(texture);</div>
<div class="line"> <span class="keywordflow">if</span> (colorModel == KHR_DF_MODEL_UASTC</div>
<div class="line"> &amp;&amp; deviceFeatures.textureCompressionASTC_LDR) {</div>
<div class="line"> tf = <a class="code hl_enumvalue" href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a26ee2ca9dbc9384ded1c41c59a8bc3b6">KTX_TTF_ASTC_4x4_RGBA</a>;</div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (colorModel == KHR_DF_MODEL_ETC1S</div>
<div class="line"> &amp;&amp; deviceFeatures.textureCompressionETC2) {</div>
<div class="line"> tf = <a class="code hl_enumvalue" href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5ad5caffd2fe438bbac51f2e314a3dd7c3">KTX_TTF_ETC</a>;</div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (deviceFeatures.textureCompressionASTC_LDR) {</div>
<div class="line"> tf = <a class="code hl_enumvalue" href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a26ee2ca9dbc9384ded1c41c59a8bc3b6">KTX_TTF_ASTC_4x4_RGBA</a>;</div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (deviceFeatures.textureCompressionETC2)</div>
<div class="line"> tf = <a class="code hl_enumvalue" href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a665baafd3c1d246bf2726342a083a26b">KTX_TTF_ETC2_RGBA</a>;</div>
<div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> (deviceFeatures.textureCompressionBC)</div>
<div class="line"> tf = <a class="code hl_enumvalue" href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a352f7aeb953d220e0fa4abc025a6f880">KTX_TTF_BC3_RGBA</a>;</div>
<div class="line"> <span class="keywordflow">else</span> {</div>
<div class="line"> message &lt;&lt; <span class="stringliteral">&quot;Vulkan implementation does not support any available transcode target.&quot;</span>;</div>
<div class="line"> <span class="keywordflow">throw</span> std::runtime_error(message.str());</div>
<div class="line"> }</div>
<div class="line"> </div>
<div class="line"> result = ktxTexture2_TranscodeBasis(texture, tf, 0);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">// Then use VkUpload or GLUpload to create a texture object on the GPU.</span></div>
<div class="line">}</div>
<div class="ttc" id="aktx_8h_html_a30cc58c576392303d9a5a54b57ef29b5a26ee2ca9dbc9384ded1c41c59a8bc3b6"><div class="ttname"><a href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a26ee2ca9dbc9384ded1c41c59a8bc3b6">KTX_TTF_ASTC_4x4_RGBA</a></div><div class="ttdeci">@ KTX_TTF_ASTC_4x4_RGBA</div><div class="ttdef"><b>Definition</b> ktx.h:1593</div></div>
<div class="ttc" id="aktx_8h_html_a30cc58c576392303d9a5a54b57ef29b5a352f7aeb953d220e0fa4abc025a6f880"><div class="ttname"><a href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a352f7aeb953d220e0fa4abc025a6f880">KTX_TTF_BC3_RGBA</a></div><div class="ttdeci">@ KTX_TTF_BC3_RGBA</div><div class="ttdef"><b>Definition</b> ktx.h:1565</div></div>
<div class="ttc" id="aktx_8h_html_a30cc58c576392303d9a5a54b57ef29b5a665baafd3c1d246bf2726342a083a26b"><div class="ttname"><a href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5a665baafd3c1d246bf2726342a083a26b">KTX_TTF_ETC2_RGBA</a></div><div class="ttdeci">@ KTX_TTF_ETC2_RGBA</div><div class="ttdef"><b>Definition</b> ktx.h:1555</div></div>
<div class="ttc" id="aktx_8h_html_a30cc58c576392303d9a5a54b57ef29b5ad5caffd2fe438bbac51f2e314a3dd7c3"><div class="ttname"><a href="ktx_8h.html#a30cc58c576392303d9a5a54b57ef29b5ad5caffd2fe438bbac51f2e314a3dd7c3">KTX_TTF_ETC</a></div><div class="ttdeci">@ KTX_TTF_ETC</div><div class="ttdef"><b>Definition</b> ktx.h:1637</div></div>
</div><!-- fragment --><h2 class="doxsection"><a class="anchor" id="autotoc_md2"></a>
Writing an ASTC-Compressed Texture</h2>
<div class="fragment"><div class="line"><span class="preprocessor">#include &lt;<a class="code" href="ktx_8h.html">ktx.h</a>&gt;</span></div>
<div class="line"><span class="preprocessor">#include &lt;vkformat_enum.h&gt;</span></div>
<div class="line"> </div>
<div class="line"><a class="code hl_class" href="structktxTexture2.html">ktxTexture2</a>* texture;</div>
<div class="line"><a class="code hl_struct" href="structktxTextureCreateInfo.html">ktxTextureCreateInfo</a> createInfo;</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#ad2efa40e38ebae48371375db92d34eaa">KTX_error_code</a> result;</div>
<div class="line">ktx_uint32_t level, layer, faceSlice;</div>
<div class="line">FILE* src;</div>
<div class="line">ktx_size_t srcSize;</div>
<div class="line"><a class="code hl_struct" href="structktxAstcParams.html">ktxAstcParams</a> params = {0};</div>
<div class="line">params.<a class="code hl_variable" href="structktxAstcParams.html#a51fe881fb2eae346ba017f7f55a1d642">structSize</a> = <span class="keyword">sizeof</span>(params);</div>
<div class="line"> </div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a1318d73f800ff61d045b740331939596">glInternalformat</a> = 0; <span class="comment">//Ignored as we&#39;ll create a KTX2 texture.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#abc50403eebde1f027704eadc05d304c7">vkFormat</a> = VK_FORMAT_R8G8B8A8_UNORM;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a> = 2048;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#afe7371a26104de3e131e82cf5cc39e9c">baseHeight</a> = 1024;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a71d7762f2b0dd61d57c0a7ec31ee46ac">baseDepth</a> = 16;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3c48573960eb90b1e38cc70457d2cda1">numDimensions</a> = 3.</div>
<div class="line"><span class="comment">// Note: it is not necessary to provide a full mipmap pyramid.</span></div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a782126a62c27ee8660a14565b906694c">numLevels</a> = log2(createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3fa51cc9001702e3f1d5a69cee65adf8">baseWidth</a>) + 1</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#ae1412e2bd82ef1baa7cb1479735d9c86">numLayers</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a3a4bc2fa2e41bcec0bdb265505af0068">numFaces</a> = 1;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9b5ca8c2e3fd76d8b427928775289078">isArray</a> = KTX_FALSE;</div>
<div class="line">createInfo.<a class="code hl_variable" href="structktxTextureCreateInfo.html#a9c26601222e6a037f7dbae7b61b18fd0">generateMipmaps</a> = KTX_FALSE;</div>
<div class="line"> </div>
<div class="line">result = ktxTexture2_Create(&amp;createInfo,</div>
<div class="line"> <a class="code hl_enumvalue" href="ktx_8h.html#a2ab4b656d36abc318aed17a5f73c505c">KTX_TEXTURE_CREATE_ALLOC_STORAGE</a>,</div>
<div class="line"> &amp;texture);</div>
<div class="line"> </div>
<div class="line">src = <span class="comment">// Open the file for the baseLevel image, slice 0 and</span></div>
<div class="line"> <span class="comment">// read it into memory.</span></div>
<div class="line">srcSize = <span class="comment">// Query size of the file.</span></div>
<div class="line">level = 0;</div>
<div class="line">layer = 0;</div>
<div class="line">faceSlice = 0; </div>
<div class="line">result = <a class="code hl_define" href="ktx_8h.html#a11077712b020a97507c1e22a4c9c45b6">ktxTexture_SetImageFromMemory</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture),</div>
<div class="line"> level, layer, faceSlice,</div>
<div class="line"> src, srcSize);</div>
<div class="line"><span class="comment">// Repeat for the other 15 slices of the base level and all other levels</span></div>
<div class="line"><span class="comment">// up to createInfo.numLevels.</span></div>
<div class="line"> </div>
<div class="line">params.<a class="code hl_variable" href="structktxAstcParams.html#a04aa92e2192b36b2d9701d23fd246386">threadCount</a> = 1;</div>
<div class="line">params.<a class="code hl_variable" href="structktxAstcParams.html#a7a2b8fd2f04b2990c176606e45a02c22">blockDimension</a> = KTX_PACK_ASTC_BLOCK_DIMENSION_6x6;</div>
<div class="line">params.<a class="code hl_variable" href="structktxAstcParams.html#aa02c398f7c7872860347560f4a33fd57">mode</a> = <a class="code hl_enumvalue" href="ktx_8h.html#ad9ebeed57afd9e14b6d857011cff38d6a6971976df75bdc5aa7099b59ad345361">KTX_PACK_ASTC_ENCODER_MODE_LDR</a>;</div>
<div class="line">params.<a class="code hl_variable" href="structktxAstcParams.html#aac5068885c586a1454efbf2e9cf4b3ed">qualityLevel</a> = <a class="code hl_enumvalue" href="ktx_8h.html#a8f70163f537a794c472479bc5c1905e9a17832137be7a8ff0b839fd41e1abb923">KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM</a>;</div>
<div class="line">result = ktxtexture2_CompressAstcEx(texture, &amp;params);</div>
<div class="line"> </div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a5a338703d7be18ef6cc97a83d5fad8fe">ktxTexture_WriteToNamedFile</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture), <span class="stringliteral">&quot;mytex3d.ktx2&quot;</span>);</div>
<div class="line"><a class="code hl_define" href="ktx_8h.html#a0becd37ccf729eed8723b969bb93df3d">ktxTexture_Destroy</a>(<a class="code hl_class" href="structktxTexture.html">ktxTexture</a>(texture));</div>
<div class="ttc" id="aktx_8h_html_a8f70163f537a794c472479bc5c1905e9a17832137be7a8ff0b839fd41e1abb923"><div class="ttname"><a href="ktx_8h.html#a8f70163f537a794c472479bc5c1905e9a17832137be7a8ff0b839fd41e1abb923">KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM</a></div><div class="ttdeci">@ KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM</div><div class="ttdef"><b>Definition</b> ktx.h:1230</div></div>
<div class="ttc" id="aktx_8h_html_ad9ebeed57afd9e14b6d857011cff38d6a6971976df75bdc5aa7099b59ad345361"><div class="ttname"><a href="ktx_8h.html#ad9ebeed57afd9e14b6d857011cff38d6a6971976df75bdc5aa7099b59ad345361">KTX_PACK_ASTC_ENCODER_MODE_LDR</a></div><div class="ttdeci">@ KTX_PACK_ASTC_ENCODER_MODE_LDR</div><div class="ttdef"><b>Definition</b> ktx.h:1282</div></div>
<div class="ttc" id="astructktxAstcParams_html"><div class="ttname"><a href="structktxAstcParams.html">ktxAstcParams</a></div><div class="ttdoc">Structure for passing extended parameters to ktxTexture_CompressAstc.</div><div class="ttdef"><b>Definition</b> ktx.h:1302</div></div>
<div class="ttc" id="astructktxAstcParams_html_a04aa92e2192b36b2d9701d23fd246386"><div class="ttname"><a href="structktxAstcParams.html#a04aa92e2192b36b2d9701d23fd246386">ktxAstcParams::threadCount</a></div><div class="ttdeci">ktx_uint32_t threadCount</div><div class="ttdef"><b>Definition</b> ktx.h:1313</div></div>
<div class="ttc" id="astructktxAstcParams_html_a51fe881fb2eae346ba017f7f55a1d642"><div class="ttname"><a href="structktxAstcParams.html#a51fe881fb2eae346ba017f7f55a1d642">ktxAstcParams::structSize</a></div><div class="ttdeci">ktx_uint32_t structSize</div><div class="ttdef"><b>Definition</b> ktx.h:1303</div></div>
<div class="ttc" id="astructktxAstcParams_html_a7a2b8fd2f04b2990c176606e45a02c22"><div class="ttname"><a href="structktxAstcParams.html#a7a2b8fd2f04b2990c176606e45a02c22">ktxAstcParams::blockDimension</a></div><div class="ttdeci">ktx_uint32_t blockDimension</div><div class="ttdef"><b>Definition</b> ktx.h:1318</div></div>
<div class="ttc" id="astructktxAstcParams_html_aa02c398f7c7872860347560f4a33fd57"><div class="ttname"><a href="structktxAstcParams.html#aa02c398f7c7872860347560f4a33fd57">ktxAstcParams::mode</a></div><div class="ttdeci">ktx_uint32_t mode</div><div class="ttdef"><b>Definition</b> ktx.h:1323</div></div>
<div class="ttc" id="astructktxAstcParams_html_aac5068885c586a1454efbf2e9cf4b3ed"><div class="ttname"><a href="structktxAstcParams.html#aac5068885c586a1454efbf2e9cf4b3ed">ktxAstcParams::qualityLevel</a></div><div class="ttdeci">ktx_uint32_t qualityLevel</div><div class="ttdef"><b>Definition</b> ktx.h:1327</div></div>
</div><!-- fragment --><p>There is a shortcut that can be used when the only <span class="tt">params</span> field you want to modify is the <span class="tt">qualityLevel</span>. Remove the declaration and initialization of <span class="tt">params</span> in the previous example and replace <span class="tt">ktxtexture2_CompressAstcEx</span> with</p>
<div class="fragment"><div class="line"><span class="comment">// Quality range is 0 - 100. 0 is fastest/lowest. 100 is slowest/highest.</span></div>
<div class="line"><span class="keywordtype">int</span> quality = <a class="code hl_enumvalue" href="ktx_8h.html#a8f70163f537a794c472479bc5c1905e9a17832137be7a8ff0b839fd41e1abb923">KTX_PACK_ASTC_QUALITY_LEVEL_MEDIUM</a>;</div>
<div class="line">result = ktxTexture2_CompressAstc(texture, quality);</div>
</div><!-- fragment --> </div></div><!-- PageDoc -->
<a href="doxygen_crawl.html"></a>
</div><!-- contents -->
</div><!-- doc-content -->
</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 libktx 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 View Git Blame Copy Permalink