SDL

1
<?xml version="1.0" encoding="UTF-8"?>
2
<protocol name="wayland">
3

4
  <copyright>
5
    Copyright © 2008-2011 Kristian Høgsberg
6
    Copyright © 2010-2011 Intel Corporation
7
    Copyright © 2012-2013 Collabora, Ltd.
8

9
    Permission is hereby granted, free of charge, to any person
10
    obtaining a copy of this software and associated documentation files
11
    (the "Software"), to deal in the Software without restriction,
12
    including without limitation the rights to use, copy, modify, merge,
13
    publish, distribute, sublicense, and/or sell copies of the Software,
14
    and to permit persons to whom the Software is furnished to do so,
15
    subject to the following conditions:
16

17
    The above copyright notice and this permission notice (including the
18
    next paragraph) shall be included in all copies or substantial
19
    portions of the Software.
20

21
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
22
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
23
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
24
    NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
25
    BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
26
    ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
27
    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
28
    SOFTWARE.
29
  </copyright>
30

31
  <interface name="wl_display" version="1">
32
    <description summary="core global object">
33
      The core global object.  This is a special singleton object.  It
34
      is used for internal Wayland protocol features.
35
    </description>
36

37
    <request name="sync">
38
      <description summary="asynchronous roundtrip">
39
	The sync request asks the server to emit the 'done' event
40
	on the returned wl_callback object.  Since requests are
41
	handled in-order and events are delivered in-order, this can
42
	be used as a barrier to ensure all previous requests and the
43
	resulting events have been handled.
44

45
	The object returned by this request will be destroyed by the
46
	compositor after the callback is fired and as such the client must not
47
	attempt to use it after that point.
48

49
	The callback_data passed in the callback is the event serial.
50
      </description>
51
      <arg name="callback" type="new_id" interface="wl_callback"
52
	   summary="callback object for the sync request"/>
53
    </request>
54

55
    <request name="get_registry">
56
      <description summary="get global registry object">
57
	This request creates a registry object that allows the client
58
	to list and bind the global objects available from the
59
	compositor.
60

61
	It should be noted that the server side resources consumed in
62
	response to a get_registry request can only be released when the
63
	client disconnects, not when the client side proxy is destroyed.
64
	Therefore, clients should invoke get_registry as infrequently as
65
	possible to avoid wasting memory.
66
      </description>
67
      <arg name="registry" type="new_id" interface="wl_registry"
68
	   summary="global registry object"/>
69
    </request>
70

71
    <event name="error">
72
      <description summary="fatal error event">
73
	The error event is sent out when a fatal (non-recoverable)
74
	error has occurred.  The object_id argument is the object
75
	where the error occurred, most often in response to a request
76
	to that object.  The code identifies the error and is defined
77
	by the object interface.  As such, each interface defines its
78
	own set of error codes.  The message is a brief description
79
	of the error, for (debugging) convenience.
80
      </description>
81
      <arg name="object_id" type="object" summary="object where the error occurred"/>
82
      <arg name="code" type="uint" summary="error code"/>
83
      <arg name="message" type="string" summary="error description"/>
84
    </event>
85

86
    <enum name="error">
87
      <description summary="global error values">
88
	These errors are global and can be emitted in response to any
89
	server request.
90
      </description>
91
      <entry name="invalid_object" value="0"
92
	     summary="server couldn't find object"/>
93
      <entry name="invalid_method" value="1"
94
	     summary="method doesn't exist on the specified interface or malformed request"/>
95
      <entry name="no_memory" value="2"
96
	     summary="server is out of memory"/>
97
      <entry name="implementation" value="3"
98
	     summary="implementation error in compositor"/>
99
    </enum>
100

101
    <event name="delete_id">
102
      <description summary="acknowledge object ID deletion">
103
	This event is used internally by the object ID management
104
	logic. When a client deletes an object that it had created,
105
	the server will send this event to acknowledge that it has
106
	seen the delete request. When the client receives this event,
107
	it will know that it can safely reuse the object ID.
108
      </description>
109
      <arg name="id" type="uint" summary="deleted object ID"/>
110
    </event>
111
  </interface>
112

113
  <interface name="wl_registry" version="1">
114
    <description summary="global registry object">
115
      The singleton global registry object.  The server has a number of
116
      global objects that are available to all clients.  These objects
117
      typically represent an actual object in the server (for example,
118
      an input device) or they are singleton objects that provide
119
      extension functionality.
120

121
      When a client creates a registry object, the registry object
122
      will emit a global event for each global currently in the
123
      registry.  Globals come and go as a result of device or
124
      monitor hotplugs, reconfiguration or other events, and the
125
      registry will send out global and global_remove events to
126
      keep the client up to date with the changes.  To mark the end
127
      of the initial burst of events, the client can use the
128
      wl_display.sync request immediately after calling
129
      wl_display.get_registry.
130

131
      A client can bind to a global object by using the bind
132
      request.  This creates a client-side handle that lets the object
133
      emit events to the client and lets the client invoke requests on
134
      the object.
135
    </description>
136

137
    <request name="bind">
138
      <description summary="bind an object to the display">
139
	Binds a new, client-created object to the server using the
140
	specified name as the identifier.
141
      </description>
142
      <arg name="name" type="uint" summary="unique numeric name of the object"/>
143
      <arg name="id" type="new_id" summary="bounded object"/>
144
    </request>
145

146
    <event name="global">
147
      <description summary="announce global object">
148
	Notify the client of global objects.
149

150
	The event notifies the client that a global object with
151
	the given name is now available, and it implements the
152
	given version of the given interface.
153
      </description>
154
      <arg name="name" type="uint" summary="numeric name of the global object"/>
155
      <arg name="interface" type="string" summary="interface implemented by the object"/>
156
      <arg name="version" type="uint" summary="interface version"/>
157
    </event>
158

159
    <event name="global_remove">
160
      <description summary="announce removal of global object">
161
	Notify the client of removed global objects.
162

163
	This event notifies the client that the global identified
164
	by name is no longer available.  If the client bound to
165
	the global using the bind request, the client should now
166
	destroy that object.
167

168
	The object remains valid and requests to the object will be
169
	ignored until the client destroys it, to avoid races between
170
	the global going away and a client sending a request to it.
171
      </description>
172
      <arg name="name" type="uint" summary="numeric name of the global object"/>
173
    </event>
174
  </interface>
175

176
  <interface name="wl_callback" version="1">
177
    <description summary="callback object">
178
      Clients can handle the 'done' event to get notified when
179
      the related request is done.
180

181
      Note, because wl_callback objects are created from multiple independent
182
      factory interfaces, the wl_callback interface is frozen at version 1.
183
    </description>
184

185
    <event name="done" type="destructor">
186
      <description summary="done event">
187
	Notify the client when the related request is done.
188
      </description>
189
      <arg name="callback_data" type="uint" summary="request-specific data for the callback"/>
190
    </event>
191
  </interface>
192

193
  <interface name="wl_compositor" version="6">
194
    <description summary="the compositor singleton">
195
      A compositor.  This object is a singleton global.  The
196
      compositor is in charge of combining the contents of multiple
197
      surfaces into one displayable output.
198
    </description>
199

200
    <request name="create_surface">
201
      <description summary="create new surface">
202
	Ask the compositor to create a new surface.
203
      </description>
204
      <arg name="id" type="new_id" interface="wl_surface" summary="the new surface"/>
205
    </request>
206

207
    <request name="create_region">
208
      <description summary="create new region">
209
	Ask the compositor to create a new region.
210
      </description>
211
      <arg name="id" type="new_id" interface="wl_region" summary="the new region"/>
212
    </request>
213
  </interface>
214

215
  <interface name="wl_shm_pool" version="1">
216
    <description summary="a shared memory pool">
217
      The wl_shm_pool object encapsulates a piece of memory shared
218
      between the compositor and client.  Through the wl_shm_pool
219
      object, the client can allocate shared memory wl_buffer objects.
220
      All objects created through the same pool share the same
221
      underlying mapped memory. Reusing the mapped memory avoids the
222
      setup/teardown overhead and is useful when interactively resizing
223
      a surface or for many small buffers.
224
    </description>
225

226
    <request name="create_buffer">
227
      <description summary="create a buffer from the pool">
228
	Create a wl_buffer object from the pool.
229

230
	The buffer is created offset bytes into the pool and has
231
	width and height as specified.  The stride argument specifies
232
	the number of bytes from the beginning of one row to the beginning
233
	of the next.  The format is the pixel format of the buffer and
234
	must be one of those advertised through the wl_shm.format event.
235

236
	A buffer will keep a reference to the pool it was created from
237
	so it is valid to destroy the pool immediately after creating
238
	a buffer from it.
239
      </description>
240
      <arg name="id" type="new_id" interface="wl_buffer" summary="buffer to create"/>
241
      <arg name="offset" type="int" summary="buffer byte offset within the pool"/>
242
      <arg name="width" type="int" summary="buffer width, in pixels"/>
243
      <arg name="height" type="int" summary="buffer height, in pixels"/>
244
      <arg name="stride" type="int" summary="number of bytes from the beginning of one row to the beginning of the next row"/>
245
      <arg name="format" type="uint" enum="wl_shm.format" summary="buffer pixel format"/>
246
    </request>
247

248
    <request name="destroy" type="destructor">
249
      <description summary="destroy the pool">
250
	Destroy the shared memory pool.
251

252
	The mmapped memory will be released when all
253
	buffers that have been created from this pool
254
	are gone.
255
      </description>
256
    </request>
257

258
    <request name="resize">
259
      <description summary="change the size of the pool mapping">
260
	This request will cause the server to remap the backing memory
261
	for the pool from the file descriptor passed when the pool was
262
	created, but using the new size.  This request can only be
263
	used to make the pool bigger.
264

265
        This request only changes the amount of bytes that are mmapped
266
        by the server and does not touch the file corresponding to the
267
        file descriptor passed at creation time. It is the client's
268
        responsibility to ensure that the file is at least as big as
269
        the new pool size.
270
      </description>
271
      <arg name="size" type="int" summary="new size of the pool, in bytes"/>
272
    </request>
273
  </interface>
274

275
  <interface name="wl_shm" version="1">
276
    <description summary="shared memory support">
277
      A singleton global object that provides support for shared
278
      memory.
279

280
      Clients can create wl_shm_pool objects using the create_pool
281
      request.
282

283
      On binding the wl_shm object one or more format events
284
      are emitted to inform clients about the valid pixel formats
285
      that can be used for buffers.
286
    </description>
287

288
    <enum name="error">
289
      <description summary="wl_shm error values">
290
	These errors can be emitted in response to wl_shm requests.
291
      </description>
292
      <entry name="invalid_format" value="0" summary="buffer format is not known"/>
293
      <entry name="invalid_stride" value="1" summary="invalid size or stride during pool or buffer creation"/>
294
      <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
295
    </enum>
296

297
    <enum name="format">
298
      <description summary="pixel formats">
299
	This describes the memory layout of an individual pixel.
300

301
	All renderers should support argb8888 and xrgb8888 but any other
302
	formats are optional and may not be supported by the particular
303
	renderer in use.
304

305
	The drm format codes match the macros defined in drm_fourcc.h, except
306
	argb8888 and xrgb8888. The formats actually supported by the compositor
307
	will be reported by the format event.
308

309
	For all wl_shm formats and unless specified in another protocol
310
	extension, pre-multiplied alpha is used for pixel values.
311
      </description>
312
      <!-- Note to protocol writers: don't update this list manually, instead
313
	   run the automated script that keeps it in sync with drm_fourcc.h. -->
314
      <entry name="argb8888" value="0" summary="32-bit ARGB format, [31:0] A:R:G:B 8:8:8:8 little endian"/>
315
      <entry name="xrgb8888" value="1" summary="32-bit RGB format, [31:0] x:R:G:B 8:8:8:8 little endian"/>
316
      <entry name="c8" value="0x20203843" summary="8-bit color index format, [7:0] C"/>
317
      <entry name="rgb332" value="0x38424752" summary="8-bit RGB format, [7:0] R:G:B 3:3:2"/>
318
      <entry name="bgr233" value="0x38524742" summary="8-bit BGR format, [7:0] B:G:R 2:3:3"/>
319
      <entry name="xrgb4444" value="0x32315258" summary="16-bit xRGB format, [15:0] x:R:G:B 4:4:4:4 little endian"/>
320
      <entry name="xbgr4444" value="0x32314258" summary="16-bit xBGR format, [15:0] x:B:G:R 4:4:4:4 little endian"/>
321
      <entry name="rgbx4444" value="0x32315852" summary="16-bit RGBx format, [15:0] R:G:B:x 4:4:4:4 little endian"/>
322
      <entry name="bgrx4444" value="0x32315842" summary="16-bit BGRx format, [15:0] B:G:R:x 4:4:4:4 little endian"/>
323
      <entry name="argb4444" value="0x32315241" summary="16-bit ARGB format, [15:0] A:R:G:B 4:4:4:4 little endian"/>
324
      <entry name="abgr4444" value="0x32314241" summary="16-bit ABGR format, [15:0] A:B:G:R 4:4:4:4 little endian"/>
325
      <entry name="rgba4444" value="0x32314152" summary="16-bit RBGA format, [15:0] R:G:B:A 4:4:4:4 little endian"/>
326
      <entry name="bgra4444" value="0x32314142" summary="16-bit BGRA format, [15:0] B:G:R:A 4:4:4:4 little endian"/>
327
      <entry name="xrgb1555" value="0x35315258" summary="16-bit xRGB format, [15:0] x:R:G:B 1:5:5:5 little endian"/>
328
      <entry name="xbgr1555" value="0x35314258" summary="16-bit xBGR 1555 format, [15:0] x:B:G:R 1:5:5:5 little endian"/>
329
      <entry name="rgbx5551" value="0x35315852" summary="16-bit RGBx 5551 format, [15:0] R:G:B:x 5:5:5:1 little endian"/>
330
      <entry name="bgrx5551" value="0x35315842" summary="16-bit BGRx 5551 format, [15:0] B:G:R:x 5:5:5:1 little endian"/>
331
      <entry name="argb1555" value="0x35315241" summary="16-bit ARGB 1555 format, [15:0] A:R:G:B 1:5:5:5 little endian"/>
332
      <entry name="abgr1555" value="0x35314241" summary="16-bit ABGR 1555 format, [15:0] A:B:G:R 1:5:5:5 little endian"/>
333
      <entry name="rgba5551" value="0x35314152" summary="16-bit RGBA 5551 format, [15:0] R:G:B:A 5:5:5:1 little endian"/>
334
      <entry name="bgra5551" value="0x35314142" summary="16-bit BGRA 5551 format, [15:0] B:G:R:A 5:5:5:1 little endian"/>
335
      <entry name="rgb565" value="0x36314752" summary="16-bit RGB 565 format, [15:0] R:G:B 5:6:5 little endian"/>
336
      <entry name="bgr565" value="0x36314742" summary="16-bit BGR 565 format, [15:0] B:G:R 5:6:5 little endian"/>
337
      <entry name="rgb888" value="0x34324752" summary="24-bit RGB format, [23:0] R:G:B little endian"/>
338
      <entry name="bgr888" value="0x34324742" summary="24-bit BGR format, [23:0] B:G:R little endian"/>
339
      <entry name="xbgr8888" value="0x34324258" summary="32-bit xBGR format, [31:0] x:B:G:R 8:8:8:8 little endian"/>
340
      <entry name="rgbx8888" value="0x34325852" summary="32-bit RGBx format, [31:0] R:G:B:x 8:8:8:8 little endian"/>
341
      <entry name="bgrx8888" value="0x34325842" summary="32-bit BGRx format, [31:0] B:G:R:x 8:8:8:8 little endian"/>
342
      <entry name="abgr8888" value="0x34324241" summary="32-bit ABGR format, [31:0] A:B:G:R 8:8:8:8 little endian"/>
343
      <entry name="rgba8888" value="0x34324152" summary="32-bit RGBA format, [31:0] R:G:B:A 8:8:8:8 little endian"/>
344
      <entry name="bgra8888" value="0x34324142" summary="32-bit BGRA format, [31:0] B:G:R:A 8:8:8:8 little endian"/>
345
      <entry name="xrgb2101010" value="0x30335258" summary="32-bit xRGB format, [31:0] x:R:G:B 2:10:10:10 little endian"/>
346
      <entry name="xbgr2101010" value="0x30334258" summary="32-bit xBGR format, [31:0] x:B:G:R 2:10:10:10 little endian"/>
347
      <entry name="rgbx1010102" value="0x30335852" summary="32-bit RGBx format, [31:0] R:G:B:x 10:10:10:2 little endian"/>
348
      <entry name="bgrx1010102" value="0x30335842" summary="32-bit BGRx format, [31:0] B:G:R:x 10:10:10:2 little endian"/>
