wayland.xml 129 KB
Newer Older
1
<?xml version="1.0" encoding="UTF-8"?>
2
<protocol name="wayland">
3

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

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

17
18
19
20
21
22
23
24
25
26
27
28
    The above copyright notice and this permission notice (including the
    next paragraph) shall be included in all copies or substantial
    portions of the Software.

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

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
Tiago Vignatti's avatar
Tiago Vignatti committed
34
      is used for internal Wayland protocol features.
35
    </description>
36

37
    <request name="sync">
38
      <description summary="asynchronous roundtrip">
Tiago Vignatti's avatar
Tiago Vignatti committed
39
	The sync request asks the server to emit the 'done' event
40
41
	on the returned wl_callback object.  Since requests are
	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
46
47

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

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

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

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

Kristian Høgsberg's avatar
Kristian Høgsberg committed
71
    <event name="error">
72
73
      <description summary="fatal error event">
	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
82
83
      <arg name="object_id" type="object" summary="object where the error occurred"/>
      <arg name="code" type="uint" summary="error code"/>
      <arg name="message" type="string" summary="error description"/>
84
85
    </event>

Kristian Høgsberg's avatar
Kristian Høgsberg committed
86
    <enum name="error">
87
88
89
90
91
92
93
      <description summary="global error values">
	These errors are global and can be emitted in response to any
	server request.
      </description>
      <entry name="invalid_object" value="0"
	     summary="server couldn't find object"/>
      <entry name="invalid_method" value="1"
94
	     summary="method doesn't exist on the specified interface or malformed request"/>
95
96
      <entry name="no_memory" value="2"
	     summary="server is out of memory"/>
97
98
      <entry name="implementation" value="3"
	     summary="implementation error in compositor"/>
Kristian Høgsberg's avatar
Kristian Høgsberg committed
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
105
106
107
	logic. When a client deletes an object that it had created,
	the server will send this event to acknowledge that it has
	seen the delete request. When the client receives this event,
	it will know that it can safely reuse the object ID.
108
      </description>
109
      <arg name="id" type="uint" summary="deleted object ID"/>
110
111
112
113
    </event>
  </interface>

  <interface name="wl_registry" version="1">
114
    <description summary="global registry object">
115
116
      The singleton global registry object.  The server has a number of
      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
120
121
122
      extension functionality.

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

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

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

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

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

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

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

168
169
170
	The object remains valid and requests to the object will be
	ignored until the client destroys it, to avoid races between
	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"/>
Laszlo Agocs's avatar
Laszlo Agocs committed
173
    </event>
174
  </interface>
175

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

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

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

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

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

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

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

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

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

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

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

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

266
  <interface name="wl_shm" version="1">
267
    <description summary="shared memory support">
268
      A singleton global object that provides support for shared
269
270
271
272
273
274
275
276
      memory.

      Clients can create wl_shm_pool objects using the create_pool
      request.

      At connection setup time, the wl_shm object emits one or more
      format events to inform clients about the valid pixel formats
      that can be used for buffers.
277
278
    </description>

279
    <enum name="error">
280
281
282
283
284
285
      <description summary="wl_shm error values">
	These errors can be emitted in response to wl_shm requests.
      </description>
      <entry name="invalid_format" value="0" summary="buffer format is not known"/>
      <entry name="invalid_stride" value="1" summary="invalid size or stride during pool or buffer creation"/>
      <entry name="invalid_fd" value="2" summary="mmapping the file descriptor failed"/>
286
287
    </enum>

288
    <enum name="format">
289
      <description summary="pixel formats">
290
	This describes the memory layout of an individual pixel.
291

292
293
294
	All renderers should support argb8888 and xrgb8888 but any other
	formats are optional and may not be supported by the particular
	renderer in use.
295

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

404
405
    <request name="create_pool">
      <description summary="create a shm pool">
406
407
408
409
	Create a new wl_shm_pool object.

	The pool can be used to create shared memory based buffer
	objects.  The server will mmap size bytes of the passed file
Peter Hutterer's avatar
Peter Hutterer committed
410
	descriptor, to use as backing memory for the pool.
411
      </description>
