protocol: warn clients about some wl_output properties

Submitted by Simon Ser on July 3, 2018, 1:01 p.m.

Details

Message ID TERPXp-lnkUlkhHqXdqOfz4Y-3fi2kL9eA_HeJGBn0tdGfC40qDkVv0tMVDpCf5yJGwRq0mnoOlWkFmm8K85ltRrC2mtgncBsoHs-Vzoow4=@emersion.fr
State New
Series "protocol: warn clients about some wl_output properties"
Headers show

Commit Message

Simon Ser July 3, 2018, 1:01 p.m.
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(-)

Patch hide | download patch | download mbox

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"/>

Comments

Philipp Kerling July 3, 2018, 2:28 p.m.
Hi,

one small comment below.

2018-07-03 (火) の 09:01 -0400 に 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.
I'm not sure if that was the original intention, but having the modes
IMO is required to you use the (still unstable) fullscreen-shell
protocol. There you really need this kind of information to make
sensible choices about your window size. Of course, this does not mean
that the mode information must or should be conveyed over wl_output in
general, it could as well be a protocol specific to fullscreen-shell.

> 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"/>