349
      <entry name="argb2101010" value="0x30335241" summary="32-bit ARGB format, [31:0] A:R:G:B 2:10:10:10 little endian"/>
350
      <entry name="abgr2101010" value="0x30334241" summary="32-bit ABGR format, [31:0] A:B:G:R 2:10:10:10 little endian"/>
351
      <entry name="rgba1010102" value="0x30334152" summary="32-bit RGBA format, [31:0] R:G:B:A 10:10:10:2 little endian"/>
352
      <entry name="bgra1010102" value="0x30334142" summary="32-bit BGRA format, [31:0] B:G:R:A 10:10:10:2 little endian"/>
353
      <entry name="yuyv" value="0x56595559" summary="packed YCbCr format, [31:0] Cr0:Y1:Cb0:Y0 8:8:8:8 little endian"/>
354
      <entry name="yvyu" value="0x55595659" summary="packed YCbCr format, [31:0] Cb0:Y1:Cr0:Y0 8:8:8:8 little endian"/>
355
      <entry name="uyvy" value="0x59565955" summary="packed YCbCr format, [31:0] Y1:Cr0:Y0:Cb0 8:8:8:8 little endian"/>
356
      <entry name="vyuy" value="0x59555956" summary="packed YCbCr format, [31:0] Y1:Cb0:Y0:Cr0 8:8:8:8 little endian"/>
357
      <entry name="ayuv" value="0x56555941" summary="packed AYCbCr format, [31:0] A:Y:Cb:Cr 8:8:8:8 little endian"/>
358
      <entry name="nv12" value="0x3231564e" summary="2 plane YCbCr Cr:Cb format, 2x2 subsampled Cr:Cb plane"/>
359
      <entry name="nv21" value="0x3132564e" summary="2 plane YCbCr Cb:Cr format, 2x2 subsampled Cb:Cr plane"/>
360
      <entry name="nv16" value="0x3631564e" summary="2 plane YCbCr Cr:Cb format, 2x1 subsampled Cr:Cb plane"/>
361
      <entry name="nv61" value="0x3136564e" summary="2 plane YCbCr Cb:Cr format, 2x1 subsampled Cb:Cr plane"/>
362
      <entry name="yuv410" value="0x39565559" summary="3 plane YCbCr format, 4x4 subsampled Cb (1) and Cr (2) planes"/>
363
      <entry name="yvu410" value="0x39555659" summary="3 plane YCbCr format, 4x4 subsampled Cr (1) and Cb (2) planes"/>
364
      <entry name="yuv411" value="0x31315559" summary="3 plane YCbCr format, 4x1 subsampled Cb (1) and Cr (2) planes"/>
365
      <entry name="yvu411" value="0x31315659" summary="3 plane YCbCr format, 4x1 subsampled Cr (1) and Cb (2) planes"/>
366
      <entry name="yuv420" value="0x32315559" summary="3 plane YCbCr format, 2x2 subsampled Cb (1) and Cr (2) planes"/>
367
      <entry name="yvu420" value="0x32315659" summary="3 plane YCbCr format, 2x2 subsampled Cr (1) and Cb (2) planes"/>
368
      <entry name="yuv422" value="0x36315559" summary="3 plane YCbCr format, 2x1 subsampled Cb (1) and Cr (2) planes"/>
369
      <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr format, 2x1 subsampled Cr (1) and Cb (2) planes"/>
370
      <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr format, non-subsampled Cb (1) and Cr (2) planes"/>
371
      <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr format, non-subsampled Cr (1) and Cb (2) planes"/>
372
      <entry name="r8" value="0x20203852" summary="[7:0] R"/>
373
      <entry name="r16" value="0x20363152" summary="[15:0] R little endian"/>
374
      <entry name="rg88" value="0x38384752" summary="[15:0] R:G 8:8 little endian"/>
375
      <entry name="gr88" value="0x38385247" summary="[15:0] G:R 8:8 little endian"/>
376
      <entry name="rg1616" value="0x32334752" summary="[31:0] R:G 16:16 little endian"/>
377
      <entry name="gr1616" value="0x32335247" summary="[31:0] G:R 16:16 little endian"/>
378
      <entry name="xrgb16161616f" value="0x48345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
379
      <entry name="xbgr16161616f" value="0x48344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
380
      <entry name="argb16161616f" value="0x48345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
381
      <entry name="abgr16161616f" value="0x48344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
382
      <entry name="xyuv8888" value="0x56555958" summary="[31:0] X:Y:Cb:Cr 8:8:8:8 little endian"/>
383
      <entry name="vuy888" value="0x34325556" summary="[23:0] Cr:Cb:Y 8:8:8 little endian"/>
384
      <entry name="vuy101010" value="0x30335556" summary="Y followed by U then V, 10:10:10. Non-linear modifier only"/>
385
      <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"/>
386
      <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"/>
387
      <entry name="y216" value="0x36313259" summary="[63:0] Cr0:Y1:Cb0:Y0 16:16:16:16 little endian per 2 Y pixels"/>
388
      <entry name="y410" value="0x30313459" summary="[31:0] A:Cr:Y:Cb 2:10:10:10 little endian"/>
389
      <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"/>
390
      <entry name="y416" value="0x36313459" summary="[63:0] A:Cr:Y:Cb 16:16:16:16 little endian"/>
391
      <entry name="xvyu2101010" value="0x30335658" summary="[31:0] X:Cr:Y:Cb 2:10:10:10 little endian"/>
392
      <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"/>
393
      <entry name="xvyu16161616" value="0x38345658" summary="[63:0] X:Cr:Y:Cb 16:16:16:16 little endian"/>
394
      <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"/>
395
      <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"/>
396
      <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"/>
397
      <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"/>
398
      <entry name="yuv420_8bit" value="0x38305559"/>
399
      <entry name="yuv420_10bit" value="0x30315559"/>
400
      <entry name="xrgb8888_a8" value="0x38415258"/>
401
      <entry name="xbgr8888_a8" value="0x38414258"/>
402
      <entry name="rgbx8888_a8" value="0x38415852"/>
403
      <entry name="bgrx8888_a8" value="0x38415842"/>
404
      <entry name="rgb888_a8" value="0x38413852"/>
405
      <entry name="bgr888_a8" value="0x38413842"/>
406
      <entry name="rgb565_a8" value="0x38413552"/>
407
      <entry name="bgr565_a8" value="0x38413542"/>
408
      <entry name="nv24" value="0x3432564e" summary="non-subsampled Cr:Cb plane"/>
409
      <entry name="nv42" value="0x3234564e" summary="non-subsampled Cb:Cr plane"/>
410
      <entry name="p210" value="0x30313250" summary="2x1 subsampled Cr:Cb plane, 10 bit per channel"/>
411
      <entry name="p010" value="0x30313050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel"/>
412
      <entry name="p012" value="0x32313050" summary="2x2 subsampled Cr:Cb plane 12 bits per channel"/>
413
      <entry name="p016" value="0x36313050" summary="2x2 subsampled Cr:Cb plane 16 bits per channel"/>
414
      <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"/>
415
      <entry name="nv15" value="0x3531564e" summary="2x2 subsampled Cr:Cb plane"/>
416
      <entry name="q410" value="0x30313451"/>
417
      <entry name="q401" value="0x31303451"/>
418
      <entry name="xrgb16161616" value="0x38345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
419
      <entry name="xbgr16161616" value="0x38344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
420
      <entry name="argb16161616" value="0x38345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
421
      <entry name="abgr16161616" value="0x38344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
422
    </enum>
423

424
    <request name="create_pool">
425
      <description summary="create a shm pool">
426
	Create a new wl_shm_pool object.
427

428
	The pool can be used to create shared memory based buffer
429
	objects.  The server will mmap size bytes of the passed file
430
	descriptor, to use as backing memory for the pool.
431
      </description>
432
      <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
433
      <arg name="fd" type="fd" summary="file descriptor for the pool"/>
434
      <arg name="size" type="int" summary="pool size, in bytes"/>
435
    </request>
436

437
    <event name="format">
438
      <description summary="pixel format description">
439
	Informs the client about a valid pixel format that
440
	can be used for buffers. Known formats include
441
	argb8888 and xrgb8888.
442
      </description>
443
      <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
444
    </event>
445
  </interface>
446

447
  <interface name="wl_buffer" version="1">
448
    <description summary="content for a wl_surface">
449
      A buffer provides the content for a wl_surface. Buffers are
450
      created through factory interfaces such as wl_shm, wp_linux_buffer_params
451
      (from the linux-dmabuf protocol extension) or similar. It has a width and
452
      a height and can be attached to a wl_surface, but the mechanism by which a
453
      client provides and updates the contents is defined by the buffer factory
454
      interface.
455

456
      If the buffer uses a format that has an alpha channel, the alpha channel
457
      is assumed to be premultiplied in the color channels unless otherwise
458
      specified.
459

460
      Note, because wl_buffer objects are created from multiple independent
461
      factory interfaces, the wl_buffer interface is frozen at version 1.
462
    </description>
463

464
    <request name="destroy" type="destructor">
465
      <description summary="destroy a buffer">
466
	Destroy a buffer. If and how you need to release the backing
467
	storage is defined by the buffer factory interface.
468

469
	For possible side-effects to a surface, see wl_surface.attach.
470
      </description>
471
    </request>
472

473
    <event name="release">
474
      <description summary="compositor releases buffer">
475
	Sent when this wl_buffer is no longer used by the compositor.
476
	The client is now free to reuse or destroy this buffer and its
477
	backing storage.
478

479
	If a client receives a release event before the frame callback
480
	requested in the same wl_surface.commit that attaches this
481
	wl_buffer to a surface, then the client is immediately free to
482
	reuse the buffer and its backing storage, and does not need a
483
	second buffer for the next surface content update. Typically
484
	this is possible, when the compositor maintains a copy of the
485
	wl_surface contents, e.g. as a GL texture. This is an important
486
	optimization for GL(ES) compositors with wl_shm clients.
487
      </description>
488
    </event>
489
  </interface>
490

491
  <interface name="wl_data_offer" version="3">
492
    <description summary="offer to transfer data">
493
      A wl_data_offer represents a piece of data offered for transfer
494
      by another client (the source client).  It is used by the
495
      copy-and-paste and drag-and-drop mechanisms.  The offer
496
      describes the different mime types that the data can be
497
      converted to and provides the mechanism for transferring the
498
      data directly from the source client.
499
    </description>
500

501
    <enum name="error">
502
      <entry name="invalid_finish" value="0"
503
	     summary="finish request was called untimely"/>
504
      <entry name="invalid_action_mask" value="1"
505
	     summary="action mask contains invalid values"/>
506
      <entry name="invalid_action" value="2"
507
	     summary="action argument has an invalid value"/>
508
      <entry name="invalid_offer" value="3"
509
	     summary="offer doesn't accept this request"/>
510
    </enum>
511

512
    <request name="accept">
513
      <description summary="accept one of the offered mime types">
514
	Indicate that the client can accept the given mime type, or
515
	NULL for not accepted.
516

517
	For objects of version 2 or older, this request is used by the
518
	client to give feedback whether the client can receive the given
519
	mime type, or NULL if none is accepted; the feedback does not
520
	determine whether the drag-and-drop operation succeeds or not.
521

522
	For objects of version 3 or newer, this request determines the
523
	final result of the drag-and-drop operation. If the end result
524
	is that no mime types were accepted, the drag-and-drop operation
525
	will be cancelled and the corresponding drag source will receive
526
	wl_data_source.cancelled. Clients may still use this event in
527
	conjunction with wl_data_source.action for feedback.
528
      </description>
529
      <arg name="serial" type="uint" summary="serial number of the accept request"/>
530
      <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the client"/>
531
    </request>
532

533
    <request name="receive">
534
      <description summary="request that the data is transferred">
535
	To transfer the offered data, the client issues this request
536
	and indicates the mime type it wants to receive.  The transfer
537
	happens through the passed file descriptor (typically created
538
	with the pipe system call).  The source client writes the data
539
	in the mime type representation requested and then closes the
540
	file descriptor.
541

542
	The receiving client reads from the read end of the pipe until
543
	EOF and then closes its end, at which point the transfer is
544
	complete.
545

546
	This request may happen multiple times for different mime types,
547
	both before and after wl_data_device.drop. Drag-and-drop destination
548
	clients may preemptively fetch data or examine it more closely to
549
	determine acceptance.
550
      </description>
551
      <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
552
      <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
553
    </request>
554

555
    <request name="destroy" type="destructor">
556
      <description summary="destroy data offer">
557
	Destroy the data offer.
558
      </description>
559
    </request>
560

561
    <event name="offer">
562
      <description summary="advertise offered mime type">
563
	Sent immediately after creating the wl_data_offer object.  One
564
	event per offered mime type.
565
      </description>
566
      <arg name="mime_type" type="string" summary="offered mime type"/>
567
    </event>
568

569
    <!-- Version 3 additions -->
570

571
    <request name="finish" since="3">
572
      <description summary="the offer will no longer be used">
573
	Notifies the compositor that the drag destination successfully
574
	finished the drag-and-drop operation.
575

576
	Upon receiving this request, the compositor will emit
577
	wl_data_source.dnd_finished on the drag source client.
578

579
	It is a client error to perform other requests than
580
	wl_data_offer.destroy after this one. It is also an error to perform
581
	this request after a NULL mime type has been set in
582
	wl_data_offer.accept or no action was received through
583
	wl_data_offer.action.
584

585
	If wl_data_offer.finish request is received for a non drag and drop
586
	operation, the invalid_finish protocol error is raised.
587
      </description>
588
    </request>
589

590
    <request name="set_actions" since="3">
591
      <description summary="set the available/preferred drag-and-drop actions">
592
	Sets the actions that the destination side client supports for
593
	this operation. This request may trigger the emission of
594
	wl_data_source.action and wl_data_offer.action events if the compositor
595
	needs to change the selected action.
596

597
	This request can be called multiple times throughout the
598
	drag-and-drop operation, typically in response to wl_data_device.enter
599
	or wl_data_device.motion events.
600

601
	This request determines the final result of the drag-and-drop
602
	operation. If the end result is that no action is accepted,
603
	the drag source will receive wl_data_source.cancelled.
604

605
	The dnd_actions argument must contain only values expressed in the
606
	wl_data_device_manager.dnd_actions enum, and the preferred_action
607
	argument must only contain one of those values set, otherwise it
608
	will result in a protocol error.
609

610
	While managing an "ask" action, the destination drag-and-drop client
611
	may perform further wl_data_offer.receive requests, and is expected
612
	to perform one last wl_data_offer.set_actions request with a preferred
613
	action other than "ask" (and optionally wl_data_offer.accept) before
614
	requesting wl_data_offer.finish, in order to convey the action selected
615
	by the user. If the preferred action is not in the
616
	wl_data_offer.source_actions mask, an error will be raised.
617

618
	If the "ask" action is dismissed (e.g. user cancellation), the client
619
	is expected to perform wl_data_offer.destroy right away.
620

621
	This request can only be made on drag-and-drop offers, a protocol error
622
	will be raised otherwise.
623
      </description>
624
      <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
625
	   enum="wl_data_device_manager.dnd_action"/>
626
      <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
627
	   enum="wl_data_device_manager.dnd_action"/>
628
    </request>
629

630
    <event name="source_actions" since="3">
631
      <description summary="notify the source-side available actions">
632
	This event indicates the actions offered by the data source. It
633
	will be sent immediately after creating the wl_data_offer object,
634
	or anytime the source side changes its offered actions through
635
	wl_data_source.set_actions.
636
      </description>
637
      <arg name="source_actions" type="uint" summary="actions offered by the data source"
638
	   enum="wl_data_device_manager.dnd_action"/>
639
    </event>
640

641
    <event name="action" since="3">
642
      <description summary="notify the selected action">
643
	This event indicates the action selected by the compositor after
644
	matching the source/destination side actions. Only one action (or
645
	none) will be offered here.
646

647
	This event can be emitted multiple times during the drag-and-drop
648
	operation in response to destination side action changes through
649
	wl_data_offer.set_actions.
650

651
	This event will no longer be emitted after wl_data_device.drop
652
	happened on the drag-and-drop destination, the client must
653
	honor the last action received, or the last preferred one set
654
	through wl_data_offer.set_actions when handling an "ask" action.
655

656
	Compositors may also change the selected action on the fly, mainly
657
	in response to keyboard modifier changes during the drag-and-drop
658
	operation.
659

660
	The most recent action received is always the valid one. Prior to
661
	receiving wl_data_device.drop, the chosen action may change (e.g.
662
	due to keyboard modifiers being pressed). At the time of receiving
663
	wl_data_device.drop the drag-and-drop destination must honor the
664
	last action received.
665

666
	Action changes may still happen after wl_data_device.drop,
667
	especially on "ask" actions, where the drag-and-drop destination
