mirrors/bgfx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated docs.

Browse Source
This commit is contained in:
Бранимир Караџић 2022-04-06 18:56:19 -07:00
parent 83fb857da2
commit 042d15dd31
13 changed files with 129 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_static/documentation_options.js
View File

@ -1,6 +1,6 @@
var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '1.115.8115',
VERSION: '1.115.8127',
LANGUAGE: 'None',
COLLAPSE_INDEX: false,
BUILDER: 'html',

59
bgfx.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>API Reference &mdash; bgfx 1.115.8115 documentation</title>
<title>API Reference &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>
@ -225,10 +225,12 @@
<h1>API Reference<a class="headerlink" href="#api-reference" title="Permalink to this headline"></a></h1>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>TL;DR for simple walkthrough how to use bgfx API, see <a class="reference external" href="https://dev.to/pperon/hello-bgfx-4dka">Hello, bgfx!</a>,
<a class="reference external" href="https://github.com/jpcy/bgfx-minimal-example#bgfx-minimal-example">bgfx-minimal-example</a>,
or <a class="reference external" href="https://www.sandeepnambiar.com/getting-started-with-bgfx/">Using the bgfx library with C++ on Ubuntu</a>
tutorial.</p>
<p>If you’re just getting started with bgfx, you might get more out of these simple walkthroughs for how to use bgfx’s API:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://dev.to/pperon/hello-bgfx-4dka">Hello, bgfx!</a></p></li>
<li><p><a class="reference external" href="https://github.com/jpcy/bgfx-minimal-example#bgfx-minimal-example">bgfx-minimal-example</a></p></li>
<li><p><a class="reference external" href="https://www.sandeepnambiar.com/getting-started-with-bgfx/">Using the bgfx library with C++ on Ubuntu</a></p></li>
</ul>
</div>
<div class="section" id="general">
<h2>General<a class="headerlink" href="#general" title="Permalink to this headline"></a></h2>
@ -1928,8 +1930,8 @@ tutorial.</p>
</div>
<div class="section" id="platform-specific">
<h3>Platform specific<a class="headerlink" href="#platform-specific" title="Permalink to this headline"></a></h3>
<p>These are platform specific APIs. It is only necessary to use these APIs in conjunction with
creating windows.</p>
<p>These are platform specific APIs.
It is only necessary to use these APIs in conjunction with creating windows.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx11renderFrameE7int32_t">
<span id="_CPPv3N4bgfx11renderFrameE7int32_t"></span><span id="_CPPv2N4bgfx11renderFrameE7int32_t"></span><span id="bgfx::renderFrame__int32_t"></span><span class="target" id="namespacebgfx_1aa21b96113ad74bf31dd3d417ac5b3e52"></span><a class="reference internal" href="#_CPPv4N4bgfx11RenderFrameE" title="bgfx::RenderFrame">RenderFrame</a>::Enum <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">renderFrame</code><span class="sig-paren">(</span>int32_t <em>_msecs</em> = -1<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx11renderFrameE7int32_t" title="Permalink to this definition"></a><br /></dt>
@ -2486,17 +2488,18 @@ creating windows.</p>
</div>
<div class="section" id="views">
<h2>Views<a class="headerlink" href="#views" title="Permalink to this headline"></a></h2>
<p>View is primary sorting mechanism in bgfx. View represent bucket of draw and compute calls. Compute
and draw calls inside bucket are sorted in the way that all compute calls are executed before draw
calls. Compute calls are always in order of submission, while draw calls are sorted by internal
state if view is not in sequential mode. In the most of cases when z-buffer is used this change in
order is not noticable to desired output. In cases where order has to be preserved (for example in
rendering GUIs), view can be set to be in sequential order. Sequential order is less efficient,
because it doesn’t allow state change optimization, and should be avoided when possible.</p>
<p>By default views ids are sorted in ascending order. For dynamic renderers where order might not be
known until the last moment, view ids can be remaped to arbitrary order by calling
<cite>bgfx::setViewOrder</cite>.</p>
<p>View state is preserved between multiple frames.</p>
<p>Views are the primary sorting mechanism in bgfx.
They represent buckets of draw and compute calls, or what are often known as ‘passes’.</p>
<p>When compute calls and draw calls occupy the same bucket, the compute calls will be sorted to execute first.
Compute calls are always executed in order of submission, while draw calls are sorted by internal state if
the View is not in sequential mode.
In most cases where the z-buffer is used, this change in order does not affect the desired output.
When draw call order needs to be preserved (e.g. when rendering GUIs), Views can be set to use sequential mode with <cite>bgfx::setViewMode</cite>.
Sequential order is less efficient, because it doesn’t allow state change optimization, and should be avoided when possible.</p>
<p>By default, Views are sorted by their View ID, in ascending order.
For dynamic renderers where the right order might not be known until the last moment,
View IDs can be changed to use arbitrary ordering with <cite>bgfx::setViewOrder</cite>.</p>
<p>A View’s state is preserved between frames.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx11setViewNameE6ViewIdPKc">
<span id="_CPPv3N4bgfx11setViewNameE6ViewIdPKc"></span><span id="_CPPv2N4bgfx11setViewNameE6ViewIdPKc"></span><span id="bgfx::setViewName__ViewId.cCP"></span><span class="target" id="namespacebgfx_1af08d8fae9b2a2ceff9debcf25c0966fb"></span>void <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">setViewName</code><span class="sig-paren">(</span>ViewId <em>_id</em>, <em class="property">const</em> char *<em>_name</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx11setViewNameE6ViewIdPKc" title="Permalink to this definition"></a><br /></dt>
@ -3599,8 +3602,8 @@ known until the last moment, view ids can be remaped to arbitrary order by calli
</div>
<div class="section" id="draw">
<h3>Draw<a class="headerlink" href="#draw" title="Permalink to this headline"></a></h3>
<p>Draw state is not preserved between two draw calls. All state is cleared after calling
<cite>bgfx::submit</cite>.</p>
<p>Draw state is not preserved between two draw calls.
All state is cleared after calling <cite>bgfx::submit</cite>.</p>
<div class="section" id="state">
<h4>State<a class="headerlink" href="#state" title="Permalink to this headline"></a></h4>
</div>
@ -3983,8 +3986,9 @@ known until the last moment, view ids can be remaped to arbitrary order by calli
</div>
<div class="section" id="scissor">
<h4>Scissor<a class="headerlink" href="#scissor" title="Permalink to this headline"></a></h4>
<p>When scissor rectangle is changing per draw call inside the same view use <cite>bgfx::setScissor</cite>,
otherwise prefer <cite>bgfx::setViewScissor</cite>.</p>
<p>If the Scissor rectangle needs to be changed for
every draw call in a View, use <cite>bgfx::setScissor</cite>.
Otherwise, use <cite>bgfx::setViewScissor</cite>.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx10setScissorE8uint16_t8uint16_t8uint16_t8uint16_t">
<span id="_CPPv3N4bgfx10setScissorE8uint16_t8uint16_t8uint16_t8uint16_t"></span><span id="_CPPv2N4bgfx10setScissorE8uint16_t8uint16_t8uint16_t8uint16_t"></span><span id="bgfx::setScissor__uint16_t.uint16_t.uint16_t.uint16_t"></span><span class="target" id="namespacebgfx_1a044469089552c76b36ec5e5ac57cf695"></span>uint16_t <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">setScissor</code><span class="sig-paren">(</span>uint16_t <em>_x</em>, uint16_t <em>_y</em>, uint16_t <em>_width</em>, uint16_t <em>_height</em><span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx10setScissorE8uint16_t8uint16_t8uint16_t8uint16_t" title="Permalink to this definition"></a><br /></dt>
@ -4572,7 +4576,7 @@ otherwise prefer <cite>bgfx::setViewScissor</cite>.</p>
</div>
<div class="section" id="submit">
<h4>Submit<a class="headerlink" href="#submit" title="Permalink to this headline"></a></h4>
<p>Within view all draw commands are executed after blit and compute commands.</p>
<p>In Views, all draw commands are executed <strong>after</strong> blit and compute commands.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx6submitE6ViewId13ProgramHandle8uint32_t7uint8_t">
<span id="_CPPv3N4bgfx6submitE6ViewId13ProgramHandle8uint32_t7uint8_t"></span><span id="_CPPv2N4bgfx6submitE6ViewId13ProgramHandle8uint32_t7uint8_t"></span><span id="bgfx::submit__ViewId.ProgramHandle.uint32_t.uint8_t"></span><span class="target" id="namespacebgfx_1aac8f69b1ff11ad6c8a95db9f9e46d019"></span>void <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">submit</code><span class="sig-paren">(</span>ViewId <em>_id</em>, ProgramHandle <em>_program</em>, uint32_t <em>_depth</em> = 0, uint8_t <em>_flags</em> = BGFX_DISCARD_ALL<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx6submitE6ViewId13ProgramHandle8uint32_t7uint8_t" title="Permalink to this definition"></a><br /></dt>
@ -4635,8 +4639,7 @@ otherwise prefer <cite>bgfx::setViewScissor</cite>.</p>
</div>
<div class="section" id="compute">
<h3>Compute<a class="headerlink" href="#compute" title="Permalink to this headline"></a></h3>
<p>Compute state is not preserved between two compute dispatches. All state is cleared after calling
<cite>bgfx::dispatch</cite>.</p>
<p>Compute state is not preserved between compute dispatches; all state is cleared after calling <cite>bgfx::dispatch</cite>.</p>
<div class="section" id="id4">
<h4>Buffers<a class="headerlink" href="#id4" title="Permalink to this headline"></a></h4>
<dl class="cpp struct">
@ -4793,7 +4796,7 @@ otherwise prefer <cite>bgfx::setViewScissor</cite>.</p>
</div>
<div class="section" id="dispatch">
<h4>Dispatch<a class="headerlink" href="#dispatch" title="Permalink to this headline"></a></h4>
<p>Within view all compute commands are dispatched after blit commands, and before draw commands.</p>
<p>In Views, all draw commands are executed <strong>after</strong> blit and compute commands.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx8dispatchE6ViewId13ProgramHandle8uint32_t8uint32_t8uint32_t7uint8_t">
<span id="_CPPv3N4bgfx8dispatchE6ViewId13ProgramHandle8uint32_t8uint32_t8uint32_t7uint8_t"></span><span id="_CPPv2N4bgfx8dispatchE6ViewId13ProgramHandle8uint32_t8uint32_t8uint32_t7uint8_t"></span><span id="bgfx::dispatch__ViewId.ProgramHandle.uint32_t.uint32_t.uint32_t.uint8_t"></span><span class="target" id="namespacebgfx_1a3f99f5af2f277674422b56e60b5d8a91"></span>void <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">dispatch</code><span class="sig-paren">(</span>ViewId <em>_id</em>, ProgramHandle <em>_handle</em>, uint32_t <em>_numX</em> = 1, uint32_t <em>_numY</em> = 1, uint32_t <em>_numZ</em> = 1, uint8_t <em>_flags</em> = BGFX_DISCARD_ALL<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx8dispatchE6ViewId13ProgramHandle8uint32_t8uint32_t8uint32_t7uint8_t" title="Permalink to this definition"></a><br /></dt>
@ -4838,7 +4841,7 @@ otherwise prefer <cite>bgfx::setViewScissor</cite>.</p>
</div>
<div class="section" id="blit">
<h3>Blit<a class="headerlink" href="#blit" title="Permalink to this headline"></a></h3>
<p>Within view all blit commands are executed before compute, and draw commands.</p>
<p>In Views, all draw commands are executed <strong>after</strong> blit and compute commands.</p>
<dl class="cpp function">
<dt id="_CPPv4N4bgfx4blitE6ViewId13TextureHandle8uint16_t8uint16_t13TextureHandle8uint16_t8uint16_t8uint16_t8uint16_t">
<span id="_CPPv3N4bgfx4blitE6ViewId13TextureHandle8uint16_t8uint16_t13TextureHandle8uint16_t8uint16_t8uint16_t8uint16_t"></span><span id="_CPPv2N4bgfx4blitE6ViewId13TextureHandle8uint16_t8uint16_t13TextureHandle8uint16_t8uint16_t8uint16_t8uint16_t"></span><span id="bgfx::blit__ViewId.TextureHandle.uint16_t.uint16_t.TextureHandle.uint16_t.uint16_t.uint16_t.uint16_t"></span><span class="target" id="namespacebgfx_1aebd5560001cdeb76b4fa88ac04b660d6"></span>void <code class="sig-prename descclassname">bgfx<code class="sig-prename descclassname">::</code></code><code class="sig-name descname">blit</code><span class="sig-paren">(</span>ViewId <em>_id</em>, TextureHandle <em>_dst</em>, uint16_t <em>_dstX</em>, uint16_t <em>_dstY</em>, TextureHandle <em>_src</em>, uint16_t <em>_srcX</em> = 0, uint16_t <em>_srcY</em> = 0, uint16_t <em>_width</em> = UINT16_MAX, uint16_t <em>_height</em> = UINT16_MAX<span class="sig-paren">)</span><a class="headerlink" href="#_CPPv4N4bgfx4blitE6ViewId13TextureHandle8uint16_t8uint16_t13TextureHandle8uint16_t8uint16_t8uint16_t8uint16_t" title="Permalink to this definition"></a><br /></dt>

