path: root/gnu/packages/patches/qtwayland-update-wayland-xml.patch

from https://salsa.debian.org/qt-kde-team/qt/qtwayland/-/blob/3f43cd57cdf7b2c1e029a6104cb1835ac08b8b34/debian/patches/wayland_1.23.diff

Description: update wayland.xml to version 1.23.0
 This updates only the protocol definition, implementations
 will need additional commits to opt into using them.
Origin: upstream, https://code.qt.io/cgit/qt/qtwayland.git/commit/?id=c2f61bc47baacf2e
Last-Update: 2024-07-30

--- a/src/3rdparty/protocol/wayland.xml
+++ b/src/3rdparty/protocol/wayland.xml
@@ -46,7 +46,7 @@
 	compositor after the callback is fired and as such the client must not
 	attempt to use it after that point.
 
-	The callback_data passed in the callback is the event serial.
+	The callback_data passed in the callback is undefined and should be ignored.
       </description>
       <arg name="callback" type="new_id" interface="wl_callback"
 	   summary="callback object for the sync request"/>
@@ -91,18 +91,20 @@
       <entry name="invalid_object" value="0"
 	     summary="server couldn't find object"/>
       <entry name="invalid_method" value="1"
-	     summary="method doesn't exist on the specified interface"/>
+	     summary="method doesn't exist on the specified interface or malformed request"/>
       <entry name="no_memory" value="2"
 	     summary="server is out of memory"/>
+      <entry name="implementation" value="3"
+	     summary="implementation error in compositor"/>
     </enum>
 
     <event name="delete_id">
       <description summary="acknowledge object ID deletion">
 	This event is used internally by the object ID management
-	logic.  When a client deletes an object, the server will send
-	this event to acknowledge that it has seen the delete request.
-	When the client receives this event, it will know that it can
-	safely reuse the object ID.
+	logic. When a client deletes an object that it had created,
+	the server will send this event to acknowledge that it has
+	seen the delete request. When the client receives this event,
+	it will know that it can safely reuse the object ID.
       </description>
       <arg name="id" type="uint" summary="deleted object ID"/>
     </event>
@@ -175,9 +177,12 @@
     <description summary="callback object">
       Clients can handle the 'done' event to get notified when
       the related request is done.
+
+      Note, because wl_callback objects are created from multiple independent
+      factory interfaces, the wl_callback interface is frozen at version 1.
     </description>
 
-    <event name="done">
+    <event name="done" type="destructor">
       <description summary="done event">
 	Notify the client when the related request is done.
       </description>
@@ -185,7 +190,7 @@
     </event>
   </interface>
 
-  <interface name="wl_compositor" version="4">
+  <interface name="wl_compositor" version="6">
     <description summary="the compositor singleton">
       A compositor.  This object is a singleton global.  The
       compositor is in charge of combining the contents of multiple
@@ -207,7 +212,7 @@
     </request>
   </interface>
 
-  <interface name="wl_shm_pool" version="1">
+  <interface name="wl_shm_pool" version="2">
     <description summary="a shared memory pool">
       The wl_shm_pool object encapsulates a piece of memory shared
       between the compositor and client.  Through the wl_shm_pool
@@ -256,12 +261,18 @@
 	for the pool from the file descriptor passed when the pool was
 	created, but using the new size.  This request can only be
 	used to make the pool bigger.
+
+	This request only changes the amount of bytes that are mmapped
+	by the server and does not touch the file corresponding to the
+	file descriptor passed at creation time. It is the client's
+	responsibility to ensure that the file is at least as big as
+	the new pool size.
       </description>
       <arg name="size" type="int" summary="new size of the pool, in bytes"/>
     </request>
   </interface>
 
-  <interface name="wl_shm" version="1">
+  <interface name="wl_shm" version="2">
     <description summary="shared memory support">
       A singleton global object that provides support for shared
       memory.
@@ -269,8 +280,8 @@
       Clients can create wl_shm_pool objects using the create_pool
       request.
 
-      At connection setup time, the wl_shm object emits one or more
-      format events to inform clients about the valid pixel formats
+      On binding the wl_shm object one or more format events
+      are emitted to inform clients about the valid pixel formats
       that can be used for buffers.
     </description>
 
@@ -291,10 +302,15 @@
 	formats are optional and may not be supported by the particular
 	renderer in use.
 
-	The drm format codes match the macros defined in drm_fourcc.h.
-	The formats actually supported by the compositor will be
-	reported by the format event.
+	The drm format codes match the macros defined in drm_fourcc.h, except
+	argb8888 and xrgb8888. The formats actually supported by the compositor
+	will be reported by the format event.
+
+	For all wl_shm formats and unless specified in another protocol
+	extension, pre-multiplied alpha is used for pixel values.
       </description>
+      <!-- Note to protocol writers: don't update this list manually, instead
+	   run the automated script that keeps it in sync with drm_fourcc.h. -->
       <entry name="argb8888" value="0" summary="32-bit ARGB format, [31:0] A:R:G:B 8:8:8:8 little endian"/>
       <entry name="xrgb8888" value="1" summary="32-bit RGB format, [31:0] x:R:G:B 8:8:8:8 little endian"/>
       <entry name="c8" value="0x20203843" summary="8-bit color index format, [7:0] C"/>
@@ -353,6 +369,71 @@
       <entry name="yvu422" value="0x36315659" summary="3 plane YCbCr format, 2x1 subsampled Cr (1) and Cb (2) planes"/>
       <entry name="yuv444" value="0x34325559" summary="3 plane YCbCr format, non-subsampled Cb (1) and Cr (2) planes"/>
       <entry name="yvu444" value="0x34325659" summary="3 plane YCbCr format, non-subsampled Cr (1) and Cb (2) planes"/>