668
	may choose another action afterwards. Action changes happening
669
	at this stage are always the result of inter-client negotiation, the
670
	compositor shall no longer be able to induce a different action.
671

672
	Upon "ask" actions, it is expected that the drag-and-drop destination
673
	may potentially choose a different action and/or mime type,
674
	based on wl_data_offer.source_actions and finally chosen by the
675
	user (e.g. popping up a menu with the available options). The
676
	final wl_data_offer.set_actions and wl_data_offer.accept requests
677
	must happen before the call to wl_data_offer.finish.
678
      </description>
679
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
680
	   enum="wl_data_device_manager.dnd_action"/>
681
    </event>
682
  </interface>
683

684
  <interface name="wl_data_source" version="3">
685
    <description summary="offer to transfer data">
686
      The wl_data_source object is the source side of a wl_data_offer.
687
      It is created by the source client in a data transfer and
688
      provides a way to describe the offered data and a way to respond
689
      to requests to transfer the data.
690
    </description>
691

692
    <enum name="error">
693
      <entry name="invalid_action_mask" value="0"
694
	     summary="action mask contains invalid values"/>
695
      <entry name="invalid_source" value="1"
696
	     summary="source doesn't accept this request"/>
697
    </enum>
698

699
    <request name="offer">
700
      <description summary="add an offered mime type">
701
	This request adds a mime type to the set of mime types
702
	advertised to targets.  Can be called several times to offer
703
	multiple types.
704
      </description>
705
      <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
706
    </request>
707

708
    <request name="destroy" type="destructor">
709
      <description summary="destroy the data source">
710
	Destroy the data source.
711
      </description>
712
    </request>
713

714
    <event name="target">
715
      <description summary="a target accepts an offered mime type">
716
	Sent when a target accepts pointer_focus or motion events.  If
717
	a target does not accept any of the offered types, type is NULL.
718

719
	Used for feedback during drag-and-drop.
720
      </description>
721
      <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
722
    </event>
723

724
    <event name="send">
725
      <description summary="send the data">
726
	Request for data from the client.  Send the data as the
727
	specified mime type over the passed file descriptor, then
728
	close it.
729
      </description>
730
      <arg name="mime_type" type="string" summary="mime type for the data"/>
731
      <arg name="fd" type="fd" summary="file descriptor for the data"/>
732
    </event>
733

734
    <event name="cancelled">
735
      <description summary="selection was cancelled">
736
	This data source is no longer valid. There are several reasons why
737
	this could happen:
738

739
	- The data source has been replaced by another data source.
740
	- The drag-and-drop operation was performed, but the drop destination
741
	  did not accept any of the mime types offered through
742
	  wl_data_source.target.
743
	- The drag-and-drop operation was performed, but the drop destination
744
	  did not select any of the actions present in the mask offered through
745
	  wl_data_source.action.
746
	- The drag-and-drop operation was performed but didn't happen over a
747
	  surface.
748
	- The compositor cancelled the drag-and-drop operation (e.g. compositor
749
	  dependent timeouts to avoid stale drag-and-drop transfers).
750

751
	The client should clean up and destroy this data source.
752

753
	For objects of version 2 or older, wl_data_source.cancelled will
754
	only be emitted if the data source was replaced by another data
755
	source.
756
      </description>
757
    </event>
758

759
    <!-- Version 3 additions -->
760

761
    <request name="set_actions" since="3">
762
      <description summary="set the available drag-and-drop actions">
763
	Sets the actions that the source side client supports for this
764
	operation. This request may trigger wl_data_source.action and
765
	wl_data_offer.action events if the compositor needs to change the
766
	selected action.
767

768
	The dnd_actions argument must contain only values expressed in the
769
	wl_data_device_manager.dnd_actions enum, otherwise it will result
770
	in a protocol error.
771

772
	This request must be made once only, and can only be made on sources
773
	used in drag-and-drop, so it must be performed before
774
	wl_data_device.start_drag. Attempting to use the source other than
775
	for drag-and-drop will raise a protocol error.
776
      </description>
777
      <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
778
	   enum="wl_data_device_manager.dnd_action"/>
779
    </request>
780

781
    <event name="dnd_drop_performed" since="3">
782
      <description summary="the drag-and-drop operation physically finished">
783
	The user performed the drop action. This event does not indicate
784
	acceptance, wl_data_source.cancelled may still be emitted afterwards
785
	if the drop destination does not accept any mime type.
786

787
	However, this event might however not be received if the compositor
788
	cancelled the drag-and-drop operation before this event could happen.
789

790
	Note that the data_source may still be used in the future and should
791
	not be destroyed here.
792
      </description>
793
    </event>
794

795
    <event name="dnd_finished" since="3">
796
      <description summary="the drag-and-drop operation concluded">
797
	The drop destination finished interoperating with this data
798
	source, so the client is now free to destroy this data source and
799
	free all associated data.
800

801
	If the action used to perform the operation was "move", the
802
	source can now delete the transferred data.
803
      </description>
804
    </event>
805

806
    <event name="action" since="3">
807
      <description summary="notify the selected action">
808
	This event indicates the action selected by the compositor after
809
	matching the source/destination side actions. Only one action (or
810
	none) will be offered here.
811

812
	This event can be emitted multiple times during the drag-and-drop
813
	operation, mainly in response to destination side changes through
814
	wl_data_offer.set_actions, and as the data device enters/leaves
815
	surfaces.
816

817
	It is only possible to receive this event after
818
	wl_data_source.dnd_drop_performed if the drag-and-drop operation
819
	ended in an "ask" action, in which case the final wl_data_source.action
820
	event will happen immediately before wl_data_source.dnd_finished.
821

822
	Compositors may also change the selected action on the fly, mainly
823
	in response to keyboard modifier changes during the drag-and-drop
824
	operation.
825

826
	The most recent action received is always the valid one. The chosen
827
	action may change alongside negotiation (e.g. an "ask" action can turn
828
	into a "move" operation), so the effects of the final action must
829
	always be applied in wl_data_offer.dnd_finished.
830

831
	Clients can trigger cursor surface changes from this point, so
832
	they reflect the current action.
833
      </description>
834
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
835
	   enum="wl_data_device_manager.dnd_action"/>
836
    </event>
837
  </interface>
838

839
  <interface name="wl_data_device" version="3">
840
    <description summary="data transfer device">
841
      There is one wl_data_device per seat which can be obtained
842
      from the global wl_data_device_manager singleton.
843

844
      A wl_data_device provides access to inter-client data transfer
845
      mechanisms such as copy-and-paste and drag-and-drop.
846
    </description>
847

848
    <enum name="error">
849
      <entry name="role" value="0" summary="given wl_surface has another role"/>
850
    </enum>
851

852
    <request name="start_drag">
853
      <description summary="start drag-and-drop operation">
854
	This request asks the compositor to start a drag-and-drop
855
	operation on behalf of the client.
856

857
	The source argument is the data source that provides the data
858
	for the eventual data transfer. If source is NULL, enter, leave
859
	and motion events are sent only to the client that initiated the
860
	drag and the client is expected to handle the data passing
861
	internally. If source is destroyed, the drag-and-drop session will be
862
	cancelled.
863

864
	The origin surface is the surface where the drag originates and
865
	the client must have an active implicit grab that matches the
866
	serial.
867

868
	The icon surface is an optional (can be NULL) surface that
869
	provides an icon to be moved around with the cursor.  Initially,
870
	the top-left corner of the icon surface is placed at the cursor
871
	hotspot, but subsequent wl_surface.attach request can move the
872
	relative position. Attach requests must be confirmed with
873
	wl_surface.commit as usual. The icon surface is given the role of
874
	a drag-and-drop icon. If the icon surface already has another role,
875
	it raises a protocol error.
876

877
	The input region is ignored for wl_surfaces with the role of a
878
	drag-and-drop icon.
879
      </description>
880
      <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
881
      <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
882
      <arg name="icon" type="object" interface="wl_surface" allow-null="true" summary="drag-and-drop icon surface"/>
883
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the origin"/>
884
    </request>
885

886
    <request name="set_selection">
887
      <description summary="copy data to the selection">
888
	This request asks the compositor to set the selection
889
	to the data from the source on behalf of the client.
890

891
	To unset the selection, set the source to NULL.
892
      </description>
893
      <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
894
      <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
895
    </request>
896

897
    <event name="data_offer">
898
      <description summary="introduce a new wl_data_offer">
899
	The data_offer event introduces a new wl_data_offer object,
900
	which will subsequently be used in either the
901
	data_device.enter event (for drag-and-drop) or the
902
	data_device.selection event (for selections).  Immediately
903
	following the data_device.data_offer event, the new data_offer
904
	object will send out data_offer.offer events to describe the
905
	mime types it offers.
906
      </description>
907
      <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
908
    </event>
909

910
    <event name="enter">
911
      <description summary="initiate drag-and-drop session">
912
	This event is sent when an active drag-and-drop pointer enters
913
	a surface owned by the client.  The position of the pointer at
914
	enter time is provided by the x and y arguments, in surface-local
915
	coordinates.
916
      </description>
917
      <arg name="serial" type="uint" summary="serial number of the enter event"/>
918
      <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
919
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
920
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
921
      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
922
	   summary="source data_offer object"/>
923
    </event>
924

925
    <event name="leave">
926
      <description summary="end drag-and-drop session">
927
	This event is sent when the drag-and-drop pointer leaves the
928
	surface and the session ends.  The client must destroy the
929
	wl_data_offer introduced at enter time at this point.
930
      </description>
931
    </event>
932

933
    <event name="motion">
934
      <description summary="drag-and-drop session motion">
935
	This event is sent when the drag-and-drop pointer moves within
936
	the currently focused surface. The new position of the pointer
937
	is provided by the x and y arguments, in surface-local
938
	coordinates.
939
      </description>
940
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
941
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
942
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
943
    </event>
944

945
    <event name="drop">
946
      <description summary="end drag-and-drop session successfully">
947
	The event is sent when a drag-and-drop operation is ended
948
	because the implicit grab is removed.
949

950
	The drag-and-drop destination is expected to honor the last action
951
	received through wl_data_offer.action, if the resulting action is
952
	"copy" or "move", the destination can still perform
953
	wl_data_offer.receive requests, and is expected to end all
954
	transfers with a wl_data_offer.finish request.
955

956
	If the resulting action is "ask", the action will not be considered
957
	final. The drag-and-drop destination is expected to perform one last
958
	wl_data_offer.set_actions request, or wl_data_offer.destroy in order
959
	to cancel the operation.
960
      </description>
961
    </event>
962

963
    <event name="selection">
964
      <description summary="advertise new selection">
965
	The selection event is sent out to notify the client of a new
966
	wl_data_offer for the selection for this device.  The
967
	data_device.data_offer and the data_offer.offer events are
968
	sent out immediately before this event to introduce the data
969
	offer object.  The selection event is sent to a client
970
	immediately before receiving keyboard focus and when a new
971
	selection is set while the client has keyboard focus.  The
972
	data_offer is valid until a new data_offer or NULL is received
973
	or until the client loses keyboard focus.  Switching surface with
974
	keyboard focus within the same client doesn't mean a new selection
975
	will be sent.  The client must destroy the previous selection
976
	data_offer, if any, upon receiving this event.
977
      </description>
978
      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
979
	   summary="selection data_offer object"/>
980
    </event>
981

982
    <!-- Version 2 additions -->
983

984
    <request name="release" type="destructor" since="2">
985
      <description summary="destroy data device">
986
	This request destroys the data device.
987
      </description>
988
    </request>
989
  </interface>
990

991
  <interface name="wl_data_device_manager" version="3">
992
    <description summary="data transfer interface">
993
      The wl_data_device_manager is a singleton global object that
994
      provides access to inter-client data transfer mechanisms such as
995
      copy-and-paste and drag-and-drop.  These mechanisms are tied to
996
      a wl_seat and this interface lets a client get a wl_data_device
997
      corresponding to a wl_seat.
998

999
      Depending on the version bound, the objects created from the bound
1000
      wl_data_device_manager object will have different requirements for
1001
      functioning properly. See wl_data_source.set_actions,
1002
      wl_data_offer.accept and wl_data_offer.finish for details.
1003
    </description>
1004

1005
    <request name="create_data_source">
1006
      <description summary="create a new data source">
1007
	Create a new data source.
1008
      </description>
1009
      <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
1010
    </request>
1011

1012
    <request name="get_data_device">
1013
      <description summary="create a new data device">
1014
	Create a new data device for a given seat.
1015
      </description>
1016
      <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
1017
      <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
1018
    </request>
1019

1020
    <!-- Version 3 additions -->
1021

1022
    <enum name="dnd_action" bitfield="true" since="3">
1023
      <description summary="drag and drop actions">
1024
	This is a bitmask of the available/preferred actions in a
1025
	drag-and-drop operation.
1026

1027
	In the compositor, the selected action is a result of matching the
1028
	actions offered by the source and destination sides.  "action" events
1029
	with a "none" action will be sent to both source and destination if
1030
	there is no match. All further checks will effectively happen on
1031
	(source actions ∩ destination actions).
1032

1033
	In addition, compositors may also pick different actions in
1034
	reaction to key modifiers being pressed. One common design that
1035
	is used in major toolkits (and the behavior recommended for
1036
	compositors) is:
1037

1038
	- If no modifiers are pressed, the first match (in bit order)
1039
	  will be used.
1040
	- Pressing Shift selects "move", if enabled in the mask.
1041
	- Pressing Control selects "copy", if enabled in the mask.
1042

1043
	Behavior beyond that is considered implementation-dependent.
1044
	Compositors may for example bind other modifiers (like Alt/Meta)
1045
	or drags initiated with other buttons than BTN_LEFT to specific
1046
	actions (e.g. "ask").
1047
      </description>
1048
      <entry name="none" value="0" summary="no action"/>
1049
      <entry name="copy" value="1" summary="copy action"/>
1050
      <entry name="move" value="2" summary="move action"/>
1051
      <entry name="ask" value="4" summary="ask action"/>
1052
    </enum>
1053
  </interface>
1054

1055
  <interface name="wl_shell" version="1">
1056
    <description summary="create desktop-style surfaces">
1057
      This interface is implemented by servers that provide
1058
      desktop-style user interfaces.
1059

1060
      It allows clients to associate a wl_shell_surface with
1061
      a basic surface.
1062

1063
      Note! This protocol is deprecated and not intended for production use.
1064
      For desktop-style user interfaces, use xdg_shell. Compositors and clients
1065
      should not implement this interface.
1066
    </description>
1067

1068
    <enum name="error">
1069
      <entry name="role" value="0" summary="given wl_surface has another role"/>
1070
    </enum>
1071

1072
    <request name="get_shell_surface">
1073
      <description summary="create a shell surface from a surface">
1074
	Create a shell surface for an existing surface. This gives
1075
	the wl_surface the role of a shell surface. If the wl_surface
1076
	already has another role, it raises a protocol error.
1077

1078
	Only one shell surface can be associated with a given surface.
1079
      </description>
1080
      <arg name="id" type="new_id" interface="wl_shell_surface" summary="shell surface to create"/>
1081
      <arg name="surface" type="object" interface="wl_surface" summary="surface to be given the shell surface role"/>
1082
    </request>
1083
  </interface>
1084

1085
  <interface name="wl_shell_surface" version="1">
1086
    <description summary="desktop-style metadata interface">
1087
      An interface that may be implemented by a wl_surface, for
1088
      implementations that provide a desktop-style user interface.
1089

1090
      It provides requests to treat surfaces like toplevel, fullscreen
1091
      or popup windows, move, resize or maximize them, associate
1092
      metadata like title and class, etc.
1093

1094
      On the server side the object is automatically destroyed when
1095
      the related wl_surface is destroyed. On the client side,
1096
      wl_shell_surface_destroy() must be called before destroying
1097
      the wl_surface object.
1098
    </description>
1099

1100
    <request name="pong">
1101
      <description summary="respond to a ping event">
1102
	A client must respond to a ping event with a pong request or
1103
	the client may be deemed unresponsive.
1104
      </description>
1105
      <arg name="serial" type="uint" summary="serial number of the ping event"/>
1106
    </request>
1107

1108
    <request name="move">
1109
      <description summary="start an interactive move">
1110
	Start a pointer-driven move of the surface.
1111

1112
	This request must be used in response to a button press event.
1113
	The server may ignore move requests depending on the state of
1114
	the surface (e.g. fullscreen or maximized).
1115
      </description>
1116
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1117
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1118
    </request>
1119

1120
    <enum name="resize" bitfield="true">
1121
      <description summary="edge values for resizing">
1122
	These values are used to indicate which edge of a surface
1123
	is being dragged in a resize operation. The server may
1124
	use this information to adapt its behavior, e.g. choose
1125
	an appropriate cursor image.
1126
      </description>
