Sol::Tutorials

Sol on Immediate Mode GUIs (IMGUI)

Note: the permanent address to this tutorial is http://iki.fi/sol/imgui/ - please use that as a link.

00 - Introduction

Immediate Mode GUIs. If you've stumbled here you either already know what's this about, or you're curious about this term. I'm going to assume the latter.

So what is it all about?

In typical GUI applications you create a bunch of widgets, they get displayed somehow, you query the widgets for information, you send messages and data to said widgets, and finally clean things up after you're done. Some parts of the above is usually done using some kind of visual editor, but the result is usually tons and tons of code all over the place.

This is ok for most applications, but not so convenient for games or other frame-by-frame realtime applications. So, instead of having one place for init, another for ui callbacks, and a third for cleanup, IMGUI can be as simple as this:


if (button(GEN_ID, 15, 15)) 
{
  button_was_pressed();
}

In practise things get a little bit more complicated, but not much.

The magic here is that the call to button will perform everything the widget would be expected to do at any single time, including the rendering of the visible widget. There's a bit of global data that's shared by all of the widgets that enables them to work.

There's no setup phase, but if a widget needs some data to show it's state (say, a scroll bar, text edit field, etc), the state data is owned by the host application and not the widget. This is surprisingly handy and performance-friendly, as there's no querying and message-sending involved.

There's also no cleanup required, except for the data that you have allocated yourself. The widgets only exist when they're called, so you'll need to ask for them each frame you want to use them.

Nothing is ever simply positive, and IMGUI does have its problems. The most obvious one is that it's just about as anti-OOP as you can get, so it may feel wrong for you. Other problems are related to the fact that the widgets don't really exist except when they are queried, and as such things like automatic layouts or keyboard focus get somewhat more difficult.

A relatively high frame rate is also required, but a low-framerate UI is never fun to use in any case.

As IMGUIs are a "new old" invention (console apps have done things pretty much the same way from day one), some solutions to problems I'm providing here may not be the most optimal ones.

In this tutorial we'll go through building of a very simple (but fully functional) IMGUI library, which, although it is implemented with SDL, can be easily applied to other environments.

So, first, go to Sol's SDL tutorial and set up an SDL development environment.

(Alternatively, you can download a zip with pre-built win32 binaries for all the chapters.)

After that, you can journey onwards to 01 - Groundwork..

Problems? Ideas? Try the forums. Any comments etc. can be emailed to me.

Legalese, for those who want to know:

Feel free to use this tutorial for personal education.
You have my blessing for using the techniques and source code from this tutorial in whatever way you wish. Since corporations keep patenting obvious things, it's entirely possible that I'm covering patented things, but in my opinion, everything I talk about is, or should be, general knowledge.
You can take copies of these pages for your personal use.
Please don't start any unofficial mirrors.
Feel free to use this tutorial as part of educational material in a schools or any other kind of educational institution, as long as:

If this tutorial is used in some school or other kind of educational institution (in full or in part), please let me know, both of the planned use and the results, so I can keep improving it. Publishable quotes are appreciated!

While effort has been made to make this tutorial as flawless as possible, some mistakes are bound to creep in. This is a fact of life and I'd rather not be held liable for any problems. Please let me know if you find something that's wrong!