1# Winit Scope 2 3Winit aims to expose an interface that abstracts over window creation and input handling, and can 4be used to create both games and applications. It supports the main graphical platforms: 5- Desktop 6 - Windows 7 - macOS 8 - Unix 9 - via X11 10 - via Wayland 11- Mobile 12 - iOS 13 - Android 14- Web 15 - via WASM 16 17Most platforms expose capabilities that cannot be meaningfully transposed onto others. Winit does not 18aim to support every single feature of every platform, but rather to abstract over the common features 19available everywhere. In this context, APIs exposed in winit can be split into different "support tiers": 20 21- **Core:** Features that are essential to providing a well-formed abstraction over each platform's 22 windowing and input APIs. 23- **Platform:** Platform-specific features that can't be meaningfully exposed through a common API and 24 cannot be implemented outside of Winit without exposing a significant amount of Winit's internals 25 or interfering with Winit's abstractions. 26- **Usability:** Features that are not strictly essential to Winit's functionality, but provide meaningful 27 usability improvements and cannot be reasonably implemented in an external crate. These are 28 generally optional and exposed through Cargo features. 29 30Core features are taken care of by the core Winit maintainers. Platform features are not. 31When a platform feature is submitted, the submitter is considered the expert in the 32feature and may be asked to support the feature should it break in the future. 33 34Winit ***does not*** directly expose functionality for drawing inside windows or creating native 35menus, but ***does*** commit to providing APIs that higher-level crates can use to implement that 36functionality. 37 38## `1.0` and stability 39 40When all core features are implemented to the satisfaction of the Winit maintainers, Winit 1.0 will 41be released and the library will enter maintenance mode. For the most part, new core features will not 42be added past this point. New platform features may be accepted and exposed through point releases. 43 44### Tier upgrades 45Some platform features could in theory be exposed across multiple platforms, but have not gone 46through the implementation work necessary to function on all platforms. When one of these features 47gets implemented across all platforms, a PR can be opened to upgrade the feature to a core feature. 48If that gets accepted, the platform-specific functions gets deprecated and become permanently 49exposed through the core, cross-platform API. 50 51# Features 52 53## Extending this section 54 55If your PR makes notable changes to Winit's features, please update this section as follows: 56 57- If your PR adds a new feature, add a brief description to the relevant section. If the feature is a core 58 feature, add a row to the feature matrix and describe what platforms the feature has been implemented on. 59 60- If your PR begins a new API rework, add a row to the `Pending API Reworks` table. If the PR implements the 61 API rework on all relevant platforms, please move it to the `Completed API Reworks` table. 62 63- If your PR implements an already-existing feature on a new platform, either mark the feature as *completed*, 64 or mark it as *mostly completed* and link to an issue describing the problems with the implementation. 65 66## Core 67 68### Windowing 69- **Window initialization**: Winit allows the creation of a window 70- **Providing pointer to init OpenGL**: Winit provides the necessary pointers to initialize a working opengl context 71- **Providing pointer to init Vulkan**: Same as OpenGL but for Vulkan 72- **Window decorations**: The windows created by winit are properly decorated, and the decorations can 73 be deactivated 74- **Window decorations toggle**: Decorations can be turned on or off after window creation 75- **Window resizing**: The windows created by winit can be resized and generate the appropriate events 76 when they are. The application can precisely control its window size if desired. 77- **Window resize increments**: When the window gets resized, the application can choose to snap the window's 78 size to specific values. 79- **Window transparency**: Winit allows the creation of windows with a transparent background. 80- **Window maximization**: The windows created by winit can be maximized upon creation. 81- **Window maximization toggle**: The windows created by winit can be maximized and unmaximized after 82 creation. 83- **Window minimization**: The windows created by winit can be minimized after creation. 84- **Fullscreen**: The windows created by winit can be put into fullscreen mode. 85- **Fullscreen toggle**: The windows created by winit can be switched to and from fullscreen after 86 creation. 87- **Exclusive fullscreen**: Winit allows changing the video mode of the monitor 88 for fullscreen windows, and if applicable, captures the monitor for exclusive 89 use by this application. 90- **HiDPI support**: Winit assists developers in appropriately scaling HiDPI content. 91- **Popup / modal windows**: Windows can be created relative to the client area of other windows, and parent 92 windows can be disabled in favor of popup windows. This feature also guarantees that popup windows 93 get drawn above their owner. 94 95 96### System Information 97- **Monitor list**: Retrieve the list of monitors and their metadata, including which one is primary. 98- **Video mode query**: Monitors can be queried for their supported fullscreen video modes (consisting of resolution, refresh rate, and bit depth). 99 100### Input Handling 101- **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events. 102- **Mouse set location**: Forcibly changing the location of the pointer. 103- **Cursor grab**: Locking the cursor so it cannot exit the client area of a window. 104- **Cursor icon**: Changing the cursor icon, or hiding the cursor. 105- **Touch events**: Single-touch events. 106- **Touch pressure**: Touch events contain information about the amount of force being applied. 107- **Multitouch**: Multi-touch events, including cancellation of a gesture. 108- **Keyboard events**: Properly processing keyboard events using the user-specified keymap and 109 translating keypresses into UTF-8 characters, handling dead keys and IMEs. 110- **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. 111- **Raw Device Events**: Capturing input from input devices without any OS filtering. 112- **Gamepad/Joystick events**: Capturing input from gamepads and joysticks. 113- **Device movement events**: Capturing input from the device gyroscope and accelerometer. 114 115## Platform 116### Windows 117* Setting the taskbar icon 118* Setting the parent window 119* `WS_EX_NOREDIRECTIONBITMAP` support 120* Theme the title bar according to Windows 10 Dark Mode setting or set a preferred theme 121 122### macOS 123* Window activation policy 124* Window movable by background 125* Transparent titlebar 126* Hidden titlebar 127* Hidden titlebar buttons 128* Full-size content view 129 130### Unix 131* Window urgency 132* X11 Window Class 133* X11 Override Redirect Flag 134* GTK Theme Variant 135* Base window size 136 137### iOS 138* `winit` has a minimum OS requirement of iOS 8 139* Get the `UIWindow` object pointer 140* Get the `UIViewController` object pointer 141* Get the `UIView` object pointer 142* Get the `UIScreen` object pointer 143* Setting the `UIView` hidpi factor 144* Valid orientations 145* Home indicator visibility 146* Status bar visibility 147* Deferrring system gestures 148* Support for custom `UIView` derived class 149* Getting the device idiom 150* Getting the preferred video mode 151 152### Web 153* Get if systems preferred color scheme is "dark" 154 155## Usability 156* `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) 157 158## Compatibility Matrix 159 160Legend: 161 162- ✔️: Works as intended 163- ▢: Mostly works but some bugs are known 164- ❌: Missing feature or large bugs making it unusable 165- **N/A**: Not applicable for this platform 166- ❓: Unknown status 167 168### Windowing 169|Feature |Windows|MacOS |Linux x11 |Linux Wayland |Android|iOS |WASM | 170|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | 171|Window initialization |✔️ |✔️ |▢[#5] |✔️ |▢[#33]|▢[#33] |✔️ | 172|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |**N/A**| 173|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A**| 174|Window decorations |✔️ |✔️ |✔️ |▢[#306] |**N/A**|**N/A**|**N/A**| 175|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**| 176|Window resizing |✔️ |▢[#219]|✔️ |▢[#306] |**N/A**|**N/A**|✔️ | 177|Window resize increments |❌ |❌ |❌ |❌ |❌ |❌ |**N/A**| 178|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|N/A | 179|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**| 180|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**| 181|Window minimization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A**| 182|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ |✔️ | 183|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ |✔️ | 184|Exclusive fullscreen |✔️ |✔️ |✔️ |**N/A** |❌ |✔️ |**N/A**| 185|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢[#721]|✔️ |✔️ \*1| 186|Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |**N/A**| 187 188\*1: `WindowEvent::ScaleFactorChanged` is not sent on `stdweb` backend. 189 190### System information 191|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |WASM | 192|---------------- | ----- | ---- | ------- | ----------- | ----- | ------- | -------- | 193|Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|✔️ |**N/A**| 194|Video mode query |✔️ |✔️ |✔️ |✔️ |❌ |✔️ |**N/A**| 195 196### Input handling 197|Feature |Windows |MacOS |Linux x11|Linux Wayland|Android|iOS |WASM | 198|----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | 199|Mouse events |✔️ |▢[#63] |✔️ |✔️ |**N/A**|**N/A**|✔️ | 200|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A**| 201|Cursor grab |✔️ |▢[#165] |▢[#242] |✔️ |**N/A**|**N/A**|❓ | 202|Cursor icon |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|✔️ | 203|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |❌ | 204|Touch pressure |✔️ |❌ |❌ |❌ |❌ |✔️ |❌ | 205|Multitouch |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |❌ | 206|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | 207|Drag & Drop |▢[#720] |▢[#720] |▢[#720] |❌[#306] |**N/A**|**N/A**|❓ | 208|Raw Device Events |▢[#750] |▢[#750] |▢[#750] |❌ |❌ |❌ |❓ | 209|Gamepad/Joystick events |❌[#804] |❌ |❌ |❌ |❌ |❌ |❓ | 210|Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❓ | 211 212### Pending API Reworks 213Changes in the API that have been agreed upon but aren't implemented across all platforms. 214 215|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |WASM | 216|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | 217|New API for HiDPI ([#315] [#319]) |✔️ |✔️ |✔️ |✔️ |▢[#721]|✔️ |❓ | 218|Event Loop 2.0 ([#459]) |✔️ |✔️ |❌ |✔️ |❌ |✔️ |❓ | 219|Keyboard Input ([#812]) |❌ |❌ |❌ |❌ |❌ |❌ |❓ | 220 221### Completed API Reworks 222|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |WASM | 223|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | 224 225[#165]: https://github.com/rust-windowing/winit/issues/165 226[#219]: https://github.com/rust-windowing/winit/issues/219 227[#242]: https://github.com/rust-windowing/winit/issues/242 228[#306]: https://github.com/rust-windowing/winit/issues/306 229[#315]: https://github.com/rust-windowing/winit/issues/315 230[#319]: https://github.com/rust-windowing/winit/issues/319 231[#33]: https://github.com/rust-windowing/winit/issues/33 232[#459]: https://github.com/rust-windowing/winit/issues/459 233[#5]: https://github.com/rust-windowing/winit/issues/5 234[#63]: https://github.com/rust-windowing/winit/issues/63 235[#720]: https://github.com/rust-windowing/winit/issues/720 236[#721]: https://github.com/rust-windowing/winit/issues/721 237[#750]: https://github.com/rust-windowing/winit/issues/750 238[#804]: https://github.com/rust-windowing/winit/issues/804 239[#812]: https://github.com/rust-windowing/winit/issues/812 240