Crate imgui_winit_support

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:

1. Initialize a WinitPlatform instance
2. Attach it to a winit Window
3. Pass events to the platform (every frame)
4. Call frame preparation callback (every frame)
5. Call render preparation callback (every frame)

Complete example for winit 0.20+ (without a renderer)

use imgui::Context;
use imgui_winit_support::{HiDpiMode, WinitPlatform};
use std::time::Instant;
use winit::event::{Event, WindowEvent};
use winit::event_loop::{ControlFlow, EventLoop};
use winit::window::{Window};

let mut event_loop = EventLoop::new();
let mut window = Window::new(&event_loop).unwrap();

let mut imgui = Context::create();
// configure imgui-rs Context if necessary

let mut platform = WinitPlatform::init(&mut imgui); // step 1
platform.attach_window(imgui.io_mut(), &window, HiDpiMode::Default); // step 2

let mut last_frame = Instant::now();
let mut run = true;
event_loop.run(move |event, _, control_flow| {
    match event {
        Event::NewEvents(_) => {
            // other application-specific logic
            last_frame = imgui.io_mut().update_delta_time(last_frame);
        },
        Event::MainEventsCleared => {
            // other application-specific logic
            platform.prepare_frame(imgui.io_mut(), &window) // step 4
                .expect("Failed to prepare frame");
            window.request_redraw();
        }
        Event::RedrawRequested(_) => {
            let ui = imgui.frame();
            // application-specific rendering *under the UI*

            // construct the UI

            platform.prepare_render(&ui, &window); // step 5
            // render the UI with a renderer
            let draw_data = ui.render();
            // renderer.render(..., draw_data).expect("UI rendering failed");

            // application-specific rendering *over the UI*
        },
        Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
            *control_flow = ControlFlow::Exit;
        }
        // other application-specific event handling
        event => {
            platform.handle_event(imgui.io_mut(), &window, &event); // step 3
            // other application-specific event handling
        }
    }
})

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 with 0.25.
• The winit-24 feature supports winit versions 0.24. This is on by default, so to use any other version you need to disable this crates default features.
• The winit-23 feature uses winit versions compatible with 0.23.
• The winit-22 feature uses winit versions compatible with 0.22.
• The winit-20 feature should support winit either 0.20 or winit 0.21.
• The winit-19 feature should support winits older than 0.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-24.

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:

[dependencies.imgui-winit-support]
version = "0.6"
features = ["winit-$YOUR_VERSION_HERE"]
default-features = 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.

Structs

WinitPlatform

winit backend platform state

Enums

HiDpiMode

DPI factor handling mode.