1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
|
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.
.. raw:: html
<p>
<iframe src="https://ghbtns.com/github-btn.html?user=bkaradzic&repo=bgfx&type=star&count=true&size=large" frameborder="0" scrolling="0" width="160px" height="30px"></iframe>
<iframe src="https://ghbtns.com/github-btn.html?user=bkaradzic&repo=bgfx&type=fork&count=true&size=large" frameborder="0" scrolling="0" width="158px" height="30px"></iframe>
</p>
Supported rendering backends
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Direct3D 9
- Direct3D 11
- Direct3D 12
- GNM (only for licensed PS4 developers, search DevNet forums for source)
- Metal
- OpenGL 2.1
- OpenGL 3.1+
- OpenGL ES 2
- OpenGL ES 3.1
- Vulkan
- WebGL 1.0
- WebGL 2.0
- WebGPU/Dawn (experimental)
Supported Platforms
~~~~~~~~~~~~~~~~~~~
- Android (14+, ARM, x86, MIPS)
- FreeBSD
- iOS (iPhone, iPad, AppleTV)
- Linux
- MIPS Creator CI20
- OSX (10.12+)
- PlayStation 4
- RaspberryPi
- UWP (Universal Windows, Xbox One)
- Wasm/Emscripten
- Windows (XP, Vista, 7, 8, 10)
Supported Compilers
~~~~~~~~~~~~~~~~~~~
- Clang 3.3 and above
- GCC 5 and above
- vs2017 and above
Supported Languages
~~~~~~~~~~~~~~~~~~~
- `C/C++ API documentation <https://bkaradzic.github.io/bgfx/bgfx.html>`__
- `Beef API bindings <https://github.com/bkaradzic/bgfx/tree/master/bindings/bf>`__
- `C# language API bindings #1 <https://github.com/bkaradzic/bgfx/tree/master/bindings/cs>`__
- `D language API bindings <https://github.com/GoaLitiuM/bindbc-bgfx>`__
- `Go language API bindings <https://github.com/james4k/go-bgfx>`__
- `Haskell language API bindings <https://github.com/haskell-game/bgfx>`__
- `Lightweight Java Game Library 3 bindings <https://github.com/LWJGL/lwjgl3#lwjgl---lightweight-java-game-library-3>`__
- `Lua language API bindings <https://github.com/cloudwu/lua-bgfx>`__
- `Nim language API bindings <https://github.com/Halsys/nim-bgfx>`__
- `Pascal language API bindings <https://github.com/Akira13641/PasBGFX>`__
- `Python language API bindings #1 <https://github.com/fbertola/bgfx-python#-----bgfx-python-->`__
- `Python language API bindings #2 <https://github.com/jnadro/pybgfx#pybgfx>`__
- `Rust language API bindings <https://github.com/rhoot/bgfx-rs#bgfx-rs>`__
- `Swift language API bindings <https://github.com/stuartcarnie/SwiftBGFX>`__
- `Zig language API bindings <https://github.com/bkaradzic/bgfx/tree/master/bindings/zig>`__
Project Page
~~~~~~~~~~~~
- https://github.com/bkaradzic/bgfx
Contact
~~~~~~~
- `GitHub Discussions <https://github.com/bkaradzic/bgfx/discussions>`__
- `Discord Chat <https://discord.gg/9eMbv7J>`__
- GitHub `@bkaradzic <https://github.com/bkaradzic>`__
- Twitter `@bkaradzic <https://twitter.com/bkaradzic>`__
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 <https://renderdoc.org/builds>`__
RenderDoc `How do I ...? <https://renderdoc.org/docs/how/index.html>`__ documentation.
`Shader debugging <https://software.intel.com/en-us/articles/shader-debugging-for-bgfx-rendering-engine>`__
with RenderDoc and MSVC.
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 <https://software.intel.com/en-us/vcsource/tools/intel-gpa>`__
Other Debuggers and Profilers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. |x| unicode:: U+2713 .. CHECK MARK
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Name | OS | DX9 | DX11 | DX12 | Metal | GL | GLES | Vulkan| Source |
+=============+=================+=======+========+======+=======+======+======+=======+========+
| APITrace | Linux/OSX/Win | |x| | |x| | | | |x| | |x| | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| CodeXL | Linux/Win | | | | | |x| | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Dissector | Win | |x| | | | | | | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| IntelGPA | Linux/OSX/Win | |x| | |x| | | | | |x| | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| Nsight | Win | |x| | |x| | | | |x| | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PerfHUD | Win | |x| | |x| | | | | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PerfStudio | Win | | |x| | |x| | | |x| | |x| | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| PIX | Win | | | |x| | | | | | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| RGP | Win | | | |x| | | | | |x| | |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| RenderDoc | Win/Linux | | |x| | | | |x| | | |x| | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
| vogl | Linux | | | | | |x| | | | |x| |
+-------------+-----------------+-------+--------+------+-------+------+------+-------+--------+
Download:
- `APITrace <https://apitrace.github.io/>`__
- `CodeXL <http://developer.amd.com/tools-and-sdks/opencl-zone/codexl/>`__
- `Dissector <https://github.com/imccown/Dissector>`__
- `GPU PerfStudio <http://developer.amd.com/tools-and-sdks/graphics-development/gpu-perfstudio/>`__
- `Linux Graphics Debugger <https://developer.nvidia.com/linux-graphics-debugger>`__
- `Nsight <https://developer.nvidia.com/nsight-graphics>`__
- `PIX <https://blogs.msdn.microsoft.com/pix/>`__
- `PerfHUD <https://developer.nvidia.com/nvidia-perfhud>`__
- `RGP (Radeon GPU Profiler) <https://github.com/GPUOpen-Tools/Radeon-GPUProfiler/releases>`__
- `vogl <https://github.com/ValveSoftware/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.
For more info see: :doc:`bgfx`.
.. note:: You can use ``--with-sdl`` when running 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_MULTITHREADED=0``
preprocessor define.
Getting Involved
----------------
Everyone is welcome to contribute to bgfx by submitting bug reports, testing on different
platforms, writing examples (see `ideas <https://github.com/bkaradzic/bgfx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+needed%22>`__),
improving documentation, profiling and optimizing, etc.
.. note:: **When contributing to the bgfx project you must agree to the BSD 2-clause
licensing terms.**
Contributors
~~~~~~~~~~~~
Chronological order:
- Branimir Karadžić (`@bkaradzic <https://github.com/bkaradzic>`__)
- Garett Bass (`@garettbass <https://github.com/garettbass>`__) - OSX port.
- Jeremie Roy (`@jeremieroy <https://github.com/jeremieroy>`__) -
`10-font <examples.html#font>`__,
and `11-fontsdf <examples.html#fontsdf>`__ examples.
- Miloš Tošić (`@milostosic <https://github.com/milostosic>`__) -
`12-lod <examples.html#lod>`__ example.
- Dario Manesku (`@dariomanesku <https://github.com/dariomanesku>`__) -
`13-stencil <examples.html#stencil>`__,
`14-shadowvolumes <examples.html#shadowvolumes>`__,
`15-shadowmaps-simple <examples.html#shadowmaps-simple>`__,
`16-shadowmaps <examples.html#shadowmaps>`__,
`18-ibl <examples.html#ibl>`__,
and `28-wireframe <examples.html#wireframe>`__ example.
- James Gray (`@james4k <https://github.com/james4k>`__) - Go language API bindings.
- Guillaume Piolat (`@p0nce <https://github.com/p0nce>`__) - D language API bindings.
- Mike Popoloski (`@MikePopoloski <https://github.com/MikePopoloski>`__) - C#/VB/F# language API
bindings, WinRT/WinPhone support.
- Kai Jourdan (`@questor <https://github.com/questor>`__) -
`23-vectordisplay <examples.html#vectordisplay>`__ example.
- Stanlo Slasinski (`@stanlo <https://github.com/stanlo>`__) -
`24-nbody <examples.html#nbody>`__ example.
- Daniel Collin (`@emoon <https://github.com/emoon>`__) - Port of Ocornut's ImGui to bgfx.
- Andre Weissflog (`@floooh <https://github.com/floooh>`__) - Alternative build system fips.
- Andrew Johnson (`@ajohnson23 <https://github.com/ajohnson23>`__) - TeamCity build.
- Tony McCrary (`@enleeten <https://github.com/enleeten>`__) - Java language API bindings.
- Attila Kocsis (`@attilaz <https://github.com/attilaz>`__) - Metal rendering backend, various OSX
and iOS improvements and bug fixes, `39-assao <examples.html#assao>`__ example.
- Richard Gale (`@RichardGale <https://github.com/RichardGale>`__) - Emscripten entry input
handling.
- Andrew Mac (`@andr3wmac <https://github.com/andr3wmac>`__) -
`27-terrain <examples.html#terrain>`__ example.
- Oliver Charles (`@ocharles <https://github.com/ocharles>`__) - Haskel language API bindings.
- Johan Sköld (`@rhoot <https://github.com/rhoot>`__) - Rust language API bindings.
- Jean-François Verdon (`@Nodrev <https://github.com/Nodrev>`__) - Alternative deployment for
Android.
- Jason Nadro (`@jnadro <https://github.com/jnadro>`__) - Python language API bindings.
- Krzysztof Kondrak (`@kondrak <https://github.com/kondrak>`__) - OculusVR integration.
- Colby Klein (`@excessive <https://github.com/excessive>`__) - Lua language API bindings.
- Stuart Carnie (`@stuartcarnie <https://github.com/stuartcarnie>`__) - Swift language API
bindings.
- Joseph Cherlin (`@jcherlin <https://github.com/jcherlin>`__) -
`30-picking <examples.html#picking>`__,
and `31-rsm <examples.html#rsm>`__ example.
- Olli Wang (`@olliwang <https://github.com/olliwang>`__) - Various NanoVG integration improvements.
- Cory Golden (`@Halsys <https://github.com/Halsys>`__) - Nim language API bindings.
- Camilla Berglund (`@elmindreda <https://github.com/elmindreda>`__) - GLFW support.
- Daniel Ludwig (`@code-disaster <https://github.com/code-disaster>`__) - Lightweight Java Game
Library 3 bindings.
- Benoit Jacquier (`@benoitjacquier <https://github.com/benoitjacquier>`__) - Added support for
cubemap as texture 2D array in a compute shader.
- Apoorva Joshi (`@ApoorvaJ <https://github.com/ApoorvaJ>`__) -
`33-pom <examples.html#pom>`__ example.
- Stanislav Pidhorsky (`@podgorskiy <https://github.com/podgorskiy>`__) -
`36-sky <examples.html#sky>`__ example.
- 云风 (`@cloudwu <https://github.com/cloudwu>`__) - Alternative Lua bindings, bgfx IDL scripts,
`42-bunnylod <examples.html#bunnylod>`__ example.
- Kostas Anagnostou (`@KostasAAA <https://github.com/KostasAAA>`__) -
`37-gpudrivenrendering <examples.html#gpudrivenrendering>`__ example.
- Andrew Willmott (`@andrewwillmott <https://github.com/andrewwillmott>`__) - ATC and ASTC support.
- Aleš Mlakar (`@jazzbre <https://github.com/jazzbre>`__) -
`40-svt <examples.html#svt>`__ example.
- Matt Chiasson (`@mchiasson <https://github.com/mchiasson>`__) - Various fixes and improvements.
- Phil Peron (`@pperon <https://github.com/pperon>`__) - Tutorial how to use bgfx API.
- Vincent Cruz (`@BlockoS <https://github.com/BlockoS>`__) - Wayland support.
- Jonathan Young (`@jpcy <https://github.com/jpcy>`__) - Renderer for ioquake3 that uses bgfx,
minimal bgfx example.
- Nick Waanders (`@NickWaanders <https://github.com/NickWaanders>`__) - shaderc: Metal fixes.
- Vladimir Vukićević (`@vvuk <https://github.com/vvuk>`__) - HTML5 context.
- Daniel Gavin (`@DanielGavin <https://github.com/DanielGavin>`__) - `41-tess <examples.html#tess>`__ example.
- Ji-yong Kwon (`@rinthel <https://github.com/rinthel>`__) - Vulkan rendering backend.
- Leandro Freire (`@leandrolfre <https://github.com/leandrolfre>`__).
- Ari Vuollet (`@GoaLitiuM <https://github.com/GoaLitiuM>`__) IDL generator for D language
bindings.
- Sebastian Marketsmueller (`@sebastianmunity3d <https://github.com/sebastianmunity3d>`__).
- Cedric Guillemet (`@CedricGuillemet <https://github.com/CedricGuillemet>`__).
- Pablo Escobar (`@pezcode <https://github.com/pezcode>`__) - Various Vulkan fixes.
- Paul Gruenbacher (`@pgruenbacher <https://github.com/pgruenbacher>`__) - Various bug fixes.
- Jukka Jylänki (`@juj <https://github.com/juj>`__) - Various WebGL optimizations and fixes.
- Hugo Amnov (`@hugoam <https://github.com/hugoam>`__) - WebGPU/Dawn rendering backend.
- Christophe Dehais (`@goodartistscopy <https://github.com/goodartistscopy>`__) - Various bug fixes.
- elvencache (`@elvencache <https://github.com/elvencache>`__) -
`43-denoise <examples.html#denoise>`__,
`44-sss <examples.html#sss>`__,
and `45-bokeh <examples.html#bokeh>`__ example.
- Richard Schubert (`@Hemofektik <https://github.com/Hemofektik>`__) - `46-fsr <examples.html#fsr>`__ example.
- Sandy Carter (`@bwrsandman <https://github.com/bwrsandman>`__) - `47-pixelformats
<examples.html#pixelformats>`__ example, and various fixes and improvements.
- Liam Twigger (`@SnapperTT <https://github.com/SnapperTT>`__) - `48-drawindirect <examples.html#drawindirect>`__ example.
- Preetish Kakkar (`@blackhole <https://github.com/preetishkakkar>`__) - `49-hextile <examples.html#49-hextile>`__ example.
- Biswapriyo Nath (`@Biswa96 <https://github.com/Biswa96>`__) - GitHub Actions CI.
- Raziel Alphadios (`@RazielXYZ <https://github.com/RazielXYZ>`__) - Various fixes and improvements.
and `others <https://github.com/bkaradzic/bgfx/graphs/contributors>`__...
Repository visualization
~~~~~~~~~~~~~~~~~~~~~~~~
.. raw:: html
<p>
<iframe width="694" height="390" src="https://www.youtube.com/embed/5ZeN_d_-BHo" frameborder="0" allowfullscreen></iframe>
</p>
|