Merge branch 'xdg-surface-shape' into 'main'

staging: add xdg-surface-shape-v1

See merge request wayland/wayland-protocols!449

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,168 @@
+<?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 its shape.
+
+        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
+      its associated xdg_surface to the compositor.
+
+      If the xdg_surface associated with the xdg_surface_shape_v1
+      object has been destroyed, any further requests to this object
+      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 windows
+        whose geometry is shaped as a rounded rectangle.
+
+        The corner radii hint is double-buffered and will be applied on
+        the next wl_surface.commit.
+
+        The values are in logical pixels and define the corner radii of the window
+        geometry of associated xdg_surface (see xdg_surface.set_window_geometry).
+        If any value exceeds half of either dimension of the window geometry
+        the radius_too_large protocol error is raised.
+
+        If your surface's visual geometry shape isn't a rounded rectangle,
+        then you shouldn't use this request to set the corner radii,
+        as the shape won't match what the compositor expects.
+
+        For example, do not use this request if your surface:
+          - is freeform or has a custom shape
+          - is a rounded rectangle, but this rectangle doesn't exactly match
+            your xdg_surface window geometry
+
+        If your surface's geometry is a rounded rectangle, but not for every corner
+        (e.g. only one of the corners is a free-form shape), then you can set that
+        corner's value to 0 (implying a square corner) or to some reasonable
+        approximation of a circle corner.
+
+        If your surface's geometry is a rectangle with square corners, it is still
+        useful to explicitly set the radii to 0, since that lets the compositor
+        differentiate known-square windows from freeform windows.
+
+        For known-square windows the compositor can draw a border around the window,
+        whereas for freeform windows the compositor may need to draw a solid
+        background, since the window shape is unknown.
+      </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 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>