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 experiment.

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 libraries but contains ~~instructions on how to download and install them~~ a CMake script to download and install them so this project can use them.

Warning: There is a little bit of setup required. Please see the prerequisites below.

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 .

Before attempting to build this project all third party dependencies (SDL, bgfx and imgui) must be downloaded and installed (CMake now takes care of this with ExternalProject_Add). To achieve this CMake must be installed on your system (repo tested with CMake version 3.15).

Note: The libraries are self contained in the repo and are not installed to the system.

Please see the third-party README for full instructions on how to do this.

Do not proceed to Build Instructions until you've done this.

Build Instructions

Once all third party libraries have been downloaded and installed, follow these build instructions to compile the repo.

Shaders for bgfx also must be compiled to be loaded by the application (the starter has an incredibly simple shader supporting vertex colours).

Info: A configure.bat and configure.sh file are provided (mainly as an exmaple) to run the CMake configure commands. Ninja was chosen as the generator for these as it's consistent across macOS, Linux and Windows, any generator should work though. There's also configure-vs.bat for generating a Visual Studio solution.

Windows

Run ./configure.bat located in the root directory to generate the build files required for the project.
Run cmake --build build/debug and/or cmake --build build/release to compile the project.
Run ./compile-shaders-win.bat located in the root directory to build the shaders.
Launch the application by running build\debug\sdl-bgfx-imgui-starter.exe or build\release\sdl-bgfx-imgui-starter.exe.

macOS

Run ./configure.sh located in the root directory to generate the build files required for the project.
Run cmake --build build/debug and/or cmake --build build/release 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/sdl-bgfx-imgui-starter or ./build/release/sdl-bgfx-imgui-starter.

Linux

Run ./configure.sh located in the root directory to generate the build files required for the project.
Run cmake --build build/debug and/or cmake --build build/release 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/sdl-bgfx-imgui-starter or ./build/release/sdl-bgfx-imgui-starter.

Emscripten (Windows/macOS/Linux)

Run ./configure-emscripten.<bat/sh> from the root directory.
Run cmake --build build/debug-emscripten and/or cmake --build build/release-emscripten.
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).
Start a local server (easiest way to do this is with python3 -m http.server).
Go to localhost:8000 in a browser and open build/<debug/release>-emscripten/sdl-bgfx-imgui-starter.html.

Info: On Windows it may be necessary to run the command-line/terminal as Administrator.

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
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 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 (used by this repo)

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.

shalomfriss / sdl-bgfx-imgui-starter Goto Github PK