1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="wayland">
3
4 <copyright>
5 Copyright © 2008-2011 Kristian Høgsberg
6 Copyright © 2010-2011 Intel Corporation
7 Copyright © 2012-2013 Collabora, Ltd.
8
9 Permission is hereby granted, free of charge, to any person
10 obtaining a copy of this software and associated documentation files
11 (the "Software"), to deal in the Software without restriction,
12 including without limitation the rights to use, copy, modify, merge,
13 publish, distribute, sublicense, and/or sell copies of the Software,
14 and to permit persons to whom the Software is furnished to do so,
15 subject to the following conditions:
16
17 The above copyright notice and this permission notice (including the
18 next paragraph) shall be included in all copies or substantial
19 portions of the Software.
20
21 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
25 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
26 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
27 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28 SOFTWARE.
29 </copyright>
30
31 <interface name="wl_display" version="1">
32 <description summary="core global object">
33 The core global object. This is a special singleton object. It
34 is used for internal Wayland protocol features.
35 </description>
36
37 <request name="sync">
38 <description summary="asynchronous roundtrip">
39 The sync request asks the server to emit the 'done' event
40 on the returned wl_callback object. Since requests are
41 handled in-order and events are delivered in-order, this can
42 be used as a barrier to ensure all previous requests and the
43 resulting events have been handled.
44
45 The object returned by this request will be destroyed by the
46 compositor after the callback is fired and as such the client must not
47 attempt to use it after that point.
48
49 The callback_data passed in the callback is undefined and should be ignored.
50 </description>
51 <arg name="callback" type="new_id" interface="wl_callback"
52 summary="callback object for the sync request"/>
53 </request>
54
55 <request name="get_registry">
56 <description summary="get global registry object">
57 This request creates a registry object that allows the client
58 to list and bind the global objects available from the
59 compositor.
60
61 It should be noted that the server side resources consumed in
62 response to a get_registry request can only be released when the
63 client disconnects, not when the client side proxy is destroyed.
64 Therefore, clients should invoke get_registry as infrequently as
65 possible to avoid wasting memory.
66 </description>
67 <arg name="registry" type="new_id" interface="wl_registry"
68 summary="global registry object"/>
69 </request>
70
71 <event name="error">
72 <description summary="fatal error event">
73 The error event is sent out when a fatal (non-recoverable)
74 error has occurred. The object_id argument is the object
75 where the error occurred, most often in response to a request
76 to that object. The code identifies the error and is defined
77 by the object interface. As such, each interface defines its
78 own set of error codes. The message is a brief description
79 of the error, for (debugging) convenience.
80 </description>
81 <arg name="object_id" type="object" summary="object where the error occurred"/>
82 <arg name="code" type="uint" summary="error code"/>
83 <arg name="message" type="string" summary="error description"/>
84 </event>
85
86 <enum name="error">
87 <description summary="global error values">
88 These errors are global and can be emitted in response to any
89 server request.
90 </description>
91 <entry name="invalid_object" value="0"
92 summary="server couldn't find object"/>
93 <entry name="invalid_method" value="1"
94 summary="method doesn't exist on the specified interface or malformed request"/>
95 <entry name="no_memory" value="2"
96 summary="server is out of memory"/>
97 <entry name="implementation" value="3"
98 summary="implementation error in compositor"/>
99 </enum>
100
101 <event name="delete_id">
102 <description summary="acknowledge object ID deletion">
103 This event is used internally by the object ID management logic.
104
105 When the server stops using an object created by the client, the server
106 sends this event. In particular, after sending this event, the server
107 will no longer send any events that contain the object as the receiver
108 or as an argument.
109
110 When the client receives this event, it knows that it can reuse the
111 object ID.
112 </description>
113 <arg name="id" type="uint" summary="deleted object ID"/>
114 </event>
115 </interface>
116
117 <interface name="wl_registry" version="1">
118 <description summary="global registry object">
119 The singleton global registry object. The server has a number of
120 global objects that are available to all clients. These objects
121 typically represent an actual object in the server (for example,
122 an input device) or they are singleton objects that provide
123 extension functionality.
124
125 When a client creates a registry object, the registry object
126 will emit a global event for each global currently in the
127 registry. Globals come and go as a result of device or
128 monitor hotplugs, reconfiguration or other events, and the
129 registry will send out global and global_remove events to
130 keep the client up to date with the changes. To mark the end
131 of the initial burst of events, the client can use the
132 wl_display.sync request immediately after calling
133 wl_display.get_registry.
134
135 A client can bind to a global object by using the bind
136 request. This creates a client-side handle that lets the object
137 emit events to the client and lets the client invoke requests on
138 the object.
139 </description>
140
141 <request name="bind">
142 <description summary="bind an object to the display">
143 Binds a new, client-created object to the server using the
144 specified name as the identifier.
145 </description>
146 <arg name="name" type="uint" summary="unique numeric name of the object"/>
147 <arg name="id" type="new_id" summary="bound object"/>
148 </request>
149
150 <event name="global">
151 <description summary="announce global object">
152 Notify the client of global objects.
153
154 The event notifies the client that a global object with
155 the given name is now available, and it implements the
156 given version of the given interface.
157 </description>
158 <arg name="name" type="uint" summary="numeric name of the global object"/>
159 <arg name="interface" type="string" summary="interface implemented by the object"/>
160 <arg name="version" type="uint" summary="interface version"/>
161 </event>
162
163 <event name="global_remove">
164 <description summary="announce removal of global object">
165 Notify the client of removed global objects.
166
167 This event notifies the client that the global identified
168 by name is no longer available. If the client bound to
169 the global using the bind request, the client should now
170 destroy that object.
171
172 The object remains valid and requests to the object will be
173 ignored until the client destroys it, to avoid races between
174 the global going away and a client sending a request to it.
175 </description>
176 <arg name="name" type="uint" summary="numeric name of the global object"/>
177 </event>
178 </interface>
179
180 <interface name="wl_callback" version="1" frozen="true">
181 <description summary="callback object">
182 Clients can handle the 'done' event to get notified when
183 the related request is done.
184
185 Note, because wl_callback objects are created from multiple independent
186 factory interfaces, the wl_callback interface is frozen at version 1.
187 </description>
188
189 <event name="done" type="destructor">
190 <description summary="done event">
191 Notify the client when the related request is done.
192 </description>
193 <arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
194 </event>
195 </interface>
196
197 <interface name="wl_compositor" version="7">
198 <description summary="the compositor singleton">
199 A compositor. This object is a singleton global. The
200 compositor is in charge of combining the contents of multiple
201 surfaces into one displayable output.
202 </description>
203
204 <request name="create_surface">
205 <description summary="create new surface">
206 Ask the compositor to create a new surface.
207 </description>
208 <arg name="id" type="new_id" interface="wl_surface" summary="the new surface"/>
209 </request>
210
211 <request name="create_region">
212 <description summary="create new region">
213 Ask the compositor to create a new region.
214 </description>
215 <arg name="id" type="new_id" interface="wl_region" summary="the new region"/>
216 </request>
217
218 <!-- Version 7 additions -->
219
220 <request name="release" type="destructor" since="7">
221 <description summary="destroy wl_compositor">
222 This request destroys the wl_compositor. This has no effect on any other objects.
223 </description>
224 </request>
225 </interface>
226
227 <interface name="wl_shm_pool" version="3">
228 <description summary="a shared memory pool">
229 The wl_shm_pool object encapsulates a piece of memory shared
230 between the compositor and client. Through the wl_shm_pool
231 object, the client can allocate shared memory wl_buffer objects.
232 All objects created through the same pool share the same
233 underlying mapped memory. Reusing the mapped memory avoids the
234 setup/teardown overhead and is useful when interactively resizing
235 a surface or for many small buffers.
236 </description>
237
238 <enum name="error" since="3">
239 <description summary="wl_shm_pool error values">
240 These errors can be emitted in response to wl_shm_pool requests.
241 </description>
242 <entry name="invalid_format" value="0" summary="buffer format is not known"/>
243 <entry name="invalid_stride" value="1" summary="invalid size or stride during buffer creation"/>
244 </enum>
245
246 <request name="create_buffer">
247 <description summary="create a buffer from the pool">
248 Create a wl_buffer object from the pool.
249
250 The buffer is created offset bytes into the pool and has
251 width and height as specified. The stride argument specifies
252 the number of bytes from the beginning of one row to the beginning
253 of the next. The format is the pixel format of the buffer and
254 must be one of those advertised through the wl_shm.format event.
255
256 A buffer will keep a reference to the pool it was created from
257 so it is valid to destroy the pool immediately after creating
258 a buffer from it.
259 </description>
260 <arg name="id" type="new_id" interface="wl_buffer" summary="buffer to create"/>
261 <arg name="offset" type="int" summary="buffer byte offset within the pool"/>
262 <arg name="width" type="int" summary="buffer width, in pixels"/>
263 <arg name="height" type="int" summary="buffer height, in pixels"/>
264 <arg name="stride" type="int" summary="number of bytes from the beginning of one row to the beginning of the next row"/>
265 <arg name="format" type="uint" enum="wl_shm.format" summary="buffer pixel format"/>
266 </request>
267
268 <request name="destroy" type="destructor">
269 <description summary="destroy the pool">
270 Destroy the shared memory pool.
271
272 The mmapped memory will be released when all
273 buffers that have been created from this pool
274 are gone.
275 </description>
276 </request>
277
278 <request name="resize">
279 <description summary="change the size of the pool mapping">
280 This request will cause the server to remap the backing memory
281 for the pool from the file descriptor passed when the pool was
282 created, but using the new size. This request can only be
283 used to make the pool bigger.
284
285 This request only changes the amount of bytes that are mmapped
286 by the server and does not touch the file corresponding to the
287 file descriptor passed at creation time. It is the client's
288 responsibility to ensure that the file is at least as big as
289 the new pool size.
290 </description>
291 <arg name="size" type="int" summary="new size of the pool, in bytes"/>
292 </request>
293 </interface>
294
295 <interface name="wl_shm" version="3">
296 <description summary="shared memory support">
297 A singleton global object that provides support for shared
298 memory.
299
300 Clients can create wl_shm_pool objects using the create_pool
301 request.
302
303 On binding the wl_shm object one or more format events
304 are emitted to inform clients about the valid pixel formats
305 that can be used for buffers.
306 </description>
307
308 <enum name="error" since="3">
309 <description summary="wl_shm error values">
310 These errors can be emitted in response to wl_shm requests.
311 </description>
312 <entry name="invalid_format" value="0" summary="buffer format is not known" deprecated-since="3"/>
313 <entry name="invalid_stride" value="1" summary="invalid size or stride during pool creation"/>
314 <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
315 </enum>
316
317 <enum name="format">
318 <description summary="pixel formats">
319 This describes the memory layout of an individual pixel.
320
321 All renderers should support argb8888 and xrgb8888 but any other
322 formats are optional and may not be supported by the particular
323 renderer in use.
324
325 The drm format codes match the macros defined in drm_fourcc.h, except
326 argb8888 and xrgb8888. The formats actually supported by the compositor
327 will be reported by the format event. See drm_fourcc.h for more detailed
328 format descriptions.
329
330 For all wl_shm formats and unless specified in another protocol
331 extension, pre-multiplied alpha is used for pixel values.
332 </description>
333 <!-- Note to protocol writers: don't update this list manually, instead
334 run the automated script that keeps it in sync with drm_fourcc.h. -->
335 <entry name="argb8888" value="0" summary="32-bit ARGB format, [31:0] A:R:G:B 8:8:8:8 little endian"/>
336 <entry name="xrgb8888" value="1" summary="32-bit RGB format, [31:0] x:R:G:B 8:8:8:8 little endian"/>
337 <entry name="c8" value="0x20203843" summary="8-bit color index format, [7:0] C"/>
338 <entry name="rgb332" value="0x38424752" summary="8-bit RGB format, [7:0] R:G:B 3:3:2"/>
339 <entry name="bgr233" value="0x38524742" summary="8-bit BGR format, [7:0] B:G:R 2:3:3"/>
340 <entry name="xrgb4444" value="0x32315258" summary="16-bit xRGB format, [15:0] x:R:G:B 4:4:4:4 little endian"/>
341 <entry name="xbgr4444" value="0x32314258" summary="16-bit xBGR format, [15:0] x:B:G:R 4:4:4:4 little endian"/>
342 <entry name="rgbx4444" value="0x32315852" summary="16-bit RGBx format, [15:0] R:G:B:x 4:4:4:4 little endian"/>
343 <entry name="bgrx4444" value="0x32315842" summary="16-bit BGRx format, [15:0] B:G:R:x 4:4:4:4 little endian"/>
344 <entry name="argb4444" value="0x32315241" summary="16-bit ARGB format, [15:0] A:R:G:B 4:4:4:4 little endian"/>
345 <entry name="abgr4444" value="0x32314241" summary="16-bit ABGR format, [15:0] A:B:G:R 4:4:4:4 little endian"/>
346 <entry name="rgba4444" value="0x32314152" summary="16-bit RGBA format, [15:0] R:G:B:A 4:4:4:4 little endian"/>
347 <entry name="bgra4444" value="0x32314142" summary="16-bit BGRA format, [15:0] B:G:R:A 4:4:4:4 little endian"/>
348 <entry name="xrgb1555" value="0x35315258" summary="16-bit xRGB format, [15:0] x:R:G:B 1:5:5:5 little endian"/>
349 <entry name="xbgr1555" value="0x35314258" summary="16-bit xBGR 1555 format, [15:0] x:B:G:R 1:5:5:5 little endian"/>
350 <entry name="rgbx5551" value="0x35315852" summary="16-bit RGBx 5551 format, [15:0] R:G:B:x 5:5:5:1 little endian"/>
351 <entry name="bgrx5551" value="0x35315842" summary="16-bit BGRx 5551 format, [15:0] B:G:R:x 5:5:5:1 little endian"/>
352 <entry name="argb1555" value="0x35315241" summary="16-bit ARGB 1555 format, [15:0] A:R:G:B 1:5:5:5 little endian"/>
353 <entry name="abgr1555" value="0x35314241" summary="16-bit ABGR 1555 format, [15:0] A:B:G:R 1:5:5:5 little endian"/>
354 <entry name="rgba5551" value="0x35314152" summary="16-bit RGBA 5551 format, [15:0] R:G:B:A 5:5:5:1 little endian"/>
355 <entry name="bgra5551" value="0x35314142" summary="16-bit BGRA 5551 format, [15:0] B:G:R:A 5:5:5:1 little endian"/>
356 <entry name="rgb565" value="0x36314752" summary="16-bit RGB 565 format, [15:0] R:G:B 5:6:5 little endian"/>
357 <entry name="bgr565" value="0x36314742" summary="16-bit BGR 565 format, [15:0] B:G:R 5:6:5 little endian"/>
358 <entry name="rgb888" value="0x34324752" summary="24-bit RGB format, [23:0] R:G:B little endian"/>
359 <entry name="bgr888" value="0x34324742" summary="24-bit BGR format, [23:0] B:G:R little endian"/>
360 <entry name="xbgr8888" value="0x34324258" summary="32-bit xBGR format, [31:0] x:B:G:R 8:8:8:8 little endian"/>
361 <entry name="rgbx8888" value="0x34325852" summary="32-bit RGBx format, [31:0] R:G:B:x 8:8:8:8 little endian"/>
362 <entry name="bgrx8888" value="0x34325842" summary="32-bit BGRx format, [31:0] B:G:R:x 8:8:8:8 little endian"/>
363 <entry name="abgr8888" value="0x34324241" summary="32-bit ABGR format, [31:0] A:B:G:R 8:8:8:8 little endian"/>
364 <entry name="rgba8888" value="0x34324152" summary="32-bit RGBA format, [31:0] R:G:B:A 8:8:8:8 little endian"/>
365 <entry name="bgra8888" value="0x34324142" summary="32-bit BGRA format, [31:0] B:G:R:A 8:8:8:8 little endian"/>
366 <entry name="xrgb2101010" value="0x30335258" summary="32-bit xRGB format, [31:0] x:R:G:B 2:10:10:10 little endian"/>
367 <entry name="xbgr2101010" value="0x30334258" summary="32-bit xBGR format, [31:0] x:B:G:R 2:10:10:10 little endian"/>
368 <entry name="rgbx1010102" value="0x30335852" summary="32-bit RGBx format, [31:0] R:G:B:x 10:10:10:2 little endian"/>
369 <entry name="bgrx1010102" value="0x30335842" summary="32-bit BGRx format, [31:0] B:G:R:x 10:10:10:2 little endian"/>
370 <entry name="argb2101010" value="0x30335241" summary="32-bit ARGB format, [31:0] A:R:G:B 2:10:10:10 little endian"/>
371 <entry name="abgr2101010" value="0x30334241" summary="32-bit ABGR format, [31:0] A:B:G:R 2:10:10:10 little endian"/>
372 <entry name="rgba1010102" value="0x30334152" summary="32-bit RGBA format, [31:0] R:G:B:A 10:10:10:2 little endian"/>
373 <entry name="bgra1010102" value="0x30334142" summary="32-bit BGRA format, [31:0] B:G:R:A 10:10:10:2 little endian"/>
374 <entry name="yuyv" value="0x56595559" summary="packed YCbCr format, [31:0] Cr0:Y1:Cb0:Y0 8:8:8:8 little endian"/>
375 <entry name="yvyu" value="0x55595659" summary="packed YCbCr format, [31:0] Cb0:Y1:Cr0:Y0 8:8:8:8 little endian"/>
376 <entry name="uyvy" value="0x59565955" summary="packed YCbCr format, [31:0] Y1:Cr0:Y0:Cb0 8:8:8:8 little endian"/>
377 <entry name="vyuy" value="0x59555956" summary="packed YCbCr format, [31:0] Y1:Cb0:Y0:Cr0 8:8:8:8 little endian"/>
378 <entry name="ayuv" value="0x56555941" summary="packed AYCbCr format, [31:0] A:Y:Cb:Cr 8:8:8:8 little endian"/>
379 <entry name="nv12" value="0x3231564e" summary="2 plane YCbCr Cr:Cb format, 2x2 subsampled Cr:Cb plane"/>
380 <entry name="nv21" value="0x3132564e" summary="2 plane YCbCr Cb:Cr format, 2x2 subsampled Cb:Cr plane"/>
381 <entry name="nv16" value="0x3631564e" summary="2 plane YCbCr Cr:Cb format, 2x1 subsampled Cr:Cb plane"/>
382 <entry name="nv61" value="0x3136564e" summary="2 plane YCbCr Cb:Cr format, 2x1 subsampled Cb:Cr plane"/>
383 <entry name="yuv410" value="0x39565559" summary="3 plane YCbCr format, 4x4 subsampled Cb (1) and Cr (2) planes"/>
384 <entry name="yvu410" value="0x39555659" summary="3 plane YCbCr format, 4x4 subsampled Cr (1) and Cb (2) planes"/>
385 <entry name="yuv411" value="0x31315559" summary="3 plane YCbCr format, 4x1 subsampled Cb (1) and Cr (2) planes"/>
386 <entry name="yvu411" value="0x31315659" summary="3 plane YCbCr format, 4x1 subsampled Cr (1) and Cb (2) planes"/>
387 <entry name="yuv420" value="0x32315559" summary="3 plane YCbCr format, 2x2 subsampled Cb (1) and Cr (2) planes"/>
388 <entry name="yvu420" value="0x32315659" summary="3 plane YCbCr format, 2x2 subsampled Cr (1) and Cb (2) planes"/>
389 <entry name="yuv422" value="0x36315559" summary="3 plane YCbCr format, 2x1 subsampled Cb (1) and Cr (2) planes"/>
390 <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr format, 2x1 subsampled Cr (1) and Cb (2) planes"/>
391 <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr format, non-subsampled Cb (1) and Cr (2) planes"/>
392 <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr format, non-subsampled Cr (1) and Cb (2) planes"/>
393 <entry name="r8" value="0x20203852" summary="[7:0] R"/>
394 <entry name="r16" value="0x20363152" summary="[15:0] R little endian"/>
395 <entry name="rg88" value="0x38384752" summary="[15:0] R:G 8:8 little endian"/>
396 <entry name="gr88" value="0x38385247" summary="[15:0] G:R 8:8 little endian"/>
397 <entry name="rg1616" value="0x32334752" summary="[31:0] R:G 16:16 little endian"/>
398 <entry name="gr1616" value="0x32335247" summary="[31:0] G:R 16:16 little endian"/>
399 <entry name="xrgb16161616f" value="0x48345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
400 <entry name="xbgr16161616f" value="0x48344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
401 <entry name="argb16161616f" value="0x48345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
402 <entry name="abgr16161616f" value="0x48344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
403 <entry name="xyuv8888" value="0x56555958" summary="[31:0] X:Y:Cb:Cr 8:8:8:8 little endian"/>
404 <entry name="vuy888" value="0x34325556" summary="[23:0] Cr:Cb:Y 8:8:8 little endian"/>
405 <entry name="vuy101010" value="0x30335556" summary="Y followed by U then V, 10:10:10. Non-linear modifier only"/>
406 <entry name="y210" value="0x30313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 10:6:10:6:10:6:10:6 little endian per 2 Y pixels"/>
407 <entry name="y212" value="0x32313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 12:4:12:4:12:4:12:4 little endian per 2 Y pixels"/>
408 <entry name="y216" value="0x36313259" summary="[63:0] Cr0:Y1:Cb0:Y0 16:16:16:16 little endian per 2 Y pixels"/>
409 <entry name="y410" value="0x30313459" summary="[31:0] A:Cr:Y:Cb 2:10:10:10 little endian"/>
410 <entry name="y412" value="0x32313459" summary="[63:0] A:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
411 <entry name="y416" value="0x36313459" summary="[63:0] A:Cr:Y:Cb 16:16:16:16 little endian"/>
412 <entry name="xvyu2101010" value="0x30335658" summary="[31:0] X:Cr:Y:Cb 2:10:10:10 little endian"/>
413 <entry name="xvyu12_16161616" value="0x36335658" summary="[63:0] X:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
414 <entry name="xvyu16161616" value="0x38345658" summary="[63:0] X:Cr:Y:Cb 16:16:16:16 little endian"/>
415 <entry name="y0l0" value="0x304c3059" summary="[63:0] A3:A2:Y3:0:Cr0:0:Y2:0:A1:A0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
416 <entry name="x0l0" value="0x304c3058" summary="[63:0] X3:X2:Y3:0:Cr0:0:Y2:0:X1:X0:Y1:0:Cb0:0:Y0:0 1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
417 <entry name="y0l2" value="0x324c3059" summary="[63:0] A3:A2:Y3:Cr0:Y2:A1:A0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
418 <entry name="x0l2" value="0x324c3058" summary="[63:0] X3:X2:Y3:Cr0:Y2:X1:X0:Y1:Cb0:Y0 1:1:10:10:10:1:1:10:10:10 little endian"/>
419 <entry name="yuv420_8bit" value="0x38305559"/>
420 <entry name="yuv420_10bit" value="0x30315559"/>
421 <entry name="xrgb8888_a8" value="0x38415258"/>
422 <entry name="xbgr8888_a8" value="0x38414258"/>
423 <entry name="rgbx8888_a8" value="0x38415852"/>
424 <entry name="bgrx8888_a8" value="0x38415842"/>
425 <entry name="rgb888_a8" value="0x38413852"/>
426 <entry name="bgr888_a8" value="0x38413842"/>
427 <entry name="rgb565_a8" value="0x38413552"/>
428 <entry name="bgr565_a8" value="0x38413542"/>
429 <entry name="nv24" value="0x3432564e" summary="non-subsampled Cr:Cb plane"/>
430 <entry name="nv42" value="0x3234564e" summary="non-subsampled Cb:Cr plane"/>
431 <entry name="p210" value="0x30313250" summary="2x1 subsampled Cr:Cb plane, 10 bit per channel"/>
432 <entry name="p010" value="0x30313050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel"/>
433 <entry name="p012" value="0x32313050" summary="2x2 subsampled Cr:Cb plane 12 bits per channel"/>
434 <entry name="p016" value="0x36313050" summary="2x2 subsampled Cr:Cb plane 16 bits per channel"/>
435 <entry name="axbxgxrx106106106106" value="0x30314241" summary="[63:0] A:x:B:x:G:x:R:x 10:6:10:6:10:6:10:6 little endian"/>
436 <entry name="nv15" value="0x3531564e" summary="2x2 subsampled Cr:Cb plane"/>
437 <entry name="q410" value="0x30313451"/>
438 <entry name="q401" value="0x31303451"/>
439 <entry name="xrgb16161616" value="0x38345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
440 <entry name="xbgr16161616" value="0x38344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
441 <entry name="argb16161616" value="0x38345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
442 <entry name="abgr16161616" value="0x38344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
443 <entry name="c1" value="0x20203143" summary="[7:0] C0:C1:C2:C3:C4:C5:C6:C7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
444 <entry name="c2" value="0x20203243" summary="[7:0] C0:C1:C2:C3 2:2:2:2 four pixels/byte"/>
445 <entry name="c4" value="0x20203443" summary="[7:0] C0:C1 4:4 two pixels/byte"/>
446 <entry name="d1" value="0x20203144" summary="[7:0] D0:D1:D2:D3:D4:D5:D6:D7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
447 <entry name="d2" value="0x20203244" summary="[7:0] D0:D1:D2:D3 2:2:2:2 four pixels/byte"/>
448 <entry name="d4" value="0x20203444" summary="[7:0] D0:D1 4:4 two pixels/byte"/>
449 <entry name="d8" value="0x20203844" summary="[7:0] D"/>
450 <entry name="r1" value="0x20203152" summary="[7:0] R0:R1:R2:R3:R4:R5:R6:R7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
451 <entry name="r2" value="0x20203252" summary="[7:0] R0:R1:R2:R3 2:2:2:2 four pixels/byte"/>
452 <entry name="r4" value="0x20203452" summary="[7:0] R0:R1 4:4 two pixels/byte"/>
453 <entry name="r10" value="0x20303152" summary="[15:0] x:R 6:10 little endian"/>
454 <entry name="r12" value="0x20323152" summary="[15:0] x:R 4:12 little endian"/>
455 <entry name="avuy8888" value="0x59555641" summary="[31:0] A:Cr:Cb:Y 8:8:8:8 little endian"/>
456 <entry name="xvuy8888" value="0x59555658" summary="[31:0] X:Cr:Cb:Y 8:8:8:8 little endian"/>
457 <entry name="p030" value="0x30333050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel packed"/>
458 <entry name="rgb161616" value="0x38344752" summary="[47:0] R:G:B 16:16:16 little endian"/>
459 <entry name="bgr161616" value="0x38344742" summary="[47:0] B:G:R 16:16:16 little endian"/>
460 <entry name="r16f" value="0x48202052" summary="[15:0] R 16 little endian"/>
461 <entry name="gr1616f" value="0x48205247" summary="[31:0] G:R 16:16 little endian"/>
462 <entry name="bgr161616f" value="0x48524742" summary="[47:0] B:G:R 16:16:16 little endian"/>
463 <entry name="r32f" value="0x46202052" summary="[31:0] R 32 little endian"/>
464 <entry name="gr3232f" value="0x46205247" summary="[63:0] G:R 32:32 little endian"/>
465 <entry name="bgr323232f" value="0x46524742" summary="[95:0] B:G:R 32:32:32 little endian"/>
466 <entry name="abgr32323232f" value="0x46384241" summary="[127:0] A:B:G:R 32:32:32:32 little endian"/>
467 <entry name="nv20" value="0x3032564e" summary="2x1 subsampled Cr:Cb plane"/>
468 <entry name="nv30" value="0x3033564e" summary="non-subsampled Cr:Cb plane"/>
469 <entry name="s010" value="0x30313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
470 <entry name="s210" value="0x30313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
471 <entry name="s410" value="0x30313453" summary="non-subsampled Cb (1) and Cr (2) planes 10 bits per channel"/>
472 <entry name="s012" value="0x32313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
473 <entry name="s212" value="0x32313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
474 <entry name="s412" value="0x32313453" summary="non-subsampled Cb (1) and Cr (2) planes 12 bits per channel"/>
475 <entry name="s016" value="0x36313053" summary="2x2 subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
476 <entry name="s216" value="0x36313253" summary="2x1 subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
477 <entry name="s416" value="0x36313453" summary="non-subsampled Cb (1) and Cr (2) planes 16 bits per channel"/>
478 <entry name="xvuy2101010" value="0x30335958" summary="[31:0] x:Cr:Cb:Y 2:10:10:10 little endian"/>
479 <entry name="p230" value="0x30333250" summary="2x1 subsampled Cr:Cb plane 10 bits per channel packed"/>
480 <entry name="t430" value="0x30333454"/>
481 <entry name="y8" value="0x59455247" summary="8-bit Y-only"/>
482 <entry name="xyyy2101010" value="0x34415059" summary="[31:0] x:Y2:Y1:Y0 2:10:10:10 little endian"/>
483 </enum>
484
485 <request name="create_pool">
486 <description summary="create a shm pool">
487 Create a new wl_shm_pool object.
488
489 The pool can be used to create shared memory based buffer
490 objects. The server will mmap size bytes of the passed file
491 descriptor, to use as backing memory for the pool.
492 </description>
493 <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
494 <arg name="fd" type="fd" summary="file descriptor for the pool"/>
495 <arg name="size" type="int" summary="pool size, in bytes"/>
496 </request>
497
498 <event name="format">
499 <description summary="pixel format description">
500 Informs the client about a valid pixel format that
501 can be used for buffers. Known formats include
502 argb8888 and xrgb8888.
503
504 Extensions to drm_fourcc.h (or the format enum) do not require
505 increasing the wl_shm version; as a result, clients may receive format
506 codes which were not in the list at the time the client was made.
507 </description>
508 <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
509 </event>
510
511 <!-- Version 2 additions -->
512
513 <request name="release" type="destructor" since="2">
514 <description summary="release the shm object">
515 Using this request a client can tell the server that it is not going to
516 use the shm object anymore.
517
518 Objects created via this interface remain unaffected.
519 </description>
520 </request>
521 </interface>
522
523 <interface name="wl_buffer" version="1" frozen="true">
524 <description summary="content for a wl_surface">
525 A buffer provides the content for a wl_surface. Buffers are
526 created through factory interfaces such as wl_shm, wp_linux_buffer_params
527 (from the linux-dmabuf protocol extension) or similar. It has a width and
528 a height and can be attached to a wl_surface, but the mechanism by which a
529 client provides and updates the contents is defined by the buffer factory
530 interface.
531
532 Color channels are assumed to be electrical rather than optical (in other
533 words, encoded with a transfer function) unless otherwise specified. If
534 the buffer uses a format that has an alpha channel, the alpha channel is
535 assumed to be premultiplied into the electrical color channel values
536 (after transfer function encoding) unless otherwise specified.
537
538 Note, because wl_buffer objects are created from multiple independent
539 factory interfaces, the wl_buffer interface is frozen at version 1.
540 </description>
541
542 <request name="destroy" type="destructor">
543 <description summary="destroy a buffer">
544 Destroy a buffer. If and how you need to release the backing
545 storage is defined by the buffer factory interface.
546
547 For possible side-effects to a surface, see wl_surface.attach.
548 </description>
549 </request>
550
551 <event name="release">
552 <description summary="compositor releases buffer">
553 Sent when this wl_buffer is no longer used by the compositor.
554
555 For more information on when release events may or may not be sent,
556 and what consequences it has, please see the description of
557 wl_surface.attach.
558
559 If a client receives a release event before the frame callback
560 requested in the same wl_surface.commit that attaches this
561 wl_buffer to a surface, then the client is immediately free to
562 reuse the buffer and its backing storage, and does not need a
563 second buffer for the next surface content update. Typically
564 this is possible, when the compositor maintains a copy of the
565 wl_surface contents, e.g. as a GL texture. This is an important
566 optimization for GL(ES) compositors with wl_shm clients.
567 </description>
568 </event>
569 </interface>
570
571 <interface name="wl_data_offer" version="4">
572 <description summary="offer to transfer data">
573 A wl_data_offer represents a piece of data offered for transfer
574 by another client (the source client). It is used by the
575 copy-and-paste and drag-and-drop mechanisms. The offer
576 describes the different mime types that the data can be
577 converted to and provides the mechanism for transferring the
578 data directly from the source client.
579 </description>
580
581 <enum name="error">
582 <entry name="invalid_finish" value="0"
583 summary="finish request was called untimely"/>
584 <entry name="invalid_action_mask" value="1"
585 summary="action mask contains invalid values"/>
586 <entry name="invalid_action" value="2"
587 summary="action argument has an invalid value"/>
588 <entry name="invalid_offer" value="3"
589 summary="offer doesn't accept this request"/>
590 </enum>
591
592 <request name="accept">
593 <description summary="accept one of the offered mime types">
594 Indicate that the client can accept the given mime type, or
595 NULL for not accepted.
596
597 For objects of version 2 or older, this request is used by the
598 client to give feedback whether the client can receive the given
599 mime type, or NULL if none is accepted; the feedback does not
600 determine whether the drag-and-drop operation succeeds or not.
601
602 For objects of version 3 or newer, this request determines the
603 final result of the drag-and-drop operation. If the end result
604 is that no mime types were accepted, the drag-and-drop operation
605 will be cancelled and the corresponding drag source will receive
606 wl_data_source.cancelled. Clients may still use this event in
607 conjunction with wl_data_source.action for feedback.
608 </description>
609 <arg name="serial" type="uint" summary="serial number of the accept request"/>
610 <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the client"/>
611 </request>
612
613 <request name="receive">
614 <description summary="request that the data is transferred">
615 To transfer the offered data, the client issues this request
616 and indicates the mime type it wants to receive. The transfer
617 happens through the passed file descriptor (typically created
618 with the pipe system call). The source client writes the data
619 in the mime type representation requested and then closes the
620 file descriptor.
621
622 The receiving client reads from the read end of the pipe until
623 EOF and then closes its end, at which point the transfer is
624 complete.
625
626 This request may happen multiple times for different mime types,
627 both before and after wl_data_device.drop. Drag-and-drop destination
628 clients may preemptively fetch data or examine it more closely to
629 determine acceptance.
630 </description>
631 <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
632 <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
633 </request>
634
635 <request name="destroy" type="destructor">
636 <description summary="destroy data offer">
637 Destroy the data offer.
638 </description>
639 </request>
640
641 <event name="offer">
642 <description summary="advertise offered mime type">
643 Sent immediately after creating the wl_data_offer object. One
644 event per offered mime type.
645 </description>
646 <arg name="mime_type" type="string" summary="offered mime type"/>
647 </event>
648
649 <!-- Version 3 additions -->
650
651 <request name="finish" since="3">
652 <description summary="the offer will no longer be used">
653 Notifies the compositor that the drag destination successfully
654 finished the drag-and-drop operation.
655
656 Upon receiving this request, the compositor will emit
657 wl_data_source.dnd_finished on the drag source client.
658
659 It is a client error to perform other requests than
660 wl_data_offer.destroy after this one. It is also an error to perform
661 this request after a NULL mime type has been set in
662 wl_data_offer.accept or no action was received through
663 wl_data_offer.action.
664
665 If wl_data_offer.finish request is received for a non drag and drop
666 operation, the invalid_finish protocol error is raised.
667 </description>
668 </request>
669
670 <request name="set_actions" since="3">
671 <description summary="set the available/preferred drag-and-drop actions">
672 Sets the actions that the destination side client supports for
673 this operation. This request may trigger the emission of
674 wl_data_source.action and wl_data_offer.action events if the compositor
675 needs to change the selected action.
676
677 This request can be called multiple times throughout the
678 drag-and-drop operation, typically in response to wl_data_device.enter
679 or wl_data_device.motion events.
680
681 This request determines the final result of the drag-and-drop
682 operation. If the end result is that no action is accepted,
683 the drag source will receive wl_data_source.cancelled.
684
685 The dnd_actions argument must contain only values expressed in the
686 wl_data_device_manager.dnd_actions enum, and the preferred_action
687 argument must only contain one of those values set, otherwise it
688 will result in a protocol error.
689
690 While managing an "ask" action, the destination drag-and-drop client
691 may perform further wl_data_offer.receive requests, and is expected
692 to perform one last wl_data_offer.set_actions request with a preferred
693 action other than "ask" (and optionally wl_data_offer.accept) before
694 requesting wl_data_offer.finish, in order to convey the action selected
695 by the user. If the preferred action is not in the
696 wl_data_offer.source_actions mask, an error will be raised.
697
698 If the "ask" action is dismissed (e.g. user cancellation), the client
699 is expected to perform wl_data_offer.destroy right away.
700
701 This request can only be made on drag-and-drop offers, a protocol error
702 will be raised otherwise.
703 </description>
704 <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
705 enum="wl_data_device_manager.dnd_action"/>
706 <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
707 enum="wl_data_device_manager.dnd_action"/>
708 </request>
709
710 <event name="source_actions" since="3">
711 <description summary="notify the source-side available actions">
712 This event indicates the actions offered by the data source. It
713 will be sent immediately after creating the wl_data_offer object,
714 or anytime the source side changes its offered actions through
715 wl_data_source.set_actions.
716 </description>
717 <arg name="source_actions" type="uint" summary="actions offered by the data source"
718 enum="wl_data_device_manager.dnd_action"/>
719 </event>
720
721 <event name="action" since="3">
722 <description summary="notify the selected action">
723 This event indicates the action selected by the compositor after
724 matching the source/destination side actions. Only one action (or
725 none) will be offered here.
726
727 This event can be emitted multiple times during the drag-and-drop
728 operation in response to destination side action changes through
729 wl_data_offer.set_actions.
730
731 This event will no longer be emitted after wl_data_device.drop
732 happened on the drag-and-drop destination, the client must
733 honor the last action received, or the last preferred one set
734 through wl_data_offer.set_actions when handling an "ask" action.
735
736 Compositors may also change the selected action on the fly, mainly
737 in response to keyboard modifier changes during the drag-and-drop
738 operation.
739
740 The most recent action received is always the valid one. Prior to
741 receiving wl_data_device.drop, the chosen action may change (e.g.
742 due to keyboard modifiers being pressed). At the time of receiving
743 wl_data_device.drop the drag-and-drop destination must honor the
744 last action received.
745
746 Action changes may still happen after wl_data_device.drop,
747 especially on "ask" actions, where the drag-and-drop destination
748 may choose another action afterwards. Action changes happening
749 at this stage are always the result of inter-client negotiation, the
750 compositor shall no longer be able to induce a different action.
751
752 Upon "ask" actions, it is expected that the drag-and-drop destination
753 may potentially choose a different action and/or mime type,
754 based on wl_data_offer.source_actions and finally chosen by the
755 user (e.g. popping up a menu with the available options). The
756 final wl_data_offer.set_actions and wl_data_offer.accept requests
757 must happen before the call to wl_data_offer.finish.
758 </description>
759 <arg name="dnd_action" type="uint" summary="action selected by the compositor"
760 enum="wl_data_device_manager.dnd_action"/>
761 </event>
762 </interface>
763
764 <interface name="wl_data_source" version="4">
765 <description summary="offer to transfer data">
766 The wl_data_source object is the source side of a wl_data_offer.
767 It is created by the source client in a data transfer and
768 provides a way to describe the offered data and a way to respond
769 to requests to transfer the data.
770 </description>
771
772 <enum name="error">
773 <entry name="invalid_action_mask" value="0"
774 summary="action mask contains invalid values"/>
775 <entry name="invalid_source" value="1"
776 summary="source doesn't accept this request"/>
777 </enum>
778
779 <request name="offer">
780 <description summary="add an offered mime type">
781 This request adds a mime type to the set of mime types
782 advertised to targets. Can be called several times to offer
783 multiple types.
784 </description>
785 <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
786 </request>
787
788 <request name="destroy" type="destructor">
789 <description summary="destroy the data source">
790 Destroy the data source.
791 </description>
792 </request>
793
794 <event name="target">
795 <description summary="a target accepts an offered mime type">
796 Sent when a target accepts pointer_focus or motion events. If
797 a target does not accept any of the offered types, type is NULL.
798
799 Used for feedback during drag-and-drop.
800 </description>
801 <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
802 </event>
803
804 <event name="send">
805 <description summary="send the data">
806 Request for data from the client. Send the data as the
807 specified mime type over the passed file descriptor, then
808 close it.
809 </description>
810 <arg name="mime_type" type="string" summary="mime type for the data"/>
811 <arg name="fd" type="fd" summary="file descriptor for the data"/>
812 </event>
813
814 <event name="cancelled">
815 <description summary="selection was cancelled">
816 This data source is no longer valid. There are several reasons why
817 this could happen:
818
819 - The data source has been replaced by another data source.
820 - The drag-and-drop operation was performed, but the drop destination
821 did not accept any of the mime types offered through
822 wl_data_source.target.
823 - The drag-and-drop operation was performed, but the drop destination
824 did not select any of the actions present in the mask offered through
825 wl_data_source.action.
826 - The drag-and-drop operation was performed but didn't happen over a
827 surface.
828 - The compositor cancelled the drag-and-drop operation (e.g. compositor
829 dependent timeouts to avoid stale drag-and-drop transfers).
830
831 The client should clean up and destroy this data source.
832
833 For objects of version 2 or older, wl_data_source.cancelled will
834 only be emitted if the data source was replaced by another data
835 source.
836 </description>
837 </event>
838
839 <!-- Version 3 additions -->
840
841 <request name="set_actions" since="3">
842 <description summary="set the available drag-and-drop actions">
843 Sets the actions that the source side client supports for this
844 operation. This request may trigger wl_data_source.action and
845 wl_data_offer.action events if the compositor needs to change the
846 selected action.
847
848 The dnd_actions argument must contain only values expressed in the
849 wl_data_device_manager.dnd_actions enum, otherwise it will result
850 in a protocol error.
851
852 This request must be made once only, and can only be made on sources
853 used in drag-and-drop, so it must be performed before
854 wl_data_device.start_drag. Attempting to use the source other than
855 for drag-and-drop will raise a protocol error.
856 </description>
857 <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
858 enum="wl_data_device_manager.dnd_action"/>
859 </request>
860
861 <event name="dnd_drop_performed" since="3">
862 <description summary="the drag-and-drop operation physically finished">
863 The user performed the drop action. This event does not indicate
864 acceptance, wl_data_source.cancelled may still be emitted afterwards
865 if the drop destination does not accept any mime type.
866
867 However, this event might not be received if the compositor cancelled
868 the drag-and-drop operation before this event could happen.
869
870 Note that the data_source may still be used in the future and should
871 not be destroyed here.
872 </description>
873 </event>
874
875 <event name="dnd_finished" since="3">
876 <description summary="the drag-and-drop operation concluded">
877 The drop destination finished interoperating with this data
878 source, so the client is now free to destroy this data source and
879 free all associated data.
880
881 If the action used to perform the operation was "move", the
882 source can now delete the transferred data.
883 </description>
884 </event>
885
886 <event name="action" since="3">
887 <description summary="notify the selected action">
888 This event indicates the action selected by the compositor after
889 matching the source/destination side actions. Only one action (or
890 none) will be offered here.
891
892 This event can be emitted multiple times during the drag-and-drop
893 operation, mainly in response to destination side changes through
894 wl_data_offer.set_actions, and as the data device enters/leaves
895 surfaces.
896
897 It is only possible to receive this event after
898 wl_data_source.dnd_drop_performed if the drag-and-drop operation
899 ended in an "ask" action, in which case the final wl_data_source.action
900 event will happen immediately before wl_data_source.dnd_finished.
901
902 Compositors may also change the selected action on the fly, mainly
903 in response to keyboard modifier changes during the drag-and-drop
904 operation.
905
906 The most recent action received is always the valid one. The chosen
907 action may change alongside negotiation (e.g. an "ask" action can turn
908 into a "move" operation), so the effects of the final action must
909 always be applied in wl_data_source.dnd_finished.
910
911 Clients can trigger cursor surface changes from this point, so
912 they reflect the current action.
913 </description>
914 <arg name="dnd_action" type="uint" summary="action selected by the compositor"
915 enum="wl_data_device_manager.dnd_action"/>
916 </event>
917 </interface>
918
919 <interface name="wl_data_device" version="4">
920 <description summary="data transfer device">
921 There is one wl_data_device per seat which can be obtained
922 from the global wl_data_device_manager singleton.
923
924 A wl_data_device provides access to inter-client data transfer
925 mechanisms such as copy-and-paste and drag-and-drop.
926 </description>
927
928 <enum name="error">
929 <entry name="role" value="0" summary="given wl_surface has another role"/>
930 <entry name="used_source" value="1" summary="source has already been used"/>
931 </enum>
932
933 <request name="start_drag">
934 <description summary="start drag-and-drop operation">
935 This request asks the compositor to start a drag-and-drop
936 operation on behalf of the client.
937
938 The source argument is the data source that provides the data
939 for the eventual data transfer. If source is NULL, enter, leave
940 and motion events are sent only to the client that initiated the
941 drag and the client is expected to handle the data passing
942 internally. If source is destroyed, the drag-and-drop session will be
943 cancelled.
944
945 The origin surface is the surface where the drag originates and
946 the client must have an active implicit grab that matches the
947 serial.
948
949 The icon surface is an optional (can be NULL) surface that
950 provides an icon to be moved around with the cursor. Initially,
951 the top-left corner of the icon surface is placed at the cursor
952 hotspot, but subsequent wl_surface.offset requests can move the
953 relative position. Attach requests must be confirmed with
954 wl_surface.commit as usual. The icon surface is given the role of
955 a drag-and-drop icon. If the icon surface already has another role,
956 it raises a protocol error.
957
958 The input region is ignored for wl_surfaces with the role of a
959 drag-and-drop icon.
960
961 The given source may not be used in any further set_selection or
962 start_drag requests. Attempting to reuse a previously-used source
963 may send a used_source error.
964 </description>
965 <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
966 <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
967 <arg name="icon" type="object" interface="wl_surface" allow-null="true" summary="drag-and-drop icon surface"/>
968 <arg name="serial" type="uint" summary="serial number of the implicit grab on the origin"/>
969 </request>
970
971 <request name="set_selection">
972 <description summary="copy data to the selection">
973 This request asks the compositor to set the selection
974 to the data from the source on behalf of the client.
975
976 To unset the selection, set the source to NULL.
977
978 The given source may not be used in any further set_selection or
979 start_drag requests. Attempting to reuse a previously-used source
980 may send a used_source error.
981 </description>
982 <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
983 <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
984 </request>
985
986 <event name="data_offer">
987 <description summary="introduce a new wl_data_offer">
988 The data_offer event introduces a new wl_data_offer object,
989 which will subsequently be used in either the
990 data_device.enter event (for drag-and-drop) or the
991 data_device.selection event (for selections). Immediately
992 following the data_device.data_offer event, the new data_offer
993 object will send out data_offer.offer events to describe the
994 mime types it offers.
995 </description>
996 <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
997 </event>
998
999 <event name="enter">
1000 <description summary="initiate drag-and-drop session">
1001 This event is sent when an active drag-and-drop pointer enters
1002 a surface owned by the client. The position of the pointer at
1003 enter time is provided by the x and y arguments, in surface-local
1004 coordinates.
1005 </description>
1006 <arg name="serial" type="uint" summary="serial number of the enter event"/>
1007 <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
1008 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
1009 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
1010 <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
1011 summary="source data_offer object"/>
1012 </event>
1013
1014 <event name="leave">
1015 <description summary="end drag-and-drop session">
1016 This event is sent when the drag-and-drop pointer leaves the
1017 surface and the session ends. The client must destroy the
1018 wl_data_offer introduced at enter time at this point.
1019 </description>
1020 </event>
1021
1022 <event name="motion">
1023 <description summary="drag-and-drop session motion">
1024 This event is sent when the drag-and-drop pointer moves within
1025 the currently focused surface. The new position of the pointer
1026 is provided by the x and y arguments, in surface-local
1027 coordinates.
1028 </description>
1029 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
1030 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
1031 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
1032 </event>
1033
1034 <event name="drop">
1035 <description summary="end drag-and-drop session successfully">
1036 The event is sent when a drag-and-drop operation is ended
1037 because the implicit grab is removed.
1038
1039 The drag-and-drop destination is expected to honor the last action
1040 received through wl_data_offer.action, if the resulting action is
1041 "copy" or "move", the destination can still perform
1042 wl_data_offer.receive requests, and is expected to end all
1043 transfers with a wl_data_offer.finish request.
1044
1045 If the resulting action is "ask", the action will not be considered
1046 final. The drag-and-drop destination is expected to perform one last
1047 wl_data_offer.set_actions request, or wl_data_offer.destroy in order
1048 to cancel the operation.
1049 </description>
1050 </event>
1051
1052 <event name="selection">
1053 <description summary="advertise new selection">
1054 The selection event is sent out to notify the client of a new
1055 wl_data_offer for the selection for this device. The
1056 data_device.data_offer and the data_offer.offer events are
1057 sent out immediately before this event to introduce the data
1058 offer object. The selection event is sent to a client
1059 immediately before receiving keyboard focus and when a new
1060 selection is set while the client has keyboard focus. The
1061 data_offer is valid until a new data_offer or NULL is received
1062 or until the client loses keyboard focus. Switching surface with
1063 keyboard focus within the same client doesn't mean a new selection
1064 will be sent. The client must destroy the previous selection
1065 data_offer, if any, upon receiving this event.
1066 </description>
1067 <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
1068 summary="selection data_offer object"/>
1069 </event>
1070
1071 <!-- Version 2 additions -->
1072
1073 <request name="release" type="destructor" since="2">
1074 <description summary="destroy data device">
1075 This request destroys the data device.
1076 </description>
1077 </request>
1078 </interface>
1079
1080 <interface name="wl_data_device_manager" version="4">
1081 <description summary="data transfer interface">
1082 The wl_data_device_manager is a singleton global object that
1083 provides access to inter-client data transfer mechanisms such as
1084 copy-and-paste and drag-and-drop. These mechanisms are tied to
1085 a wl_seat and this interface lets a client get a wl_data_device
1086 corresponding to a wl_seat.
1087
1088 Depending on the version bound, the objects created from the bound
1089 wl_data_device_manager object will have different requirements for
1090 functioning properly. See wl_data_source.set_actions,
1091 wl_data_offer.accept and wl_data_offer.finish for details.
1092 </description>
1093
1094 <request name="create_data_source">
1095 <description summary="create a new data source">
1096 Create a new data source.
1097 </description>
1098 <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
1099 </request>
1100
1101 <request name="get_data_device">
1102 <description summary="create a new data device">
1103 Create a new data device for a given seat.
1104 </description>
1105 <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
1106 <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
1107 </request>
1108
1109 <!-- Version 3 additions -->
1110
1111 <enum name="dnd_action" bitfield="true" since="3">
1112 <description summary="drag and drop actions">
1113 This is a bitmask of the available/preferred actions in a
1114 drag-and-drop operation.
1115
1116 In the compositor, the selected action is a result of matching the
1117 actions offered by the source and destination sides. "action" events
1118 with a "none" action will be sent to both source and destination if
1119 there is no match. All further checks will effectively happen on
1120 (source actions ∩ destination actions).
1121
1122 In addition, compositors may also pick different actions in
1123 reaction to key modifiers being pressed. One common design that
1124 is used in major toolkits (and the behavior recommended for
1125 compositors) is:
1126
1127 - If no modifiers are pressed, the first match (in bit order)
1128 will be used.
1129 - Pressing Shift selects "move", if enabled in the mask.
1130 - Pressing Control selects "copy", if enabled in the mask.
1131
1132 Behavior beyond that is considered implementation-dependent.
1133 Compositors may for example bind other modifiers (like Alt/Meta)
1134 or drags initiated with other buttons than BTN_LEFT to specific
1135 actions (e.g. "ask").
1136 </description>
1137 <entry name="none" value="0" summary="no action"/>
1138 <entry name="copy" value="1" summary="copy action"/>
1139 <entry name="move" value="2" summary="move action"/>
1140 <entry name="ask" value="4" summary="ask action"/>
1141 </enum>
1142
1143 <!-- Version 4 additions -->
1144
1145 <request name="release" type="destructor" since="4">
1146 <description summary="destroy wl_data_device_manager">
1147 This request destroys the wl_data_device_manager. This has no effect on any other
1148 objects.
1149 </description>
1150 </request>
1151 </interface>
1152
1153 <interface name="wl_shell" version="1">
1154 <description summary="create desktop-style surfaces">
1155 This interface is implemented by servers that provide
1156 desktop-style user interfaces.
1157
1158 It allows clients to associate a wl_shell_surface with
1159 a basic surface.
1160
1161 Note! This protocol is deprecated and not intended for production use.
1162 For desktop-style user interfaces, use xdg_shell. Compositors and clients
1163 should not implement this interface.
1164 </description>
1165
1166 <enum name="error">
1167 <entry name="role" value="0" summary="given wl_surface has another role"/>
1168 </enum>
1169
1170 <request name="get_shell_surface">
1171 <description summary="create a shell surface from a surface">
1172 Create a shell surface for an existing surface. This gives
1173 the wl_surface the role of a shell surface. If the wl_surface
1174 already has another role, it raises a protocol error.
1175
1176 Only one shell surface can be associated with a given surface.
1177 </description>
1178 <arg name="id" type="new_id" interface="wl_shell_surface" summary="shell surface to create"/>
1179 <arg name="surface" type="object" interface="wl_surface" summary="surface to be given the shell surface role"/>
1180 </request>
1181 </interface>
1182
1183 <interface name="wl_shell_surface" version="1">
1184 <description summary="desktop-style metadata interface">
1185 An interface that may be implemented by a wl_surface, for
1186 implementations that provide a desktop-style user interface.
1187
1188 It provides requests to treat surfaces like toplevel, fullscreen
1189 or popup windows, move, resize or maximize them, associate
1190 metadata like title and class, etc.
1191
1192 On the server side the object is automatically destroyed when
1193 the related wl_surface is destroyed. On the client side,
1194 wl_shell_surface_destroy() must be called before destroying
1195 the wl_surface object.
1196 </description>
1197
1198 <request name="pong">
1199 <description summary="respond to a ping event">
1200 A client must respond to a ping event with a pong request or
1201 the client may be deemed unresponsive.
1202 </description>
1203 <arg name="serial" type="uint" summary="serial number of the ping event"/>
1204 </request>
1205
1206 <request name="move">
1207 <description summary="start an interactive move">
1208 Start a pointer-driven move of the surface.
1209
1210 This request must be used in response to a button press event.
1211 The server may ignore move requests depending on the state of
1212 the surface (e.g. fullscreen or maximized).
1213 </description>
1214 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1215 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1216 </request>
1217
1218 <enum name="resize" bitfield="true">
1219 <description summary="edge values for resizing">
1220 These values are used to indicate which edge of a surface
1221 is being dragged in a resize operation. The server may
1222 use this information to adapt its behavior, e.g. choose
1223 an appropriate cursor image.
1224 </description>
1225 <entry name="none" value="0" summary="no edge"/>
1226 <entry name="top" value="1" summary="top edge"/>
1227 <entry name="bottom" value="2" summary="bottom edge"/>
1228 <entry name="left" value="4" summary="left edge"/>
1229 <entry name="top_left" value="5" summary="top and left edges"/>
1230 <entry name="bottom_left" value="6" summary="bottom and left edges"/>
1231 <entry name="right" value="8" summary="right edge"/>
1232 <entry name="top_right" value="9" summary="top and right edges"/>
1233 <entry name="bottom_right" value="10" summary="bottom and right edges"/>
1234 </enum>
1235
1236 <request name="resize">
1237 <description summary="start an interactive resize">
1238 Start a pointer-driven resizing of the surface.
1239
1240 This request must be used in response to a button press event.
1241 The server may ignore resize requests depending on the state of
1242 the surface (e.g. fullscreen or maximized).
1243 </description>
1244 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1245 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1246 <arg name="edges" type="uint" enum="resize" summary="which edge or corner is being dragged"/>
1247 </request>
1248
1249 <request name="set_toplevel">
1250 <description summary="make the surface a toplevel surface">
1251 Map the surface as a toplevel surface.
1252
1253 A toplevel surface is not fullscreen, maximized or transient.
1254 </description>
1255 </request>
1256
1257 <enum name="transient" bitfield="true">
1258 <description summary="details of transient behaviour">
1259 These flags specify details of the expected behaviour
1260 of transient surfaces. Used in the set_transient request.
1261 </description>
1262 <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
1263 </enum>
1264
1265 <request name="set_transient">
1266 <description summary="make the surface a transient surface">
1267 Map the surface relative to an existing surface.
1268
1269 The x and y arguments specify the location of the upper left
1270 corner of the surface relative to the upper left corner of the
1271 parent surface, in surface-local coordinates.
1272
1273 The flags argument controls details of the transient behaviour.
1274 </description>
1275 <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1276 <arg name="x" type="int" summary="surface-local x coordinate"/>
1277 <arg name="y" type="int" summary="surface-local y coordinate"/>
1278 <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1279 </request>
1280
1281 <enum name="fullscreen_method">
1282 <description summary="different method to set the surface fullscreen">
1283 Hints to indicate to the compositor how to deal with a conflict
1284 between the dimensions of the surface and the dimensions of the
1285 output. The compositor is free to ignore this parameter.
1286 </description>
1287 <entry name="default" value="0" summary="no preference, apply default policy"/>
1288 <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
1289 <entry name="driver" value="2" summary="switch output mode to the smallest mode that can fit the surface, add black borders to compensate size mismatch"/>
1290 <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1291 </enum>
1292
1293 <request name="set_fullscreen">
1294 <description summary="make the surface a fullscreen surface">
1295 Map the surface as a fullscreen surface.
1296
1297 If an output parameter is given then the surface will be made
1298 fullscreen on that output. If the client does not specify the
1299 output then the compositor will apply its policy - usually
1300 choosing the output on which the surface has the biggest surface
1301 area.
1302
1303 The client may specify a method to resolve a size conflict
1304 between the output size and the surface size - this is provided
1305 through the method parameter.
1306
1307 The framerate parameter is used only when the method is set
1308 to "driver", to indicate the preferred framerate. A value of 0
1309 indicates that the client does not care about framerate. The
1310 framerate is specified in mHz, that is framerate of 60000 is 60Hz.
1311
1312 A method of "scale" or "driver" implies a scaling operation of
1313 the surface, either via a direct scaling operation or a change of
1314 the output mode. This will override any kind of output scaling, so
1315 that mapping a surface with a buffer size equal to the mode can
1316 fill the screen independent of buffer_scale.
1317
1318 A method of "fill" means we don't scale up the buffer, however
1319 any output scale is applied. This means that you may run into
1320 an edge case where the application maps a buffer with the same
1321 size of the output mode but buffer_scale 1 (thus making a
1322 surface larger than the output). In this case it is allowed to
1323 downscale the results to fit the screen.
1324
1325 The compositor must reply to this request with a configure event
1326 with the dimensions for the output on which the surface will
1327 be made fullscreen.
1328 </description>
1329 <arg name="method" type="uint" enum="fullscreen_method" summary="method for resolving size conflict"/>
1330 <arg name="framerate" type="uint" summary="framerate in mHz"/>
1331 <arg name="output" type="object" interface="wl_output" allow-null="true"
1332 summary="output on which the surface is to be fullscreen"/>
1333 </request>
1334
1335 <request name="set_popup">
1336 <description summary="make the surface a popup surface">
1337 Map the surface as a popup.
1338
1339 A popup surface is a transient surface with an added pointer
1340 grab.
1341
1342 An existing implicit grab will be changed to owner-events mode,
1343 and the popup grab will continue after the implicit grab ends
1344 (i.e. releasing the mouse button does not cause the popup to
1345 be unmapped).
1346
1347 The popup grab continues until the window is destroyed or a
1348 mouse button is pressed in any other client's window. A click
1349 in any of the client's surfaces is reported as normal, however,
1350 clicks in other clients' surfaces will be discarded and trigger
1351 the callback.
1352
1353 The x and y arguments specify the location of the upper left
1354 corner of the surface relative to the upper left corner of the
1355 parent surface, in surface-local coordinates.
1356 </description>
1357 <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1358 <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1359 <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1360 <arg name="x" type="int" summary="surface-local x coordinate"/>
1361 <arg name="y" type="int" summary="surface-local y coordinate"/>
1362 <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1363 </request>
1364
1365 <request name="set_maximized">
1366 <description summary="make the surface a maximized surface">
1367 Map the surface as a maximized surface.
1368
1369 If an output parameter is given then the surface will be
1370 maximized on that output. If the client does not specify the
1371 output then the compositor will apply its policy - usually
1372 choosing the output on which the surface has the biggest surface
1373 area.
1374
1375 The compositor will reply with a configure event telling
1376 the expected new surface size. The operation is completed
1377 on the next buffer attach to this surface.
1378
1379 A maximized surface typically fills the entire output it is
1380 bound to, except for desktop elements such as panels. This is
1381 the main difference between a maximized shell surface and a
1382 fullscreen shell surface.
1383
1384 The details depend on the compositor implementation.
1385 </description>
1386 <arg name="output" type="object" interface="wl_output" allow-null="true"
1387 summary="output on which the surface is to be maximized"/>
1388 </request>
1389
1390 <request name="set_title">
1391 <description summary="set surface title">
1392 Set a short title for the surface.
1393
1394 This string may be used to identify the surface in a task bar,
1395 window list, or other user interface elements provided by the
1396 compositor.
1397
1398 The string must be encoded in UTF-8.
1399 </description>
1400 <arg name="title" type="string" summary="surface title"/>
1401 </request>
1402
1403 <request name="set_class">
1404 <description summary="set surface class">
1405 Set a class for the surface.
1406
1407 The surface class identifies the general class of applications
1408 to which the surface belongs. A common convention is to use the
1409 file name (or the full path if it is a non-standard location) of
1410 the application's .desktop file as the class.
1411 </description>
1412 <arg name="class_" type="string" summary="surface class"/>
1413 </request>
1414
1415 <event name="ping">
1416 <description summary="ping client">
1417 Ping a client to check if it is receiving events and sending
1418 requests. A client is expected to reply with a pong request.
1419 </description>
1420 <arg name="serial" type="uint" summary="serial number of the ping"/>
1421 </event>
1422
1423 <event name="configure">
1424 <description summary="suggest resize">
1425 The configure event asks the client to resize its surface.
1426
1427 The size is a hint, in the sense that the client is free to
1428 ignore it if it doesn't resize, pick a smaller size (to
1429 satisfy aspect ratio or resize in steps of NxM pixels).
1430
1431 The edges parameter provides a hint about how the surface
1432 was resized. The client may use this information to decide
1433 how to adjust its content to the new size (e.g. a scrolling
1434 area might adjust its content position to leave the viewable
1435 content unmoved).
1436
1437 The client is free to dismiss all but the last configure
1438 event it received.
1439
1440 The width and height arguments specify the size of the window
1441 in surface-local coordinates.
1442 </description>
1443 <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
1444 <arg name="width" type="int" summary="new width of the surface"/>
1445 <arg name="height" type="int" summary="new height of the surface"/>
1446 </event>
1447
1448 <event name="popup_done">
1449 <description summary="popup interaction is done">
1450 The popup_done event is sent out when a popup grab is broken,
1451 that is, when the user clicks a surface that doesn't belong
1452 to the client owning the popup surface.
1453 </description>
1454 </event>
1455 </interface>
1456
1457 <interface name="wl_surface" version="7">
1458 <description summary="an onscreen surface">
1459 A surface is a rectangular area that may be displayed on zero
1460 or more outputs, and shown any number of times at the compositor's
1461 discretion. They can present wl_buffers, receive user input, and
1462 define a local coordinate system.
1463
1464 The size of a surface (and relative positions on it) is described
1465 in surface-local coordinates, which may differ from the buffer
1466 coordinates of the pixel content, in case a buffer_transform
1467 or a buffer_scale is used.
1468
1469 A surface without a "role" is fairly useless: a compositor does
1470 not know where, when or how to present it. The role is the
1471 purpose of a wl_surface. Examples of roles are a cursor for a
1472 pointer (as set by wl_pointer.set_cursor), a drag icon
1473 (wl_data_device.start_drag), a sub-surface
1474 (wl_subcompositor.get_subsurface), and a window as defined by a
1475 shell protocol (e.g. wl_shell.get_shell_surface).
1476
1477 A surface can have only one role at a time. Initially a
1478 wl_surface does not have a role. Once a wl_surface is given a
1479 role, it is set permanently for the whole lifetime of the
1480 wl_surface object. Giving the current role again is allowed,
1481 unless explicitly forbidden by the relevant interface
1482 specification.
1483
1484 Surface roles are given by requests in other interfaces such as
1485 wl_pointer.set_cursor. The request should explicitly mention
1486 that this request gives a role to a wl_surface. Often, this
1487 request also creates a new protocol object that represents the
1488 role and adds additional functionality to wl_surface. When a
1489 client wants to destroy a wl_surface, they must destroy this role
1490 object before the wl_surface, otherwise a defunct_role_object error is
1491 sent.
1492
1493 Destroying the role object does not remove the role from the
1494 wl_surface, but it may stop the wl_surface from "playing the role".
1495 For instance, if a wl_subsurface object is destroyed, the wl_surface
1496 it was created for will be unmapped and forget its position and
1497 z-order. It is allowed to create a wl_subsurface for the same
1498 wl_surface again, but it is not allowed to use the wl_surface as
1499 a cursor (cursor is a different role than sub-surface, and role
1500 switching is not allowed).
1501 </description>
1502
1503 <enum name="error">
1504 <description summary="wl_surface error values">
1505 These errors can be emitted in response to wl_surface requests.
1506 </description>
1507 <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
1508 <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
1509 <entry name="invalid_size" value="2" summary="buffer size is invalid"/>
1510 <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
1511 <entry name="defunct_role_object" value="4"
1512 summary="surface was destroyed before its role object"/>
1513 <entry name="no_buffer" value="5" summary="no buffer was attached"/>
1514 </enum>
1515
1516 <request name="destroy" type="destructor">
1517 <description summary="delete surface">
1518 Deletes the surface and invalidates its object ID.
1519 </description>
1520 </request>
1521
1522 <request name="attach">
1523 <description summary="set the surface contents">
1524 Set a buffer as the content of this surface.
1525
1526 The new size of the surface is calculated based on the buffer
1527 size transformed by the inverse buffer_transform and the
1528 inverse buffer_scale. This means that at commit time the supplied
1529 buffer size must be an integer multiple of the buffer_scale. If
1530 that's not the case, an invalid_size error is sent.
1531
1532 The x and y arguments specify the location of the new pending
1533 buffer's upper left corner, relative to the current buffer's upper
1534 left corner, in surface-local coordinates. In other words, the
1535 x and y, combined with the new surface size define in which
1536 directions the surface's size changes. Setting anything other than 0
1537 as x and y arguments is discouraged, and should instead be replaced
1538 with using the separate wl_surface.offset request.
1539
1540 When the bound wl_surface version is 5 or higher, passing any
1541 non-zero x or y is a protocol violation, and will result in an
1542 'invalid_offset' error being raised. The x and y arguments are ignored
1543 and do not change the pending state. To achieve equivalent semantics,
1544 use wl_surface.offset.
1545
1546 Surface contents are double-buffered state, see wl_surface.commit.
1547
1548 The initial surface contents are void; there is no content.
1549 wl_surface.attach assigns the given wl_buffer as the pending
1550 wl_buffer. wl_surface.commit makes the pending wl_buffer the new
1551 surface contents, and the size of the surface becomes the size
1552 calculated from the wl_buffer, as described above. After commit,
1553 there is no pending buffer until the next attach.
1554
1555 Committing a pending wl_buffer allows the compositor to read the
1556 pixels in the wl_buffer. The compositor may access the pixels at
1557 any time after the wl_surface.commit request. When the compositor
1558 will not access the pixels anymore, it will send the
1559 wl_buffer.release event. Only after receiving wl_buffer.release,
1560 the client may reuse the wl_buffer. A wl_buffer that has been
1561 attached and then replaced by another attach instead of committed
1562 will not receive a release event, and is not used by the
1563 compositor.
1564
1565 If a pending wl_buffer has been committed to more than one wl_surface,
1566 the delivery of wl_buffer.release events becomes undefined. A well
1567 behaved client should not rely on wl_buffer.release events in this
1568 case. Instead, clients hitting this case should use
1569 wl_surface.get_release or use a protocol extension providing per-commit
1570 release notifications (if none of these options are available, a
1571 fallback can be implemented by creating multiple wl_buffer objects from
1572 the same backing storage).
1573
1574 Destroying the wl_buffer after wl_buffer.release does not change
1575 the surface contents. Destroying the wl_buffer before wl_buffer.release
1576 is allowed as long as the underlying buffer storage isn't re-used (this
1577 can happen e.g. on client process termination). However, if the client
1578 destroys the wl_buffer before receiving the wl_buffer.release event and
1579 mutates the underlying buffer storage, the surface contents become
1580 undefined immediately.
1581
1582 If wl_surface.attach is sent with a NULL wl_buffer, the
1583 following wl_surface.commit will remove the surface content.
1584
1585 If a pending wl_buffer has been destroyed, the result is not specified.
1586 Many compositors are known to remove the surface content on the following
1587 wl_surface.commit, but this behaviour is not universal. Clients seeking to
1588 maximise compatibility should not destroy pending buffers and should
1589 ensure that they explicitly remove content from surfaces, even after
1590 destroying buffers.
1591 </description>
1592 <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
1593 summary="buffer of surface contents"/>
1594 <arg name="x" type="int" summary="surface-local x coordinate"/>
1595 <arg name="y" type="int" summary="surface-local y coordinate"/>
1596 </request>
1597
1598 <request name="damage">
1599 <description summary="mark part of the surface damaged">
1600 This request is used to describe the regions where the pending
1601 buffer is different from the current surface contents, and where
1602 the surface therefore needs to be repainted. The compositor
1603 ignores the parts of the damage that fall outside of the surface.
1604
1605 Damage is double-buffered state, see wl_surface.commit.
1606
1607 The damage rectangle is specified in surface-local coordinates,
1608 where x and y specify the upper left corner of the damage rectangle.
1609
1610 The initial value for pending damage is empty: no damage.
1611 wl_surface.damage adds pending damage: the new pending damage
1612 is the union of old pending damage and the given rectangle.
1613
1614 wl_surface.commit assigns pending damage as the current damage,
1615 and clears pending damage. The server will clear the current
1616 damage as it repaints the surface.
1617
1618 Note! New clients should not use this request. Instead damage can be
1619 posted with wl_surface.damage_buffer which uses buffer coordinates
1620 instead of surface coordinates.
1621 </description>
1622 <arg name="x" type="int" summary="surface-local x coordinate"/>
1623 <arg name="y" type="int" summary="surface-local y coordinate"/>
1624 <arg name="width" type="int" summary="width of damage rectangle"/>
1625 <arg name="height" type="int" summary="height of damage rectangle"/>
1626 </request>
1627
1628 <request name="frame">
1629 <description summary="request a frame throttling hint">
1630 Request a notification when it is a good time to start drawing a new
1631 frame, by creating a frame callback. This is useful for throttling
1632 redrawing operations, and driving animations.
1633
1634 When a client is animating on a wl_surface, it can use the 'frame'
1635 request to get notified when it is a good time to draw and commit the
1636 next frame of animation. If the client commits an update earlier than
1637 that, it is likely that some updates will not make it to the display,
1638 and the client is wasting resources by drawing too often.
1639
1640 The frame request will take effect on the next wl_surface.commit.
1641 The notification will only be posted for one frame unless
1642 requested again. For a wl_surface, the notifications are posted in
1643 the order the frame requests were committed.
1644
1645 The server must send the notifications so that a client
1646 will not send excessive updates, while still allowing
1647 the highest possible update rate for clients that wait for the reply
1648 before drawing again. The server should give some time for the client
1649 to draw and commit after sending the frame callback events to let it
1650 hit the next output refresh.
1651
1652 A server should avoid signaling the frame callbacks if the
1653 surface is not visible in any way, e.g. the surface is off-screen,
1654 or completely obscured by other opaque surfaces.
1655
1656 The object returned by this request will be destroyed by the
1657 compositor after the callback is fired and as such the client must not
1658 attempt to use it after that point.
1659
1660 The callback_data passed in the callback is the current time, in
1661 milliseconds, with an undefined base.
1662 </description>
1663 <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the frame request"/>
1664 </request>
1665
1666 <request name="set_opaque_region">
1667 <description summary="set opaque region">
1668 This request sets the region of the surface that contains
1669 opaque content.
1670
1671 The opaque region is an optimization hint for the compositor
1672 that lets it optimize the redrawing of content behind opaque
1673 regions. Setting an opaque region is not required for correct
1674 behaviour, but marking transparent content as opaque will result
1675 in repaint artifacts.
1676
1677 The opaque region is specified in surface-local coordinates.
1678
1679 The compositor ignores the parts of the opaque region that fall
1680 outside of the surface.
1681
1682 Opaque region is double-buffered state, see wl_surface.commit.
1683
1684 wl_surface.set_opaque_region changes the pending opaque region.
1685 wl_surface.commit copies the pending region to the current region.
1686 Otherwise, the pending and current regions are never changed.
1687
1688 The initial value for an opaque region is empty. Setting the pending
1689 opaque region has copy semantics, and the wl_region object can be
1690 destroyed immediately. A NULL wl_region causes the pending opaque
1691 region to be set to empty.
1692 </description>
1693 <arg name="region" type="object" interface="wl_region" allow-null="true"
1694 summary="opaque region of the surface"/>
1695 </request>
1696
1697 <request name="set_input_region">
1698 <description summary="set input region">
1699 This request sets the region of the surface that can receive
1700 pointer and touch events.
1701
1702 Input events happening outside of this region will try the next
1703 surface in the server surface stack. The compositor ignores the
1704 parts of the input region that fall outside of the surface.
1705
1706 The input region is specified in surface-local coordinates.
1707
1708 Input region is double-buffered state, see wl_surface.commit.
1709
1710 wl_surface.set_input_region changes the pending input region.
1711 wl_surface.commit copies the pending region to the current region.
1712 Otherwise the pending and current regions are never changed,
1713 except cursor and icon surfaces are special cases, see
1714 wl_pointer.set_cursor and wl_data_device.start_drag.
1715
1716 The initial value for an input region is infinite. That means the
1717 whole surface will accept input. Setting the pending input region
1718 has copy semantics, and the wl_region object can be destroyed
1719 immediately. A NULL wl_region causes the input region to be set
1720 to infinite.
1721 </description>
1722 <arg name="region" type="object" interface="wl_region" allow-null="true"
1723 summary="input region of the surface"/>
1724 </request>
1725
1726 <request name="commit">
1727 <description summary="commit pending surface state">
1728 Surface state (input, opaque, and damage regions, attached buffers,
1729 etc.) is double-buffered. Protocol requests modify the pending state,
1730 as opposed to the active state in use by the compositor.
1731
1732 All requests that need a commit to become effective are documented
1733 to affect double-buffered state.
1734
1735 Other interfaces may add further double-buffered surface state.
1736
1737 A commit request atomically creates a Content Update (CU) from the
1738 pending state, even if the pending state has not been touched. The
1739 content update is placed at the end of a per-surface queue until it
1740 becomes active. After commit, the new pending state is as documented for
1741 each related request.
1742
1743 A CU is either a Desync Content Update (DCU) or a Sync Content Update
1744 (SCU). If the surface is effectively synchronized at the commit request,
1745 it is a SCU, otherwise a DCU.
1746
1747 When a surface transitions from effectively synchronized to effectively
1748 desynchronized, all SCUs in its queue which are not reachable by any
1749 DCU become DCUs and dependency edges from outside the queue to these CUs
1750 are removed.
1751
1752 See wl_subsurface for the definition of 'effectively synchronized' and
1753 'effectively desynchronized'.
1754
1755 When a CU is placed in the queue, the CU has a dependency on the CU in
1756 front of it and to the SCU at end of the queue of every direct child
1757 surface if that SCU exists and does not have another dependent. This can
1758 form a directed acyclic graph of CUs with dependencies as edges.
1759
1760 In addition to surface state, the CU can have constraints that must be
1761 satisfied before it can be applied. Other interfaces may add CU
1762 constraints.
1763
1764 All DCUs which do not have a SCU in front of themselves in their queue,
1765 are candidates. If the graph that's reachable by a candidate does not
1766 have any unsatisfied constraints, the entire graph must be applied
1767 atomically.
1768
1769 When a CU is applied, the wl_buffer is applied before all other state.
1770 This means that all coordinates in double-buffered state are relative to
1771 the newly attached wl_buffers, except for wl_surface.attach itself. If
1772 there is no newly attached wl_buffer, the coordinates are relative to
1773 the previous content update.
1774 </description>
1775 </request>
1776
1777 <event name="enter">
1778 <description summary="surface enters an output">
1779 This is emitted whenever a surface's creation, movement, or resizing
1780 results in some part of it being within the scanout region of an
1781 output.
1782
1783 Note that a surface may be overlapping with zero or more outputs.
1784 </description>
1785 <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
1786 </event>
1787
1788 <event name="leave">
1789 <description summary="surface leaves an output">
1790 This is emitted whenever a surface's creation, movement, or resizing
1791 results in it no longer having any part of it within the scanout region
1792 of an output.
1793
1794 Clients should not use the number of outputs the surface is on for frame
1795 throttling purposes. The surface might be hidden even if no leave event
1796 has been sent, and the compositor might expect new surface content
1797 updates even if no enter event has been sent. The frame event should be
1798 used instead.
1799 </description>
1800 <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
1801 </event>
1802
1803 <!-- Version 2 additions -->
1804
1805 <request name="set_buffer_transform" since="2">
1806 <description summary="sets the buffer transformation">
1807 This request sets the transformation that the client has already applied
1808 to the content of the buffer. The accepted values for the transform
1809 parameter are the values for wl_output.transform.
1810
1811 The compositor applies the inverse of this transformation whenever it
1812 uses the buffer contents.
1813
1814 Buffer transform is double-buffered state, see wl_surface.commit.
1815
1816 A newly created surface has its buffer transformation set to normal.
1817
1818 wl_surface.set_buffer_transform changes the pending buffer
1819 transformation. wl_surface.commit copies the pending buffer
1820 transformation to the current one. Otherwise, the pending and current
1821 values are never changed.
1822
1823 The purpose of this request is to allow clients to render content
1824 according to the output transform, thus permitting the compositor to
1825 use certain optimizations even if the display is rotated. Using
1826 hardware overlays and scanning out a client buffer for fullscreen
1827 surfaces are examples of such optimizations. Those optimizations are
1828 highly dependent on the compositor implementation, so the use of this
1829 request should be considered on a case-by-case basis.
1830
1831 Note that if the transform value includes 90 or 270 degree rotation,
1832 the width of the buffer will become the surface height and the height
1833 of the buffer will become the surface width.
1834
1835 If transform is not one of the values from the
1836 wl_output.transform enum the invalid_transform protocol error
1837 is raised.
1838 </description>
1839 <arg name="transform" type="int" enum="wl_output.transform"
1840 summary="transform for interpreting buffer contents"/>
1841 </request>
1842
1843 <!-- Version 3 additions -->
1844
1845 <request name="set_buffer_scale" since="3">
1846 <description summary="sets the buffer scaling factor">
1847 This request sets an optional scaling factor on how the compositor
1848 interprets the contents of the buffer attached to the window.
1849
1850 Buffer scale is double-buffered state, see wl_surface.commit.
1851
1852 A newly created surface has its buffer scale set to 1.
1853
1854 wl_surface.set_buffer_scale changes the pending buffer scale.
1855 wl_surface.commit copies the pending buffer scale to the current one.
1856 Otherwise, the pending and current values are never changed.
1857
1858 The purpose of this request is to allow clients to supply higher
1859 resolution buffer data for use on high resolution outputs. It is
1860 intended that you pick the same buffer scale as the scale of the
1861 output that the surface is displayed on. This means the compositor
1862 can avoid scaling when rendering the surface on that output.
1863
1864 Note that if the scale is larger than 1, then you have to attach
1865 a buffer that is larger (by a factor of scale in each dimension)
1866 than the desired surface size.
1867
1868 If scale is not greater than 0 the invalid_scale protocol error is
1869 raised.
1870 </description>
1871 <arg name="scale" type="int"
1872 summary="scale for interpreting buffer contents"/>
1873 </request>
1874
1875 <!-- Version 4 additions -->
1876 <request name="damage_buffer" since="4">
1877 <description summary="mark part of the surface damaged using buffer coordinates">
1878 This request is used to describe the regions where the pending
1879 buffer is different from the current surface contents, and where
1880 the surface therefore needs to be repainted. The compositor
1881 ignores the parts of the damage that fall outside of the surface.
1882
1883 Damage is double-buffered state, see wl_surface.commit.
1884
1885 The damage rectangle is specified in buffer coordinates,
1886 where x and y specify the upper left corner of the damage rectangle.
1887
1888 The initial value for pending damage is empty: no damage.
1889 wl_surface.damage_buffer adds pending damage: the new pending
1890 damage is the union of old pending damage and the given rectangle.
1891
1892 wl_surface.commit assigns pending damage as the current damage,
1893 and clears pending damage. The server will clear the current
1894 damage as it repaints the surface.
1895
1896 This request differs from wl_surface.damage in only one way - it
1897 takes damage in buffer coordinates instead of surface-local
1898 coordinates. While this generally is more intuitive than surface
1899 coordinates, it is especially desirable when using wp_viewport
1900 or when a drawing library (like EGL) is unaware of buffer scale
1901 and buffer transform.
1902
1903 Note: Because buffer transformation changes and damage requests may
1904 be interleaved in the protocol stream, it is impossible to determine
1905 the actual mapping between surface and buffer damage until
1906 wl_surface.commit time. Therefore, compositors wishing to take both
1907 kinds of damage into account will have to accumulate damage from the
1908 two requests separately and only transform from one to the other
1909 after receiving the wl_surface.commit.
1910 </description>
1911 <arg name="x" type="int" summary="buffer-local x coordinate"/>
1912 <arg name="y" type="int" summary="buffer-local y coordinate"/>
1913 <arg name="width" type="int" summary="width of damage rectangle"/>
1914 <arg name="height" type="int" summary="height of damage rectangle"/>
1915 </request>
1916
1917 <!-- Version 5 additions -->
1918
1919 <request name="offset" since="5">
1920 <description summary="set the surface contents offset">
1921 The x and y arguments specify the location of the new pending
1922 buffer's upper left corner, relative to the current buffer's upper
1923 left corner, in surface-local coordinates. In other words, the
1924 x and y, combined with the new surface size define in which
1925 directions the surface's size changes.
1926
1927 The exact semantics of wl_surface.offset are role-specific. Refer to
1928 the documentation of specific roles for more information.
1929
1930 Surface location offset is double-buffered state, see
1931 wl_surface.commit.
1932
1933 This request is semantically equivalent to and the replaces the x and y
1934 arguments in the wl_surface.attach request in wl_surface versions prior
1935 to 5. See wl_surface.attach for details.
1936 </description>
1937 <arg name="x" type="int" summary="surface-local x coordinate"/>
1938 <arg name="y" type="int" summary="surface-local y coordinate"/>
1939 </request>
1940
1941 <!-- Version 6 additions -->
1942
1943 <event name="preferred_buffer_scale" since="6">
1944 <description summary="preferred buffer scale for the surface">
1945 This event indicates the preferred buffer scale for this surface. It is
1946 sent whenever the compositor's preference changes.
1947
1948 Before receiving this event the preferred buffer scale for this surface
1949 is 1.
1950
1951 It is intended that scaling aware clients use this event to scale their
1952 content and use wl_surface.set_buffer_scale to indicate the scale they
1953 have rendered with. This allows clients to supply a higher detail
1954 buffer.
1955
1956 The compositor shall emit a scale value greater than 0.
1957 </description>
1958 <arg name="factor" type="int" summary="preferred scaling factor"/>
1959 </event>
1960
1961 <event name="preferred_buffer_transform" since="6">
1962 <description summary="preferred buffer transform for the surface">
1963 This event indicates the preferred buffer transform for this surface.
1964 It is sent whenever the compositor's preference changes.
1965
1966 Before receiving this event the preferred buffer transform for this
1967 surface is normal.
1968
1969 Applying this transformation to the surface buffer contents and using
1970 wl_surface.set_buffer_transform might allow the compositor to use the
1971 surface buffer more efficiently.
1972 </description>
1973 <arg name="transform" type="uint" enum="wl_output.transform"
1974 summary="preferred transform"/>
1975 </event>
1976
1977 <!-- Version 7 additions -->
1978
1979 <request name="get_release" since="7">
1980 <description summary="get a release callback">
1981 Create a callback for the release of the buffer attached by the client
1982 with wl_surface.attach.
1983
1984 The compositor will release the buffer when it has finished its usage of
1985 the underlying storage for the relevant commit. Once the client receives
1986 this event, and assuming the associated buffer is not pending release
1987 from other wl_surface.commit requests, the client can safely re-use the
1988 buffer.
1989
1990 Release callbacks are double-buffered state, and will be associated
1991 with the pending buffer at wl_surface.commit time.
1992
1993 The callback_data passed in the wl_callback.done event is unused and
1994 is always zero.
1995
1996 Sending this request without attaching a non-null buffer in the same
1997 content update is a protocol error. The compositor will send the
1998 no_buffer error in this case.
1999 </description>
2000 <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the release"/>
2001 </request>
2002 </interface>
2003
2004 <interface name="wl_seat" version="11">
2005 <description summary="group of input devices">
2006 A seat is a group of keyboards, pointer and touch devices. This
2007 object is published as a global during start up, or when such a
2008 device is hot plugged. A seat typically has a pointer and
2009 maintains a keyboard focus and a pointer focus.
2010 </description>
2011
2012 <enum name="capability" bitfield="true">
2013 <description summary="seat capability bitmask">
2014 This is a bitmask of capabilities this seat has; if a member is
2015 set, then it is present on the seat.
2016 </description>
2017 <entry name="pointer" value="1" summary="the seat has pointer devices"/>
2018 <entry name="keyboard" value="2" summary="the seat has one or more keyboards"/>
2019 <entry name="touch" value="4" summary="the seat has touch devices"/>
2020 </enum>
2021
2022 <enum name="error">
2023 <description summary="wl_seat error values">
2024 These errors can be emitted in response to wl_seat requests.
2025 </description>
2026 <entry name="missing_capability" value="0"
2027 summary="get_pointer, get_keyboard or get_touch called on seat without the matching capability"/>
2028 </enum>
2029
2030 <event name="capabilities">
2031 <description summary="seat capabilities changed">
2032 This is sent on binding to the seat global or whenever a seat gains
2033 or loses the pointer, keyboard or touch capabilities.
2034 The argument is a capability enum containing the complete set of
2035 capabilities this seat has.
2036
2037 When the pointer capability is added, a client may create a
2038 wl_pointer object using the wl_seat.get_pointer request. This object
2039 will receive pointer events until the capability is removed in the
2040 future.
2041
2042 When the pointer capability is removed, a client should destroy the
2043 wl_pointer objects associated with the seat where the capability was
2044 removed, using the wl_pointer.release request. No further pointer
2045 events will be received on these objects.
2046
2047 In some compositors, if a seat regains the pointer capability and a
2048 client has a previously obtained wl_pointer object of version 4 or
2049 less, that object may start sending pointer events again. This
2050 behavior is considered a misinterpretation of the intended behavior
2051 and must not be relied upon by the client. wl_pointer objects of
2052 version 5 or later must not send events if created before the most
2053 recent event notifying the client of an added pointer capability.
2054
2055 The above behavior also applies to wl_keyboard and wl_touch with the
2056 keyboard and touch capabilities, respectively.
2057 </description>
2058 <arg name="capabilities" type="uint" enum="capability" summary="capabilities of the seat"/>
2059 </event>
2060
2061 <request name="get_pointer">
2062 <description summary="return pointer object">
2063 The ID provided will be initialized to the wl_pointer interface
2064 for this seat.
2065
2066 This request only takes effect if the seat has the pointer
2067 capability, or has had the pointer capability in the past.
2068 It is a protocol violation to issue this request on a seat that has
2069 never had the pointer capability. The missing_capability error will
2070 be sent in this case.
2071 </description>
2072 <arg name="id" type="new_id" interface="wl_pointer" summary="seat pointer"/>
2073 </request>
2074
2075 <request name="get_keyboard">
2076 <description summary="return keyboard object">
2077 The ID provided will be initialized to the wl_keyboard interface
2078 for this seat.
2079
2080 This request only takes effect if the seat has the keyboard
2081 capability, or has had the keyboard capability in the past.
2082 It is a protocol violation to issue this request on a seat that has
2083 never had the keyboard capability. The missing_capability error will
2084 be sent in this case.
2085 </description>
2086 <arg name="id" type="new_id" interface="wl_keyboard" summary="seat keyboard"/>
2087 </request>
2088
2089 <request name="get_touch">
2090 <description summary="return touch object">
2091 The ID provided will be initialized to the wl_touch interface
2092 for this seat.
2093
2094 This request only takes effect if the seat has the touch
2095 capability, or has had the touch capability in the past.
2096 It is a protocol violation to issue this request on a seat that has
2097 never had the touch capability. The missing_capability error will
2098 be sent in this case.
2099 </description>
2100 <arg name="id" type="new_id" interface="wl_touch" summary="seat touch interface"/>
2101 </request>
2102
2103 <!-- Version 2 additions -->
2104
2105 <event name="name" since="2">
2106 <description summary="unique identifier for this seat">
2107 In a multi-seat configuration the seat name can be used by clients to
2108 help identify which physical devices the seat represents.
2109
2110 The seat name is a UTF-8 string with no convention defined for its
2111 contents. Each name is unique among all wl_seat globals. The name is
2112 only guaranteed to be unique for the current compositor instance.
2113
2114 The same seat names are used for all clients. Thus, the name can be
2115 shared across processes to refer to a specific wl_seat global.
2116
2117 The name event is sent after binding to the seat global, and should be sent
2118 before announcing capabilities. This event is only sent once per seat object,
2119 and the name does not change over the lifetime of the wl_seat global.
2120
2121 Compositors may re-use the same seat name if the wl_seat global is
2122 destroyed and re-created later.
2123 </description>
2124 <arg name="name" type="string" summary="seat identifier"/>
2125 </event>
2126
2127 <!-- Version 5 additions -->
2128
2129 <request name="release" type="destructor" since="5">
2130 <description summary="release the seat object">
2131 Using this request a client can tell the server that it is not going to
2132 use the seat object anymore.
2133 </description>
2134 </request>
2135
2136 </interface>
2137
2138 <interface name="wl_pointer" version="11">
2139 <description summary="pointer input device">
2140 The wl_pointer interface represents one or more input devices,
2141 such as mice, which control the pointer location and pointer_focus
2142 of a seat.
2143
2144 The wl_pointer interface generates motion, enter and leave
2145 events for the surfaces that the pointer is located over,
2146 and button and axis events for button presses, button releases
2147 and scrolling.
2148 </description>
2149
2150 <enum name="error">
2151 <entry name="role" value="0" summary="given wl_surface has another role"/>
2152 </enum>
2153
2154 <request name="set_cursor">
2155 <description summary="set the pointer surface">
2156 Set the pointer surface, i.e., the surface that contains the
2157 pointer image (cursor). This request gives the surface the role
2158 of a cursor. If the surface already has another role, it raises
2159 a protocol error.
2160
2161 The cursor actually changes only if the pointer
2162 focus for this device is one of the requesting client's surfaces
2163 or the surface parameter is the current pointer surface. If
2164 there was a previous surface set with this request it is
2165 replaced. If surface is NULL, the pointer image is hidden.
2166
2167 The parameters hotspot_x and hotspot_y define the position of
2168 the pointer surface relative to the pointer location. Its
2169 top-left corner is always at (x, y) - (hotspot_x, hotspot_y),
2170 where (x, y) are the coordinates of the pointer location, in
2171 surface-local coordinates.
2172
2173 On wl_surface.offset requests to the pointer surface, hotspot_x
2174 and hotspot_y are decremented by the x and y parameters
2175 passed to the request. The offset must be applied by
2176 wl_surface.commit as usual.
2177
2178 The hotspot can also be updated by passing the currently set
2179 pointer surface to this request with new values for hotspot_x
2180 and hotspot_y.
2181
2182 The input region is ignored for wl_surfaces with the role of
2183 a cursor. When the use as a cursor ends, the wl_surface is
2184 unmapped.
2185
2186 The serial parameter must match the latest wl_pointer.enter
2187 serial number sent to the client. Otherwise the request will be
2188 ignored.
2189 </description>
2190 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2191 <arg name="surface" type="object" interface="wl_surface" allow-null="true"
2192 summary="pointer surface"/>
2193 <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
2194 <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
2195 </request>
2196
2197 <event name="enter">
2198 <description summary="enter event">
2199 Notification that this seat's pointer is focused on a certain
2200 surface.
2201
2202 When a seat's focus enters a surface, the pointer image
2203 is undefined and a client should respond to this event by setting
2204 an appropriate pointer image with the set_cursor request.
2205 </description>
2206 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2207 <arg name="surface" type="object" interface="wl_surface" summary="surface entered by the pointer"/>
2208 <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2209 <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2210 </event>
2211
2212 <event name="leave">
2213 <description summary="leave event">
2214 Notification that this seat's pointer is no longer focused on
2215 a certain surface.
2216
2217 The leave notification is sent before the enter notification
2218 for the new focus.
2219 </description>
2220 <arg name="serial" type="uint" summary="serial number of the leave event"/>
2221 <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
2222 </event>
2223
2224 <event name="motion">
2225 <description summary="pointer motion event">
2226 Notification of pointer location change. The arguments
2227 surface_x and surface_y are the location relative to the
2228 focused surface.
2229 </description>
2230 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2231 <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2232 <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2233 </event>
2234
2235 <enum name="button_state">
2236 <description summary="physical button state">
2237 Describes the physical state of a button that produced the button
2238 event.
2239 </description>
2240 <entry name="released" value="0" summary="the button is not pressed"/>
2241 <entry name="pressed" value="1" summary="the button is pressed"/>
2242 </enum>
2243
2244 <event name="button">
2245 <description summary="pointer button event">
2246 Mouse button click and release notifications.
2247
2248 The location of the click is given by the last motion, warp or
2249 enter event.
2250 The time argument is a timestamp with millisecond
2251 granularity, with an undefined base.
2252
2253 The button is a button code as defined in the Linux kernel's
2254 linux/input-event-codes.h header file, e.g. BTN_LEFT.
2255
2256 Any 16-bit button code value is reserved for future additions to the
2257 kernel's event code list. All other button codes above 0xFFFF are
2258 currently undefined but may be used in future versions of this
2259 protocol.
2260 </description>
2261 <arg name="serial" type="uint" summary="serial number of the button event"/>
2262 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2263 <arg name="button" type="uint" summary="button that produced the event"/>
2264 <arg name="state" type="uint" enum="button_state" summary="physical state of the button"/>
2265 </event>
2266
2267 <enum name="axis">
2268 <description summary="axis types">
2269 Describes the axis types of scroll events.
2270 </description>
2271 <entry name="vertical_scroll" value="0" summary="vertical axis"/>
2272 <entry name="horizontal_scroll" value="1" summary="horizontal axis"/>
2273 </enum>
2274
2275 <event name="axis">
2276 <description summary="axis event">
2277 Scroll and other axis notifications.
2278
2279 For scroll events (vertical and horizontal scroll axes), the
2280 value parameter is the length of a vector along the specified
2281 axis in a coordinate space identical to those of motion events,
2282 representing a relative movement along the specified axis.
2283
2284 For devices that support movements non-parallel to axes multiple
2285 axis events will be emitted.
2286
2287 When applicable, for example for touch pads, the server can
2288 choose to emit scroll events where the motion vector is
2289 equivalent to a motion event vector.
2290
2291 When applicable, a client can transform its content relative to the
2292 scroll distance.
2293 </description>
2294 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2295 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2296 <arg name="value" type="fixed" summary="length of vector in surface-local coordinate space"/>
2297 </event>
2298
2299 <!-- Version 3 additions -->
2300
2301 <request name="release" type="destructor" since="3">
2302 <description summary="release the pointer object">
2303 Using this request a client can tell the server that it is not going to
2304 use the pointer object anymore.
2305
2306 This request destroys the pointer proxy object, so clients must not call
2307 wl_pointer_destroy() after using this request.
2308 </description>
2309 </request>
2310
2311 <!-- Version 5 additions -->
2312
2313 <event name="frame" since="5">
2314 <description summary="end of a pointer event sequence">
2315 Indicates the end of a set of events that logically belong together.
2316 A client is expected to accumulate the data in all events within the
2317 frame before proceeding.
2318
2319 All wl_pointer events before a wl_pointer.frame event belong
2320 logically together. For example, in a diagonal scroll motion the
2321 compositor will send an optional wl_pointer.axis_source event, two
2322 wl_pointer.axis events (horizontal and vertical) and finally a
2323 wl_pointer.frame event. The client may use this information to
2324 calculate a diagonal vector for scrolling.
2325
2326 When multiple wl_pointer.axis events occur within the same frame,
2327 the motion vector is the combined motion of all events.
2328 When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
2329 the same frame, this indicates that axis movement in one axis has
2330 stopped but continues in the other axis.
2331 When multiple wl_pointer.axis_stop events occur within the same
2332 frame, this indicates that these axes stopped in the same instance.
2333
2334 A wl_pointer.frame event is sent for every logical event group,
2335 even if the group only contains a single wl_pointer event.
2336 Specifically, a client may get a sequence: motion, frame, button,
2337 frame, axis, frame, axis_stop, frame.
2338
2339 The wl_pointer.enter and wl_pointer.leave events are logical events
2340 generated by the compositor and not the hardware. These events are
2341 also grouped by a wl_pointer.frame. When a pointer moves from one
2342 surface to another, a compositor should group the
2343 wl_pointer.leave event within the same wl_pointer.frame.
2344 However, a client must not rely on wl_pointer.leave and
2345 wl_pointer.enter being in the same wl_pointer.frame.
2346 Compositor-specific policies may require the wl_pointer.leave and
2347 wl_pointer.enter event being split across multiple wl_pointer.frame
2348 groups.
2349 </description>
2350 </event>
2351
2352 <enum name="axis_source">
2353 <description summary="axis source types">
2354 Describes the source types for axis events. This indicates to the
2355 client how an axis event was physically generated; a client may
2356 adjust the user interface accordingly. For example, scroll events
2357 from a "finger" source may be in a smooth coordinate space with
2358 kinetic scrolling whereas a "wheel" source may be in discrete steps
2359 of a number of lines.
2360
2361 The "continuous" axis source is a device generating events in a
2362 continuous coordinate space, but using something other than a
2363 finger. One example for this source is button-based scrolling where
2364 the vertical motion of a device is converted to scroll events while
2365 a button is held down.
2366
2367 The "wheel tilt" axis source indicates that the actual device is a
2368 wheel but the scroll event is not caused by a rotation but a
2369 (usually sideways) tilt of the wheel.
2370 </description>
2371 <entry name="wheel" value="0" summary="a physical wheel rotation" />
2372 <entry name="finger" value="1" summary="finger on a touch surface" />
2373 <entry name="continuous" value="2" summary="continuous coordinate space"/>
2374 <entry name="wheel_tilt" value="3" summary="a physical wheel tilt" since="6"/>
2375 </enum>
2376
2377 <event name="axis_source" since="5">
2378 <description summary="axis source event">
2379 Source information for scroll and other axes.
2380
2381 This event does not occur on its own. It is sent before a
2382 wl_pointer.frame event and carries the source information for
2383 all events within that frame.
2384
2385 The source specifies how this event was generated. If the source is
2386 wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
2387 sent when the user lifts the finger off the device.
2388
2389 If the source is wl_pointer.axis_source.wheel,
2390 wl_pointer.axis_source.wheel_tilt or
2391 wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
2392 or may not be sent. Whether a compositor sends an axis_stop event
2393 for these sources is hardware-specific and implementation-dependent;
2394 clients must not rely on receiving an axis_stop event for these
2395 scroll sources and should treat scroll sequences from these scroll
2396 sources as unterminated by default.
2397
2398 This event is optional. If the source is unknown for a particular
2399 axis event sequence, no event is sent.
2400 Only one wl_pointer.axis_source event is permitted per frame.
2401
2402 The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2403 not guaranteed.
2404 </description>
2405 <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
2406 </event>
2407
2408 <event name="axis_stop" since="5">
2409 <description summary="axis stop event">
2410 Stop notification for scroll and other axes.
2411
2412 For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
2413 is sent to notify a client that the axis sequence has terminated.
2414 This enables the client to implement kinetic scrolling.
2415 See the wl_pointer.axis_source documentation for information on when
2416 this event may be generated.
2417
2418 Any wl_pointer.axis events with the same axis_source after this
2419 event should be considered as the start of a new axis motion.
2420
2421 The timestamp is to be interpreted identical to the timestamp in the
2422 wl_pointer.axis event. The timestamp value may be the same as a
2423 preceding wl_pointer.axis event.
2424 </description>
2425 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2426 <arg name="axis" type="uint" enum="axis" summary="the axis stopped with this event"/>
2427 </event>
2428
2429 <event name="axis_discrete" since="5" deprecated-since="8">
2430 <description summary="axis click event">
2431 Discrete step information for scroll and other axes.
2432
2433 This event carries the axis value of the wl_pointer.axis event in
2434 discrete steps (e.g. mouse wheel clicks).
2435
2436 This event is deprecated with wl_pointer version 8 - this event is not
2437 sent to clients supporting version 8 or later.
2438
2439 This event does not occur on its own, it is coupled with a
2440 wl_pointer.axis event that represents this axis value on a
2441 continuous scale. The protocol guarantees that each axis_discrete
2442 event is always followed by exactly one axis event with the same
2443 axis number within the same wl_pointer.frame. Note that the protocol
2444 allows for other events to occur between the axis_discrete and
2445 its coupled axis event, including other axis_discrete or axis
2446 events. A wl_pointer.frame must not contain more than one axis_discrete
2447 event per axis type.
2448
2449 This event is optional; continuous scrolling devices
2450 like two-finger scrolling on touchpads do not have discrete
2451 steps and do not generate this event.
2452
2453 The discrete value carries the directional information. e.g. a value
2454 of -2 is two steps towards the negative direction of this axis.
2455
2456 The axis number is identical to the axis number in the associated
2457 axis event.
2458
2459 The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2460 not guaranteed.
2461 </description>
2462 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2463 <arg name="discrete" type="int" summary="number of steps"/>
2464 </event>
2465
2466 <event name="axis_value120" since="8">
2467 <description summary="axis high-resolution scroll event">
2468 Discrete high-resolution scroll information.
2469
2470 This event carries high-resolution wheel scroll information,
2471 with each multiple of 120 representing one logical scroll step
2472 (a wheel detent). For example, an axis_value120 of 30 is one quarter of
2473 a logical scroll step in the positive direction, a value120 of
2474 -240 are two logical scroll steps in the negative direction within the
2475 same hardware event.
2476 Clients that rely on discrete scrolling should accumulate the
2477 value120 to multiples of 120 before processing the event.
2478
2479 The value120 must not be zero.
2480
2481 This event replaces the wl_pointer.axis_discrete event in clients
2482 supporting wl_pointer version 8 or later.
2483
2484 Where a wl_pointer.axis_source event occurs in the same
2485 wl_pointer.frame, the axis source applies to this event.
2486
2487 The order of wl_pointer.axis_value120 and wl_pointer.axis_source is
2488 not guaranteed.
2489 </description>
2490 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2491 <arg name="value120" type="int" summary="scroll distance as fraction of 120"/>
2492 </event>
2493
2494 <!-- Version 9 additions -->
2495
2496 <enum name="axis_relative_direction">
2497 <description summary="axis relative direction">
2498 This specifies the direction of the physical motion that caused a
2499 wl_pointer.axis event, relative to the wl_pointer.axis direction.
2500 </description>
2501 <entry name="identical" value="0"
2502 summary="physical motion matches axis direction"/>
2503 <entry name="inverted" value="1"
2504 summary="physical motion is the inverse of the axis direction"/>
2505 </enum>
2506
2507 <event name="axis_relative_direction" since="9">
2508 <description summary="axis relative physical direction event">
2509 Relative directional information of the entity causing the axis
2510 motion.
2511
2512 For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
2513 event specifies the movement direction of the entity causing the
2514 wl_pointer.axis event. For example:
2515 - if a user's fingers on a touchpad move down and this
2516 causes a wl_pointer.axis vertical_scroll down event, the physical
2517 direction is 'identical'
2518 - if a user's fingers on a touchpad move down and this causes a
2519 wl_pointer.axis vertical_scroll up scroll up event ('natural
2520 scrolling'), the physical direction is 'inverted'.
2521
2522 A client may use this information to adjust scroll motion of
2523 components. Specifically, enabling natural scrolling causes the
2524 content to change direction compared to traditional scrolling.
2525 Some widgets like volume control sliders should usually match the
2526 physical direction regardless of whether natural scrolling is
2527 active. This event enables clients to match the scroll direction of
2528 a widget to the physical direction.
2529
2530 This event does not occur on its own, it is coupled with a
2531 wl_pointer.axis event that represents this axis value.
2532 The protocol guarantees that each axis_relative_direction event is
2533 always followed by exactly one axis event with the same
2534 axis number within the same wl_pointer.frame. Note that the protocol
2535 allows for other events to occur between the axis_relative_direction
2536 and its coupled axis event.
2537
2538 The axis number is identical to the axis number in the associated
2539 axis event.
2540
2541 The order of wl_pointer.axis_relative_direction,
2542 wl_pointer.axis_discrete and wl_pointer.axis_source is not
2543 guaranteed.
2544 </description>
2545 <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2546 <arg name="direction" type="uint" enum="axis_relative_direction"
2547 summary="physical direction relative to axis motion"/>
2548 </event>
2549
2550 <!-- Version 11 additions -->
2551
2552 <event name="warp" since="11">
2553 <description summary="pointer warp event">
2554 Notification of pointer location change within a surface.
2555
2556 This location change is not due to events on the input device,
2557 but because either the surface under the pointer was moved and
2558 thus the relative position of the pointer changed, or because
2559 the compositor changed the pointer position in response to an
2560 event like pointer confinement being exited.
2561
2562 The arguments surface_x and surface_y are the location relative to
2563 the focused surface.
2564
2565 This event must not occur in the same wl_pointer.frame as a
2566 wl_pointer.enter or wl_pointer.motion event.
2567 </description>
2568 <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2569 <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2570 </event>
2571 </interface>
2572
2573 <interface name="wl_keyboard" version="11">
2574 <description summary="keyboard input device">
2575 The wl_keyboard interface represents one or more keyboards
2576 associated with a seat.
2577
2578 Each wl_keyboard has the following logical state:
2579
2580 - an active surface (possibly null),
2581 - the keys currently logically down,
2582 - the active modifiers,
2583 - the active group.
2584
2585 By default, the active surface is null, the keys currently logically down
2586 are empty, the active modifiers and the active group are 0.
2587 </description>
2588
2589 <enum name="keymap_format">
2590 <description summary="keyboard mapping format">
2591 This specifies the format of the keymap provided to the
2592 client with the wl_keyboard.keymap event.
2593 </description>
2594 <entry name="no_keymap" value="0"
2595 summary="no keymap; client must understand how to interpret the raw keycode"/>
2596 <entry name="xkb_v1" value="1"
2597 summary="libxkbcommon compatible, null-terminated string; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
2598 </enum>
2599
2600 <event name="keymap">
2601 <description summary="keyboard mapping">
2602 This event provides a file descriptor to the client which can be
2603 memory-mapped in read-only mode to provide a keyboard mapping
2604 description.
2605
2606 From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
2607 the recipient, as MAP_SHARED may fail.
2608 </description>
2609 <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
2610 <arg name="fd" type="fd" summary="keymap file descriptor"/>
2611 <arg name="size" type="uint" summary="keymap size, in bytes"/>
2612 </event>
2613
2614 <event name="enter">
2615 <description summary="enter event">
2616 Notification that this seat's keyboard focus is on a certain
2617 surface.
2618
2619 The compositor must send the wl_keyboard.modifiers event after this
2620 event.
2621
2622 In the wl_keyboard logical state, this event sets the active surface to
2623 the surface argument and the keys currently logically down to the keys
2624 in the keys argument. The compositor must not send this event if the
2625 wl_keyboard already had an active surface immediately before this event.
2626
2627 Clients should not use the list of pressed keys to emulate key-press
2628 events. The order of keys in the list is unspecified.
2629 </description>
2630 <arg name="serial" type="uint" summary="serial number of the enter event"/>
2631 <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
2632 <arg name="keys" type="array" summary="the keys currently logically down"/>
2633 </event>
2634
2635 <event name="leave">
2636 <description summary="leave event">
2637 Notification that this seat's keyboard focus is no longer on
2638 a certain surface.
2639
2640 The leave notification is sent before the enter notification
2641 for the new focus.
2642
2643 In the wl_keyboard logical state, this event resets all values to their
2644 defaults. The compositor must not send this event if the active surface
2645 of the wl_keyboard was not equal to the surface argument immediately
2646 before this event.
2647 </description>
2648 <arg name="serial" type="uint" summary="serial number of the leave event"/>
2649 <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
2650 </event>
2651
2652 <enum name="key_state">
2653 <description summary="physical key state">
2654 Describes the physical state of a key that produced the key event.
2655
2656 Since version 10, the key can be in a "repeated" pseudo-state which
2657 means the same as "pressed", but is used to signal repetition in the
2658 key event.
2659
2660 The key may only enter the repeated state after entering the pressed
2661 state and before entering the released state. This event may be
2662 generated multiple times while the key is down.
2663 </description>
2664 <entry name="released" value="0" summary="key is not pressed"/>
2665 <entry name="pressed" value="1" summary="key is pressed"/>
2666 <entry name="repeated" value="2" summary="key was repeated" since="10"/>
2667 </enum>
2668
2669 <event name="key">
2670 <description summary="key event">
2671 A key was pressed or released.
2672 The time argument is a timestamp with millisecond
2673 granularity, with an undefined base.
2674
2675 The key is a platform-specific key code that can be interpreted
2676 by feeding it to the keyboard mapping (see the keymap event).
2677
2678 If this event produces a change in modifiers, then the resulting
2679 wl_keyboard.modifiers event must be sent after this event.
2680
2681 In the wl_keyboard logical state, this event adds the key to the keys
2682 currently logically down (if the state argument is pressed) or removes
2683 the key from the keys currently logically down (if the state argument is
2684 released). The compositor must not send this event if the wl_keyboard
2685 did not have an active surface immediately before this event. The
2686 compositor must not send this event if state is pressed (resp. released)
2687 and the key was already logically down (resp. was not logically down)
2688 immediately before this event.
2689
2690 Since version 10, compositors may send key events with the "repeated"
2691 key state when a wl_keyboard.repeat_info event with a rate argument of
2692 0 has been received. This allows the compositor to take over the
2693 responsibility of key repetition.
2694 </description>
2695 <arg name="serial" type="uint" summary="serial number of the key event"/>
2696 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2697 <arg name="key" type="uint" summary="key that produced the event"/>
2698 <arg name="state" type="uint" enum="key_state" summary="physical state of the key"/>
2699 </event>
2700
2701 <event name="modifiers">
2702 <description summary="modifier and group state">
2703 Notifies clients that the modifier and/or group state has
2704 changed, and it should update its local state.
2705
2706 The compositor may send this event without a surface of the client
2707 having keyboard focus, for example to tie modifier information to
2708 pointer focus instead. If a modifier event with pressed modifiers is sent
2709 without a prior enter event, the client can assume the modifier state is
2710 valid until it receives the next wl_keyboard.modifiers event. In order to
2711 reset the modifier state again, the compositor can send a
2712 wl_keyboard.modifiers event with no pressed modifiers.
2713
2714 In the wl_keyboard logical state, this event updates the modifiers and
2715 group.
2716 </description>
2717 <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
2718 <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
2719 <arg name="mods_latched" type="uint" summary="latched modifiers"/>
2720 <arg name="mods_locked" type="uint" summary="locked modifiers"/>
2721 <arg name="group" type="uint" summary="keyboard layout"/>
2722 </event>
2723
2724 <!-- Version 3 additions -->
2725
2726 <request name="release" type="destructor" since="3">
2727 <description summary="release the keyboard object"/>
2728 </request>
2729
2730 <!-- Version 4 additions -->
2731
2732 <event name="repeat_info" since="4">
2733 <description summary="repeat rate and delay">
2734 Informs the client about the keyboard's repeat rate and delay.
2735
2736 This event is sent as soon as the wl_keyboard object has been created,
2737 and is guaranteed to be received by the client before any key press
2738 event.
2739
2740 Negative values for either rate or delay are illegal. A rate of zero
2741 will disable any repeating (regardless of the value of delay).
2742
2743 This event can be sent later on as well with a new value if necessary,
2744 so clients should continue listening for the event past the creation
2745 of wl_keyboard.
2746 </description>
2747 <arg name="rate" type="int"
2748 summary="the rate of repeating keys in characters per second"/>
2749 <arg name="delay" type="int"
2750 summary="delay in milliseconds since key down until repeating starts"/>
2751 </event>
2752 </interface>
2753
2754 <interface name="wl_touch" version="11">
2755 <description summary="touchscreen input device">
2756 The wl_touch interface represents a touchscreen
2757 associated with a seat.
2758
2759 Touch interactions can consist of one or more contacts.
2760 For each contact, a series of events is generated, starting
2761 with a down event, followed by zero or more motion events,
2762 and ending with an up event. Events relating to the same
2763 contact point can be identified by the ID of the sequence.
2764 </description>
2765
2766 <event name="down">
2767 <description summary="touch down event and beginning of a touch sequence">
2768 A new touch point has appeared on the surface. This touch point is
2769 assigned a unique ID. Future events from this touch point reference
2770 this ID. The ID ceases to be valid after a touch up event and may be
2771 reused in the future.
2772 </description>
2773 <arg name="serial" type="uint" summary="serial number of the touch down event"/>
2774 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2775 <arg name="surface" type="object" interface="wl_surface" summary="surface touched"/>
2776 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2777 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2778 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2779 </event>
2780
2781 <event name="up">
2782 <description summary="end of a touch event sequence">
2783 The touch point has disappeared. No further events will be sent for
2784 this touch point and the touch point's ID is released and may be
2785 reused in a future touch down event.
2786 </description>
2787 <arg name="serial" type="uint" summary="serial number of the touch up event"/>
2788 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2789 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2790 </event>
2791
2792 <event name="motion">
2793 <description summary="update of touch point coordinates">
2794 A touch point has changed coordinates.
2795 </description>
2796 <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2797 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2798 <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2799 <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2800 </event>
2801
2802 <event name="frame">
2803 <description summary="end of touch frame event">
2804 Indicates the end of a set of events that logically belong together.
2805 A client is expected to accumulate the data in all events within the
2806 frame before proceeding.
2807
2808 A wl_touch.frame terminates at least one event but otherwise no
2809 guarantee is provided about the set of events within a frame. A client
2810 must assume that any state not updated in a frame is unchanged from the
2811 previously known state.
2812 </description>
2813 </event>
2814
2815 <event name="cancel">
2816 <description summary="touch session cancelled">
2817 Sent if the compositor decides the touch stream is a global
2818 gesture. No further events are sent to the clients from that
2819 particular gesture. Touch cancellation applies to all touch points
2820 currently active on this client's surface. The client is
2821 responsible for finalizing the touch points, future touch points on
2822 this surface may reuse the touch point ID.
2823
2824 No frame event is required after the cancel event.
2825 </description>
2826 </event>
2827
2828 <!-- Version 3 additions -->
2829
2830 <request name="release" type="destructor" since="3">
2831 <description summary="release the touch object"/>
2832 </request>
2833
2834 <!-- Version 6 additions -->
2835
2836 <event name="shape" since="6">
2837 <description summary="update shape of touch point">
2838 Sent when a touchpoint has changed its shape.
2839
2840 This event does not occur on its own. It is sent before a
2841 wl_touch.frame event and carries the new shape information for
2842 any previously reported, or new touch points of that frame.
2843
2844 Other events describing the touch point such as wl_touch.down,
2845 wl_touch.motion or wl_touch.orientation may be sent within the
2846 same wl_touch.frame. A client should treat these events as a single
2847 logical touch point update. The order of wl_touch.shape,
2848 wl_touch.orientation and wl_touch.motion is not guaranteed.
2849 A wl_touch.down event is guaranteed to occur before the first
2850 wl_touch.shape event for this touch ID but both events may occur within
2851 the same wl_touch.frame.
2852
2853 A touchpoint shape is approximated by an ellipse through the major and
2854 minor axis length. The major axis length describes the longer diameter
2855 of the ellipse, while the minor axis length describes the shorter
2856 diameter. Major and minor are orthogonal and both are specified in
2857 surface-local coordinates. The center of the ellipse is always at the
2858 touchpoint location as reported by wl_touch.down or wl_touch.motion.
2859
2860 This event is only sent by the compositor if the touch device supports
2861 shape reports. The client has to make reasonable assumptions about the
2862 shape if it did not receive this event.
2863 </description>
2864 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2865 <arg name="major" type="fixed" summary="length of the major axis in surface-local coordinates"/>
2866 <arg name="minor" type="fixed" summary="length of the minor axis in surface-local coordinates"/>
2867 </event>
2868
2869 <event name="orientation" since="6">
2870 <description summary="update orientation of touch point">
2871 Sent when a touchpoint has changed its orientation.
2872
2873 This event does not occur on its own. It is sent before a
2874 wl_touch.frame event and carries the new shape information for
2875 any previously reported, or new touch points of that frame.
2876
2877 Other events describing the touch point such as wl_touch.down,
2878 wl_touch.motion or wl_touch.shape may be sent within the
2879 same wl_touch.frame. A client should treat these events as a single
2880 logical touch point update. The order of wl_touch.shape,
2881 wl_touch.orientation and wl_touch.motion is not guaranteed.
2882 A wl_touch.down event is guaranteed to occur before the first
2883 wl_touch.orientation event for this touch ID but both events may occur
2884 within the same wl_touch.frame.
2885
2886 The orientation describes the clockwise angle of a touchpoint's major
2887 axis to the positive surface y-axis and is normalized to the -180 to
2888 +180 degree range. The granularity of orientation depends on the touch
2889 device, some devices only support binary rotation values between 0 and
2890 90 degrees.
2891
2892 This event is only sent by the compositor if the touch device supports
2893 orientation reports.
2894 </description>
2895 <arg name="id" type="int" summary="the unique ID of this touch point"/>
2896 <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
2897 </event>
2898 </interface>
2899
2900 <interface name="wl_output" version="4">
2901 <description summary="compositor output region">
2902 An output describes part of the compositor geometry. The
2903 compositor works in the 'compositor coordinate system' and an
2904 output corresponds to a rectangular area in that space that is
2905 actually visible. This typically corresponds to a monitor that
2906 displays part of the compositor space. This object is published
2907 as global during start up, or when a monitor is hotplugged.
2908 </description>
2909
2910 <enum name="subpixel">
2911 <description summary="subpixel geometry information">
2912 This enumeration describes how the physical
2913 pixels on an output are laid out.
2914 </description>
2915 <entry name="unknown" value="0" summary="unknown geometry"/>
2916 <entry name="none" value="1" summary="no geometry"/>
2917 <entry name="horizontal_rgb" value="2" summary="horizontal RGB"/>
2918 <entry name="horizontal_bgr" value="3" summary="horizontal BGR"/>
2919 <entry name="vertical_rgb" value="4" summary="vertical RGB"/>
2920 <entry name="vertical_bgr" value="5" summary="vertical BGR"/>
2921 </enum>
2922
2923 <enum name="transform">
2924 <description summary="transformation applied to buffer contents">
2925 This describes transformations that clients and compositors apply to
2926 buffer contents.
2927
2928 The flipped values correspond to an initial flip around a
2929 vertical axis followed by rotation.
2930
2931 The purpose is mainly to allow clients to render accordingly and
2932 tell the compositor, so that for fullscreen surfaces, the
2933 compositor will still be able to scan out directly from client
2934 surfaces.
2935 </description>
2936 <entry name="normal" value="0" summary="no transform"/>
2937 <entry name="90" value="1" summary="90 degrees counter-clockwise"/>
2938 <entry name="180" value="2" summary="180 degrees counter-clockwise"/>
2939 <entry name="270" value="3" summary="270 degrees counter-clockwise"/>
2940 <entry name="flipped" value="4" summary="180 degree flip around a vertical axis"/>
2941 <entry name="flipped_90" value="5" summary="flip and rotate 90 degrees counter-clockwise"/>
2942 <entry name="flipped_180" value="6" summary="flip and rotate 180 degrees counter-clockwise"/>
2943 <entry name="flipped_270" value="7" summary="flip and rotate 270 degrees counter-clockwise"/>
2944 </enum>
2945
2946 <event name="geometry">
2947 <description summary="properties of the output">
2948 The geometry event describes geometric properties of the output.
2949 The event is sent when binding to the output object and whenever
2950 any of the properties change.
2951
2952 The physical size can be set to zero if it doesn't make sense for this
2953 output (e.g. for projectors or virtual outputs).
2954
2955 The geometry event will be followed by a done event (starting from
2956 version 2).
2957
2958 Clients should use wl_surface.preferred_buffer_transform instead of the
2959 transform advertised by this event to find the preferred buffer
2960 transform to use for a surface.
2961
2962 Note: wl_output only advertises partial information about the output
2963 position and identification. Some compositors, for instance those not
2964 implementing a desktop-style output layout or those exposing virtual
2965 outputs, might fake this information. Instead of using x and y, clients
2966 should use xdg_output.logical_position. Instead of using make and model,
2967 clients should use name and description.
2968 </description>
2969 <arg name="x" type="int"
2970 summary="x position within the global compositor space"/>
2971 <arg name="y" type="int"
2972 summary="y position within the global compositor space"/>
2973 <arg name="physical_width" type="int"
2974 summary="width in millimeters of the output"/>
2975 <arg name="physical_height" type="int"
2976 summary="height in millimeters of the output"/>
2977 <arg name="subpixel" type="int" enum="subpixel"
2978 summary="subpixel orientation of the output"/>
2979 <arg name="make" type="string"
2980 summary="textual description of the manufacturer"/>
2981 <arg name="model" type="string"
2982 summary="textual description of the model"/>
2983 <arg name="transform" type="int" enum="transform"
2984 summary="additional transformation applied to buffer contents during presentation"/>
2985 </event>
2986
2987 <enum name="mode" bitfield="true">
2988 <description summary="mode information">
2989 These flags describe properties of an output mode.
2990 They are used in the flags bitfield of the mode event.
2991 </description>
2992 <entry name="current" value="0x1"
2993 summary="indicates this is the current mode"/>
2994 <entry name="preferred" value="0x2"
2995 summary="indicates this is the preferred mode"/>
2996 </enum>
2997
2998 <event name="mode">
2999 <description summary="advertise available modes for the output">
3000 The mode event describes an available mode for the output.
3001
3002 The event is sent when binding to the output object and there
3003 will always be one mode, the current mode. The event is sent
3004 again if an output changes mode, for the mode that is now
3005 current. In other words, the current mode is always the last
3006 mode that was received with the current flag set.
3007
3008 Non-current modes are deprecated. A compositor can decide to only
3009 advertise the current mode and never send other modes. Clients
3010 should not rely on non-current modes.
3011
3012 The size of a mode is given in physical hardware units of
3013 the output device. This is not necessarily the same as
3014 the output size in the global compositor space. For instance,
3015 the output may be scaled, as described in wl_output.scale,
3016 or transformed, as described in wl_output.transform. Clients
3017 willing to retrieve the output size in the global compositor
3018 space should use xdg_output.logical_size instead.
3019
3020 The vertical refresh rate can be set to zero if it doesn't make
3021 sense for this output (e.g. for virtual outputs).
3022
3023 The mode event will be followed by a done event (starting from
3024 version 2).
3025
3026 Clients should not use the refresh rate to schedule frames. Instead,
3027 they should use the wl_surface.frame event or the presentation-time
3028 protocol.
3029
3030 Note: this information is not always meaningful for all outputs. Some
3031 compositors, such as those exposing virtual outputs, might fake the
3032 refresh rate or the size.
3033 </description>
3034 <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
3035 <arg name="width" type="int" summary="width of the mode in hardware units"/>
3036 <arg name="height" type="int" summary="height of the mode in hardware units"/>
3037 <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
3038 </event>
3039
3040 <!-- Version 2 additions -->
3041
3042 <event name="done" since="2">
3043 <description summary="sent all information about output">
3044 This event is sent after all other properties have been
3045 sent after binding to the output object and after any
3046 other property changes done after that. This allows
3047 changes to the output properties to be seen as
3048 atomic, even if they happen via multiple events.
3049 </description>
3050 </event>
3051
3052 <event name="scale" since="2">
3053 <description summary="output scaling properties">
3054 This event contains scaling geometry information
3055 that is not in the geometry event. It may be sent after
3056 binding the output object or if the output scale changes
3057 later. The compositor will emit a non-zero, positive
3058 value for scale. If it is not sent, the client should
3059 assume a scale of 1.
3060
3061 A scale larger than 1 means that the compositor will
3062 automatically scale surface buffers by this amount
3063 when rendering. This is used for very high resolution
3064 displays where applications rendering at the native
3065 resolution would be too small to be legible.
3066
3067 Clients should use wl_surface.preferred_buffer_scale
3068 instead of this event to find the preferred buffer
3069 scale to use for a surface.
3070
3071 The scale event will be followed by a done event.
3072 </description>
3073 <arg name="factor" type="int" summary="scaling factor of output"/>
3074 </event>
3075
3076 <!-- Version 3 additions -->
3077
3078 <request name="release" type="destructor" since="3">
3079 <description summary="release the output object">
3080 Using this request a client can tell the server that it is not going to
3081 use the output object anymore.
3082 </description>
3083 </request>
3084
3085 <!-- Version 4 additions -->
3086
3087 <event name="name" since="4">
3088 <description summary="name of this output">
3089 Many compositors will assign user-friendly names to their outputs, show
3090 them to the user, allow the user to refer to an output, etc. The client
3091 may wish to know this name as well to offer the user similar behaviors.
3092
3093 The name is a UTF-8 string with no convention defined for its contents.
3094 Each name is unique among all wl_output globals. The name is only
3095 guaranteed to be unique for the compositor instance.
3096
3097 The same output name is used for all clients for a given wl_output
3098 global. Thus, the name can be shared across processes to refer to a
3099 specific wl_output global.
3100
3101 The name is not guaranteed to be persistent across sessions, thus cannot
3102 be used to reliably identify an output in e.g. configuration files.
3103
3104 Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
3105 not assume that the name is a reflection of an underlying DRM connector,
3106 X11 connection, etc.
3107
3108 The name event is sent after binding the output object. This event is
3109 only sent once per output object, and the name does not change over the
3110 lifetime of the wl_output global.
3111
3112 Compositors may re-use the same output name if the wl_output global is
3113 destroyed and re-created later. Compositors should avoid re-using the
3114 same name if possible.
3115
3116 The name event will be followed by a done event.
3117 </description>
3118 <arg name="name" type="string" summary="output name"/>
3119 </event>
3120
3121 <event name="description" since="4">
3122 <description summary="human-readable description of this output">
3123 Many compositors can produce human-readable descriptions of their
3124 outputs. The client may wish to know this description as well, e.g. for
3125 output selection purposes.
3126
3127 The description is a UTF-8 string with no convention defined for its
3128 contents. The description is not guaranteed to be unique among all
3129 wl_output globals. Examples might include 'Foocorp 11" Display' or
3130 'Virtual X11 output via :1'.
3131
3132 The description event is sent after binding the output object and
3133 whenever the description changes. The description is optional, and may
3134 not be sent at all.
3135
3136 The description event will be followed by a done event.
3137 </description>
3138 <arg name="description" type="string" summary="output description"/>
3139 </event>
3140 </interface>
3141
3142 <interface name="wl_region" version="7">
3143 <description summary="region interface">
3144 A region object describes an area.
3145
3146 Region objects are used to describe the opaque and input
3147 regions of a surface.
3148 </description>
3149
3150 <request name="destroy" type="destructor">
3151 <description summary="destroy region">
3152 Destroy the region. This will invalidate the object ID.
3153 </description>
3154 </request>
3155
3156 <request name="add">
3157 <description summary="add rectangle to region">
3158 Add the specified rectangle to the region.
3159 </description>
3160 <arg name="x" type="int" summary="region-local x coordinate"/>
3161 <arg name="y" type="int" summary="region-local y coordinate"/>
3162 <arg name="width" type="int" summary="rectangle width"/>
3163 <arg name="height" type="int" summary="rectangle height"/>
3164 </request>
3165
3166 <request name="subtract">
3167 <description summary="subtract rectangle from region">
3168 Subtract the specified rectangle from the region.
3169 </description>
3170 <arg name="x" type="int" summary="region-local x coordinate"/>
3171 <arg name="y" type="int" summary="region-local y coordinate"/>
3172 <arg name="width" type="int" summary="rectangle width"/>
3173 <arg name="height" type="int" summary="rectangle height"/>
3174 </request>
3175 </interface>
3176
3177 <interface name="wl_subcompositor" version="1">
3178 <description summary="sub-surface compositing">
3179 The global interface exposing sub-surface compositing capabilities.
3180 A wl_surface, that has sub-surfaces associated, is called the
3181 parent surface. Sub-surfaces can be arbitrarily nested and create
3182 a tree of sub-surfaces.
3183
3184 The root surface in a tree of sub-surfaces is the main
3185 surface. The main surface cannot be a sub-surface, because
3186 sub-surfaces must always have a parent.
3187
3188 A main surface with its sub-surfaces forms a (compound) window.
3189 For window management purposes, this set of wl_surface objects is
3190 to be considered as a single window, and it should also behave as
3191 such.
3192
3193 The aim of sub-surfaces is to offload some of the compositing work
3194 within a window from clients to the compositor. A prime example is
3195 a video player with decorations and video in separate wl_surface
3196 objects. This should allow the compositor to pass YUV video buffer
3197 processing to dedicated overlay hardware when possible.
3198 </description>
3199
3200 <request name="destroy" type="destructor">
3201 <description summary="unbind from the subcompositor interface">
3202 Informs the server that the client will not be using this
3203 protocol object anymore. This does not affect any other
3204 objects, wl_subsurface objects included.
3205 </description>
3206 </request>
3207
3208 <enum name="error">
3209 <entry name="bad_surface" value="0"
3210 summary="the to-be sub-surface is invalid"/>
3211 <entry name="bad_parent" value="1"
3212 summary="the to-be sub-surface parent is invalid"/>
3213 </enum>
3214
3215 <request name="get_subsurface">
3216 <description summary="give a surface the role sub-surface">
3217 Create a sub-surface interface for the given surface, and
3218 associate it with the given parent surface. This turns a
3219 plain wl_surface into a sub-surface.
3220
3221 The to-be sub-surface must not already have another role, and it
3222 must not have an existing wl_subsurface object. Otherwise the
3223 bad_surface protocol error is raised.
3224
3225 Adding sub-surfaces to a parent is a double-buffered operation on the
3226 parent (see wl_surface.commit). The effect of adding a sub-surface
3227 becomes visible on the next time the state of the parent surface is
3228 applied.
3229
3230 The parent surface must not be one of the child surface's descendants,
3231 and the parent must be different from the child surface, otherwise the
3232 bad_parent protocol error is raised.
3233
3234 This request modifies the behaviour of wl_surface.commit request on
3235 the sub-surface, see the documentation on wl_subsurface interface.
3236 </description>
3237 <arg name="id" type="new_id" interface="wl_subsurface"
3238 summary="the new sub-surface object ID"/>
3239 <arg name="surface" type="object" interface="wl_surface"
3240 summary="the surface to be turned into a sub-surface"/>
3241 <arg name="parent" type="object" interface="wl_surface"
3242 summary="the parent surface"/>
3243 </request>
3244 </interface>
3245
3246 <interface name="wl_subsurface" version="1">
3247 <description summary="sub-surface interface to a wl_surface">
3248 An additional interface to a wl_surface object, which has been
3249 made a sub-surface. A sub-surface has one parent surface. A
3250 sub-surface's size and position are not limited to that of the parent.
3251 Particularly, a sub-surface is not automatically clipped to its
3252 parent's area.
3253
3254 A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
3255 and the parent surface is mapped. The order of which one happens
3256 first is irrelevant. A sub-surface is hidden if the parent becomes
3257 hidden, or if a NULL wl_buffer is applied. These rules apply
3258 recursively through the tree of surfaces.
3259
3260 A sub-surface can be in one of two modes. The possible modes are
3261 synchronized and desynchronized, see methods wl_subsurface.set_sync and
3262 wl_subsurface.set_desync.
3263
3264 The main surface can be thought to be always in desynchronized mode,
3265 since it does not have a parent in the sub-surfaces sense.
3266
3267 Even if a sub-surface is in desynchronized mode, it will behave as
3268 in synchronized mode, if its parent surface behaves as in
3269 synchronized mode. This rule is applied recursively throughout the
3270 tree of surfaces. This means, that one can set a sub-surface into
3271 synchronized mode, and then assume that all its child and grand-child
3272 sub-surfaces are synchronized, too, without explicitly setting them.
3273
3274 If a surface behaves as in synchronized mode, it is effectively
3275 synchronized, otherwise it is effectively desynchronized.
3276
3277 A sub-surface is initially in the synchronized mode.
3278
3279 The wl_subsurface interface has requests which modify double-buffered
3280 state of the parent surface (wl_subsurface.set_position, .place_above and
3281 .place_below).
3282
3283 Destroying a sub-surface takes effect immediately. If you need to
3284 synchronize the removal of a sub-surface to the parent surface update,
3285 unmap the sub-surface first by attaching a NULL wl_buffer, update parent,
3286 and then destroy the sub-surface.
3287
3288 If the parent wl_surface object is destroyed, the sub-surface is
3289 unmapped.
3290
3291 A sub-surface never has the keyboard focus of any seat.
3292
3293 The wl_surface.offset request is ignored: clients must use set_position
3294 instead to move the sub-surface.
3295 </description>
3296
3297 <request name="destroy" type="destructor">
3298 <description summary="remove sub-surface interface">
3299 The sub-surface interface is removed from the wl_surface object
3300 that was turned into a sub-surface with a
3301 wl_subcompositor.get_subsurface request. The wl_surface's association
3302 to the parent is deleted. The wl_surface is unmapped immediately.
3303 </description>
3304 </request>
3305
3306 <enum name="error">
3307 <entry name="bad_surface" value="0"
3308 summary="wl_surface is not a sibling or the parent"/>
3309 </enum>
3310
3311 <request name="set_position">
3312 <description summary="reposition the sub-surface">
3313 This sets the position of the sub-surface, relative to the parent
3314 surface.
3315
3316 The sub-surface will be moved so that its origin (top left
3317 corner pixel) will be at the location x, y of the parent surface
3318 coordinate system. The coordinates are not restricted to the parent
3319 surface area. Negative values are allowed.
3320
3321 The initial position is 0, 0.
3322
3323 Position is double-buffered state on the parent surface, see
3324 wl_subsurface and wl_surface.commit for more information.
3325 </description>
3326 <arg name="x" type="int" summary="x coordinate in the parent surface"/>
3327 <arg name="y" type="int" summary="y coordinate in the parent surface"/>
3328 </request>
3329
3330 <request name="place_above">
3331 <description summary="restack the sub-surface">
3332 This sub-surface is taken from the stack, and put back just
3333 above the reference surface, changing the z-order of the sub-surfaces.
3334 The reference surface must be one of the sibling surfaces, or the
3335 parent surface. Using any other surface, including this sub-surface,
3336 will cause a protocol error.
3337
3338 A new sub-surface is initially added as the top-most in the stack
3339 of its siblings and parent.
3340
3341 Z-order is double-buffered state on the parent surface, see
3342 wl_subsurface and wl_surface.commit for more information.
3343 </description>
3344 <arg name="sibling" type="object" interface="wl_surface"
3345 summary="the reference surface"/>
3346 </request>
3347
3348 <request name="place_below">
3349 <description summary="restack the sub-surface">
3350 The sub-surface is placed just below the reference surface.
3351
3352 See wl_subsurface.place_above.
3353 </description>
3354 <arg name="sibling" type="object" interface="wl_surface"
3355 summary="the reference surface"/>
3356 </request>
3357
3358 <request name="set_sync">
3359 <description summary="set sub-surface to synchronized mode">
3360 Change the commit behaviour of the sub-surface to synchronized
3361 mode.
3362
3363 See wl_subsurface and wl_surface.commit for more information.
3364 </description>
3365 </request>
3366
3367 <request name="set_desync">
3368 <description summary="set sub-surface to desynchronized mode">
3369 Change the commit behaviour of the sub-surface to desynchronized
3370 mode.
3371
3372 See wl_subsurface and wl_surface.commit for more information.
3373 </description>
3374 </request>
3375 </interface>
3376
3377 <interface name="wl_fixes" version="2">
3378 <description summary="wayland protocol fixes">
3379 This global fixes problems with other core-protocol interfaces that
3380 cannot be fixed in these interfaces themselves.
3381 </description>
3382
3383 <enum name="error">
3384 <description summary="wl_fixes error values">
3385 These errors can be emitted in response to wl_fixes requests.
3386 </description>
3387 <entry name="invalid_ack_remove" value="0"
3388 summary="unknown global or the global is not removed"/>
3389 </enum>
3390
3391 <request name="destroy" type="destructor">
3392 <description summary="destroys this object"/>
3393 </request>
3394
3395 <request name="destroy_registry">
3396 <description summary="destroy a wl_registry">
3397 This request destroys a wl_registry object.
3398
3399 The client should no longer use the wl_registry after making this
3400 request.
3401
3402 The compositor will emit a wl_display.delete_id event with the object ID
3403 of the registry and will no longer emit any events on the registry. The
3404 client should re-use the object ID once it receives the
3405 wl_display.delete_id event.
3406 </description>
3407 <arg name="registry" type="object" interface="wl_registry"
3408 summary="the registry to destroy"/>
3409 </request>
3410
3411 <request name="ack_global_remove" since="2">
3412 <description summary="acknowledge global removal">
3413 Acknowledge the removal of the specified global.
3414
3415 If no global with the specified name exists or the global is not removed,
3416 the wl_fixes.invalid_ack_remove protocol error will be posted.
3417
3418 Due to the Wayland protocol being asynchronous, the wl_global objects
3419 cannot be destroyed immediately. For example, if a wl_global is removed
3420 and a client attempts to bind that global around same time, it can
3421 result in a protocol error due to an unknown global name in the bind
3422 request.
3423
3424 In order to avoid crashing clients, the compositor should remove the
3425 wl_global once it is guaranteed that no more bind requests will come.
3426
3427 The wl_fixes.ack_global_remove() request is used to signal to the
3428 compositor that the client will not bind the given global anymore. After
3429 all clients acknowledge the removal of the global, the compositor can
3430 safely destroy it.
3431
3432 The client must call the wl_fixes.ack_global_remove() request in
3433 response to a wl_registry.global_remove() event even if it did not bind
3434 the corresponding global.
3435 </description>
3436 <arg name="registry" type="object" interface="wl_registry"
3437 summary="the registry object"/>
3438 <arg name="name" type="uint" summary="unique name of the global"/>
3439 </request>
3440 </interface>
3441
3442</protocol>