The real Dear ImGui (1.93.1 WIP, vendored in
bindings/imgui/extern/imgui) runs on BUI: BUI's window hosts give it input, BUI's
renderers (software raster, Direct3D 11, OpenGL 3.3) draw it, and it looks like Blender
(Blender's theme colors and metrics, Blender's UI font). The backend itself is described in
bindings/imgui/README.md.
Every public Dear ImGui function and type can be used from four languages:
| Language | What you use | Built by |
|---|---|---|
| C++ | imgui.h + imgui_impl_bui.h |
CMake target bui_imgui |
| C | cimgui.h + cimgui_impl_bui.h (bindings/imgui/c) |
CMake target bui_cimgui |
| Python | import blenderui.imgui as imgui (or bui.imgui) |
CMake target buipy (compiled in) |
| Rust | crate blenderui-imgui (bindings/rust/blenderui-imgui) |
Cargo (blenderui-sys builds the C++ through CMake) |
The C, Python and Rust bindings are generated from imgui.h; see
Regenerating.
#include "imgui.h"
#include "imgui_impl_bui.h"
static void frame(void*) { ImGui::ShowDemoWindow(); }
int main() {
ImGui::CreateContext();
ImGui_ImplBUI_App* app = ImGui_ImplBUI_CreateApp("Dear ImGui on BUI", 1280, 800, frame, nullptr);
ImGui_ImplBUI_RunApp(app); // BUI's message loop until the window closes
ImGui_ImplBUI_DestroyApp(app);
ImGui::DestroyContext();
}Link bui::imgui. Example: examples/imgui_demo.cpp (bui_imgui_demo).
The C API follows cimgui / dear_bindings conventions:
ImGui::ButtonisImGui_Button; methods take the object first:ImDrawList_AddLine(draw_list, p1, p2, col).- C has no default arguments:
ImGui_Button(label)takes the required ones,ImGui_ButtonEx(label, size)all of them. - Overloads get a suffix from the parameter types that differ:
ImGui_PushID(str),ImGui_PushIDInt(int),ImGui_PushIDPtr(ptr),ImGui_MenuItemBoolPtr(...),ImGui_RadioButtonIntPtr(...),ImGui_PushStyleVarVec2(...). - References become pointers (
ImGui_GetIO()returnsImGuiIO*);const ImVec2&is a plainImVec2. ImGui_Text(fmt, ...)and the other printf-style functions keep their...; the...Vvariants take ava_list.- Every struct has its C++ layout (checked by
static_asserts at build time):io->DisplaySize,style->Colors[ImGuiCol_Text],ImVector_ImDrawCmd(Size,Capacity,Data). - Constructors and destructors:
ImGuiListClipper_New(),ImGuiTextFilter_NewEx("x"),X_Delete(obj).
#include "cimgui.h"
#include "cimgui_impl_bui.h"
static void frame(void* user)
{
float* value = (float*)user;
ImGui_ShowDemoWindow();
ImGui_Begin("Hello");
ImGui_SliderFloat("Value", value, 0.0f, 1.0f);
ImGui_Text("%.2f", *value);
ImGui_End();
}
int main(void)
{
float value = 0.5f;
ImGui_CreateContext();
cImGui_ImplBUI_App* app = cImGui_ImplBUI_CreateApp("Hello", 1280, 800, frame, &value, NULL);
cImGui_ImplBUI_RunApp(app);
cImGui_ImplBUI_DestroyApp(app);
ImGui_DestroyContext();
}Link bui::cimgui (CMake). cimgui_impl_bui.h is the backend for C: apps (window or
headless), cImGui_ImplBUI_Init(node, frame, user, config) for a node in an existing BUI
UI, cImGui_ImplBUI_StyleBlender, cImGui_ImplBUI_AbandonFrame (ends a frame that a callback left early on an error), the UI scale, and headless input helpers. Example:
examples/imgui_demo_c.c (bui_imgui_demo_c, --screenshot out.png for headless).
import blenderui.imgui as imgui
state = {"value": 0.5, "text": "Edit me", "opened": True}
def frame():
imgui.show_demo_window()
expanded, state["opened"] = imgui.begin("Hello", state["opened"])
changed, state["value"] = imgui.slider_float("Value", state["value"], 0.0, 1.0)
changed, state["text"] = imgui.input_text("Text", state["text"])
if imgui.button("Reset"):
state["value"] = 0.5
imgui.text("value %.2f" % state["value"])
imgui.end()
imgui.run(frame, title="Hello", size=(1280, 800))pyimgui-style:
- functions in snake_case; an in/out pointer is an argument, and its new value comes back
after the result:
changed, v = imgui.slider_float(...),changed, (r, g, b) = imgui.color_edit3("Color", (r, g, b));NonepassesNULL(imgui.begin("Window")has no close button). Pure outputs are returned:h, s, v = imgui.color_convert_rgb_to_hsv(1, 0, 0). ImVec2/ImVec4arguments are tuples; results areimgui.Vec2/imgui.Vec4named tuples (pos.x).- printf-style functions take one string:
imgui.text("%d items" % n). - lists replace (pointer, count) pairs:
imgui.combo("Combo", current, ["a", "b"]),imgui.plot_lines("Plot", values),draw_list.add_polyline(points, col). input_text*take and return astrof any length (the buffer grows).- one name per overload set, trying each overload in turn:
imgui.push_id("x"),imgui.push_id(3); each also keeps its own name (push_id_int,push_style_var_vec2). - enums:
imgui.WINDOW_NO_TITLE_BARand the C++ nameimgui.ImGuiWindowFlags_NoTitleBar. - structs are objects whose fields have snake_case and C++ names:
imgui.get_io().display_size,io.config_flags |= imgui.CONFIG_NAV_ENABLE_KEYBOARD,io.ini_filename = None,imgui.get_style().colors[imgui.COL_TEXT] = (1, 1, 1, 1),io.fonts.fonts[0]; arrays andImVectors are indexable views. - methods:
imgui.get_window_draw_list().add_line(p1, p2, imgui.im_col32(255, 0, 0)). - constructors:
imgui.ImGuiListClipper(),imgui.ImGuiTextFilter("x"),imgui.ImGuiStorage()(deleted with the Python object). imgui.run(frame, title=..., size=...)opens a BUI window (creating the ImGui context if none is current); an exception inframecloses the window and propagates.imgui.HeadlessApprenders without a window (below).help(imgui.begin)shows the Python signature and the C++ function.
Dear ImGui is compiled into the buipy extension (cmake --build build --target buipy, and
the wheel), not built as a second extension: a process loads one copy of the kit (two copies
registered the Cocoa classes twice on macOS). bui.imgui gets its module from
buipy.imgui_module(), which creates it on first use; it is also importable as _buiimgui.
blenderui-imgui is on crates.io (cargo add blenderui-imgui);
you can also take it from git, or by path from a clone. Add features = ["blender-widgets"] for Blender's widgets.
[dependencies]
blenderui-imgui = "0.2"
# or from git: blenderui-imgui = { git = "https://github.com/ppmpreetham/BUI" }
# or, from a clone: blenderui-imgui = { path = "bindings/rust/blenderui-imgui" }use blenderui_imgui as imgui;
fn main() {
let mut value = 0.5f32;
let mut text = String::from("Edit me");
imgui::run("Hello", [1280, 800], move || {
imgui::show_demo_window();
imgui::begin("Hello");
imgui::slider_float("Value", &mut value, 0.0, 1.0);
imgui::input_text("Text", &mut text);
if imgui::button("Reset") {
value = 0.5;
}
imgui::text(&format!("value {value:.2}"));
if let Some(dl) = imgui::get_window_draw_list() {
let p = imgui::get_cursor_screen_pos();
dl.add_circle_filled([p.x + 10.0, p.y + 10.0], 8.0, imgui::im_col32(71, 114, 179, 255));
}
imgui::end();
});
}cargo run -p blenderui-imgui --example demo (-- --screenshot demo.png headless).
imgui::sys: the raw FFI, generated from the same description ascimgui.h(no bindgen or libclang): every struct with its layout (ImVector<T>, unions, bit fields as storage words), every enum value as a constant, every C function.sysis re-exported at the crate root, soimgui::ImGuiWindowFlags_NoTitleBarandimgui::ImVec2work.- the safe layer:
button(label)/button_ex(label, size)like C;&strfor strings,&mut Tfor in/out values (Option<&mut T>where C++ acceptsNULL),&mut [f32; 3]for arrays, slices for (pointer, count) pairs,&mut Stringforinput_text*,impl Into<ImVec2>([x, y],(x, y)) for vectors; methods on the structs (draw_list.add_line(...),clipper.step()); constructors returnOwned<T>(dropped withX_Delete):ImGuiTextFilter::new_ex("x"). - references returned by imgui (
get_io(),get_style(), draw lists) are'staticin the signatures but only valid while their context lives. imgui::run(title, size, frame),imgui::App::new / headless / with_config: creates the ImGui context if none is current; a panic inframecloses the window and resumes fromrun()/render().
The crate depends on blenderui-sys with its imgui feature, which builds Dear ImGui,
the BUI backend and the C API with the project's CMake files (as for the C kit; a published
crate carries them in csrc/, see scripts/vendor_c.py). Nothing else is downloaded.
ImGui's user textures are BUI textures. Decode any image the kit reads and
get its id: Python tex, w, h = blenderui.image_texture(data) then
imgui.image(tex, (w, h)) and blenderui.texture_free(tex); Rust
blenderui::Image::open(path)?.texture(); C BK_imbuf_texture(ib, 0).
Animated GIF and WebP: Python blenderui.AnimatedTexture(data) (call
update() each frame, draw texture), Rust blenderui::Animation with
Image::update_texture, C BK_anim_next with BK_imbuf_texture_update.
Video: Python tex = clip.texture(tex, w, h) on a blenderui.Video, Rust
Video::texture, C BK_video_texture: the current frame, updated in place;
calling it each frame keeps the video playing.
All three bindings can run Dear ImGui without a window: frames render into an offscreen BUI raster and input is fed the way the window hosts feed it.
with imgui.HeadlessApp(frame, size=(800, 600)) as app:
app.render(3) # request and run 3 frames
app.click(100, 40) # mouse_move / mouse_down / mouse_up / scroll
app.type_text("hello") # key("Return"), key("a", imgui.BK_CTRL)
w, h, pixels = app.pixels() # BGRA bytes; app.save_png("shot.png")C: cImGui_ImplBUI_CreateHeadlessApp, cImGui_ImplBUI_Render, cImGui_ImplBUI_Click,
cImGui_ImplBUI_TypeText, cImGui_ImplBUI_Pixels. Rust: App::headless(size, frame),
app.render(n), app.click(x, y), app.type_text(..), app.pixels().
Tests:
| Test | Runs |
|---|---|
imgui_c_api (ctest) |
bindings/imgui/tests/test_cimgui.c: widgets, tables, list clipper, draw list, popups, IO/style structs, helpers, text filter/storage/text buffer, clicks, a slider, typing |
buipy_imgui (ctest) |
bindings/python/tests/test_imgui.py (unittest): the same from Python, plus drags, the wheel, buffer growth, overload dispatch, struct fields and array views, the demo/metrics/style windows, errors |
cargo test -p blenderui-imgui |
tests/headless.rs: Rust/C++ struct sizes, widgets and input, owned objects, a panic in the frame |
imgui_backend (ctest) |
the backend itself, in C++ (phase 1); with Blender widgets also their interaction (drag steps, Shift, Ctrl snapping, arrows, click / double-click / Ctrl+click to type, relative sliders, drag-toggle) |
imgui_blender_widgets_match_kit (ctest, BUI_IMGUI_BLENDER_WIDGETS=ON) |
examples/imgui_blender_compare.cpp: ImGui's Blender widgets and the kit's native widgets are the same pixels |
The C, Python and C++ tests run in both widget variants; expectations that differ with Blender widgets (sliders do not jump to the pointer, a click types a value) are marked "variant" in them.
Built with -DBUI_IMGUI_BLENDER_WIDGETS=ON (Rust: blenderui-imgui feature
blender-widgets), Dear ImGui's widgets are Blender's widgets: drawn by the BUI kit with
its own widget drawing and handled with Blender's rules where they differ (number fields,
sliders, checkboxes). Nothing changes in the API; the switch is also available at runtime:
| C++ | C | Python | Rust | |
|---|---|---|---|---|
| built with them | ImGui_ImplBUI_HasBlenderWidgets() |
cImGui_ImplBUI_HasBlenderWidgets() |
imgui.has_blender_widgets() |
has_blender_widgets() |
| in use | ImGui_ImplBUI_GetBlenderWidgets() |
cImGui_ImplBUI_GetBlenderWidgets() |
imgui.get_blender_widgets() |
blender_widgets() |
| switch | ImGui_ImplBUI_SetBlenderWidgets(on) |
cImGui_ImplBUI_SetBlenderWidgets(on) |
imgui.set_blender_widgets(on) |
set_blender_widgets(on) |
The widget mapping, the behavior differences and the gaps are in bindings/imgui/blender/README.md.
Counted from bindings/imgui/gen/coverage.json (written by the generator). Dear ImGui
1.93.1 WIP has 399 functions in namespace ImGui (overloads counted separately,
obsolete ones excluded; 14 of them are ...V functions taking a va_list) and 264
methods and constructors on its structs (223 methods, 41 constructors); the bindings
add a default constructor to the 9 structs that declare none.
namespace ImGui |
Methods + constructors | Notes | |
|---|---|---|---|
| C | 399 / 399 | 273 / 273 | 894 C functions with the Ex variants; all 41 structs with their layout, 5 opaque; 737 enum values |
| Python | 366 / 399 (366 / 385 without va_list) |
264 / 273 | 1474 constants (both spellings); fields of all structs |
| Rust FFI | 385 / 399 (all but va_list) |
272 / 273 | 879 of the 894 C functions |
| Rust safe layer | 366 / 399 | 264 / 273 | the rest is in sys |
Not in Python or the Rust safe layer (all are in C and Rust sys):
- the 14
...Vfunctions taking ava_list(use the...ones, or format first); - functions taking an untyped
void*value:PushID(const void*),GetID(const void*),TreeNode/TreeNodeEx/TreePush(const void*, ...), the 8*Scalar/*ScalarNwidgets (DragScalar,SliderScalar,InputScalar... use the typeddrag_float,input_int...),MemFree,ImGuiStorage::SetVoidPtr,ImGuiStoragePair(key, void*),ImFontAtlas::AddFontFromMemoryTTF/AddFontFromMemoryCompressedTTF(useadd_font_from_file_ttf); - functions taking C callbacks: the getter overloads of
Combo,ListBox,PlotLines,PlotHistogram(the list overloads are bound),SetAllocatorFunctions,GetAllocatorFunctions,ImDrawList::AddCallback, andInputText's user callback (its buffer callback is used internally to grow strings); ImFontGlyphRangesBuilder::AddRanges/BuildRanges,ImGuiSelectionBasicStorage::GetNextSelectedItem(pointer-to-pointer).
py -3 -I bindings/imgui/gen/gen.pyThe generator is stdlib-only Python (gen.py, with gen_python.py and gen_rust.py). It
parses bindings/imgui/extern/imgui/imgui.h (comments, preprocessor conditionals, the
IMGUI_API declarations in namespace ImGui, enums and flags, typedefs, structs with
their fields, methods and constructors, default arguments, overloads, fmt, ...,
arrays, callbacks) into bindings/imgui/gen/imgui_api.json, then writes:
| File | |
|---|---|
bindings/imgui/c/cimgui.h, cimgui.cpp |
the C API |
bindings/python/src/buiimgui_gen.inc |
the Python functions, types, field tables and constants |
bindings/rust/blenderui-imgui/src/sys.rs, safe.rs |
the Rust FFI and safe layer |
bindings/imgui/gen/coverage.json |
what each language binds (and why not) |
Hand-written: cimgui_impl_bui.h/.cpp (the backend's C API), the Python runtime
(buiimgui_rt.h: argument parsing, conversions, struct wrappers, array views) and module
(buiimgui_module.cpp: the App type, init), bui/imgui.py (run, HeadlessApp),
the Rust lib.rs (helpers, Owned, the runner), examples and tests.
After updating the vendored Dear ImGui, run the generator and rebuild: the C++ compiler
checks the C struct layouts (static_asserts in cimgui.cpp) and
imgui::sys::layout_mismatches() the Rust ones.
- Dear ImGui's single current context: create apps and call imgui from one thread. Python and Rust references to imgui objects (draw lists, IO, fonts) are borrowed: do not keep them past their context.
- Python objects wrapping imgui structs do not keep the context alive; owned objects
(
imgui.ImGuiListClipper()...) are deleted with the Python object. - In release builds
IM_ASSERTis off and Dear ImGui recovers from most API misuse (io.ConfigErrorRecovery); with assertions on, misuse aborts the process from every language. - The backend's own gaps (IME placement, gamepads, multi-viewports) are listed in bindings/imgui/README.md.