10
build.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Building &mdash; bgfx 1.115.8115 documentation</title>
<title>Building &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>
@ -109,7 +109,7 @@
<li class="toctree-l2"><a class="reference internal" href="#amalgamated-build">Amalgamated Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="#alternative-build-systems">Alternative build systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="#minimal-example-without-bgfx-example-harness">Minimal example without bgfx’ example harness</a></li>
<li class="toctree-l2"><a class="reference internal" href="#minimal-example-without-bgfx-s-example-harness">Minimal example without bgfx’s example harness</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a></li>
@ -366,8 +366,8 @@ instead) inside different build system.</p>
<p><strong>Conan</strong> package
<a class="reference external" href="https://github.com/firefalcom/bgfx-conan">https://github.com/firefalcom/bgfx-conan</a></p>
</div>
<div class="section" id="minimal-example-without-bgfx-example-harness">
<h2>Minimal example without bgfx’ example harness<a class="headerlink" href="#minimal-example-without-bgfx-example-harness" title="Permalink to this headline"></a></h2>
<div class="section" id="minimal-example-without-bgfx-s-example-harness">
<h2>Minimal example without bgfx’s example harness<a class="headerlink" href="#minimal-example-without-bgfx-s-example-harness" title="Permalink to this headline"></a></h2>
<p>This project demonstrates minimal amount of code needed to integrate bgfx with GLFW, but without
any of existing bgfx example harness. It also demonstrates how to build bgfx with alternative build
system.</p>

