| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<protocol name="xx_cutouts_unstable_v1"> |
| 3 |
|
| 4 |
<copyright> |
| 5 |
Copyright © 2026 Phosh.mobi e.V. |
| 6 |
|
| 7 |
Permission is hereby granted, free of charge, to any person obtaining a |
| 8 |
copy of this software and associated documentation files (the "Software"), |
| 9 |
to deal in the Software without restriction, including without limitation |
| 10 |
the rights to use, copy, modify, merge, publish, distribute, sublicense, |
| 11 |
and/or sell copies of the Software, and to permit persons to whom the |
| 12 |
Software is furnished to do so, subject to the following conditions: |
| 13 |
|
| 14 |
The above copyright notice and this permission notice (including the next |
| 15 |
paragraph) shall be included in all copies or substantial portions of the |
| 16 |
Software. |
| 17 |
|
| 18 |
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 19 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 20 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL |
| 21 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 22 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING |
| 23 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER |
| 24 |
DEALINGS IN THE SOFTWARE. |
| 25 |
|
| 26 |
Warning! The protocol described in this file is currently in the |
| 27 |
experimental phase. Backwards incompatible major versions of the protocol |
| 28 |
are to be expected. Exposing this protocol without an opt-in mechanism is |
| 29 |
discouraged. |
| 30 |
</copyright> |
| 31 |
|
| 32 |
<description summary="Protocol to describe cut out surface regions"> |
| 33 |
This protocol describes the areas of a toplevel that are cut out |
| 34 |
of the available surface area by hardware elements present in the |
| 35 |
physical display. This allows clients to avoid placing user interface |
| 36 |
elements in those areas. |
| 37 |
|
| 38 |
Typical cutout areas are notches (i.e. embedding a camera) or |
| 39 |
"waterfall" display edges. In the case of a notch the compositor |
| 40 |
would usually supply the bounding box of the notch or an |
| 41 |
approximation by multiple rectangles. Thus a single physical |
| 42 |
element in the display can correspond to multiple cutout events in |
| 43 |
the protocol. |
| 44 |
|
| 45 |
The protocol currently supports xdg_toplevel surfaces but is meant |
| 46 |
to be extended to other surfaces (like layer surfaces) in the |
| 47 |
future. |
| 48 |
|
| 49 |
Warning! The protocol described in this file is experimental and |
| 50 |
backward incompatible changes may be made. Backward compatible |
| 51 |
changes may be added together with the corresponding interface |
| 52 |
version bump. Backward incompatible changes can only be done by |
| 53 |
creating a new major version of the extension. |
| 54 |
</description> |
| 55 |
|
| 56 |
<interface name="xx_cutouts_manager_v1" version="1"> |
| 57 |
<description summary="Display cutouts area manager"> |
| 58 |
This interface allows a compositor to announce support for |
| 59 |
supplying cutout information to the client. |
| 60 |
</description> |
| 61 |
|
| 62 |
<enum name="error"> |
| 63 |
<entry name="invalid_role" value="0" summary="given wl_surface has incorrect role"/> |
| 64 |
<entry name="defunct_cutouts_object" value="1" |
| 65 |
summary="wl_surface or surface role was destroyed before the cutouts object"/> |
| 66 |
</enum> |
| 67 |
|
| 68 |
<request name="destroy" type="destructor"> |
| 69 |
<description summary="destroy the xx_cutouts_manager object"> |
| 70 |
Using this request a client can tell the server that it is not |
| 71 |
going to use the xx_cutouts_manger object anymore. |
| 72 |
|
| 73 |
Any objects already created through this instance are not affected. |
| 74 |
</description> |
| 75 |
</request> |
| 76 |
|
| 77 |
<request name="get_cutouts"> |
| 78 |
<description summary="create a cutout notifier from a xdg toplevel"> |
| 79 |
This creates a new xx_cutouts object for the given |
| 80 |
surface. The role of the surface must be xdg_toplevel |
| 81 |
otherwise an invalid_role protocol error will be raised. Later |
| 82 |
versions of this protocol might allow for other surface roles. |
| 83 |
</description> |
| 84 |
<arg name="id" type="new_id" interface="xx_cutouts_v1"/> |
| 85 |
<arg name="surface" type="object" interface="wl_surface"/> |
| 86 |
</request> |
| 87 |
|
| 88 |
</interface> |
| 89 |
|
| 90 |
<interface name="xx_cutouts_v1" version="1"> |
| 91 |
<description summary="cutout regions information"> |
| 92 |
An xx_cutouts describes the areas currently "cut out" of a |
| 93 |
toplevel. |
| 94 |
|
| 95 |
Each cutout event carries an id that identifies the |
| 96 |
physical element. If the compositor describes an element by |
| 97 |
multiple cutout events these should use the same element |
| 98 |
id. A typical example is a curved notch that is approximated |
| 99 |
by several cutout_box elements. Using the same element |
| 100 |
id allows the client to identify that these belong to the |
| 101 |
same physical object. Ids are only valid during one configure |
| 102 |
sequence. No guarantee is given that the same id identifies |
| 103 |
the same element in different configure sequences. |
| 104 |
|
| 105 |
Typically compositors would only send cutout information when |
| 106 |
the toplevel enters fullscreen or maxmized state (as specified |
| 107 |
in the xdg_shell protocol). |
| 108 |
|
| 109 |
The xx_cutouts_v1 object must be destroyed before its |
| 110 |
underlying xdg_toplevel and wl_surface. Otherwise the |
| 111 |
defunct_cutouts_object protocol error will be send. |
| 112 |
</description> |
| 113 |
|
| 114 |
<enum name="type"> |
| 115 |
<description summary="Cutout type"> |
| 116 |
These values indicate the type of cutout. The information is |
| 117 |
meant to help clients to decide whether they can possibly |
| 118 |
ignore the element. |
| 119 |
</description> |
| 120 |
|
| 121 |
<entry name="cutout" value="0"> |
| 122 |
<description summary="A generic cutout"> |
| 123 |
This element type can be used by the compositor if it |
| 124 |
doesn't want to provide a more specific type. |
| 125 |
</description> |
| 126 |
</entry> |
| 127 |
<entry name="notch" value="1"> |
| 128 |
<description summary="Small functional cutout area"> |
| 129 |
A functional, irregular shape on one of the device's |
| 130 |
edges. It often contains a camera. |
| 131 |
</description> |
| 132 |
</entry> |
| 133 |
<entry name="waterfall" value="2"> |
| 134 |
<description summary="A curved display edge"> |
| 135 |
A curved display edge intended to make the device appear |
| 136 |
like not having any bezel. |
| 137 |
</description> |
| 138 |
</entry> |
| 139 |
</enum> |
| 140 |
|
| 141 |
<enum name="corner_position"> |
| 142 |
<description summary="Corner position"> |
| 143 |
The position of a corner on a surface |
| 144 |
</description> |
| 145 |
|
| 146 |
<entry name="top_left" value="0"/> |
| 147 |
<entry name="top_right" value="1"/> |
| 148 |
<entry name="bottom_right" value="2"/> |
| 149 |
<entry name="bottom_left" value="3"/> |
| 150 |
</enum> |
| 151 |
|
| 152 |
<enum name="error"> |
| 153 |
<entry name="invalid_element_id" value="0" |
| 154 |
summary="Invalid element id in a set_unhandled request"/> |
| 155 |
</enum> |
| 156 |
|
| 157 |
<request name="destroy" type="destructor"> |
| 158 |
<description summary="destroy the xx_cutouts object"> |
| 159 |
Using this request a client can tell the server that it is not |
| 160 |
going to use the xx_cutouts object anymore. |
| 161 |
</description> |
| 162 |
</request> |
| 163 |
|
| 164 |
<event name="cutout_box"> |
| 165 |
<description summary="A rectangular cutout region"> |
| 166 |
The cutout_box event describes a rectangular cutout area in |
| 167 |
surface-local coordinates. |
| 168 |
|
| 169 |
This can be an approximation of e.g. a circular camera notch. |
| 170 |
</description> |
| 171 |
<arg name="x" type="int" |
| 172 |
summary="x coordinate of the box's top left corner"/> |
| 173 |
<arg name="y" type="int" |
| 174 |
summary="y coordinate of the box's top left corner"/> |
| 175 |
<arg name="width" type="int"/> |
| 176 |
<arg name="height" type="int"/> |
| 177 |
<arg name="type" type="uint" enum="type" summary="The type of cutout"/> |
| 178 |
<arg name="id" type="uint" summary="An identifier identifying the physical element"/> |
| 179 |
</event> |
| 180 |
|
| 181 |
<event name="cutout_corner"> |
| 182 |
<description summary="A cutout corner"> |
| 183 |
The cutout_corner event describes a rounded corner in |
| 184 |
surface-local coordinates. The area towards the screen edge is |
| 185 |
the cutout corner part. |
| 186 |
</description> |
| 187 |
<arg name="position" type="uint" enum="corner_position" summary="The position of the described corner"/> |
| 188 |
<arg name="radius" type="uint" summary="The corner's radius"/> |
| 189 |
<arg name="id" type="uint" summary="An identifier identifying the physical element"/> |
| 190 |
</event> |
| 191 |
|
| 192 |
<event name="configure"> |
| 193 |
<description summary="notify cutout changes"> |
| 194 |
The configure event marks the end of a configure sequence. A |
| 195 |
configure sequence is a set of zero or more cutout events and |
| 196 |
the final xx_cutout.configure event. |
| 197 |
|
| 198 |
In the case of a xdg_toplevel clients should arrange their |
| 199 |
surface for the new cutouts, and then send an |
| 200 |
xdg_surface.ack_configure request at some point before |
| 201 |
committing the new surface. See xdg_surface.configure and |
| 202 |
xdg_surface.ack_configure in the xdg_shell protocol for |
| 203 |
details. |
| 204 |
|
| 205 |
If the cutout sequence consists of only a configure event and |
| 206 |
contains no cutout or corner events this indicates that the |
| 207 |
surface isn't overlapping with any cutouts or corners. |
| 208 |
|
| 209 |
If the client receives multiple configure events before it can |
| 210 |
respond to one, it is free to discard all but the last event |
| 211 |
it received. |
| 212 |
</description> |
| 213 |
</event> |
| 214 |
|
| 215 |
<request name="set_unhandled"> |
| 216 |
<description summary="Notify about unhandled cutouts"> |
| 217 |
If a client doesn't handle one or more cutouts in the to be |
| 218 |
acked sequence, it can add their element's id to the |
| 219 |
unhandled array. The compositor might then try to reposition |
| 220 |
the surface in a way that avoids these elements in a future |
| 221 |
configure sequence. |
| 222 |
|
| 223 |
The request (if used) must be sent before acking the configure |
| 224 |
sequence. State set with this request is double-buffered. It |
| 225 |
will get applied on the next ack_configure and stay valid |
| 226 |
until the next configure event. |
| 227 |
</description> |
| 228 |
<arg name="unhandled" type="array" summary="array of unhandled element ids"/> |
| 229 |
</request> |
| 230 |
|
| 231 |
</interface> |
| 232 |
</protocol> |