# imgui-rs: Rust bindings for Dear ImGui

[![Build Status](https://github.com/imgui-rs/imgui-rs/workflows/ci/badge.svg)](https://github.com/imgui-rs/imgui-rs/actions)
[![Latest release on crates.io](https://meritbadge.herokuapp.com/imgui)](https://crates.io/crates/imgui)
[![Documentation on docs.rs](https://docs.rs/imgui/badge.svg)](https://docs.rs/imgui)
[![Wrapped Dear ImGui Version](https://img.shields.io/badge/Dear%20ImGui%20Version-1.79-blue.svg)](https://github.com/ocornut/imgui)

(Recently under new maintenance, things subject to change)

![Hello world](hello_world.png)

```rust
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](https://github.com/Gekkio/imgui-rs/issues/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

```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 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](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 http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://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.