[PATCH] protocol: warn clients about some wl_output properties

[Simon Ser]

All wl_output properties don't always make sense for all
compositors.

Some compositors might not implement a "global compositor space",
(e.g. 3D compositors) in which case properties like x and y don't
make sense.

Some compositors might expose virtual outputs, in which case modes,
make and model are not relevant.

In a lot of these situations, information from xdg_output is better
suited.
---
Regular clients shouldn't use most of these properties anyway.
wl_output is not meant to be an output management protocol. wl_output
should only expose enough information to allow clients to display
themselves properly. I don't think there's any legitimate use-case
to read geometry.{x,y,make,model} and modes for regular clients. Some
clients (e.g. xwayland) need more information and support an additional
protocol (xdg-output) that's better suited.

Because of this, compositors should be allowed to fake these properties,
and clients should be prepared to receive fake data.

I'm not completely happy with this patch. IMHO we should completely
deprecate modes because I really fail to see how clients will use this
information properly. To do so we can probably just bump the protocol
version and make this event optional?

 protocol/wayland.xml | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index b5662e0..b4ffcd5 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -2399,6 +2399,13 @@
 	The geometry event describes geometric properties of the output.
 	The event is sent when binding to the output object and whenever
 	any of the properties change.
+
+	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 xdg_output.name and xdg_output.description.
       </description>
       <arg name="x" type="int"
 	   summary="x position within the global compositor space"/>
@@ -2443,7 +2450,13 @@
 	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.
+
+	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"/>
-- 
2.18.0