IrrIMGUI Documentation

Welcome to the IrrIMGUI project

• Visit the GitHub repository: Repository
• Screenshots: Example Pictures
• Download this library: Download
• HowTo build this library: Build process
• Online API documentation: Doxygen
• Example description: Examples

IrrIMGUI API documentation

Index

• Most Important API Bookmarks
• Code Snippets
  • Getting started
    • Step 1: Include Header Files
    • Step 2: Initialize Irrlicht Device and GUI
    • Step 3: Start GUI Frame
    • Step 4: Render GUI
    • Step 5: Delete GUI
  • Use custom Event Receiver
    • Method 1: Inherit from standard Event Receiver
    • Method 2: An Event Receiver from the scratch
  • Use TTF fonts
    • Step 1: Load Fonts
    • Step 2: Compile Fonts
    • Step 3: Activate a Font
    • Optional: Reset Fonts
  • Use images
    • Step 1: Create Irrlicht Image
    • Step 2: Create GUI Texture
    • Step 3: Use image in GUI
    • Step 4: Free-up image memory
  • Use Irrlicht textures
    • Step 1: Create GUI Texture
    • Optional: Update GUI Texture
    • Step 2: Free-up GUI texture memory
  • Dependency Injection
    • Step 1: Create your own factory
    • Step 2: Setting up your factory
    • Step 3: Reset factory to default
  • IIMGUIHandle Mock
    • Step 1: Enable- and Disable Mock
    • Step 2: Expecting calls
  • Memory Leak Detection
• Additional Project Links

Most Important API Bookmarks

• Class IrrIMGUI::IIMGUIHandle - Use this class as main handle to the Irrlicht IMGUI Binding
• Class IrrIMGUI::CIMGUIEventReceiver - A standard Event Receiver for Irrlicht, that passes all Mouse and Keyboard events to the GUI
• Class IrrIMGUI::IGUITexture - A general texture object for drawing images to the GUI

Code Snippets

Getting started

Full explanation: Example 1: HelloWorld

Step 1: Include header files

// include Irrlicht and IrrIMGUI header
#include <IrrIMGUI/IrrIMGUI.h>
#include <IrrIMGUI/IncludeIrrlicht.h>

Step 2: Initialize Irrlicht Device and GUI

using namespace irr;
using namespace IrrIMGUI;

// Irrlicht OpenGL Settings
SIrrlichtCreationParameters IrrlichtParams;
IrrlichtParams.DriverType    = video::EDT_OPENGL;
IrrlichtParams.WindowSize    = core::dimension2d<u32>(1024, 800);
IrrlichtParams.Bits          = 32;
IrrlichtParams.Fullscreen    = false;
IrrlichtParams.Stencilbuffer = true;
IrrlichtParams.AntiAlias     = 16;
IrrlichtParams.Vsync         = false;

// Create standard event receiver for the IrrIMGUI
CIMGUIEventReceiver EventReceiver;  
IrrlichtParams.EventReceiver = &EventReceiver;

// Create Irrlicht device
IrrlichtDevice * const pDevice = createDeviceEx(IrrlichtParams);

// Create GUI object
IIMGUIHandle * const pGUI = createIMGUI(pDevice, &EventReceiver);

Step 3: Start GUI Frame

Inside the Main-Loop:

// create the GUI elements
pGUI->startGUI();
ImGui::Begin("My first Window");
ImGui::Text("Hello World!");
if (ImGui::Button("Exit", ImVec2(40, 20)))
{
  pDevice->closeDevice();
}
ImGui::End();

Step 4: Render GUI

Inside the Main-Loop:

// render your Irrlicht scene
pSceneManager->drawAll();

// render the GUI
pGUI->drawAll();

Step 5: Delete GUI

After the Main-Loop:

pGUI->drop();

Use custom Event Receiver

Method 1: Inherit from standard Event Receiver

• Inherit from the IrrIMGUI::CIMGUIEventReceiver class
• Overwrite method IrrIMGUI::CIMGUIEventReceiver::OnEvent to handle the event first

  class CMyOwnEventReceiver : private IrrIMGUI::CIMGUIEventReceiver
  {
    bool OnEvent(const irr::SEvent & rEvent)
    {
      // do your own stuff with rEvent...
  
      // when rEvent has not been consumed by your game logic pass it to the CIMGUIEventReceiver class
      return CIMGUIEventReceiver::OnEvent(rEvent);
    }
  };

• Don't forget to call IrrIMGUI::CIMGUIEventReceiver::OnEvent when you want to pass this Event to the GUI
• Give a pointer of this custom Event Receiver while creating the GUI handle object and the Irrlicht Device

Method 2: An Event Receiver from the scratch

• Create an Event Receiver class that inherits from irr::IEventReceiver and IrrIMGUI::CIMGUIEventStorage
• Overwrite the irr::IEventReceiver::OnEvent method to handle the event
• If you want to pass any input event information to the GUI, just write to the corresponding variables of IrrIMGUI::CIMGUIEventStorage
• Give a pointer of this custom Event Receiver while creating the GUI handle object and the Irrlicht Device

Use TTF fonts

Full explanation: Example 2: Different Fonts

Step 1: Load Fonts

// load the Cousine-Regular.ttf file from the media directory
ImFont *pCousine16 = pGUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 16.0f);
ImFont *pCousine24 = pGUI->addFontFromFileTTF("../../media/Cousine-Regular.ttf", 24.0f);