+      <entry name="r8" value="0x20203852" summary="[7:0] R"/>
+      <entry name="r16" value="0x20363152" summary="[15:0] R little endian"/>
+      <entry name="rg88" value="0x38384752" summary="[15:0] R:G 8:8 little endian"/>
+      <entry name="gr88" value="0x38385247" summary="[15:0] G:R 8:8 little endian"/>
+      <entry name="rg1616" value="0x32334752" summary="[31:0] R:G 16:16 little endian"/>
+      <entry name="gr1616" value="0x32335247" summary="[31:0] G:R 16:16 little endian"/>
+      <entry name="xrgb16161616f" value="0x48345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
+      <entry name="xbgr16161616f" value="0x48344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
+      <entry name="argb16161616f" value="0x48345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
+      <entry name="abgr16161616f" value="0x48344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
+      <entry name="xyuv8888" value="0x56555958" summary="[31:0] X:Y:Cb:Cr 8:8:8:8 little endian"/>
+      <entry name="vuy888" value="0x34325556" summary="[23:0] Cr:Cb:Y 8:8:8 little endian"/>
+      <entry name="vuy101010" value="0x30335556" summary="Y followed by U then V, 10:10:10. Non-linear modifier only"/>
+      <entry name="y210" value="0x30313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 10:6:10:6:10:6:10:6 little endian per 2 Y pixels"/>
+      <entry name="y212" value="0x32313259" summary="[63:0] Cr0:0:Y1:0:Cb0:0:Y0:0 12:4:12:4:12:4:12:4 little endian per 2 Y pixels"/>
+      <entry name="y216" value="0x36313259" summary="[63:0] Cr0:Y1:Cb0:Y0 16:16:16:16 little endian per 2 Y pixels"/>
+      <entry name="y410" value="0x30313459" summary="[31:0] A:Cr:Y:Cb 2:10:10:10 little endian"/>
+      <entry name="y412" value="0x32313459" summary="[63:0] A:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
+      <entry name="y416" value="0x36313459" summary="[63:0] A:Cr:Y:Cb 16:16:16:16 little endian"/>
+      <entry name="xvyu2101010" value="0x30335658" summary="[31:0] X:Cr:Y:Cb 2:10:10:10 little endian"/>
+      <entry name="xvyu12_16161616" value="0x36335658" summary="[63:0] X:0:Cr:0:Y:0:Cb:0 12:4:12:4:12:4:12:4 little endian"/>
+      <entry name="xvyu16161616" value="0x38345658" summary="[63:0] X:Cr:Y:Cb 16:16:16:16 little endian"/>
+      <entry name="y0l0" value="0x304c3059" summary="[63:0]   A3:A2:Y3:0:Cr0:0:Y2:0:A1:A0:Y1:0:Cb0:0:Y0:0  1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
+      <entry name="x0l0" value="0x304c3058" summary="[63:0]   X3:X2:Y3:0:Cr0:0:Y2:0:X1:X0:Y1:0:Cb0:0:Y0:0  1:1:8:2:8:2:8:2:1:1:8:2:8:2:8:2 little endian"/>
+      <entry name="y0l2" value="0x324c3059" summary="[63:0]   A3:A2:Y3:Cr0:Y2:A1:A0:Y1:Cb0:Y0  1:1:10:10:10:1:1:10:10:10 little endian"/>
+      <entry name="x0l2" value="0x324c3058" summary="[63:0]   X3:X2:Y3:Cr0:Y2:X1:X0:Y1:Cb0:Y0  1:1:10:10:10:1:1:10:10:10 little endian"/>
+      <entry name="yuv420_8bit" value="0x38305559"/>
+      <entry name="yuv420_10bit" value="0x30315559"/>
+      <entry name="xrgb8888_a8" value="0x38415258"/>
+      <entry name="xbgr8888_a8" value="0x38414258"/>
+      <entry name="rgbx8888_a8" value="0x38415852"/>
+      <entry name="bgrx8888_a8" value="0x38415842"/>
+      <entry name="rgb888_a8" value="0x38413852"/>
+      <entry name="bgr888_a8" value="0x38413842"/>
+      <entry name="rgb565_a8" value="0x38413552"/>
+      <entry name="bgr565_a8" value="0x38413542"/>
+      <entry name="nv24" value="0x3432564e" summary="non-subsampled Cr:Cb plane"/>
+      <entry name="nv42" value="0x3234564e" summary="non-subsampled Cb:Cr plane"/>
+      <entry name="p210" value="0x30313250" summary="2x1 subsampled Cr:Cb plane, 10 bit per channel"/>
+      <entry name="p010" value="0x30313050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel"/>
+      <entry name="p012" value="0x32313050" summary="2x2 subsampled Cr:Cb plane 12 bits per channel"/>
+      <entry name="p016" value="0x36313050" summary="2x2 subsampled Cr:Cb plane 16 bits per channel"/>
+      <entry name="axbxgxrx106106106106" value="0x30314241" summary="[63:0] A:x:B:x:G:x:R:x 10:6:10:6:10:6:10:6 little endian"/>
+      <entry name="nv15" value="0x3531564e" summary="2x2 subsampled Cr:Cb plane"/>
+      <entry name="q410" value="0x30313451"/>
+      <entry name="q401" value="0x31303451"/>
+      <entry name="xrgb16161616" value="0x38345258" summary="[63:0] x:R:G:B 16:16:16:16 little endian"/>
+      <entry name="xbgr16161616" value="0x38344258" summary="[63:0] x:B:G:R 16:16:16:16 little endian"/>
+      <entry name="argb16161616" value="0x38345241" summary="[63:0] A:R:G:B 16:16:16:16 little endian"/>
+      <entry name="abgr16161616" value="0x38344241" summary="[63:0] A:B:G:R 16:16:16:16 little endian"/>
+      <entry name="c1" value="0x20203143" summary="[7:0] C0:C1:C2:C3:C4:C5:C6:C7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
+      <entry name="c2" value="0x20203243" summary="[7:0] C0:C1:C2:C3 2:2:2:2 four pixels/byte"/>
+      <entry name="c4" value="0x20203443" summary="[7:0] C0:C1 4:4 two pixels/byte"/>
+      <entry name="d1" value="0x20203144" summary="[7:0] D0:D1:D2:D3:D4:D5:D6:D7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
+      <entry name="d2" value="0x20203244" summary="[7:0] D0:D1:D2:D3 2:2:2:2 four pixels/byte"/>
+      <entry name="d4" value="0x20203444" summary="[7:0] D0:D1 4:4 two pixels/byte"/>
+      <entry name="d8" value="0x20203844" summary="[7:0] D"/>
+      <entry name="r1" value="0x20203152" summary="[7:0] R0:R1:R2:R3:R4:R5:R6:R7 1:1:1:1:1:1:1:1 eight pixels/byte"/>
+      <entry name="r2" value="0x20203252" summary="[7:0] R0:R1:R2:R3 2:2:2:2 four pixels/byte"/>
+      <entry name="r4" value="0x20203452" summary="[7:0] R0:R1 4:4 two pixels/byte"/>
+      <entry name="r10" value="0x20303152" summary="[15:0] x:R 6:10 little endian"/>
+      <entry name="r12" value="0x20323152" summary="[15:0] x:R 4:12 little endian"/>
+      <entry name="avuy8888" value="0x59555641" summary="[31:0] A:Cr:Cb:Y 8:8:8:8 little endian"/>
+      <entry name="xvuy8888" value="0x59555658" summary="[31:0] X:Cr:Cb:Y 8:8:8:8 little endian"/>
+      <entry name="p030" value="0x30333050" summary="2x2 subsampled Cr:Cb plane 10 bits per channel packed"/>
     </enum>
 
     <request name="create_pool">
@@ -376,15 +457,36 @@
       </description>
       <arg name="format" type="uint" enum="format" summary="buffer pixel format"/>
     </event>
+
+    <!-- Version 2 additions -->
+
+    <request name="release" type="destructor" since="2">
+      <description summary="release the shm object">
+	Using this request a client can tell the server that it is not going to
+	use the shm object anymore.
+
+	Objects created via this interface remain unaffected.
+      </description>
+    </request>
   </interface>
 
   <interface name="wl_buffer" version="1">
     <description summary="content for a wl_surface">
       A buffer provides the content for a wl_surface. Buffers are
