wayland.xml 122 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>

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>

86
    <enum name="error">
87 88 89 90 91 92 93 94 95 96
      <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"
	     summary="method doesn't exist on the specified interface"/>
      <entry name="no_memory" value="2"
	     summary="server is out of memory"/>
97 98
      <entry name="implementation" value="3"
	     summary="implementation error in compositor"/>
99
    </enum>
100

101
    <event name="delete_id">
102
      <description summary="acknowledge object ID deletion">
103 104 105
	This event is used internally by the object ID management
	logic.  When a client deletes an object, the server will send
	this event to acknowledge that it has seen the delete request.
106
	When the client receives this event, it will know that it can
107
	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
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.

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>

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

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"/>
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>
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
	The drm format codes match the macros defined in drm_fourcc.h.
297 298 299 300 301 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
	The formats actually supported by the compositor will be
	reported by the format event.
      </description>
      <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"/>
358 359
    </enum>

360 361
    <request name="create_pool">
      <description summary="create a shm pool">
362 363 364 365
	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
366
	descriptor, to use as backing memory for the pool.
367
      </description>
368 369 370
      <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"/>
371
    </request>
372 373

    <event name="format">
374 375 376 377 378
      <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>
379
      <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
380
    </event>
381 382
  </interface>

383
  <interface name="wl_buffer" version="1">
384
    <description summary="content for a wl_surface">
385
      A buffer provides the content for a wl_surface. Buffers are
386
      created through factory interfaces such as wl_drm, wl_shm or
387
      similar. It has a width and a height and can be attached to a
Tiago Vignatti's avatar
Tiago Vignatti committed
388
      wl_surface, but the mechanism by which a client provides and
389
      updates the contents is defined by the buffer factory interface.
390 391 392 393
    </description>

    <request name="destroy" type="destructor">
      <description summary="destroy a buffer">
394 395
	Destroy a buffer. If and how you need to release the backing
	storage is defined by the buffer factory interface.
396 397

	For possible side-effects to a surface, see wl_surface.attach.
398 399
      </description>
    </request>
400

401
    <event name="release">
Tiago Vignatti's avatar
Tiago Vignatti committed
402
      <description summary="compositor releases buffer">
403
	Sent when this wl_buffer is no longer used by the compositor.
404
	The client is now free to reuse or destroy this buffer and its
405 406 407 408 409
	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
410
	reuse the buffer and its backing storage, and does not need a
411
	second buffer for the next surface content update. Typically
412 413 414
	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.
415 416
      </description>
    </event>
417 418
  </interface>

419
  <interface name="wl_data_offer" version="3">
420 421 422 423 424 425 426 427 428
    <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>

429 430 431
    <enum name="error">
      <entry name="invalid_finish" value="0"
	     summary="finish request was called untimely"/>
432 433 434 435 436 437
      <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"/>
438 439
    </enum>

440
    <request name="accept">
441 442 443 444
      <description summary="accept one of the offered mime types">
	Indicate that the client can accept the given mime type, or
	NULL for not accepted.

445 446 447 448 449 450 451 452 453 454 455
	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.
456
      </description>
457 458
      <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"/>
459 460 461
    </request>

    <request name="receive">
462 463
      <description summary="request that the data is transferred">
	To transfer the offered data, the client issues this request
464 465 466 467 468 469
	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.

470
	The receiving client reads from the read end of the pipe until
471
	EOF and then closes its end, at which point the transfer is
472
	complete.
473

474
	This request may happen multiple times for different mime types,
475 476 477
	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.
478
      </description>
479 480
      <arg name="mime_type" type="string" summary="mime type desired by receiver"/>
      <arg name="fd" type="fd" summary="file descriptor for data transfer"/>
481 482
    </request>

483 484 485 486 487
    <request name="destroy" type="destructor">
      <description summary="destroy data offer">
	Destroy the data offer.
      </description>
    </request>
488 489

    <event name="offer">
490
      <description summary="advertise offered mime type">
491 492 493
	Sent immediately after creating the wl_data_offer object.  One
	event per offered mime type.
      </description>
494
      <arg name="mime_type" type="string" summary="offered mime type"/>
495
    </event>
496 497 498 499 500 501 502 503 504 505 506 507 508 509

    <!-- 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