4
examples.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Examples &mdash; bgfx 1.115.8115 documentation</title>
<title>Examples &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>

4
genindex.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Index &mdash; bgfx 1.115.8115 documentation</title>
<title>Index &mdash; bgfx 1.115.8127 documentation</title>
@ -59,7 +59,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>

6
index.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Documentation &mdash; bgfx 1.115.8115 documentation</title>
<title>Documentation &mdash; bgfx 1.115.8127 documentation</title>
@ -60,7 +60,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>
@ -215,7 +215,7 @@ licensed under permissive BSD-2 clause open source license.</p>
<li class="toctree-l2"><a class="reference internal" href="build.html#amalgamated-build">Amalgamated Build</a></li>
<li class="toctree-l2"><a class="reference internal" href="build.html#tools">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="build.html#alternative-build-systems">Alternative build systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="build.html#minimal-example-without-bgfx-example-harness">Minimal example without bgfx’ example harness</a></li>
<li class="toctree-l2"><a class="reference internal" href="build.html#minimal-example-without-bgfx-s-example-harness">Minimal example without bgfx’s example harness</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="examples.html">Examples</a><ul>

4
internals.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Internals &mdash; bgfx 1.115.8115 documentation</title>
<title>Internals &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>

4
license.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>License &mdash; bgfx 1.115.8115 documentation</title>
<title>License &mdash; bgfx 1.115.8127 documentation</title>
@ -60,7 +60,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>