-      created through factory interfaces such as wl_drm, wl_shm or
-      similar. It has a width and a height and can be attached to a
-      wl_surface, but the mechanism by which a client provides and
-      updates the contents is defined by the buffer factory interface.
+      created through factory interfaces such as wl_shm, wp_linux_buffer_params
+      (from the linux-dmabuf protocol extension) or similar. It has a width and
+      a height and can be attached to a wl_surface, but the mechanism by which a
+      client provides and updates the contents is defined by the buffer factory
+      interface.
+
+      Color channels are assumed to be electrical rather than optical (in other
+      words, encoded with a transfer function) unless otherwise specified. If
+      the buffer uses a format that has an alpha channel, the alpha channel is
+      assumed to be premultiplied into the electrical color channel values
+      (after transfer function encoding) unless otherwise specified.
+
+      Note, because wl_buffer objects are created from multiple independent
+      factory interfaces, the wl_buffer interface is frozen at version 1.
     </description>
 
     <request name="destroy" type="destructor">
@@ -507,6 +609,9 @@
 	this request after a NULL mime type has been set in
 	wl_data_offer.accept or no action was received through
 	wl_data_offer.action.
+
+	If wl_data_offer.finish request is received for a non drag and drop
+	operation, the invalid_finish protocol error is raised.
       </description>
     </request>
 
@@ -523,7 +628,7 @@
 
 	This request determines the final result of the drag-and-drop
 	operation. If the end result is that no action is accepted,
-	the drag source will receive wl_drag_source.cancelled.
+	the drag source will receive wl_data_source.cancelled.
 
 	The dnd_actions argument must contain only values expressed in the
 	wl_data_device_manager.dnd_actions enum, and the preferred_action
@@ -544,17 +649,21 @@
 	This request can only be made on drag-and-drop offers, a protocol error
 	will be raised otherwise.
       </description>
-      <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"/>
-      <arg name="preferred_action" type="uint" summary="action preferred by the destination client"/>
+      <arg name="dnd_actions" type="uint" summary="actions supported by the destination client"
+	   enum="wl_data_device_manager.dnd_action"/>
+      <arg name="preferred_action" type="uint" summary="action preferred by the destination client"
+	   enum="wl_data_device_manager.dnd_action"/>
     </request>
 
     <event name="source_actions" since="3">
       <description summary="notify the source-side available actions">
 	This event indicates the actions offered by the data source. It
-	will be sent right after wl_data_device.enter, or anytime the source
-	side changes its offered actions through wl_data_source.set_actions.
+	will be sent immediately after creating the wl_data_offer object,
+	or anytime the source side changes its offered actions through
+	wl_data_source.set_actions.
       </description>
-      <arg name="source_actions" type="uint" summary="actions offered by the data source"/>
+      <arg name="source_actions" type="uint" summary="actions offered by the data source"
+	   enum="wl_data_device_manager.dnd_action"/>
     </event>
 
     <event name="action" since="3">
@@ -595,7 +704,8 @@
 	final wl_data_offer.set_actions and wl_data_offer.accept requests
 	must happen before the call to wl_data_offer.finish.
       </description>
-      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
+      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
+	   enum="wl_data_device_manager.dnd_action"/>
     </event>
   </interface>
 
@@ -692,7 +802,8 @@
 	wl_data_device.start_drag. Attempting to use the source other than
 	for drag-and-drop will raise a protocol error.
       </description>
-      <arg name="dnd_actions" type="uint" summary="actions supported by the data source"/>
+      <arg name="dnd_actions" type="uint" summary="actions supported by the data source"
+	   enum="wl_data_device_manager.dnd_action"/>
     </request>
 
     <event name="dnd_drop_performed" since="3">
@@ -748,7 +859,8 @@
 	Clients can trigger cursor surface changes from this point, so
 	they reflect the current action.
       </description>
-      <arg name="dnd_action" type="uint" summary="action selected by the compositor"/>
+      <arg name="dnd_action" type="uint" summary="action selected by the compositor"
+	   enum="wl_data_device_manager.dnd_action"/>
     </event>
   </interface>
 
@@ -763,6 +875,7 @@
 
     <enum name="error">
       <entry name="role" value="0" summary="given wl_surface has another role"/>
+      <entry name="used_source" value="1" summary="source has already been used"/>
     </enum>
 
     <request name="start_drag">
@@ -774,7 +887,8 @@
 	for the eventual data transfer. If source is NULL, enter, leave
 	and motion events are sent only to the client that initiated the
 	drag and the client is expected to handle the data passing
-	internally.
+	internally. If source is destroyed, the drag-and-drop session will be
+	cancelled.
 
 	The origin surface is the surface where the drag originates and
 	the client must have an active implicit grab that matches the
@@ -783,17 +897,18 @@
 	The icon surface is an optional (can be NULL) surface that
 	provides an icon to be moved around with the cursor.  Initially,
 	the top-left corner of the icon surface is placed at the cursor
-	hotspot, but subsequent wl_surface.attach request can move the
+	hotspot, but subsequent wl_surface.offset requests can move the
 	relative position. Attach requests must be confirmed with
 	wl_surface.commit as usual. The icon surface is given the role of
 	a drag-and-drop icon. If the icon surface already has another role,
 	it raises a protocol error.
 
-	The current and pending input regions of the icon wl_surface are
-	cleared, and wl_surface.set_input_region is ignored until the
-	wl_surface is no longer used as the icon surface. When the use
-	as an icon ends, the current and pending input regions become
-	undefined, and the wl_surface is unmapped.
+	The input region is ignored for wl_surfaces with the role of a
+	drag-and-drop icon.
+
+	The given source may not be used in any further set_selection or
+	start_drag requests. Attempting to reuse a previously-used source
+	may send a used_source error.
       </description>
       <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the eventual transfer"/>
       <arg name="origin" type="object" interface="wl_surface" summary="surface where the drag originates"/>
@@ -807,6 +922,10 @@
 	to the data from the source on behalf of the client.
 
 	To unset the selection, set the source to NULL.
+
+	The given source may not be used in any further set_selection or
+	start_drag requests. Attempting to reuse a previously-used source
+	may send a used_source error.
       </description>
       <arg name="source" type="object" interface="wl_data_source" allow-null="true" summary="data source for the selection"/>
       <arg name="serial" type="uint" summary="serial number of the event that triggered this request"/>
@@ -818,7 +937,7 @@
 	which will subsequently be used in either the
 	data_device.enter event (for drag-and-drop) or the
 	data_device.selection event (for selections).  Immediately
-	following the data_device_data_offer event, the new data_offer
+	following the data_device.data_offer event, the new data_offer
 	object will send out data_offer.offer events to describe the
 	mime types it offers.
       </description>
@@ -888,9 +1007,10 @@
 	immediately before receiving keyboard focus and when a new
 	selection is set while the client has keyboard focus.  The
 	data_offer is valid until a new data_offer or NULL is received
-	or until the client loses keyboard focus.  The client must
-	destroy the previous selection data_offer, if any, upon receiving
-	this event.
+	or until the client loses keyboard focus.  Switching surface with
+	keyboard focus within the same client doesn't mean a new selection
+	will be sent.  The client must destroy the previous selection
+	data_offer, if any, upon receiving this event.
       </description>
       <arg name="id" type="object" interface="wl_data_offer" allow-null="true"
 	   summary="selection data_offer object"/>
