mirror of
https://github.com/eliasstepanik/imgui-rs.git
synced 2026-01-11 05:28:35 +00:00
170 lines
6.8 KiB
Markdown
170 lines
6.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
|
|
|
|
The core of imgui-rs consists of:
|
|
|
|
- [`imgui`](./imgui): High-level safe API
|
|
- [`imgui-sys`](./imgui-sys): Low-level unsafe API (automatically generated)
|
|
|
|
Next, we provide two example renderers, and two example backend platform implementations:
|
|
|
|
- [`imgui-winit-support`](./imgui-winit-support): Backend platform implementation that uses the `winit` crate
|
|
- [`imgui-sdl2-support`](./imgui-sdl2-support): Backend platform using SDL2
|
|
- [`imgui-glow-renderer`](./imgui-glow-renderer): Renderer implementation that uses the `glow` crate
|
|
- [`imgui-glium-renderer`](./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`](./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`](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)
|
|
4. [`imgui-gfx-renderer`](https://github.com/imgui-rs/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](https://crates.io) either using search or the ["dependents" page](https://crates.io/crates/imgui/reverse_dependencies) (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
|
|
|
|
```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.
|