[dependencies]
winit = "0.29.3"For features within the scope of winit, see FEATURES.md.
For features outside the scope of winit, see Are we GUI Yet? and Are we game yet?, depending on what kind of project you're looking to do.
Join us in any of these:
Winit is a window creation and management library. It can create windows and lets you handle events (for example: the window being resized, a key being pressed, a mouse movement, etc.) produced by window.
Winit is designed to be a low-level brick in a hierarchy of libraries. Consequently, in order to show something on the window you need to use the platform-specific getters provided by winit, or another library.
Winit provides the following features, which can be enabled in your Cargo.toml file:
serde: Enables serialization/deserialization of certain types with Serde.x11(enabled by default): On Unix platform, compiles with the X11 backendwayland(enabled by default): On Unix platform, compiles with the Wayland backendmint: Enables mint (math interoperability standard types) conversions.
The Minimum Supported Rust Version (MSRV) of this crate is 1.65. Changes to the MSRV will be accompanied by a minor version bump.
As a tentative policy, the upper bound of the MSRV is given by the following formula:
min(sid, stable - 3)
Where sid is the current version of rustc provided by Debian Sid, and
stable is the latest stable version of Rust. This bound may be broken in the
event of a major ecosystem shift or a security vulnerability.
The exception to this is for the Android platform, where a higher Rust version must be used for certain Android features. In this case, the MSRV will be capped at the latest stable version of Rust minus three. This inconsistency is not reflected in Cargo metadata, as it is not powerful enough to expose this restriction.
All crates in the rust-windowing organizations have the
same MSRV policy.
Note that windows don't appear on Wayland until you draw/present to them.
To run the web example: cargo run-wasm --example web
Winit supports compiling to the wasm32-unknown-unknown target with web-sys.
On the web platform, a Winit window is backed by a <canvas> element. You can
either provide Winit with a <canvas> element, or let Winit
create a <canvas> element which you can then retrieve and
insert it into the DOM yourself.
For example code using Winit with WebAssembly, check out the web example. For information on using Rust on WebAssembly, check out the Rust and WebAssembly book.
The Android backend builds on (and exposes types from) the ndk crate.
Native Android applications need some form of "glue" crate that is responsible for defining the main entry point for your Rust application as well as tracking various life-cycle events and synchronizing with the main JVM thread.
Winit uses the android-activity as a
glue crate (prior to 0.28 it used
ndk-glue).
The version of the glue crate that your application depends on must match the version that Winit depends on because the glue crate is responsible for your application's main entrypoint. If Cargo resolves multiple versions they will clash.
winit glue compatibility table:
| winit | ndk-glue |
|---|---|
| 0.29 | android-activity = "0.5" |
| 0.28 | android-activity = "0.4" |
| 0.27 | ndk-glue = "0.7" |
| 0.26 | ndk-glue = "0.5" |
| 0.25 | ndk-glue = "0.3" |
| 0.24 | ndk-glue = "0.2" |
The recommended way to avoid a conflict with the glue version is to avoid explicitly
depending on the android-activity crate, and instead consume the API that
is re-exported by Winit under winit::platform::android::activity::*
Running on an Android device needs a dynamic system library, add this to Cargo.toml:
[lib]
name = "main"
crate-type = ["cdylib"]All Android applications are based on an Activity subclass and the
android-activity crate is designed to support different choices for this base
class. Your application must specify the base class it needs via a feature flag:
| Base Class | Feature Flag | Notes |
|---|---|---|
NativeActivity |
android-native-activity |
Built-in to Android - it is possible to use without compiling any Java or Kotlin code. Java or Kotlin code may be needed to subclass NativeActivity to access some platform features. It does not derive from the AndroidAppCompat base class. |
GameActivity |
android-game-activity |
Derives from AndroidAppCompat which is a defacto standard Activity base class that helps support a wider range of Android versions. Requires a build system that can compile Java or Kotlin and fetch Android dependencies from a Maven repository (or link with an embedded release of GameActivity) |
For more details, refer to these android-activity example applications.
If your application is currently based on NativeActivity via the ndk-glue crate and building with cargo apk then the minimal changes would be:
- Remove
ndk-gluefrom yourCargo.toml - Enable the
"android-native-activity"feature for Winit:winit = { version = "0.29.3", features = [ "android-native-activity" ] } - Add an
android_mainentrypoint (as above), instead of using the '[ndk_glue::main]proc macro fromndk-macros(optionally add a dependency onandroid_loggerand initialize logging as above). - Pass a clone of the
AndroidAppthat your application receives to Winit when building your event loop (as shown above).
A lot of functionality expects the application to be ready before you start doing anything; this includes creating windows, fetching monitors, drawing, and so on, see issues #2238, #2051 and #2087.
If you encounter problems, you should try doing your initialization inside
Event::Resumed.
Similar to macOS, iOS's main UIApplicationMain does some init work that's required
by all UI related code, see issue #1705. You should consider creating your windows
inside Event::Resumed.
Redox OS has some functionality not present yet, that will be implemented when its orbital display server provides it.