imgui-rs: Rust bindings for Dear ImGui

ui.window("Hello world")
    .size([300.0, 100.0], Condition::FirstUseEver)
    .build(|| {
        ui.text("Hello world!");
        ui.text("こんにちは世界！");
        ui.text("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

The core of imgui-rs consists of:

• imgui: High-level safe API
• imgui-sys: Low-level unsafe API (automatically generated)

Next, we provide two example renderers, and two example backend platform implementations:

• imgui-winit-support: Backend platform implementation that uses the winit crate
• imgui-sdl2-support: Backend platform using SDL2
• imgui-glow-renderer: Renderer implementation that uses the glow crate
• imgui-glium-renderer: Renderer implementation that uses the glium crate

Each of these contain an examples folder showing their usage. Check their respective Cargo.toml to find compatible versions (e.g imgui-glow-renderer/Cargo.toml the [dependencies] describes the compatible glow version and [dev-dependencies] describes the compatible glutin version)

Finally the imgui-examples folder contains examples of how to use the imgui crate itself - this covers general topics like how to show text, how to create buttons, etc - and should be applicable to usage with any backend/renderer.

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
• Easy integration with glow/ glium
• Easy integration with winit and sdl2 (backend platform)
• Optional support for the freetype font rasterizer and the docking branch

Minimum Support Rust Version (MSRV)

The MSRV for imgui-rs and all of the backend crates is 1.70. We update our MSRV periodically, and issue a minor bump for it.

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.

imgui-rs is not tied to any particular renderer or platform.

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

We provide the following renderers as an official source (ie, they will always be up to date and working): imgui-glow-renderer and imgui-glium-renderer.

Additionally, we provide the following backends as an official source (ie, they will always be up to date and working): imgui-winit-support and imgui-sdl2-support.

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-glow-renderer, which will increasingly replace glium.

Additionally, there are other libraries which provide other kinds of renderers, which may be out of date with imgui-rs releases, but might work well for your use case:

1. imgui-wgpu
2. imgui-d3d12-renderer
3. imgui-dx11-renderer
4. imgui-gfx-renderer: Deprecated (no longer maintained beyond imgui-rs v0.8). Renderer implementation that uses the gfx crate (not the new gfx-hal crate)
5. Many more can be found on crates.io either using search or the "dependents" page (the "depends on" text indicates if the crate has been updated for current versions of imgui-rs)

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/imgui-rs/imgui-rs
cd imgui-rs

Main examples are located in the imgui-examples directory. These can be run like so:

# At the reposity root
cargo test

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

Examples for the Glow renderer are under the imgui-glow-renderer/examples/ directory. These can be run the same way as any other examples:

cargo test

cargo run --example glow_01_basic

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 https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://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.