Crate easy_imgui

source ·
Expand description

Crate for easy integration of the Dear ImGui library.

This crate is a bind to the Dear ImGui library only. There is also a matching rendering library, easy-imgui-renderer, that renders the UI using OpenGl, and a matching window-integrated library, easy-imgui-window, that enables to build a full desktop application in just a few lines.

If you don’t know where to start, then start with the latter. Take a look at the examples. The simplest easy-imgui program would be something like this:

use easy_imgui_window::{
    easy_imgui as imgui,
    MainWindow,
    MainWindowWithRenderer,
    winit::event_loop::EventLoopBuilder,
};

// The App type, this will do the actual app. stuff.
struct App;

impl imgui::UiBuilder for App {
    // There are other function in this trait, but this is the only one
    // mandatory and the most important: it build the UI.
    fn do_ui(&mut self, ui: &imgui::Ui<Self>) {
        ui.show_demo_window(None);
    }
}

fn main() {
    // Create a `winit` event loop.
    let event_loop = EventLoopBuilder::new().build().unwrap();
    // Create a `winit` window.
    let main_window = MainWindow::new(&event_loop, "Example").unwrap();
    // Create a `easy-imgui` window.
    let mut window = MainWindowWithRenderer::new(main_window);

    // Create the app object.
    let mut app = App;

    // Run the loop.
    event_loop.run(move |event, w| {
        // Do the magic!
        let res = window.do_event(&mut app, &event, w);
        // If the user requested to close the app, you should consider doing that.
        if res.is_break() {
            w.exit();
        }
    }).unwrap();
}

§Alternatives

This crate is similar to imgui-rs, and it is inpired by it, but with a few key differences:

  • It doesn’t use any C++-to-C api generator, as rust-bindgen is able to import simple C++ libraries directly.
  • It is lower level, there are fewer high-level abstractions over the ImGui API. This means that:
    • This API is less Rusty than imgui-rs’s.
    • If you know how to use Dear ImGui, then you know how to use easy-imgui.
    • It is far easier to upgrade to new Dear ImGui versions.

§Features

These are the available features for this crate:

  • freetype: Uses an external freetype font loader for Dear ImGui, instead of the embedded stb_truetype library.
  • docking: Uses the docking branch of Dear ImGui. Note that this is considered somewhat experimental.

§Usage

It is easier to use one of the higher level crates [easy-imgui-window] or [easy-imgui-renderer]. But if you intend to render the UI yourself, then you can use this directly.

These are the main pieces of this crate:

  • Context: It represents the ImGui context. In DearImgui this is a global variable. Here it is a thread-local variable. Still, since it is implicit in most API calls, most uses of this type are unsafe. If you use [easy-imgui-window] or [easy-imgui-renderer] you will rarely need to touch this type directly.
  • Ui: A frame that is being built. Most ImGui functions are members of Ui.
  • UiBuilder: A trait that your application implements do build your user interface.

If you want to use this library directly, just create a Context, set up its properties, and when you want to render a frame do Context::set_current and then CurrentContext::do_frame.

If you use one of the helper crates then you will just implement UiBuilder and get a Ui for free.

§Conventions

This crate follows a series of naming conventions to make the API more predictable, particularly with the Ui member functions:

  • A Pushable is any value that can be made active by a push function and inactive by a corresponding pop function. Examples are styles, colors, fonts…
  • A Hashable is any value that can be used to build an ImGui hash id. Ideally there should be one of these everywhere, but the Dear ImGui API it not totally othogonal here…
  • A function without special prefix or suffix does the same thing as its Dear ImGui counterpart. For example Ui::button calls ImGui_Button.
  • A function name that contains the with word takes a function that is called immediately. It corresponds to a pair of *Begin and *End functions in Dear ImGui. The function is called between these two functions. The value returned will be that of the function.
    • If the function is called based on some condition, such as with ImGui_BeginChild, then there will be another function with prefix with_always_ that takes a function with a bool argument opened: bool, that can be used if you need the function to be called even if the condition is not met.
  • A function name that ends as _config will create a builder object (with the must_use annotation). This object will have a few properties to be set and a build or a with function to create the actual UI element.
  • Most builder object have a push_for_begin function, that will set up the pushable to be used only for the begin part of the UI. This is useful for example to set up the style for a window but not for its contents.

When a function takes a value of type String this crate will usually take a generic impl IntoCStr. This is an optimization that allows you to pass either a String, a &str, a CString or a &CStr, avoiding an extra allocation if it is not really necessary. If you pass a constant string and have a recent Rust compiler you can pass a literal CStr with the new syntax c"hello".

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

  • Hashable
    Represents any type that can be converted to a Dear ImGui hash id.
  • IntoCStr
    Represents any type that can be converted into something that can be deref’ed to a &CStr.
  • Pushable
    Any value that can be applied with a push function and unapplied with a pop function.
  • UiBuilder
    The main trait that the user must implement to create a UI.

Functions§

  • im_to_v2
    Helper function to create a Vector2.
  • im_vec2
    Helper function to create a ImVec2.
  • to_v2
    Helper function to create a Vector2.
  • v2_to_im
    Helper function to create a ImVec2.
  • vec2
    Helper function to create a Vector2.

Type Aliases§