510 511
	wl_data_offer.accept or no action was received through
	wl_data_offer.action.
512 513
      </description>
    </request>
514 515 516 517 518 519

    <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
520
	needs to change the selected action.
521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548

	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,
	the drag source will receive wl_drag_source.cancelled.

	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>
549 550
      <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"/>
      <arg name="preferred_action" type="uint" summary="action preferred by the destination client"/>
551 552 553 554 555 556 557 558
    </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>
559
      <arg name="source_actions" type="uint" summary="actions offered by the data source"/>
560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593
    </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
594
	may potentially choose a different action and/or mime type,
595 596 597 598 599
	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>
600
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
601
    </event>
602 603
  </interface>

604
  <interface name="wl_data_source" version="3">
605 606 607 608 609 610 611
    <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>

612 613 614 615 616 617 618
    <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>

619
    <request name="offer">
620
      <description summary="add an offered mime type">
621
	This request adds a mime type to the set of mime types
622 623 624
	advertised to targets.  Can be called several times to offer
	multiple types.
      </description>
625
      <arg name="mime_type" type="string" summary="mime type offered by the data source"/>
626 627
    </request>

628 629 630 631 632
    <request name="destroy" type="destructor">
      <description summary="destroy the data source">
	Destroy the data source.
      </description>
    </request>
633 634

    <event name="target">
635
      <description summary="a target accepts an offered mime type">
636 637
	Sent when a target accepts pointer_focus or motion events.  If
	a target does not accept any of the offered types, type is NULL.
638 639

	Used for feedback during drag-and-drop.
640
      </description>
641
      <arg name="mime_type" type="string" allow-null="true" summary="mime type accepted by the target"/>
642 643 644
    </event>

    <event name="send">
645
      <description summary="send the data">
646 647 648
	Request for data from the client.  Send the data as the
	specified mime type over the passed file descriptor, then
	close it.
649
      </description>
650 651
      <arg name="mime_type" type="string" summary="mime type for the data"/>
      <arg name="fd" type="fd" summary="file descriptor for the data"/>
652 653
    </event>

654 655
    <event name="cancelled">
      <description summary="selection was cancelled">
656 657 658 659 660
	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
661
	  did not accept any of the mime types offered through
662
	  wl_data_source.target.
663 664 665
	- 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.
666 667 668 669 670
	- 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).

671
	The client should clean up and destroy this data source.
672 673 674 675

	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.
676 677 678
      </description>
    </event>

679 680
    <!-- Version 3 additions -->

681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696
    <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>
697
      <arg name="dnd_actions" type="uint" summary="actions supported by the data source"/>
698 699
    </request>

700 701 702 703
    <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
704
	if the drop destination does not accept any mime type.
705 706 707 708 709 710 711 712 713 714 715 716 717 718

	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.
719 720 721

	If the action used to perform the operation was "move", the
	source can now delete the transferred data.
722 723
      </description>
    </event>
724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752

    <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>
753
      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
754
    </event>
755 756
  </interface>

757
  <interface name="wl_data_device" version="3">
758 759 760 761 762 763 764
    <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>
765 766 767 768 769

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

770
    <request name="start_drag">
771 772
      <description summary="start drag-and-drop operation">
	This request asks the compositor to start a drag-and-drop
773 774 775 776 777 778 779 780 781 782 783 784
	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.

785
	The icon surface is an optional (can be NULL) surface that
786 787
	provides an icon to be moved around with the cursor.  Initially,
	the top-left corner of the icon surface is placed at the cursor
788 789
	hotspot, but subsequent wl_surface.attach request can move the
	relative position. Attach requests must be confirmed with
790
	wl_surface.commit as usual. The icon surface is given the role of
791 792
	a drag-and-drop icon. If the icon surface already has another role,
	it raises a protocol error.
793

794
	The current and pending input regions of the icon wl_surface are
795
	cleared, and wl_surface.set_input_region is ignored until the
796
	wl_surface is no longer used as the icon surface. When the use
797 798
	as an icon ends, the current and pending input regions become
	undefined, and the wl_surface is unmapped.
799
      </description>
800 801 802 803
      <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"/>
804 805 806
    </request>

    <request name="set_selection">
