[RFC PATCH wayland-protocols] Introduce logical output protocol for Xwayland

Fri Jun 30 03:31:08 UTC 2017

On Thu, Jun 29, 2017 at 04:44:34PM +0200, Olivier Fourdan wrote:
> This introduces a new protocol for the compositor to describe outputs
> size in a logical way for Xwayland.
> 
> This is needed for X11 applications that would want to configure an X11
> window based on the size of the output, without knowing the output scale
> factor applied by the compositor to the corresponding Xwayland surface.

So, yes, Xwayland needs this, and I see no way around it. On IRC you
raised the question whether this should really be part of wl_output is a
good question indeed. Would it ever be useful for a regular Wayland
client to know about this?

For fullscreening, we already communicate the expected size (in the
surface coordinate space) via the xdg_toplevel.configure event. Knowing
how much space is available on a work space (i.e. possibly useful for
avoiding too big windows) wouldn't be possible as this wouldn't include
panels, launchers etc, nor would the client know on what output it'll be
started (yet at least).

Adding it to wl_output might be fine anyway, as we could refer to it
when talking about how clients should not rely on calculating its own
"output size" by looking at wl_output::mode, wl_output::transform and
wl_output::scale, but we could just as well clarify that they simply
shouldn't.

Anyway, some comments about this proposal below:

> 
> https://bugs.freedesktop.org/show_bug.cgi?id=101436
> 
> Signed-off-by: Olivier Fourdan <ofourdan at redhat.com>
> ---
>  Note: This is what Jonas called "wp_xwayland_configure_screen"
>  in https://bugs.freedesktop.org/show_bug.cgi?id=101436#c5
> 
>  Makefile.am                                        |   1 +
>  unstable/xwayland-logical-output/README            |   5 +
>  .../xwayland-logical-output-unstable-v1.xml        | 101 +++++++++++++++++++++
>  3 files changed, 107 insertions(+)
>  create mode 100644 unstable/xwayland-logical-output/README
>  create mode 100644 unstable/xwayland-logical-output/xwayland-logical-output-unstable-v1.xml
> 
> diff --git a/Makefile.am b/Makefile.am
> index e693afa..e198362 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -12,6 +12,7 @@ unstable_protocols =								\
>  	unstable/tablet/tablet-unstable-v2.xml			                \
>  	unstable/xdg-foreign/xdg-foreign-unstable-v1.xml			\
>  	unstable/idle-inhibit/idle-inhibit-unstable-v1.xml			\
> +	unstable/xwayland-logical-output/xwayland-logical-output-unstable-v1.xml	\
>  	$(NULL)
>  
>  stable_protocols =								\
> diff --git a/unstable/xwayland-logical-output/README b/unstable/xwayland-logical-output/README
> new file mode 100644
> index 0000000..efcaf69
> --- /dev/null
> +++ b/unstable/xwayland-logical-output/README
> @@ -0,0 +1,5 @@
> +Xwayland logical output protocol
> +
> +Maintainers:
> +Olivier Fourdan <ofourdan at redhat.com>
> +
> diff --git a/unstable/xwayland-logical-output/xwayland-logical-output-unstable-v1.xml b/unstable/xwayland-logical-output/xwayland-logical-output-unstable-v1.xml
> new file mode 100644
> index 0000000..2b1d537
> --- /dev/null
> +++ b/unstable/xwayland-logical-output/xwayland-logical-output-unstable-v1.xml
> @@ -0,0 +1,101 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="xwayland_logical_output_unstable_v1">
> +
> +  <copyright>
> +    Copyright © 2017 Red Hat Inc.
> +
> +    Permission is hereby granted, free of charge, to any person obtaining a
> +    copy of this software and associated documentation files (the "Software"),
> +    to deal in the Software without restriction, including without limitation
> +    the rights to use, copy, modify, merge, publish, distribute, sublicense,
> +    and/or sell copies of the Software, and to permit persons to whom the
> +    Software is furnished to do so, subject to the following conditions:
> +
> +    The above copyright notice and this permission notice (including the next
> +    paragraph) shall be included in all copies or substantial portions of the
> +    Software.
> +
> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
> +    DEALINGS IN THE SOFTWARE.
> +  </copyright>
> +
> +  <description summary="Protocol to describe logical output setup for Xwayland">
> +    This optional protocol is application-specific to describe the logical
> +    output setup for Xwayland. It provides a way for the compositor to
> +    provide Xwayland with a specific pre-computed scaled size of the outputs.
> +
> +    The core Wayland interface wl_output lists all outputs and their
> +    modes in hardware units along with the output scaling properties,
> +    but Xwayland surfaces may be treated differently from regular Wayland
> +    surfaces by the compositor, making it impossible for Xwayland to
> +    reliably and consistently report all outputs to X11 clients via either
> +    Xrandr or Xvidmode protocols based solely on the wl_output properties.
> +
> +    For example, for a compositor who does not scale Xwayland surfaces,
> +    the reported output mode can match the hardware units, since the
> +    requested size by X11 clients will match the actual size on the output,
> +    but for another compositor who will scale the Xwayland surfaces, the
> +    reported output size should be scaled down by the output scale factor
> +    so that the resulting size matches the expected requested size by the
> +    X11 client.
> +
> +    On top of that, some compositors implementing fractional scaling may
> +    chose to report a larger scale factor via wl_output scale factor and

