xdg_cutouts_unstable_v1
This protocol describes the areas of a toplevel that are cut out of the available surface area by hardware elements present in the physical display. This allows fullscreen or maximized clients to avoid placing user interface elements in those areas.
Typical cutout areas are notches (i.e. embedding a camera) or "waterfall" display edges. In the case of a notch the compositor would usually supply the bounding box of the notch or an approximation by multiple rectangles. Thus a single physical element in the display can correspond to multiple cutout events in the protocol.
Warning! The protocol described in this file is experimental and backward incompatible changes may be made. Backward compatible changes may be added together with the corresponding interface version bump. Backward incompatible changes can only be done by creating a new major version of the extension.
xdg_cutouts_manager_v1
This interface allows a compositor to announce support for supplying cutout information to the client.
destroy()
Using this request a client can tell the server that it is not going to use the xdg_cutouts_manger object anymore.
Any objects already created through this instance are not affected.
get_cutouts(id: new_id<xdg_cutouts_v1>, surface: object<wl_surface>)
Argument | Type | Description |
|---|---|---|
| id | new_id<xdg_cutouts_v1> | |
| surface | object<wl_surface> |
This creates a new xdg_cutouts object for the given surface. The role of the surface must be xdg_toplevel otherwise an invalid_role protocol error will be raised. Later versions of this protocol might allow for other surface roles.
The surface doesn't need to be fullscreen or maximized at this point.
error { invalid_role, defunct_cutouts_object }
Argument | Value | Description |
|---|---|---|
| invalid_role | 0 | given wl_surface has incorrect role |
| defunct_cutouts_object | 1 | wl_surface or surface role was destroyed before the cutouts object |
xdg_cutouts_v1
An xdg_cutouts describes the areas currently "cut out" of a toplevel.
If the toplevel gets maximized or fullscreened (as specified in the xdg_shell protocol) the compositor sends a list of events describing the cutout areas via this interface.
Each cutout event carries an id that identifies the physical element. If the compositor describes an element by multiple cutout events these should use the same element id. A typical example is a curved notch that is approximated by several cutout_box elements. Using the same element id allows the client to identify that these belong to the same physical object. Ids are only during one configure sequence. No guarantee is given that the same id identifies the same element in different configure sequences.
Compositors shouldn't send cutout information when the toplevel doesn't have fullscreen or maxmized state (as specified in the xdg_shell protocol).
The xdg_cutouts_v1 object must be destroyed before its underlying xdg_toplevel and wl_surface. Otherwise the defunct_cutouts_object protocol error will be send.
destroy()
Using this request a client can tell the server that it is not going to use the xdg_cutouts object anymore.
set_unhandled(unhandled: array)
Argument | Type | Description |
|---|---|---|
| unhandled | array | array of unhandled element ids |
If a client doesn't handle one or more cutouts in the to be acked sequence, it can add their element's id to the unhandled array. The compositor might then try to reposition the surface in a way that avoids these elements in a future configure sequence.
The request (if used) must be sent before acking the configure sequence. State set with this request is double-buffered. It will get applied on the next ack_configure and stay valid until the next configure event.
cutout_box(x: int, y: int, width: int, height: int, type: uint<xdg_cutouts_v1.type>, resolution: fixed, id: uint)
Argument | Type | Description |
|---|---|---|
| x | int | x coordinate of the box's top left corner |
| y | int | y coordinate of the box's top left corner |
| width | int | |
| height | int | |
| type | uint<xdg_cutouts_v1.type> | The type of cutout |
| resolution | fixed | The areas resolution A resolution greater than 0 indicates that the cutout area isn't fully opaque but that fewer pixels are backing that area and it hence has a lower resolution. The resolution is given as a fraction of the surface scale and greater or equal 0 and smaller than 1. |
| id | uint | An identifier identifying the physical element |
The cutout_box event describes a rectangular cutout area in surface-local coordinates.
This can be an approximation of e.g. a circular camera notch.
cutout_corner(position: uint<xdg_cutouts_v1.corner_position>, radius: uint, id: uint)
Argument | Type | Description |
|---|---|---|
| position | uint<xdg_cutouts_v1.corner_position> | The position of the described corner |
| radius | uint | The corner's radius |
| id | uint | An identifier identifying the physical element |
The cutout_corner event describes a rounded corner in surface-local coordinates. The area towards the screen edge is the cutout corner part.
configure()
The configure event marks the end of a configure sequence. A configure sequence is a set of zero or more cutout events and the final xdg_cutout.configure event.
Clients should arrange their surface for the new cutouts, and then send an xdg_surface.ack_configure request at some point before committing the new surface. See xdg_surface.configure and xdg_surface.ack_configure in the xdg_shell protocol for details.
If the cutout sequence consists of only a configure event and contains no cutout events this indicates that the surface isn't overlapping with any cutouts.
If the client receives multiple configure events before it can respond to one, it is free to discard all but the last event it received.
Argument | Value | Description |
|---|---|---|
| cutout | 0 | A generic cutout This element type can be used by the compositor if it doesn't want to provide a more specific type. |
| notch | 1 | Small functional cutout area A functional, irregular shape on one of the device's edges. It often contains a camera. |
| waterfall | 2 | A curved display edge A curved display edge intended to make the device appear like not having any bezel. |
These values indicate the type of cutout. The information is meant to help clients to decide whether they can possibly ignore the element.
corner_position { top_left, top_right, bottom_right, bottom_left }
Argument | Value | Description |
|---|---|---|
| top_left | 0 | |
| top_right | 1 | |
| bottom_right | 2 | |
| bottom_left | 3 |
The position of a corner on a surface
error { invalid_element_id }
Argument | Value | Description |
|---|---|---|
| invalid_element_id | 0 | Invalid element id in a set_unhandled request |
Compositor Support
Copyright
Copyright © 2025 Guido Günther
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.