412
413
414
      <arg name="id" type="new_id" interface="wl_shm_pool" summary="pool to create"/>
      <arg name="fd" type="fd" summary="file descriptor for the pool"/>
      <arg name="size" type="int" summary="pool size, in bytes"/>
415
    </request>
416
417

    <event name="format">
418
419
420
421
422
      <description summary="pixel format description">
	Informs the client about a valid pixel format that
	can be used for buffers. Known formats include
	argb8888 and xrgb8888.
      </description>
423
      <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
424
    </event>
425
426
  </interface>

427
  <interface name="wl_buffer" version="1">
428
    <description summary="content for a wl_surface">
429
      A buffer provides the content for a wl_surface. Buffers are
430
      created through factory interfaces such as wl_drm, wl_shm or
431
      similar. It has a width and a height and can be attached to a
Tiago Vignatti's avatar
Tiago Vignatti committed
432
      wl_surface, but the mechanism by which a client provides and
433
      updates the contents is defined by the buffer factory interface.
434
435
436
437
    </description>

    <request name="destroy" type="destructor">
      <description summary="destroy a buffer">
438
439
	Destroy a buffer. If and how you need to release the backing
	storage is defined by the buffer factory interface.
440
441

	For possible side-effects to a surface, see wl_surface.attach.
442
443
      </description>
    </request>
Benjamin Franzke's avatar
Benjamin Franzke committed
444

445
    <event name="release">
Tiago Vignatti's avatar
Tiago Vignatti committed
446
      <description summary="compositor releases buffer">
447
	Sent when this wl_buffer is no longer used by the compositor.
448
	The client is now free to reuse or destroy this buffer and its
449
450
451
452
453
	backing storage.

	If a client receives a release event before the frame callback
	requested in the same wl_surface.commit that attaches this
	wl_buffer to a surface, then the client is immediately free to
454
	reuse the buffer and its backing storage, and does not need a
455
	second buffer for the next surface content update. Typically
456
457
458
	this is possible, when the compositor maintains a copy of the
	wl_surface contents, e.g. as a GL texture. This is an important
	optimization for GL(ES) compositors with wl_shm clients.
459
460
      </description>
    </event>
461
462
  </interface>

463
  <interface name="wl_data_offer" version="3">
464
465
466
467
468
469
470
471
472
    <description summary="offer to transfer data">
      A wl_data_offer represents a piece of data offered for transfer
      by another client (the source client).  It is used by the
      copy-and-paste and drag-and-drop mechanisms.  The offer
      describes the different mime types that the data can be
      converted to and provides the mechanism for transferring the
      data directly from the source client.
    </description>

473
474
475
    <enum name="error">
      <entry name="invalid_finish" value="0"
	     summary="finish request was called untimely"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
476
477
478
479
480
481
      <entry name="invalid_action_mask" value="1"
	     summary="action mask contains invalid values"/>
      <entry name="invalid_action" value="2"
	     summary="action argument has an invalid value"/>
      <entry name="invalid_offer" value="3"
	     summary="offer doesn't accept this request"/>
482
483
    </enum>

484
    <request name="accept">
485
486
487
488
      <description summary="accept one of the offered mime types">
	Indicate that the client can accept the given mime type, or
	NULL for not accepted.

489
490
491
492
493
494
495
496
497
498
499
	For objects of version 2 or older, this request is used by the
	client to give feedback whether the client can receive the given
	mime type, or NULL if none is accepted; the feedback does not
	determine whether the drag-and-drop operation succeeds or not.

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

    <request name="receive">
506
507
      <description summary="request that the data is transferred">
	To transfer the offered data, the client issues this request
508
509
510
511
512
513
	and indicates the mime type it wants to receive.  The transfer
	happens through the passed file descriptor (typically created
	with the pipe system call).  The source client writes the data
	in the mime type representation requested and then closes the
	file descriptor.

514
	The receiving client reads from the read end of the pipe until
515
	EOF and then closes its end, at which point the transfer is
516
	complete.
517

518
	This request may happen multiple times for different mime types,
519
520
521
	both before and after wl_data_device.drop. Drag-and-drop destination
	clients may preemptively fetch data or examine it more closely to
	determine acceptance.
522
      </description>
523
524
      <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
      <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