1127
      <entry name="none" value="0" summary="no edge"/>
1128
      <entry name="top" value="1" summary="top edge"/>
1129
      <entry name="bottom" value="2" summary="bottom edge"/>
1130
      <entry name="left" value="4" summary="left edge"/>
1131
      <entry name="top_left" value="5" summary="top and left edges"/>
1132
      <entry name="bottom_left" value="6" summary="bottom and left edges"/>
1133
      <entry name="right" value="8" summary="right edge"/>
1134
      <entry name="top_right" value="9" summary="top and right edges"/>
1135
      <entry name="bottom_right" value="10" summary="bottom and right edges"/>
1136
    </enum>
1137

1138
    <request name="resize">
1139
      <description summary="start an interactive resize">
1140
	Start a pointer-driven resizing of the surface.
1141

1142
	This request must be used in response to a button press event.
1143
	The server may ignore resize requests depending on the state of
1144
	the surface (e.g. fullscreen or maximized).
1145
      </description>
1146
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1147
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1148
      <arg name="edges" type="uint" enum="resize" summary="which edge or corner is being dragged"/>
1149
    </request>
1150

1151
    <request name="set_toplevel">
1152
      <description summary="make the surface a toplevel surface">
1153
	Map the surface as a toplevel surface.
1154

1155
	A toplevel surface is not fullscreen, maximized or transient.
1156
      </description>
1157
    </request>
1158

1159
    <enum name="transient" bitfield="true">
1160
      <description summary="details of transient behaviour">
1161
	These flags specify details of the expected behaviour
1162
	of transient surfaces. Used in the set_transient request.
1163
      </description>
1164
      <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
1165
    </enum>
1166

1167
    <request name="set_transient">
1168
      <description summary="make the surface a transient surface">
1169
	Map the surface relative to an existing surface.
1170

1171
	The x and y arguments specify the location of the upper left
1172
	corner of the surface relative to the upper left corner of the
1173
	parent surface, in surface-local coordinates.
1174

1175
	The flags argument controls details of the transient behaviour.
1176
      </description>
1177
      <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1178
      <arg name="x" type="int" summary="surface-local x coordinate"/>
1179
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1180
      <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1181
    </request>
1182

1183
    <enum name="fullscreen_method">
1184
      <description summary="different method to set the surface fullscreen">
1185
	Hints to indicate to the compositor how to deal with a conflict
1186
	between the dimensions of the surface and the dimensions of the
1187
	output. The compositor is free to ignore this parameter.
1188
      </description>
1189
      <entry name="default" value="0" summary="no preference, apply default policy"/>
1190
      <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
1191
      <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"/>
1192
      <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1193
    </enum>
1194

1195
    <request name="set_fullscreen">
1196
      <description summary="make the surface a fullscreen surface">
1197
	Map the surface as a fullscreen surface.
1198

1199
	If an output parameter is given then the surface will be made
1200
	fullscreen on that output. If the client does not specify the
1201
	output then the compositor will apply its policy - usually
1202
	choosing the output on which the surface has the biggest surface
1203
	area.
1204

1205
	The client may specify a method to resolve a size conflict
1206
	between the output size and the surface size - this is provided
1207
	through the method parameter.
1208

1209
	The framerate parameter is used only when the method is set
1210
	to "driver", to indicate the preferred framerate. A value of 0
1211
	indicates that the client does not care about framerate.  The
1212
	framerate is specified in mHz, that is framerate of 60000 is 60Hz.
1213

1214
	A method of "scale" or "driver" implies a scaling operation of
1215
	the surface, either via a direct scaling operation or a change of
1216
	the output mode. This will override any kind of output scaling, so
1217
	that mapping a surface with a buffer size equal to the mode can
1218
	fill the screen independent of buffer_scale.
1219

1220
	A method of "fill" means we don't scale up the buffer, however
1221
	any output scale is applied. This means that you may run into
1222
	an edge case where the application maps a buffer with the same
1223
	size of the output mode but buffer_scale 1 (thus making a
1224
	surface larger than the output). In this case it is allowed to
1225
	downscale the results to fit the screen.
1226

1227
	The compositor must reply to this request with a configure event
1228
	with the dimensions for the output on which the surface will
1229
	be made fullscreen.
1230
      </description>
1231
      <arg name="method" type="uint" enum="fullscreen_method" summary="method for resolving size conflict"/>
1232
      <arg name="framerate" type="uint" summary="framerate in mHz"/>
1233
      <arg name="output" type="object" interface="wl_output" allow-null="true"
1234
	   summary="output on which the surface is to be fullscreen"/>
1235
    </request>
1236

1237
    <request name="set_popup">
1238
      <description summary="make the surface a popup surface">
1239
	Map the surface as a popup.
1240

1241
	A popup surface is a transient surface with an added pointer
1242
	grab.
1243

1244
	An existing implicit grab will be changed to owner-events mode,
1245
	and the popup grab will continue after the implicit grab ends
1246
	(i.e. releasing the mouse button does not cause the popup to
1247
	be unmapped).
1248

1249
	The popup grab continues until the window is destroyed or a
1250
	mouse button is pressed in any other client's window. A click
1251
	in any of the client's surfaces is reported as normal, however,
1252
	clicks in other clients' surfaces will be discarded and trigger
1253
	the callback.
1254

1255
	The x and y arguments specify the location of the upper left
1256
	corner of the surface relative to the upper left corner of the
1257
	parent surface, in surface-local coordinates.
1258
      </description>
1259
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1260
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1261
      <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
1262
      <arg name="x" type="int" summary="surface-local x coordinate"/>
1263
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1264
      <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1265
    </request>
1266

1267
    <request name="set_maximized">
1268
      <description summary="make the surface a maximized surface">
1269
	Map the surface as a maximized surface.
1270

1271
	If an output parameter is given then the surface will be
1272
	maximized on that output. If the client does not specify the
1273
	output then the compositor will apply its policy - usually
1274
	choosing the output on which the surface has the biggest surface
1275
	area.
1276

1277
	The compositor will reply with a configure event telling
1278
	the expected new surface size. The operation is completed
1279
	on the next buffer attach to this surface.
1280

1281
	A maximized surface typically fills the entire output it is
1282
	bound to, except for desktop elements such as panels. This is
1283
	the main difference between a maximized shell surface and a
1284
	fullscreen shell surface.
1285

1286
	The details depend on the compositor implementation.
1287
      </description>
1288
      <arg name="output" type="object" interface="wl_output" allow-null="true"
1289
	   summary="output on which the surface is to be maximized"/>
1290
    </request>
1291

1292
    <request name="set_title">
1293
      <description summary="set surface title">
1294
	Set a short title for the surface.
1295

1296
	This string may be used to identify the surface in a task bar,
1297
	window list, or other user interface elements provided by the
1298
	compositor.
1299

1300
	The string must be encoded in UTF-8.
1301
      </description>
1302
      <arg name="title" type="string" summary="surface title"/>
1303
    </request>
1304

1305
    <request name="set_class">
1306
      <description summary="set surface class">
1307
	Set a class for the surface.
1308

1309
	The surface class identifies the general class of applications
1310
	to which the surface belongs. A common convention is to use the
1311
	file name (or the full path if it is a non-standard location) of
1312
	the application's .desktop file as the class.
1313
      </description>
1314
      <arg name="class_" type="string" summary="surface class"/>
1315
    </request>
1316

1317
    <event name="ping">
1318
      <description summary="ping client">
1319
	Ping a client to check if it is receiving events and sending
1320
	requests. A client is expected to reply with a pong request.
1321
      </description>
1322
      <arg name="serial" type="uint" summary="serial number of the ping"/>
1323
    </event>
1324

1325
    <event name="configure">
1326
      <description summary="suggest resize">
1327
	The configure event asks the client to resize its surface.
1328

1329
	The size is a hint, in the sense that the client is free to
1330
	ignore it if it doesn't resize, pick a smaller size (to
1331
	satisfy aspect ratio or resize in steps of NxM pixels).
1332

1333
	The edges parameter provides a hint about how the surface
1334
	was resized. The client may use this information to decide
1335
	how to adjust its content to the new size (e.g. a scrolling
1336
	area might adjust its content position to leave the viewable
1337
	content unmoved).
1338

1339
	The client is free to dismiss all but the last configure
1340
	event it received.
1341

1342
	The width and height arguments specify the size of the window
1343
	in surface-local coordinates.
1344
      </description>
1345
      <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
1346
      <arg name="width" type="int" summary="new width of the surface"/>
1347
      <arg name="height" type="int" summary="new height of the surface"/>
1348
    </event>
1349

1350
    <event name="popup_done">
1351
      <description summary="popup interaction is done">
1352
	The popup_done event is sent out when a popup grab is broken,
1353
	that is, when the user clicks a surface that doesn't belong
1354
	to the client owning the popup surface.
1355
      </description>
1356
    </event>
1357
  </interface>
1358

1359
  <interface name="wl_surface" version="6">
1360
    <description summary="an onscreen surface">
1361
      A surface is a rectangular area that may be displayed on zero
1362
      or more outputs, and shown any number of times at the compositor's
1363
      discretion. They can present wl_buffers, receive user input, and
1364
      define a local coordinate system.
1365

1366
      The size of a surface (and relative positions on it) is described
1367
      in surface-local coordinates, which may differ from the buffer
1368
      coordinates of the pixel content, in case a buffer_transform
1369
      or a buffer_scale is used.
1370

1371
      A surface without a "role" is fairly useless: a compositor does
1372
      not know where, when or how to present it. The role is the
1373
      purpose of a wl_surface. Examples of roles are a cursor for a
1374
      pointer (as set by wl_pointer.set_cursor), a drag icon
1375
      (wl_data_device.start_drag), a sub-surface
1376
      (wl_subcompositor.get_subsurface), and a window as defined by a
1377
      shell protocol (e.g. wl_shell.get_shell_surface).
1378

1379
      A surface can have only one role at a time. Initially a
1380
      wl_surface does not have a role. Once a wl_surface is given a
1381
      role, it is set permanently for the whole lifetime of the
1382
      wl_surface object. Giving the current role again is allowed,
1383
      unless explicitly forbidden by the relevant interface
1384
      specification.
1385

1386
      Surface roles are given by requests in other interfaces such as
1387
      wl_pointer.set_cursor. The request should explicitly mention
1388
      that this request gives a role to a wl_surface. Often, this
1389
      request also creates a new protocol object that represents the
1390
      role and adds additional functionality to wl_surface. When a
1391
      client wants to destroy a wl_surface, they must destroy this role
1392
      object before the wl_surface, otherwise a defunct_role_object error is
1393
      sent.
1394

1395
      Destroying the role object does not remove the role from the
1396
      wl_surface, but it may stop the wl_surface from "playing the role".
1397
      For instance, if a wl_subsurface object is destroyed, the wl_surface
1398
      it was created for will be unmapped and forget its position and
1399
      z-order. It is allowed to create a wl_subsurface for the same
1400
      wl_surface again, but it is not allowed to use the wl_surface as
1401
      a cursor (cursor is a different role than sub-surface, and role
1402
      switching is not allowed).
1403
    </description>
1404

1405
    <enum name="error">
1406
      <description summary="wl_surface error values">
1407
	These errors can be emitted in response to wl_surface requests.
1408
      </description>
1409
      <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
1410
      <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
1411
      <entry name="invalid_size" value="2" summary="buffer size is invalid"/>
1412
      <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
1413
      <entry name="defunct_role_object" value="4"
1414
             summary="surface was destroyed before its role object"/>
1415
    </enum>
1416

1417
    <request name="destroy" type="destructor">
1418
      <description summary="delete surface">
1419
	Deletes the surface and invalidates its object ID.
1420
      </description>
1421
    </request>
1422

1423
    <request name="attach">
1424
      <description summary="set the surface contents">
1425
	Set a buffer as the content of this surface.
1426

1427
	The new size of the surface is calculated based on the buffer
1428
	size transformed by the inverse buffer_transform and the
1429
	inverse buffer_scale. This means that at commit time the supplied
1430
	buffer size must be an integer multiple of the buffer_scale. If
1431
	that's not the case, an invalid_size error is sent.
1432

1433
	The x and y arguments specify the location of the new pending
1434
	buffer's upper left corner, relative to the current buffer's upper
1435
	left corner, in surface-local coordinates. In other words, the
1436
	x and y, combined with the new surface size define in which
1437
	directions the surface's size changes. Setting anything other than 0
1438
	as x and y arguments is discouraged, and should instead be replaced
1439
	with using the separate wl_surface.offset request.
1440

1441
	When the bound wl_surface version is 5 or higher, passing any
1442
	non-zero x or y is a protocol violation, and will result in an
1443
        'invalid_offset' error being raised. The x and y arguments are ignored
1444
        and do not change the pending state. To achieve equivalent semantics,
1445
        use wl_surface.offset.
1446

1447
	Surface contents are double-buffered state, see wl_surface.commit.
1448

1449
	The initial surface contents are void; there is no content.
1450
	wl_surface.attach assigns the given wl_buffer as the pending
1451
	wl_buffer. wl_surface.commit makes the pending wl_buffer the new
1452
	surface contents, and the size of the surface becomes the size
1453
	calculated from the wl_buffer, as described above. After commit,
1454
	there is no pending buffer until the next attach.
1455

1456
	Committing a pending wl_buffer allows the compositor to read the
1457
	pixels in the wl_buffer. The compositor may access the pixels at
1458
	any time after the wl_surface.commit request. When the compositor
1459
	will not access the pixels anymore, it will send the
1460
	wl_buffer.release event. Only after receiving wl_buffer.release,
1461
	the client may reuse the wl_buffer. A wl_buffer that has been
1462
	attached and then replaced by another attach instead of committed
1463
	will not receive a release event, and is not used by the
1464
	compositor.
1465

1466
	If a pending wl_buffer has been committed to more than one wl_surface,
1467
	the delivery of wl_buffer.release events becomes undefined. A well
1468
	behaved client should not rely on wl_buffer.release events in this
1469
	case. Alternatively, a client could create multiple wl_buffer objects
1470
	from the same backing storage or use wp_linux_buffer_release.
1471

1472
	Destroying the wl_buffer after wl_buffer.release does not change
1473
	the surface contents. Destroying the wl_buffer before wl_buffer.release
1474
	is allowed as long as the underlying buffer storage isn't re-used (this
1475
	can happen e.g. on client process termination). However, if the client
1476
	destroys the wl_buffer before receiving the wl_buffer.release event and
1477
	mutates the underlying buffer storage, the surface contents become
1478
	undefined immediately.
1479

1480
	If wl_surface.attach is sent with a NULL wl_buffer, the
1481
	following wl_surface.commit will remove the surface content.
1482
      </description>
1483
      <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
1484
	   summary="buffer of surface contents"/>
1485
      <arg name="x" type="int" summary="surface-local x coordinate"/>
1486
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1487
    </request>
1488

1489
    <request name="damage">
1490
      <description summary="mark part of the surface damaged">
1491
	This request is used to describe the regions where the pending
1492
	buffer is different from the current surface contents, and where
1493
	the surface therefore needs to be repainted. The compositor
1494
	ignores the parts of the damage that fall outside of the surface.
1495

1496
	Damage is double-buffered state, see wl_surface.commit.
1497

1498
	The damage rectangle is specified in surface-local coordinates,
1499
	where x and y specify the upper left corner of the damage rectangle.
1500

1501
	The initial value for pending damage is empty: no damage.
1502
	wl_surface.damage adds pending damage: the new pending damage
1503
	is the union of old pending damage and the given rectangle.
1504

1505
	wl_surface.commit assigns pending damage as the current damage,
1506
	and clears pending damage. The server will clear the current
1507
	damage as it repaints the surface.
1508

1509
	Note! New clients should not use this request. Instead damage can be
1510
	posted with wl_surface.damage_buffer which uses buffer coordinates
1511
	instead of surface coordinates.
1512
      </description>
1513
      <arg name="x" type="int" summary="surface-local x coordinate"/>
1514
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1515
      <arg name="width" type="int" summary="width of damage rectangle"/>
1516
      <arg name="height" type="int" summary="height of damage rectangle"/>
1517
    </request>
1518

1519
    <request name="frame">
1520
      <description summary="request a frame throttling hint">
1521
	Request a notification when it is a good time to start drawing a new
1522
	frame, by creating a frame callback. This is useful for throttling
1523
	redrawing operations, and driving animations.
1524

1525
	When a client is animating on a wl_surface, it can use the 'frame'
1526
	request to get notified when it is a good time to draw and commit the
1527
	next frame of animation. If the client commits an update earlier than
1528
	that, it is likely that some updates will not make it to the display,
1529
	and the client is wasting resources by drawing too often.
1530

1531
	The frame request will take effect on the next wl_surface.commit.
1532
	The notification will only be posted for one frame unless
