Irrlicht Binding for IMGUI

Shortcuts: [Kanban Board] - [Devlopers Blog] - [Last Version] - [HowToStart]

ATTENTION: The version on the master branch is unstable. For a stable version please look at Latest Version News.

Index

• Introduction
• Latest Version News
• Example Images
• How to Start
• Preparations
• Embed IrrIMGUI into your Application
• Build the Library
• HelloWorld Example
• Further Examples
• API Documentation
• Version History

<a name="Introduction"></a>Introduction

The goal of IrrIMGUI is to provide a render engine for the IMGUI system that works together with Irrlicht.

• Irrlicht is an easy to learn and very fast 3D graphic engine, that supports OpenGL and DirectX.
• IMGUI is an Immediate Mode GUI system, that allows users to draw complex GUI widgets very easily. Furthermore, I think it has a very nice and modern default graphic style.

Of course IMGUI is not as complex like CEGUI. But for small application it is the ideal solution to have a very potential user interface with just some lines of code. However if you need a complex user interface with scripted widgets and events, and a highly adaptable template system, you should use CEGUI instead. But take care, you will end up with much more code and dependencies.

Following Features are supported so far:

• An Irrlicht bases render engine, that uses high level Irrlicht functions to draw the GUI elements.
• A native OpenGL renderer for test purposes and as a fall-back solution.
• An out of the box working Event Receiver for Irrlicht to bind mouse and keyboard events to the GUI.
• The input event handling for IMGUI can be easily customized to bind new input devices like joystick and another key-types to the GUI.
• Full support for different TTF fonts and font sizes.
• Support for drawing Irrlicht Image objects (IImage) inside the GUI.
• Support for drawing Irrlicht Texture objects (ITextrue) inside the GUI (thus you can render 3D content directly into GUI elements).

<a name="LatestVersionNews"></a>Latest Version

Upcomming: master-branch (unstable not tested yet)

Highlights

• nothing planned

Fixes

• nothing planned

Dependency Versions

• IMGUI 1.46
• Irrlicht 1.8.3
• Other versions may work as well, but they are not tested.

24.10.2015: Version 0.3.1 (Download Source) (Download Binaries)

Fixes