@@ -978,7 +1098,8 @@
       a basic surface.
 
       Note! This protocol is deprecated and not intended for production use.
-      For desktop-style user interfaces, use xdg_shell.
+      For desktop-style user interfaces, use xdg_shell. Compositors and clients
+      should not implement this interface.
     </description>
 
     <enum name="error">
@@ -1272,10 +1393,12 @@
     </event>
   </interface>
 
-  <interface name="wl_surface" version="4">
+  <interface name="wl_surface" version="6">
     <description summary="an onscreen surface">
-      A surface is a rectangular area that is displayed on the screen.
-      It has a location, size and pixel contents.
+      A surface is a rectangular area that may be displayed on zero
+      or more outputs, and shown any number of times at the compositor's
+      discretion. They can present wl_buffers, receive user input, and
+      define a local coordinate system.
 
       The size of a surface (and relative positions on it) is described
       in surface-local coordinates, which may differ from the buffer
@@ -1302,8 +1425,9 @@
       that this request gives a role to a wl_surface. Often, this
       request also creates a new protocol object that represents the
       role and adds additional functionality to wl_surface. When a
-      client wants to destroy a wl_surface, they must destroy this 'role
-      object' before the wl_surface.
+      client wants to destroy a wl_surface, they must destroy this role
+      object before the wl_surface, otherwise a defunct_role_object error is
+      sent.
 
       Destroying the role object does not remove the role from the
       wl_surface, but it may stop the wl_surface from "playing the role".
@@ -1321,6 +1445,10 @@
       </description>
       <entry name="invalid_scale" value="0" summary="buffer scale value is invalid"/>
       <entry name="invalid_transform" value="1" summary="buffer transform value is invalid"/>
+      <entry name="invalid_size" value="2" summary="buffer size is invalid"/>
+      <entry name="invalid_offset" value="3" summary="buffer offset is invalid"/>
+      <entry name="defunct_role_object" value="4"
+	     summary="surface was destroyed before its role object"/>
     </enum>
 
     <request name="destroy" type="destructor">
@@ -1335,14 +1463,23 @@
 
 	The new size of the surface is calculated based on the buffer
 	size transformed by the inverse buffer_transform and the
-	inverse buffer_scale. This means that the supplied buffer
-	must be an integer multiple of the buffer_scale.
+	inverse buffer_scale. This means that at commit time the supplied
+	buffer size must be an integer multiple of the buffer_scale. If
+	that's not the case, an invalid_size error is sent.
 
 	The x and y arguments specify the location of the new pending
 	buffer's upper left corner, relative to the current buffer's upper
 	left corner, in surface-local coordinates. In other words, the
 	x and y, combined with the new surface size define in which
-	directions the surface's size changes.
+	directions the surface's size changes. Setting anything other than 0
+	as x and y arguments is discouraged, and should instead be replaced
+	with using the separate wl_surface.offset request.
+
+	When the bound wl_surface version is 5 or higher, passing any
+	non-zero x or y is a protocol violation, and will result in an
+	'invalid_offset' error being raised. The x and y arguments are ignored
+	and do not change the pending state. To achieve equivalent semantics,
+	use wl_surface.offset.
 
 	Surface contents are double-buffered state, see wl_surface.commit.
 
@@ -1363,13 +1500,29 @@
 	will not receive a release event, and is not used by the
 	compositor.
 
+	If a pending wl_buffer has been committed to more than one wl_surface,
+	the delivery of wl_buffer.release events becomes undefined. A well
+	behaved client should not rely on wl_buffer.release events in this
+	case. Alternatively, a client could create multiple wl_buffer objects
+	from the same backing storage or use wp_linux_buffer_release.
+
 	Destroying the wl_buffer after wl_buffer.release does not change
-	the surface contents. However, if the client destroys the
-	wl_buffer before receiving the wl_buffer.release event, the surface
-	contents become undefined immediately.
+	the surface contents. Destroying the wl_buffer before wl_buffer.release
+	is allowed as long as the underlying buffer storage isn't re-used (this
+	can happen e.g. on client process termination). However, if the client
+	destroys the wl_buffer before receiving the wl_buffer.release event and
+	mutates the underlying buffer storage, the surface contents become
+	undefined immediately.
 
 	If wl_surface.attach is sent with a NULL wl_buffer, the
 	following wl_surface.commit will remove the surface content.
+
+	If a pending wl_buffer has been destroyed, the result is not specified.
+	Many compositors are known to remove the surface content on the following
+	wl_surface.commit, but this behaviour is not universal. Clients seeking to
+	maximise compatibility should not destroy pending buffers and should
+	ensure that they explicitly remove content from surfaces, even after
+	destroying buffers.
       </description>
       <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
 	   summary="buffer of surface contents"/>
@@ -1397,9 +1550,9 @@
 	and clears pending damage. The server will clear the current
 	damage as it repaints the surface.
 
-	Alternatively, damage can be posted with wl_surface.damage_buffer
-	which uses buffer coordinates instead of surface coordinates,
-	and is probably the preferred and intuitive way of doing this.
+	Note! New clients should not use this request. Instead damage can be
+	posted with wl_surface.damage_buffer which uses buffer coordinates
+	instead of surface coordinates.
       </description>
       <arg name="x" type="int" summary="surface-local x coordinate"/>
       <arg name="y" type="int" summary="surface-local y coordinate"/>
@@ -1509,16 +1662,18 @@
       <description summary="commit pending surface state">
 	Surface state (input, opaque, and damage regions, attached buffers,
 	etc.) is double-buffered. Protocol requests modify the pending state,
-	as opposed to the current state in use by the compositor. A commit
-	request atomically applies all pending state, replacing the current
-	state. After commit, the new pending state is as documented for each
-	related request.
-
-	On commit, a pending wl_buffer is applied first, and all other state
-	second. This means that all coordinates in double-buffered state are
-	relative to the new wl_buffer coming into use, except for
-	wl_surface.attach itself. If there is no pending wl_buffer, the
-	coordinates are relative to the current surface contents.
+	as opposed to the active state in use by the compositor.
+
+	A commit request atomically creates a content update from the pending
+	state, even if the pending state has not been touched. The content
+	update is placed in a queue until it becomes active. After commit, the
+	new pending state is as documented for each related request.
+
+	When the content update is applied, the wl_buffer is applied before all
+	other state. This means that all coordinates in double-buffered state
+	are relative to the newly attached wl_buffers, except for
+	wl_surface.attach itself. If there is no newly attached wl_buffer, the
+	coordinates are relative to the previous content update.
 
 	All requests that need a commit to become effective are documented
 	to affect double-buffered state.
@@ -1543,6 +1698,12 @@
 	This is emitted whenever a surface's creation, movement, or resizing
 	results in it no longer having any part of it within the scanout region
 	of an output.
+
+	Clients should not use the number of outputs the surface is on for frame
+	throttling purposes. The surface might be hidden even if no leave event
+	has been sent, and the compositor might expect new surface content
+	updates even if no enter event has been sent. The frame event should be
+	used instead.
       </description>
       <arg name="output" type="object" interface="wl_output" summary="output left by the surface"/>
     </event>
