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