Table of contents


Related article: Using ImGui with modern C++ and STL


This is the first part of tutorial about Dear ImGui (AKA ImGui) and it’ll show you how to set it up with SFML. The second part will be library agnostic and will talk about common ways of doing stuff in ImGui, some awesome widgets and some useful STL overloads.

ImGui widgets

Different ImGui widgets (taken from ImGui’s github page)


Introduction

Having good content creation (level editor, resource editor, etc.) and debugging tools for your game is very important and can lead to productivity and creativity boost. Here are some examples of tools I managed to make with ImGui for my game:

Level editor Level Editor

Animation editor Animation editor

It was possible to add ability to change members of C++ objects with ImGui by doing some meta template stuff, maybe I’ll write an article about that later!

As you can see there’s a wide range of widgets that ImGui can provide and there are lots of other great examples of how other people use it here.

Dear ImGui and immediate mode GUI concept

Dear ImGui is an immediate mode GUI library which makes making GUI for all kinds of tools very easy.

Immediate mode GUI is a bit different to what people think when they hear “GUI” (“retained mode” is a classic way of doing GUI). Immediate mode GUI is a way of doing GUI which involves creating and drawing widgets in each frame. Widgets doesn’t hold any (or close to none) GUI state. All this stuff actually makes GUI much easier to write in lots of cases. You don’t have to create widget instance and store it somewhere, you just call ImGui::Button and it will return true if the button is pressed. Simple as that. Note that you’ll have to call this function in each frame you want widget to be displayed and processed. At first this concept may seem weird, but shortly it all starts to make sense.

For a great in-depth talk on this concept, I recommend to check out Casey Muratori’s talk on IMGUI.

Back to Dear ImGui. It’s:

  • MIT Licensed
  • Very fast and light
  • Constantly updated and expanded
  • Doesn’t do dynamic allocation/deallocation
  • Very portable – has lots of bindings for different libraries and frameworks
  • Easily expandable

Setting up

Okay, let’s begin!

  1. Use SFML to get a simple window to show up. Follow the “Getting started” tutorial here if you have never done it before.
  2. Download ImGui.
  3. Download ImGui SFML binding and put it into ImGui folder.

    Important: you have to add the contents of imconfig-SFML.h to ImGui’s imconfig.h to get implicit ImVec2 sf::Vector2f conversion working!

  4. Add ImGui folder to your include directories.
  5. Add these files to your build / project:
    • imgui.cpp
    • imgui_draw.cpp
    • imgui-SFML.cpp
    • imgui_demo.cpp
  6. (Optional) If you get linking errors, link OpenGL to your project.

Here’s a complete example of using ImGui and SMFL together.

#include "imgui.h"
#include "imgui-sfml.h"
 
#include <SFML/Graphics/RenderWindow.hpp>
#include <SFML/System/Clock.hpp>
#include <SFML/Window/Event.hpp>
 
int main()
{
    sf::RenderWindow window(sf::VideoMode(640, 480), "");
    window.setVerticalSyncEnabled(true);
    ImGui::SFML::Init(window);
 
    sf::Color bgColor;
 
    float color[3] = { 0.f, 0.f, 0.f };
 
    // let's use char array as buffer, see next part
    // for instructions on using std::string with ImGui
    char windowTitle[255] = "ImGui + SFML = <3";
 
    window.setTitle(windowTitle);
    window.resetGLStates(); // call it if you only draw ImGui. Otherwise not needed.
    sf::Clock deltaClock;
    while (window.isOpen()) {
        sf::Event event;
        while (window.pollEvent(event)) {
            ImGui::SFML::ProcessEvent(event);
 
            if (event.type == sf::Event::Closed) {
                window.close();
            }
        }
 
        ImGui::SFML::Update(window, deltaClock.restart());
 
        ImGui::Begin("Sample window"); // begin window
 
                                       // Background color edit
        if (ImGui::ColorEdit3("Background color", color)) {
            // this code gets called if color value changes, so
            // the background color is upgraded automatically!
            bgColor.r = static_cast<sf::Uint8>(color[0] * 255.f);
            bgColor.g = static_cast<sf::Uint8>(color[1] * 255.f);
            bgColor.b = static_cast<sf::Uint8>(color[2] * 255.f);
        }
 
        // Window title text edit
        ImGui::InputText("Window title", windowTitle, 255);
 
        if (ImGui::Button("Update window title")) {
            // this code gets if user clicks on the button
            // yes, you could have written if(ImGui::InputText(...))
            // but I do this to show how buttons work :)
            window.setTitle(windowTitle);
        }
        ImGui::End(); // end window
 
        window.clear(bgColor); // fill background with color
        ImGui::Render();
        window.display();
    }
 
    ImGui::SFML::Shutdown();
}

