sdl-bgfx-imgui-starter

The idea behind this repo is for it to be used as a minimal starting point for development of a game, demo or prototype.

It utilizes SDL2 for the windowing system, bgfx (by @bkaradzic) for the graphics library and Dear ImGui (by @ocornut) for the user interface.

The code in main.cpp is derived from two excellent bgfx tutorials (hello-bgfx by Phil Peron and bgfx-ubuntu by Sandeep Nambiar). I highly recommend checking them out.

This repo does not directly include any of these dependencies. Instead, CMake is used to download and install them so this project can use them. This is handled through the use of a superbuild.

Prerequisites

To begin with create a directory to hold the repo:

mkdir sdl-bgfx-imgui-starter
cd sdl-bgfx-imgui-starter

Then clone the repo:

git clone https://github.com/pr0g/sdl-bgfx-imgui-starter.git .

This project comes with a superbuild CMake script which will build all third party dependencies and the main application in one step. The third party dependencies are built and installed to a separate build folder in the third party directory. To achieve this CMake must be installed on your system (the repo has most recently been tested with CMake version 3.24).

Note: It is possible to build the third party dependencies separately, but the configure scripts described below now default to use -DSUPERBUILD=ON (as this is the simplest and most common workflow). If you do wish to build the third party dependencies separately, please see the third party README for full instructions on how to do this.

Note: When building the dependencies, the libraries are by default self contained in the repo and are not installed to the system.

Build Instructions

All

Shaders for bgfx must be compiled to be loaded by the application (the starter has an incredibly simple shader supporting vertex colours). See compile-shaders-<platform>.sh/bat for details. shaderc is built as part of bgfx when first building the repo and is used to compile the shaders.

Note: A number of configure-<generator>.bat/sh files are provided to run the CMake configure commands. Ninja is preferred as it's consistent across macOS, Linux and Windows (and it's very fast), any generator should work though. For example there's a configure-vs-19/22.bat for generating a Visual Studio 2019 or 2022 solution.

Windows

• Run configure-vs-19.bat, configure-vs-22.bat or configure-ninja.bat located in the root directory to generate the build files required for the project.
• Run cmake --build build\debug-ninja and/or cmake --build build\release-ninja to compile the project using Ninja or cmake --build build\vs<year> --config Debug and/or cmake --build build\vs<year> --config Release if using the Visual Studio generator.
• Run compile-shaders-win.bat located in the root directory to build the shaders.
• Launch the application by running build\debug-ninja\sdl-bgfx-imgui-starter.exe or build\release-ninja\sdl-bgfx-imgui-starter.exe if using Ninja or build\vs<year>\Debug\sdl-bgfx-imgui-starter.exe or build\vs<year>\Release\sdl-bgfx-imgui-starter.exe if using Visual Studio.

macOS

• Run ./configure-make.sh or ./configure-ninja.sh located in the root directory to generate the build files required for the project (prefer Ninja if possible as it's much faster).
• Run cmake --build build/debug-<generator> and/or cmake --build build/release-<generator> to compile the project.
• Run ./compile-shaders-macos.sh located in the root directory to build the shaders.
• Launch the application by running ./build/debug-<generator>/sdl-bgfx-imgui-starter or ./build/release-<generator>/sdl-bgfx-imgui-starter.

Linux

• Check the prerequisites when first starting out on Linux to ensure you have all the fundamentals (e.g. X11, OpenGL, Ninja etc...).
• Run ./configure-make.sh or ./configure-ninja.sh located in the root directory to generate the build files required for the project (prefer Ninja if possible as it's much faster).
• Run cmake --build build/debug-<generator> and/or cmake --build build/release-<generator> to compile the project.
• Run ./compile-shaders-linux.sh located in the root directory to build the shaders.
• Launch the application by running ./build/debug-<generator>/sdl-bgfx-imgui-starter or ./build/release-<generator>/sdl-bgfx-imgui-starter.

Emscripten (Windows/macOS/Linux)

Note: Emscripten is built in a separate build folder called embuild, not build. This is to prevent Emscripten from overwriting native builds when built separately.

Note: On Windows it may be necessary to run the command-line/terminal as Administrator when building Emscripten.

• Ensure you have Python installed on your system.
• Follow the install steps to setup Emscripten here (This is required to be able to use the emcmake command in the various configure scripts).
• Run ./configure-emscripten.<bat/sh> from the root directory.
  • Ensure emsdk_env.bat or source ./emsdk_env.sh have been run before attempting this so emcmake is added to the path (see Emscripten instructions above for more details).
• Run ./compile-shaders-emscripten.<bat/sh> located in the root directory. (Note: In order to invoke shaderc, the third party dependencies (specifically bgfx) will have to have been built for the target platform as well as Emscripten, so the shaders can be compiled). The build step for Emscripten copies the built shaders to the build folder (embuild), so compiling the shaders should happen before the main Emscripten build.
• Run cmake --build embuild/debug-emscripten and/or cmake --build embuild/release-emscripten.
• Start a local server (the easiest way to do this is with python3 -m http.server).
• Go to localhost:8000 in a browser and open embuild/<debug/release>-emscripten/sdl-bgfx-imgui-starter.html.

Resources

While getting this project setup I discovered a number of excellent resources. I'd highly recommend checking them out to learn more about bgfx and Dear ImGui.

• bgfx - bgfx main repo.
• bgfx docs - extensive docs covering much of bgfx's API.
• bkaradzic/bgfx.cmake (originally widberg/bgfx.cmake) - a complimentary repo to add CMake support to bgfx (used by this repo).
• hello-bgfx (tutorial) - a great intro to bgfx and covers most of the code in the main.cpp of this repo.
• bgfx-ubuntu(tutorial) - another great tutorial on bgfx (showing how to get setup on Ubuntu).
• minimal-bgfx - a similar repo to this one only using premake and git submodules instead of CMake and with no Dear ImGui.
• dear-imgui - Dear ImGui main repo - lots of documentation and examples are available there.
• cmakefied - a complimentary repo to add CMake support to imgui (originally used by this repo but now replaced with a simpler repo called imgui.cmake, similar in design to bgfx.cmake mentioned above).

Special Thanks

• Бранимир Караџић (@bkaradzic) for the excellent bgfx
• Omar Cornut (@ocornut) for the brilliant Dear ImGui
• Widberg/MissingBitStudios for the bgfx CMake support
• Tamas Kenez for the Dear ImGui CMake support
• Richard Gale (@richardg4) for the bgfx implementation for Dear ImGui
• Phil Peron (@pperon) and Sandeep Nambiar (@_sandeepnambiar) for the great bgfx setup tutorials.
• sudo-carson for laying the ground work for integrating Emscripten into the project. See this PR for all the details.