@@ -1551,10 +1712,12 @@
 
     <request name="set_buffer_transform" since="2">
       <description summary="sets the buffer transformation">
-	This request sets an optional transformation on how the compositor
-	interprets the contents of the buffer attached to the surface. The
-	accepted values for the transform parameter are the values for
-	wl_output.transform.
+	This request sets the transformation that the client has already applied
+	to the content of the buffer. The accepted values for the transform
+	parameter are the values for wl_output.transform.
+
+	The compositor applies the inverse of this transformation whenever it
+	uses the buffer contents.
 
 	Buffer transform is double-buffered state, see wl_surface.commit.
 
@@ -1610,11 +1773,11 @@
 	a buffer that is larger (by a factor of scale in each dimension)
 	than the desired surface size.
 
-	If scale is not positive the invalid_scale protocol error is
+	If scale is not greater than 0 the invalid_scale protocol error is
 	raised.
       </description>
       <arg name="scale" type="int"
-	   summary="positive scale for interpreting buffer contents"/>
+	   summary="scale for interpreting buffer contents"/>
     </request>
 
     <!-- Version 4 additions -->
@@ -1658,9 +1821,66 @@
       <arg name="width" type="int" summary="width of damage rectangle"/>
       <arg name="height" type="int" summary="height of damage rectangle"/>
     </request>
+
+    <!-- Version 5 additions -->
+
+    <request name="offset" since="5">
+      <description summary="set the surface contents offset">
+	The x and y arguments specify the location of the new pending
+	buffer's upper left corner, relative to the current buffer's upper
+	left corner, in surface-local coordinates. In other words, the
+	x and y, combined with the new surface size define in which
+	directions the surface's size changes.
+
+	Surface location offset is double-buffered state, see
+	wl_surface.commit.
+
+	This request is semantically equivalent to and the replaces the x and y
+	arguments in the wl_surface.attach request in wl_surface versions prior
+	to 5. See wl_surface.attach for details.
+      </description>
+      <arg name="x" type="int" summary="surface-local x coordinate"/>
+      <arg name="y" type="int" summary="surface-local y coordinate"/>
+    </request>
+
+    <!-- Version 6 additions -->
+
+    <event name="preferred_buffer_scale" since="6">
+      <description summary="preferred buffer scale for the surface">
+	This event indicates the preferred buffer scale for this surface. It is
+	sent whenever the compositor's preference changes.
+
+	Before receiving this event the preferred buffer scale for this surface
+	is 1.
+
+	It is intended that scaling aware clients use this event to scale their
+	content and use wl_surface.set_buffer_scale to indicate the scale they
+	have rendered with. This allows clients to supply a higher detail
+	buffer.
+
+	The compositor shall emit a scale value greater than 0.
+      </description>
+      <arg name="factor" type="int" summary="preferred scaling factor"/>
+    </event>
+
+    <event name="preferred_buffer_transform" since="6">
+      <description summary="preferred buffer transform for the surface">
+	This event indicates the preferred buffer transform for this surface.
+	It is sent whenever the compositor's preference changes.
+
+	Before receiving this event the preferred buffer transform for this
+	surface is normal.
+
+	Applying this transformation to the surface buffer contents and using
+	wl_surface.set_buffer_transform might allow the compositor to use the
+	surface buffer more efficiently.
+      </description>
+      <arg name="transform" type="uint" enum="wl_output.transform"
+	   summary="preferred transform"/>
+    </event>
    </interface>
 
-  <interface name="wl_seat" version="6">
+  <interface name="wl_seat" version="9">
     <description summary="group of input devices">
       A seat is a group of keyboards, pointer and touch devices. This
       object is published as a global during start up, or when such a
@@ -1678,6 +1898,14 @@
       <entry name="touch" value="4" summary="the seat has touch devices"/>
     </enum>
 
+    <enum name="error">
+      <description summary="wl_seat error values">
+	These errors can be emitted in response to wl_seat requests.
+      </description>
+      <entry name="missing_capability" value="0"
+	     summary="get_pointer, get_keyboard or get_touch called on seat without the matching capability"/>
+    </enum>
+
     <event name="capabilities">
       <description summary="seat capabilities changed">
 	This is emitted whenever a seat gains or loses the pointer,
@@ -1716,7 +1944,8 @@
 	This request only takes effect if the seat has the pointer
 	capability, or has had the pointer capability in the past.
 	It is a protocol violation to issue this request on a seat that has
-	never had the pointer capability.
+	never had the pointer capability. The missing_capability error will
+	be sent in this case.
       </description>
       <arg name="id" type="new_id" interface="wl_pointer" summary="seat pointer"/>
     </request>
@@ -1729,7 +1958,8 @@
 	This request only takes effect if the seat has the keyboard
 	capability, or has had the keyboard capability in the past.
 	It is a protocol violation to issue this request on a seat that has
-	never had the keyboard capability.
+	never had the keyboard capability. The missing_capability error will
+	be sent in this case.
       </description>
       <arg name="id" type="new_id" interface="wl_keyboard" summary="seat keyboard"/>
     </request>
@@ -1742,7 +1972,8 @@
 	This request only takes effect if the seat has the touch
 	capability, or has had the touch capability in the past.
 	It is a protocol violation to issue this request on a seat that has
-	never had the touch capability.
+	never had the touch capability. The missing_capability error will
+	be sent in this case.
       </description>
       <arg name="id" type="new_id" interface="wl_touch" summary="seat touch interface"/>
     </request>
@@ -1751,9 +1982,22 @@
 
     <event name="name" since="2">
       <description summary="unique identifier for this seat">
-	In a multiseat configuration this can be used by the client to help
-	identify which physical devices the seat represents. Based on
-	the seat configuration used by the compositor.
+	In a multi-seat configuration the seat name can be used by clients to
+	help identify which physical devices the seat represents.
+
+	The seat name is a UTF-8 string with no convention defined for its
+	contents. Each name is unique among all wl_seat globals. The name is
+	only guaranteed to be unique for the current compositor instance.
+
+	The same seat names are used for all clients. Thus, the name can be
+	shared across processes to refer to a specific wl_seat global.
+
+	The name event is sent after binding to the seat global. This event is
+	only sent once per seat object, and the name does not change over the
+	lifetime of the wl_seat global.
+
+	Compositors may re-use the same seat name if the wl_seat global is
+	destroyed and re-created later.
       </description>
       <arg name="name" type="string" summary="seat identifier"/>
     </event>
@@ -1769,7 +2013,7 @@
 
   </interface>
 
-  <interface name="wl_pointer" version="6">
+  <interface name="wl_pointer" version="9">
     <description summary="pointer input device">
       The wl_pointer interface represents one or more input devices,
       such as mice, which control the pointer location and pointer_focus
@@ -1804,20 +2048,22 @@
 	where (x, y) are the coordinates of the pointer location, in
 	surface-local coordinates.
 
-	On surface.attach requests to the pointer surface, hotspot_x
+	On wl_surface.offset requests to the pointer surface, hotspot_x
 	and hotspot_y are decremented by the x and y parameters