chose -> choose

> +    then scale the surface down to achieve the expected fractional scale.
> +
> +    This protocol specifies a way for the compositor to describe the output
> +    size to Xwayland in a way that the X11 clients can use when requesting
> +    a size or position.
> +
> +    Compositors are not required to implement this interface which remains
> +    optional, however when implementing this interface, compositors are
> +    required to restrict access to this application specific protocol to
> +    Xwayland alone.
> +
> +    Warning! The protocol described in this file is experimental and
> +    backward incompatible changes may be made. Backward compatible
> +    changes may be added together with the corresponding interface
> +    version bump.
> +    Backward incompatible changes are done by bumping the version
> +    number in the protocol and interface names and resetting the
> +    interface version. Once the protocol is to be declared stable,
> +    the 'z' prefix and the version number in the protocol and
> +    interface names are removed and the interface version number is
> +    reset.
> +  </description>
> +
> +  <interface name="zwp_xwayland_logical_output" version="1">

Food for thought: if we call this just "zwp_xwayland_output" or
something more generic like that we can potentially cramp more stuff
here that should only be available to Xwayand. Would just have to rename
the event to "logical_geometry".

> +    <description summary="Compositor logical output region">
> +      A zwp_xwayland_logical_output describes part of the output geometry
> +      as exposed to X11 clients by Xwayland.
> +
> +      This typically corresponds to a monitor that displays part of the
> +      compositor space in scaled units.

I think we should refer to it as "compositor space" some how,
rather than "scaled". Whether it is "scaled" in some way or another
may or may not be true. Also, documenting it only in the event below
might be better, so we don't have to repeat things.

> +
> +      This object is published during start up, when a monitor is hot 
> +      plugged or when the logical (scaled) size of the output is changed.

Should we maybe maybe make this a single "manager" kind of thing? The
wl_output is part of the event anyway, so we only need of this object.
We'll then emit events on bind or on when wl_output bound before
wl_output.done.

> +    </description>
> +
> +    <event name="geometry">
> +      <description summary="Logical geometry of the output">
> +	The geometry event describes the logical size of a wl_output.
> +
> +	This event is sent when binding to the xwl_logical_output object
> +	and whenever the logical size changes.

As mentioned, I'd say not talking about "scaled" is better, but rather
talk about coordinate spaces, and how a surface size is represented in
it. wl_output talks about the "compositor space" which is indeed what we
are communicating here, but having an example about how the size of a
surface normally will have corresponding size in the compositor space
would be good.

For example, a surface with the same size as the size advertised here
will normally have the same size as the monitor when displayed could be
such an example.

Jonas

> +      </description>
> +      <arg name="output" type="object" interface="wl_output"
> +           summary="corresponding wl_output"/>
> +      <arg name="width" type="int"
> +           summary="width of the mode in logical (scaled) units"/>
> +      <arg name="height" type="int"
> +           summary="height of the mode in logical (scaled) units"/>
> +    </event>
> +  </interface>
> +
> +</protocol>
> +
> -- 
> 2.9.4
> 
> _______________________________________________
> xorg-devel at lists.x.org: X.Org development
> Archives: http://lists.x.org/archives/xorg-devel
> Info: https://lists.x.org/mailman/listinfo/xorg-devel