mirror of
https://github.com/eliasstepanik/imgui-rs.git
synced 2026-01-11 21:48:36 +00:00
156 lines
5.8 KiB
Markdown
156 lines
5.8 KiB
Markdown
# 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)
|
|
|
|
|
|
|
|
```rust
|
|
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
|
|
|
|
- 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 `glow` 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_). This can be found at [imgui-rs/imgui-gfx-renderer](https://github.com/imgui-rs/imgui-gfx-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 (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.57**. 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`](https://github.com/Yatekii/imgui-wgpu-rs)
|
|
2. [`imgui-d3d12-renderer`](https://github.com/curldivergence/imgui-d3d12-renderer)
|
|
3. [`imgui-dx11-renderer`](https://github.com/veykril/imgui-dx11-renderer)
|
|
|
|
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
|
|
```
|
|
|
|
Main examples are located in the `imgui-examples` directory. These can be run like so:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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](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.
|