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