# Overview

## What is it?

Cross-platform, graphics API agnostic, “Bring Your Own Engine/Framework” style rendering library, licensed under permissive BSD-2 clause open source license.

### Supported rendering backends

- Direct3D 9
- Direct3D 11
- Direct3D 12 (WIP)
- Metal (WIP)
- OpenGL 2.1
- OpenGL 3.1+
- OpenGL ES 2
- OpenGL ES 3.1
- WebGL 1.0
- WebGL 2.0

### Supported HMD

- OculusVR (1.3.0)

### Supported Platforms

- Android (14+, ARM, x86, MIPS)
- asm.js/Emscripten (1.25.0)
- FreeBSD
- iOS (iPhone, iPad, AppleTV)
- Linux
- MIPS Creator CI20
- Native Client (PPAPI 37+, ARM, x86, x64, PNaCl)
- OSX (10.9+)
- RaspberryPi
- SteamLink
- Windows (XP, Vista, 7, 8, 10)
- WinRT (WinPhone 8.0+)

### Supported Compilers

- Clang 3.3 and above
- GCC 4.6 and above
- vs2008 and above

### Supported Languages

- C/C++ API documentation
- C#/VB/F# language API bindings
- D language API bindings
- Go language API bindings
- Haskell language API bindings
- Java language API bindings
- Lua language API bindings
- Python language API bindings
- Rust language API bindings

### Project Page

- https://github.com/bkaradzic/bgfx

### Contact

> - Twitter @bkaradzic
> - GitHub @bkaradzic

## Internals

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 this 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 `bgfx::setViewSeq`).

Internally all low-level rendering draw calls are issued inside single function `RendererContextI::submit`. This function exist inside each renderer backend implementation.

> - More detailed description of sort-based draw call bucketing can be found at: Order your graphics draw calls around!
> - High level overview of bgfx, presented at EclipseCon 2016: From the Dark Side of the Moon: GPU Programming with BGFX and Eclipse, Tony McCrary [l33t labs], Slides: [PDF]

## Customization

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:- OpenGL ES 2.0 and EGL on desktop

If you’re targeting specific mobile hardware, you can find GLES support in their official SDKs: Adreno SDK, Mali SDK, PowerVR SDK.

All configuration settings are located inside src/config.h.

Every `BGFX_CONFIG_*` setting can be changed by passing defines thru compiler switches. For example setting preprocessor define `BGFX_CONFIG_RENDERER_OPENGL=1` 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. Certain platforms have only single choice, for example the Native Client works only with OpenGL ES 2.0 renderer, using anything other than that will result in build errors.

## Debugging and Profiling

### RenderDoc

Loading of RenderDoc is integrated in bgfx when using DX11 or OpenGL renderer. You can drop in `renderdoc.dll` from RenderDoc distribution into working directory, and it will be automatically loaded during bgfx initialization. This allows frame capture at any time by pressing F11.

Download: RenderDoc

### IntelGPA

Right click Intel GPA Monitor tray icon, choose preferences, check “Auto-detect launched applications” option. Find `InjectionList.txt` in GPA directory and add `examples-*` to the list.

Download: IntelGPA

### Other Debuggers and Profilers

Name | OS | DX9 | DX11 | DX12 | Metal | GL | GLES | Vulkan | Source
--- | --- | --- | --- | --- | --- | --- | --- | --- | ---
APITrace | Linux/OSX/Win | ✓ | ✓ |  |  | ✓ | ✓ |  | ✓
CodeXL | Linux/Win |  |  |  |  | ✓ |  |  |
Dissector | Win | ✓ |  |  |  |  |  |  | ✓
PerfStudio | Win |  | ✓ | ✓ |  | ✓ | ✓ |  |
IntelGPA | Linux/OSX/Win | ✓ | ✓ |  |  |  | ✓ |  |
Nsight | Win | ✓ | ✓ |  |  | ✓ |  |  |
PerfHUD | Win | ✓ | ✓ |  |  |  |  |  |
RenderDoc | Win/Linux |  | ✓ |  |  | ✓ |  | ✓ | ✓
vogl | Linux |  |  |  |  | ✓ |  |  | ✓

