[PATCHv4] Add name event to xdg-output

Submitted by Drew DeVault on April 14, 2018, 2:15 p.m.

Details

Message ID 20180414141508.11628-1-sir@cmpwn.com
State Superseded
Headers show
Series "Add name event to xdg-output" ( rev: 5 ) in Wayland

Not browsing as part of any series.

Commit Message

Drew DeVault April 14, 2018, 2:15 p.m.
Signed-off-by: Drew DeVault <sir@cmpwn.com>
Reviewed-by: Simon Ser <contact@emersion.fr>
---
This revision addresses Pekka's feedback, specifying that the output
name will not change over the lifetime of the xdg_output. This also
answers a question from an earlier email:

On 2018-04-11 11:02 AM, Pekka Paalanen wrote:
> There is still the corner-case of: can removing wl_output global A
> cause the name for wl_output global B to change, but I suppose that
> falls to common sense to not do so strange things.

Since the name can no longer change, this is implicitly addressed.

Also bumps the version on zxdg_output_manager_v1.

 .../xdg-output/xdg-output-unstable-v1.xml     | 22 +++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

Patch hide | download patch | download mbox

diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
index 0c0c481..c0f6b0e 100644
--- a/unstable/xdg-output/xdg-output-unstable-v1.xml
+++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
@@ -54,7 +54,7 @@ 
     reset.
   </description>
 
-  <interface name="zxdg_output_manager_v1" version="1">
+  <interface name="zxdg_output_manager_v1" version="2">
     <description summary="manage xdg_output objects">
       A global factory interface for xdg_output objects.
     </description>
@@ -77,7 +77,7 @@ 
     </request>
   </interface>
 
-  <interface name="zxdg_output_v1" version="1">
+  <interface name="zxdg_output_v1" version="2">
     <description summary="compositor logical output region">
       An xdg_output describes part of the compositor geometry.
 
@@ -157,5 +157,23 @@ 
       </description>
     </event>
 
+    <event name="name" since="2">
+      <description summary="name of this output">
+    Many compositors will assign names to their outputs, show them to the user,
+    allow them to be configured by name, etc. The client may wish to know this
+    name as well to offer the user similar behaviors.
+
+    The naming convention is compositor defined. Each name is unique among all
+    wl_output globals, but if a wl_output global is destroyed the same name may
+    be reused later. The names will also remain consistent across sessions with
+    the same hardware and software configuration.
+
+    The name event is sent after creating an xdg_output (see
+    xdg_output_manager.get_xdg_output). The name does not change over the
+    lifetime of the xdg_output, and this event will not be sent again.
+      </description>
+      <arg name="name" type="string" summary="output name"/>
+    </event>
+
   </interface>
 </protocol>

Comments

Hi,

one elementary detail I have missed is that you have no commit message.
For the record, you should give a justification for why xdg_output
needs a name event added.


On Sat, 14 Apr 2018 10:15:08 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> Reviewed-by: Simon Ser <contact@emersion.fr>
> ---
> This revision addresses Pekka's feedback, specifying that the output
> name will not change over the lifetime of the xdg_output. This also
> answers a question from an earlier email:
> 
> On 2018-04-11 11:02 AM, Pekka Paalanen wrote:
> > There is still the corner-case of: can removing wl_output global A
> > cause the name for wl_output global B to change, but I suppose that
> > falls to common sense to not do so strange things.  
> 
> Since the name can no longer change, this is implicitly addressed.
> 
> Also bumps the version on zxdg_output_manager_v1.
> 
>  .../xdg-output/xdg-output-unstable-v1.xml     | 22 +++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
> index 0c0c481..c0f6b0e 100644
> --- a/unstable/xdg-output/xdg-output-unstable-v1.xml
> +++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
> @@ -54,7 +54,7 @@
>      reset.
>    </description>
>  
> -  <interface name="zxdg_output_manager_v1" version="1">
> +  <interface name="zxdg_output_manager_v1" version="2">
>      <description summary="manage xdg_output objects">
>        A global factory interface for xdg_output objects.
>      </description>
> @@ -77,7 +77,7 @@
>      </request>
>    </interface>
>  
> -  <interface name="zxdg_output_v1" version="1">
> +  <interface name="zxdg_output_v1" version="2">
>      <description summary="compositor logical output region">
>        An xdg_output describes part of the compositor geometry.
>  
> @@ -157,5 +157,23 @@
>        </description>
>      </event>
>  
> +    <event name="name" since="2">

All the versioning stuff seem good now.

> +      <description summary="name of this output">
> +    Many compositors will assign names to their outputs, show them to the user,
> +    allow them to be configured by name, etc. The client may wish to know this
> +    name as well to offer the user similar behaviors.
> +
> +    The naming convention is compositor defined. Each name is unique among all
> +    wl_output globals, but if a wl_output global is destroyed the same name may
> +    be reused later. The names will also remain consistent across sessions with
> +    the same hardware and software configuration.
> +
> +    The name event is sent after creating an xdg_output (see
> +    xdg_output_manager.get_xdg_output). The name does not change over the
> +    lifetime of the xdg_output, and this event will not be sent again.

That's very clear, but is it precisely your intention? Would it make
more sense to define that the name does not change during the lifetime
of the wl_output global instead? That would guarantee that the name
will stay the same for the same wl_output global even if one creates
new xdg_output objects or even restarts the application or starts
another application.

Or do you think that's already implied by the previous paragraph?

Would there be any harm in using the lifetime of the wl_output global
in the wording? I think it would be more clear than the current wording.


Thanks,
pq

> +      </description>
> +      <arg name="name" type="string" summary="output name"/>
> +    </event>
> +
>    </interface>
>  </protocol>
On 2018-04-16 10:53 AM, Pekka Paalanen wrote:
> That's very clear, but is it precisely your intention? Would it make
> more sense to define that the name does not change during the lifetime
> of the wl_output global instead? That would guarantee that the name
> will stay the same for the same wl_output global even if one creates
> new xdg_output objects or even restarts the application or starts
> another application.
> 
> Or do you think that's already implied by the previous paragraph?
> 
> Would there be any harm in using the lifetime of the wl_output global
> in the wording? I think it would be more clear than the current wording.

I have updated it to the following:

+    The name event is sent after creating an xdg_output (see
+    xdg_output_manager.get_xdg_output). This event is only sent once per
+    xdg_output, and the name does not change over the lifetime of the
+    wl_output.

Will wait a while for a little more feedback to come in and then will
send off a new patch.

--
Drew DeVault
On Sat, Apr 14, 2018 at 10:15:08AM -0400, Drew DeVault wrote:
> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> Reviewed-by: Simon Ser <contact@emersion.fr>
> ---
> This revision addresses Pekka's feedback, specifying that the output
> name will not change over the lifetime of the xdg_output. This also
> answers a question from an earlier email:
> 
> On 2018-04-11 11:02 AM, Pekka Paalanen wrote:
> > There is still the corner-case of: can removing wl_output global A
> > cause the name for wl_output global B to change, but I suppose that
> > falls to common sense to not do so strange things.
> 
> Since the name can no longer change, this is implicitly addressed.
> 
> Also bumps the version on zxdg_output_manager_v1.
> 
>  .../xdg-output/xdg-output-unstable-v1.xml     | 22 +++++++++++++++++--
>  1 file changed, 20 insertions(+), 2 deletions(-)
> 
> diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
> index 0c0c481..c0f6b0e 100644
> --- a/unstable/xdg-output/xdg-output-unstable-v1.xml
> +++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
> @@ -54,7 +54,7 @@
>      reset.
>    </description>
>  
> -  <interface name="zxdg_output_manager_v1" version="1">
> +  <interface name="zxdg_output_manager_v1" version="2">
>      <description summary="manage xdg_output objects">
>        A global factory interface for xdg_output objects.
>      </description>
> @@ -77,7 +77,7 @@
>      </request>
>    </interface>
>  
> -  <interface name="zxdg_output_v1" version="1">
> +  <interface name="zxdg_output_v1" version="2">
>      <description summary="compositor logical output region">
>        An xdg_output describes part of the compositor geometry.
>  
> @@ -157,5 +157,23 @@
>        </description>
>      </event>
>  
> +    <event name="name" since="2">
> +      <description summary="name of this output">
> +    Many compositors will assign names to their outputs, show them to the user,
> +    allow them to be configured by name, etc. The client may wish to know this
> +    name as well to offer the user similar behaviors.
> +
> +    The naming convention is compositor defined. Each name is unique among all
> +    wl_output globals, but if a wl_output global is destroyed the same name may
> +    be reused later. The names will also remain consistent across sessions with
> +    the same hardware and software configuration.

I'd still like a bit more clarification about what to expect of this
string. What I'm trying to avoid is one compositor sending "eDP-1" while
another sends "Built-in Display". For example, the first is suitable for
command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
the second is suitable for GUI's (e.g. a widget for selecting what
monitor to play a movie on). If it can be either one, I don't see its
usefulness in a generic client.

I'm suspecting, given what you've written in other E-mails in this
thread that you intend to use this for the "HDMI-1" style names, but at
the same time I've seen the word "human readable" been used which more
commonly refers to "Built-in Display" or "ASUS 24"", which might not
even be unique (there might be two 24 inch ASUS monitors connected).

I don't want to end up with a situation where we get wildly different
results depending on what compositor is the one sending the value.

What I'm assuming is a major reason for keeping things relatively vague
is to make sure that it's not specifically connector data, as that may
not be available for centain types of compositors.


Jonas

> +
> +    The name event is sent after creating an xdg_output (see
> +    xdg_output_manager.get_xdg_output). The name does not change over the
> +    lifetime of the xdg_output, and this event will not be sent again.
> +      </description>
> +      <arg name="name" type="string" summary="output name"/>
> +    </event>
> +
>    </interface>
>  </protocol>
> -- 
> 2.17.0
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
On 2018-04-16  2:57 PM, Jonas Ådahl wrote:
> I'd still like a bit more clarification about what to expect of this
> string. What I'm trying to avoid is one compositor sending "eDP-1" while
> another sends "Built-in Display". For example, the first is suitable for
> command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
> the second is suitable for GUI's (e.g. a widget for selecting what
> monitor to play a movie on). If it can be either one, I don't see its
> usefulness in a generic client.

I'm explicitly not trying to avoid that. To me it's acceptable that one
compositor uses "eDP-1" and another uses "Built-in Display".

> I'm suspecting, given what you've written in other E-mails in this
> thread that you intend to use this for the "HDMI-1" style names, but at
> the same time I've seen the word "human readable" been used which more
> commonly refers to "Built-in Display" or "ASUS 24"", which might not
> even be unique (there might be two 24 inch ASUS monitors connected).

HDMI-1 is human readable to the sort of humans that use my compositor.
Each compositor has a different target audience and should cater their
naming conventions accordingly.

> I don't want to end up with a situation where we get wildly different
> results depending on what compositor is the one sending the value.

Why is this important?

> What I'm assuming is a major reason for keeping things relatively vague
> is to make sure that it's not specifically connector data, as that may
> not be available for centain types of compositors.

Yes, that is a major reason. This also isn't some vague theoretical
compositor either, my own compositor has situations where connector
names don't make sense.

--
Drew DeVault
On Mon, 16 Apr 2018 08:40:52 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> On 2018-04-16 10:53 AM, Pekka Paalanen wrote:
> > That's very clear, but is it precisely your intention? Would it make
> > more sense to define that the name does not change during the lifetime
> > of the wl_output global instead? That would guarantee that the name
> > will stay the same for the same wl_output global even if one creates
> > new xdg_output objects or even restarts the application or starts
> > another application.
> > 
> > Or do you think that's already implied by the previous paragraph?
> > 
> > Would there be any harm in using the lifetime of the wl_output global
> > in the wording? I think it would be more clear than the current wording.  
> 
> I have updated it to the following:
> 
> +    The name event is sent after creating an xdg_output (see
> +    xdg_output_manager.get_xdg_output). This event is only sent once per
> +    xdg_output, and the name does not change over the lifetime of the
> +    wl_output.
> 
> Will wait a while for a little more feedback to come in and then will
> send off a new patch.

Hi Drew,

should it be "wl_output global", to differentiate from "wl_output
object" (wl_proxy)?


Thanks,
pq
On Mon, 16 Apr 2018 11:14:51 -0400
Drew DeVault <sir@cmpwn.com> wrote:

> On 2018-04-16  2:57 PM, Jonas Ådahl wrote:
> > I'd still like a bit more clarification about what to expect of this
> > string. What I'm trying to avoid is one compositor sending "eDP-1" while
> > another sends "Built-in Display". For example, the first is suitable for
> > command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
> > the second is suitable for GUI's (e.g. a widget for selecting what
> > monitor to play a movie on). If it can be either one, I don't see its
> > usefulness in a generic client.  
> 
> I'm explicitly not trying to avoid that. To me it's acceptable that one
> compositor uses "eDP-1" and another uses "Built-in Display".

Hi,

FWIW, I would personally be ok with the vague definition. First, I
don't think that apps that use command line or other textual interface
to specify an output are a thing. We're aiming for a graphical user
interface, after all. Second, even if they are, the app can still offer
shorthands for the possibly complicated "names", e.g. by using the
wl_output global's name (uint). A CLI would need an option to list the
possible outputs for a user to pick in the first place.

The only thing I could criticise there is, is it really "name" or more
like "description"? One still requires them to be unique anyway. I
think calling it "description" would make people expect less of a
standardized or single-alphanumeric-word spelling. But I won't insist
on it.


Thanks,
pq
Replying to both Pekka and Drew at the same time here:

On Mon, Apr 16, 2018 at 11:14:51AM -0400, Drew DeVault wrote:
> On 2018-04-16  2:57 PM, Jonas Ådahl wrote:
> > I'd still like a bit more clarification about what to expect of this
> > string. What I'm trying to avoid is one compositor sending "eDP-1" while
> > another sends "Built-in Display". For example, the first is suitable for
> > command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
> > the second is suitable for GUI's (e.g. a widget for selecting what
> > monitor to play a movie on). If it can be either one, I don't see its
> > usefulness in a generic client.
> 
> I'm explicitly not trying to avoid that. To me it's acceptable that one
> compositor uses "eDP-1" and another uses "Built-in Display".

I'd be more fine if the expectation was clear that the string is
suitable for a graphical user interface and not as a keyword in a
command line or something similar.

> 
> > I'm suspecting, given what you've written in other E-mails in this
> > thread that you intend to use this for the "HDMI-1" style names, but at
> > the same time I've seen the word "human readable" been used which more
> > commonly refers to "Built-in Display" or "ASUS 24"", which might not
> > even be unique (there might be two 24 inch ASUS monitors connected).
> 
> HDMI-1 is human readable to the sort of humans that use my compositor.
> Each compositor has a different target audience and should cater their
> naming conventions accordingly.

How well users are educated doesn't have much to do with writing
specificaions. What we do here is target toolkit and application
developers, not end users.

> 
> > I don't want to end up with a situation where we get wildly different
> > results depending on what compositor is the one sending the value.
> 
> Why is this important?

Because it may result in unnecessary inconveniences and bugs. If
"console-movie-player" starts using a "human readable description" as a command
line argument because it's unclear what to expect from it, but
gnome-shell provides a descriptive string that may very well change,
that is localized etc, it's suddenly very unsuitable for how it the use
case the "consolemovie-player" intended to use it for.

Another thing to note is that a human readable description ala "Built-in
Display" or "Dell HD123456 24"" may not even be unique.

> 
> > What I'm assuming is a major reason for keeping things relatively vague
> > is to make sure that it's not specifically connector data, as that may
> > not be available for centain types of compositors.
> 
> Yes, that is a major reason. This also isn't some vague theoretical
> compositor either, my own compositor has situations where connector
> names don't make sense.

Right, so implying it has anything to do with connector is indeed
unwanted.

> 
> --
> Drew DeVault


On Wed, Apr 18, 2018 at 10:27:51AM +0300, Pekka Paalanen wrote:
> On Mon, 16 Apr 2018 11:14:51 -0400
> Drew DeVault <sir@cmpwn.com> wrote:
> 
> > On 2018-04-16  2:57 PM, Jonas Ådahl wrote:
> > > I'd still like a bit more clarification about what to expect of this
> > > string. What I'm trying to avoid is one compositor sending "eDP-1" while
> > > another sends "Built-in Display". For example, the first is suitable for
> > > command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
> > > the second is suitable for GUI's (e.g. a widget for selecting what
> > > monitor to play a movie on). If it can be either one, I don't see its
> > > usefulness in a generic client.  
> > 
> > I'm explicitly not trying to avoid that. To me it's acceptable that one
> > compositor uses "eDP-1" and another uses "Built-in Display".
> 
> Hi,
> 
> FWIW, I would personally be ok with the vague definition. First, I
> don't think that apps that use command line or other textual interface
> to specify an output are a thing. We're aiming for a graphical user
> interface, after all. Second, even if they are, the app can still offer
> shorthands for the possibly complicated "names", e.g. by using the
> wl_output global's name (uint). A CLI would need an option to list the
> possible outputs for a user to pick in the first place.
> 
> The only thing I could criticise there is, is it really "name" or more
> like "description"? One still requires them to be unique anyway. I
> think calling it "description" would make people expect less of a
> standardized or single-alphanumeric-word spelling. But I won't insist
> on it.

The thing is that what is wanted here, AFAIU, is not a "description" but
really a name that can is potentially somewhat descriptive (as in not
completely arbitrary), but most importantly unique for a
software+hardware configuration (so that, for example one can script a
program to fullscreen itself on the same monitor each time).

What we probably want is rather two things, one "name" that is not
necessarily very descriptive, that is unique, doesn't change unless the
hardware+software configuration changes, and suitable for typing on a
command line (not that we should explicitly in the spec), and another
thing that really is descriptive, not necessarily unique, and
specifically suitable for using as a string in a graphical user
interface. If some compositors provides a "description" that is
identical as "name", so be it, but at least we won't end up with
situations described above.


Jonas

> 
> 
> Thanks,
> pq
On April 18, 2018 9:57 AM, Jonas Ådahl <jadahl@gmail.com> wrote:
> Replying to both Pekka and Drew at the same time here:
> 
> On Mon, Apr 16, 2018 at 11:14:51AM -0400, Drew DeVault wrote:
> > On 2018-04-16  2:57 PM, Jonas Ådahl wrote:
> > > I'd still like a bit more clarification about what to expect of this
> > > string. What I'm trying to avoid is one compositor sending "eDP-1" while
> > > another sends "Built-in Display". For example, the first is suitable for
> > > command line interfaces (e.g. movie-player --fullscreen-on HDMI-2), but
> > > the second is suitable for GUI's (e.g. a widget for selecting what
> > > monitor to play a movie on). If it can be either one, I don't see its
> > > usefulness in a generic client.
> > 
> > I'm explicitly not trying to avoid that. To me it's acceptable that one
> > compositor uses "eDP-1" and another uses "Built-in Display".
> 
> I'd be more fine if the expectation was clear that the string is
> suitable for a graphical user interface and not as a keyword in a
> command line or something similar.
>
> […]
>
> Because it may result in unnecessary inconveniences and bugs. If
> "console-movie-player" starts using a "human readable description" as a command
> line argument because it's unclear what to expect from it, but
> gnome-shell provides a descriptive string that may very well change,
> that is localized etc, it's suddenly very unsuitable for how it the use
> case the "consolemovie-player" intended to use it for.
> 
> Another thing to note is that a human readable description ala "Built-in
> Display" or "Dell HD123456 24"" may not even be unique.

I agree with Jonas here. Maybe we could add two fields:

- "codename", restricted to alphanumeric + hyphens characters (to reflect the
  current informal practice to name outputs like "VGA-1"), specified to be
  unique and persistent. These could be used in configuration files.
- "description", specified to be human-readable and not necessarily unique.
  These could be used in user interfaces.