mirror of
https://github.com/eliasstepanik/imgui-rs.git
synced 2026-01-11 13:38:35 +00:00
Update readme
This commit is contained in:
Joonas Javanainen
parent
6062347643
commit
d22f763ff0
126
README.markdown
126
README.markdown
@ -1,10 +1,10 @@
|
||||
# imgui-rs: Rust bindings for ImGui
|
||||
# imgui-rs: Rust bindings for Dear ImGui
|
||||
|
||||
**Still fairly experimental!**
|
||||
|
||||
Minimum Rust version: 1.36
|
||||
|
||||
Wrapped Dear ImGui version: 1.71
|
||||
Wrapped Dear ImGui version: 1.72b
|
||||
|
||||
[](https://travis-ci.org/Gekkio/imgui-rs)
|
||||
[](https://crates.io/crates/imgui)
|
||||
@ -25,68 +25,104 @@ ui.window(im_str!("Hello world"))
|
||||
})
|
||||
```
|
||||
|
||||
## Currently implemented things
|
||||
## Main library crates
|
||||
|
||||
* Low-level API (imgui-sys)
|
||||
* Renderer for easy integration with [Glium](https://github.com/tomaka/glium) projects (optional)
|
||||
* Parts of high-level API
|
||||
* Not horrible way of defining and passing null-terminated UTF-8 to ImGui.
|
||||
The macro `im_str!` needs to be used most of the time. For more
|
||||
information and justification for this design, please see [issue #7](https://github.com/Gekkio/imgui-rs/issues/7)
|
||||
* Parts of imgui\_demo.cpp reimplemented in Rust as an API usage example (imgui-examples/examples/test\_window\_impl.rs)
|
||||
* 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)
|
||||
|
||||
## Important but unimplemented things
|
||||
## Features
|
||||
|
||||
* Documentation (rustdoc)
|
||||
* Support passing a custom Program to Glium renderer (e.g. from a shader cache, or custom shader)
|
||||
- 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)
|
||||
|
||||
## Core design questions and current choices
|
||||
## Choosing a backend platform and a renderer
|
||||
|
||||
* Closures VS begin/end pairs (current choice: closures)
|
||||
* Mutable references VS return values (current choice: mutable references)
|
||||
* Passing around Ui<'ui> VS passing around &'ui Ui (current choice: Ui<'ui>)
|
||||
* Splitting the API to smaller pieces VS all draw calls in Ui (current choice: all draw calls in Ui)
|
||||
* Builder pattern for optional arguments VS something else (current choice: builder)
|
||||
* Mutation functions in builders VS self-consuming functions in builders (current choice: self-consuming)
|
||||
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
|
||||
|
||||
|
||||
git clone https://github.com/Gekkio/imgui-rs
|
||||
cd imgui-rs
|
||||
git submodule update --init --recursive
|
||||
```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.
|
||||
|
||||
# At the reposity root
|
||||
cd imgui-examples
|
||||
cargo test
|
||||
```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
|
||||
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.
|
||||
|
||||
cd imgui-gfx-examples
|
||||
cargo test
|
||||
```bash
|
||||
cd imgui-gfx-examples
|
||||
cargo test
|
||||
|
||||
cargo run --example hello_world
|
||||
cargo run --example test_window
|
||||
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
|
||||
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. Run rustfmt to guarantee code style conformance
|
||||
2. Make sure you're using the latest stable Rust
|
||||
3. Run rustfmt to guarantee code style conformance
|
||||
|
||||
rustup component add rustfmt
|
||||
cargo fmt
|
||||
```bash
|
||||
rustup component add rustfmt
|
||||
cargo fmt
|
||||
```
|
||||
|
||||
3. Open a pull request in Github
|
||||
4. Open a pull request in Github
|
||||
|
||||
## License
|
||||
|
||||
@ -97,11 +133,11 @@ Licensed under either of
|
||||
|
||||
at your option.
|
||||
|
||||
Uses [ImGui](https://github.com/ocornut/imgui) and [cimgui](https://github.com/cimgui/cimgui).
|
||||
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.
|
||||
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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user