-	passed to the request. Attach must be confirmed by
+	passed to the request. The offset must be applied by
 	wl_surface.commit as usual.
 
 	The hotspot can also be updated by passing the currently set
 	pointer surface to this request with new values for hotspot_x
 	and hotspot_y.
 
-	The current and pending input regions of the wl_surface are
-	cleared, and wl_surface.set_input_region is ignored until the
-	wl_surface is no longer used as the cursor. When the use as a
-	cursor ends, the current and pending input regions become
-	undefined, and the wl_surface is unmapped.
+	The input region is ignored for wl_surfaces with the role of
+	a cursor. When the use as a cursor ends, the wl_surface is
+	unmapped.
+
+	The serial parameter must match the latest wl_pointer.enter
+	serial number sent to the client. Otherwise the request will be
+	ignored.
       </description>
       <arg name="serial" type="uint" summary="serial number of the enter event"/>
       <arg name="surface" type="object" interface="wl_surface" allow-null="true"
@@ -2058,13 +2304,16 @@
       <arg name="axis" type="uint" enum="axis" summary="the axis stopped with this event"/>
     </event>
 
-    <event name="axis_discrete" since="5">
+    <event name="axis_discrete" since="5" deprecated-since="8">
       <description summary="axis click event">
 	Discrete step information for scroll and other axes.
 
 	This event carries the axis value of the wl_pointer.axis event in
 	discrete steps (e.g. mouse wheel clicks).
 
+	This event is deprecated with wl_pointer version 8 - this event is not
+	sent to clients supporting version 8 or later.
+
 	This event does not occur on its own, it is coupled with a
 	wl_pointer.axis event that represents this axis value on a
 	continuous scale. The protocol guarantees that each axis_discrete
@@ -2072,7 +2321,8 @@
 	axis number within the same wl_pointer.frame. Note that the protocol
 	allows for other events to occur between the axis_discrete and
 	its coupled axis event, including other axis_discrete or axis
-	events.
+	events. A wl_pointer.frame must not contain more than one axis_discrete
+	event per axis type.
 
 	This event is optional; continuous scrolling devices
 	like two-finger scrolling on touchpads do not have discrete
@@ -2090,12 +2340,106 @@
       <arg name="axis" type="uint" enum="axis" summary="axis type"/>
       <arg name="discrete" type="int" summary="number of steps"/>
     </event>
