From d22f763ff04f09e0e425e36843d8b2e0ec1299db Mon Sep 17 00:00:00 2001 From: Joonas Javanainen Date: Sat, 7 Sep 2019 20:07:28 +0300 Subject: [PATCH] Update readme --- README.markdown | 126 +++++++++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 45 deletions(-) diff --git a/README.markdown b/README.markdown index 4a36627..bf01cca 100644 --- a/README.markdown +++ b/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 [![Build Status](https://travis-ci.org/Gekkio/imgui-rs.svg?branch=master)](https://travis-ci.org/Gekkio/imgui-rs) [![Latest release on crates.io](https://meritbadge.herokuapp.com/imgui)](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.