Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Winit Features and Scope #695

Merged
merged 19 commits into from
Apr 13, 2019
+218 −23
Merged

Winit Features and Scope #695

Show file tree
Hide file tree
Changes from 16 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
1605adc
Add initial draft of SCOPE document
Osspial Nov 10, 2018
1133995
Rephrase/rename feature tiers
Osspial Nov 10, 2018
4df37e4
Rename to FEATURES and add a few annotations
Osspial Nov 10, 2018
cd6a6c8
Fix API Reworks table
Osspial Nov 10, 2018
479cf5d
Add more annotations
Osspial Nov 10, 2018
81d7458
Some phrasing
Osspial Nov 10, 2018
915eb6d
Split compat matrix into seperate section, to be moved into wiki
Osspial Nov 11, 2018
f99c8ea
Mention compatibility in CONTRIBUTING
Osspial Nov 11, 2018
fe70a66
Remove some discuss annotations
Osspial Nov 13, 2018
8b5065e
Apply review changes and rename child windows feature to popup windows
Osspial Nov 17, 2018
8c64495
Update based on discussion
Osspial Nov 20, 2018
ed0a3a6
Add issue for Android HiDPI
Osspial Nov 20, 2018
67b9176
Update FEATURES.md
Osspial Dec 31, 2018
bf2fb85
Update FEATURES.md
Osspial Apr 8, 2019
554cd23
Update PULL_REQUEST_TEMPLATE.md
Osspial Apr 8, 2019
26c41ba
Update PULL_REQUEST_TEMPLATE.md
Osspial Apr 8, 2019
60208e5
Reformat FEATURES.MD
Osspial Apr 8, 2019
ad41504
Remove comments
Osspial Apr 8, 2019
54abf0a
Improve formatting and add guide for extending #Features
Osspial Apr 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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](TODO: LINK), if new features were added or implemented
31 changes: 8 additions & 23 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,14 @@
# Winit Contributing Guidelines

## 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

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
Expand All @@ -41,9 +23,12 @@ 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
- 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
Expand Down
178 changes: 178 additions & 0 deletions FEATURES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,178 @@
# 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

## Core

Osspial marked this conversation as resolved.
Show resolved Hide resolved
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
- **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 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.
- **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.
***//DISCUSS: WINIT SUPPORTS FILE DROPS, BUT NOT TEXT OR IMAGE DROPS***
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this is a point I discussed in an earlier issue / PR. I don't know how this works for other platforms, but in wayland, drag'n'drop is unified for all kind of contents. The way it works is that the application starting the d'n'd and the application receiving it negociate a mime type for the data transfer. Dragging files from a file explorer is just a special case of this.

Can this kind of general behavior be transposed to other platforms?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume? I know that it works on Windows, and I'm pretty sure I've done it before on macOS and X11 but I can't quite recall.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can confirm that it's similar on X11 and macOS, so I think we can reasonably provide this functionality.

Also, what about knowing the hover position and being able to decide whether to accept or reject a drop (based on both position and type)? Anyone building GUIs on top of winit will demand this, and it's at least easy to implement on X11.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, what about knowing the hover position and being able to decide whether to accept or reject a drop (based on both position and type)?

That's also the natural way it works on wayland. With the added case that the sender application can actually provide a list of available mime types that the receiver can choose from.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From skimming the Windows code, that also seems to be how Windows does it. The one question I have is how do we implement communication from the callback back to the operating system to accept or reject the drop? The best way I can think of doing it would be to pass a mutable reference along with the event that the callback can modify (as otherwise we're getting into the realm of having different return types for different events), but that isn't possible on Windows before Event Loop 2.0 gets merged.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another thing - Winit supports dragging content into windows. Should we support dragging content from windows? In principle I'm not opposed to it, but I don't know what the API would look like and it starts to turn Winit from windowing and user input to general cross-platform desktop interfacing which is a substantially bigger project.

Perhaps we could publicly expose some of Winit's internals in a permanently unstable way (say, hide them behind a feature or make them all #[doc(hidden)]) and split that into a separate crate, alongside non-windowing stuff like clipboard handling? Doing that would have issues and I'm honestly not entirely sold on it myself, but it would allow us to keep the core of Winit simple and build more specialized libraries around it.

- **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 - 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 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) |❌ |❌ |❌ |❌ |❌ |❌ |❌ |