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,15 @@
 
     <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 applied to
+	the buffer relative to the surface. The accepted values for the
+	transform parameter are the values for wl_output.transform.
+
+	The compositor will apply the inverse transformation to the buffer
+	before positioning it in surface space. 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 compositor can display
+	it on the output without applying any rotation or mirroring.
 
 	Buffer transform is double-buffered state, see wl_surface.commit.
 
@@ -2723,9 +2728,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
+	surface space before displaying it on the output device. This is to
+	compensate for the rotation or mirroring of the output.
 
 	The flipped values correspond to an initial flip around a
 	vertical axis followed by rotation.