Dear ImGUI Plugin

Plugin Name ImGUIPlugin

ImGUI is used only for game development utilities. It may be possible to use it for the game interface but it may lack some functional.

Important

built-in ImGui::Image(…) is not supported. There is no support for images yet, but it should be possible to implement images basing on Gsage::OgreView.

Creating ImGUI Views in Lua

All ImGui views manipulation must be done using imguiInterface. Registering a simple view is pretty straightforward:

local imguiInterface = require 'imgui.base'

if imguiInterface:available() then

  -- simple function
  imguiInterface:addView("window", function()
    imgui.TextWrapped("Hello world")
  end, true)
end

It is possible to use Lua class for some complicated views:

local imguiInterface = require 'imgui.base'

-- imgui engine stats view
Stats = class(ImguiWindow, function(self, title, docked, open)
  ImguiWindow.init(self, title, docked, open)
  self.fps = 0
  self.frames = 0
  self.elapsedTime = 0
  self.monitor = ResourceMonitor.new(0.1)
  self.stats = self.monitor.stats

  self.handleTime = function(delta)
    self.frames = self.frames + 1
    self.elapsedTime = self.elapsedTime + delta
    if self.elapsedTime >= 1 then
      self.fps = self.frames
      self.frames = 0
      self.elapsedTime = 0
    end
  end
  game:addUpdateListener(self.monitor)
  time.addHandler("stats", self.handleTime, true)
end)

-- render stats
function Stats:__call()
  if self:imguiBegin() then
    imgui.Text("FPS:" .. self.fps)
    imgui.Text("CPU:" .. math.floor(self.stats.lastCPU * 100))
    self:imguiEnd()
  end
end

if imguiInterface:available() then
  local stats = Stats("stats", true)
  imguiInterface:addView("window", stats)
end

Note that this view inherits ImguiWindow. This allows this view to be configured as dockable window by setting docked parameter to true.

ImGui Lua Interface

ImGui interface for Lua differs from the what there is for C++. ImGui relies on pointers to bool, float and other types, but there is no way to pass pointer to primitive types from Lua to C++.

Refer to PlugIns/ImGUI/include/ImguiLuaInterface.h file to see the list of all available methods.

There are some additional utility classes for Ogre:

class OgreView : public EventSubscriber<OgreView>

Allows displaying ogre camera into imgui window.

Lua usage example:

-- create ogre viewport
viewport = imgui.createOgreView("#000000FF")

local textureID = "myOgreView"

-- render camera to texture
local cam = camera:create("free")
cam:renderToTexture(textureID, {
  autoUpdated = false
})

-- set ogre view texture
viewport:setTextureID(textureID)
-- update on each imgui render call
viewport:render(320, 240)

class Gizmo : public EventSubscriber<Gizmo>

Transformation Gizmo, supports move, scale and rotate operations.

Lua usage example:

-- create gizmo
gizmo = imgui.createGizmo()

-- setting target
local render = eal:getEntity("test").render
if render == nil then
  exit(1)
end
gizmo:addTarget(render.root)

-- enable
gizmo:enable(true)

-- render on each ImGUI cycle
gizmo:render(0, 0, 320, 240)

-- changing mode
gizmo.mode = imgui.gizmo.WORLD

-- changing operation
gizmo.operation = imgui.gizmo.ROTATE

-- draw coordinates editor for this gizmo
-- it is separate to make it possible to draw it in the separate window
gizmo:drawCoordinatesEditor(1, 0, 0, "%.3f", 1,
"position",
"scale",
"rotation")

class ImGuiDockspaceRenderer

Dockspace for ImGUI.

Provides alternate methods for Begin and End. Docked view should be surrounded by BeginDock and EndDock methods.

local flags = 0
local active, open = imgui.BeginDockOpen("test", true, flags)
if active and open then
  -- render some view here
  imgui.TextWrapped("Hello World!")
end
imgui.EndDock()

Saving and loading dockspace state:

-- save dock state (will get lua table)
local savedState = imgui.GetDockState()

...

-- restore dock state
imgui.SetDockState(savedState)

Additional imgui global variables: