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

Discussion:

Olivier Fourdan

2017-06-29 14:44:34 UTC

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.

https://bugs.freedesktop.org/show_bug.cgi?id=101436

Signed-off-by: Olivier Fourdan <***@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 <***@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
+ 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">
+ <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.
+
+ This object is published during start up, when a monitor is hot
+ plugged or when the logical (scaled) size of the output is changed.
+ </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.
+ </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

Jonas Ådahl

2017-06-30 03:31:08 UTC

Permalink

Post by Olivier Fourdan
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.

Post by Olivier Fourdan
https://bugs.freedesktop.org/show_bug.cgi?id=101436
---
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
+
+
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
+
+ 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

Post by Olivier Fourdan
+ 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".

Post by Olivier Fourdan
+ <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.

Post by Olivier Fourdan
+
+ 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.

Post by Olivier Fourdan
+ </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

Post by Olivier Fourdan
+ </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
_______________________________________________
Archives: http://lists.x.org/archives/xorg-devel
Info: https://lists.x.org/mailman/listinfo/xorg-devel

Olivier Fourdan

2017-06-30 08:38:07 UTC

Permalink

Hi Jonas,

Post by Jonas Ãdahl

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.

Yes, on further consideration and as we discussed earlier today on irc, this might be of interest to some other clients as well, so adding it to the existing wl_output interface makes sense imho, rather than adding an Xwayland specific interface...

Post by Jonas Ãdahl
[...]
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.

I'll take this as an example in the wl_output addition indeed.

Cheers
Olivier

Pekka Paalanen

2017-06-30 09:04:51 UTC

Permalink

On Fri, 30 Jun 2017 04:38:07 -0400 (EDT)

Post by Olivier Fourdan
Hi Jonas,

Post by Jonas Ãdahl

Post by Olivier Fourdan
This introduces a new protocol for the compositor to describe outputs
size in a logical way for Xwayland.

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.

Yes, on further consideration and as we discussed earlier today on
irc, this might be of interest to some other clients as well, so
adding it to the existing wl_output interface makes sense imho,
rather than adding an Xwayland specific interface...

Hi,

please consider that it is impossible to have a stabilization period
for changes to the wl_output interface. What ever you add will be set
in stone immediately, before a considerable user base has had a chance
to try it. There will be no going back once it's there, AFAICT no way
to have it reasonably tested on the field beforehand.

In hindsight I think the position x,y arguments we already have in
wl_output do not belong there. Only traditional 2D desktops can
meaningfully set them. They already break down completely in IVI
systems, where the outputs may be independent in the sense that there
is no path in the logical coordinate system that you could take to
travel from one output to another in a way that would make sense. Not
all systems have a single connected area created from outputs, that
design is quite specific to desktops.

I would like us to be careful with not adding more desktop assumptions
to core Wayland interfaces. Whether this proposal would add some, I
cannot tell yet.

Thanks,
pq

Olivier Fourdan

2017-07-03 08:42:52 UTC

Permalink

Hi Pekka,

Post by Pekka Paalanen
please consider that it is impossible to have a stabilization period
for changes to the wl_output interface. What ever you add will be set
in stone immediately, before a considerable user base has had a chance
to try it. There will be no going back once it's there, AFAICT no way
to have it reasonably tested on the field beforehand.
In hindsight I think the position x,y arguments we already have in
wl_output do not belong there. Only traditional 2D desktops can
meaningfully set them. They already break down completely in IVI
systems, where the outputs may be independent in the sense that there
is no path in the logical coordinate system that you could take to
travel from one output to another in a way that would make sense. Not
all systems have a single connected area created from outputs, that
design is quite specific to desktops.
I would like us to be careful with not adding more desktop assumptions
to core Wayland interfaces. Whether this proposal would add some, I
cannot tell yet.

Yes, you're right, the fact that it's needed primarily for Xwayland, which is a bit of a corner case in itself, and to avoid issues due to the way compositors treat Xwayland surfaces differently, definitely raises concerns about the relevance in wl_output...

So, 3 possibilities so far:

1. Add the logical output in wl_output
Looked like a good idea initially, not so much on further consideration.
pro: It's just an additional event to a existing Wayland core protocol
cons: It's quite limited in usefulness outside of its indented use for Xwayland and remains fairly desktop centric

2. Add a specific Xwayland protocol
pro: It's just an event for now, but this could be extended in the future, but not sure with what.
cons: might seem a bit overkill to add a new protocol just for that, unless it's extended in the future. Might need to be deprecated again if/when option #3 is chosen. Not necessarily a huge problem though if the protocol is limited to Xwayland.

3. Deprecate most of the desktop centric parts of wl_output and add a new wp_output protocol for this intended use, as discussed on irc (*)
pro: would clean up wl_output from most concepts "desktop-ish". Even if size might be less "desktop-ish" that position, Xwayland need both anyway.
cons: might take some considerable time to get to an agreement to such a protocol, could be seen as a longer term solution.

I, for one, has no preference, other than we shall need this as I see no other way to make Xwayland work reliably with the various Wayland compositors implementations that already exist.

Cheers,
Olivier

(*) incidentally, the login who captured the irc logs probably got kicked off irc, there's no more logs of past discussions:
https://people.freedesktop.org/~cbrill/dri-log/index.php?channel=wayland&date=2017-06-30

Pekka Paalanen

2017-07-03 09:25:02 UTC

Permalink

On Mon, 3 Jul 2017 04:42:52 -0400 (EDT)

Post by Olivier Fourdan
1. Add the logical output in wl_output
Looked like a good idea initially, not so much on further
consideration. pro: It's just an additional event to a existing
Wayland core protocol cons: It's quite limited in usefulness outside
of its indented use for Xwayland and remains fairly desktop centric

Right.

Post by Olivier Fourdan
2. Add a specific Xwayland protocol
pro: It's just an event for now, but this could be extended in
the future, but not sure with what. cons: might seem a bit overkill
to add a new protocol just for that, unless it's extended in the
future. Might need to be deprecated again if/when option #3 is
chosen. Not necessarily a huge problem though if the protocol is
limited to Xwayland.

Yup.

Post by Olivier Fourdan
3. Deprecate most of the desktop centric parts of wl_output and add a
new wp_output protocol for this intended use, as discussed on irc (*)
pro: would clean up wl_output from most concepts "desktop-ish". Even
if size might be less "desktop-ish" that position, Xwayland need both
anyway. cons: might take some considerable time to get to an
agreement to such a protocol, could be seen as a longer term solution.

Maybe more along the lines of xdg_output rather than wp_output. Is
there something else desktops would need about outputs? Identification
(machine-wide unique connector name, output number?) has come up
before, in both human-readable description and persistent
machine-parseable forms. Output type (monitor, projector, ...) maybe?

No need to add everything from the start, but I think it could make
sense. Start with the position and size parameters all desktops use
today, but maybe leave them somehow optional, and don't pack more than
one thing (e.g. logical size) per event.

As for deprecation of existing wl_output bits, it could be as simple
start as changing nothing. Maybe add documentation saying that
extensions offer probably better things to use, or that some particular
parameters are not always reliable.

Thanks,
pq

Post by Olivier Fourdan
I, for one, has no preference, other than we shall need this as I see
no other way to make Xwayland work reliably with the various Wayland
compositors implementations that already exist.
Cheers,
Olivier
(*) incidentally, the login who captured the irc logs probably got
https://people.freedesktop.org/~cbrill/dri-log/index.php?channel=wayland&date=2017-06-30

Olivier Fourdan

2017-07-03 09:42:36 UTC

Permalink

Hi Pekka,

Post by Pekka Paalanen
[...]
Maybe more along the lines of xdg_output rather than wp_output. Is
there something else desktops would need about outputs? Identification
(machine-wide unique connector name, output number?) has come up
before, in both human-readable description and persistent
machine-parseable forms. Output type (monitor, projector, ...) maybe?
No need to add everything from the start, but I think it could make
sense. Start with the position and size parameters all desktops use
today, but maybe leave them somehow optional, and don't pack more than
one thing (e.g. logical size) per event.
As for deprecation of existing wl_output bits, it could be as simple
start as changing nothing. Maybe add documentation saying that
extensions offer probably better things to use, or that some particular
parameters are not always reliable.

Right, sounds like a plan, start with a new, very simple xdg_output protocol that (at least) fulfils the needs for Xwayland at first, and extend that over time as people need more.

Cheers,
Olivier

Olivier Fourdan

2017-07-04 10:04:27 UTC

Permalink

Hi

This is a follow-up on my previous attempts at adding a logical size to
outputs (as required for Xwayland).

This introduces the xdg_output protocol aimed at complementing wl_output
for desktop specific concepts.

For now it just adds a couple of events referring to the corresponding
wl_output, but it should be extended in the future as needs arise.

For reference:

https://lists.freedesktop.org/archives/wayland-devel/2017-June/034360.html
https://lists.freedesktop.org/archives/wayland-devel/2017-June/034385.html

Cheers,
Olivier

Olivier Fourdan (1):
Add xdg-output protocol

Makefile.am | 1 +
unstable/xdg-output/README | 4 +
unstable/xdg-output/xdg-output-unstable-v1.xml | 135 +++++++++++++++++++++++++
3 files changed, 140 insertions(+)
create mode 100644 unstable/xdg-output/README
create mode 100644 unstable/xdg-output/xdg-output-unstable-v1.xml

--
2.9.4

Olivier Fourdan

2017-07-04 10:04:28 UTC

Permalink

This protocol aims at describing outputs in way which is more in line
with the concept of an output on desktop oriented systems.

Some information are more specific to the concept of an output for a
desktop oriented system and may not make sense in other applications,
such as IVI systems for example.

The goal is to gradually move the desktop specific concepts out of the
core wl_output protocol.

For now it just features the position and logical size which describe
the output position and size in the global compositor space.

Signed-off-by: Olivier Fourdan <***@redhat.com>
---
Makefile.am | 1 +
unstable/xdg-output/README | 4 +
unstable/xdg-output/xdg-output-unstable-v1.xml | 135 +++++++++++++++++++++++++
3 files changed, 140 insertions(+)
create mode 100644 unstable/xdg-output/README
create mode 100644 unstable/xdg-output/xdg-output-unstable-v1.xml

diff --git a/Makefile.am b/Makefile.am
index e693afa..6c696aa 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/xdg-output/xdg-output-unstable-v1.xml \
$(NULL)

stable_protocols = \
diff --git a/unstable/xdg-output/README b/unstable/xdg-output/README
new file mode 100644
index 0000000..e42b711
--- /dev/null
+++ b/unstable/xdg-output/README
@@ -0,0 +1,4 @@
+xdg_output protocol
+
+Maintainers:
+Olivier Fourdan <***@redhat.com>
diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
new file mode 100644
index 0000000..36e2cee
--- /dev/null
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_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 output regions">
+ This protocol aims at describing outputs in way which is more in line
+ with the concept of an output on desktop oriented systems.
+
+ Some information are more specific to the concept of an output for
+ a desktop oriented system and may not make sense in other applications,
+ such as IVI systems for example.
+
+ Some of the information provided in this protocol might be identical
+ to their counterpart already available from wl_output, in which case
+ the information provided by this protocol should be preferred to their
+ equivalent in wl_output. The goal is to move the desktop specific
+ concepts (such as output location within the global compositor space,
+ the connector name and types, etc.) out of the core wl_output protocol.
+
+ 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="zxdg_output" version="1">
+ <description summary="Compositor logical output region">
+ An xdg_output describes part of the compositor geometry.
+
+ This typically corresponds to a monitor that displays part of the
+ compositor space.
+
+ This object is published during start up, when a monitor is hot
+ plugged or when the logical size of a wl_output is changed.
+ </description>
+
+ <event name="position">
+ <description summary="Position of the output within the global compositor space">
+ The position event describes the location of the wl_output within the
+ global compositor space.
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the location of the output changes within the global compositor
+ space.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="x" type="int"
+ summary="x position within the global compositor space"/>
+ <arg name="y" type="int"
+ summary="y position within the global compositor space"/>
+ </event>
+
+ <event name="logical_size">
+ <description summary="Size of the output in the global compositor space">
+ The logical_size event describes the size of the output in the global
+ compositor space.
+
+ For example, a surface with the size matching the logical_size will
+ have the same size as the corresponding output when displayed.
+
+ Clients such as Xwayland need this to configure their surfaces in
+ the global compositor space as the compositor may apply a different
+ scale from what is advertised by the output scaling property (to
+ achieve fractional scaling, for example).
+
+ The logical size being in global compositor space implies that the
+ client does not need to apply any wl_output.scale or wl_output.rotation
+ to the given logical_size to figure the size of a surface when
+ displayed on the output.
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the logical size of the output changes, either as a result of a
+ change in the applied scale or because of a change in the corresponding
+ output mode (see wl_output.mode) or transform (see wl_output.transform).
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="width" type="int"
+ summary="width of the mode in global compositor space"/>
+ <arg name="height" type="int"
+ summary="height of the mode in global compositor space"/>
+ </event>
+
+ <event name="done">
+ <description summary="Sent all information about output">
+ This event is sent after all other properties have been sent, after
+ binding to an xdg_output interface and after any other property changes
+ done after that.
+
+ This allows changes to the xdg_output properties to be seen as atomic,
+ even if they happen via multiple events.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ </event>
+
+ <request name="release" type="destructor">
+ <description summary="Destroy the xdg_output object">
+ Using this request a client can tell the server that it is not going to
+ use the xdg_output object anymore.
+ </description>
+ </request>
+
+ </interface>
+</protocol>
+

--
2.9.4

Olivier Fourdan

2017-07-04 12:13:43 UTC

Permalink

This protocol aims at describing outputs in way which is more in line
with the concept of an output on desktop oriented systems.

Some information are more specific to the concept of an output for a
desktop oriented system and may not make sense in other applications,
such as IVI systems for example.

The goal is to gradually move the desktop specific concepts out of the
core wl_output protocol.

For now it just features the position and logical size which describe
the output position and size in the global compositor space.

Signed-off-by: Olivier Fourdan <***@redhat.com>
---
v2: use "destroy" instead of "release" for destructor

Makefile.am | 1 +
unstable/xdg-output/README | 4 +
unstable/xdg-output/xdg-output-unstable-v1.xml | 135 +++++++++++++++++++++++++
3 files changed, 140 insertions(+)
create mode 100644 unstable/xdg-output/README
create mode 100644 unstable/xdg-output/xdg-output-unstable-v1.xml

diff --git a/Makefile.am b/Makefile.am
index e693afa..6c696aa 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/xdg-output/xdg-output-unstable-v1.xml \
$(NULL)

stable_protocols = \
diff --git a/unstable/xdg-output/README b/unstable/xdg-output/README
new file mode 100644
index 0000000..e42b711
--- /dev/null
+++ b/unstable/xdg-output/README
@@ -0,0 +1,4 @@
+xdg_output protocol
+
+Maintainers:
+Olivier Fourdan <***@redhat.com>
diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
new file mode 100644
index 0000000..09d03eb
--- /dev/null
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_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 output regions">
+ This protocol aims at describing outputs in way which is more in line
+ with the concept of an output on desktop oriented systems.
+
+ Some information are more specific to the concept of an output for
+ a desktop oriented system and may not make sense in other applications,
+ such as IVI systems for example.
+
+ Some of the information provided in this protocol might be identical
+ to their counterpart already available from wl_output, in which case
+ the information provided by this protocol should be preferred to their
+ equivalent in wl_output. The goal is to move the desktop specific
+ concepts (such as output location within the global compositor space,
+ the connector name and types, etc.) out of the core wl_output protocol.
+
+ 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="zxdg_output" version="1">
+ <description summary="Compositor logical output region">
+ An xdg_output describes part of the compositor geometry.
+
+ This typically corresponds to a monitor that displays part of the
+ compositor space.
+
+ This object is published during start up, when a monitor is hot
+ plugged or when the logical size of a wl_output is changed.
+ </description>
+
+ <event name="position">
+ <description summary="Position of the output within the global compositor space">
+ The position event describes the location of the wl_output within the
+ global compositor space.
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the location of the output changes within the global compositor
+ space.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="x" type="int"
+ summary="x position within the global compositor space"/>
+ <arg name="y" type="int"
+ summary="y position within the global compositor space"/>
+ </event>
+
+ <event name="logical_size">
+ <description summary="Size of the output in the global compositor space">
+ The logical_size event describes the size of the output in the global
+ compositor space.
+
+ For example, a surface with the size matching the logical_size will
+ have the same size as the corresponding output when displayed.
+
+ Clients such as Xwayland need this to configure their surfaces in
+ the global compositor space as the compositor may apply a different
+ scale from what is advertised by the output scaling property (to
+ achieve fractional scaling, for example).
+
+ The logical size being in global compositor space implies that the
+ client does not need to apply any wl_output.scale or wl_output.rotation
+ to the given logical_size to figure the size of a surface when
+ displayed on the output.
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the logical size of the output changes, either as a result of a
+ change in the applied scale or because of a change in the corresponding
+ output mode (see wl_output.mode) or transform (see wl_output.transform).
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="width" type="int"
+ summary="width of the mode in global compositor space"/>
+ <arg name="height" type="int"
+ summary="height of the mode in global compositor space"/>
+ </event>
+
+ <event name="done">
+ <description summary="Sent all information about output">
+ This event is sent after all other properties have been sent, after
+ binding to an xdg_output interface and after any other property changes
+ done after that.
+
+ This allows changes to the xdg_output properties to be seen as atomic,
+ even if they happen via multiple events.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ </event>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the xdg_output object">
+ Using this request a client can tell the server that it is not going to
+ use the xdg_output object anymore.
+ </description>
+ </request>
+
+ </interface>
+</protocol>
+

--
2.9.4

Pekka Paalanen

2017-07-06 08:01:47 UTC

Permalink

On Tue, 4 Jul 2017 14:13:43 +0200

Hi Olivier,

I think I can offer only mostly mechanical comments, as I am still
quite confused about how this will actually be used.

Post by Olivier Fourdan
diff --git a/Makefile.am b/Makefile.am
index e693afa..6c696aa 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/xdg-output/xdg-output-unstable-v1.xml \
$(NULL)
stable_protocols = \
diff --git a/unstable/xdg-output/README b/unstable/xdg-output/README
new file mode 100644
index 0000000..e42b711
--- /dev/null
+++ b/unstable/xdg-output/README
@@ -0,0 +1,4 @@
+xdg_output protocol
+
diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
new file mode 100644
index 0000000..09d03eb
--- /dev/null
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="xdg_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
+
+ 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 output regions">
+ This protocol aims at describing outputs in way which is more in line
+ with the concept of an output on desktop oriented systems.
+
+ Some information are more specific to the concept of an output for
+ a desktop oriented system and may not make sense in other applications,
+ such as IVI systems for example.

Would it be good to explain here, that on desktop the outputs are
expected to form a single connected 2D region? Exactly like RandR
outputs inside a single X11 SCREEN are, IOW window spanning and input
(pointer traveling) wise. Essentially this is that "global compositor
space" implies in practice.

And that each output is rectangular, able to show the complete
described area?

Or are these not actually always true?

Post by Olivier Fourdan
+
+ Some of the information provided in this protocol might be identical
+ to their counterpart already available from wl_output, in which case
+ the information provided by this protocol should be preferred to their
+ equivalent in wl_output. The goal is to move the desktop specific
+ concepts (such as output location within the global compositor space,
+ the connector name and types, etc.) out of the core wl_output protocol.

Good.

Post by Olivier Fourdan
+
+ 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="zxdg_output" version="1">
+ <description summary="Compositor logical output region">
+ An xdg_output describes part of the compositor geometry.
+
+ This typically corresponds to a monitor that displays part of the
+ compositor space.
+
+ This object is published during start up, when a monitor is hot
+ plugged or when the logical size of a wl_output is changed.

Do you mean that zxgd_output interface is a global interface advertised
via wl_registry?

Can you explain why picked this design instead of the (IMO) more
conventional design of advertising a global factory interface in
wl_registry, and the factory interface having a request
get_xdg_output(xdg_output new_id, wl_output base)?

I see some inconveniences with the design of using wl_output as an
event argument:

A client may bind to the same wl_output global many times. This may
happen from independent software components (libraries). The compositor
cannot know which events should be sent with which wl_output
wl_resource, so it must send events for all wl_resources pointing to
the same output. Likewise, client components then must be able to cope
with getting a wl_output proxy they did not create or set up, the first
issue there being identifying whether the user data of the proxy is of
the expected type.

Every single event in the interface must carry an explicit wl_output
argument, while this could be implicit from the xdg_output proxy
instance if it was created for a specific wl_output proxy instance to
begin with.

The more conventional design I mentioned above does impose any
additional roundtrips, the client binding to a wl_output and also
create a xdg_output immediately without waiting for any reply. The
events from both wl_output and xdg_output still come to the client in
the same burst.

Post by Olivier Fourdan
+ </description>
+
+ <event name="position">

To mirror logical_size, should this be called logical_position?

Post by Olivier Fourdan
+ <description summary="Position of the output within the global compositor space">
+ The position event describes the location of the wl_output within the
+ global compositor space.
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the location of the output changes within the global compositor
+ space.
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="x" type="int"
+ summary="x position within the global compositor space"/>
+ <arg name="y" type="int"
+ summary="y position within the global compositor space"/>
+ </event>
+
+ <event name="logical_size">
+ <description summary="Size of the output in the global compositor space">
+ The logical_size event describes the size of the output in the global
+ compositor space.
+
+ For example, a surface with the size matching the logical_size will
+ have the same size as the corresponding output when displayed.
+
+ Clients such as Xwayland need this to configure their surfaces in
+ the global compositor space as the compositor may apply a different
+ scale from what is advertised by the output scaling property (to
+ achieve fractional scaling, for example).

IOW, this event is a different way of sending the output scale,
supporting arbitrary fractional values. Except that we expect most
clients to ignore this and draw with the integer scale factor, instead
of using this information and wp_viewport to realize the fractional
scale factor. Is that correct?

Should there be wording to say that "normal" - however you define that -
clients should not use this information for sizing their buffers and
surfaces? And instead rely on the xdg_shell family of interfaces to
provide a target size.

I suppose we could really use a good write-up (with examples and
pictures!) on how Xwayland and compositors are intended to use this
information, how it affects RandR parameters and how X11 clients will
use this, and how their windows go through Xwayland to the compositor,
to achieve compositor-bypass and hit the direct scanout path in a
mixed-dpi environment. I get dizzy when I try to think of that. IOW, I
feel I cannot really evaluate the suitability of this solution for the
underlying Xwayland issue.

Post by Olivier Fourdan
+
+ The logical size being in global compositor space implies that the
+ client does not need to apply any wl_output.scale or wl_output.rotation
+ to the given logical_size to figure the size of a surface when
+ displayed on the output.

The only way you can actually directly set the size of a surface is via
wp_viewport, and in all other cases the surface size is computed from
the buffer size via the client-set buffer_scale and buffer_transform.

I think you wanted to talk about the output size here, somehow, that
you are given it directly and not need to take into account
output_scale and output_transform. If one then arranges a wl_surface to
have that size, it will be the same size as the output area. So it's
about finding out what size a client wants to have, not how the size of
a wl_surface is determined. Can you see what I mean?

Post by Olivier Fourdan
+
+ The event is sent when binding to the xdg_output interface and whenever
+ the logical size of the output changes, either as a result of a
+ change in the applied scale or because of a change in the corresponding
+ output mode (see wl_output.mode) or transform (see wl_output.transform).

Ok.

Post by Olivier Fourdan
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ <arg name="width" type="int"
+ summary="width of the mode in global compositor space"/>
+ <arg name="height" type="int"
+ summary="height of the mode in global compositor space"/>
+ </event>
+
+ <event name="done">
+ <description summary="Sent all information about output">
+ This event is sent after all other properties have been sent, after
+ binding to an xdg_output interface and after any other property changes
+ done after that.
+
+ This allows changes to the xdg_output properties to be seen as atomic,
+ even if they happen via multiple events.

A good idea.

Post by Olivier Fourdan
+ </description>
+ <arg name="output" type="object" interface="wl_output"
+ summary="corresponding wl_output"/>
+ </event>
+
+ <request name="destroy" type="destructor">
+ <description summary="Destroy the xdg_output object">
+ Using this request a client can tell the server that it is not going to
+ use the xdg_output object anymore.
+ </description>
+ </request>
+
+ </interface>
+</protocol>
+

Thanks,
pq

Olivier Fourdan

2017-07-06 11:53:15 UTC

Permalink

Hi Pekka,

Post by Pekka Paalanen
I think I can offer only mostly mechanical comments, as I am still
quite confused about how this will actually be used.

Well, for now, it will be used by Xwayland, might be of some interest for other clients who might need to know about the output "logical" size (e.g. screencast maybe? not even sure...).

Post by Pekka Paalanen
Would it be good to explain here, that on desktop the outputs are
expected to form a single connected 2D region? Exactly like RandR
outputs inside a single X11 SCREEN are, IOW window spanning and input
(pointer traveling) wise. Essentially this is that "global compositor
space" implies in practice.
And that each output is rectangular, able to show the complete
described area?
Or are these not actually always true?

Yes, I kind of took for granted that those concepts where defined in wl_output, but considering this protocol is aimed at complementing wl_output for the desktop concept of an ouptut, it indeed makes sense to clarify further in xdg_output.