BIN
objects.inv
View File

Binary file not shown.

9
overview.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Overview &mdash; bgfx 1.115.8115 documentation</title>
<title>Overview &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>
@ -235,19 +235,20 @@ licensed under permissive BSD-2 clause open source license.</p>
<h3>Supported Languages<a class="headerlink" href="#supported-languages" title="Permalink to this headline"></a></h3>
<ul class="simple">
<li><p><a class="reference external" href="https://bkaradzic.github.io/bgfx/bgfx.html">C/C++ API documentation</a></p></li>
<li><p><a class="reference external" href="https://github.com/bkaradzic/bgfx/tree/master/bindings/bf">Beef API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/bkaradzic/bgfx/tree/master/bindings/cs">C# language API bindings #1</a></p></li>
<li><p><a class="reference external" href="https://github.com/MikePopoloski/SharpBgfx">C#/VB/F# language API bindings #2</a></p></li>
<li><p><a class="reference external" href="https://github.com/GoaLitiuM/bindbc-bgfx">D language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/james4k/go-bgfx">Go language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/haskell-game/bgfx">Haskell language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/LWJGL/lwjgl3#lwjgl---lightweight-java-game-library-3">Lightweight Java Game Library 3 bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/cloudwu/lua-bgfx">Lua language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/Halsys/nim-bgfx">Nim language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/Akira13641/PasBGFX">Pascal language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/fbertola/bgfx-python#-----bgfx-python--">Python language API bindings #1</a></p></li>
<li><p><a class="reference external" href="https://github.com/jnadro/pybgfx#pybgfx">Python language API bindings #2</a></p></li>
<li><p><a class="reference external" href="https://github.com/rhoot/bgfx-rs#bgfx-rs">Rust language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/stuartcarnie/SwiftBGFX">Swift language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/Akira13641/PasBGFX">Pascal language API bindings</a></p></li>
<li><p><a class="reference external" href="https://github.com/bkaradzic/bgfx/tree/master/bindings/zig">Zig language API bindings</a></p></li>
</ul>
</div>
<div class="section" id="project-page">