• Hint: Look-up for further methods to load fonts in the GUI Handle class ( LoadFonts )

Step 2: Compile Fonts

pGUI->compileFonts();

Step 3: Activate a Font

Inside the Main-Loop:

ImGui::Begin("Different Fonts", NULL, ImGuiWindowFlags_ShowBorders);
ImGui::Text("Default Font");

ImGui::PushFont(pCousine16);
ImGui::Text("Cousine-Regular.ttf; 16px");
ImGui::PopFont(); // switch back to last font (in this case default)

ImGui::PushFont(pCousine24);
ImGui::Text("Cousine-Regular.ttf; 24px");
ImGui::PopFont(); // switch back to last font (in this case default)

ImGui::End();

Optional: Reset Fonts

pGUI->resetFonts();

Use images

Full explanation: Example 4: Using Images

Step 1: Create Irrlicht Image

irr::video::IVideoDriver * const pDriver = pDevice->getVideoDriver();

irr::video::IImage * pSoyuz  = pDriver->createImageFromFile("../../media/Soyuz.jpg");
irr::video::IImage * pSpaceX = pDriver->createImageFromFile("../../media/SpaceX.jpg");

Step 2: Create GUI Texture

IrrIMGUI::IGUITexture * pSoyuzTex  = pGUI->createTexture(pSoyuz);
IrrIMGUI::IGUITexture * pSpaceXTex = pGUI->createTexture(pSpaceX);

• Hint: Look-up for further methods to create textures in the GUI Handle class ( CreateTextures )

Step 3: Use image in GUI

Inside the Main-Loop:

ImGui::Begin("Images");

ImGui::Image(pSoyuzTex, ImVec2(200.0f, 132.0f));

ImGui::Separator();

ImGui::Image(pSpaceXTex, ImVec2(200.0f, 132.0f));

ImGui::End();

Step 4: Free-up image memory

pSoyuz->drop();
pSpaceX->drop();
pGUI->deleteTexture(pSoyuzTex);
pGUI->deleteTexture(pSpaceXTex);

Use Irrlicht textures

Full explanation: Example 4: Using Images

Step 1: Create GUI Texture

// Create Render Target texture in Irrlicht
video::ITexture * const pRenderTarget = pDriver->addRenderTargetTexture(core::dimension2d<u32>(384, 300), "Moon");

// create GUI Texture handle
IGUITexture * const pRenderTextureID  = pGUI->createTexture(pRenderTarget);

• Hint: Look-up for further methods to create textures in the GUI Handle class ( CreateTextures )

Optional: Update GUI Texture

Inside the Main-Loop:

pGUI->updateTexture(pRenderTextureID, pRenderTarget);

Step 2: Free-up GUI texture memory

pGUI->deleteTexture(pRenderTextureID);

Dependency Injection

Full explanation: Unit Testing

Step 1: Create your own factory

IrrIMGUI::IIMGUIHandle * dummyFactory(irr::IrrlichtDevice * pDevice, IrrIMGUI::CIMGUIEventStorage * pEventStorage, IrrIMGUI::SIMGUISettings const * pSettings)
{
  // create an object that is derived from IIMGUIHandle and return the pointer to it...
  return NULL;
}

Step 2: Setting up your factory

IrrIMGUI::Inject::setIMGUIFactory(dummyFactory);

Step 3: Reset factory to default

IrrIMGUI::Inject::setIMGUIFactory();

IIMGUIHandle Mock

Full explanation: Unit Testing

Step 1: Enable- and Disable Mock

Attention: Disable the Mock always inside the tear-down-function.

#include <IrrIMGUI/UnitTest/IIMGUIHandleMock.h>

TEST_GROUP(TestGroupName)
{
  TEST_SETUP()
  {
    IrrIMGUI::UnitTest::IIMGUIHandleMock::enableMock();
  }

  TEST_TEARDOWN()
  {
    IrrIMGUI::UnitTest::IIMGUIHandleMock::disableMock();
  }
};

Step 2: Expecting calls

TEST(TestGroupName, checkCreateAndDestory)
{
  irr::IrrlichtDevice * const pDevice = irr::createDevice(irr::video::EDT_NULL);
  CIMGUIEventStorage EventStorage;
  SIMGUISettings Settings;

  // Expect call to constructor
  mock().expectOneCall("IIMGUIHandleMock::IIMGUIHandleMock")
          .withParameter("pDevice",               pDevice)
          .withParameter("pEventStorage",         &EventStorage)
          .withConstPointerParameter("pSettings", &Settings);

  // Expect call to destructor
  mock().expectOneCall("IIMGUIHandleMock::~IIMGUIHandleMock");

  // ignore everything else (we don't want to be too rigid here)
  mock().ignoreOtherCalls();

  IIMGUIHandle * const pGUI = createIMGUI(pDevice, &EventStorage, &Settings);

  pGUI->drop();
  pDevice->drop();

  return;
}

Memory Leak Detection

Full explanation: Unit Testing

// library includes
#include <IrrIMGUI/Tools/CBasicMemoryLeakDetection.h>

int main(int Arguments, char const ** ppCommandLineList)
{
  IrrIMGUI::Tools::CBasicMemoryLeakDetection MemoryLeakDetection;

  {
    // here is your application code...
  }

  return 0;
}

Additional Project Links

• IMGUI GitHub Project
• IMGUI Wiki
• Irrlicht Project
• Irrlicht Tutorials
• Irrlicht API
• Irrlicht Wiki