imgui-rs: Rust bindings for Dear ImGui
Still fairly experimental!
Minimum Rust version: 1.38
Wrapped Dear ImGui version: 1.75
.size
.build;
new
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 thewinit-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 andim_str!
macro for defining and passing null-terminated UTF-8 to Dear ImGui, which doesn't accept Rust&str
/String
values. See issue #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
Main examples are located in the imgui-examples directory.
# At the reposity root
Examples for the gfx backend are under the imgui-gfx-examples directory.
Note to Windows users: You will need to use the MSVC ABI version of the Rust compiler along with its associated dependencies to build this libary and run the examples.
How to contribute
-
Change or add something
-
Make sure you're using the latest stable Rust
-
Run rustfmt to guarantee code style conformance
-
Open a pull request in Github
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Uses Dear ImGui and 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.