From 5eeaac6e1114fddeb36682ef1eead967c06e9b02 Mon Sep 17 00:00:00 2001
From: Julian Orth <ju.orth@gmail.com>
Date: Tue, 27 Feb 2024 14:21:05 +0100
Subject: [PATCH] Clarify behavior of buffer transformations

The new text describes how

- 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.

[mpv]: https://github.com/mpv-player/mpv/pull/12509

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

Signed-off-by: Julian Orth <ju.orth@gmail.com>
---
 protocol/wayland.xml | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index bde7d008..4c376160 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1704,10 +1704,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.
 
@@ -1861,9 +1863,9 @@
 	Before receiving this event the preferred buffer transform for this
 	surface is normal.
 
-	It is intended that transform aware clients use this event to apply the
-	transform to their content and use wl_surface.set_buffer_transform to
-	indicate the transform they have rendered with.
+	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"/>
@@ -2726,10 +2728,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.
@@ -2787,7 +2788,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">