wayland: Add experimental zone positioning support

Author: Kontrabant

docs/README-wayland.md

@@ -6,6 +6,22 @@ encounter limitations or behavior that is different from other windowing systems
 
 ## Common issues:
 
+### ```SDL_SetWindowPosition()``` doesn't work on non-popup windows
+
+- Wayland requires the `ext-zones-v1` extension to position windows programmatically. Otherwise, toplevel windows may
+  not be positioned programmatically.\
+  \
+  Enabling this protocol requires setting the `SDL_VIDEO_WAYLAND_ENABLE_ZONES` hint to `1`. After initializing the video
+  subsystem, compositor support for the required protocol may be queried via the
+  `SDL_PROP_GLOBAL_VIDEO_WAYLAND_HAS_ZONES_BOOLEAN` global video property.\
+  \
+  This protocol allows for positioning windows within the boundaries of desktop zones, the coordinates of which may not
+  correspond 1:1 to output display coordinates. This is primarily intended for clients with multi-window interfaces that
+  need to position windows relative to one another, development environments/workflows, and embedded scenarios where
+  positioning is desired and the underlying environment and its capabilities are known. Single window clients should
+  _not_ enable this by default, as it can override compositor window positioning, and tiling window managers in
+  particular may demonstrate undesirable behavior with it.
+
 ### Legacy, DPI-unaware applications are blurry
 
 - Wayland handles high-DPI displays by scaling the desktop, which causes applications that are not designed to be
@@ -34,10 +50,6 @@ encounter limitations or behavior that is different from other windowing systems
   system settings, and falling back to a selection algorithm if this fails. If it is incorrect, it can be manually
   overridden by setting the ```SDL_VIDEO_DISPLAY_PRIORITY``` hint.
 
-### ```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

include/SDL3/SDL_hints.h

@@ -3784,6 +3784,34 @@ extern "C" {
  */
 #define SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR "SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR"
 
+/**
+ * A variable controlling whether to allow positioning of windows via the
+ * `ext-zones-v1` protocol.
+ *
+ * This hint requires that the compositor supports the `ext-zones-v1` protocol.
+ * Support for this protocol can be checked via the global
+ * `SDL_PROP_GLOBAL_VIDEO_WAYLAND_HAS_ZONES_BOOLEAN` property after initializing
+ * the video subsystem with this hint set.
+ *
+ * If the compositor lacks support for the required protocol, this hint does
+ * nothing.
+ *
+ * Zones are arbitrary regions that allow for limited window placement within a
+ * logical space, and should not be presumed to correlate 1:1 to display output
+ * coordinates, so care must be taken when enabling this. See
+ * docs/README-wayland.md and wayland-protocols/ext-zones-v1.xml for more details.
+ *
+ * The variable can be set to the following values:
+ *
+ * - "0": positioning with ext-zones is disabled. (default)
+ * - "1": positioning with ext-zones is enabled.
+ *
+ * This hint should be set before SDL is initialized.
+ *
+ * \since This hint is available since SDL 3.1.6.
+ */
+#define SDL_HINT_VIDEO_WAYLAND_ENABLE_ZONES "SDL_VIDEO_WAYLAND_ENABLE_ZONES"
+
 /**
  * A variable controlling whether video mode emulation is enabled under
  * Wayland.

include/SDL3/SDL_video.h

@@ -100,6 +100,26 @@ typedef Uint32 SDL_WindowID;
  */
 #define SDL_PROP_GLOBAL_VIDEO_WAYLAND_WL_DISPLAY_POINTER "SDL.video.wayland.wl_display"
 
+/**
+ * A boolean set to true if the windowing system supports the optional
+ * ext-zones protocol for positioning windows in Wayland. Requires that the
+ * `SDL_VIDEO_WAYLAND_ENABLE_ZONES` hint be set to enable. See
+ * docs/README-wayland.md for more information.
+ *
+ * Can be queried after video subsystem initialization.
+ */
+#define SDL_PROP_GLOBAL_VIDEO_WAYLAND_HAS_ZONES_BOOLEAN "SDL.video.wayland.has_zones"
+
+/**
+ * A semicolon-separated list containing the mappings of outputs to zone handles, with
+ * list items in the form <display name>=<zone handle>.
+ *
+ * Can be set before the video subsystem is initialized to import a list of existing
+ * zone handles for outputs, or read after initialization to retrieve the current list of
+ * zone handles for outputs.
+ */
+#define SDL_PROP_GLOBAL_VIDEO_WAYLAND_ZONE_MAPPING_STRING "SDL.video.wayland.zone_mapping"
+
 /**
  * System theme.
  *
@@ -1337,6 +1357,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
  * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface
  *   associated with the window, if you want to wrap an existing window. See
  *   [README-wayland](README-wayland) for more information.
+ * - `SDL_PROP_WINDOW_CREATE_WAYLAND_ZONE_LAYER_NUMBER` - the layer for the
+ *   window when the ext-zones protocol is in use. See
+ *   [README-wayland](README-wayland) for more information.
  *
  * These are additional supported properties on Windows:
  *
@@ -1434,6 +1457,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowWithProperties(SDL_Prop
 #define SDL_PROP_WINDOW_CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN "SDL.window.create.wayland.surface_role_custom"
 #define SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN   "SDL.window.create.wayland.create_egl_window"
 #define SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER          "SDL.window.create.wayland.wl_surface"
+#define SDL_PROP_WINDOW_CREATE_WAYLAND_ZONE_LAYER_NUMBER           "SDL.window.create.wayland.zone_layer"
 #define SDL_PROP_WINDOW_CREATE_WIN32_HWND_POINTER                  "SDL.window.create.win32.hwnd"
 #define SDL_PROP_WINDOW_CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER     "SDL.window.create.win32.pixel_format_hwnd"
 #define SDL_PROP_WINDOW_CREATE_X11_WINDOW_NUMBER                   "SDL.window.create.x11.window"