1533
	requested again. For a wl_surface, the notifications are posted in
1534
	the order the frame requests were committed.
1535

1536
	The server must send the notifications so that a client
1537
	will not send excessive updates, while still allowing
1538
	the highest possible update rate for clients that wait for the reply
1539
	before drawing again. The server should give some time for the client
1540
	to draw and commit after sending the frame callback events to let it
1541
	hit the next output refresh.
1542

1543
	A server should avoid signaling the frame callbacks if the
1544
	surface is not visible in any way, e.g. the surface is off-screen,
1545
	or completely obscured by other opaque surfaces.
1546

1547
	The object returned by this request will be destroyed by the
1548
	compositor after the callback is fired and as such the client must not
1549
	attempt to use it after that point.
1550

1551
	The callback_data passed in the callback is the current time, in
1552
	milliseconds, with an undefined base.
1553
      </description>
1554
      <arg name="callback" type="new_id" interface="wl_callback" summary="callback object for the frame request"/>
1555
    </request>
1556

1557
    <request name="set_opaque_region">
1558
      <description summary="set opaque region">
1559
	This request sets the region of the surface that contains
1560
	opaque content.
1561

1562
	The opaque region is an optimization hint for the compositor
1563
	that lets it optimize the redrawing of content behind opaque
1564
	regions.  Setting an opaque region is not required for correct
1565
	behaviour, but marking transparent content as opaque will result
1566
	in repaint artifacts.
1567

1568
	The opaque region is specified in surface-local coordinates.
1569

1570
	The compositor ignores the parts of the opaque region that fall
1571
	outside of the surface.
1572

1573
	Opaque region is double-buffered state, see wl_surface.commit.
1574

1575
	wl_surface.set_opaque_region changes the pending opaque region.
1576
	wl_surface.commit copies the pending region to the current region.
1577
	Otherwise, the pending and current regions are never changed.
1578

1579
	The initial value for an opaque region is empty. Setting the pending
1580
	opaque region has copy semantics, and the wl_region object can be
1581
	destroyed immediately. A NULL wl_region causes the pending opaque
1582
	region to be set to empty.
1583
      </description>
1584
      <arg name="region" type="object" interface="wl_region" allow-null="true"
1585
	   summary="opaque region of the surface"/>
1586
    </request>
1587

1588
    <request name="set_input_region">
1589
      <description summary="set input region">
1590
	This request sets the region of the surface that can receive
1591
	pointer and touch events.
1592

1593
	Input events happening outside of this region will try the next
1594
	surface in the server surface stack. The compositor ignores the
1595
	parts of the input region that fall outside of the surface.
1596

1597
	The input region is specified in surface-local coordinates.
1598

1599
	Input region is double-buffered state, see wl_surface.commit.
1600

1601
	wl_surface.set_input_region changes the pending input region.
1602
	wl_surface.commit copies the pending region to the current region.
1603
	Otherwise the pending and current regions are never changed,
1604
	except cursor and icon surfaces are special cases, see
1605
	wl_pointer.set_cursor and wl_data_device.start_drag.
1606

1607
	The initial value for an input region is infinite. That means the
1608
	whole surface will accept input. Setting the pending input region
1609
	has copy semantics, and the wl_region object can be destroyed
1610
	immediately. A NULL wl_region causes the input region to be set
1611
	to infinite.
1612
      </description>
1613
      <arg name="region" type="object" interface="wl_region" allow-null="true"
1614
	   summary="input region of the surface"/>
1615
    </request>
1616

1617
    <request name="commit">
1618
      <description summary="commit pending surface state">
1619
	Surface state (input, opaque, and damage regions, attached buffers,
1620
	etc.) is double-buffered. Protocol requests modify the pending state,
1621
	as opposed to the current state in use by the compositor. A commit
1622
	request atomically applies all pending state, replacing the current
1623
	state. After commit, the new pending state is as documented for each
1624
	related request.
1625

1626
	On commit, a pending wl_buffer is applied first, and all other state
1627
	second. This means that all coordinates in double-buffered state are
1628
	relative to the new wl_buffer coming into use, except for
1629
	wl_surface.attach itself. If there is no pending wl_buffer, the
1630
	coordinates are relative to the current surface contents.
1631

1632
	All requests that need a commit to become effective are documented
1633
	to affect double-buffered state.
1634

1635
	Other interfaces may add further double-buffered surface state.
1636
      </description>
1637
    </request>
1638

1639
    <event name="enter">
1640
      <description summary="surface enters an output">
1641
	This is emitted whenever a surface's creation, movement, or resizing
1642
	results in some part of it being within the scanout region of an
1643
	output.
1644

1645
	Note that a surface may be overlapping with zero or more outputs.
1646
      </description>
1647
      <arg name="output" type="object" interface="wl_output" summary="output entered by the surface"/>
1648
    </event>
1649

1650
    <event name="leave">
1651
      <description summary="surface leaves an output">
1652
	This is emitted whenever a surface's creation, movement, or resizing
1653
	results in it no longer having any part of it within the scanout region
1654
	of an output.
1655

1656
	Clients should not use the number of outputs the surface is on for frame
1657
	throttling purposes. The surface might be hidden even if no leave event
1658
	has been sent, and the compositor might expect new surface content
1659
	updates even if no enter event has been sent. The frame event should be
1660
	used instead.
1661
      </description>
1662
      <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
1663
    </event>
1664

1665
    <!-- Version 2 additions -->
1666

1667
    <request name="set_buffer_transform" since="2">
1668
      <description summary="sets the buffer transformation">
1669
	This request sets an optional transformation on how the compositor
1670
	interprets the contents of the buffer attached to the surface. The
1671
	accepted values for the transform parameter are the values for
1672
	wl_output.transform.
1673

1674
	Buffer transform is double-buffered state, see wl_surface.commit.
1675

1676
	A newly created surface has its buffer transformation set to normal.
1677

1678
	wl_surface.set_buffer_transform changes the pending buffer
1679
	transformation. wl_surface.commit copies the pending buffer
1680
	transformation to the current one. Otherwise, the pending and current
1681
	values are never changed.
1682

1683
	The purpose of this request is to allow clients to render content
1684
	according to the output transform, thus permitting the compositor to
1685
	use certain optimizations even if the display is rotated. Using
1686
	hardware overlays and scanning out a client buffer for fullscreen
1687
	surfaces are examples of such optimizations. Those optimizations are
1688
	highly dependent on the compositor implementation, so the use of this
1689
	request should be considered on a case-by-case basis.
1690

1691
	Note that if the transform value includes 90 or 270 degree rotation,
1692
	the width of the buffer will become the surface height and the height
1693
	of the buffer will become the surface width.
1694

1695
	If transform is not one of the values from the
1696
	wl_output.transform enum the invalid_transform protocol error
1697
	is raised.
1698
      </description>
1699
      <arg name="transform" type="int" enum="wl_output.transform"
1700
	   summary="transform for interpreting buffer contents"/>
1701
    </request>
1702

1703
    <!-- Version 3 additions -->
1704

1705
    <request name="set_buffer_scale" since="3">
1706
      <description summary="sets the buffer scaling factor">
1707
	This request sets an optional scaling factor on how the compositor
1708
	interprets the contents of the buffer attached to the window.
1709

1710
	Buffer scale is double-buffered state, see wl_surface.commit.
1711

1712
	A newly created surface has its buffer scale set to 1.
1713

1714
	wl_surface.set_buffer_scale changes the pending buffer scale.
1715
	wl_surface.commit copies the pending buffer scale to the current one.
1716
	Otherwise, the pending and current values are never changed.
1717

1718
	The purpose of this request is to allow clients to supply higher
1719
	resolution buffer data for use on high resolution outputs. It is
1720
	intended that you pick the same buffer scale as the scale of the
1721
	output that the surface is displayed on. This means the compositor
1722
	can avoid scaling when rendering the surface on that output.
1723

1724
	Note that if the scale is larger than 1, then you have to attach
1725
	a buffer that is larger (by a factor of scale in each dimension)
1726
	than the desired surface size.
1727

1728
	If scale is not positive the invalid_scale protocol error is
1729
	raised.
1730
      </description>
1731
      <arg name="scale" type="int"
1732
	   summary="positive scale for interpreting buffer contents"/>
1733
    </request>
1734

1735
    <!-- Version 4 additions -->
1736
    <request name="damage_buffer" since="4">
1737
      <description summary="mark part of the surface damaged using buffer coordinates">
1738
	This request is used to describe the regions where the pending
1739
	buffer is different from the current surface contents, and where
1740
	the surface therefore needs to be repainted. The compositor
1741
	ignores the parts of the damage that fall outside of the surface.
1742

1743
	Damage is double-buffered state, see wl_surface.commit.
1744

1745
	The damage rectangle is specified in buffer coordinates,
1746
	where x and y specify the upper left corner of the damage rectangle.
1747

1748
	The initial value for pending damage is empty: no damage.
1749
	wl_surface.damage_buffer adds pending damage: the new pending
1750
	damage is the union of old pending damage and the given rectangle.
1751

1752
	wl_surface.commit assigns pending damage as the current damage,
1753
	and clears pending damage. The server will clear the current
1754
	damage as it repaints the surface.
1755

1756
	This request differs from wl_surface.damage in only one way - it
1757
	takes damage in buffer coordinates instead of surface-local
1758
	coordinates. While this generally is more intuitive than surface
1759
	coordinates, it is especially desirable when using wp_viewport
1760
	or when a drawing library (like EGL) is unaware of buffer scale
1761
	and buffer transform.
1762

1763
	Note: Because buffer transformation changes and damage requests may
1764
	be interleaved in the protocol stream, it is impossible to determine
1765
	the actual mapping between surface and buffer damage until
1766
	wl_surface.commit time. Therefore, compositors wishing to take both
1767
	kinds of damage into account will have to accumulate damage from the
1768
	two requests separately and only transform from one to the other
1769
	after receiving the wl_surface.commit.
1770
      </description>
1771
      <arg name="x" type="int" summary="buffer-local x coordinate"/>
1772
      <arg name="y" type="int" summary="buffer-local y coordinate"/>
1773
      <arg name="width" type="int" summary="width of damage rectangle"/>
1774
      <arg name="height" type="int" summary="height of damage rectangle"/>
1775
    </request>
1776

1777
    <!-- Version 5 additions -->
1778

1779
    <request name="offset" since="5">
1780
      <description summary="set the surface contents offset">
1781
	The x and y arguments specify the location of the new pending
1782
	buffer's upper left corner, relative to the current buffer's upper
1783
	left corner, in surface-local coordinates. In other words, the
1784
	x and y, combined with the new surface size define in which
1785
	directions the surface's size changes.
1786

1787
	Surface location offset is double-buffered state, see
1788
	wl_surface.commit.
1789

1790
	This request is semantically equivalent to and the replaces the x and y
1791
	arguments in the wl_surface.attach request in wl_surface versions prior
1792
	to 5. See wl_surface.attach for details.
1793
      </description>
1794
      <arg name="x" type="int" summary="surface-local x coordinate"/>
1795
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1796
    </request>
1797

1798
    <!-- Version 6 additions -->
1799

1800
    <event name="preferred_buffer_scale" since="6">
1801
      <description summary="preferred buffer scale for the surface">
1802
	This event indicates the preferred buffer scale for this surface. It is
1803
	sent whenever the compositor's preference changes.
1804

1805
	It is intended that scaling aware clients use this event to scale their
1806
	content and use wl_surface.set_buffer_scale to indicate the scale they
1807
	have rendered with. This allows clients to supply a higher detail
1808
	buffer.
1809
      </description>
1810
      <arg name="factor" type="int" summary="preferred scaling factor"/>
1811
    </event>
1812

1813
    <event name="preferred_buffer_transform" since="6">
1814
      <description summary="preferred buffer transform for the surface">
1815
	This event indicates the preferred buffer transform for this surface.
1816
	It is sent whenever the compositor's preference changes.
1817

1818
	It is intended that transform aware clients use this event to apply the
1819
	transform to their content and use wl_surface.set_buffer_transform to
1820
	indicate the transform they have rendered with.
1821
      </description>
1822
      <arg name="transform" type="uint" enum="wl_output.transform"
1823
	   summary="preferred transform"/>
1824
    </event>
1825
   </interface>
1826

1827
  <interface name="wl_seat" version="9">
1828
    <description summary="group of input devices">
1829
      A seat is a group of keyboards, pointer and touch devices. This
1830
      object is published as a global during start up, or when such a
1831
      device is hot plugged.  A seat typically has a pointer and
1832
      maintains a keyboard focus and a pointer focus.
1833
    </description>
1834

1835
    <enum name="capability" bitfield="true">
1836
      <description summary="seat capability bitmask">
1837
	This is a bitmask of capabilities this seat has; if a member is
1838
	set, then it is present on the seat.
1839
      </description>
1840
      <entry name="pointer" value="1" summary="the seat has pointer devices"/>
1841
      <entry name="keyboard" value="2" summary="the seat has one or more keyboards"/>
1842
      <entry name="touch" value="4" summary="the seat has touch devices"/>
1843
    </enum>
1844

1845
    <enum name="error">
1846
      <description summary="wl_seat error values">
1847
	These errors can be emitted in response to wl_seat requests.
1848
      </description>
1849
      <entry name="missing_capability" value="0"
1850
	     summary="get_pointer, get_keyboard or get_touch called on seat without the matching capability"/>
1851
    </enum>
1852

1853
    <event name="capabilities">
1854
      <description summary="seat capabilities changed">
1855
	This is emitted whenever a seat gains or loses the pointer,
1856
	keyboard or touch capabilities.  The argument is a capability
1857
	enum containing the complete set of capabilities this seat has.
1858

1859
	When the pointer capability is added, a client may create a
1860
	wl_pointer object using the wl_seat.get_pointer request. This object
1861
	will receive pointer events until the capability is removed in the
1862
	future.
1863

1864
	When the pointer capability is removed, a client should destroy the
1865
	wl_pointer objects associated with the seat where the capability was
1866
	removed, using the wl_pointer.release request. No further pointer
1867
	events will be received on these objects.
1868

1869
	In some compositors, if a seat regains the pointer capability and a
1870
	client has a previously obtained wl_pointer object of version 4 or
1871
	less, that object may start sending pointer events again. This
1872
	behavior is considered a misinterpretation of the intended behavior
1873
	and must not be relied upon by the client. wl_pointer objects of
1874
	version 5 or later must not send events if created before the most
1875
	recent event notifying the client of an added pointer capability.
1876

1877
	The above behavior also applies to wl_keyboard and wl_touch with the
1878
	keyboard and touch capabilities, respectively.
1879
      </description>
1880
      <arg name="capabilities" type="uint" enum="capability" summary="capabilities of the seat"/>
1881
    </event>
1882

1883
    <request name="get_pointer">
1884
      <description summary="return pointer object">
1885
	The ID provided will be initialized to the wl_pointer interface
1886
	for this seat.
1887

1888
	This request only takes effect if the seat has the pointer
1889
	capability, or has had the pointer capability in the past.
1890
	It is a protocol violation to issue this request on a seat that has
1891
	never had the pointer capability. The missing_capability error will
1892
	be sent in this case.
1893
      </description>
1894
      <arg name="id" type="new_id" interface="wl_pointer" summary="seat pointer"/>
1895
    </request>
1896

1897
    <request name="get_keyboard">
1898
      <description summary="return keyboard object">
1899
	The ID provided will be initialized to the wl_keyboard interface
1900
	for this seat.
1901

1902
	This request only takes effect if the seat has the keyboard
1903
	capability, or has had the keyboard capability in the past.
1904
	It is a protocol violation to issue this request on a seat that has
1905
	never had the keyboard capability. The missing_capability error will
1906
	be sent in this case.
1907
      </description>
1908
      <arg name="id" type="new_id" interface="wl_keyboard" summary="seat keyboard"/>
1909
    </request>
1910

1911
    <request name="get_touch">
1912
      <description summary="return touch object">
1913
	The ID provided will be initialized to the wl_touch interface
1914
	for this seat.
1915

1916
	This request only takes effect if the seat has the touch
1917
	capability, or has had the touch capability in the past.
1918
	It is a protocol violation to issue this request on a seat that has
1919
	never had the touch capability. The missing_capability error will
1920
	be sent in this case.
1921
      </description>
1922
      <arg name="id" type="new_id" interface="wl_touch" summary="seat touch interface"/>
1923
    </request>
1924

1925
    <!-- Version 2 additions -->
1926

1927
    <event name="name" since="2">
1928
      <description summary="unique identifier for this seat">
1929
	In a multi-seat configuration the seat name can be used by clients to
1930
	help identify which physical devices the seat represents.
1931

1932
	The seat name is a UTF-8 string with no convention defined for its
1933
	contents. Each name is unique among all wl_seat globals. The name is
