Skip to content

Latest commit

 

History

History
342 lines (283 loc) · 16.7 KB

imgui.md

File metadata and controls

342 lines (283 loc) · 16.7 KB

Dear ImGui on BUI: C++, C, Python and Rust

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.

C++

#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).

C

The C API follows cimgui / dear_bindings conventions:

  • ImGui::Button is ImGui_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() returns ImGuiIO*); const ImVec2& is a plain ImVec2.
  • ImGui_Text(fmt, ...) and the other printf-style functions keep their ...; the ...V variants take a va_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).

Python

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)); None passes NULL (imgui.begin("Window") has no close button). Pure outputs are returned: h, s, v = imgui.color_convert_rgb_to_hsv(1, 0, 0).
  • ImVec2 / ImVec4 arguments are tuples; results are imgui.Vec2 / imgui.Vec4 named 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 a str of 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_BAR and the C++ name imgui.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 and ImVectors 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 in frame closes the window and propagates. imgui.HeadlessApp renders 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.

Rust

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 as cimgui.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. sys is re-exported at the crate root, so imgui::ImGuiWindowFlags_NoTitleBar and imgui::ImVec2 work.
  • the safe layer: button(label) / button_ex(label, size) like C; &str for strings, &mut T for in/out values (Option<&mut T> where C++ accepts NULL), &mut [f32; 3] for arrays, slices for (pointer, count) pairs, &mut String for input_text*, impl Into<ImVec2> ([x, y], (x, y)) for vectors; methods on the structs (draw_list.add_line(...), clipper.step()); constructors return Owned<T> (dropped with X_Delete): ImGuiTextFilter::new_ex("x").
  • references returned by imgui (get_io(), get_style(), draw lists) are 'static in 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 in frame closes the window and resumes from run() / 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.

Images as textures

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.

Headless rendering and tests

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.

Blender widgets

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.

Coverage

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 ...V functions taking a va_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 / *ScalarN widgets (DragScalar, SliderScalar, InputScalar... use the typed drag_float, input_int ...), MemFree, ImGuiStorage::SetVoidPtr, ImGuiStoragePair(key, void*), ImFontAtlas::AddFontFromMemoryTTF / AddFontFromMemoryCompressedTTF (use add_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, and InputText's user callback (its buffer callback is used internally to grow strings);
  • ImFontGlyphRangesBuilder::AddRanges / BuildRanges, ImGuiSelectionBasicStorage::GetNextSelectedItem (pointer-to-pointer).

Regenerating

py -3 -I bindings/imgui/gen/gen.py

The 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.

Limitations

  • 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_ASSERT is 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.