Dear ImGui Module
GX ships bindings for Dear ImGui 1.92.9b (the docking branch) through the cimgui C wrapper, plus backends that run it on a sokol or a raylib window.
| Module | What it is |
|---|---|
cimgui | The whole ImGui API: 1524 functions, 1066 enum members, the commonly used structs |
cimgui_sokol | Backend for sokol.app + sokol.gfx (wraps sokol’s own sokol_imgui.h) |
cimgui_raylib | Backend for raylib (input, cursors, clipboard, rlgl drawing) |
ImGui is C++, so these modules compile with clang (@compiler("clang") is set
for you). The ImGui sources are compiled as part of your program; expect a
few seconds on each build.
A complete program (sokol, with docking)
import sokol.app
import sokol.gfx
import sokol.glue
import cimgui
import cimgui_sokol
var g_speed: f32 = 1.0
var g_clicks: i32 = 0
@c_abi
fn init() {
var gfx_desc: sg_desc
gfx_desc.environment = sglue_environment()
sg_setup(&gfx_desc)
gx_imgui_sokol_setup(true) // true: enable docking
}
@c_abi
fn event(ev: *sapp_event) {
gx_imgui_sokol_handle_event(ev)
}
@c_abi
fn frame() {
gx_imgui_sokol_new_frame()
// The whole window is a dock space; the central node stays see-through.
igDockSpaceOverViewport(0, null, ImGuiDockNodeFlags_PassthruCentralNode, null)
if (igBegin("Controls", null, 0)) {
igTextUnformatted("clicked {g_clicks} times", null)
igSliderFloat("Speed", &g_speed, 0.0, 4.0, "%.2f", 0)
if (igButton("Click me", vec2{120.0, 0.0})) { g_clicks++ }
}
igEnd()
var pass: sg_pass
pass.action.colors[0].load_action = 1 // SG_LOADACTION_CLEAR
pass.swapchain = sglue_swapchain()
sg_begin_pass(&pass)
// ... your own sokol drawing ...
gx_imgui_sokol_render() // ImGui on top, inside the pass
sg_end_pass()
sg_commit()
}
@c_abi
fn cleanup() {
gx_imgui_sokol_shutdown()
sg_shutdown()
}
fn main() {
var desc: sapp_desc
desc.init_cb = init
desc.frame_cb = frame
desc.event_cb = event
desc.cleanup_cb = cleanup
desc.width = 1280
desc.height = 720
desc.window_title = "tool"
sapp_run(&desc)
}
examples/56_cimgui_sokol.gx is the fuller version. For raylib see
the raylib backend and examples/55_cimgui_raylib.gx.
How the API maps to GX
The function, enum and struct names are ImGui’s C names, unchanged, so the ImGui documentation and the demo window source apply directly.
| C | GX |
|---|---|
ImVec2, ImVec4 | vec2, vec4 (the same type, so vector math and swizzles work) |
const char* | cstr; a GX str converts implicitly |
char* buf (text input) | *c_char: declare var buf: c_char[256], pass &buf[0] |
bool*, float*, int* | *bool, *f32, *i32: pass &variable |
float v[3], float col[4] | *f32: pass &v.x of a vec3 / vec4, or &arr[0] |
flags and enums (ImGuiWindowFlags_...) | i32 constants, combined with ` |
ImGuiIO*, ImGuiStyle*, ImGuiViewport*, ImGuiDockNode*, ImDrawData*, … | typed pointers with readable and writable fields |
other struct pointers (ImGuiContext*, ImDrawList*, ImFont*) | opaque *void |
| callbacks | *void: pass null, or a @c_abi fn |
fmt, ... functions | C variadics |
var io: *ImGuiIO = igGetIO_Nil()
io.ConfigFlags = io.ConfigFlags | ImGuiConfigFlags_NavEnableKeyboard
var style: *ImGuiStyle = igGetStyle()
style.WindowRounding = 6.0
style.Colors[ImGuiCol_WindowBg] = vec4{0.08, 0.09, 0.11, 1.0}
Functions that ImGui overloads get cimgui’s suffixed names, for example
igBeginChild_Str / igBeginChild_ID and igGetIO_Nil.
Text and formatting
igText("%d items", count) is a C variadic call. The simplest way to show
formatted text is GX interpolation with the unformatted call:
igTextUnformatted("{count} items, {fps} fps", null)
Docking
Turn it on with gx_imgui_sokol_setup(true) (or set
ImGuiConfigFlags_DockingEnable on igGetIO_Nil().ConfigFlags yourself), and
call igDockSpaceOverViewport every frame before your windows. Panels can
then be dragged by their title bar onto other panels or window edges. ImGui
saves the layout to imgui.ini in the working directory.
A default layout is built with the DockBuilder functions:
fn build_layout(dock_id: u32) {
var vp: *ImGuiViewport = igGetMainViewport()
igDockBuilderRemoveNode(dock_id)
igDockBuilderAddNode(dock_id, ImGuiDockNodeFlags_PassthruCentralNode | ImGuiDockNodeFlags_DockSpace)
igDockBuilderSetNodeSize(dock_id, vp.Size)
var right: u32 = 0
var rest: u32 = 0
igDockBuilderSplitNode(dock_id, ImGuiDir_Right, 0.25, &right, &rest)
igDockBuilderDockWindow("Properties", right)
igDockBuilderFinish(dock_id)
}
Call it once with the id returned by igDockSpaceOverViewport, for example
on the first run when there is no imgui.ini.
To draw your own content (a canvas, a 3D view) in the middle, leave the central node empty and read its rectangle:
var node: *ImGuiDockNode = igDockBuilderGetCentralNode(dock_id)
if (node != null) {
// node.Pos and node.Size are the free area, in ImGui coordinates
}
A window docked into the central node gets an opaque background from the
dock host, so ImGuiWindowFlags_NoBackground does not make it see-through.
Multi-viewport (dragging a panel out into its own OS window) needs a
multi-window platform backend. sokol_app has one window, so it is not
available with cimgui_sokol; the raylib backend does not implement it
either.
cimgui_sokol
| Function | Purpose |
|---|---|
gx_imgui_sokol_setup(docking) | Call in the init callback, after sg_setup(). Creates the ImGui context |
gx_imgui_sokol_shutdown() | Call in the cleanup callback, before sg_shutdown() |
gx_imgui_sokol_new_frame() | Start of the frame callback: size, time and DPI scale from sokol_app, then igNewFrame() |
gx_imgui_sokol_render() | Inside a render pass, after your own drawing: igRender() and draw |
gx_imgui_sokol_handle_event(ev) | From the event callback. Returns true when ImGui consumed the event |
gx_imgui_sokol_wants_mouse() / gx_imgui_sokol_wants_keyboard() | True while ImGui is using that input |
simgui_imtextureid(view) / simgui_imtextureid_with_sampler(view, smp) | ImGui texture id for a sokol_gfx texture view |
A sokol texture view is shown with:
igImage(ImTextureRef_c{null, simgui_imtextureid(view)}, vec2{256.0, 256.0}, vec2{0.0, 0.0}, vec2{1.0, 1.0})
With sapp_desc.high_dpi set, ImGui coordinates are logical points; multiply
by sapp_dpi_scale() to get framebuffer pixels for sg_apply_viewport or
sgp_viewport.
cimgui_raylib
import raylib
import cimgui
import cimgui_raylib
fn main() {
InitWindow(1280, 720, "tool")
SetTargetFPS(60)
gx_imgui_raylib_init()
var clicks = 0
while (!WindowShouldClose()) {
gx_imgui_raylib_begin() // input + igNewFrame()
if (igBegin("Controls", null, 0)) {
if (igButton("Click me", vec2{120.0, 0.0})) { clicks++ }
}
igEnd()
BeginDrawing()
ClearBackground(DARKGRAY)
gx_imgui_raylib_end() // igRender() + draw, on top
EndDrawing()
}
gx_imgui_raylib_shutdown()
CloseWindow()
}
| Function | Purpose |
|---|---|
gx_imgui_raylib_init() | Call once after InitWindow(). Creates an ImGui context if none exists |
gx_imgui_raylib_shutdown() | Call before CloseWindow() |
gx_imgui_raylib_begin() | Feed input, then igNewFrame() |
gx_imgui_raylib_end() | igRender(), then draw. Call between BeginDrawing() and EndDrawing(), after your own drawing |
gx_imgui_raylib_new_frame() / gx_imgui_raylib_render() | The same two halves without the ImGui calls |
gx_imgui_raylib_wants_mouse() / gx_imgui_raylib_wants_keyboard() | True while ImGui is using that input |
The raylib backend uses the OpenGL texture id as the ImGui texture id:
var tex = ImTextureRef_c{null, (u64)texture.id}
igImage(tex, vec2{256.0, 256.0}, vec2{0.0, 0.0}, vec2{1.0, 1.0})
// A RenderTexture is stored bottom-up: flip V with uv0 = vec2{0.0, 1.0}, uv1 = vec2{1.0, 0.0}.
For docking with raylib, set ImGuiConfigFlags_DockingEnable on
igGetIO_Nil().ConfigFlags after gx_imgui_raylib_init().
What is not bound
73 functions are skipped: the va_list variants (igTextV, …) and
internal functions that pass ImRect or ImColor by value.
Updating the vendored sources
modules/cimgui/c/VENDOR.md and modules/cimgui_sokol/c/VENDOR.md record the
upstream commits. After replacing the sources:
python modules/cimgui/tools/patch_cimgui.py # ImVec2 / ImVec4 = vec2 / vec4
python modules/cimgui/tools/gen_bindings.py # regenerates gx/cimgui_*.gx