1934
	only guaranteed to be unique for the current compositor instance.
1935

1936
	The same seat names are used for all clients. Thus, the name can be
1937
	shared across processes to refer to a specific wl_seat global.
1938

1939
	The name event is sent after binding to the seat global. This event is
1940
	only sent once per seat object, and the name does not change over the
1941
	lifetime of the wl_seat global.
1942

1943
	Compositors may re-use the same seat name if the wl_seat global is
1944
	destroyed and re-created later.
1945
      </description>
1946
      <arg name="name" type="string" summary="seat identifier"/>
1947
    </event>
1948

1949
    <!-- Version 5 additions -->
1950

1951
    <request name="release" type="destructor" since="5">
1952
      <description summary="release the seat object">
1953
	Using this request a client can tell the server that it is not going to
1954
	use the seat object anymore.
1955
      </description>
1956
    </request>
1957

1958
  </interface>
1959

1960
  <interface name="wl_pointer" version="9">
1961
    <description summary="pointer input device">
1962
      The wl_pointer interface represents one or more input devices,
1963
      such as mice, which control the pointer location and pointer_focus
1964
      of a seat.
1965

1966
      The wl_pointer interface generates motion, enter and leave
1967
      events for the surfaces that the pointer is located over,
1968
      and button and axis events for button presses, button releases
1969
      and scrolling.
1970
    </description>
1971

1972
    <enum name="error">
1973
      <entry name="role" value="0" summary="given wl_surface has another role"/>
1974
    </enum>
1975

1976
    <request name="set_cursor">
1977
      <description summary="set the pointer surface">
1978
	Set the pointer surface, i.e., the surface that contains the
1979
	pointer image (cursor). This request gives the surface the role
1980
	of a cursor. If the surface already has another role, it raises
1981
	a protocol error.
1982

1983
	The cursor actually changes only if the pointer
1984
	focus for this device is one of the requesting client's surfaces
1985
	or the surface parameter is the current pointer surface. If
1986
	there was a previous surface set with this request it is
1987
	replaced. If surface is NULL, the pointer image is hidden.
1988

1989
	The parameters hotspot_x and hotspot_y define the position of
1990
	the pointer surface relative to the pointer location. Its
1991
	top-left corner is always at (x, y) - (hotspot_x, hotspot_y),
1992
	where (x, y) are the coordinates of the pointer location, in
1993
	surface-local coordinates.
1994

1995
	On surface.attach requests to the pointer surface, hotspot_x
1996
	and hotspot_y are decremented by the x and y parameters
1997
	passed to the request. Attach must be confirmed by
1998
	wl_surface.commit as usual.
1999

2000
	The hotspot can also be updated by passing the currently set
2001
	pointer surface to this request with new values for hotspot_x
2002
	and hotspot_y.
2003

2004
	The input region is ignored for wl_surfaces with the role of
2005
	a cursor. When the use as a cursor ends, the wl_surface is
2006
	unmapped.
2007

2008
	The serial parameter must match the latest wl_pointer.enter
2009
	serial number sent to the client. Otherwise the request will be
2010
	ignored.
2011
      </description>
2012
      <arg name="serial" type="uint" summary="serial number of the enter event"/>
2013
      <arg name="surface" type="object" interface="wl_surface" allow-null="true"
2014
	   summary="pointer surface"/>
2015
      <arg name="hotspot_x" type="int" summary="surface-local x coordinate"/>
2016
      <arg name="hotspot_y" type="int" summary="surface-local y coordinate"/>
2017
    </request>
2018

2019
    <event name="enter">
2020
      <description summary="enter event">
2021
	Notification that this seat's pointer is focused on a certain
2022
	surface.
2023

2024
	When a seat's focus enters a surface, the pointer image
2025
	is undefined and a client should respond to this event by setting
2026
	an appropriate pointer image with the set_cursor request.
2027
      </description>
2028
      <arg name="serial" type="uint" summary="serial number of the enter event"/>
2029
      <arg name="surface" type="object" interface="wl_surface" summary="surface entered by the pointer"/>
2030
      <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2031
      <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2032
    </event>
2033

2034
    <event name="leave">
2035
      <description summary="leave event">
2036
	Notification that this seat's pointer is no longer focused on
2037
	a certain surface.
2038

2039
	The leave notification is sent before the enter notification
2040
	for the new focus.
2041
      </description>
2042
      <arg name="serial" type="uint" summary="serial number of the leave event"/>
2043
      <arg name="surface" type="object" interface="wl_surface" summary="surface left by the pointer"/>
2044
    </event>
2045

2046
    <event name="motion">
2047
      <description summary="pointer motion event">
2048
	Notification of pointer location change. The arguments
2049
	surface_x and surface_y are the location relative to the
2050
	focused surface.
2051
      </description>
2052
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2053
      <arg name="surface_x" type="fixed" summary="surface-local x coordinate"/>
2054
      <arg name="surface_y" type="fixed" summary="surface-local y coordinate"/>
2055
    </event>
2056

2057
    <enum name="button_state">
2058
      <description summary="physical button state">
2059
	Describes the physical state of a button that produced the button
2060
	event.
2061
      </description>
2062
      <entry name="released" value="0" summary="the button is not pressed"/>
2063
      <entry name="pressed" value="1" summary="the button is pressed"/>
2064
    </enum>
2065

2066
    <event name="button">
2067
      <description summary="pointer button event">
2068
	Mouse button click and release notifications.
2069

2070
	The location of the click is given by the last motion or
2071
	enter event.
2072
	The time argument is a timestamp with millisecond
2073
	granularity, with an undefined base.
2074

2075
	The button is a button code as defined in the Linux kernel's
2076
	linux/input-event-codes.h header file, e.g. BTN_LEFT.
2077

2078
	Any 16-bit button code value is reserved for future additions to the
2079
	kernel's event code list. All other button codes above 0xFFFF are
2080
	currently undefined but may be used in future versions of this
2081
	protocol.
2082
      </description>
2083
      <arg name="serial" type="uint" summary="serial number of the button event"/>
2084
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2085
      <arg name="button" type="uint" summary="button that produced the event"/>
2086
      <arg name="state" type="uint" enum="button_state" summary="physical state of the button"/>
2087
    </event>
2088

2089
    <enum name="axis">
2090
      <description summary="axis types">
2091
	Describes the axis types of scroll events.
2092
      </description>
2093
      <entry name="vertical_scroll" value="0" summary="vertical axis"/>
2094
      <entry name="horizontal_scroll" value="1" summary="horizontal axis"/>
2095
    </enum>
2096

2097
    <event name="axis">
2098
      <description summary="axis event">
2099
	Scroll and other axis notifications.
2100

2101
	For scroll events (vertical and horizontal scroll axes), the
2102
	value parameter is the length of a vector along the specified
2103
	axis in a coordinate space identical to those of motion events,
2104
	representing a relative movement along the specified axis.
2105

2106
	For devices that support movements non-parallel to axes multiple
2107
	axis events will be emitted.
2108

2109
	When applicable, for example for touch pads, the server can
2110
	choose to emit scroll events where the motion vector is
2111
	equivalent to a motion event vector.
2112

2113
	When applicable, a client can transform its content relative to the
2114
	scroll distance.
2115
      </description>
2116
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2117
      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2118
      <arg name="value" type="fixed" summary="length of vector in surface-local coordinate space"/>
2119
    </event>
2120

2121
    <!-- Version 3 additions -->
2122

2123
    <request name="release" type="destructor" since="3">
2124
      <description summary="release the pointer object">
2125
	Using this request a client can tell the server that it is not going to
2126
	use the pointer object anymore.
2127

2128
	This request destroys the pointer proxy object, so clients must not call
2129
	wl_pointer_destroy() after using this request.
2130
      </description>
2131
    </request>
2132

2133
    <!-- Version 5 additions -->
2134

2135
    <event name="frame" since="5">
2136
      <description summary="end of a pointer event sequence">
2137
	Indicates the end of a set of events that logically belong together.
2138
	A client is expected to accumulate the data in all events within the
2139
	frame before proceeding.
2140

2141
	All wl_pointer events before a wl_pointer.frame event belong
2142
	logically together. For example, in a diagonal scroll motion the
2143
	compositor will send an optional wl_pointer.axis_source event, two
2144
	wl_pointer.axis events (horizontal and vertical) and finally a
2145
	wl_pointer.frame event. The client may use this information to
2146
	calculate a diagonal vector for scrolling.
2147

2148
	When multiple wl_pointer.axis events occur within the same frame,
2149
	the motion vector is the combined motion of all events.
2150
	When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
2151
	the same frame, this indicates that axis movement in one axis has
2152
	stopped but continues in the other axis.
2153
	When multiple wl_pointer.axis_stop events occur within the same
2154
	frame, this indicates that these axes stopped in the same instance.
2155

2156
	A wl_pointer.frame event is sent for every logical event group,
2157
	even if the group only contains a single wl_pointer event.
2158
	Specifically, a client may get a sequence: motion, frame, button,
2159
	frame, axis, frame, axis_stop, frame.
2160

2161
	The wl_pointer.enter and wl_pointer.leave events are logical events
2162
	generated by the compositor and not the hardware. These events are
2163
	also grouped by a wl_pointer.frame. When a pointer moves from one
2164
	surface to another, a compositor should group the
2165
	wl_pointer.leave event within the same wl_pointer.frame.
2166
	However, a client must not rely on wl_pointer.leave and
2167
	wl_pointer.enter being in the same wl_pointer.frame.
2168
	Compositor-specific policies may require the wl_pointer.leave and
2169
	wl_pointer.enter event being split across multiple wl_pointer.frame
2170
	groups.
2171
      </description>
2172
    </event>
2173

2174
    <enum name="axis_source">
2175
      <description summary="axis source types">
2176
	Describes the source types for axis events. This indicates to the
2177
	client how an axis event was physically generated; a client may
2178
	adjust the user interface accordingly. For example, scroll events
2179
	from a "finger" source may be in a smooth coordinate space with
2180
	kinetic scrolling whereas a "wheel" source may be in discrete steps
2181
	of a number of lines.
2182

2183
	The "continuous" axis source is a device generating events in a
2184
	continuous coordinate space, but using something other than a
2185
	finger. One example for this source is button-based scrolling where
2186
	the vertical motion of a device is converted to scroll events while
2187
	a button is held down.
2188

2189
	The "wheel tilt" axis source indicates that the actual device is a
2190
	wheel but the scroll event is not caused by a rotation but a
2191
	(usually sideways) tilt of the wheel.
2192
      </description>
2193
      <entry name="wheel" value="0" summary="a physical wheel rotation" />
2194
      <entry name="finger" value="1" summary="finger on a touch surface" />
2195
      <entry name="continuous" value="2" summary="continuous coordinate space"/>
2196
      <entry name="wheel_tilt" value="3" summary="a physical wheel tilt" since="6"/>
2197
    </enum>
2198

2199
    <event name="axis_source" since="5">
2200
      <description summary="axis source event">
2201
	Source information for scroll and other axes.
2202

2203
	This event does not occur on its own. It is sent before a
2204
	wl_pointer.frame event and carries the source information for
2205
	all events within that frame.
2206

2207
	The source specifies how this event was generated. If the source is
2208
	wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
2209
	sent when the user lifts the finger off the device.
2210

2211
	If the source is wl_pointer.axis_source.wheel,
2212
	wl_pointer.axis_source.wheel_tilt or
2213
	wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
2214
	or may not be sent. Whether a compositor sends an axis_stop event
2215
	for these sources is hardware-specific and implementation-dependent;
2216
	clients must not rely on receiving an axis_stop event for these
2217
	scroll sources and should treat scroll sequences from these scroll
2218
	sources as unterminated by default.
2219

2220
	This event is optional. If the source is unknown for a particular
2221
	axis event sequence, no event is sent.
2222
	Only one wl_pointer.axis_source event is permitted per frame.
2223

2224
	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2225
	not guaranteed.
2226
      </description>
2227
      <arg name="axis_source" type="uint" enum="axis_source" summary="source of the axis event"/>
2228
    </event>
2229

2230
    <event name="axis_stop" since="5">
2231
      <description summary="axis stop event">
2232
	Stop notification for scroll and other axes.
2233

2234
	For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
2235
	is sent to notify a client that the axis sequence has terminated.
2236
	This enables the client to implement kinetic scrolling.
2237
	See the wl_pointer.axis_source documentation for information on when
2238
	this event may be generated.
2239

2240
	Any wl_pointer.axis events with the same axis_source after this
2241
	event should be considered as the start of a new axis motion.
2242

2243
	The timestamp is to be interpreted identical to the timestamp in the
2244
	wl_pointer.axis event. The timestamp value may be the same as a
2245
	preceding wl_pointer.axis event.
2246
      </description>
2247
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2248
      <arg name="axis" type="uint" enum="axis" summary="the axis stopped with this event"/>
2249
    </event>
2250

2251
    <event name="axis_discrete" since="5">
2252
      <description summary="axis click event">
2253
	Discrete step information for scroll and other axes.
2254

2255
	This event carries the axis value of the wl_pointer.axis event in
2256
	discrete steps (e.g. mouse wheel clicks).
2257

2258
	This event is deprecated with wl_pointer version 8 - this event is not
2259
	sent to clients supporting version 8 or later.
2260

2261
	This event does not occur on its own, it is coupled with a
2262
	wl_pointer.axis event that represents this axis value on a
2263
	continuous scale. The protocol guarantees that each axis_discrete
2264
	event is always followed by exactly one axis event with the same
2265
	axis number within the same wl_pointer.frame. Note that the protocol
2266
	allows for other events to occur between the axis_discrete and
2267
	its coupled axis event, including other axis_discrete or axis
2268
	events. A wl_pointer.frame must not contain more than one axis_discrete
2269
	event per axis type.
2270

2271
	This event is optional; continuous scrolling devices
2272
	like two-finger scrolling on touchpads do not have discrete
2273
	steps and do not generate this event.
2274

2275
	The discrete value carries the directional information. e.g. a value
2276
	of -2 is two steps towards the negative direction of this axis.
2277

2278
	The axis number is identical to the axis number in the associated
2279
	axis event.
2280

2281
	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
2282
	not guaranteed.
2283
      </description>
2284
      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2285
      <arg name="discrete" type="int" summary="number of steps"/>
2286
    </event>
2287

2288
    <event name="axis_value120" since="8">
2289
      <description summary="axis high-resolution scroll event">
2290
	Discrete high-resolution scroll information.
2291

2292
	This event carries high-resolution wheel scroll information,
2293
	with each multiple of 120 representing one logical scroll step
2294
	(a wheel detent). For example, an axis_value120 of 30 is one quarter of
2295
	a logical scroll step in the positive direction, a value120 of
2296
	-240 are two logical scroll steps in the negative direction within the
2297
	same hardware event.
2298
	Clients that rely on discrete scrolling should accumulate the
2299
	value120 to multiples of 120 before processing the event.
2300

2301
	The value120 must not be zero.
2302

2303
	This event replaces the wl_pointer.axis_discrete event in clients
2304
	supporting wl_pointer version 8 or later.
2305

2306
	Where a wl_pointer.axis_source event occurs in the same
2307
	wl_pointer.frame, the axis source applies to this event.
2308

2309
	The order of wl_pointer.axis_value120 and wl_pointer.axis_source is
2310
	not guaranteed.
2311
      </description>
2312
      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2313
      <arg name="value120" type="int" summary="scroll distance as fraction of 120"/>
2314
    </event>
2315

2316
    <!-- Version 9 additions -->
2317

2318
    <enum name="axis_relative_direction">
2319
      <description summary="axis relative direction">
2320
	This specifies the direction of the physical motion that caused a
2321
	wl_pointer.axis event, relative to the wl_pointer.axis direction.
2322
      </description>
2323
      <entry name="identical" value="0"
2324
	  summary="physical motion matches axis direction"/>
2325
      <entry name="inverted" value="1"
2326
	  summary="physical motion is the inverse of the axis direction"/>
2327
    </enum>
2328

2329
    <event name="axis_relative_direction" since="9">
2330
      <description summary="axis relative physical direction event">
2331
	Relative directional information of the entity causing the axis
2332
	motion.
2333

2334
	For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
2335
	event specifies the movement direction of the entity causing the
2336
	wl_pointer.axis event. For example:
2337
	- if a user's fingers on a touchpad move down and this
2338
	  causes a wl_pointer.axis vertical_scroll down event, the physical
2339
	  direction is 'identical'
2340
	- if a user's fingers on a touchpad move down and this causes a