Download:

- APITrace
- CodeXL
- Dissector
- GPU PerfStudio
- Linux Graphics Debugger
- Nsight
- PerfHUD
- vogl

## SDL, GLFW, etc.

It is possible to use bgfx with SDL, GLFW and similar cross platform windowing libraries. The main requirement is that windowing library provides access to native window handle that’s used to create Direct3D device or OpenGL context.

Using bgfx with SDL example:

    #include <SDL.h>
    #include <bgfx/bgfxplatform.h> // it must be included after SDL to enable SDL
                                   // integration code path.

    #include <bgfx/bgfx.h>
    ...

    int main(...
    {
        SDL_window* window = SDL_CreateWindow(...
        bgfx::sdlSetWindow(window);

        ...
        bgfx::init();

Note

You can use `--with-sdl` when runnning GENie to enable SDL2 integration with examples: `genie --with-sdl vs2012`

Note

`--with-glfw` is also available, but it’s just simple stub to be used to test GLFW integration API.

Note

Special care is necessary to make custom windowing to work with multithreaded renderer. Each platform has rules about where renderer can be and how multithreading interacts with context/device. To disable multithreaded render use `BGFX_CONFIG_MULTITHREDED=0` preprocessor define.

## Todo

- Fullscreen mode.
- ETC2, PVRTC1/2 decoding fallback for targets that don’t support it natively.
- shaderc as library for runtime shader building.
- Multiple vertex streams support.
- Animated mesh example.
- Vulkan renderer backend.

## Getting Involved

Everyone is welcome to contribute to bgfx by submitting bug reports, testing on different platforms, writing examples, improving documentation, profiling and optimizing, etc.

Note

When contributing to the bgfx project you must agree to the BSD 2-clause licensing terms.

### Contributors

Chrnonological order:

> - Branimir Karadžić (@bkaradzic)
> - Garett Bass (@gtbass) - OSX port.
> - Jeremie Roy (@jeremieroy) - Font system and examples.
> - Miloš Tošić (@milostosic) - 12-lod example.
> - Dario Manesku (@dariomanesku) - 13-stencil, 14-shadowvolumes, 15-shadowmaps-simple, 16-shadowmaps, 18-ibl, 28-wireframe.
> - James Gray (@james4k) - Go language API bindings.
> - Guillaume Piolat (@p0nce) - D language API bindings.
> - Mike Popoloski (@MikePopoloski) - C#/VB/F# language API bindings, WinRT/WinPhone support.
> - Kai Jourdan (@questor) - 23-vectordisplay example
> - Stanlo Slasinski (@stanlo) - 24-nbody example
> - Daniel Collin (@emoon) - Port of Ocornut’s ImGui to bgfx.
> - Andre Weissflog (@floooh) - Alternative build system fips.
> - Andrew Johnson (@ajohnson23) - TeamCity build.
> - Tony McCrary (@enleeten) - Java language API bindings.
> - Attila Kocsis (@attilaz) - Metal rendering backend, various OSX and iOS improvements and bug fixes.
> - Richard Gale (@RichardGale) - Emscripten entry input handling.
> - Andrew Mac (@andr3wmac) - 27-terrain.
> - Oliver Charles (@ocharles) - Haskel language API bindings.
> - Johan Sköld (@rhoot) - Rust language API bindings.
> - Jean-François Verdon (@Nodrev) - Alternative deployment for Android.
> - Jason Nadro (@jnadro) - Python language API bindings.
> - Krzysztof Kondrak (@kondrak) - OculusVR integration.
> - Colby Klein (@excessive) - Lua language API bindings.
> - Stuart Carnie (@stuartcarnie) - Swift language API bindings.

### Repository visualization