Skip to main content

helios::imgui

Dear ImGui integration for the helios engine modules.

Overview​

helios::imgui provides a debug/developer UI layer on top of Dear ImGui. It combines a platform-agnostic backend interface, a GLFW+OpenGL backend, overlay/widget orchestration, log forwarding, and ready-to-use widgets for runtime diagnostics.

Features​

  • Platform-agnostic ImGuiBackend abstraction
  • GLFW+OpenGL backend for Dear ImGui frame setup and draw-data submission
  • Central ImGuiOverlay for rendering multiple widgets per frame
  • Engine render-system adapter for invoking the overlay from the runtime update loop
  • Docking-enabled overlay support
  • Base ImGuiWidget interface for custom developer tools
  • Log sink bridge from the helios logging system to an ImGui console
  • Built-in FPS, log-console, and main-menu widgets
  • Optional legacy camera-control widget behind a CMake option

Module surface​

AreaPublic modules / APIs
Backend abstractionImGuiBackend
GLFW/OpenGL backendImGuiGlfwOpenGLBackend
Overlay orchestrationImGuiOverlay
Runtime systemshelios.imgui.systems, systems::ImGuiOverlayRenderSystem
Widget interfaceImGuiWidget
Logging integrationImGuiLogSink, widgets::LogWidget
Widgetshelios.imgui.widgets, FpsWidget, LogWidget, MainMenuWidget
Aggregatorhelios.imgui

Usage​

C++ module​

import helios.imgui;

Overlay architecture​

ImGuiBackend defines the frame lifecycle used by the overlay. Concrete implementations call Dear ImGui platform/renderer backends in newFrame() and submit ImDrawData in renderDrawData().

ImGuiGlfwOpenGLBackend initializes a Dear ImGui context for a helios GLFW window entity and enables keyboard navigation and docking. It resolves the native GLFW window through GLFWWindowHandleComponent in the platform world.

ImGuiOverlay::forBackend() returns the singleton overlay for a backend. Widgets are registered with addWidget() and are drawn in registration order; the overlay does not take ownership, so widget instances must outlive their registration.

systems::ImGuiOverlayRenderSystem adapts an ImGuiOverlay to the engine runtime system interface and calls ImGuiOverlay::render() during its update.

Built-in widgets include:

  • widgets::FpsWidget for FPS metrics, frame-time history, and frame-pacer control
  • widgets::LogWidget for scope-aware, filterable log output
  • widgets::MainMenuWidget for docking, transparency, style, and debug-menu controls

ImGuiLogSink forwards helios log messages into widgets::LogWidget.

The legacy widgets::CameraWidget can be included in builds with HELIOS_IMGUI_ENABLE_LEGACY_CAMERA_WIDGET=ON.

CMake​

Use as a local sibling/subdirectory module:

add_subdirectory(path/to/helios-imgui)
target_link_libraries(your_target PRIVATE helios::imgui)

Build locally:

cmake -S . -B build
cmake --build build

When installed/package-export support is enabled, consume from another project:

find_package(helios-ecs CONFIG REQUIRED)
find_package(helios-engine CONFIG REQUIRED)
find_package(helios-glfw CONFIG REQUIRED)
find_package(helios-imgui CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE helios::imgui)

Configure a consumer against an installed prefix:

cmake -S . -B build -DCMAKE_PREFIX_PATH="/path/to/helios-prefix"
cmake --build build

Package export generation is controlled by HELIOS_IMGUI_ENABLE_PACKAGE and is disabled by default for local sibling-repository development.

Development​

Run the regular CMake build from the repository root:

cmake -S . -B build
cmake --build build

Enable the optional legacy camera widget when needed:

cmake -S . -B build -DHELIOS_IMGUI_ENABLE_LEGACY_CAMERA_WIDGET=ON
cmake --build build

The default build excludes legacy camera/gamepad UI that still depends on old scene/input APIs or has not yet been ported to the split repository layout.