807 808 809 810 811 812
      <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>
813 814
      <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"/>
815 816 817
    </request>

    <event name="data_offer">
818 819 820
      <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
821
	data_device.enter event (for drag-and-drop) or the
822 823 824
	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
825
	mime types it offers.
826
      </description>
827
      <arg name="id" type="new_id" interface="wl_data_offer" summary="the new data_offer object"/>
828 829 830
    </event>

    <event name="enter">
831
      <description summary="initiate drag-and-drop session">
832 833
	This event is sent when an active drag-and-drop pointer enters
	a surface owned by the client.  The position of the pointer at
834 835
	enter time is provided by the x and y arguments, in surface-local
	coordinates.
836
      </description>
837 838 839 840 841 842
      <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"/>
843 844
    </event>

845
    <event name="leave">
846
      <description summary="end drag-and-drop session">
847 848 849 850 851
	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>
852 853

    <event name="motion">
854
      <description summary="drag-and-drop session motion">
855 856
	This event is sent when the drag-and-drop pointer moves within
	the currently focused surface. The new position of the pointer
857
	is provided by the x and y arguments, in surface-local
858 859
	coordinates.
      </description>
860
      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
861 862
      <arg name="x" type="fixed" summary="surface-local x coordinate"/>
      <arg name="y" type="fixed" summary="surface-local y coordinate"/>
863 864
    </event>

865
    <event name="drop">
866
      <description summary="end drag-and-drop session successfully">
867 868
	The event is sent when a drag-and-drop operation is ended
	because the implicit grab is removed.
869 870 871 872 873 874 875 876 877 878 879

	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.
880 881
      </description>
    </event>
882 883

    <event name="selection">
884 885 886 887 888 889 890 891 892
      <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
893 894 895
	or until the client loses keyboard focus.  The client must
	destroy the previous selection data_offer, if any, upon receiving
	this event.
896
      </description>
897 898
      <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
	   summary="selection data_offer object"/>
899
    </event>
900 901 902 903 904 905 906 907

    <!-- Version 2 additions -->

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

910
  <interface name="wl_data_device_manager" version="3">
911
    <description summary="data transfer interface">
912
      The wl_data_device_manager is a singleton global object that
913
      provides access to inter-client data transfer mechanisms such as
914
      copy-and-paste and drag-and-drop.  These mechanisms are tied to
915 916
      a wl_seat and this interface lets a client get a wl_data_device
      corresponding to a wl_seat.
917 918 919 920 921

      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.
922 923
    </description>

924
    <request name="create_data_source">
925
      <description summary="create a new data source">
926
	Create a new data source.
927
      </description>
928
      <arg name="id" type="new_id" interface="wl_data_source" summary="data source to create"/>
929 930 931
    </request>

    <request name="get_data_device">
932
      <description summary="create a new data device">
933
	Create a new data device for a given seat.
934
      </description>
935 936
      <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"/>
937
    </request>
938 939 940 941 942 943 944 945 946 947 948 949 950 951 952

    <!-- 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
953
	reaction to key modifiers being pressed. One common design that
954 955 956 957 958 959 960 961 962 963 964 965 966
	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>
967 968 969 970
      <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"/>
971
    </enum>
972 973
  </interface>

974
  <interface name="wl_shell" version="1">
975 976 977 978 979 980
    <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.
981 982 983

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

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

990
    <request name="get_shell_surface">
991
      <description summary="create a shell surface from a surface">
992
	Create a shell surface for an existing surface. This gives
993 994
	the wl_surface the role of a shell surface. If the wl_surface
	already has another role, it raises a protocol error.
995 996 997

	Only one shell surface can be associated with a given surface.
      </description>
998 999
      <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"/>
1000 1001 1002 1003
    </request>
  </interface>

  <interface name="wl_shell_surface" version="1">
1004 1005 1006 1007 1008 1009 1010 1011 1012
    <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
1013
      the related wl_surface is destroyed. On the client side,
1014 1015
      wl_shell_surface_destroy() must be called before destroying
      the wl_surface object.
1016 1017
    </description>

1018 1019 1020 1021 1022
    <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>
1023
      <arg name="serial" type="uint" summary="serial number of the ping event"/>
1024 1025
    </request>

