This crate provides a winit-based backend platform for imgui-rs.
A backend platform handles window/input device events and manages their state.
Using the library
There are five things you need to do to use this library correctly:
- Initialize a
WinitPlatform
instance - Attach it to a winit
Window
- Pass events to the platform (every frame)
- Call frame preparation callback (every frame)
- Call render preparation callback (every frame)
Complete example for winit 0.20+ (without a renderer)
# // TODO: Remove ignore when only one winit version is used
use Context;
use ;
use Instant;
use ;
use ;
use ;
let mut event_loop = new;
let mut window = new.unwrap;
let mut imgui = create;
// configure imgui-rs Context if necessary
let mut platform = init; // step 1
platform.attach_window; // step 2
let mut last_frame = now;
let mut run = true;
event_loop.run
winit
versions and features.
This crate has several features which control the version of winit which is used.
The following versions are supported, controlled by the listed feature.
- The
winit-25
feature uses winit versions compatible with0.25
. This is on by default, so to use any other version you need to disable this crates default features. - The
winit-24
feature supports winit versions0.24
. - The
winit-23
feature uses winit versions compatible with0.23
. - The
winit-22
feature uses winit versions compatible with0.22
. - The
winit-20
feature should support winit either0.20
or winit0.21
. - The
winit-19
feature should support winits older than0.19
(possibly back to winit 0.16.*, but this isn't regularly tested and may not work).
If multiple winit-*
features are enabled, and it is a debug build (as
determined by debug_assertions
), we will log a warning to stderr during
init. This can be disabled by either turning on the no-warn-on-multiple
feature, fixing the configuration, or disabling debug_assertions
.
Conversely, if no winit-*
features are enabled, we will fail to compile.
This is not an issue generally, as by default we turn on winit-25
.
All of this is in attempt to preserve the additive nature of features (while still helping users notice project configuration issues), however it's done fairly weakly as our this crate's API isn't 100% identical across winit versions.
Using an older winit
version
To use an older version, you must configure default-features = false
in
your Cargo.toml
:
[]
= "0.6"
= ["winit-$YOUR_VERSION_HERE"]
= false
Old winit
compatibility
No guarantee is made on how long this crate will support legacy versions of
winit
, but we'll try to follow these rules:
-
Versions which are still in widespread use in the ecosystem will be supported while that is true (for example, 0.19 at the time of writing is quite old, but used by the most recent version of several popular crates).
-
Versions which are not a significant maintenance burden will be supported (for example, supporting versions older than winit 0.19 given that we support 0.19).
-
Explicitly removing support for a feature-indicated version will be considered a breaking change.
-
Changing the default feature to the new latest
winit
version is not a breaking change.