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