1026
    <request name="move">
1027 1028 1029 1030 1031 1032 1033
      <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>
1034
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1035
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1036 1037
    </request>

1038
    <enum name="resize" bitfield="true">
1039 1040 1041 1042 1043 1044
      <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>
1045 1046 1047 1048 1049 1050 1051 1052 1053
      <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"/>
1054 1055
    </enum>

1056
    <request name="resize">
1057 1058 1059 1060 1061 1062 1063
      <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>
1064
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1065
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1066
      <arg name="edges" type="uint" enum="resize" summary="which edge or corner is being dragged"/>
1067 1068
    </request>

1069
    <request name="set_toplevel">
1070 1071 1072 1073
      <description summary="make the surface a toplevel surface">
	Map the surface as a toplevel surface.

	A toplevel surface is not fullscreen, maximized or transient.
1074 1075 1076
      </description>
    </request>

1077
    <enum name="transient" bitfield="true">
1078 1079 1080 1081
      <description summary="details of transient behaviour">
	These flags specify details of the expected behaviour
	of transient surfaces. Used in the set_transient request.
      </description>
1082 1083 1084
      <entry name="inactive" value="0x1" summary="do not set keyboard focus"/>
    </enum>

1085
    <request name="set_transient">
1086
      <description summary="make the surface a transient surface">
1087 1088
	Map the surface relative to an existing surface.

1089
	The x and y arguments specify the location of the upper left
1090
	corner of the surface relative to the upper left corner of the
1091
	parent surface, in surface-local coordinates.
1092 1093

	The flags argument controls details of the transient behaviour.
1094
      </description>
1095 1096 1097 1098
      <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"/>
1099 1100
    </request>

1101 1102 1103 1104 1105 1106 1107 1108 1109
    <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"/>
1110
      <entry name="fill" value="3" summary="no upscaling, center on output and add black borders to compensate size mismatch"/>
1111 1112
    </enum>

1113 1114
    <request name="set_fullscreen">
      <description summary="make the surface a fullscreen surface">
1115
	Map the surface as a fullscreen surface.
1116

1117 1118 1119 1120 1121
	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.
1122

1123 1124 1125
	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.
1126

1127 1128
	The framerate parameter is used only when the method is set
	to "driver", to indicate the preferred framerate. A value of 0
1129
	indicates that the client does not care about framerate.  The
1130 1131
	framerate is specified in mHz, that is framerate of 60000 is 60Hz.

1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144
	A method of "scale" or "driver" implies a scaling operation of
	the surface, either via a direct scaling operation or a change of
	the output mode. This will override any kind of output scaling, so
	that mapping a surface with a buffer size equal to the mode can
	fill the screen independent of buffer_scale.

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

1145 1146 1147
	The compositor must reply to this request with a configure event
	with the dimensions for the output on which the surface will
	be made fullscreen.
1148
      </description>
1149 1150 1151 1152
      <arg name="method" type="uint" enum="fullscreen_method" summary="method for resolving size conflict"/>
      <arg name="framerate" type="uint" summary="framerate in mHz"/>
      <arg name="output" type="object" interface="wl_output" allow-null="true"
	   summary="output on which the surface is to be fullscreen"/>
1153 1154
    </request>

1155 1156 1157
    <request name="set_popup">
      <description summary="make the surface a popup surface">
	Map the surface as a popup.
1158

1159 1160
	A popup surface is a transient surface with an added pointer
	grab.
1161

1162 1163 1164 1165
	An existing implicit grab will be changed to owner-events mode,
	and the popup grab will continue after the implicit grab ends
	(i.e. releasing the mouse button does not cause the popup to
	be unmapped).
1166

1167
	The popup grab continues until the window is destroyed or a
1168 1169 1170
	mouse button is pressed in any other client's window. A click
	in any of the client's surfaces is reported as normal, however,
	clicks in other clients' surfaces will be discarded and trigger
1171
	the callback.
1172

1173
	The x and y arguments specify the location of the upper left
1174
	corner of the surface relative to the upper left corner of the
1175
	parent surface, in surface-local coordinates.
1176
      </description>
1177
      <arg name="seat" type="object" interface="wl_seat" summary="seat whose pointer is used"/>