4
search.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Search &mdash; bgfx 1.115.8115 documentation</title>
<title>Search &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>

2
searchindex.js
View File

File diff suppressed because one or more lines are too long

140
tools.html
View File

@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tools &mdash; bgfx 1.115.8115 documentation</title>
<title>Tools &mdash; bgfx 1.115.8127 documentation</title>
@ -61,7 +61,7 @@
<div class="version">
1.115.8115
1.115.8127
</div>
@ -171,7 +171,7 @@
<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 file to format optimal for using with bgfx.</p>
<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>
@ -205,16 +205,16 @@
<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><p>Display this help and exit.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Version information only.</p>
<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>Input file path.</p>
<dd><p>Input’s 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><p>Output’s 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>
@ -226,76 +226,77 @@
<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><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).
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).
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><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><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>
–[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>Geometry viewer.</p>
<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>bgfx cross-platform shader language is based on GLSL syntax. It’s uses
ANSI C preprocessor to transform GLSL like language syntax into HLSL.
This technique has certain drawbacks, but overall it’s simple and allows
quick authoring of cross-platform shaders.</p>
<p>Some differences between bgfx’s shaderc flavor of GLSL and regular GLSL:</p>
<p>Shader Compiler is used to compile bgfx’s 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 it’s simple and allows for quick authoring of cross-platform shaders.</p>
<p>Some differences between bgfx’s shaderc flavor of GLSL and vanilla 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>
<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 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">
<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>Help.</p>
<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>Version information only.</p>
<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>Input file path.</p>
<dd><p>Input’s 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><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><p>Output’s 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>
@ -307,40 +308,42 @@ macros</a>.</p>
<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><p>Shader model.</p>
<p>Defaults to GLSL.</p>
</dd>
<dt><kbd><span class="option">--preprocess</span></kbd></dt>
<dd><p>Preprocess only.</p>
<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><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><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, compute)</p>
<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>Path to varying.def.sc file.</p>
<dd><p>A varying.def.sc’s file path.</p>
</dd>
<dt><kbd><span class="option">--verbose</span></kbd></dt>
<dd><p>Verbose.</p>
<dd><p>Be verbose.</p>
</dd>
</dl>
</dd>
</dl>
<p>Options (DX9 and DX11 only):</p>
</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 compiled shader.</p>
<dd><p>Disassemble a 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><p>Set optimization level.</p>
<p>Can be 0–3.</p>
</dd>
<dt><kbd><span class="option">--Werror</span></kbd></dt>
<dd><p>Treat warnings as errors.</p>
@ -349,13 +352,14 @@ macros</a>.</p>
</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 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>
<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, PVR texture into bgfx supported texture formats.</p>
<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>
@ -426,22 +430,23 @@ shaders is provided in examples. D3D shaders can be only compiled on Windows.</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><p>Display this help and exit.</p>
</dd>
<dt><kbd><span class="option">-v</span>, <span class="option">--version</span></kbd></dt>
<dd><p>Version information only.</p>
<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>Input file path.</p>
<dd><p>Input’s 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><p>Output’s 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><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><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>
@ -471,13 +476,14 @@ shaders is provided in examples. D3D shaders can be only compiled on Windows.</p
<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 won’t be applied).</p>
<dd><p>Input and output texture is linear color space. (Gamma correction won’t 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><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><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>
@ -493,7 +499,7 @@ shaders is provided in examples. D3D shaders can be only compiled on Windows.</p
</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>Texture viewer.</p>
<p>A texture viewer.</p>
</div>
</div>