From 12e1b2546a7d92759b793d32407df31330ece93b Mon Sep 17 00:00:00 2001
From: Frank Praznik <[EMAIL REDACTED]>
Date: Sat, 13 May 2023 12:33:19 -0400
Subject: [PATCH] docs: Add README-wayland
Add a README file for Wayland that lists common issues and limitations.
---
docs/README-wayland.md | 36 ++++++++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
create mode 100644 docs/README-wayland.md
diff --git a/docs/README-wayland.md b/docs/README-wayland.md
new file mode 100644
index 000000000000..e2db21dcc583
--- /dev/null
+++ b/docs/README-wayland.md
@@ -0,0 +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.
\ No newline at end of file