1178
      <arg name="serial" type="uint" summary="serial number of the implicit grab on the pointer"/>
1179 1180 1181 1182
      <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"/>
1183 1184
    </request>

Juan Zhao's avatar
Juan Zhao committed
1185 1186
    <request name="set_maximized">
      <description summary="make the surface a maximized surface">
1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199
	Map the surface as a maximized surface.

	If an output parameter is given then the surface will be
	maximized 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.

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

	A maximized surface typically fills the entire output it is
1200
	bound to, except for desktop elements such as panels. This is
1201 1202 1203 1204
	the main difference between a maximized shell surface and a
	fullscreen shell surface.

	The details depend on the compositor implementation.
Juan Zhao's avatar
Juan Zhao committed
1205
      </description>
1206 1207
      <arg name="output" type="object" interface="wl_output" allow-null="true"
	   summary="output on which the surface is to be maximized"/>
Juan Zhao's avatar
Juan Zhao committed
1208 1209
    </request>

1210 1211
    <request name="set_title">
      <description summary="set surface title">
1212 1213 1214 1215 1216 1217 1218
	Set a short title for the surface.

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

	The string must be encoded in UTF-8.
1219
      </description>
1220
      <arg name="title" type="string" summary="surface title"/>
1221 1222 1223 1224
    </request>

    <request name="set_class">
      <description summary="set surface class">
1225 1226
	Set a class for the surface.

1227
	The surface class identifies the general class of applications
1228 1229 1230
	to which the surface belongs. A common convention is to use the
	file name (or the full path if it is a non-standard location) of
	the application's .desktop file as the class.
1231
      </description>
1232
      <arg name="class_" type="string" summary="surface class"/>
1233 1234
    </request>

1235 1236 1237 1238 1239
    <event name="ping">
      <description summary="ping client">
	Ping a client to check if it is receiving events and sending
	requests. A client is expected to reply with a pong request.
      </description>
1240
      <arg name="serial" type="uint" summary="serial number of the ping"/>
1241 1242
    </event>

1243
    <event name="configure">
1244 1245
      <description summary="suggest resize">
	The configure event asks the client to resize its surface.
1246

1247 1248
	The size is a hint, in the sense that the client is free to
	ignore it if it doesn't resize, pick a smaller size (to
1249 1250 1251 1252 1253 1254 1255 1256 1257 1258
	satisfy aspect ratio or resize in steps of NxM pixels).

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

	The client is free to dismiss all but the last configure
	event it received.
1259 1260

	The width and height arguments specify the size of the window
1261
	in surface-local coordinates.
1262
      </description>
1263 1264 1265
      <arg name="edges" type="uint" enum="resize" summary="how the surface was resized"/>
      <arg name="width" type="int" summary="new width of the surface"/>
      <arg name="height" type="int" summary="new height of the surface"/>
1266
    </event>
1267

1268 1269 1270
    <event name="popup_done">
      <description summary="popup interaction is done">
	The popup_done event is sent out when a popup grab is broken,
1271
	that is, when the user clicks a surface that doesn't belong
1272 1273 1274
	to the client owning the popup surface.
      </description>
    </event>
1275
  </interface>
1276

1277
  <interface name="wl_surface" version="4">
1278
    <description summary="an onscreen surface">
1279
      A surface is a rectangular area that is displayed on the screen.
1280
      It has a location, size and pixel contents.
1281

1282
      The size of a surface (and relative positions on it) is described
1283 1284
      in surface-local coordinates, which may differ from the buffer
      coordinates of the pixel content, in case a buffer_transform
1285 1286
      or a buffer_scale is used.

1287
      A surface without a "role" is fairly useless: a compositor does
1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317
      not know where, when or how to present it. The role is the
      purpose of a wl_surface. Examples of roles are a cursor for a
      pointer (as set by wl_pointer.set_cursor), a drag icon
      (wl_data_device.start_drag), a sub-surface
      (wl_subcompositor.get_subsurface), and a window as defined by a
      shell protocol (e.g. wl_shell.get_shell_surface).

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

      Surface roles are given by requests in other interfaces such as
      wl_pointer.set_cursor. The request should explicitly mention
      that this request gives a role to a wl_surface. Often, this
      request also creates a new protocol object that represents the
      role and adds additional functionality to wl_surface. When a
      client wants to destroy a wl_surface, they must destroy this 'role
      object' before the wl_surface.

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

