Clarify behavior of buffer transformations

The new text describes how

• Weston
• Mutter
• Plasma
• Sway 1.8
• Jay

behave.

Sway 1.9 flipped the behavior of 90 degree and 270 degree set_buffer_transform requests. mpv also changed the behavior of its vo_wayland_dmabuf backend which makes it only work correctly on sway 1.9.

It seems that the previous text was open to interpretation or at least caused some amount of confusion.

---

Consider the following example:

• The user has rotated his display 90 degrees clockwise.
• The compositor will rotate surface space 90 degrees counter-clockwise during compositing. It reports wl_output::transform = 90.
• The client has rotated its buffer 90 degrees counter-clockwise relative to its surface. It sets wl_surface::set_buffer_transform = 90.
• During compositing, the compositor does not have to apply any rotation to the buffer.

protocol/wayland.xml

@@ -1702,10 +1702,14 @@
 
     <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.
+
+	If the surface is displayed on an output and the client set a buffer
+	transformation that is identical to the transformation of the output,
+	then the two transformations cancel each other out, and the buffer
+	contents can be sent to the display as-is.
 
 	Buffer transform is double-buffered state, see wl_surface.commit.
 
@@ -2723,9 +2727,9 @@
 
     <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.
+	This describes the transformation that the compositor will apply to
+	the surface before displaying it on the output device. This is to
+	compensate for the rotation or mirroring of the device.
 
 	The flipped values correspond to an initial flip around a
 	vertical axis followed by rotation.
@@ -2783,7+2787,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"/>
     </event>
 
     <enum name="mode" bitfield="true">