staging: add xdg-surface-shape-v1

This protocol provides a way for clients to communicate the
shape of their surface, for example the radii of rounded corners.

This hint can then be used by the compositor to draw fitting outlines
or prevent overdrawing of other server-side drawn interfaces.

Signed-off-by: Victoria Brekenfeld <github@drakulix.de>

meson.build

@@ -70,6 +70,7 @@ staging_protocols = {
 	'tearing-control': ['v1'],
 	'xdg-activation': ['v1'],
 	'xdg-dialog': ['v1'],
+	'xdg-surface-shape': ['v1'],
 	'xdg-system-bell': ['v1'],
 	'xdg-toplevel-drag': ['v1'],
 	'xdg-toplevel-icon': ['v1'],

staging/xdg-surface-shape/README

@@ -0,0 +1,4 @@
+Surface shape
+
+Maintainers:
+Victoria Brekenfeld <victoria@system76.com> (@drakulix)

staging/xdg-surface-shape/xdg-surface-shape-v1.xml

@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_surface_shape_v1">
+  <copyright>
+    Copyright © 2025 Victoria Brekenfeld
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="communicate the shape of an xdg surface">
+    This protocol provides a way for clients to communicate the
+    shape of their surface, for example the radii of rounded corners.
+
+    This hint can then be used by the compositor to draw fitting outlines
+    or prevent overdrawing of other server-side drawn interfaces.
+  </description>
+
+  <interface name="xdg_surface_shape_manager_v1" version="1">
+    <description summary="surface shape global">
+      Manager for creating surface shape objects for existing xdg-surfaces
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the global">
+        Informs the server, that the client will no longer use this global.
+        Any previously created surface-shape objects remain valid until destroyed.
+      </description>
+    </request>
+
+    <request name="get_surface_shape">
+      <description summary="Create a new surface-shape object for a xdg_surface">
+        Instantiate an interface extension for the given xdg_surface to specify their corner radius.
+
+        If the given xdg_surface already has a xdg_surface_shape_v1 object associated,
+        the surface_shape_exists protocol error will be raised.
+      </description>
+      <arg name="id" type="new_id" interface="xdg_surface_shape_v1"
+        summary="the new xdg_surface_shape_v1 object"/>
+      <arg name="surface" type="object" interface="xdg_surface"
+        summary="the xdg-surface"/>
+    </request>
+
+    <enum name="error">
+      <entry name="surface_shape_exists" value="0"
+        summary="the surface already has a surface_shape object"/>
+    </enum>
+  </interface>
+
+  <interface name="xdg_surface_shape_v1" version="1">
+    <description summary="surface shape extension">
+      The surface-shape object provides a way to specify the shape of
+      it's associated xdg_surface to the compositor.
+
+      If the xdg_surface associated with the xdg_surface_shape_v1
+      object has been destroyed, this object becomes inert. Any further requests
+      other than destroy will raise the surface_destroyed protocol error.
+    </description>
+
+    <request name="destroy" type="destructor">
+      <description summary="Destroy the surface-shape object">
+        Informs the server that the client will no longer be using this protocol
+        object. The surface-shape state will be unset on the next commit.
+      </description>
+    </request>
+
+    <request name="set_corner_radii">
+      <description summary="Set corner radii">
+        This request sets the hinted corner radii values for rectangular windows.
+
+        The corner radii hint is double-buffered and will be applied on
+        the next wl_surface.commit.
+
+        The value is given in logical space relative to the window geometry of the
+        associated xdg_surface. If any value exceeds a quarter of either dimension
+        of the window geometry the radius_too_large protocol error is raised.
+      </description>
+      <arg name="top_left" type="uint" summary="top-left corner radius"/>
+      <arg name="top_right" type="uint" summary="top-right corner radius"/>
+      <arg name="bottom_right" type="uint" summary="bottom-right corner radius"/>
+      <arg name="bottom_left" type="uint" summary="bottom-left corner radius"/>
+    </request>
+
+    <request name="unset_radii">
+      <description summary="Unset corner radii">
+        Unsets any previously hinted corner radii values without invalidating the object for later use.
+        Can be used by clients that possibly have temporary irregular shapes.
+
+        The corner radii hint is double-buffered, meaning the previous state
+        will still apply until the next wl_surface.commit.
+
+        Compositors should treat a surface with an unset-radii the same as surface
+        with a freshly created xdg_surface_shape_v1 that has no radii set yet or
+        any surface without an xdg_surface_shape_v1 object for that matter.
+      </description>
+    </request>
+
+    <enum name="error">
+      <entry name="surface_destroyed" value="0"
+        summary="the associated xdg-surface object has been already destroyed"/>
+      <entry name="radius_too_large" value="1"
+        summary="the associated xdg-surface's window geometry isn't large enough for a requested radius"/>
+    </enum>
+  </interface>
+</protocol>