From 2ae1afa15b96d6c1ec55011c3234627c68887cbe Mon Sep 17 00:00:00 2001 From: Jonathan Spira Date: Sun, 29 Sep 2024 21:28:47 -0400 Subject: [PATCH] adding a new readme --- README.md | 64 +++++++++++++++---------------------- imgui/src/lib.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index cd2ce9e..e406bca 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ ui.window("Hello world") }); ``` +`imgui-rs` are the Rust bindings to [Dear ImGui](https://github.com/ocornut/imgui), the standard immediate mode user interface library. + ## Main library crates The core of imgui-rs consists of: @@ -30,12 +32,11 @@ 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: +Next, we provide an example renderer, 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 +- [`imgui-glow-renderer`](https://github.com/imgui-rs/imgui-glow-renderer): Renderer implementation that uses the `glow` crate +- [`imgui-winit-support`](https://github.com/imgui-rs/imgui-winit-support): Backend platform implementation that uses the `winit` crate +- [`imgui-sdl2-support`](https://github.com/imgui-rs/imgui-sdl2-support): Backend platform using SDL2 Each of these contain an `examples` folder showing their usage. Check their respective `Cargo.toml` to find compatible versions (e.g @@ -43,10 +44,7 @@ their respective `Cargo.toml` to find compatible versions (e.g 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. +See below as well for community lead platform and renderer crates. ## Features @@ -54,8 +52,8 @@ be applicable to usage with any backend/renderer. 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) +- Easy integration with `glow` and community integrations with `wgpu` and `glium` +- Easy integration with `winit` and `sdl2` - Optional support for the freetype font rasterizer and the docking branch ## Minimum Support Rust Version (MSRV) @@ -85,54 +83,44 @@ responsibilities include the following: - 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`. +We provide the following renderer as an official source (ie, they will always be up to date and working): `imgui-glow-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`. +The most tested platform/renderer combination is `imgui-glow-renderer` + +`imgui-winit-support` + `winit`, but this is not the only possible +combination. 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) - +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. [`imgui-glium-renderer`](https://github.com/imgui-rs/imgui-glium-renderer): Deprecated implementation that uses the `glium` crate +6. 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: +Examples for `imgui` are in their own crate [`imgui-examples`](https://github.com/imgui-rs/imgui-examples). ```bash +git clone https://github.com/imgui-rs/imgui-examples +cd imgui-examples + # At the reposity root -cargo test +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: +## Windows Platform Notes -```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 +Windows platform users 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. diff --git a/imgui/src/lib.rs b/imgui/src/lib.rs index 8a180a1..1473062 100644 --- a/imgui/src/lib.rs +++ b/imgui/src/lib.rs @@ -1,3 +1,86 @@ +//! `imgui-rs` are the Rust bindings to [Dear ImGui](https://github.com/ocornut/imgui), the standard, +//! battle-tested, immediate mode user-interface library. Although Dear ImGui and `imgui-rs` are under +//! active development, Dear ImGui is extremely production ready, having been used across the software +//! industry to ship small and massive projects. +//! +//! ## Hello World +//! +//! ```no_run +//! # fn render_ui(ui: &mut imgui::Ui) { +//! ui.window("Hello world") +//! .size([300.0, 100.0], imgui::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] +//! )); +//! }); +//! # } +//!``` +//! ## 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` and community integrations with `wgpu` and `glium` +//! - Easy integration with `winit` and `sdl2` +//! - Optional support for the freetype font rasterizer and the docking branch +//! +//! ## Getting Started +//! +//! 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.** +//! +//! ### Backend 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 +//! +//! We provide the following backends: +//! - [`imgui-winit-support`](https://github.com/imgui-rs/imgui-winit-support) +//! - [`imgui-sdl2-support`](https://github.com/imgui-rs/imgui-sdl2-support) +//! +//! 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**. +//! +//! ### Renderer +//! +//! 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 renderer as an official source (ie, it will always be up to date and working): +//! - [`imgui-glow-renderer`](https://github.com/imgui-rs/imgui-glow-renderer) +//! +//! 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. [`imgui-glium-renderer`](https://github.com/imgui-rs/imgui-glium-renderer): Deprecated implementation that uses the `glium` crate +//! 6. 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**. + #![cfg_attr(test, allow(clippy::float_cmp))] #![deny(rust_2018_idioms)] //#![deny(missing_docs)]