Debian Codegraph @

experimental/xx-cutouts/xx-cutouts-v1.xml

raw
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>