525
526
    </request>

527
528
529
530
531
    <request name="destroy" type="destructor">
      <description summary="destroy data offer">
	Destroy the data offer.
      </description>
    </request>
532
533

    <event name="offer">
534
      <description summary="advertise offered mime type">
535
536
537
	Sent immediately after creating the wl_data_offer object.  One
	event per offered mime type.
      </description>
538
      <arg name="mime_type" type="string" summary="offered mime type"/>
539
    </event>
540
541
542
543
544
545
546
547
548
549
550
551
552
553

    <!-- Version 3 additions -->

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

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

	It is a client error to perform other requests than
	wl_data_offer.destroy after this one. It is also an error to perform
	this request after a NULL mime type has been set in
Carlos Garnacho's avatar
Carlos Garnacho committed
554
555
	wl_data_offer.accept or no action was received through
	wl_data_offer.action.
556
557
558

	If wl_data_offer.finish request is received for a non drag and drop
	operation, the invalid_finish protocol error is raised.
559
560
      </description>
    </request>
Carlos Garnacho's avatar
Carlos Garnacho committed
561
562
563
564
565
566

    <request name="set_actions" since="3">
      <description summary="set the available/preferred drag-and-drop actions">
	Sets the actions that the destination side client supports for
	this operation. This request may trigger the emission of
	wl_data_source.action and wl_data_offer.action events if the compositor
567
	needs to change the selected action.
Carlos Garnacho's avatar
Carlos Garnacho committed
568
569
570
571
572
573
574

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

	This request determines the final result of the drag-and-drop
	operation. If the end result is that no action is accepted,
575
	the drag source will receive wl_data_source.cancelled.
Carlos Garnacho's avatar
Carlos Garnacho committed
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595

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

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

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

	This request can only be made on drag-and-drop offers, a protocol error
	will be raised otherwise.
      </description>
596
      <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
597
	   enum="wl_data_device_manager.dnd_action"/>
598
      <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
599
	   enum="wl_data_device_manager.dnd_action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
600
601
602
603
604
605
606
607
    </request>

    <event name="source_actions" since="3">
      <description summary="notify the source-side available actions">
	This event indicates the actions offered by the data source. It
	will be sent right after wl_data_device.enter, or anytime the source
	side changes its offered actions through wl_data_source.set_actions.
      </description>
608
      <arg name="source_actions" type="uint" summary="actions offered by the data source"
609
	   enum="wl_data_device_manager.dnd_action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
    </event>

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

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

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

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

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

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

	Upon "ask" actions, it is expected that the drag-and-drop destination
644
	may potentially choose a different action and/or mime type,
Carlos Garnacho's avatar
Carlos Garnacho committed
645
646
647
648
649
	based on wl_data_offer.source_actions and finally chosen by the
	user (e.g. popping up a menu with the available options). The
	final wl_data_offer.set_actions and wl_data_offer.accept requests
	must happen before the call to wl_data_offer.finish.
      </description>
650
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
651
	   enum="wl_data_device_manager.dnd_action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
652
    </event>
653
654
  </interface>

655
  <interface name="wl_data_source" version="3">
656
657
658
659
660
661
662
    <description summary="offer to transfer data">
      The wl_data_source object is the source side of a wl_data_offer.
      It is created by the source client in a data transfer and
      provides a way to describe the offered data and a way to respond
      to requests to transfer the data.
    </description>

Carlos Garnacho's avatar
Carlos Garnacho committed
663
664
665
666
667
668
669
    <enum name="error">
      <entry name="invalid_action_mask" value="0"
	     summary="action mask contains invalid values"/>
      <entry name="invalid_source" value="1"
	     summary="source doesn't accept this request"/>
    </enum>

670
    <request name="offer">
671
      <description summary="add an offered mime type">
672
	This request adds a mime type to the set of mime types
673
674
675
	advertised to targets.  Can be called several times to offer
	multiple types.
      </description>
676
      <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
677
678
    </request>

679
680
681
682
683
    <request name="destroy" type="destructor">
      <description summary="destroy the data source">
	Destroy the data source.
      </description>
    </request>
684
685

    <event name="target">
686
      <description summary="a target accepts an offered mime type">
