mirror of
https://github.com/italicsjenga/winit-sonoma-fix.git
synced 2024-12-24 06:11:30 +11:00
Winit Features and Scope (#695)
* Add initial draft of SCOPE document * Rephrase/rename feature tiers * Rename to FEATURES and add a few annotations * Fix API Reworks table * Add more annotations * Some phrasing * Split compat matrix into seperate section, to be moved into wiki * Mention compatibility in CONTRIBUTING * Remove some discuss annotations * Apply review changes and rename child windows feature to popup windows * Update based on discussion * Add issue for Android HiDPI * Update FEATURES.md * Update FEATURES.md * Update PULL_REQUEST_TEMPLATE.md * Update PULL_REQUEST_TEMPLATE.md * Reformat FEATURES.MD * Remove comments * Improve formatting and add guide for extending #Features
This commit is contained in:
Osspial
Victor Berger
parent
94f998af0a
commit
e579a03035
1
.github/PULL_REQUEST_TEMPLATE.md
vendored
1
.github/PULL_REQUEST_TEMPLATE.md
vendored
|
|
@ -2,3 +2,4 @@
|
||||||
- [ ] Added an entry to `CHANGELOG.md` if knowledge of this change could be valuable to users
|
- [ ] 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
|
- [ ] 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
|
- [ ] Created an example program if it would help users understand this functionality
|
||||||
|
- [ ] Updated [feature matrix](TODO: LINK), if new features were added or implemented
|
||||||
|
|
|
||||||
|
|
@ -1,28 +1,10 @@
|
||||||
# Winit Contributing Guidelines
|
# Winit Contributing Guidelines
|
||||||
|
|
||||||
## Scope
|
## Scope
|
||||||
|
[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.
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
## Reporting an issue
|
## Reporting an issue
|
||||||
|
|
||||||
|
|
@ -44,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
|
- 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
|
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
|
- 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
|
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
|
is that a PR must be approved by at least two maintainers of winit before being merged, including
|
||||||
|
|
|
||||||
209
FEATURES.md
Normal file
209
FEATURES.md
Normal file
|
|
@ -0,0 +1,209 @@
|
||||||
|
# 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
|
||||||
|
|
||||||
|
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.
|
||||||
|
- **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.
|
||||||
|
|
||||||
|
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
|
||||||
|
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. 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
|
||||||
|
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
|
||||||
|
|
||||||
|
## 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
|
||||||
|
- **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 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 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.
|
||||||
|
|
||||||
|
|
||||||
|
### System Information
|
||||||
|
- **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.
|
||||||
|
- **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.
|
||||||
|
- **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.
|
||||||
|
|
||||||
|
## Platform
|
||||||
|
### Windows
|
||||||
|
* Setting the taskbar icon
|
||||||
|
* Setting the parent window
|
||||||
|
* `WS_EX_NOREDIRECTIONBITMAP` support
|
||||||
|
|
||||||
|
### macOS
|
||||||
|
* Window activation policy
|
||||||
|
* Window movable by background
|
||||||
|
* Transparent titlebar
|
||||||
|
* Hidden titlebar
|
||||||
|
* Hidden titlebar buttons
|
||||||
|
* Full-size content view
|
||||||
|
|
||||||
|
### Unix
|
||||||
|
* Window urgency
|
||||||
|
* X11 Window Class
|
||||||
|
* X11 Override Redirect Flag
|
||||||
|
* GTK Theme Variant
|
||||||
|
* Base window size
|
||||||
|
|
||||||
|
## Usability
|
||||||
|
* `serde`: Enables serialization/deserialization of certain types with Serde. (Maintainer: @Osspial)
|
||||||
|
|
||||||
|
## Compatibility Matrix
|
||||||
|
|
||||||
|
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 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|
|
||||||
|
|------------ | ----- | ---- | ------- | ----------- | ----- | ----- | -------- |
|
||||||
|
|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 |❓ |❓ |❓ |❓ |❌ |❌ |❌ |
|
||||||
|
|
||||||
|
### 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]) |❌ |❌ |❌ |❌ |❌ |❌ |❌ |
|
||||||
|
|
||||||
|
### 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
|
||||||
|
[#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
|
||||||
Loading…
Reference in a new issue