wayland-protocols/wayland.xml
author Sylvain Becker <sylvain.becker@gmail.com>
Mon, 21 Jan 2019 23:41:43 +0100
changeset 12569 05aff4771d9a
parent 12035 1a7dec71e8e0
permissions -rw-r--r--
Fixed bug 4024 - GameController error "Unexpected controller element"

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