687
688
	Sent when a target accepts pointer_focus or motion events.  If
	a target does not accept any of the offered types, type is NULL.
689
690

	Used for feedback during drag-and-drop.
691
      </description>
692
      <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
693
694
695
    </event>

    <event name="send">
696
      <description summary="send the data">
697
698
699
	Request for data from the client.  Send the data as the
	specified mime type over the passed file descriptor, then
	close it.
700
      </description>
701
702
      <arg name="mime_type" type="string" summary="mime type for the data"/>
      <arg name="fd" type="fd" summary="file descriptor for the data"/>
703
704
    </event>

705
706
    <event name="cancelled">
      <description summary="selection was cancelled">
707
708
709
710
711
	This data source is no longer valid. There are several reasons why
	this could happen:

	- The data source has been replaced by another data source.
	- The drag-and-drop operation was performed, but the drop destination
712
	  did not accept any of the mime types offered through
713
	  wl_data_source.target.
Carlos Garnacho's avatar
Carlos Garnacho committed
714
715
716
	- The drag-and-drop operation was performed, but the drop destination
	  did not select any of the actions present in the mask offered through
	  wl_data_source.action.
717
718
719
720
721
	- The drag-and-drop operation was performed but didn't happen over a
	  surface.
	- The compositor cancelled the drag-and-drop operation (e.g. compositor
	  dependent timeouts to avoid stale drag-and-drop transfers).

722
	The client should clean up and destroy this data source.
723
724
725
726

	For objects of version 2 or older, wl_data_source.cancelled will
	only be emitted if the data source was replaced by another data
	source.
727
728
729
      </description>
    </event>

730
731
    <!-- Version 3 additions -->

Carlos Garnacho's avatar
Carlos Garnacho committed
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
    <request name="set_actions" since="3">
      <description summary="set the available drag-and-drop actions">
	Sets the actions that the source side client supports for this
	operation. This request may trigger wl_data_source.action and
	wl_data_offer.action events if the compositor needs to change the
	selected action.

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

	This request must be made once only, and can only be made on sources
	used in drag-and-drop, so it must be performed before
	wl_data_device.start_drag. Attempting to use the source other than
	for drag-and-drop will raise a protocol error.
      </description>
748
      <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
749
	   enum="wl_data_device_manager.dnd_action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
750
751
    </request>

752
753
754
755
    <event name="dnd_drop_performed" since="3">
      <description summary="the drag-and-drop operation physically finished">
	The user performed the drop action. This event does not indicate
	acceptance, wl_data_source.cancelled may still be emitted afterwards
756
	if the drop destination does not accept any mime type.
757
758
759
760
761
762
763
764
765
766
767
768
769
770

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

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

    <event name="dnd_finished" since="3">
      <description summary="the drag-and-drop operation concluded">
	The drop destination finished interoperating with this data
	source, so the client is now free to destroy this data source and
	free all associated data.
Carlos Garnacho's avatar
Carlos Garnacho committed
771
772
773

	If the action used to perform the operation was "move", the
	source can now delete the transferred data.
774
775
      </description>
    </event>
Carlos Garnacho's avatar
Carlos Garnacho committed
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804

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

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

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

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

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

	Clients can trigger cursor surface changes from this point, so
	they reflect the current action.
      </description>
805
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
806
	   enum="wl_data_device_manager.dnd_action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
807
    </event>
808
809
  </interface>

810
  <interface name="wl_data_device" version="3">
811
812
813
814
815
816
817
    <description summary="data transfer device">
      There is one wl_data_device per seat which can be obtained
      from the global wl_data_device_manager singleton.

      A wl_data_device provides access to inter-client data transfer
      mechanisms such as copy-and-paste and drag-and-drop.
    </description>
818
819
820
821
822

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

823
    <request name="start_drag">
824
825
      <description summary="start drag-and-drop operation">
	This request asks the compositor to start a drag-and-drop
826
827
828
829
830
831
832
833
834
835
836
837
	operation on behalf of the client.

	The source argument is the data source that provides the data
	for the eventual data transfer. If source is NULL, enter, leave
	and motion events are sent only to the client that initiated the
	drag and the client is expected to handle the data passing
	internally.

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

