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.
xdg_surface_shape_manager_v1
Manager for creating surface shape objects for existing xdg-surfaces
destroy()
Informs the server that the client will no longer use this global. Any previously created surface-shape objects remain valid until destroyed.
get_surface_shape(id: new_id<xdg_surface_shape_v1>, surface: object<xdg_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<xdg_surface_shape_v1> | the new xdg_surface_shape_v1 object |
| surface | object<xdg_surface> | the 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.
error { surface_shape_exists }
Argument | Value | Description |
|---|---|---|
| surface_shape_exists | 0 | the surface already has a surface_shape object |
xdg_surface_shape_v1
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.
destroy()
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.
set_corner_radii(top_left: uint, top_right: uint, bottom_right: uint, bottom_left: uint)
Argument | Type | Description |
|---|---|---|
| top_left | uint | top-left corner radius |
| top_right | uint | top-right corner radius |
| bottom_right | uint | bottom-right corner radius |
| bottom_left | uint | bottom-left corner radius |
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.
unset_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.
error { surface_destroyed, radius_too_large }
Argument | Value | Description |
|---|---|---|
| surface_destroyed | 0 | the associated xdg-surface object has been already destroyed |
| radius_too_large | 1 | the associated xdg-surface's window geometry isn't large enough for a requested radius |
Compositor Support
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.