imgui 0.10.0

High-level Rust bindings to dear imgui
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# imgui-rs: Rust bindings for Dear ImGui

[![Build Status](https://github.com/imgui-rs/imgui-rs/workflows/ci/badge.svg)](https://github.com/imgui-rs/imgui-rs/actions)
[![Latest release on crates.io](https://img.shields.io/crates/v/imgui.svg)](https://crates.io/crates/imgui)
[![Documentation on docs.rs](https://docs.rs/imgui/badge.svg)](https://docs.rs/imgui)
[![Wrapped Dear ImGui Version](https://img.shields.io/badge/Dear%20ImGui%20Version-1.89.2-blue.svg)](https://github.com/ocornut/imgui)

![Hello world](hello_world.png)

```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.57**. 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.