+
+    <event name="axis_value120" since="8">
+      <description summary="axis high-resolution scroll event">
+	Discrete high-resolution scroll information.
+
+	This event carries high-resolution wheel scroll information,
+	with each multiple of 120 representing one logical scroll step
+	(a wheel detent). For example, an axis_value120 of 30 is one quarter of
+	a logical scroll step in the positive direction, a value120 of
+	-240 are two logical scroll steps in the negative direction within the
+	same hardware event.
+	Clients that rely on discrete scrolling should accumulate the
+	value120 to multiples of 120 before processing the event.
+
+	The value120 must not be zero.
+
+	This event replaces the wl_pointer.axis_discrete event in clients
+	supporting wl_pointer version 8 or later.
+
+	Where a wl_pointer.axis_source event occurs in the same
+	wl_pointer.frame, the axis source applies to this event.
+
+	The order of wl_pointer.axis_value120 and wl_pointer.axis_source is
+	not guaranteed.
+      </description>
+      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
+      <arg name="value120" type="int" summary="scroll distance as fraction of 120"/>
+    </event>
+
+    <!-- Version 9 additions -->
+
+    <enum name="axis_relative_direction">
+      <description summary="axis relative direction">
+	This specifies the direction of the physical motion that caused a
+	wl_pointer.axis event, relative to the wl_pointer.axis direction.
+      </description>
+      <entry name="identical" value="0"
+	  summary="physical motion matches axis direction"/>
+      <entry name="inverted" value="1"
+	  summary="physical motion is the inverse of the axis direction"/>
+    </enum>
+
+    <event name="axis_relative_direction" since="9">
+      <description summary="axis relative physical direction event">
+	Relative directional information of the entity causing the axis
+	motion.
+
+	For a wl_pointer.axis event, the wl_pointer.axis_relative_direction
+	event specifies the movement direction of the entity causing the
+	wl_pointer.axis event. For example:
+	- if a user's fingers on a touchpad move down and this
+	  causes a wl_pointer.axis vertical_scroll down event, the physical
+	  direction is 'identical'
+	- if a user's fingers on a touchpad move down and this causes a
+	  wl_pointer.axis vertical_scroll up scroll up event ('natural
+	  scrolling'), the physical direction is 'inverted'.
+
+	A client may use this information to adjust scroll motion of
+	components. Specifically, enabling natural scrolling causes the
+	content to change direction compared to traditional scrolling.
+	Some widgets like volume control sliders should usually match the
+	physical direction regardless of whether natural scrolling is
+	active. This event enables clients to match the scroll direction of
+	a widget to the physical direction.
+
+	This event does not occur on its own, it is coupled with a
+	wl_pointer.axis event that represents this axis value.
+	The protocol guarantees that each axis_relative_direction event is
+	always followed by exactly one axis event with the same
+	axis number within the same wl_pointer.frame. Note that the protocol
+	allows for other events to occur between the axis_relative_direction
+	and its coupled axis event.
+
+	The axis number is identical to the axis number in the associated
+	axis event.
+
+	The order of wl_pointer.axis_relative_direction,
+	wl_pointer.axis_discrete and wl_pointer.axis_source is not
+	guaranteed.
+      </description>
+      <arg name="axis" type="uint" enum="axis" summary="axis type"/>
+      <arg name="direction" type="uint" enum="axis_relative_direction"
+	  summary="physical direction relative to axis motion"/>
+    </event>
   </interface>
 
-  <interface name="wl_keyboard" version="6">
+  <interface name="wl_keyboard" version="9">
     <description summary="keyboard input device">
       The wl_keyboard interface represents one or more keyboards
       associated with a seat.
+
+      Each wl_keyboard has the following logical state:
+
+      - an active surface (possibly null),
+      - the keys currently logically down,
+      - the active modifiers,
+      - the active group.
+
+      By default, the active surface is null, the keys currently logically down
+      are empty, the active modifiers and the active group are 0.
     </description>
 
     <enum name="keymap_format">
@@ -2106,13 +2450,17 @@
       <entry name="no_keymap" value="0"
 	     summary="no keymap; client must understand how to interpret the raw keycode"/>
       <entry name="xkb_v1" value="1"
-	     summary="libxkbcommon compatible; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
+	     summary="libxkbcommon compatible, null-terminated string; to determine the xkb keycode, clients must add 8 to the key event keycode"/>
     </enum>
 
     <event name="keymap">
       <description summary="keyboard mapping">
 	This event provides a file descriptor to the client which can be
-	memory-mapped to provide a keyboard mapping description.
+	memory-mapped in read-only mode to provide a keyboard mapping
+	description.
+
+	From version 7 onwards, the fd must be mapped with MAP_PRIVATE by
+	the recipient, as MAP_SHARED may fail.
       </description>
       <arg name="format" type="uint" enum="keymap_format" summary="keymap format"/>
       <arg name="fd" type="fd" summary="keymap file descriptor"/>
@@ -2123,10 +2471,18 @@
       <description summary="enter event">
 	Notification that this seat's keyboard focus is on a certain
 	surface.
+
+	The compositor must send the wl_keyboard.modifiers event after this
+	event.
+
+	In the wl_keyboard logical state, this event sets the active surface to
+	the surface argument and the keys currently logically down to the keys
+	in the keys argument. The compositor must not send this event if the
+	wl_keyboard already had an active surface immediately before this event.
       </description>
       <arg name="serial" type="uint" summary="serial number of the enter event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface gaining keyboard focus"/>
-      <arg name="keys" type="array" summary="the currently pressed keys"/>
+      <arg name="keys" type="array" summary="the keys currently logically down"/>
     </event>
 
     <event name="leave">
@@ -2136,6 +2492,11 @@
 
 	The leave notification is sent before the enter notification
 	for the new focus.
+
+	In the wl_keyboard logical state, this event resets all values to their
+	defaults. The compositor must not send this event if the active surface
+	of the wl_keyboard was not equal to the surface argument immediately
+	before this event.
       </description>
       <arg name="serial" type="uint" summary="serial number of the leave event"/>
       <arg name="surface" type="object" interface="wl_surface" summary="surface that lost keyboard focus"/>
@@ -2154,6 +2515,21 @@
 	A key was pressed or released.
 	The time argument is a timestamp with millisecond
 	granularity, with an undefined base.
+
+	The key is a platform-specific key code that can be interpreted
+	by feeding it to the keyboard mapping (see the keymap event).
+
+	If this event produces a change in modifiers, then the resulting
+	wl_keyboard.modifiers event must be sent after this event.
+
+	In the wl_keyboard logical state, this event adds the key to the keys
+	currently logically down (if the state argument is pressed) or removes
+	the key from the keys currently logically down (if the state argument is
+	released). The compositor must not send this event if the wl_keyboard
+	did not have an active surface immediately before this event. The
+	compositor must not send this event if state is pressed (resp. released)
+	and the key was already logically down (resp. was not logically down)
+	immediately before this event.
       </description>
       <arg name="serial" type="uint" summary="serial number of the key event"/>
       <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
@@ -2165,6 +2541,17 @@
       <description summary="modifier and group state">
 	Notifies clients that the modifier and/or group state has
 	changed, and it should update its local state.
+
+	The compositor may send this event without a surface of the client
+	having keyboard focus, for example to tie modifier information to
+	pointer focus instead. If a modifier event with pressed modifiers is sent
+	without a prior enter event, the client can assume the modifier state is
+	valid until it receives the next wl_keyboard.modifiers event. In order to
+	reset the modifier state again, the compositor can send a
+	wl_keyboard.modifiers event with no pressed modifiers.
+
+	In the wl_keyboard logical state, this event updates the modifiers and
+	group.
       </description>
       <arg name="serial" type="uint" summary="serial number of the modifiers event"/>
       <arg name="mods_depressed" type="uint" summary="depressed modifiers"/>
@@ -2203,7 +2590,7 @@
     </event>
   </interface>
 
-  <interface name="wl_touch" version="6">
+  <interface name="wl_touch" version="9">
     <description summary="touchscreen input device">
       The wl_touch interface represents a touchscreen
       associated with a seat.
@@ -2272,6 +2659,8 @@
 	currently active on this client's surface. The client is
 	responsible for finalizing the touch points, future touch points on
 	this surface may reuse the touch point ID.
+
+	No frame event is required after the cancel event.
       </description>
     </event>
 
@@ -2347,7 +2736,7 @@
     </event>
   </interface>
 
-  <interface name="wl_output" version="3">
+  <interface name="wl_output" version="4">
     <description summary="compositor output region">
       An output describes part of the compositor geometry.  The
       compositor works in the 'compositor coordinate system' and an
@@ -2371,10 +2760,9 @@
     </enum>
 
     <enum name="transform">
-      <description summary="transform from framebuffer to output">
-	This describes the transform that a compositor will apply to a
-	surface to compensate for the rotation or mirroring of an
-	output device.
+      <description summary="transformation applied to buffer contents">
+	This describes transformations that clients and compositors apply to
+	buffer contents.
 
 	The flipped values correspond to an initial flip around a
 	vertical axis followed by rotation.
@@ -2402,6 +2790,20 @@
 
 	The physical size can be set to zero if it doesn't make sense for this
 	output (e.g. for projectors or virtual outputs).
+
+	The geometry event will be followed by a done event (starting from
+	version 2).
+
+	Clients should use wl_surface.preferred_buffer_transform instead of the
+	transform advertised by this event to find the preferred buffer
+	transform to use for a surface.
+
+	Note: wl_output only advertises partial information about the output
+	position and identification. Some compositors, for instance those not
+	implementing a desktop-style output layout or those exposing virtual
+	outputs, might fake this information. Instead of using x and y, clients
+	should use xdg_output.logical_position. Instead of using make and model,
+	clients should use name and description.
       </description>
       <arg name="x" type="int"
 	   summary="x position within the global compositor space"/>
@@ -2418,7 +2820,7 @@
       <arg name="model" type="string"
 	   summary="textual description of the model"/>
       <arg name="transform" type="int" enum="transform"
-	   summary="transform that maps framebuffer to output"/>
+	   summary="additional transformation applied to buffer contents during presentation"/>
     </event>
 
     <enum name="mode" bitfield="true">
@@ -2442,11 +2844,31 @@
 	current.  In other words, the current mode is always the last
 	mode that was received with the current flag set.
 
+	Non-current modes are deprecated. A compositor can decide to only
+	advertise the current mode and never send other modes. Clients
+	should not rely on non-current modes.
+
 	The size of a mode is given in physical hardware units of
 	the output device. This is not necessarily the same as
 	the output size in the global compositor space. For instance,
 	the output may be scaled, as described in wl_output.scale,
-	or transformed, as described in wl_output.transform.
+	or transformed, as described in wl_output.transform. Clients
+	willing to retrieve the output size in the global compositor
+	space should use xdg_output.logical_size instead.
+
+	The vertical refresh rate can be set to zero if it doesn't make
+	sense for this output (e.g. for virtual outputs).
+
+	The mode event will be followed by a done event (starting from
+	version 2).
+
+	Clients should not use the refresh rate to schedule frames. Instead,
+	they should use the wl_surface.frame event or the presentation-time
+	protocol.
+
+	Note: this information is not always meaningful for all outputs. Some
+	compositors, such as those exposing virtual outputs, might fake the
+	refresh rate or the size.
       </description>
       <arg name="flags" type="uint" enum="mode" summary="bitfield of mode flags"/>
       <arg name="width" type="int" summary="width of the mode in hardware units"/>
@@ -2471,8 +2893,9 @@
 	This event contains scaling geometry information
 	that is not in the geometry event. It may be sent after
 	binding the output object or if the output scale changes
-	later. If it is not sent, the client should assume a
-	scale of 1.
+	later. The compositor will emit a non-zero, positive
+	value for scale. If it is not sent, the client should
+	assume a scale of 1.
 
 	A scale larger than 1 means that the compositor will
 	automatically scale surface buffers by this amount
@@ -2480,12 +2903,11 @@
 	displays where applications rendering at the native
 	resolution would be too small to be legible.
 
-	It is intended that scaling aware clients track the
-	current output of a surface, and if it is on a scaled
-	output it should use wl_surface.set_buffer_scale with
-	the scale of the output. That way the compositor can
-	avoid scaling the surface, and the client can supply
-	a higher detail image.
+	Clients should use wl_surface.preferred_buffer_scale
+	instead of this event to find the preferred buffer
+	scale to use for a surface.
+
+	The scale event will be followed by a done event.
       </description>
       <arg name="factor" type="int" summary="scaling factor of output"/>
     </event>
@@ -2498,6 +2920,62 @@
 	use the output object anymore.
       </description>
     </request>
+
+    <!-- Version 4 additions -->
+
+    <event name="name" since="4">
+      <description summary="name of this output">
+	Many compositors will assign user-friendly names to their outputs, show
+	them to the user, allow the user to refer to an output, etc. The client
+	may wish to know this name as well to offer the user similar behaviors.
+
+	The name is a UTF-8 string with no convention defined for its contents.
+	Each name is unique among all wl_output globals. The name is only
+	guaranteed to be unique for the compositor instance.
+
+	The same output name is used for all clients for a given wl_output
+	global. Thus, the name can be shared across processes to refer to a
+	specific wl_output global.
+
+	The name is not guaranteed to be persistent across sessions, thus cannot
+	be used to reliably identify an output in e.g. configuration files.
+
+	Examples of names include 'HDMI-A-1', 'WL-1', 'X11-1', etc. However, do
+	not assume that the name is a reflection of an underlying DRM connector,
+	X11 connection, etc.
+
+	The name event is sent after binding the output object. This event is
+	only sent once per output object, and the name does not change over the
+	lifetime of the wl_output global.
+
+	Compositors may re-use the same output name if the wl_output global is
+	destroyed and re-created later. Compositors should avoid re-using the
+	same name if possible.
+
+	The name event will be followed by a done event.
+      </description>
+      <arg name="name" type="string" summary="output name"/>
+    </event>
+
+    <event name="description" since="4">
+      <description summary="human-readable description of this output">
+	Many compositors can produce human-readable descriptions of their
+	outputs. The client may wish to know this description as well, e.g. for
+	output selection purposes.
+
+	The description is a UTF-8 string with no convention defined for its
+	contents. The description is not guaranteed to be unique among all
+	wl_output globals. Examples might include 'Foocorp 11" Display' or
+	'Virtual X11 output via :1'.
+
+	The description event is sent after binding the output object and
+	whenever the description changes. The description is optional, and may
+	not be sent at all.
+
+	The description event will be followed by a done event.
+      </description>
+      <arg name="description" type="string" summary="output description"/>
+    </event>
   </interface>
 
   <interface name="wl_region" version="1">
@@ -2569,6 +3047,8 @@
     <enum name="error">
       <entry name="bad_surface" value="0"
 	     summary="the to-be sub-surface is invalid"/>
+      <entry name="bad_parent" value="1"
+	     summary="the to-be sub-surface parent is invalid"/>
     </enum>
 
     <request name="get_subsurface">
@@ -2578,14 +3058,18 @@
 	plain wl_surface into a sub-surface.
 
 	The to-be sub-surface must not already have another role, and it
-	must not have an existing wl_subsurface object. Otherwise a protocol
-	error is raised.
+	must not have an existing wl_subsurface object. Otherwise the
+	bad_surface protocol error is raised.
 
 	Adding sub-surfaces to a parent is a double-buffered operation on the
 	parent (see wl_surface.commit). The effect of adding a sub-surface
 	becomes visible on the next time the state of the parent surface is
 	applied.
 
+	The parent surface must not be one of the child surface's descendants,
+	and the parent must be different from the child surface, otherwise the
+	bad_parent protocol error is raised.
+
 	This request modifies the behaviour of wl_surface.commit request on
 	the sub-surface, see the documentation on wl_subsurface interface.
       </description>
@@ -2621,7 +3105,7 @@
       wl_surface state directly. A sub-surface is initially in the
       synchronized mode.
 
-      Sub-surfaces have also other kind of state, which is managed by
+      Sub-surfaces also have another kind of state, which is managed by
       wl_subsurface requests, as opposed to wl_surface requests. This
       state includes the sub-surface position relative to the parent
       surface (wl_subsurface.set_position), and the stacking order of
@@ -2640,15 +3124,18 @@
       synchronized mode, and then assume that all its child and grand-child
       sub-surfaces are synchronized, too, without explicitly setting them.
 
-      If the wl_surface associated with the wl_subsurface is destroyed, the
-      wl_subsurface object becomes inert. Note, that destroying either object
-      takes effect immediately. If you need to synchronize the removal
-      of a sub-surface to the parent surface update, unmap the sub-surface
-      first by attaching a NULL wl_buffer, update parent, and then destroy
-      the sub-surface.
+      Destroying a sub-surface takes effect immediately. If you need to
+      synchronize the removal of a sub-surface to the parent surface update,
+      unmap the sub-surface first by attaching a NULL wl_buffer, update parent,
+      and then destroy the sub-surface.
 
       If the parent wl_surface object is destroyed, the sub-surface is
       unmapped.
+
+      A sub-surface never has the keyboard focus of any seat.
+
+      The wl_surface.offset request is ignored: clients must use set_position
+      instead to move the sub-surface.
     </description>
 
     <request name="destroy" type="destructor">
@@ -2656,8 +3143,7 @@
 	The sub-surface interface is removed from the wl_surface object
 	that was turned into a sub-surface with a
 	wl_subcompositor.get_subsurface request. The wl_surface's association
-	to the parent is deleted, and the wl_surface loses its role as
-	a sub-surface. The wl_surface is unmapped immediately.
+	to the parent is deleted. The wl_surface is unmapped immediately.
       </description>
     </request>
 
@@ -2675,9 +3161,7 @@
 	surface area. Negative values are allowed.
 
 	The scheduled coordinates will take effect whenever the state of the
-	parent surface is applied. When this happens depends on whether the
-	parent surface is in synchronized mode or not. See
-	wl_subsurface.set_sync and wl_subsurface.set_desync for details.
+	parent surface is applied.
 
 	If more than one set_position request is invoked by the client before
 	the commit of the parent surface, the position of a new request always
@@ -2700,9 +3184,7 @@
 	The z-order is double-buffered. Requests are handled in order and
 	applied immediately to a pending state. The final pending state is
 	copied to the active state the next time the state of the parent
-	surface is applied. When this happens depends on whether the parent
-	surface is in synchronized mode or not. See wl_subsurface.set_sync and
-	wl_subsurface.set_desync for details.
+	surface is applied.
 
 	A new sub-surface is initially added as the top-most in the stack
 	of its siblings and parent.