# imgui-rs: Rust bindings for Dear ImGui
[](https://github.com/imgui-rs/imgui-rs/actions)
[](https://crates.io/crates/imgui)
[](https://docs.rs/imgui)
[](https://github.com/ocornut/imgui)
(Recently under new maintenance, things subject to change)
```rust
Window::new("Hello world")
.size([300.0, 100.0], Condition::FirstUseEver)
.build(&ui, || {
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
- imgui: High-level safe API
- imgui-winit-support: Backend platform implementation that uses the `winit`
crate (latest by default, but earlier versions are supported via feature flags)
- imgui-glow-renderer: Renderer implementation that uses the `imgui` crate
- imgui-glium-renderer: Renderer implementation that uses the `glium` crate
- imgui-sys: Low-level unsafe API (automatically generated)
Additionally, the following are no longer maintained, but might work still:
- imgui-gfx-renderer: Renderer implementation that uses the `gfx` crate (_not
the new gfx-hal crate_)
## 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 (backend platform)
- Optional support for the freetype font rasterizer
## Minimum Support Rust Version (MSRV)
The MSRV for `imgui-rs` and all of the backend crates is **1.54**. 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.
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-glow-renderer`, which will increasingly replace
`glium`, 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
```bash
git clone https://github.com/imgui-rs/imgui-rs
cd imgui-rs
git submodule update --init --recursive
```
Main examples are located in the `imgui-examples` directory.
```bash
# 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.
```bash
cd imgui-gfx-examples
cargo test
cargo run --example gfx_hello_world
cargo run --example gfx_test_window
```
Note to Windows users: You will need to use the _MSVC ABI_ version of the Rust
compiler along with its associated
[dependencies](https://www.rust-lang.org/en-US/downloads.html#win-foot) 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
```bash
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](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
at your option.
Uses [Dear ImGui](https://github.com/ocornut/imgui) and
[cimgui](https://github.com/cimgui/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.