You’ll see something like this:

First example

Try to change some stuff. Double click on r/g/b field to set values precisely, or just drag some widgets to change window’s background color. Press the button to change window title. Here, it works!

First example Awesome! Now let’s see how it works.

ImGui is initialized by calling ImGui::SFML::Init function to which you pass your sf::RenderWindow. If you use window and want to use another sf::RenderTarget for drawing, you can do this by passing window as first argument and sf::RenderTarget as the second. ImGui-SFML internally creates a font atlas, but if you want to create and manage it yourself, you can pass sf::Texture pointer when you call Init. You can create default font atlas by calling ImGui::SFML::createFontTexture and passing your sf::Texture in it.

Shutting down is done with ImGui::SFML::Shutdown call which cleans some things up. (Deleting internal font atlas, if it’s used, for example).

There are two phases of using ImGui in your game loop: update and render.

Updating consists of event processing, state update and widget update. Event processing is done by calling ImGui::SFML::ProcessEvent and it’s almost the same as processing SFML events. State update (which is being done by calling ImGui::SFML::Update) updates delta time which ImGui uses internally, so you have to pass it using your delta time clock, as well as mouse coordinates. ImGui::NewFrame is also being called here and you can call ImGui widget creation functions after that. Calling stuff like ImGui::Button or ImGui::Color3Edit updates widgets and it also generates one draw list which is used for rendering later.

Drawing is done with ImGui::Render() call.

You must create all widgets between ImGui::SFML::Update() and ImGui::Render().

If you’re updating more than you draw, then you have two options:

  1. Update ImGui once per render frame.
  2. Update ImGui more than once per render frame (helps for low FPS because with ImGui::Update and all widget calls you can still process your input if you have to update for several times without rendering). There’s one difference: you have to call ImGui::EndFrame() after each update iteration. The problem with this approach is that all widgets still generate render lists even if you don’t draw them which may impact performance (but I’ve never noticed any slowdowns due to ImGui). The issue is currently being addressed and hopefully we’ll get separation from drawing and updating soon.

Important: if you only draw ImGui stuff, don’t forget to call window.resetGLStates() before you render anything. SFML does it for you, if you draw SFML stuff before drawing ImGui, so it’s not needed in this case.

Widgets are easily created by calling corresponding functions (more about them in the next part). For example, you can call ImGui::InputInt and pass a pointer to int there.When you change widget’s value, the integer is changed too. Buttons work pretty easy too – they don’t need callbacks, you just wrap code which you want to call after the button is pressed in if(ImGui::Button(…)) { … } and that’s all you have to do.

Call ImGui::ShowTestWindow somewhere when you create widgets and you’ll get a nice window with lots of examples of ImGui stuff. This is very useful as example of how to do stuff with ImGui. Just look for the thing you want to make in this test window and you’ll easily find how to do it in corresponding part of imgui_demo.cpp.

Useful overloads for SFML

There are also some useful overloads implemented in SFML ImGui binding. For example, you can use ImGui::Image and ImGui::ImageButton with sf::Textures and sf::Sprites! I’ve also defined implicit conversions between ImVec2 and sf::Vector2f, so you can pass sf::Vector2f to ImGui’s functions without needing to cast explicitly.

Conclusion

As you can see, using ImGui is easy and it’s easy to start doing really impressive and useful stuff with it right away. Thank you for reading this tutorial, I hope it was useful and that ImGui will help you make better tools and greater games as the result of having awesome tools.


Follow me on twitter @EliasDaler to not miss the new stuff!