1320 1321
    <enum name="error">
      <description summary="wl_surface error values">
1322
	These errors can be emitted in response to wl_surface requests.
1323 1324 1325 1326 1327
      </description>
      <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
      <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
    </enum>

1328 1329
    <request name="destroy" type="destructor">
      <description summary="delete surface">
1330
	Deletes the surface and invalidates its object ID.
1331 1332
      </description>
    </request>
1333 1334

    <request name="attach">
1335
      <description summary="set the surface contents">
1336 1337
	Set a buffer as the content of this surface.

1338 1339 1340 1341 1342
	The new size of the surface is calculated based on the buffer
	size transformed by the inverse buffer_transform and the
	inverse buffer_scale. This means that the supplied buffer
	must be an integer multiple of the buffer_scale.

1343
	The x and y arguments specify the location of the new pending
1344
	buffer's upper left corner, relative to the current buffer's upper
1345
	left corner, in surface-local coordinates. In other words, the
1346 1347
	x and y, combined with the new surface size define in which
	directions the surface's size changes.
1348 1349 1350 1351

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

	The initial surface contents are void; there is no content.
1352 1353
	wl_surface.attach assigns the given wl_buffer as the pending
	wl_buffer. wl_surface.commit makes the pending wl_buffer the new
1354 1355 1356
	surface contents, and the size of the surface becomes the size
	calculated from the wl_buffer, as described above. After commit,
	there is no pending buffer until the next attach.
1357 1358

	Committing a pending wl_buffer allows the compositor to read the
1359 1360 1361 1362
	pixels in the wl_buffer. The compositor may access the pixels at
	any time after the wl_surface.commit request. When the compositor
	will not access the pixels anymore, it will send the
	wl_buffer.release event. Only after receiving wl_buffer.release,
1363
	the client may reuse the wl_buffer. A wl_buffer that has been
1364 1365 1366 1367 1368 1369
	attached and then replaced by another attach instead of committed
	will not receive a release event, and is not used by the
	compositor.

	Destroying the wl_buffer after wl_buffer.release does not change
	the surface contents. However, if the client destroys the
1370
	wl_buffer before receiving the wl_buffer.release event, the surface
1371 1372
	contents become undefined immediately.

1373
	If wl_surface.attach is sent with a NULL wl_buffer, the
1374
	following wl_surface.commit will remove the surface content.
1375
      </description>
1376 1377 1378 1379
      <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
	   summary="buffer of surface contents"/>
      <arg name="x" type="int" summary="surface-local x coordinate"/>
      <arg name="y" type="int" summary="surface-local y coordinate"/>
1380 1381 1382
    </request>

    <request name="damage">
1383
      <description summary="mark part of the surface damaged">
1384
	This request is used to describe the regions where the pending
1385
	buffer is different from the current surface contents, and where
1386 1387
	the surface therefore needs to be repainted. The compositor
	ignores the parts of the damage that fall outside of the surface.
1388 1389 1390

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

1391 1392
	The damage rectangle is specified in surface-local coordinates,
	where x and y specify the upper left corner of the damage rectangle.
1393

1394
	The initial value for pending damage is empty: no damage.
1395 1396 1397 1398 1399 1400
	wl_surface.damage adds pending damage: the new pending damage
	is the union of old pending damage and the given rectangle.

	wl_surface.commit assigns pending damage as the current damage,
	and clears pending damage. The server will clear the current
	damage as it repaints the surface.
1401

1402 1403 1404
	Note! New clients should not use this request. Instead damage can be
	posted with wl_surface.damage_buffer which uses buffer coordinates
	instead of surface coordinates.
1405
      </description>
1406 1407 1408 1409
      <arg name="x" type="int" summary="surface-local x coordinate"/>
      <arg name="y" type="int" summary="surface-local y coordinate"/>
      <arg name="width" type="int" summary="width of damage rectangle"/>
      <arg name="height" type="int" summary="height of damage rectangle"/>
1410
    </request>
1411 1412

    <request name="frame">
1413
      <description summary="request a frame throttling hint">
1414
	Request a notification when it is a good time to start drawi