imgui-docking-rs: Rust bindings for Dear ImGui

This is a fork of the https://github.com/Gekkio/imgui-rs repo, adding support for docking from this repo https://github.com/rasky/imgui-rs/tree/docking, with some updates. This repo also has a basic safe api for the dearimgui DockBuilder.

This repo stays in lock step with the master branch of Gekkio/imgui-rs, but with changes that comes from the docking branch in dearimgui.

To use docking:

• enable it in the config.

let mut imgui = imgui::Context::create();
// ...
imgui.io_mut().config_flags |= imgui::ConfigFlags::DOCKING_ENABLE;

• then if you want to use the Dock builder.

imgui::Window::new(im_str!("Viewport")).build(&ui, || {});
imgui::Window::new(im_str!("NodeGraph")).build(&ui, || {});
imgui::Window::new(im_str!("Properties")).build(&ui, || {});
imgui::Window::new(im_str!("Outliner")).build(&ui, || {});

imgui::Dock::new().build(|root| {
    root.size([500_f32, 500_f32]).position([0_f32, 0_f32]).split(
        imgui::Direction::Left,
        0.7_f32,
        |left| {
            left.dock_window(im_str!("Viewport"));
            left.dock_window(im_str!("NodeGraph"));
        },
        |right| {
            right.dock_window(im_str!("Properties"));
            right.dock_window(im_str!("Outliner"));
        },
    )
});

Still fairly experimental!

Minimum Rust version: 1.40

Wrapped Dear ImGui version: 'docking' branch (commit aa8e09d7f1481641792e3bb6419acda896af62ae).

Window::new(im_str!("Hello world"))
    .size([300.0, 100.0], Condition::FirstUseEver)
    .build(&ui, || {
        ui.text(im_str!("Hello world!"));
        ui.text(im_str!("こんにちは世界！"));
        ui.text(im_str!("This...is...imgui-rs!"));
        ui.separator();
        let mouse_pos = ui.io().mouse_pos;
        ui.text(format!(
            "Mouse Position: ({:.1},{:.1})",
            mouse_pos[0], mouse_pos[1]
        ));
    });

Main library crates

• imgui: High-level safe API
• imgui-glium-renderer: Renderer implementation that uses the glium crate
• imgui-gfx-renderer: Renderer implementation that uses the gfx crate (not the new gfx-hal crate)
• imgui-winit-support: Backend platform implementation that uses the winit crate (0.22 by default, but 0.19-0.21 are supported via feature flags)
• imgui-sys: Low-level unsafe API (automatically generated)

Features

• Bindings for Dear ImGui that can be used with safe Rust. Note: API coverage is not 100%, but will keep improving over time.
• Builder structs for use cases where the original C++ library uses optional function parameters
• &ImStr / ImString types and im_str! macro for defining and passing null-terminated UTF-8 to Dear ImGui, which doesn't accept Rust &str / String values. See issue #7 for more information and justification for this design.
• Easy integration with Glium / pre-ll gfx (renderer)
• Easy integration with winit (backend platform)

Choosing a backend platform and a renderer

Almost every application that uses imgui-rs needs two additional components in addition to the main imgui crate: a backend platform, and a renderer.

The backend platform is responsible for integrating imgui-rs with the operating system and its window management. Its responsibilities include the following:

• Handling input events (e.g. keyboard, mouse) and updating imgui-rs state accordingly
• Passing information about the OS window (e.g. size, DPI factor) to imgui-rs
• Updating the OS-side mouse cursor when imgui-rs requests it

The renderer is responsible for taking generic, renderer-agnostic draw lists generated by imgui-rs, and rendering them using some graphics API. Its responsibilities include the following:

• Rendering using vertex/index buffers and command lists
• Handling of DPI factors and scissor rects
• Texture management

The most tested platform/renderer combination is imgui-glium-renderer + glium + imgui-winit-support + winit, but this is not the only possible combination. There's also imgui-gfx-renderer, and you can find additional 3rd party crates that provide a wider support for more libraries (e.g. raw OpenGL, SDL2). You can also write your own support code if you have a more advanced use case, because imgui-rs is not tied to any specific graphics / OS API.

Compiling and running the demos

git clone https://github.com/Gekkio/imgui-rs
cd imgui-rs
git submodule update --init --recursive

Main examples are located in the imgui-examples directory.

# At the reposity root
cd imgui-examples
cargo test

cargo run --example hello_world
cargo run --example test_window
cargo run --example test_window_impl

Examples for the gfx backend are under the imgui-gfx-examples directory.

cd imgui-gfx-examples
cargo test

cargo run --example hello_world
cargo run --example test_window

Note to Windows users: You will need to use the MSVC ABI version of the Rust compiler along with its associated dependencies to build this libary and run the examples.

How to contribute

1. Change or add something

2. Make sure you're using the latest stable Rust

3. Run rustfmt to guarantee code style conformance

   rustup component add rustfmt
   cargo fmt

4. Open a pull request in Github

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Uses Dear ImGui and cimgui.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.