wayland-protocols/wayland.xml
author Ryan C. Gordon <icculus@icculus.org>
Mon, 25 Jun 2018 09:37:25 -0700
changeset 12035 1a7dec71e8e0
permissions -rw-r--r--
wayland: Keep protocol XML files in-tree.

Now you don't need the latest Wayland installed to build with
newer protocols supported, as they'll build correctly; even if
your system can't use them, we can make intelligent decisions
at runtime about what's available on the current machine anyhow.

This also simplifies some logic and possible failure cases in
the configure and CMake scripts.

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