From 1605adc4d4438fcfdc8cacf4a1c13eff6b40f27e Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 14:42:28 -0500 Subject: [PATCH 01/19] Add initial draft of SCOPE document --- CONTRIBUTING.md | 27 +------ SCOPE.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+), 24 deletions(-) create mode 100644 SCOPE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0440c6b497..59dd93b9eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,32 +1,11 @@ # Winit Contributing Guidelines ## Scope - -Winit aims to provide a generic platform abstracting the main graphic platforms (Windows, macOS, X11, -Wayland, Android, iOS and the web platform via Emscripten). - -Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not -aim to support every single functionality of every platform, but rather to abstract the set of -capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into -different "support levels": - -- Tier 1: features which are in the main scope of winit. They are part of the common API of winit, and - are taken care of by the maintainers. Any part of these features that is not working correctly is - considered a bug in winit. -- Tier 2: some platform-specific features can be sufficiently fundamental to the platform that winit can - integrate support for them in the platform-specific part of the API. These features are not considered - directly handled by the maintainers of winit. If you have a strong incentive to have such a feature - integrated in winit, consider implementing it and proposing yourself to maintain it in the future. -- Tier 3: these features are not directly exposed by winit, but rather can be implemented using the - raw handles to the underlying platform that winit exposes. If your feature of interest is rather - niche, this is probably where it belongs. - -The exact list of supported Tier 1 features is tracked in this issue: -[#252](https://github.com/tomaka/winit/issues/252). +[See `SCOPE.md`](./SCOPE.md) ## Reporting an issue -When reporting an issue, in order to help the maintainers understand what the problem is, please make +When reporting an issue, in order to help the maintainers understand what the problem is, please make your description of the issue as detailed as possible: - if it is a bug, please provide clear explanation of what happens, what should happen, and how to @@ -41,7 +20,7 @@ When making a code contribution to winit, before opening your pull request, plea - you tested your modifications on all the platforms impacted, or if not possible detail which platforms were not tested, and what should be tested, so that a maintainer or another contributor can test them - you updated any relevant documentation in winit -- you left comments in your code explaining any part that is not straightforward, so that the +- you left comments in your code explaining any part that is not straightforward, so that the maintainers and future contributors don't have to try to guess what your code is supposed to do - your PR adds an entry to the changelog file if the introduced change is relevant to winit users diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000000..201f8cc6d2 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,182 @@ +# Winit Scope + +Winit aims to expose an interface that abstracts over window creation and input handling, and can +be used to create both games and applications. It supports the main graphical platforms: +- Desktop + - Windows + - macOS + - Unix + - via X11 + - via Wayland +- Mobile + - iOS + - Android +- Web + - via Emscripten + - via WASM ***// TODO: DO WE ACTUALLY WANT TO SUPPORT THIS?*** + +Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not +aim to support every single functionality of every platform, but rather to abstract the set of +capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into +different "support levels": + +- Tier 1: Features that are essential to providing a well-formed abstraction over each platform's + windowing and input APIs. +- Tier 2: Platform-specific features. There are two classes of Tier 2 features: + - Tier 2A: Features that can't be meaningfully exposed through a common API and + cannot be implemented outside of Winit without exposing a significant amount of Winit's internals + or interfering with Winit's abstractions. + - Tier 2B: Features that could in theory be exposed across multiple platforms, but have not gone + through the implementation work necessary to function on all platforms. Winit provides no + stability guarantees for these features. +- Tier 3: Features that are not strictly essential to Winit's functionality, but provide meaningful + usability improvements and cannot be reasonably implemented in an external crate. These are + generally optional and exposed through Cargo features. + +Tier 1 features are taken care of by the core Winit maintainers. Tier 2 and 3 features are not. When +a Tier 2 or 3 feature is submitted, the submitter is considered the expert in the feature and may be +asked to support the feature should it break in the future. + +Winit ***does not*** directly expose functionality for drawing inside windows or creating native +menus, but ***does*** commit to providing APIs that higher-level crates can use to implement that +functionality. When requesting or implementing a new Winit feature, you should consider whether or +not it's directly related to window creation or input handling. If it isn't, it may be worth creating +a separate crate that extends Winit's API to add that functionality. + +## Tier upgrades +In some cases, Tier 2 features get implemented across enough platforms that a common API *can* be +exposed. When this happens, these features may be moved out of their platform module and into the +core Winit API. + +## The `1.0` release +When all Tier 1 features are implemented to the satisfaction of the Winit maintainers, Winit will +enter maintenance mode. New Tier 1 features will, for the most part, not be added past this point. +New Tier 2 and 3 features may be accepted and exposed through point releases. + +# Features + +## Tier 1 +Each section includes a collapsed description of the features it lists. + +Legend: + +- ✔️: Works as intended +- ▢: Mostly works but some bugs are known +- ❌: Missing feature or large bugs making it unusable +- **N/A**: Not applicable for this platform +- ❓: Unknown status + + +### Windowing +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Window initialization |✔️ |✔️ |▢#5 |✔️ |▢#33 |▢#33 |❓ | +|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ | +|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A** | +|Window decorations |✔️ |✔️ |✔️ |▢#306 |**N/A**|**N/A**|**N/A** | +|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window resizing |✔️ |▢#219 |✔️ |▢#306 |**N/A**|**N/A**|❓ | +|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|HiDPI support #105 |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | +|Child windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | + +#### Details +- **Window initialization**: Winit allows the creation of a window +- **Pointer to OpenGL**: Winit provides the necessary pointers to initialize a working opengl context +- **Pointer to Vulkan**: Same as OpenGL but for Vulkan +- **Window decorations**: The windows created by winit are properly decorated, and the decorations can + be deactivated +- **Window decorations toggle**: Decorations can be turned on or off after window creation +- **Window resizing**: The windows created by winit can be resized and generate the appropriate events + when they are. The application can precisely control its window size if wanted. +- **Window transaprency**: Winit allows the creation of windows with a transparent background. +- **Window maximization**: The windows created by winit can be maximized upon creation. +- **Window maximization toggle**: The windows created by winit can be maximized and unmaximized after + creation. +- **Fullscreen**: The windows created by winit support being fullscreen. +- **Fullscreen toggle**: The windows created by winit can be switched to and from fullscreen after + creation. +- **Child windows**: Windows can be created relative to the client area of other windows, and parent + windows can be disabled in favor of child windows. + +### System information +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | + +#### Details +- **Monitor list**: Retrieve the list of monitors and their metada, including which one is primary is applicable + +### Input handling +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|--------------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Mouse events |✔️ |▢ #63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | +|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | +|Cursor grab |✔️ |▢ #165|▢ #242 |❌ #306 |**N/A**|**N/A**|✔️ | +|Cursor icon |✔️ |✔️ |✔️ |❌ #306 |**N/A**|**N/A**|❌ | +|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | +|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | +|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | +|Drag & Drop |✔️ |✔️ |✔️ |❌ #306 |❌ |❌ |❌ | +|Clipboard #162 |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Raw Device Events |▢ |▢ |▢ |❌ |❌ |❌ |❌ | +|Gamepad/Joystick events ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Device movement events ***//DISCUSS*** |❓ |❓ |❓ |❓ |❌ |❌ |❌ | + +#### Details +- **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events. +- **Mouse set location**: Forcibly changing the location of the pointer. +- **Cursor grab**: Locking the cursor so it cannot exit the client area of a window. +- **Cursor icon**: Changing the cursor icon, or hiding the cursor. +- **Touch events**: Single-touch events. +- **Multitouch**: Multi-touch events, including cancellation of a gesture. +- **Keyboard events**: Properly processing keyboard events using the user-specified keymap and + translating keypresses into UTF-8 characters, handling dead keys and IMEs. +- **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. + ***//DISCUSS: WINIT SUPPORTS FILE DROPS, BUT NOT TEXT OR IMAGE DROPS*** +- **Clipboard**: Winit supports copy-pasting content to and from winit. + ***//DISCUSS: AN ISSUE SHOULD BE OPENED REGARDING HOW THIS API SHOULD WORK*** +- **Raw Device Events**: Capturing input from input devices without any OS filtering. +- **Gamepad/Joystick events**: Capturing input from gampads and joysticks. + ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** +- **Device movement events:**: Capturing input from the device gyroscope and accelerometer. + ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** + +### Pending API Reworks +Here are listed Changes in the API that have been merged but are still stubbed out in some platforms +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | +|Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | + +## Tier 2 +### Windows +* Setting the taskbar icon (Maintainer: ***???***) +* Setting the parent window (Maintainer: ***???***) + ***//DISCUSS: SHOULD THIS BE SUBSUMED INTO A CORE CHILD WINDOW FEATURE?*** +* `WS_EX_NOREDIRECTIONBITMAP` support (Maintainer: ***???***) + +### macOS +* Window activation policy (Maintainer: ***???***) +* Window movable by background (Maintainer: ***???***) +* Transparent titlebar (Maintainer: ***???***) +* Hidden titlebar (Maintainer: ***???***) +* Hidden titlebar buttons (Maintainer: ***???***) +* Full-size content view (Maintainer: ***???***) +* Resize increments (Maintainer: ***???***) + +### Unix +* Window urgency +* X11 Window Class +* X11 Override Redirect Flag +* GTK Theme Variant +* Resize increment +* Base window size + +## Tier 3 +* `icon_loading`: Enables loading window icons directly from files. (Maintainer: @francesca64) +* `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) From 11339952e0f5d399d0fc3be07f4d37a284039a64 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 14:54:37 -0500 Subject: [PATCH 02/19] Rephrase/rename feature tiers --- SCOPE.md | 60 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index 201f8cc6d2..2ee1f3dd9c 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -20,22 +20,18 @@ aim to support every single functionality of every platform, but rather to abstr capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into different "support levels": -- Tier 1: Features that are essential to providing a well-formed abstraction over each platform's +- **Core:** Features that are essential to providing a well-formed abstraction over each platform's windowing and input APIs. -- Tier 2: Platform-specific features. There are two classes of Tier 2 features: - - Tier 2A: Features that can't be meaningfully exposed through a common API and - cannot be implemented outside of Winit without exposing a significant amount of Winit's internals - or interfering with Winit's abstractions. - - Tier 2B: Features that could in theory be exposed across multiple platforms, but have not gone - through the implementation work necessary to function on all platforms. Winit provides no - stability guarantees for these features. -- Tier 3: Features that are not strictly essential to Winit's functionality, but provide meaningful +- **Platform:** Platform-specific features that can't be meaningfully exposed through a common API and + cannot be implemented outside of Winit without exposing a significant amount of Winit's internals + or interfering with Winit's abstractions. +- **Usability:** Features that are not strictly essential to Winit's functionality, but provide meaningful usability improvements and cannot be reasonably implemented in an external crate. These are generally optional and exposed through Cargo features. -Tier 1 features are taken care of by the core Winit maintainers. Tier 2 and 3 features are not. When -a Tier 2 or 3 feature is submitted, the submitter is considered the expert in the feature and may be -asked to support the feature should it break in the future. +Core features are taken care of by the core Winit maintainers. Platform features are not. +When a Platform feature is submitted, the submitter is considered the expert in the +feature and may be asked to support the feature should it break in the future. Winit ***does not*** directly expose functionality for drawing inside windows or creating native menus, but ***does*** commit to providing APIs that higher-level crates can use to implement that @@ -43,19 +39,22 @@ functionality. When requesting or implementing a new Winit feature, you should c not it's directly related to window creation or input handling. If it isn't, it may be worth creating a separate crate that extends Winit's API to add that functionality. -## Tier upgrades -In some cases, Tier 2 features get implemented across enough platforms that a common API *can* be -exposed. When this happens, these features may be moved out of their platform module and into the -core Winit API. +## `1.0` and stability -## The `1.0` release -When all Tier 1 features are implemented to the satisfaction of the Winit maintainers, Winit will -enter maintenance mode. New Tier 1 features will, for the most part, not be added past this point. -New Tier 2 and 3 features may be accepted and exposed through point releases. +When all core features are implemented to the satisfaction of the Winit maintainers, Winit 1.0 will +be released and the library will enter maintenance mode. New core features will for the most part not +be added past this point. New Platform features may be accepted and exposed through point releases. + +### Tier upgrades +Some platform features could in theory be exposed across multiple platforms, but have not gone +through the implementation work necessary to function on all platforms. When one of these features +gets implemented across all platforms, a PR can be opened to upgrade the feature to a core feature. +If that gets accepted, the platform-specific functions gets deprecated and become permanently +exposed through the core, cross-platform API. # Features -## Tier 1 +## Core Each section includes a collapsed description of the features it lists. Legend: @@ -102,6 +101,7 @@ Legend: creation. - **Child windows**: Windows can be created relative to the client area of other windows, and parent windows can be disabled in favor of child windows. + ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** ### System information |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| @@ -153,7 +153,7 @@ Here are listed Changes in the API that have been merged but are still stubbed o |New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | |Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | -## Tier 2 +## Platform ### Windows * Setting the taskbar icon (Maintainer: ***???***) * Setting the parent window (Maintainer: ***???***) @@ -170,13 +170,13 @@ Here are listed Changes in the API that have been merged but are still stubbed o * Resize increments (Maintainer: ***???***) ### Unix -* Window urgency -* X11 Window Class -* X11 Override Redirect Flag -* GTK Theme Variant -* Resize increment -* Base window size - -## Tier 3 +* Window urgency (Maintainer: ***???***) +* X11 Window Class (Maintainer: ***???***) +* X11 Override Redirect Flag (Maintainer: ***???***) +* GTK Theme Variant (Maintainer: ***???***) +* Resize increments (Maintainer: ***???***) +* Base window size (Maintainer: ***???***) + +## Usability * `icon_loading`: Enables loading window icons directly from files. (Maintainer: @francesca64) * `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) From 4df37e440673aeb4d7e4054cb6eebbdaf0f96f5e Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 15:02:42 -0500 Subject: [PATCH 03/19] Rename to FEATURES and add a few annotations --- CONTRIBUTING.md | 3 ++- SCOPE.md => FEATURES.md | 26 +++++++++++++------------- 2 files changed, 15 insertions(+), 14 deletions(-) rename SCOPE.md => FEATURES.md (91%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 59dd93b9eb..02607b0dff 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,8 @@ # Winit Contributing Guidelines ## Scope -[See `SCOPE.md`](./SCOPE.md) +[See `FEATURES.md`](./FEATURES.md). New features should fall into one of the three feature categories +described in that document. ## Reporting an issue diff --git a/SCOPE.md b/FEATURES.md similarity index 91% rename from SCOPE.md rename to FEATURES.md index 2ee1f3dd9c..5825e64bdd 100644 --- a/SCOPE.md +++ b/FEATURES.md @@ -13,7 +13,7 @@ be used to create both games and applications. It supports the main graphical pl - Android - Web - via Emscripten - - via WASM ***// TODO: DO WE ACTUALLY WANT TO SUPPORT THIS?*** + - via WASM ***// TODO: DO WE WANT TO SUPPORT THIS?*** Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not aim to support every single functionality of every platform, but rather to abstract the set of @@ -29,8 +29,8 @@ different "support levels": usability improvements and cannot be reasonably implemented in an external crate. These are generally optional and exposed through Cargo features. -Core features are taken care of by the core Winit maintainers. Platform features are not. -When a Platform feature is submitted, the submitter is considered the expert in the +Core features are taken care of by the core Winit maintainers. Platform features are not. +When a platform feature is submitted, the submitter is considered the expert in the feature and may be asked to support the feature should it break in the future. Winit ***does not*** directly expose functionality for drawing inside windows or creating native @@ -42,8 +42,8 @@ a separate crate that extends Winit's API to add that functionality. ## `1.0` and stability When all core features are implemented to the satisfaction of the Winit maintainers, Winit 1.0 will -be released and the library will enter maintenance mode. New core features will for the most part not -be added past this point. New Platform features may be accepted and exposed through point releases. +be released and the library will enter maintenance mode. For the most part, new core features will not +be added past this point. New platform features may be accepted and exposed through point releases. ### Tier upgrades Some platform features could in theory be exposed across multiple platforms, but have not gone @@ -114,16 +114,16 @@ Legend: ### Input handling |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |--------------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Mouse events |✔️ |▢ #63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | +|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | |Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | -|Cursor grab |✔️ |▢ #165|▢ #242 |❌ #306 |**N/A**|**N/A**|✔️ | -|Cursor icon |✔️ |✔️ |✔️ |❌ #306 |**N/A**|**N/A**|❌ | +|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | +|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | |Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | |Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | |Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | -|Drag & Drop |✔️ |✔️ |✔️ |❌ #306 |❌ |❌ |❌ | +|Drag & Drop |✔️ |✔️ |✔️ |❌#306 |❌ |❌ |❌ | |Clipboard #162 |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Raw Device Events |▢ |▢ |▢ |❌ |❌ |❌ |❌ | +|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | |Gamepad/Joystick events ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | |Device movement events ***//DISCUSS*** |❓ |❓ |❓ |❓ |❌ |❌ |❌ | @@ -150,7 +150,7 @@ Legend: Here are listed Changes in the API that have been merged but are still stubbed out in some platforms |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | +|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢*#??* |✔️ |✔️ | |Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | ## Platform @@ -167,14 +167,14 @@ Here are listed Changes in the API that have been merged but are still stubbed o * Hidden titlebar (Maintainer: ***???***) * Hidden titlebar buttons (Maintainer: ***???***) * Full-size content view (Maintainer: ***???***) -* Resize increments (Maintainer: ***???***) +* Resize increments (Maintainer: ***???***) ***//DISCUSS: SHOULD RESIZE INCREMENTS BE CORE?*** ### Unix * Window urgency (Maintainer: ***???***) * X11 Window Class (Maintainer: ***???***) * X11 Override Redirect Flag (Maintainer: ***???***) * GTK Theme Variant (Maintainer: ***???***) -* Resize increments (Maintainer: ***???***) +* Resize increments (Maintainer: ***???***) ***//DISCUSS: SHOULD RESIZE INCREMENTS BE CORE?*** * Base window size (Maintainer: ***???***) ## Usability From cd6a6c88ae9ae08b1e5ed7ece10dae1fac72fcc7 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 15:09:48 -0500 Subject: [PATCH 04/19] Fix API Reworks table --- FEATURES.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/FEATURES.md b/FEATURES.md index 5825e64bdd..a54ad68b57 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -147,7 +147,8 @@ Legend: ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** ### Pending API Reworks -Here are listed Changes in the API that have been merged but are still stubbed out in some platforms +Changes in the API that have been agreed upon but aren't implemented across all platforms. + |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | |New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢*#??* |✔️ |✔️ | From 479cf5d198af6fad6e24beb2f203e2a9acaf77c5 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 15:22:34 -0500 Subject: [PATCH 05/19] Add more annotations --- CONTRIBUTING.md | 3 ++- FEATURES.md | 4 +++- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 02607b0dff..a63380be98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,8 @@ ## Scope [See `FEATURES.md`](./FEATURES.md). New features should fall into one of the three feature categories -described in that document. +described in that document. If your PR adds a new feature, it should be included in one of the feature +lists in that document. ## Reporting an issue diff --git a/FEATURES.md b/FEATURES.md index a54ad68b57..3c414eb063 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -13,7 +13,7 @@ be used to create both games and applications. It supports the main graphical pl - Android - Web - via Emscripten - - via WASM ***// TODO: DO WE WANT TO SUPPORT THIS?*** + - via WASM ***//DISCUSS: DO WE WANT TO SUPPORT THIS?*** Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not aim to support every single functionality of every platform, but rather to abstract the set of @@ -44,6 +44,7 @@ a separate crate that extends Winit's API to add that functionality. When all core features are implemented to the satisfaction of the Winit maintainers, Winit 1.0 will be released and the library will enter maintenance mode. For the most part, new core features will not be added past this point. New platform features may be accepted and exposed through point releases. +***//DISCUSS: IS THIS ACCURATE?*** ### Tier upgrades Some platform features could in theory be exposed across multiple platforms, but have not gone @@ -51,6 +52,7 @@ through the implementation work necessary to function on all platforms. When one gets implemented across all platforms, a PR can be opened to upgrade the feature to a core feature. If that gets accepted, the platform-specific functions gets deprecated and become permanently exposed through the core, cross-platform API. +***//DISCUSS: DO WE WANT TO HAVE THIS BE AN OFFICIAL PROCESS, OR NO?*** # Features From 81d7458c288e7e5ed71f7503583706ffcd9ad4c1 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sat, 10 Nov 2018 15:24:36 -0500 Subject: [PATCH 06/19] Some phrasing --- CONTRIBUTING.md | 7 ++++--- FEATURES.md | 11 ++++------- 2 files changed, 8 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a63380be98..f2642a6d7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,9 +1,10 @@ # Winit Contributing Guidelines ## Scope -[See `FEATURES.md`](./FEATURES.md). New features should fall into one of the three feature categories -described in that document. If your PR adds a new feature, it should be included in one of the feature -lists in that document. +[See `FEATURES.md`](./FEATURES.md). When requesting or implementing a new Winit feature, you should +consider whether or not it's directly related to window creation or input handling. If it isn't, it +may be worth creating a separate crate that extends Winit's API to add that functionality. + ## Reporting an issue diff --git a/FEATURES.md b/FEATURES.md index 3c414eb063..14abbf708a 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -15,10 +15,9 @@ be used to create both games and applications. It supports the main graphical pl - via Emscripten - via WASM ***//DISCUSS: DO WE WANT TO SUPPORT THIS?*** -Most platforms expose capabilities that cannot be meaningfully transposed to the others. Winit does not -aim to support every single functionality of every platform, but rather to abstract the set of -capabilities that is common to all platforms. In this context, APIs exposed in winit can be split into -different "support levels": +Most platforms expose capabilities that cannot be meaningfully transposed onto others. Winit does not +aim to support every single feature of every platform, but rather to abstract over the common features +available everywhere. In this context, APIs exposed in winit can be split into different "support tiers": - **Core:** Features that are essential to providing a well-formed abstraction over each platform's windowing and input APIs. @@ -35,9 +34,7 @@ feature and may be asked to support the feature should it break in the future. Winit ***does not*** directly expose functionality for drawing inside windows or creating native menus, but ***does*** commit to providing APIs that higher-level crates can use to implement that -functionality. When requesting or implementing a new Winit feature, you should consider whether or -not it's directly related to window creation or input handling. If it isn't, it may be worth creating -a separate crate that extends Winit's API to add that functionality. +functionality. ## `1.0` and stability From 915eb6dbcf060e9806670272db208beb699e14c3 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sun, 11 Nov 2018 13:17:44 -0500 Subject: [PATCH 07/19] Split compat matrix into seperate section, to be moved into wiki --- FEATURES.md | 116 +++++++++++++++++++++++++++------------------------- 1 file changed, 60 insertions(+), 56 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 14abbf708a..a2eb29bac6 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -54,35 +54,10 @@ exposed through the core, cross-platform API. # Features ## Core -Each section includes a collapsed description of the features it lists. - -Legend: - -- ✔️: Works as intended -- ▢: Mostly works but some bugs are known -- ❌: Missing feature or large bugs making it unusable -- **N/A**: Not applicable for this platform -- ❓: Unknown status +Tables detailing feature compatibility across platforms can be found in the wiki ***//TODO: MAKE LINK*** ### Windowing -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Window initialization |✔️ |✔️ |▢#5 |✔️ |▢#33 |▢#33 |❓ | -|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ | -|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A** | -|Window decorations |✔️ |✔️ |✔️ |▢#306 |**N/A**|**N/A**|**N/A** | -|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window resizing |✔️ |▢#219 |✔️ |▢#306 |**N/A**|**N/A**|❓ | -|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|HiDPI support #105 |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | -|Child windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | - -#### Details - **Window initialization**: Winit allows the creation of a window - **Pointer to OpenGL**: Winit provides the necessary pointers to initialize a working opengl context - **Pointer to Vulkan**: Same as OpenGL but for Vulkan @@ -102,31 +77,11 @@ Legend: windows can be disabled in favor of child windows. ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** -### System information -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -#### Details +### System Information - **Monitor list**: Retrieve the list of monitors and their metada, including which one is primary is applicable -### Input handling -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|--------------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | -|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | -|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | -|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | -|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | -|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | -|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | -|Drag & Drop |✔️ |✔️ |✔️ |❌#306 |❌ |❌ |❌ | -|Clipboard #162 |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | -|Gamepad/Joystick events ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Device movement events ***//DISCUSS*** |❓ |❓ |❓ |❓ |❌ |❌ |❌ | - -#### Details +### Input Handling - **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events. - **Mouse set location**: Forcibly changing the location of the pointer. - **Cursor grab**: Locking the cursor so it cannot exit the client area of a window. @@ -145,14 +100,6 @@ Legend: - **Device movement events:**: Capturing input from the device gyroscope and accelerometer. ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** -### Pending API Reworks -Changes in the API that have been agreed upon but aren't implemented across all platforms. - -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢*#??* |✔️ |✔️ | -|Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | - ## Platform ### Windows * Setting the taskbar icon (Maintainer: ***???***) @@ -180,3 +127,60 @@ Changes in the API that have been agreed upon but aren't implemented across all ## Usability * `icon_loading`: Enables loading window icons directly from files. (Maintainer: @francesca64) * `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) + +# Compatibility Matrix - Move to wiki on merge + +Each section includes a collapsed description of the features it lists. + +Legend: + +- ✔️: Works as intended +- ▢: Mostly works but some bugs are known +- ❌: Missing feature or large bugs making it unusable +- **N/A**: Not applicable for this platform +- ❓: Unknown status +## Windowing +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Window initialization |✔️ |✔️ |▢#5 |✔️ |▢#33 |▢#33 |❓ | +|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ | +|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A** | +|Window decorations |✔️ |✔️ |✔️ |▢#306 |**N/A**|**N/A**|**N/A** | +|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window resizing |✔️ |▢#219 |✔️ |▢#306 |**N/A**|**N/A**|❓ | +|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|HiDPI support #105 |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | +|Child windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | + +## System information +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | + +## Input handling +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|--------------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | +|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | +|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | +|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | +|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | +|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | +|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | +|Drag & Drop |✔️ |✔️ |✔️ |❌#306 |❌ |❌ |❌ | +|Clipboard #162 |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | +|Gamepad/Joystick events ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Device movement events ***//DISCUSS*** |❓ |❓ |❓ |❓ |❌ |❌ |❌ | + +## Pending API Reworks +Changes in the API that have been agreed upon but aren't implemented across all platforms. + +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢*#??* |✔️ |✔️ | +|Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | From f99c8ea1594a82cc42a9a4c8b99bdfba49af91a8 Mon Sep 17 00:00:00 2001 From: Osspial Date: Sun, 11 Nov 2018 13:20:53 -0500 Subject: [PATCH 08/19] Mention compatibility in CONTRIBUTING --- CONTRIBUTING.md | 3 +++ FEATURES.md | 1 + 2 files changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2642a6d7a..5d12ba303b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,9 @@ When making a code contribution to winit, before opening your pull request, plea - you left comments in your code explaining any part that is not straightforward, so that the maintainers and future contributors don't have to try to guess what your code is supposed to do - your PR adds an entry to the changelog file if the introduced change is relevant to winit users +- if your PR affects the platform compatibility of one or more features or adds another feature, the + relevant table in the wiki should be updated + ***//TODO: LINKY*** Once your PR is open, you can ask for review by a maintainer of your platform. Winit's merging policy is that a PR must be approved by at least two maintainers of winit before being merged, including diff --git a/FEATURES.md b/FEATURES.md index a2eb29bac6..f17419b686 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -139,6 +139,7 @@ Legend: - ❌: Missing feature or large bugs making it unusable - **N/A**: Not applicable for this platform - ❓: Unknown status + ## Windowing |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | From fe70a668bd20362fb5d71d78ec17e4184a2e6c18 Mon Sep 17 00:00:00 2001 From: Osspial Date: Tue, 13 Nov 2018 14:32:39 -0500 Subject: [PATCH 09/19] Remove some discuss annotations --- FEATURES.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index f17419b686..1f48b3d6da 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -41,7 +41,6 @@ functionality. When all core features are implemented to the satisfaction of the Winit maintainers, Winit 1.0 will be released and the library will enter maintenance mode. For the most part, new core features will not be added past this point. New platform features may be accepted and exposed through point releases. -***//DISCUSS: IS THIS ACCURATE?*** ### Tier upgrades Some platform features could in theory be exposed across multiple platforms, but have not gone @@ -49,7 +48,6 @@ through the implementation work necessary to function on all platforms. When one gets implemented across all platforms, a PR can be opened to upgrade the feature to a core feature. If that gets accepted, the platform-specific functions gets deprecated and become permanently exposed through the core, cross-platform API. -***//DISCUSS: DO WE WANT TO HAVE THIS BE AN OFFICIAL PROCESS, OR NO?*** # Features @@ -93,7 +91,6 @@ Tables detailing feature compatibility across platforms can be found in the wiki - **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. ***//DISCUSS: WINIT SUPPORTS FILE DROPS, BUT NOT TEXT OR IMAGE DROPS*** - **Clipboard**: Winit supports copy-pasting content to and from winit. - ***//DISCUSS: AN ISSUE SHOULD BE OPENED REGARDING HOW THIS API SHOULD WORK*** - **Raw Device Events**: Capturing input from input devices without any OS filtering. - **Gamepad/Joystick events**: Capturing input from gampads and joysticks. ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** From 8b5065ebdffddb11f2c41fa29ddfea15dab0b5a9 Mon Sep 17 00:00:00 2001 From: Osspial Date: Fri, 16 Nov 2018 20:31:37 -0500 Subject: [PATCH 10/19] Apply review changes and rename child windows feature to popup windows --- FEATURES.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 1f48b3d6da..5d17d68275 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -64,20 +64,21 @@ Tables detailing feature compatibility across platforms can be found in the wiki - **Window decorations toggle**: Decorations can be turned on or off after window creation - **Window resizing**: The windows created by winit can be resized and generate the appropriate events when they are. The application can precisely control its window size if wanted. -- **Window transaprency**: Winit allows the creation of windows with a transparent background. +- **Window transparency**: Winit allows the creation of windows with a transparent background. - **Window maximization**: The windows created by winit can be maximized upon creation. - **Window maximization toggle**: The windows created by winit can be maximized and unmaximized after creation. - **Fullscreen**: The windows created by winit support being fullscreen. - **Fullscreen toggle**: The windows created by winit can be switched to and from fullscreen after creation. -- **Child windows**: Windows can be created relative to the client area of other windows, and parent - windows can be disabled in favor of child windows. +- **Popup windows**: Windows can be created relative to the client area of other windows, and parent + windows can be disabled in favor of popup windows. This feature also guarantees that popup windows + get drawn above their owner. ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** ### System Information -- **Monitor list**: Retrieve the list of monitors and their metada, including which one is primary is applicable +- **Monitor list**: Retrieve the list of monitors and their metadata, including which one is primary. ### Input Handling - **Mouse events**: Generating mouse events associated with pointer motion, click, and scrolling events. @@ -101,7 +102,7 @@ Tables detailing feature compatibility across platforms can be found in the wiki ### Windows * Setting the taskbar icon (Maintainer: ***???***) * Setting the parent window (Maintainer: ***???***) - ***//DISCUSS: SHOULD THIS BE SUBSUMED INTO A CORE CHILD WINDOW FEATURE?*** + ***//DISCUSS: SHOULD THIS BE SUBSUMED INTO A CORE POPUP WINDOW FEATURE?*** * `WS_EX_NOREDIRECTIONBITMAP` support (Maintainer: ***???***) ### macOS @@ -152,7 +153,7 @@ Legend: |Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | |Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | |HiDPI support #105 |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | -|Child windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Popup windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | ## System information |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| From 8c64495a46fc55ec9de7945d8e0846ceaf6bc4f8 Mon Sep 17 00:00:00 2001 From: Osspial Date: Tue, 20 Nov 2018 11:48:01 -0500 Subject: [PATCH 11/19] Update based on discussion --- FEATURES.md | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 5d17d68275..5650be5a11 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -13,7 +13,7 @@ be used to create both games and applications. It supports the main graphical pl - Android - Web - via Emscripten - - via WASM ***//DISCUSS: DO WE WANT TO SUPPORT THIS?*** + - via WASM Most platforms expose capabilities that cannot be meaningfully transposed onto others. Winit does not aim to support every single feature of every platform, but rather to abstract over the common features @@ -74,7 +74,6 @@ Tables detailing feature compatibility across platforms can be found in the wiki - **Popup windows**: Windows can be created relative to the client area of other windows, and parent windows can be disabled in favor of popup windows. This feature also guarantees that popup windows get drawn above their owner. - ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** ### System Information @@ -91,12 +90,9 @@ Tables detailing feature compatibility across platforms can be found in the wiki translating keypresses into UTF-8 characters, handling dead keys and IMEs. - **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. ***//DISCUSS: WINIT SUPPORTS FILE DROPS, BUT NOT TEXT OR IMAGE DROPS*** -- **Clipboard**: Winit supports copy-pasting content to and from winit. - **Raw Device Events**: Capturing input from input devices without any OS filtering. - **Gamepad/Joystick events**: Capturing input from gampads and joysticks. - ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** - **Device movement events:**: Capturing input from the device gyroscope and accelerometer. - ***//DISCUSS: SHOULD THIS BE SUPPORTED?*** ## Platform ### Windows @@ -152,8 +148,8 @@ Legend: |Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | |Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | |Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|HiDPI support #105 |✔️ |✔️ |✔️ |✔️ |▢ |✔️ |✔️ | -|Popup windows ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢*#??*|✔️ |✔️ | +|Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |❌ | ## System information |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| @@ -161,20 +157,19 @@ Legend: |Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | ## Input handling -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|--------------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | -|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | -|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | -|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | -|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | -|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | -|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | -|Drag & Drop |✔️ |✔️ |✔️ |❌#306 |❌ |❌ |❌ | -|Clipboard #162 |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | -|Gamepad/Joystick events ***//DISCUSS*** |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Device movement events ***//DISCUSS*** |❓ |❓ |❓ |❓ |❌ |❌ |❌ | +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | +|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | +|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | +|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | +|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | +|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | +|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | +|Drag & Drop |▢#720 |▢#720️ |▢#720️ |❌#306 |**N/A**|**N/A**|❓ | +|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | +|Gamepad/Joystick events |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | ## Pending API Reworks Changes in the API that have been agreed upon but aren't implemented across all platforms. From ed0a3a63bfa07cc2198b3f849f6ecfa289ac08d6 Mon Sep 17 00:00:00 2001 From: Osspial Date: Tue, 20 Nov 2018 11:56:35 -0500 Subject: [PATCH 12/19] Add issue for Android HiDPI --- FEATURES.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 5650be5a11..961c755cbf 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -148,7 +148,7 @@ Legend: |Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | |Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | |Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢*#??*|✔️ |✔️ | +|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢#721 |✔️ |✔️ | |Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |❌ | ## System information @@ -176,5 +176,5 @@ Changes in the API that have been agreed upon but aren't implemented across all |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢*#??* |✔️ |✔️ | +|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢#721 |✔️ |✔️ | |Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | From 67b91764bb2fdc07bc096189a15d1eedec910f56 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 31 Dec 2018 16:45:06 -0500 Subject: [PATCH 13/19] Update FEATURES.md --- FEATURES.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 961c755cbf..a25e6feb73 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -98,7 +98,6 @@ Tables detailing feature compatibility across platforms can be found in the wiki ### Windows * Setting the taskbar icon (Maintainer: ***???***) * Setting the parent window (Maintainer: ***???***) - ***//DISCUSS: SHOULD THIS BE SUBSUMED INTO A CORE POPUP WINDOW FEATURE?*** * `WS_EX_NOREDIRECTIONBITMAP` support (Maintainer: ***???***) ### macOS @@ -167,7 +166,7 @@ Legend: |Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | |Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | |Drag & Drop |▢#720 |▢#720️ |▢#720️ |❌#306 |**N/A**|**N/A**|❓ | -|Raw Device Events |▢*#??*|▢*#??*|▢*#??* |❌ |❌ |❌ |❌ | +|Raw Device Events |▢#750 |▢#750 |▢#750 |❌ |❌ |❌ |❌ | |Gamepad/Joystick events |❌ |❌ |❌ |❌ |❌ |❌ |❌ | |Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | From bf2fb85fd20beea933113d7909d5796d22526372 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 01:02:56 -0400 Subject: [PATCH 14/19] Update FEATURES.md --- FEATURES.md | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index a25e6feb73..1ab13d7d60 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -96,29 +96,26 @@ Tables detailing feature compatibility across platforms can be found in the wiki ## Platform ### Windows -* Setting the taskbar icon (Maintainer: ***???***) -* Setting the parent window (Maintainer: ***???***) -* `WS_EX_NOREDIRECTIONBITMAP` support (Maintainer: ***???***) +* Setting the taskbar icon +* Setting the parent window +* `WS_EX_NOREDIRECTIONBITMAP` support ### macOS -* Window activation policy (Maintainer: ***???***) -* Window movable by background (Maintainer: ***???***) -* Transparent titlebar (Maintainer: ***???***) -* Hidden titlebar (Maintainer: ***???***) -* Hidden titlebar buttons (Maintainer: ***???***) -* Full-size content view (Maintainer: ***???***) -* Resize increments (Maintainer: ***???***) ***//DISCUSS: SHOULD RESIZE INCREMENTS BE CORE?*** +* Window activation policy +* Window movable by background +* Transparent titlebar +* Hidden titlebar +* Hidden titlebar buttons +* Full-size content view ### Unix -* Window urgency (Maintainer: ***???***) -* X11 Window Class (Maintainer: ***???***) -* X11 Override Redirect Flag (Maintainer: ***???***) -* GTK Theme Variant (Maintainer: ***???***) -* Resize increments (Maintainer: ***???***) ***//DISCUSS: SHOULD RESIZE INCREMENTS BE CORE?*** -* Base window size (Maintainer: ***???***) +* Window urgency +* X11 Window Class +* X11 Override Redirect Flag +* GTK Theme Variant +* Base window size ## Usability -* `icon_loading`: Enables loading window icons directly from files. (Maintainer: @francesca64) * `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) # Compatibility Matrix - Move to wiki on merge @@ -142,6 +139,7 @@ Legend: |Window decorations |✔️ |✔️ |✔️ |▢#306 |**N/A**|**N/A**|**N/A** | |Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | |Window resizing |✔️ |▢#219 |✔️ |▢#306 |**N/A**|**N/A**|❓ | +|Window resize increments |❌ |❌ |❌ |❌ |❌ |❌ |❌ | |Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | |Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | |Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | @@ -167,7 +165,7 @@ Legend: |Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | |Drag & Drop |▢#720 |▢#720️ |▢#720️ |❌#306 |**N/A**|**N/A**|❓ | |Raw Device Events |▢#750 |▢#750 |▢#750 |❌ |❌ |❌ |❌ | -|Gamepad/Joystick events |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Gamepad/Joystick events |❌#804|❌ |❌ |❌ |❌ |❌ |❌ | |Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | ## Pending API Reworks @@ -176,4 +174,5 @@ Changes in the API that have been agreed upon but aren't implemented across all |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | |New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢#721 |✔️ |✔️ | -|Event Loop 2.0 (#459) |❌#638|❌ |❌ |❌ |❌ |❌ |❌ | +|Event Loop 2.0 (#459) |✔️ |❌ |❌ |✔️ |❌ |❌ |❌ | +|Keyboard Input (#812) |❌ |❌ |❌ |❌ |❌ |❌ |❌ | From 554cd238036977ba32d05193528c7549761827d8 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 01:03:37 -0400 Subject: [PATCH 15/19] Update PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 08cd768b50..19075df060 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,3 +2,4 @@ - [ ] Added an entry to `CHANGELOG.md` if knowledge of this change could be valuable to users - [ ] Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior - [ ] Created an example program if it would help users understand this functionality +- [ ] Updated feature matrix, if new features were added From 26c41babf10ae0ef2d1387976570a5584a1946ce Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 01:04:30 -0400 Subject: [PATCH 16/19] Update PULL_REQUEST_TEMPLATE.md --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 19075df060..b6c3ba0593 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,4 +2,4 @@ - [ ] Added an entry to `CHANGELOG.md` if knowledge of this change could be valuable to users - [ ] Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior - [ ] Created an example program if it would help users understand this functionality -- [ ] Updated feature matrix, if new features were added +- [ ] Updated [feature matrix](TODO: LINK), if new features were added or implemented From 60208e5ece255a03b32298e2355e0d1216c3e7f4 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 17:28:54 -0400 Subject: [PATCH 17/19] Reformat FEATURES.MD --- FEATURES.md | 86 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 35 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 1ab13d7d60..edaf5f6185 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -118,7 +118,7 @@ Tables detailing feature compatibility across platforms can be found in the wiki ## Usability * `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) -# Compatibility Matrix - Move to wiki on merge +# Compatibility Matrix Each section includes a collapsed description of the features it lists. @@ -131,22 +131,22 @@ Legend: - ❓: Unknown status ## Windowing -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Window initialization |✔️ |✔️ |▢#5 |✔️ |▢#33 |▢#33 |❓ | -|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ | -|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A** | -|Window decorations |✔️ |✔️ |✔️ |▢#306 |**N/A**|**N/A**|**N/A** | -|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window resizing |✔️ |▢#219 |✔️ |▢#306 |**N/A**|**N/A**|❓ | -|Window resize increments |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | -|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢#721 |✔️ |✔️ | -|Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Feature |Windows|MacOS |Linux x11 |Linux Wayland |Android|iOS |Emscripten| +|-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Window initialization |✔️ |✔️ |▢[#5] |✔️ |▢[#33]|▢[#33] |❓ | +|Providing pointer to init OpenGL |✔️ |✔️ |✔️ |✔️ |✔️ |✔️ |❓ | +|Providing pointer to init Vulkan |✔️ |✔️ |✔️ |✔️ |✔️ |❓ |**N/A** | +|Window decorations |✔️ |✔️ |✔️ |▢[#306] |**N/A**|**N/A**|**N/A** | +|Window decorations toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window resizing |✔️ |▢[#219]|✔️ |▢[#306] |**N/A**|**N/A**|❓ | +|Window resize increments |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Window transparency |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Window maximization toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | +|Fullscreen |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|Fullscreen toggle |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|❌ | +|HiDPI support |✔️ |✔️ |✔️ |✔️ |▢[#721]|✔️ |✔️ | +|Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |❌ | ## System information |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| @@ -154,25 +154,41 @@ Legend: |Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | ## Input handling -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|Mouse events |✔️ |▢#63 |✔️ |✔️ |**N/A**|**N/A**|✔️ | -|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | -|Cursor grab |✔️ |▢#165 |▢#242 |❌#306 |**N/A**|**N/A**|✔️ | -|Cursor icon |✔️ |✔️ |✔️ |❌#306 |**N/A**|**N/A**|❌ | -|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | -|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | -|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | -|Drag & Drop |▢#720 |▢#720️ |▢#720️ |❌#306 |**N/A**|**N/A**|❓ | -|Raw Device Events |▢#750 |▢#750 |▢#750 |❌ |❌ |❌ |❌ | -|Gamepad/Joystick events |❌#804|❌ |❌ |❌ |❌ |❌ |❌ | -|Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | +|Feature |Windows |MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|Mouse events |✔️ |▢[#63] |✔️ |✔️ |**N/A**|**N/A**|✔️ | +|Mouse set location |✔️ |✔️ |✔️ |❓ |**N/A**|**N/A**|**N/A** | +|Cursor grab |✔️ |▢[#165] |▢[#242] |❌[#306] |**N/A**|**N/A**|✔️ | +|Cursor icon |✔️ |✔️ |✔️ |❌[#306] |**N/A**|**N/A**|❌ | +|Touch events |✔️ |❌ |✔️ |✔️ |✔️ |✔️ |✔️ | +|Multitouch |❓ |❌ |✔️ |✔️ |❓ |❌ |❌ | +|Keyboard events |✔️ |✔️ |✔️ |✔️ |❓ |❌ |✔️ | +|Drag & Drop |▢[#720] |▢[#720] |▢[#720] |❌[#306] |**N/A**|**N/A**|❓ | +|Raw Device Events |▢[#750] |▢[#750] |▢[#750] |❌ |❌ |❌ |❌ | +|Gamepad/Joystick events |❌[#804] |❌ |❌ |❌ |❌ |❌ |❌ | +|Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | ## Pending API Reworks Changes in the API that have been agreed upon but aren't implemented across all platforms. -|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| -|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | -|New API for HiDPI (#315 #319) |✔️ |✔️ |✔️ |✔️ |▢#721 |✔️ |✔️ | -|Event Loop 2.0 (#459) |✔️ |❌ |❌ |✔️ |❌ |❌ |❌ | -|Keyboard Input (#812) |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | +|New API for HiDPI ([#315] [#319]) |✔️ |✔️ |✔️ |✔️ |▢[#721]|✔️ |✔️ | +|Event Loop 2.0 ([#459]) |✔️ |❌ |❌ |✔️ |❌ |❌ |❌ | +|Keyboard Input ([#812]) |❌ |❌ |❌ |❌ |❌ |❌ |❌ | + +[#165]: https://github.com/tomaka/winit/issues/165 +[#219]: https://github.com/tomaka/winit/issues/219 +[#242]: https://github.com/tomaka/winit/issues/242 +[#306]: https://github.com/tomaka/winit/issues/306 +[#315]: https://github.com/tomaka/winit/issues/315 +[#319]: https://github.com/tomaka/winit/issues/319 +[#33]: https://github.com/tomaka/winit/issues/33 +[#459]: https://github.com/tomaka/winit/issues/459 +[#5]: https://github.com/tomaka/winit/issues/5 +[#63]: https://github.com/tomaka/winit/issues/63 +[#720]: https://github.com/tomaka/winit/issues/720 +[#721]: https://github.com/tomaka/winit/issues/721 +[#750]: https://github.com/tomaka/winit/issues/750 +[#804]: https://github.com/tomaka/winit/issues/804 +[#812]: https://github.com/tomaka/winit/issues/812 From ad4150467016190fe57f0345cf1b5c8202482ed9 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 17:30:30 -0400 Subject: [PATCH 18/19] Remove comments --- FEATURES.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index edaf5f6185..50f1383688 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -53,8 +53,6 @@ exposed through the core, cross-platform API. ## Core -Tables detailing feature compatibility across platforms can be found in the wiki ***//TODO: MAKE LINK*** - ### Windowing - **Window initialization**: Winit allows the creation of a window - **Pointer to OpenGL**: Winit provides the necessary pointers to initialize a working opengl context @@ -89,7 +87,6 @@ Tables detailing feature compatibility across platforms can be found in the wiki - **Keyboard events**: Properly processing keyboard events using the user-specified keymap and translating keypresses into UTF-8 characters, handling dead keys and IMEs. - **Drag & Drop**: Dragging content into winit, detecting when content enters, drops, or if the drop is cancelled. - ***//DISCUSS: WINIT SUPPORTS FILE DROPS, BUT NOT TEXT OR IMAGE DROPS*** - **Raw Device Events**: Capturing input from input devices without any OS filtering. - **Gamepad/Joystick events**: Capturing input from gampads and joysticks. - **Device movement events:**: Capturing input from the device gyroscope and accelerometer. From 54abf0a54d9ed196f8a2f5faf0070ae0d6e97367 Mon Sep 17 00:00:00 2001 From: Osspial Date: Mon, 8 Apr 2019 18:16:43 -0400 Subject: [PATCH 19/19] Improve formatting and add guide for extending #Features --- FEATURES.md | 40 +++++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/FEATURES.md b/FEATURES.md index 50f1383688..84344e1dce 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -51,24 +51,40 @@ exposed through the core, cross-platform API. # Features +## Extending this section + +If your PR makes notable changes to Winit's features, please update this section as follows: + +- If your PR adds a new feature, add a brief description to the relevant section. If the feature is a core + feature, add a row to the feature matrix and describe what platforms the feature has been implemented on. + +- If your PR begins a new API rework, add a row to the `Pending API Reworks` table. If the PR implements the + API rework on all relevant platforms, please move it to the `Completed API Reworks` table. + +- If your PR implements an already-existing feature on a new platform, either mark the feature as *completed*, + or mark it as *mostly completed* and link to an issue describing the problems with the implementation. + ## Core ### Windowing - **Window initialization**: Winit allows the creation of a window -- **Pointer to OpenGL**: Winit provides the necessary pointers to initialize a working opengl context -- **Pointer to Vulkan**: Same as OpenGL but for Vulkan +- **Providing pointer to init OpenGL**: Winit provides the necessary pointers to initialize a working opengl context +- **Providing pointer to init Vulkan**: Same as OpenGL but for Vulkan - **Window decorations**: The windows created by winit are properly decorated, and the decorations can be deactivated - **Window decorations toggle**: Decorations can be turned on or off after window creation - **Window resizing**: The windows created by winit can be resized and generate the appropriate events - when they are. The application can precisely control its window size if wanted. + when they are. The application can precisely control its window size if desired. +- **Window resize increments**: When the window gets resized, the application can choose to snap the window's + size to specific values. - **Window transparency**: Winit allows the creation of windows with a transparent background. - **Window maximization**: The windows created by winit can be maximized upon creation. - **Window maximization toggle**: The windows created by winit can be maximized and unmaximized after creation. -- **Fullscreen**: The windows created by winit support being fullscreen. +- **Fullscreen**: The windows created by winit can be put into fullscreen mode. - **Fullscreen toggle**: The windows created by winit can be switched to and from fullscreen after creation. +- **HiDPI support**: Winit assists developers in appropriately scaling HiDPI content. - **Popup windows**: Windows can be created relative to the client area of other windows, and parent windows can be disabled in favor of popup windows. This feature also guarantees that popup windows get drawn above their owner. @@ -115,9 +131,7 @@ exposed through the core, cross-platform API. ## Usability * `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial) -# Compatibility Matrix - -Each section includes a collapsed description of the features it lists. +## Compatibility Matrix Legend: @@ -127,7 +141,7 @@ Legend: - **N/A**: Not applicable for this platform - ❓: Unknown status -## Windowing +### Windowing |Feature |Windows|MacOS |Linux x11 |Linux Wayland |Android|iOS |Emscripten| |-------------------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | |Window initialization |✔️ |✔️ |▢[#5] |✔️ |▢[#33]|▢[#33] |❓ | @@ -145,12 +159,12 @@ Legend: |HiDPI support |✔️ |✔️ |✔️ |✔️ |▢[#721]|✔️ |✔️ | |Popup windows |❌ |❌ |❌ |❌ |❌ |❌ |❌ | -## System information +### System information |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | |Monitor list |✔️ |✔️ |✔️ |✔️ |**N/A**|**N/A**|**N/A** | -## Input handling +### Input handling |Feature |Windows |MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| |----------------------- | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | |Mouse events |✔️ |▢[#63] |✔️ |✔️ |**N/A**|**N/A**|✔️ | @@ -165,7 +179,7 @@ Legend: |Gamepad/Joystick events |❌[#804] |❌ |❌ |❌ |❌ |❌ |❌ | |Device movement events |❓ |❓ |❓ |❓ |❌ |❌ |❌ | -## Pending API Reworks +### Pending API Reworks Changes in the API that have been agreed upon but aren't implemented across all platforms. |Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| @@ -174,6 +188,10 @@ Changes in the API that have been agreed upon but aren't implemented across all |Event Loop 2.0 ([#459]) |✔️ |❌ |❌ |✔️ |❌ |❌ |❌ | |Keyboard Input ([#812]) |❌ |❌ |❌ |❌ |❌ |❌ |❌ | +### Completed API Reworks +|Feature |Windows|MacOS |Linux x11|Linux Wayland|Android|iOS |Emscripten| +|------------------------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- | + [#165]: https://github.com/tomaka/winit/issues/165 [#219]: https://github.com/tomaka/winit/issues/219 [#242]: https://github.com/tomaka/winit/issues/242