mirror of
https://github.com/eliasstepanik/imgui-rs.git
synced 2026-01-11 21:48:36 +00:00
147 lines
4.9 KiB
Markdown
147 lines
4.9 KiB
Markdown
# imgui-rs: Rust bindings for Dear ImGui
|
|
|
|
**Still fairly experimental!**
|
|
|
|
Minimum Rust version: 1.38
|
|
|
|
Wrapped Dear ImGui version: 1.75
|
|
|
|
[](https://github.com/Gekkio/imgui-rs/actions)
|
|
[](https://crates.io/crates/imgui)
|
|
[](https://docs.rs/imgui)
|
|
|
|
|
|
|
|
```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.19 by default, but 0.20 is supported via the `winit-20` feature)
|
|
* 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/Gekkio/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.
|