838
	The icon surface is an optional (can be NULL) surface that
839
840
	provides an icon to be moved around with the cursor.  Initially,
	the top-left corner of the icon surface is placed at the cursor
841
842
	hotspot, but subsequent wl_surface.attach request can move the
	relative position. Attach requests must be confirmed with
843
	wl_surface.commit as usual. The icon surface is given the role of
844
845
	a drag-and-drop icon. If the icon surface already has another role,
	it raises a protocol error.
846

847
	The current and pending input regions of the icon wl_surface are
848
	cleared, and wl_surface.set_input_region is ignored until the
849
	wl_surface is no longer used as the icon surface. When the use
850
851
	as an icon ends, the current and pending input regions become
	undefined, and the wl_surface is unmapped.
852
      </description>
853
854
855
856
      <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
      <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
      <arg name="icon" type="object" interface="wl_surface" allow-null="true" summary="drag-and-drop icon surface"/>
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the origin"/>
857
858
859
    </request>

    <request name="set_selection">
860
861
862
863
864
865
      <description summary="copy data to the selection">
	This request asks the compositor to set the selection
	to the data from the source on behalf of the client.

	To unset the selection, set the source to NULL.
      </description>
866
867
      <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
      <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
868
869
870
    </request>

    <event name="data_offer">
871
872
873
      <description summary="introduce a new wl_data_offer">
	The data_offer event introduces a new wl_data_offer object,
	which will subsequently be used in either the
874
	data_device.enter event (for drag-and-drop) or the
875
876
877
	data_device.selection event (for selections).  Immediately
	following the data_device_data_offer event, the new data_offer
	object will send out data_offer.offer events to describe the
878
	mime types it offers.
879
      </description>
880
      <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
881
882
883
    </event>

    <event name="enter">
884
      <description summary="initiate drag-and-drop session">
885
886
	This event is sent when an active drag-and-drop pointer enters
	a surface owned by the client.  The position of the pointer at
887
888
	enter time is provided by the x and y arguments, in surface-local
	coordinates.
889
      </description>
890
891
892
893
894
895
      <arg name="serial" type="uint" summary="serial number of the enter event"/>
      <arg name="surface" type="object" interface="wl_surface" summary="client surface entered"/>
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
	   summary="source data_offer object"/>
896
897
    </event>

898
    <event name="leave">
899
      <description summary="end drag-and-drop session">
900
901
902
903
904
	This event is sent when the drag-and-drop pointer leaves the
	surface and the session ends.  The client must destroy the
	wl_data_offer introduced at enter time at this point.
      </description>
    </event>
905
906

    <event name="motion">
907
      <description summary="drag-and-drop session motion">
908
909
	This event is sent when the drag-and-drop pointer moves within
	the currently focused surface. The new position of the pointer
910
	is provided by the x and y arguments, in surface-local
911
912
	coordinates.
      </description>
913
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
914
915
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
916
917
    </event>

918
    <event name="drop">
919
      <description summary="end drag-and-drop session successfully">
920
921
	The event is sent when a drag-and-drop operation is ended
	because the implicit grab is removed.
Carlos Garnacho's avatar
Carlos Garnacho committed
922
923
924
925
926
927
928
929
930
931
932

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

	If the resulting action is "ask", the action will not be considered
	final. The drag-and-drop destination is expected to perform one last
	wl_data_offer.set_actions request, or wl_data_offer.destroy in order
	to cancel the operation.
933
934
      </description>
    </event>
935
936

    <event name="selection">
937
938
939
940
941
942
943
944
945
      <description summary="advertise new selection">
	The selection event is sent out to notify the client of a new
	wl_data_offer for the selection for this device.  The
	data_device.data_offer and the data_offer.offer events are
	sent out immediately before this event to introduce the data
	offer object.  The selection event is sent to a client
	immediately before receiving keyboard focus and when a new
	selection is set while the client has keyboard focus.  The
	data_offer is valid until a new data_offer or NULL is received
946
947
948
	or until the client loses keyboard focus.  The client must
	destroy the previous selection data_offer, if any, upon receiving
	this event.
949
      </description>
950
951
      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
	   summary="selection data_offer object"/>
952
    </event>
