bgfx/tools.html
Бранимир Караџић fa06a36a6c Updated docs.
2022-07-16 09:47:16 -07:00

554 lines
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tools &mdash; bgfx 1.115.8127 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Internals" href="internals.html" />
<link rel="prev" title="API Reference" href="bgfx.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home" alt="Documentation Home"> bgfx
</a>
<div class="version">
1.115.8127
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="build.html">Building</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="bgfx.html">API Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Tools</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#geometry-compiler-geometryc">Geometry Compiler (geometryc)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#geometry-viewer-geometryv">Geometry Viewer (geometryv)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#shader-compiler-shaderc">Shader Compiler (shaderc)</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#building-shaders">Building shaders</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#texture-compiler-texturec">Texture Compiler (texturec)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#texture-viewer-texturev">Texture Viewer (texturev)</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="internals.html">Internals</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">bgfx</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> &raquo;</li>
<li>Tools</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="tools">
<h1>Tools<a class="headerlink" href="#tools" title="Permalink to this headline"></a></h1>
<div class="section" id="geometry-compiler-geometryc">
<h2>Geometry Compiler (geometryc)<a class="headerlink" href="#geometry-compiler-geometryc" title="Permalink to this headline"></a></h2>
<p>Converts Wavefront .obj, or glTF 2.0 mesh files to a format which is optimized for use with bgfx.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">geometryc</span> <span class="o">-</span><span class="n">f</span> <span class="o">&lt;</span><span class="ow">in</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">o</span> <span class="o">&lt;</span><span class="n">out</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>Supported input file formats:</p>
<blockquote>
<div><table class="docutils align-default">
<colgroup>
<col style="width: 18%" />
<col style="width: 82%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Format</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>.obj</p></td>
<td><p>Wavefront</p></td>
</tr>
<tr class="row-odd"><td><p>.gltf</p></td>
<td><p>glTF 2.0</p></td>
</tr>
<tr class="row-even"><td><p>.glb</p></td>
<td><p>glTF 2.0</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Options:</p>
<blockquote>
<div><dl class="option-list">
<dt><kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></dt>
<dd><p>Display this help and exit.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Output version information and exit.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Inputs file path.</p>
</dd>
<dt><kbd><span class="option">-o <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Outputs file path.</p>
</dd>
<dt><kbd><span class="option">-s</span>, <span class="option">--scale <var>&lt;num&gt;</var></span></kbd></dt>
<dd><p>Scale factor.</p>
</dd>
<dt><kbd><span class="option">--ccw</span></kbd></dt>
<dd><p>Front face is counter-clockwise winding order.</p>
</dd>
<dt><kbd><span class="option">--flipv</span></kbd></dt>
<dd><p>Flip texture coordinate V.</p>
</dd>
<dt><kbd><span class="option">--obb <var>&lt;num&gt;</var></span></kbd></dt>
<dd><p>Number of steps for calculating oriented bounding box.</p>
<p>Defaults to 17.</p>
<p>Less steps = less precise OBB.</p>
<p>More steps = slower calculation.</p>
</dd>
<dt><kbd><span class="option">--packnormal <var>&lt;num&gt;</var></span></kbd></dt>
<dd><p>Normal packing.
0 - unpacked 12 bytes. (Default)
1 - packed 4 bytes.</p>
</dd>
<dt><kbd><span class="option">--packuv <var>&lt;num&gt;</var></span></kbd></dt>
<dd><p>Texture coordinate packing.
0 - unpacked 8 bytes. (Default)
1 - packed 4 bytes.</p>
</dd>
<dt><kbd><span class="option">--tangent</span></kbd></dt>
<dd><p>Calculate tangent vectors. (Packing mode is the same as normal)</p>
</dd>
<dt><kbd><span class="option">--barycentric</span></kbd></dt>
<dd><p>Adds barycentric vertex attribute. (Packed in bgfx::Attrib::Color1)</p>
</dd>
<dt><kbd><span class="option">-c</span>, <span class="option">--compress</span></kbd></dt>
<dd><p>Compress indices.
[l/r]h-up+[y/z] Coordinate system. Defaults to lh-up+y — Left-Handed +Y is up.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="geometry-viewer-geometryv">
<h2>Geometry Viewer (geometryv)<a class="headerlink" href="#geometry-viewer-geometryv" title="Permalink to this headline"></a></h2>
<p>A geometry viewer.</p>
</div>
<div class="section" id="shader-compiler-shaderc">
<h2>Shader Compiler (shaderc)<a class="headerlink" href="#shader-compiler-shaderc" title="Permalink to this headline"></a></h2>
<p>Shader Compiler is used to compile bgfxs cross-platform shader language, which based on GLSL.
It uses an ANSI C pre-processor to transform the GLSL-like language into HLSL.
This method has certain drawbacks,
but overall its simple and allows for quick authoring of cross-platform shaders.</p>
<p>Some differences between bgfxs shaderc flavor of GLSL and vanilla GLSL:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">bool/int</span></code> uniforms are not allowed; all uniforms must be <code class="docutils literal notranslate"><span class="pre">float</span></code>.</p></li>
<li><p>Attributes and varyings can only be accessed from <code class="docutils literal notranslate"><span class="pre">main()</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SAMPLER2D/3D/CUBE/etc.</span></code> macros replace the <code class="docutils literal notranslate"><span class="pre">sampler2D/3D/Cube/etc.</span></code> tokens.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">vec2/3/4_splat(&lt;value&gt;)</span></code> replaces the <code class="docutils literal notranslate"><span class="pre">vec2/3/4(&lt;value&gt;)</span></code> constructor.
<code class="docutils literal notranslate"><span class="pre">vec2/3/4</span></code> constructors with multiple values are still valid.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mtxFromCols/mtxFromRows</span></code> must be used for constructing matrices.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mul(x,</span> <span class="pre">y)</span></code> must be used when multiplying vectors with matrices.</p></li>
<li><p>A <code class="docutils literal notranslate"><span class="pre">varying.def.sc</span></code> file must be used to define input/output semantics and types,
instead of using <code class="docutils literal notranslate"><span class="pre">attribute/in</span></code> and <code class="docutils literal notranslate"><span class="pre">varying/in/out</span></code>.
This file cannot include comments, and typically only one is necessary.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$input/$output</span></code> tokens corresponding to inputs and outputs defined in
<code class="docutils literal notranslate"><span class="pre">varying.def.sc</span></code> must be used at the beginning of shader.</p></li>
</ul>
<p>For more info, see the <a class="reference external" href="https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh">shader helper macros</a>.</p>
<p>Options:</p>
<blockquote>
<div><dl class="option-list">
<dt><kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></dt>
<dd><p>Display this help and exit.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Output version information and exit.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Inputs file path.</p>
</dd>
<dt><kbd><span class="option">-i <var>&lt;include path&gt;</var></span></kbd></dt>
<dd><p>Include path. (for multiple paths use -i multiple times)</p>
</dd>
<dt><kbd><span class="option">-o <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Outputs file path.</p>
</dd>
<dt><kbd><span class="option">--bin2c <var>&lt;array name&gt;</var></span></kbd></dt>
<dd><p>Generate C header file. If array name is not specified base file name will be used as name.</p>
</dd>
<dt><kbd><span class="option">--depends</span></kbd></dt>
<dd><p>Generate makefile style depends file.</p>
</dd>
<dt><kbd><span class="option">--platform <var>&lt;platform&gt;</var></span></kbd></dt>
<dd><p>Target platform.</p>
</dd>
<dt><kbd><span class="option">-p</span>, <span class="option">--profile <var>&lt;profile&gt;</var></span></kbd></dt>
<dd><p>Shader model.</p>
<p>Defaults to GLSL.</p>
</dd>
<dt><kbd><span class="option">--preprocess</span></kbd></dt>
<dd><p>Only pre-process.</p>
</dd>
<dt><kbd><span class="option">--define <var>&lt;defines&gt;</var></span></kbd></dt>
<dd><p>Add defines to preprocessor. (semicolon separated)</p>
</dd>
<dt><kbd><span class="option">--raw</span></kbd></dt>
<dd><p>Do not process shader. No preprocessor, and no glsl-optimizer. (GLSL only)</p>
</dd>
<dt><kbd><span class="option">--type <var>&lt;type&gt;</var></span></kbd></dt>
<dd><p>Shader type.</p>
<p>Can be vertex, fragment, or compute.</p>
</dd>
<dt><kbd><span class="option">--varyingdef <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>A varying.def.scs file path.</p>
</dd>
<dt><kbd><span class="option">--verbose</span></kbd></dt>
<dd><p>Be verbose.</p>
</dd>
</dl>
</div></blockquote>
<p>(DX9 and DX11 only):</p>
<blockquote>
<div><dl class="option-list">
<dt><kbd><span class="option">--debug</span></kbd></dt>
<dd><p>Debug information.</p>
</dd>
<dt><kbd><span class="option">--disasm</span></kbd></dt>
<dd><p>Disassemble a compiled shader.</p>
</dd>
<dt><kbd><span class="option">-O <var>&lt;level&gt;</var></span></kbd></dt>
<dd><p>Set optimization level.</p>
<p>Can be 03.</p>
</dd>
<dt><kbd><span class="option">--Werror</span></kbd></dt>
<dd><p>Treat warnings as errors.</p>
</dd>
</dl>
</div></blockquote>
<div class="section" id="building-shaders">
<h3>Building shaders<a class="headerlink" href="#building-shaders" title="Permalink to this headline"></a></h3>
<p>Shaders can be compiled for all renderers by using the <code class="docutils literal notranslate"><span class="pre">shaderc</span></code> tool.
A Makefile to simplify building shaders is provided in the <a class="reference external" href="https://github.com/bkaradzic/bgfx/tree/master/examples">bgfx examples</a>.
D3D shaders can be only compiled on Windows.</p>
</div>
</div>
<div class="section" id="texture-compiler-texturec">
<h2>Texture Compiler (texturec)<a class="headerlink" href="#texture-compiler-texturec" title="Permalink to this headline"></a></h2>
<p>Convert PNG, TGA, DDS, KTX, and PVR textures into bgfx-supported texture formats.</p>
<p>Usage:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">texturec</span> <span class="o">-</span><span class="n">f</span> <span class="o">&lt;</span><span class="ow">in</span><span class="o">&gt;</span> <span class="o">-</span><span class="n">o</span> <span class="o">&lt;</span><span class="n">out</span><span class="o">&gt;</span> <span class="p">[</span><span class="o">-</span><span class="n">t</span> <span class="o">&lt;</span><span class="n">texture</span> <span class="nb">format</span><span class="o">&gt;</span><span class="p">]</span>
</pre></div>
</div>
<p>Supported file formats:</p>
<blockquote>
<div><table class="docutils align-default">
<colgroup>
<col style="width: 12%" />
<col style="width: 32%" />
<col style="width: 56%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>Format</p></th>
<th class="head"><p>In/Out</p></th>
<th class="head"><p>Description</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>.bmp</p></td>
<td><p>(input)</p></td>
<td><p>Windows Bitmap.</p></td>
</tr>
<tr class="row-odd"><td><p>.dds</p></td>
<td><p>(input, output)</p></td>
<td><p>Direct Draw Surface.</p></td>
</tr>
<tr class="row-even"><td><p>.exr</p></td>
<td><p>(input, output)</p></td>
<td><p>OpenEXR.</p></td>
</tr>
<tr class="row-odd"><td><p>.gif</p></td>
<td><p>(input)</p></td>
<td><p>Graphics Interchange Format.</p></td>
</tr>
<tr class="row-even"><td><p>.jpg</p></td>
<td><p>(input)</p></td>
<td><p>JPEG Interchange Format.</p></td>
</tr>
<tr class="row-odd"><td><p>.hdr</p></td>
<td><p>(input, output)</p></td>
<td><p>Radiance RGBE.</p></td>
</tr>
<tr class="row-even"><td><p>.ktx</p></td>
<td><p>(input, output)</p></td>
<td><p>Khronos Texture.</p></td>
</tr>
<tr class="row-odd"><td><p>.png</p></td>
<td><p>(input, output)</p></td>
<td><p>Portable Network Graphics.</p></td>
</tr>
<tr class="row-even"><td><p>.psd</p></td>
<td><p>(input)</p></td>
<td><p>Photoshop Document.</p></td>
</tr>
<tr class="row-odd"><td><p>.pvr</p></td>
<td><p>(input)</p></td>
<td><p>PowerVR.</p></td>
</tr>
<tr class="row-even"><td><p>.tga</p></td>
<td><p>(input)</p></td>
<td><p>Truevision TGA.</p></td>
</tr>
</tbody>
</table>
</div></blockquote>
<p>Options:</p>
<blockquote>
<div><dl class="option-list">
<dt><kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></dt>
<dd><p>Display this help and exit.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Output version information and exit.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Inputs file path.</p>
</dd>
<dt><kbd><span class="option">-o <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Outputs file path.</p>
</dd>
<dt><kbd><span class="option">-t <var>&lt;format&gt;</var></span></kbd></dt>
<dd><p>Output format type. (BC1/2/3/4/5, ETC1, PVR14, etc.)</p>
</dd>
<dt><kbd><span class="option">-q <var>&lt;quality&gt;</var></span></kbd></dt>
<dd><p>Encoding quality.</p>
<p>Can be default, fastest, or highest.</p>
</dd>
<dt><kbd><span class="option">-m</span>, <span class="option">--mips</span></kbd></dt>
<dd><p>Generate mip-maps.</p>
</dd>
<dt><kbd><span class="option">--mipskip <var>&lt;N&gt;</var></span></kbd></dt>
<dd><p>Skip &lt;N&gt; number of mips.</p>
</dd>
<dt><kbd><span class="option">-n</span>, <span class="option">--normalmap</span></kbd></dt>
<dd><p>Input texture is normal map. (Implies linear)</p>
</dd>
<dt><kbd><span class="option">--equirect</span></kbd></dt>
<dd><p>Input texture is equirectangular projection of cubemap.</p>
</dd>
<dt><kbd><span class="option">--strip</span></kbd></dt>
<dd><p>Input texture is horizontal strip of cubemap.</p>
</dd>
<dt><kbd><span class="option">--sdf</span></kbd></dt>
<dd><p>Compute SDF texture.</p>
</dd>
<dt><kbd><span class="option">--ref <var>&lt;alpha&gt;</var></span></kbd></dt>
<dd><p>Alpha reference value.</p>
</dd>
<dt><kbd><span class="option">--iqa</span></kbd></dt>
<dd><p>Image Quality Assessment</p>
</dd>
<dt><kbd><span class="option">--pma</span></kbd></dt>
<dd><p>Premultiply alpha into RGB channel.</p>
</dd>
<dt><kbd><span class="option">--linear</span></kbd></dt>
<dd><p>Input and output texture is linear color space. (Gamma correction wont be applied)</p>
</dd>
<dt><kbd><span class="option">--max <var>&lt;max size&gt;</var></span></kbd></dt>
<dd><p>Maximum width/height. (Image will be scaled down and aspect ratio will be preserved)</p>
</dd>
<dt><kbd><span class="option">--radiance <var>&lt;model&gt;</var></span></kbd></dt>
<dd><p>Radiance cubemap filter.</p>
<p>Model can be Phong, PhongBrdf, Blinn, BlinnBrdf, or GGX.</p>
</dd>
<dt><kbd><span class="option">--as <var>&lt;extension&gt;</var></span></kbd></dt>
<dd><p>Save as.</p>
</dd>
<dt><kbd><span class="option">--formats</span></kbd></dt>
<dd><p>List all supported formats.</p>
</dd>
<dt><kbd><span class="option">--validate</span></kbd></dt>
<dd><p><strong>DEBUG</strong> Validate that output image produced matches after loading.</p>
</dd>
</dl>
</div></blockquote>
</div>
<div class="section" id="texture-viewer-texturev">
<h2>Texture Viewer (texturev)<a class="headerlink" href="#texture-viewer-texturev" title="Permalink to this headline"></a></h2>
<p>A texture viewer.</p>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="internals.html" class="btn btn-neutral float-right" title="Internals" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="bgfx.html" class="btn btn-neutral float-left" title="API Reference" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2010-2022, Branimir Karadžić
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>