2341
	  wl_pointer.axis vertical_scroll up scroll up event ('natural
2342
	  scrolling'), the physical direction is 'inverted'.
2343

2344
	A client may use this information to adjust scroll motion of
2345
	components. Specifically, enabling natural scrolling causes the
2346
	content to change direction compared to traditional scrolling.
2347
	Some widgets like volume control sliders should usually match the
2348
	physical direction regardless of whether natural scrolling is
2349
	active. This event enables clients to match the scroll direction of
2350
	a widget to the physical direction.
2351

2352
	This event does not occur on its own, it is coupled with a
2353
	wl_pointer.axis event that represents this axis value.
2354
	The protocol guarantees that each axis_relative_direction event is
2355
	always followed by exactly one axis event with the same
2356
	axis number within the same wl_pointer.frame. Note that the protocol
2357
	allows for other events to occur between the axis_relative_direction
2358
	and its coupled axis event.
2359

2360
	The axis number is identical to the axis number in the associated
2361
	axis event.
2362

2363
	The order of wl_pointer.axis_relative_direction,
2364
	wl_pointer.axis_discrete and wl_pointer.axis_source is not
2365
	guaranteed.
2366
      </description>
2367
      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
2368
      <arg name="direction" type="uint" enum="axis_relative_direction"
2369
	  summary="physical direction relative to axis motion"/>
2370
    </event>
2371
  </interface>
2372

2373
  <interface name="wl_keyboard" version="9">
2374
    <description summary="keyboard input device">
2375
      The wl_keyboard interface represents one or more keyboards
2376
      associated with a seat.
2377
    </description>
2378

2379
    <enum name="keymap_format">
2380
      <description summary="keyboard mapping format">
2381
	This specifies the format of the keymap provided to the
2382
	client with the wl_keyboard.keymap event.
2383
      </description>
2384
      <entry name="no_keymap" value="0"
2385
	     summary="no keymap; client must understand how to interpret the raw keycode"/>
2386
      <entry name="xkb_v1" value="1"
2387
	     summary="libxkbcommon compatible, null-terminated string; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
2388
    </enum>
2389

2390
    <event name="keymap">
2391
      <description summary="keyboard mapping">
2392
	This event provides a file descriptor to the client which can be
2393
	memory-mapped in read-only mode to provide a keyboard mapping
2394
	description.
2395

2396
	From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
2397
	the recipient, as MAP_SHARED may fail.
2398
      </description>
2399
      <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
2400
      <arg name="fd" type="fd" summary="keymap file descriptor"/>
2401
      <arg name="size" type="uint" summary="keymap size, in bytes"/>
2402
    </event>
2403

2404
    <event name="enter">
2405
      <description summary="enter event">
2406
	Notification that this seat's keyboard focus is on a certain
2407
	surface.
2408

2409
	The compositor must send the wl_keyboard.modifiers event after this
2410
	event.
2411
      </description>
2412
      <arg name="serial" type="uint" summary="serial number of the enter event"/>
2413
      <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
2414
      <arg name="keys" type="array" summary="the currently pressed keys"/>
2415
    </event>
2416

2417
    <event name="leave">
2418
      <description summary="leave event">
2419
	Notification that this seat's keyboard focus is no longer on
2420
	a certain surface.
2421

2422
	The leave notification is sent before the enter notification
2423
	for the new focus.
2424

2425
	After this event client must assume that all keys, including modifiers,
2426
	are lifted and also it must stop key repeating if there's some going on.
2427
      </description>
2428
      <arg name="serial" type="uint" summary="serial number of the leave event"/>
2429
      <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
2430
    </event>
2431

2432
    <enum name="key_state">
2433
      <description summary="physical key state">
2434
	Describes the physical state of a key that produced the key event.
2435
      </description>
2436
      <entry name="released" value="0" summary="key is not pressed"/>
2437
      <entry name="pressed" value="1" summary="key is pressed"/>
2438
    </enum>
2439

2440
    <event name="key">
2441
      <description summary="key event">
2442
	A key was pressed or released.
2443
	The time argument is a timestamp with millisecond
2444
	granularity, with an undefined base.
2445

2446
	The key is a platform-specific key code that can be interpreted
2447
	by feeding it to the keyboard mapping (see the keymap event).
2448

2449
	If this event produces a change in modifiers, then the resulting
2450
	wl_keyboard.modifiers event must be sent after this event.
2451
      </description>
2452
      <arg name="serial" type="uint" summary="serial number of the key event"/>
2453
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2454
      <arg name="key" type="uint" summary="key that produced the event"/>
2455
      <arg name="state" type="uint" enum="key_state" summary="physical state of the key"/>
2456
    </event>
2457

2458
    <event name="modifiers">
2459
      <description summary="modifier and group state">
2460
	Notifies clients that the modifier and/or group state has
2461
	changed, and it should update its local state.
2462
      </description>
2463
      <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
2464
      <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
2465
      <arg name="mods_latched" type="uint" summary="latched modifiers"/>
2466
      <arg name="mods_locked" type="uint" summary="locked modifiers"/>
2467
      <arg name="group" type="uint" summary="keyboard layout"/>
2468
    </event>
2469

2470
    <!-- Version 3 additions -->
2471

2472
    <request name="release" type="destructor" since="3">
2473
      <description summary="release the keyboard object"/>
2474
    </request>
2475

2476
    <!-- Version 4 additions -->
2477

2478
    <event name="repeat_info" since="4">
2479
      <description summary="repeat rate and delay">
2480
	Informs the client about the keyboard's repeat rate and delay.
2481

2482
	This event is sent as soon as the wl_keyboard object has been created,
2483
	and is guaranteed to be received by the client before any key press
2484
	event.
2485

2486
	Negative values for either rate or delay are illegal. A rate of zero
2487
	will disable any repeating (regardless of the value of delay).
2488

2489
	This event can be sent later on as well with a new value if necessary,
2490
	so clients should continue listening for the event past the creation
2491
	of wl_keyboard.
2492
      </description>
2493
      <arg name="rate" type="int"
2494
	   summary="the rate of repeating keys in characters per second"/>
2495
      <arg name="delay" type="int"
2496
	   summary="delay in milliseconds since key down until repeating starts"/>
2497
    </event>
2498
  </interface>
2499

2500
  <interface name="wl_touch" version="9">
2501
    <description summary="touchscreen input device">
2502
      The wl_touch interface represents a touchscreen
2503
      associated with a seat.
2504

2505
      Touch interactions can consist of one or more contacts.
2506
      For each contact, a series of events is generated, starting
2507
      with a down event, followed by zero or more motion events,
2508
      and ending with an up event. Events relating to the same
2509
      contact point can be identified by the ID of the sequence.
2510
    </description>
2511

2512
    <event name="down">
2513
      <description summary="touch down event and beginning of a touch sequence">
2514
	A new touch point has appeared on the surface. This touch point is
2515
	assigned a unique ID. Future events from this touch point reference
2516
	this ID. The ID ceases to be valid after a touch up event and may be
2517
	reused in the future.
2518
      </description>
2519
      <arg name="serial" type="uint" summary="serial number of the touch down event"/>
2520
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2521
      <arg name="surface" type="object" interface="wl_surface" summary="surface touched"/>
2522
      <arg name="id" type="int" summary="the unique ID of this touch point"/>
2523
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2524
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2525
    </event>
2526

2527
    <event name="up">
2528
      <description summary="end of a touch event sequence">
2529
	The touch point has disappeared. No further events will be sent for
2530
	this touch point and the touch point's ID is released and may be
2531
	reused in a future touch down event.
2532
      </description>
2533
      <arg name="serial" type="uint" summary="serial number of the touch up event"/>
2534
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2535
      <arg name="id" type="int" summary="the unique ID of this touch point"/>
2536
    </event>
2537

2538
    <event name="motion">
2539
      <description summary="update of touch point coordinates">
2540
	A touch point has changed coordinates.
2541
      </description>
2542
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
2543
      <arg name="id" type="int" summary="the unique ID of this touch point"/>
2544
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
2545
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
2546
    </event>
2547

2548
    <event name="frame">
2549
      <description summary="end of touch frame event">
2550
	Indicates the end of a set of events that logically belong together.
2551
	A client is expected to accumulate the data in all events within the
2552
	frame before proceeding.
2553

2554
	A wl_touch.frame terminates at least one event but otherwise no
2555
	guarantee is provided about the set of events within a frame. A client
2556
	must assume that any state not updated in a frame is unchanged from the
2557
	previously known state.
2558
      </description>
2559
    </event>
2560

2561
    <event name="cancel">
2562
      <description summary="touch session cancelled">
2563
	Sent if the compositor decides the touch stream is a global
2564
	gesture. No further events are sent to the clients from that
2565
	particular gesture. Touch cancellation applies to all touch points
2566
	currently active on this client's surface. The client is
2567
	responsible for finalizing the touch points, future touch points on
2568
	this surface may reuse the touch point ID.
2569
      </description>
2570
    </event>
2571

2572
    <!-- Version 3 additions -->
2573

2574
    <request name="release" type="destructor" since="3">
2575
      <description summary="release the touch object"/>
2576
    </request>
2577

2578
    <!-- Version 6 additions -->
2579

2580
    <event name="shape" since="6">
2581
      <description summary="update shape of touch point">
2582
	Sent when a touchpoint has changed its shape.
2583

2584
	This event does not occur on its own. It is sent before a
2585
	wl_touch.frame event and carries the new shape information for
2586
	any previously reported, or new touch points of that frame.
2587

2588
	Other events describing the touch point such as wl_touch.down,
2589
	wl_touch.motion or wl_touch.orientation may be sent within the
2590
	same wl_touch.frame. A client should treat these events as a single
2591
	logical touch point update. The order of wl_touch.shape,
2592
	wl_touch.orientation and wl_touch.motion is not guaranteed.
2593
	A wl_touch.down event is guaranteed to occur before the first
2594
	wl_touch.shape event for this touch ID but both events may occur within
2595
	the same wl_touch.frame.
2596

2597
	A touchpoint shape is approximated by an ellipse through the major and
2598
	minor axis length. The major axis length describes the longer diameter
2599
	of the ellipse, while the minor axis length describes the shorter
2600
	diameter. Major and minor are orthogonal and both are specified in
2601
	surface-local coordinates. The center of the ellipse is always at the
2602
	touchpoint location as reported by wl_touch.down or wl_touch.move.
2603

2604
	This event is only sent by the compositor if the touch device supports
2605
	shape reports. The client has to make reasonable assumptions about the
2606
	shape if it did not receive this event.
2607
      </description>
2608
      <arg name="id" type="int" summary="the unique ID of this touch point"/>
2609
      <arg name="major" type="fixed" summary="length of the major axis in surface-local coordinates"/>
2610
      <arg name="minor" type="fixed" summary="length of the minor axis in surface-local coordinates"/>
2611
    </event>
2612

2613
    <event name="orientation" since="6">
2614
      <description summary="update orientation of touch point">
2615
	Sent when a touchpoint has changed its orientation.
2616

2617
	This event does not occur on its own. It is sent before a
2618
	wl_touch.frame event and carries the new shape information for
2619
	any previously reported, or new touch points of that frame.
2620

2621
	Other events describing the touch point such as wl_touch.down,
2622
	wl_touch.motion or wl_touch.shape may be sent within the
2623
	same wl_touch.frame. A client should treat these events as a single
2624
	logical touch point update. The order of wl_touch.shape,
2625
	wl_touch.orientation and wl_touch.motion is not guaranteed.
2626
	A wl_touch.down event is guaranteed to occur before the first
2627
	wl_touch.orientation event for this touch ID but both events may occur
2628
	within the same wl_touch.frame.
2629

2630
	The orientation describes the clockwise angle of a touchpoint's major
2631
	axis to the positive surface y-axis and is normalized to the -180 to
2632
	+180 degree range. The granularity of orientation depends on the touch
2633
	device, some devices only support binary rotation values between 0 and
2634
	90 degrees.
2635

2636
	This event is only sent by the compositor if the touch device supports
2637
	orientation reports.
2638
      </description>
2639
      <arg name="id" type="int" summary="the unique ID of this touch point"/>
2640
      <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
2641
    </event>
2642
  </interface>
2643

2644
  <interface name="wl_output" version="4">
2645
    <description summary="compositor output region">
2646
      An output describes part of the compositor geometry.  The
2647
      compositor works in the 'compositor coordinate system' and an
2648
      output corresponds to a rectangular area in that space that is
2649
      actually visible.  This typically corresponds to a monitor that
2650
      displays part of the compositor space.  This object is published
2651
      as global during start up, or when a monitor is hotplugged.
2652
    </description>
2653

2654
    <enum name="subpixel">
2655
      <description summary="subpixel geometry information">
2656
	This enumeration describes how the physical
2657
	pixels on an output are laid out.
2658
      </description>
2659
      <entry name="unknown" value="0" summary="unknown geometry"/>
2660
      <entry name="none" value="1" summary="no geometry"/>
2661
      <entry name="horizontal_rgb" value="2" summary="horizontal RGB"/>
2662
      <entry name="horizontal_bgr" value="3" summary="horizontal BGR"/>
2663
      <entry name="vertical_rgb" value="4" summary="vertical RGB"/>
2664
      <entry name="vertical_bgr" value="5" summary="vertical BGR"/>
2665
    </enum>
2666

2667
    <enum name="transform">
2668
      <description summary="transform from framebuffer to output">
2669
	This describes the transform that a compositor will apply to a
2670
	surface to compensate for the rotation or mirroring of an
2671
	output device.
2672

2673
	The flipped values correspond to an initial flip around a
2674
	vertical axis followed by rotation.
2675

2676
	The purpose is mainly to allow clients to render accordingly and
2677
	tell the compositor, so that for fullscreen surfaces, the
2678
	compositor will still be able to scan out directly from client
2679
	surfaces.
2680
      </description>
2681
      <entry name="normal" value="0" summary="no transform"/>
2682
      <entry name="90" value="1" summary="90 degrees counter-clockwise"/>
2683
      <entry name="180" value="2" summary="180 degrees counter-clockwise"/>
2684
      <entry name="270" value="3" summary="270 degrees counter-clockwise"/>
2685
      <entry name="flipped" value="4" summary="180 degree flip around a vertical axis"/>
2686
      <entry name="flipped_90" value="5" summary="flip and rotate 90 degrees counter-clockwise"/>
2687
      <entry name="flipped_180" value="6" summary="flip and rotate 180 degrees counter-clockwise"/>
2688
      <entry name="flipped_270" value="7" summary="flip and rotate 270 degrees counter-clockwise"/>
2689
    </enum>
2690

2691
    <event name="geometry">
2692
      <description summary="properties of the output">
2693
	The geometry event describes geometric properties of the output.
2694
	The event is sent when binding to the output object and whenever
2695
	any of the properties change.
2696

2697
	The physical size can be set to zero if it doesn't make sense for this
2698
	output (e.g. for projectors or virtual outputs).
2699

2700
	The geometry event will be followed by a done event (starting from
2701
	version 2).
2702

2703
	Note: wl_output only advertises partial information about the output
2704
	position and identification. Some compositors, for instance those not
2705
	implementing a desktop-style output layout or those exposing virtual
2706
	outputs, might fake this information. Instead of using x and y, clients
2707
	should use xdg_output.logical_position. Instead of using make and model,
2708
	clients should use name and description.
2709
      </description>
2710
      <arg name="x" type="int"
2711
	   summary="x position within the global compositor space"/>
2712
      <arg name="y" type="int"
2713
	   summary="y position within the global compositor space"/>
2714
      <arg name="physical_width" type="int"
2715
	   summary="width in millimeters of the output"/>
2716
      <arg name="physical_height" type="int"
2717
	   summary="height in millimeters of the output"/>
2718
      <arg name="subpixel" type="int" enum="subpixel"
2719
	   summary="subpixel orientation of the output"/>
2720
      <arg name="make" type="string"
2721
	   summary="textual description of the manufacturer"/>
2722
      <arg name="model" type="string"
2723
	   summary="textual description of the model"/>
2724
      <arg name="transform" type="int" enum="transform"
2725
	   summary="transform that maps framebuffer to output"/>
2726
    </event>
2727

2728
    <enum name="mode" bitfield="true">
2729
      <description summary="mode information">
2730
	These flags describe properties of an output mode.
2731
	They are used in the flags bitfield of the mode event.
2732
      </description>
2733
      <entry name="current" value="0x1"
2734
	     summary="indicates this is the current mode"/>
2735
      <entry name="preferred" value="0x2"
2736
	     summary="indicates this is the preferred mode"/>
2737
    </enum>
2738

2739
    <event name="mode">
2740
      <description summary="advertise available modes for the output">
2741
	The mode event describes an available mode for the output.
2742

2743
	The event is sent when binding to the output object and there
2744
	will always be one mode, the current mode.  The event is sent
2745
	again if an output changes mode, for the mode that is now
2746
	current.  In other words, the current mode is always the last
2747
	mode that was received with the current flag set.
2748

2749
	Non-current modes are deprecated. A compositor can decide to only
2750
	advertise the current mode and never send other modes. Clients
2751
	should not rely on non-current modes.
2752

2753
	The size of a mode is given in physical hardware units of
2754
	the output device. This is not necessarily the same as
2755
	the output size in the global compositor space. For instance,
2756
	the output may be scaled, as described in wl_output.scale,
2757
	or transformed, as described in wl_output.transform. Clients
2758
	willing to retrieve the output size in the global compositor
2759
	space should use xdg_output.logical_size instead.
2760

2761
	The vertical refresh rate can be set to zero if it doesn't make
2762
	sense for this output (e.g. for virtual outputs).
2763

2764
	The mode event will be followed by a done event (starting from
2765
	version 2).
2766

2767
	Clients should not use the refresh rate to schedule frames. Instead,
2768
	they should use the wl_surface.frame event or the presentation-time
2769
	protocol.
2770

2771
	Note: this information is not always meaningful for all outputs. Some
2772
	compositors, such as those exposing virtual outputs, might fake the
2773
	refresh rate or the size.
2774
      </description>
2775
      <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
2776
      <arg name="width" type="int" summary="width of the mode in hardware units"/>
2777
      <arg name="height" type="int" summary="height of the mode in hardware units"/>
2778
      <arg name="refresh" type="int" summary="vertical refresh rate in mHz"/>
2779
    </event>
2780

2781
    <!-- Version 2 additions -->
2782

2783
    <event name="done" since="2">
2784
      <description summary="sent all information about output">
2785
	This event is sent after all other properties have been
2786
	sent after binding to the output object and after any
2787
	other property changes done after that. This allows
2788
	changes to the output properties to be seen as
2789
	atomic, even if they happen via multiple events.
2790
      </description>
2791
    </event>
2792

2793
    <event name="scale" since="2">
2794
      <description summary="output scaling properties">
2795
	This event contains scaling geometry information
2796
	that is not in the geometry event. It may be sent after
2797
	binding the output object or if the output scale changes
2798
	later. If it is not sent, the client should assume a
2799
	scale of 1.
2800

2801
	A scale larger than 1 means that the compositor will
2802
	automatically scale surface buffers by this amount
2803
	when rendering. This is used for very high resolution
2804
	displays where applications rendering at the native
2805
	resolution would be too small to be legible.
2806

2807
	It is intended that scaling aware clients track the
2808
	current output of a surface, and if it is on a scaled
2809
	output it should use wl_surface.set_buffer_scale with
2810
	the scale of the output. That way the compositor can
2811
	avoid scaling the surface, and the client can supply
2812
	a higher detail image.
2813

2814
	The scale event will be followed by a done event.
2815
      </description>
2816
      <arg name="factor" type="int" summary="scaling factor of output"/>
2817
    </event>
2818

2819
    <!-- Version 3 additions -->
2820

2821
    <request name="release" type="destructor" since="3">
2822
      <description summary="release the output object">
2823
	Using this request a client can tell the server that it is not going to
2824
	use the output object anymore.
2825
      </description>
2826
    </request>
2827

2828
    <!-- Version 4 additions -->
2829

2830
    <event name="name" since="4">
2831
      <description summary="name of this output">
2832
	Many compositors will assign user-friendly names to their outputs, show
2833
	them to the user, allow the user to refer to an output, etc. The client
2834
	may wish to know this name as well to offer the user similar behaviors.
2835

2836
	The name is a UTF-8 string with no convention defined for its contents.
2837
	Each name is unique among all wl_output globals. The name is only
2838
	guaranteed to be unique for the compositor instance.
2839

2840
	The same output name is used for all clients for a given wl_output
2841
	global. Thus, the name can be shared across processes to refer to a
2842
	specific wl_output global.
2843

2844
	The name is not guaranteed to be persistent across sessions, thus cannot
2845
	be used to reliably identify an output in e.g. configuration files.
2846

2847
	Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
2848
	not assume that the name is a reflection of an underlying DRM connector,
2849
	X11 connection, etc.
2850

2851
	The name event is sent after binding the output object. This event is
2852
	only sent once per output object, and the name does not change over the
2853
	lifetime of the wl_output global.
2854

2855
	Compositors may re-use the same output name if the wl_output global is
2856
	destroyed and re-created later. Compositors should avoid re-using the
2857
	same name if possible.
2858

2859
	The name event will be followed by a done event.
2860
      </description>
2861
      <arg name="name" type="string" summary="output name"/>
2862
    </event>
2863

2864
    <event name="description" since="4">
2865
      <description summary="human-readable description of this output">
2866
	Many compositors can produce human-readable descriptions of their
2867
	outputs. The client may wish to know this description as well, e.g. for
2868
	output selection purposes.
2869

2870
	The description is a UTF-8 string with no convention defined for its
2871
	contents. The description is not guaranteed to be unique among all
2872
	wl_output globals. Examples might include 'Foocorp 11" Display' or
2873
	'Virtual X11 output via :1'.
2874

2875
	The description event is sent after binding the output object and
2876
	whenever the description changes. The description is optional, and may
2877
	not be sent at all.
2878

2879
	The description event will be followed by a done event.
2880
      </description>
2881
      <arg name="description" type="string" summary="output description"/>
2882
    </event>
2883
  </interface>
2884

2885
  <interface name="wl_region" version="1">
2886
    <description summary="region interface">
2887
      A region object describes an area.
2888

2889
      Region objects are used to describe the opaque and input
2890
      regions of a surface.
2891
    </description>
2892

2893
    <request name="destroy" type="destructor">
2894
      <description summary="destroy region">
2895
	Destroy the region.  This will invalidate the object ID.
2896
      </description>
2897
    </request>
2898

2899
    <request name="add">
2900
      <description summary="add rectangle to region">
2901
	Add the specified rectangle to the region.
2902
      </description>
2903
      <arg name="x" type="int" summary="region-local x coordinate"/>
2904
      <arg name="y" type="int" summary="region-local y coordinate"/>
2905
      <arg name="width" type="int" summary="rectangle width"/>
2906
      <arg name="height" type="int" summary="rectangle height"/>
2907
    </request>
2908

2909
    <request name="subtract">
2910
      <description summary="subtract rectangle from region">
2911
	Subtract the specified rectangle from the region.
2912
      </description>
2913
      <arg name="x" type="int" summary="region-local x coordinate"/>
2914
      <arg name="y" type="int" summary="region-local y coordinate"/>
2915
      <arg name="width" type="int" summary="rectangle width"/>
2916
      <arg name="height" type="int" summary="rectangle height"/>
2917
    </request>
2918
  </interface>
2919

2920
  <interface name="wl_subcompositor" version="1">
2921
    <description summary="sub-surface compositing">
2922
      The global interface exposing sub-surface compositing capabilities.
2923
      A wl_surface, that has sub-surfaces associated, is called the
2924
      parent surface. Sub-surfaces can be arbitrarily nested and create
2925
      a tree of sub-surfaces.
2926

2927
      The root surface in a tree of sub-surfaces is the main
2928
      surface. The main surface cannot be a sub-surface, because
2929
      sub-surfaces must always have a parent.
2930

2931
      A main surface with its sub-surfaces forms a (compound) window.
2932
      For window management purposes, this set of wl_surface objects is
2933
      to be considered as a single window, and it should also behave as
2934
      such.
2935

2936
      The aim of sub-surfaces is to offload some of the compositing work
2937
      within a window from clients to the compositor. A prime example is
2938
      a video player with decorations and video in separate wl_surface
2939
      objects. This should allow the compositor to pass YUV video buffer
2940
      processing to dedicated overlay hardware when possible.
2941
    </description>
2942

2943
    <request name="destroy" type="destructor">
2944
      <description summary="unbind from the subcompositor interface">
2945
	Informs the server that the client will not be using this
2946
	protocol object anymore. This does not affect any other
2947
	objects, wl_subsurface objects included.
2948
      </description>
2949
    </request>
2950

2951
    <enum name="error">
2952
      <entry name="bad_surface" value="0"
2953
	     summary="the to-be sub-surface is invalid"/>
2954
      <entry name="bad_parent" value="1"
2955
	     summary="the to-be sub-surface parent is invalid"/>
2956
    </enum>
2957

2958
    <request name="get_subsurface">
2959
      <description summary="give a surface the role sub-surface">
2960
	Create a sub-surface interface for the given surface, and
2961
	associate it with the given parent surface. This turns a
2962
	plain wl_surface into a sub-surface.
2963

2964
	The to-be sub-surface must not already have another role, and it
2965
	must not have an existing wl_subsurface object. Otherwise the
2966
	bad_surface protocol error is raised.
2967

2968
	Adding sub-surfaces to a parent is a double-buffered operation on the
2969
	parent (see wl_surface.commit). The effect of adding a sub-surface
2970
	becomes visible on the next time the state of the parent surface is
2971
	applied.
2972

2973
	The parent surface must not be one of the child surface's descendants,
2974
	and the parent must be different from the child surface, otherwise the
2975
	bad_parent protocol error is raised.
2976

2977
	This request modifies the behaviour of wl_surface.commit request on
2978
	the sub-surface, see the documentation on wl_subsurface interface.
2979
      </description>
2980
      <arg name="id" type="new_id" interface="wl_subsurface"
2981
	   summary="the new sub-surface object ID"/>
2982
      <arg name="surface" type="object" interface="wl_surface"
2983
	   summary="the surface to be turned into a sub-surface"/>
2984
      <arg name="parent" type="object" interface="wl_surface"
2985
	   summary="the parent surface"/>
2986
    </request>
2987
  </interface>
2988

2989
  <interface name="wl_subsurface" version="1">
2990
    <description summary="sub-surface interface to a wl_surface">
2991
      An additional interface to a wl_surface object, which has been
2992
      made a sub-surface. A sub-surface has one parent surface. A
2993
      sub-surface's size and position are not limited to that of the parent.
2994
      Particularly, a sub-surface is not automatically clipped to its
2995
      parent's area.
2996

2997
      A sub-surface becomes mapped, when a non-NULL wl_buffer is applied
2998
      and the parent surface is mapped. The order of which one happens
2999
      first is irrelevant. A sub-surface is hidden if the parent becomes
3000
      hidden, or if a NULL wl_buffer is applied. These rules apply
3001
      recursively through the tree of surfaces.
3002

3003
      The behaviour of a wl_surface.commit request on a sub-surface
3004
      depends on the sub-surface's mode. The possible modes are
3005
      synchronized and desynchronized, see methods
3006
      wl_subsurface.set_sync and wl_subsurface.set_desync. Synchronized
3007
      mode caches the wl_surface state to be applied when the parent's
3008
      state gets applied, and desynchronized mode applies the pending
3009
      wl_surface state directly. A sub-surface is initially in the
3010
      synchronized mode.
3011

3012
      Sub-surfaces also have another kind of state, which is managed by
3013
      wl_subsurface requests, as opposed to wl_surface requests. This
3014
      state includes the sub-surface position relative to the parent
3015
      surface (wl_subsurface.set_position), and the stacking order of
3016
      the parent and its sub-surfaces (wl_subsurface.place_above and
3017
      .place_below). This state is applied when the parent surface's
3018
      wl_surface state is applied, regardless of the sub-surface's mode.
3019
      As the exception, set_sync and set_desync are effective immediately.
3020

3021
      The main surface can be thought to be always in desynchronized mode,
3022
      since it does not have a parent in the sub-surfaces sense.
3023

3024
      Even if a sub-surface is in desynchronized mode, it will behave as
3025
      in synchronized mode, if its parent surface behaves as in
3026
      synchronized mode. This rule is applied recursively throughout the
3027
      tree of surfaces. This means, that one can set a sub-surface into
3028
      synchronized mode, and then assume that all its child and grand-child
3029
      sub-surfaces are synchronized, too, without explicitly setting them.
3030

3031
      Destroying a sub-surface takes effect immediately. If you need to
3032
      synchronize the removal of a sub-surface to the parent surface update,
3033
      unmap the sub-surface first by attaching a NULL wl_buffer, update parent,
3034
      and then destroy the sub-surface.
3035

3036
      If the parent wl_surface object is destroyed, the sub-surface is
3037
      unmapped.
3038
    </description>
3039

3040
    <request name="destroy" type="destructor">
3041
      <description summary="remove sub-surface interface">
3042
	The sub-surface interface is removed from the wl_surface object
3043
	that was turned into a sub-surface with a
3044
	wl_subcompositor.get_subsurface request. The wl_surface's association
3045
	to the parent is deleted. The wl_surface is unmapped immediately.
3046
      </description>
3047
    </request>
3048

3049
    <enum name="error">
3050
      <entry name="bad_surface" value="0"
3051
	     summary="wl_surface is not a sibling or the parent"/>
3052
    </enum>
3053

3054
    <request name="set_position">
3055
      <description summary="reposition the sub-surface">
3056
	This schedules a sub-surface position change.
3057
	The sub-surface will be moved so that its origin (top left
3058
	corner pixel) will be at the location x, y of the parent surface
3059
	coordinate system. The coordinates are not restricted to the parent
3060
	surface area. Negative values are allowed.
3061

3062
	The scheduled coordinates will take effect whenever the state of the
3063
	parent surface is applied. When this happens depends on whether the
3064
	parent surface is in synchronized mode or not. See
3065
	wl_subsurface.set_sync and wl_subsurface.set_desync for details.
3066

3067
	If more than one set_position request is invoked by the client before
3068
	the commit of the parent surface, the position of a new request always
3069
	replaces the scheduled position from any previous request.
3070

3071
	The initial position is 0, 0.
3072
      </description>
3073
      <arg name="x" type="int" summary="x coordinate in the parent surface"/>
3074
      <arg name="y" type="int" summary="y coordinate in the parent surface"/>
3075
    </request>
3076

3077
    <request name="place_above">
3078
      <description summary="restack the sub-surface">
3079
	This sub-surface is taken from the stack, and put back just
3080
	above the reference surface, changing the z-order of the sub-surfaces.
3081
	The reference surface must be one of the sibling surfaces, or the
3082
	parent surface. Using any other surface, including this sub-surface,
3083
	will cause a protocol error.
3084

3085
	The z-order is double-buffered. Requests are handled in order and
3086
	applied immediately to a pending state. The final pending state is
3087
	copied to the active state the next time the state of the parent
3088
	surface is applied. When this happens depends on whether the parent
3089
	surface is in synchronized mode or not. See wl_subsurface.set_sync and
3090
	wl_subsurface.set_desync for details.
3091

3092
	A new sub-surface is initially added as the top-most in the stack
3093
	of its siblings and parent.
3094
      </description>
3095
      <arg name="sibling" type="object" interface="wl_surface"
3096
	   summary="the reference surface"/>
3097
    </request>
3098

3099
    <request name="place_below">
3100
      <description summary="restack the sub-surface">
3101
	The sub-surface is placed just below the reference surface.
3102
	See wl_subsurface.place_above.
3103
      </description>
3104
      <arg name="sibling" type="object" interface="wl_surface"
3105
	   summary="the reference surface"/>
3106
    </request>
3107

3108
    <request name="set_sync">
3109
      <description summary="set sub-surface to synchronized mode">
3110
	Change the commit behaviour of the sub-surface to synchronized
3111
	mode, also described as the parent dependent mode.
3112

3113
	In synchronized mode, wl_surface.commit on a sub-surface will
3114
	accumulate the committed state in a cache, but the state will
3115
	not be applied and hence will not change the compositor output.
3116
	The cached state is applied to the sub-surface immediately after
3117
	the parent surface's state is applied. This ensures atomic
3118
	updates of the parent and all its synchronized sub-surfaces.
3119
	Applying the cached state will invalidate the cache, so further
3120
	parent surface commits do not (re-)apply old state.
3121

3122
	See wl_subsurface for the recursive effect of this mode.
3123
      </description>
3124
    </request>
3125

3126
    <request name="set_desync">
3127
      <description summary="set sub-surface to desynchronized mode">
3128
	Change the commit behaviour of the sub-surface to desynchronized
3129
	mode, also described as independent or freely running mode.
3130

3131
	In desynchronized mode, wl_surface.commit on a sub-surface will
3132
	apply the pending state directly, without caching, as happens
3133
	normally with a wl_surface. Calling wl_surface.commit on the
3134
	parent surface has no effect on the sub-surface's wl_surface
3135
	state. This mode allows a sub-surface to be updated on its own.
3136

3137
	If cached state exists when wl_surface.commit is called in
3138
	desynchronized mode, the pending state is added to the cached
3139
	state, and applied as a whole. This invalidates the cache.
3140

3141
	Note: even if a sub-surface is set to desynchronized, a parent
3142
	sub-surface may override it to behave as synchronized. For details,
3143
	see wl_subsurface.
3144

3145
	If a surface's parent surface behaves as desynchronized, then
3146
	the cached state is applied on set_desync.
3147
      </description>
3148
    </request>
3149
  </interface>
3150

3151
</protocol>
3152