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,16 @@ 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"
+
 /**
  * System theme.
  *

src/video/wayland/SDL_waylandvideo.c

@@ -47,6 +47,7 @@
 
 #include "alpha-modifier-v1-client-protocol.h"
 #include "cursor-shape-v1-client-protocol.h"
+#include "ext-zones-v1-client-protocol.h"
 #include "fractional-scale-v1-client-protocol.h"
 #include "frog-color-management-v1-client-protocol.h"
 #include "idle-inhibit-unstable-v1-client-protocol.h"
@@ -400,6 +401,7 @@ static void handle_wl_output_done(void *data, struct wl_output *output);
 // Initialization/Query functions
 static bool Wayland_VideoInit(SDL_VideoDevice *_this);
 static bool Wayland_GetDisplayBounds(SDL_VideoDevice *_this, SDL_VideoDisplay *display, SDL_Rect *rect);
+static bool Wayland_GetDisplayUsableBounds(SDL_VideoDevice *_this, SDL_VideoDisplay *display, SDL_Rect *rect);
 static void Wayland_VideoQuit(SDL_VideoDevice *_this);
 
 static const char *SDL_WAYLAND_surface_tag = "sdl-window";
@@ -617,6 +619,7 @@ static SDL_VideoDevice *Wayland_CreateDevice(bool require_preferred_protocols)
     device->VideoInit = Wayland_VideoInit;
     device->VideoQuit = Wayland_VideoQuit;
     device->GetDisplayBounds = Wayland_GetDisplayBounds;
+    device->GetDisplayUsableBounds = Wayland_GetDisplayUsableBounds;
     device->SuspendScreenSaver = Wayland_SuspendScreenSaver;
 
     device->PumpEvents = Wayland_PumpEvents;
@@ -661,6 +664,7 @@ static SDL_VideoDevice *Wayland_CreateDevice(bool require_preferred_protocols)
     device->GetWindowSizeInPixels = Wayland_GetWindowSizeInPixels;
     device->GetWindowContentScale = Wayland_GetWindowContentScale;
     device->GetWindowICCProfile = Wayland_GetWindowICCProfile;
+    device->GetWindowBordersSize = Wayland_GetWindowBorderSize;
     device->GetDisplayForWindow = Wayland_GetDisplayForWindow;
     device->DestroyWindow = Wayland_DestroyWindow;
     device->SetWindowHitTest = Wayland_SetWindowHitTest;
@@ -673,6 +677,7 @@ static SDL_VideoDevice *Wayland_CreateDevice(bool require_preferred_protocols)
     device->SyncWindow = Wayland_SyncWindow;
     device->SetWindowFocusable = Wayland_SetWindowFocusable;
     device->ReconfigureWindow = Wayland_ReconfigureWindow;
+    device->SetWindowAlwaysOnTop = Wayland_SetWindowAlwaysOnTop;
 
 #ifdef SDL_USE_LIBDBUS
     if (SDL_SystemTheme_Init())
@@ -731,7 +736,86 @@ VideoBootStrap Wayland_bootstrap = {
     false
 };
 
-static void handle_xdg_output_logical_position(void *data, struct zxdg_output_v1 *xdg_output, int32_t x, int32_t y)
+static void handle_zone_size(void *data, struct ext_zone_v1 *ext_zone_v1, int32_t width, int32_t height)
+{
+    SDL_DisplayData *disp = (SDL_DisplayData *)data;
+
+    // Negative size values mean that zone creation on this output was denied.
+    if (width < 0 || height < 0) {
+        ext_zone_v1_destroy(disp->ext_zone_v1);
+        disp->ext_zone_v1 = NULL;
+        return;
+    }
+
+    disp->zone_width = width ? width : SDL_MAX_SINT32;
+    disp->zone_height = height ? height : SDL_MAX_SINT32;
+
+    if (disp->display) {
+        SDL_VideoDisplay *display = SDL_GetVideoDisplay(disp->display);
+        if (display) {
+            SDL_SendDisplayEvent(display, SDL_EVENT_DISPLAY_USABLE_BOUNDS_CHANGED, width, height);
+        }
+    }
+}
+
+static void handle_zone_handle(void *data, struct ext_zone_v1 *ext_zone_v1, const char *handle)
+{
+    // NOP
+}
+
+static void handle_zone_done(void *data, struct ext_zone_v1 *ext_zone_v1)
+{
+    // NOP
+}
+
+static void handle_zone_item_blocked(void *data, struct ext_zone_v1 *ext_zone_v1, struct ext_zone_item_v1 *item)
+{
+    SDL_WindowData *wind = (SDL_WindowData *)ext_zone_item_v1_get_user_data(item);
+    wind->entering_new_zone = false;
+}
+
+static void handle_zone_item_entered(void *data, struct ext_zone_v1 *ext_zone_v1, struct ext_zone_item_v1 *item)
+{
+    if (item) {
+        SDL_WindowData *wind = (SDL_WindowData *)ext_zone_item_v1_get_user_data(item);
+        wind->current_ext_zone_v1 = ext_zone_v1;
+
+        if (wind->entering_new_zone) {
+            Wayland_ApplyZoneItemPosition(wind);
+        }
+
+        wind->entering_new_zone = false;
+    }
+}
+
+static void handle_zone_item_left(void *data, struct ext_zone_v1 *ext_zone_v1, struct ext_zone_item_v1 *item)
+{
+    if (item) {
+        SDL_WindowData *wind = (SDL_WindowData *)ext_zone_item_v1_get_user_data(item);
+        wind->current_ext_zone_v1 = NULL;
+
+        if (!wind->entering_new_zone) {
+            // If leaving a zone without a new join pending, find a new zone to join.
+            const SDL_DisplayData *display = Wayland_GetDisplayForWindowZone(wind);
+
+            if (display) {
+                ext_zone_v1_add_item(display->ext_zone_v1, item);
+            }
+        }
+    }
+}
+
+static const struct ext_zone_v1_listener zone_listener = {
+    handle_zone_size,
+    handle_zone_handle,
+    handle_zone_done,
+    handle_zone_item_blocked,
+    handle_zone_item_entered,
+    handle_zone_item_left
+};
+
+static void handle_xdg_output_logical_position(void *data, struct zxdg_output_v1 *xdg_output,
+                                               int32_t x, int32_t y)
 {
     SDL_DisplayData *internal = (SDL_DisplayData *)data;
 
@@ -1071,6 +1155,13 @@ static void handle_wl_output_done(void *data, struct wl_output *output)
 
     SDL_SetDisplayHDRProperties(dpy, &internal->HDR);
 
+    // Get the zone for this output, if the extension is available.
+    if (video->ext_zone_manager_v1 && !internal->ext_zone_v1) {
+        internal->ext_zone_v1 = ext_zone_manager_v1_get_zone(video->ext_zone_manager_v1, internal->output);
+        ext_zone_v1_set_user_data(internal->ext_zone_v1, internal);
+        ext_zone_v1_add_listener(internal->ext_zone_v1, &zone_listener, internal);
+    }
+
     if (internal->display == 0) {
         // First time getting display info, initialize the VideoDisplay
         if (internal->physical_width_mm >= internal->physical_height_mm) {
@@ -1197,6 +1288,10 @@ static void Wayland_free_display(SDL_VideoDisplay *display, bool send_event)
             wp_color_management_output_v1_destroy(display_data->wp_color_management_output);
         }
 
+        if (display_data->ext_zone_v1) {
+            ext_zone_v1_destroy(display_data->ext_zone_v1);
+        }
+
         if (display_data->xdg_output) {
             zxdg_output_v1_destroy(display_data->xdg_output);
         }
@@ -1327,6 +1422,10 @@ static void handle_registry_global(void *data, struct wl_registry *registry, uin
         d->wp_alpha_modifier_v1 = wl_registry_bind(d->registry, id, &wp_alpha_modifier_v1_interface, 1);
     } else if (SDL_strcmp(interface, "xdg_toplevel_icon_manager_v1") == 0) {
         d->xdg_toplevel_icon_manager_v1 = wl_registry_bind(d->registry, id, &xdg_toplevel_icon_manager_v1_interface, 1);
+    } else if (SDL_strcmp(interface, "ext_zone_manager_v1") == 0) {
+        if (SDL_GetHintBoolean(SDL_HINT_VIDEO_WAYLAND_ENABLE_ZONES, false)) {
+            d->ext_zone_manager_v1 = wl_registry_bind(d->registry, id, &ext_zone_manager_v1_interface, 1);
+        }
     } else if (SDL_strcmp(interface, "frog_color_management_factory_v1") == 0) {
         d->frog_color_management_factory_v1 = wl_registry_bind(d->registry, id, &frog_color_management_factory_v1_interface, 1);
     } else if (SDL_strcmp(interface, "wp_color_manager_v1") == 0) {
@@ -1462,11 +1561,18 @@ bool Wayland_VideoInit(SDL_VideoDevice *_this)
     // Second roundtrip to receive all output events.
     WAYLAND_wl_display_roundtrip(data->display);
 
+    // Third roundtrip, if necessary, to retrieve zone info.
+    if (data->ext_zone_manager_v1) {
+        WAYLAND_wl_display_roundtrip(data->display);
+    }
+
     Wayland_FinalizeDisplays(data);
 
     Wayland_InitMouse(data);
     Wayland_InitKeyboard(_this);
 
+    SDL_SetBooleanProperty(SDL_GetGlobalProperties(), SDL_PROP_GLOBAL_VIDEO_WAYLAND_HAS_ZONES_BOOLEAN, !!data->ext_zone_manager_v1);
+
     if (data->primary_selection_device_manager) {
         _this->SetPrimarySelectionText = Wayland_SetPrimarySelectionText;
         _this->GetPrimarySelectionText = Wayland_GetPrimarySelectionText;
@@ -1508,6 +1614,22 @@ static bool Wayland_GetDisplayBounds(SDL_VideoDevice *_this, SDL_VideoDisplay *d
     return true;
 }
 
+static bool Wayland_GetDisplayUsableBounds(SDL_VideoDevice *_this, SDL_VideoDisplay *display,  SDL_Rect *rect)
+{
+    SDL_DisplayData *internal = display->internal;
+
+    if (internal->ext_zone_v1) {
+        rect->x = internal->x;
+        rect->y = internal->y;
+        rect->w = internal->zone_width;
+        rect->h = internal->zone_height;
+
+        return true;
+    }
+
+    return Wayland_GetDisplayBounds(_this, display, rect);
+}
+
 static void Wayland_VideoCleanup(SDL_VideoDevice *_this)
 {
     SDL_VideoData *data = _this->internal;
@@ -1642,6 +1764,11 @@ static void Wayland_VideoCleanup(SDL_VideoDevice *_this)
         data->xdg_toplevel_icon_manager_v1 = NULL;
     }
 
+    if (data->ext_zone_manager_v1) {
+        ext_zone_manager_v1_destroy(data->ext_zone_manager_v1);
+        data->ext_zone_manager_v1 = NULL;
+    }
+
     if (data->frog_color_management_factory_v1) {
         frog_color_management_factory_v1_destroy(data->frog_color_management_factory_v1);
         data->frog_color_management_factory_v1 = NULL;

src/video/wayland/SDL_waylandvideo.h

@@ -87,6 +87,7 @@ struct SDL_VideoData
     struct zwp_tablet_manager_v2 *tablet_manager;
     struct wl_fixes *wl_fixes;
     struct zwp_pointer_gestures_v1 *zwp_pointer_gestures;
+    struct ext_zone_manager_v1 *ext_zone_manager_v1;
 
     struct xkb_context *xkb_context;
 
@@ -109,12 +110,14 @@ struct SDL_DisplayData
     struct wl_output *output;
     struct zxdg_output_v1 *xdg_output;
     struct wp_color_management_output_v1 *wp_color_management_output;
+    struct ext_zone_v1 *ext_zone_v1;
     char *wl_output_name;
     double scale_factor;
     uint32_t registry_id;
     int logical_width, logical_height;
     int pixel_width, pixel_height;
     int x, y, refresh, transform;
+    int zone_width, zone_height;
     SDL_DisplayOrientation orientation;
     int physical_width_mm, physical_height_mm;
     bool has_logical_position, has_logical_size;