• Switched off IMGUI memory leak detection in Demo example to prevent false negative (see #10).
• Fixed case sensitive related errors, where headers are not found.

Dependency Versions

• IMGUI 1.46
• Irrlicht 1.8.3
• Other versions may work as well, but they are not tested.

Tested Build Variants

• Visual C++ 2015 (64bit): debug, static library
• Visual C++ 2015 (64bit): debug, shared library
• Visual C++ 2015 (64bit): release, static library
• Visual C++ 2015 (64bit): release, shared library
• Visual C++ 2015 (32bit): debug, static library
• Visual C++ 2015 (32bit): debug, shared library
• Visual C++ 2015 (32bit): release, static library
• Visual C++ 2015 (32bit): release, shared library
• Visual C++ 2013 (64bit): debug, static library
• Visual C++ 2013 (64bit): debug, shared library
• Visual C++ 2013 (64bit): release, static library
• Visual C++ 2013 (64bit): release, shared library
• Visual C++ 2013 (32bit): debug, static library
• Visual C++ 2013 (32bit): debug, shared library
• Visual C++ 2013 (32bit): release, static library
• Visual C++ 2013 (32bit): release, shared library
• MinGW (32bit): debug, static library
• MinGW (32bit): debug, shared library
• MinGW (32bit): release, static library
• MinGW (32bit): release, shared library
• MinGW (64bit): debug, static library
• MinGW (64bit): debug, shared library
• MinGW (64bit): release, static library
• MinGW (64bit): release, shared library
• Intel 16.0 (with MSVC 2015) (64bit, Win7): debug, static library
• Intel 16.0 (with MSVC 2015) (64bit, Win7): debug, shared library
• Intel 16.0 (with MSVC 2015) (64bit, Win7): release, static library
• Intel 16.0 (with MSVC 2015) (64bit, Win7): release, shared library
• GCC (64bit, Linux): debug, static library
• GCC (64bit, Linux): debug, shared library
• GCC (64bit, Linux): release, static library
• GCC (64bit, Linux): release, shared library
• Visual C++ 2015 (64bit - native OpenGL GUI renderer): debug, shared library
• MinGW (32bit - native OpenGL GUI renderer): release, static library
• GCC (64bit, Linux - native OpenGL GUI renderer): release, shared library

<a name="ExampleImages"></a>Example Images

A picture is worth a thousand Words. So I will show you some examples:

This is a simple control interface created with IMGUI (example program 02.AnotherWindow).

IMGUI supports also TTF fonts (example program 03.DifferentFonts).

With the Irrlicht IMGUI binding you can draw every IImage object to the GUI (example program 05.DragNDrop).

You can also draw a render target texture to the GUI (example program 06.RenderWindow).

<a name="HowToStart"></a> How to Start

<a name="HowToStart_Preparations"></a> Preparations

• You need a compiled Irrlicht library. Please test with the Irrlicht examples, if the library works as expected.
• Download the Irrlicht IMGUI binding (IrrIMGUI): Download
• Download the latest version of IMGUI and copy all files from the ZIP into the directory <IrrIMGUI-Path>/dependency/IMGUI The IrrIMGUI and IMGUI files are compiled together to a single shared or static library file.
• When you want to compile IrrIMGUI as library, you need CMake to generate the makefiles or project file you want to use

<a name="HowToStart_ApplicationEmbedded"></a> Possibility 1: Embed IrrIMGUI into your Application

There are two ways how you can use IrrIMGUI. The first way is to embed all source files into your application and build it together with your project.

• For this you simply need to create the following directory structure in your project:

 <Your-Project-Path>/
 + lib_includes/
 |+ IMGUI/
 |+ IrrIMGUI/
 + lib_source/
 |+ IrrIMGUI/

• Copy the source files from <IrrIMGUI-Path>/source to <Your-Project-Path>/lib_source/IrrIMGUI

• Copy the header files from <IrrIMGUI-Path>/includes/IrrIMGUI to <Your-Project-Path>/lib_includes/IrrIMGUI

• Copy the *.cpp and *.h files from <IrrIMGUI-Path>/dependency/IMGUI to <Your-Project-Path>/lib_includes/IMGUI

• Setup the path <Your-Project-Path>/lib_includes/ as include search directory

• Setup the preprocessor defines to compile IrrIMGUI as static library (_IRRIMGUI_STATIC_LIB_)

• Setup the preprocessor define _IRRIMGUI_SUBDIR_IRRLICHT_INCLUDE_ if your project includes Irrlicht like #include <Irrlicht/irrlicht.h> and not like #include <irrlicht.h>

• Setup the following preprocessor defines if you want:

• _IRRIMGUI_NATIVE_OPENGL_ to use the native OpenGL driver instead of the Irrlicht driver (test and fall-back solution)

• _IRRIMGUI_FAST_OPENGL_TEXTURE_HANDLE_ to use in the native OpenGL driver a dirty but very fast hack to determine the OpenGL texture ID from an ITexture object (this feature might be broken for other Irrlicht versions than the tested one)

<a name="HowToStart_BuildTheLibrary"></a> Possibility 2: Build the Library

The second way is to build a shared or static library. This library will contain the Irrlicht IMGUI binding and the IMGUI System. The build tool CMake supports a build on many different platforms and with many different compilers. You can use CMake from command line or - more convenient for an individual configuration - with a graphical user interface called cmake-gui. I will explain the cmake-gui build process to you, since I expect that the CMake command line tools are anyway for experts that know how to build a library with CMake.

• Start a command shell with a proper compiler setup and with the CMake binary directory inside your path variable (Visual Studio for example has a batch file that setups all variables and paths for your compiler: e.g. VsDevCmd.bat).

• Goto your IrrIMGUI directory and start the program cmake-gui

• At top of the CMake GUI window you can enter two paths "Where is the source code" and "Where to build the binary"

• Enter in the first text field "Where is the source code" the path to the IrrIMGUI library (the root directory of this library where also CMakeLists.txt is located)

• Enter in the second text field "Where to build the binary" the path where the temporary build files should be stored. For example <IrrIMGUI-Path>/build/vc64/debug/shared In this way you can have different build paths for different compilers and bu