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.

ModuleWhat it is
cimguiThe whole ImGui API: 1524 functions, 1066 enum members, the commonly used structs
cimgui_sokolBackend for sokol.app + sokol.gfx (wraps sokol’s own sokol_imgui.h)
cimgui_raylibBackend 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.

CGX
ImVec2, ImVec4vec2, 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, ... functionsC 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

FunctionPurpose
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()
}
FunctionPurpose
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