953
954
955
956
957
958
959
960

    <!-- Version 2 additions -->

    <request name="release" type="destructor" since="2">
      <description summary="destroy data device">
	This request destroys the data device.
      </description>
    </request>
961
962
  </interface>

963
  <interface name="wl_data_device_manager" version="3">
964
    <description summary="data transfer interface">
965
      The wl_data_device_manager is a singleton global object that
966
      provides access to inter-client data transfer mechanisms such as
967
      copy-and-paste and drag-and-drop.  These mechanisms are tied to
968
969
      a wl_seat and this interface lets a client get a wl_data_device
      corresponding to a wl_seat.
970
971
972
973
974

      Depending on the version bound, the objects created from the bound
      wl_data_device_manager object will have different requirements for
      functioning properly. See wl_data_source.set_actions,
      wl_data_offer.accept and wl_data_offer.finish for details.
975
976
    </description>

977
    <request name="create_data_source">
978
      <description summary="create a new data source">
Peter Hutterer's avatar
Peter Hutterer committed
979
	Create a new data source.
980
      </description>
981
      <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
982
983
984
    </request>

    <request name="get_data_device">
985
      <description summary="create a new data device">
Peter Hutterer's avatar
Peter Hutterer committed
986
	Create a new data device for a given seat.
987
      </description>
988
989
      <arg name="id" type="new_id" interface="wl_data_device" summary="data device to create"/>
      <arg name="seat" type="object" interface="wl_seat" summary="seat associated with the data device"/>
990
    </request>
Carlos Garnacho's avatar
Carlos Garnacho committed
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005

    <!-- Version 3 additions -->

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

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

	In addition, compositors may also pick different actions in
1006
	reaction to key modifiers being pressed. One common design that
Carlos Garnacho's avatar
Carlos Garnacho committed
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
	is used in major toolkits (and the behavior recommended for
	compositors) is:

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

	Behavior beyond that is considered implementation-dependent.
	Compositors may for example bind other modifiers (like Alt/Meta)
	or drags initiated with other buttons than BTN_LEFT to specific
	actions (e.g. "ask").
      </description>
1020
1021
1022
1023
      <entry name="none" value="0" summary="no action"/>
      <entry name="copy" value="1" summary="copy action"/>
      <entry name="move" value="2" summary="move action"/>
      <entry name="ask" value="4" summary="ask action"/>
Carlos Garnacho's avatar
Carlos Garnacho committed
1024
    </enum>
1025
1026
  </interface>

1027
  <interface name="wl_shell" version="1">
1028
1029
1030
1031
1032
1033
    <description summary="create desktop-style surfaces">
      This interface is implemented by servers that provide
      desktop-style user interfaces.

      It allows clients to associate a wl_shell_surface with
      a basic surface.
1034
1035
1036

      Note! This protocol is deprecated and not intended for production use.
      For desktop-style user interfaces, use xdg_shell.
1037
1038
    </description>

1039
1040
1041
1042
    <enum name="error">
      <entry name="role" value="0" summary="given wl_surface has another role"/>
    </enum>

1043
    <request name="get_shell_surface">
1044
      <description summary="create a shell surface from a surface">
1045
	Create a shell surface for an existing surface. This gives
1046
1047
	the wl_surface the role of a shell surface. If the wl_surface
	already has another role, it raises a protocol error.
1048
1049
1050

	Only one shell surface can be associated with a given surface.
      </description>
1051
1052
      <arg name="id" type="new_id" interface="wl_shell_surface" summary="shell surface to create"/>
      <arg name="surface" type="object" interface="wl_surface" summary="surface to be given the shell surface role"/>
1053
1054
1055
1056
    </request>
  </interface>

  <interface name="wl_shell_surface" version="1">
1057
1058
1059
1060
1061
1062
1063
1064
1065
    <description summary="desktop-style metadata interface">
      An interface that may be implemented by a wl_surface, for
      implementations that provide a desktop-style user interface.

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

      On the server side the object is automatically destroyed when
1066
      the related wl_surface is destroyed. On the client side,
1067
1068
      wl_shell_surface_destroy() must be called before destroying
      the wl_surface object.
1069
1070
    </description>

