mirrors
/
SDL
mirror of https://github.com/libsdl-org/SDL
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

This commit is contained in:
SDL Wiki Bot 2023-05-13 16:55:14 +00:00
parent 12e1b2546a
commit 78251f973d
1 changed files with 36 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/README-wayland.md
View File

@ -1,36 +1,36 @@
Wayland
=======
Wayland is a replacement for the X11 window system protocol and architecture and is favored over X11 by default in SDL3
for communicating with desktop compositors. It works well for the majority of applications, however, applications may
encounter limitations or behavior that is different from other windowing systems.
## Common issues:
### Window decorations are missing, or the decorations look strange
- On some desktops (i.e. GNOME), Wayland applications use a library
called [libdecor](https://gitlab.freedesktop.org/libdecor/libdecor) to provide window decorations. If this library is
not installed, the decorations will be missing. This library uses plugins to generate different decoration styles, and
if a plugin to generate native-looking decorations is not installed (i.e. the GTK plugin), the decorations will not
appear to be 'native'.
### Windows do not appear immediately after creation
- Wayland requires that the application initially present a buffer before the window becomes visible. Additionally,
applications _must_ have an event loop and processes messages on a regular basis, or the application can appear
unresponsive to both the user and desktop compositor.
### ```SDL_SetWindowPosition()``` doesn't work on non-popup windows
- Wayland does not allow toplevel windows to position themselves programmatically.
### Retrieving the global mouse cursor position when the cursor is outside a window doesn't work
- Wayland only provides applications with the cursor position within the borders of the application windows. Querying
the global position when an application window does not have mouse focus returns 0,0 as the actual cursor position is
unknown. In most cases, applications don't actually need the global cursor position and should use the window-relative
coordinates as provided by the mouse movement event or from ```SDL_GetMouseState()``` instead.
### Warping the global mouse cursor position via ```SDL_WarpMouseGlobal()``` doesn't work
- For security reasons, Wayland does not allow warping the global mouse cursor position.
Wayland
=======
Wayland is a replacement for the X11 window system protocol and architecture and is favored over X11 by default in SDL3
for communicating with desktop compositors. It works well for the majority of applications, however, applications may
encounter limitations or behavior that is different from other windowing systems.
## Common issues:
### Window decorations are missing, or the decorations look strange
- On some desktops (i.e. GNOME), Wayland applications use a library
called [libdecor](https://gitlab.freedesktop.org/libdecor/libdecor) to provide window decorations. If this library is
not installed, the decorations will be missing. This library uses plugins to generate different decoration styles, and
if a plugin to generate native-looking decorations is not installed (i.e. the GTK plugin), the decorations will not
appear to be 'native'.
### Windows do not appear immediately after creation
- Wayland requires that the application initially present a buffer before the window becomes visible. Additionally,
applications _must_ have an event loop and processes messages on a regular basis, or the application can appear
unresponsive to both the user and desktop compositor.
### ```SDL_SetWindowPosition()``` doesn't work on non-popup windows
- Wayland does not allow toplevel windows to position themselves programmatically.
### Retrieving the global mouse cursor position when the cursor is outside a window doesn't work
- Wayland only provides applications with the cursor position within the borders of the application windows. Querying
the global position when an application window does not have mouse focus returns 0,0 as the actual cursor position is
unknown. In most cases, applications don't actually need the global cursor position and should use the window-relative
coordinates as provided by the mouse movement event or from ```SDL_GetMouseState()``` instead.
### Warping the global mouse cursor position via ```SDL_WarpMouseGlobal()``` doesn't work
- For security reasons, Wayland does not allow warping the global mouse cursor position.