Integrating Dear ImGui in unity builds

Dear Imgui is an awesome C/C++ immediate mode graphical user interface (GUI) made by ocornut. It provides just about every widget you might need, buttons, color pickers, plots and many, many more. It’s also fast and super easy to use.

Here’s a screenshot of someone’s game using Dear ImGui.

Cool uh?. It’s easy to integrate into your project. The official documentation says integration should take you less than 3 hours. That’s a lot of features and awesomeness for such a short amount of time.

I personally build my projects using unity builds(also called single translation unit compilation). I could not find any guide on how to setup dear imgui for this type of build system.

So here’s how i did it.

What are unity builds?

The standard way of building C/C++ applications is to build each .c/.cpp file separately (each instance is called a translation unit) and link all of them at the linker stage producing the executable.

Unity build’s basic idea is to include every .c/.cpp source file in a single file, and after the preprocessor runs you have just one huge file to compile. Unity builds also have faster compilation time, even while rebuilding the whole project each time. I have seen codebases bigger than 150000 lines compile in a second. really.

1
2
3
4
5
6
7
8

#include "my_other_file.cpp"
#include "my_other_file2.cpp"
#include "my_other_file3.cpp"

int main()
{
    // My program...
}

1

jsanchez@scarlet:~$ cl main.cpp

If you are not compiling your code like this, you don’t need to follow this guide. Head over to the official integration guide.

Copying files to your project

Start by downloading Dear ImGui. We are going to select a few source code files from the zip and copy them to our project, feel free to extract it wherever you prefer.

ImGui is meant to be used on many operating systems, alongside many platform libraries and every major rendering api. In order to do its job it needs to read keyboard/mouse/gamepad input, upload textures/buffers to the gpu and render. There’s a lot of glue code to be done here. Luckily there are many “backends” ready for you to use.

In my case i’m using libSDL for my platform code and OpenGL 3.3 as my rendering api. So i need to use the two following backends imgui_impl_sdl and imgui_ imgui_impl_opengl3. You can find all available backends inside the backends directory.

Now, create a folder inside your project to hold the Dear ImGui files. Copy the following files from the root directory of the Dear ImGui zip file.

imconfig.h
imgui.h
imgui.cpp
imgui_draw.cpp
imgui_demo.cpp
imgui_internal.h
imgui_tables.cpp
imgui_widgets.cpp
imstb_rectpack.h
imstb_textedit.h
imstb_truetype.h

Also copy the following files from the backends directory. If you are not using libSDL and OpenGL you will need to replace the following files with whatever files you need.

imgui_impl_opengl3.cpp
imgui_impl_opengl3.h
imgui_impl_opengl3_loader.h
imgui_impl_sdl.h
imgui_impl_sdl.cpp

Remember to add the new directory holding this files to the project’s include path.

We are now ready to open our text editor, and because we are using unity builds:

Instead of doing this.

1
2
3

#include "imgui.h"
#include "imgui_impl_sdl.h"
#include "imgui_impl_opengl3.h"

We do this!

1
2
3
4
5
6
7

#include "imgui.cpp"
#include "imgui_tables.cpp"
#include "imgui_widgets.cpp"
#include "imgui_draw.cpp"
#include "imgui_demo.cpp" // You don't need this file, i use it as gui reference
#include "imgui_impl_opengl3.cpp"
#include "imgui_impl_sdl.cpp"

We are almost ready to use Dear ImGui. There’s just one more problem.

OpenGL loader clash

OpenGL is generally implemented in the video driver, and before using it you need to query the driver for function pointers. ImGui has it’s own loader but it’s not a replacement for a full opengl loader like glad. Since you now have two loaders, your code will not compile because there will be multiple function pointer redefinitions.

To solve this #define IMGUI_IMPL_OPENGL_LOADER_CUSTOM before you include your OpenGL loader.

1
2

#define IMGUI_IMPL_OPENGL_LOADER_CUSTOM
#include "glad.c"

You are now ready to write some code. You need to write some minimal boilerplate code to get ImGui up and running. I recommend checking the examples directory inside ImGui’s zip file and running ImGui’s example demo window to get an idea of what can be done. I hope this helps.

See you next time!