<h2>Sort based draw call bucketing<aclass="headerlink"href="#sort-based-draw-call-bucketing"title="Permalink to this headline">¶</a></h2>
<p>bgfx is using sort-based draw call bucketing. This means that submission order doesn’t necessarily match the rendering order, but on the low-level they will be sorted and ordered correctly. On the high level bgfx uses declarative API and internal sorting allows more optimal way of submitting draw calls for all passes at one place, and on the low-level this allows better optimization of rendering order. This sometimes creates undesired results usually for GUI rendering, where draw order should usually match submit order. bgfx provides way to enable sequential rendering for these cases (see <codeclass="docutils literal"><spanclass="pre">bgfx::setViewMode</span></code>).</p>
<blockquote>
<div><ulclass="simple">
<li>More detailed description of sort-based draw call bucketing can be found at: <aclass="reference external"href="http://realtimecollisiondetection.net/blog/?p=86">Order your graphics draw calls around!</a></li>
</ul>
</div></blockquote>
</div>
<divclass="section"id="api-and-render-thread">
<h2>API and render thread<aclass="headerlink"href="#api-and-render-thread"title="Permalink to this headline">¶</a></h2>
<p>API thread is thread from which <codeclass="docutils literal"><spanclass="pre">bgfx::init</span></code> is called. Once <codeclass="docutils literal"><spanclass="pre">bgfx::init</span></code> is called on thread, internally bgfx assumes that all API calls will be called from the same thread with exception of Resource, View, and Encoder API.</p>
<p>Render thread from where internal rendering <codeclass="docutils literal"><spanclass="pre">bgfx::renderFrame</span></code> is called. On most of OS’ it’s required that this call be called on thread that OS created when executing process (some refer to this thread as “main” thread, or thread where <codeclass="docutils literal"><spanclass="pre">main</span></code> function is called).</p>
<p>When bgfx is compiled with option <codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_MULTITHREADED=1</span></code> (default is on) <codeclass="docutils literal"><spanclass="pre">bgfx::renderFrame</span></code> can be called by user. It’s required to be called before <codeclass="docutils literal"><spanclass="pre">bgfx::init</span></code> from thread that will be used as render thread. If both <codeclass="docutils literal"><spanclass="pre">bgfx::renderFrame</span></code> and <codeclass="docutils literal"><spanclass="pre">bgfx::init</span></code> are called from the same thread, bgfx will switch to execute in single threaded mode, and calling <codeclass="docutils literal"><spanclass="pre">bgfx::renderFrame</span></code> is not required, since it will be called automatically during <codeclass="docutils literal"><spanclass="pre">bgfx::frame</span></code> call.</p>
</div>
<divclass="section"id="resource-api">
<h2>Resource API<aclass="headerlink"href="#resource-api"title="Permalink to this headline">¶</a></h2>
<p>Any API call starting with <codeclass="docutils literal"><spanclass="pre">bgfx::create*</span></code>, <codeclass="docutils literal"><spanclass="pre">bgfx::destroy</span></code>, <codeclass="docutils literal"><spanclass="pre">bgfx::update*</span></code>, <codeclass="docutils literal"><spanclass="pre">bgfx::alloc*</span></code> is considered part of resource API. Internally resource API calls are guarded by mutex. There is no limit of number of threads that can call resource API simultanesly. Calling any resource API is infrequent, and functions are cheap since most of work with resurces is done at later point on render thread.</p>
</div>
<divclass="section"id="view-api">
<h2>View API<aclass="headerlink"href="#view-api"title="Permalink to this headline">¶</a></h2>
<p>Any API call starting with <codeclass="docutils literal"><spanclass="pre">bgfx::setView*</span></code> is considered part of view API. View API is not designed to be thread safe at all since all views are independentent from each other. Calling any view API for different views from different threads is safe. What’s not safe is to update the same view from multiple threads. This will lead to undefined behavior. Only view API that has to be set before any draw calls are issued is view mode <codeclass="docutils literal"><spanclass="pre">bgfx::setViewMode</span></code>. Internal encoder requires view mode to select sort key encoding and if user changes view mode after submit it will cause incorrect sort behavior within the view.</p>
</div>
<divclass="section"id="encoder-api">
<h2>Encoder API<aclass="headerlink"href="#encoder-api"title="Permalink to this headline">¶</a></h2>
<p>Encoder API can be obtained by calling <codeclass="docutils literal"><spanclass="pre">bgfx::begin</span></code>. bgfx by default allows 8 simultaneous threads to use encoders. This can be configured by changing <codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_MAX_ENCODERS</span></code> option.</p>
</div>
<divclass="section"id="customization">
<h2>Customization<aclass="headerlink"href="#customization"title="Permalink to this headline">¶</a></h2>
<p>By default each platform has sane default values. For example on Windows default renderer is DirectX9, and on Linux it is OpenGL 2.1. On Windows platform all rendering backends are available. For OpenGL ES on desktop you can find more information at:- <aclass="reference external"href="http://www.g-truc.net/post-0457.html">OpenGL ES 2.0 and EGL on desktop</a></p>
<p>If you’re targeting specific mobile hardware, you can find GLES support in their official SDKs: <aclass="reference external"href="http://developer.qualcomm.com/mobile-development/mobile-technologies/gaming-graphics-optimization-adreno/tools-and-resources">Adreno
<p>All configuration settings are located inside <aclass="reference external"href="https://github.com/bkaradzic/bgfx/blob/master/src/config.h">src/config.h</a>.</p>
<p>Every <codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_*</span></code> setting can be changed by passing defines thru compiler switches. For example setting preprocessor define <codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_RENDERER_OPENGL=1</span></code> will change backend renderer to OpenGL 2.1. on Windows. Since rendering APIs are platform specific, this obviously won’t work nor make sense in all cases.</p>
<divclass="section"id="options">
<h3>Options<aclass="headerlink"href="#options"title="Permalink to this headline">¶</a></h3>
<p><codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_MULTITHREADED</span></code> is used to enable/disable threading support inside bgfx. By default set to 1 on all platforms that support threading.</p>
<p><codeclass="docutils literal"><spanclass="pre">BGFX_CONFIG_MAX_ENCODERS</span></code> maximum number of encoders supported by bgfx. This many threads can simultaneosly generate draw calls.</p>
