bgfx/tools.html
Бранимир Караџић 39d91615ef Updated docs.
2021-07-03 01:29:38 -07:00

548 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="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tools &mdash; bgfx 1.0 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.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 data-url_root="./" id="documentation_options" 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 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"> bgfx
</a>
<div class="version">
1.0
</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">
<section id="tools">
<h1>Tools<a class="headerlink" href="#tools" title="Permalink to this headline"></a></h1>
<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 file to format optimal for using 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>Help.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Version information only.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Input file path.</p>
</dd>
<dt><kbd><span class="option">-o <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Output 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.
Default value is 17. Less steps less precise OBB is.
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. Default is lh-up+y Left-Handed +Y is up.</p>
</dd>
</dl>
</div></blockquote>
</section>
<section id="geometry-viewer-geometryv">
<h2>Geometry Viewer (geometryv)<a class="headerlink" href="#geometry-viewer-geometryv" title="Permalink to this headline"></a></h2>
<p>Geometry viewer.</p>
</section>
<section id="shader-compiler-shaderc">
<h2>Shader Compiler (shaderc)<a class="headerlink" href="#shader-compiler-shaderc" title="Permalink to this headline"></a></h2>
<p>bgfx cross-platform shader language is based on GLSL syntax. Its uses
ANSI C preprocessor to transform GLSL like language syntax into HLSL.
This technique has certain drawbacks, but overall its simple and allows
quick authoring of cross-platform shaders.</p>
<p>Some differences between bgfxs shaderc flavor of GLSL and regular GLSL:</p>
<ul class="simple">
<li><p>No <code class="docutils literal notranslate"><span class="pre">bool/int</span></code> uniforms, all uniforms must be <code class="docutils literal notranslate"><span class="pre">float</span></code>.</p></li>
<li><p>Attributes and varyings can be accessed only from <code class="docutils literal notranslate"><span class="pre">main()</span></code>
function.</p></li>
<li><p>Must use <code class="docutils literal notranslate"><span class="pre">SAMPLER2D/3D/CUBE/etc.</span></code> macros instead of
<code class="docutils literal notranslate"><span class="pre">sampler2D/3D/Cube/etc.</span></code> tokens.</p></li>
<li><p>Must use <code class="docutils literal notranslate"><span class="pre">vec2/3/4_splat(&lt;value&gt;)</span></code> instead of
<code class="docutils literal notranslate"><span class="pre">vec2/3/4(&lt;value&gt;)</span></code>.</p></li>
<li><p>Must use <code class="docutils literal notranslate"><span class="pre">mtxFromCols/mtxFromRows</span></code> when constructing matrices in shaders.</p></li>
<li><p>Must use <code class="docutils literal notranslate"><span class="pre">mul(x,</span> <span class="pre">y)</span></code> when multiplying vectors and matrices.</p></li>
<li><p>Must use <code class="docutils literal notranslate"><span class="pre">varying.def.sc</span></code> to define input/output semantic and
precission 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>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$input/$output</span></code> tokens must appear at the begining of shader.</p></li>
</ul>
<p>For more info see <a class="reference external" href="https://github.com/bkaradzic/bgfx/blob/master/src/bgfx_shader.sh">shader helper
macros</a>.</p>
<dl>
<dt>Options:</dt><dd><dl class="option-list">
<dt><kbd><span class="option">-h</span>, <span class="option">--help</span></kbd></dt>
<dd><p>Help.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Version information only.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Input 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>Output 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 (default GLSL).</p>
</dd>
<dt><kbd><span class="option">--preprocess</span></kbd></dt>
<dd><p>Preprocess only.</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 (vertex, fragment)</p>
</dd>
<dt><kbd><span class="option">--varyingdef <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Path to varying.def.sc file.</p>
</dd>
<dt><kbd><span class="option">--verbose</span></kbd></dt>
<dd><p>Verbose.</p>
</dd>
</dl>
</dd>
</dl>
<p>Options (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 compiled shader.</p>
</dd>
<dt><kbd><span class="option">-O <var>&lt;level&gt;</var></span></kbd></dt>
<dd><p>Optimization level (0, 1, 2, 3).</p>
</dd>
<dt><kbd><span class="option">--Werror</span></kbd></dt>
<dd><p>Treat warnings as errors.</p>
</dd>
</dl>
</div></blockquote>
<section id="building-shaders">
<h3>Building shaders<a class="headerlink" href="#building-shaders" title="Permalink to this headline"></a></h3>
<p>Shaders must be compiled for all renderers by using <cite>shaderc</cite> tool. Makefile to simplify building
shaders is provided in examples. D3D shaders can be only compiled on Windows.</p>
</section>
</section>
<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, PVR texture 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>Help.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Version information only.</p>
</dd>
<dt><kbd><span class="option">-f <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Input file path.</p>
</dd>
<dt><kbd><span class="option">-o <var>&lt;file path&gt;</var></span></kbd></dt>
<dd><p>Output 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 (default, fastest, 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. (Lighting model: Phong, PhongBrdf, Blinn, BlinnBrdf, 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>
</section>
<section id="texture-viewer-texturev">
<h2>Texture Viewer (texturev)<a class="headerlink" href="#texture-viewer-texturev" title="Permalink to this headline"></a></h2>
<p>Texture viewer.</p>
</section>
</section>
</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" aria-hidden="true"></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" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&#169; Copyright 2010-2020, Branimir Karadžić.
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>