1071
1072
1073
1074
1075
    <request name="pong">
      <description summary="respond to a ping event">
	A client must respond to a ping event with a pong request or
	the client may be deemed unresponsive.
      </description>
1076
      <arg name="serial" type="uint" summary="serial number of the ping event"/>
1077
1078
    </request>

1079
    <request name="move">
1080
1081
1082
1083
1084
1085
1086
      <description summary="start an interactive move">
	Start a pointer-driven move of the surface.

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

1091
    <enum name="resize" bitfield="true">
1092
1093
1094
1095
1096
1097
      <description summary="edge values for resizing">
	These values are used to indicate which edge of a surface
	is being dragged in a resize operation. The server may
	use this information to adapt its behavior, e.g. choose
	an appropriate cursor image.
      </description>
1098
1099
1100
1101
1102
1103
1104
1105
1106
      <entry name="none" value="0" summary="no edge"/>
      <entry name="top" value="1" summary="top edge"/>
      <entry name="bottom" value="2" summary="bottom edge"/>
      <entry name="left" value="4" summary="left edge"/>
      <entry name="top_left" value="5" summary="top and left edges"/>
      <entry name="bottom_left" value="6" summary="bottom and left edges"/>
      <entry name="right" value="8" summary="right edge"/>
      <entry name="top_right" value="9" summary="top and right edges"/>
      <entry name="bottom_right" value="10" summary="bottom and right edges"/>
1107
1108
    </enum>

1109
    <request name="resize">
1110
1111
1112
1113
1114
1115
1116
      <description summary="start an interactive resize">
	Start a pointer-driven resizing of the surface.

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

1122
    <request name="set_toplevel">
1123
1124
1125
1126
      <description summary="make the surface a toplevel surface">
	Map the surface as a toplevel surface.

	A toplevel surface is not fullscreen, maximized or transient.
1127
1128
1129
      </description>
    </request>

1130
    <enum name="transient" bitfield="true">
1131
1132
1133
1134
      <description summary="details of transient behaviour">
	These flags specify details of the expected behaviour
	of transient surfaces. Used in the set_transient request.
      </description>
1135
1136
1137
      <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
    </enum>

1138
    <request name="set_transient">
1139
      <description summary="make the surface a transient surface">
1140
1141
	Map the surface relative to an existing surface.

1142
	The x and y arguments specify the location of the upper left
1143
	corner of the surface relative to the upper left corner of the
1144
	parent surface, in surface-local coordinates.
1145
1146

	The flags argument controls details of the transient behaviour.
1147
      </description>
1148
1149
1150
1151
      <arg name="parent" type="object" interface="wl_surface" summary="parent surface"/>
      <arg name="x" type="int" summary="surface-local x coordinate"/>
      <arg name="y" type="int" summary="surface-local y coordinate"/>
      <arg name="flags" type="uint" enum="transient" summary="transient surface behavior"/>
1152
1153
    </request>

1154
1155
1156
1157
1158
1159
1160
1161
1162
    <enum name="fullscreen_method">
      <description summary="different method to set the surface fullscreen">
	Hints to indicate to the compositor how to deal with a conflict
	between the dimensions of the surface and the dimensions of the
	output. The compositor is free to ignore this parameter.
      </description>
      <entry name="default" value="0" summary="no preference, apply default policy"/>
      <entry name="scale" value="1" summary="scale, preserve the surface's aspect ratio and center on output"/>
      <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"/>
1163
      <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1164
1165
    </enum>

1166
1167
    <request name="set_fullscreen">
      <description summary="make the surface a fullscreen surface">
1168
	Map the surface as a fullscreen surface.
1169

1170
1171
1172
1173
1174
	If an output parameter is given then the surface will be made
	fullscreen on that output. If the client does not specify the
	output then the compositor will apply its policy - usually
	choosing the output on which the surface has the biggest surface
	area.
1175

1176
1177
1178
	The client may specify a method to resolve a size conflict
	between the output size and the surface size - this is provided
	through the method parameter.
1179

1180
1181
	The framerate parameter is used only when the method is set
	to "driver", to indicate the preferred framerate. A value of 0
1182
	indicates that the client does not care about framerate.  The
1183
1184
<