[PATCH v3 wayland] protocol: specify behavior of get_pointer when capabilities change

[Peter Hutterer]

On Mon, Dec 07, 2015 at 10:12:54AM -0800, Bill Spitzak wrote:
> Again I don't understand why you think it is important to include all this
> confusing text.
> 
> If I am not mistaken, *some* compositors less than version 5 do *NOT* act
> in the old way.
> 
> Therefore no client can rely on this behaviour even if the compositor is
> less than verison 5. And people writing compositors I think should be
> encouraged to write the newest version api. So this text is irrelevant for
> everybody.
> 
> I really would just delete all this text. You want to require clients to
> monitor the capability events and destroy/create the wl_pointer in
> response, so just say that. Stop giving them ways to get around what you
> want.
> 
> I'm not sure if it is possible, but you might want to change creation of
> wl_pointer before the capability is received into an error. I would suspect
> a lot of clients create the wl_seat and then immediately create the
> wl_pointer (and wl_keyboard, etc) without waiting for anything. This is
> technically wrong, and probably a good indicator of a client that will also
> fail to destroy/recreate the wl_pointer correctly.

we have three moving parts. the protocol, the compositor and the client. In
theory, the protocol defines how compositor and client communicate but
it is underdocumented in some cases. This means that compositor and client
interpret the protocol's intention, and as a result any behaviour that is
understood by both is valid protocol.

This does not scale. 

A client that can talk to compositor A may not be able to talk to compositor
B because of different interpretations of the same behaviour. But since the
protocol doesn't specify the intended behaviour, you can't say which
component is buggy. Fast-forward by a couple of years and a couple of
implementations and you now have an unmaintainable mess where you have to
special-case a million different behaviours just because they were all valid
at the time of writing.

Being more precise of the documentation reduces the special cases and makes
it clear what behaviour would be considered a client or compositor bug.
but since we don't have a time machine we need to document the behaviour of
already existing clients, because *they are behaving correctly*.
Few clients are controlled by us, few clients can be easily changed and
updated, so unless you want to explicity break working clients, you
cannot redefine the protocol willy-nilly.

And it's not 'irrelevant'. If you're writing a compositor, you need to be
aware that a client may expect this behaviour and you need to implement it.

Cheers,
   Peter

> 
> 
> On Sun, Dec 6, 2015 at 11:29 PM, Jonas Ådahl <jadahl at gmail.com> wrote:
> 
> > On Mon, Dec 07, 2015 at 03:43:35PM +1000, Peter Hutterer wrote:
> > > Also applies to touch/keyboard
> > >
> > > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> >
> > Looks good to me now, so consider this Reviewed-by: Jonas Ådahl
> > <jadahl at gmail.com>
> >
> >
> > Jonas
> >
> > > ---
> > > Changes to v1:
> > > - reword the paragraph detailing the pre v5 behaviour
> > >
> > >  protocol/wayland.xml | 33 ++++++++++++++++++++++++++++++---
> > >  1 file changed, 30 insertions(+), 3 deletions(-)
> > >
> > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > > index 7ca5049..df8ed19 100644
> > > --- a/protocol/wayland.xml
> > > +++ b/protocol/wayland.xml
> > > @@ -1396,6 +1396,27 @@
> > >       This is emitted whenever a seat gains or loses the pointer,
> > >       keyboard or touch capabilities.  The argument is a capability
> > >       enum containing the complete set of capabilities this seat has.
> > > +
> > > +     When the pointer capability is added, a client may create a
> > > +     wl_pointer object using the wl_seat.get_pointer request. This
> > object
> > > +     will receive pointer events until the capability is removed in the
> > > +     future.
> > > +
> > > +     When the pointer capability is removed, a client should destroy the
> > > +     wl_pointer objects associated with the seat where the capability
> > was
> > > +     removed, using the wl_pointer.release request. No further pointer
> > > +     events will be received on these objects.
> > > +
> > > +     In some compositors, if a seat regains the pointer capability and a
> > > +     client has a previously obtained wl_pointer object of version 4 or
> > > +     less, that object may start sending pointer events again. This
> > > +     behavior is considered a misinterpretation of the intended behavior
> > > +     and must not be relied upon by the client. wl_pointer objects of
> > > +     version 5 or later must not send events if created before the most
> > > +     recent event notifying the client of an added pointer capability.
> > > +
> > > +     The above behavior also applies to wl_keyboard and wl_touch with
> > the
> > > +     keyboard and touch capabilities, respectively.
> > >        </description>
> > >        <arg name="capabilities" type="uint" enum="capability"/>
> > >      </event>
> > > @@ -1406,7 +1427,9 @@
> > >       for this seat.
> > >
> > >       This request only takes effect if the seat has the pointer
> > > -     capability.
> > > +     capability, or has had the pointer capability in the past.
> > > +     It is a protocol violation to issue this request on a seat that has
> > > +     never had the pointer capability.
> > >        </description>
> > >        <arg name="id" type="new_id" interface="wl_pointer"/>
> > >      </request>
> > > @@ -1417,7 +1440,9 @@
> > >       for this seat.
> > >
> > >       This request only takes effect if the seat has the keyboard
> > > -     capability.
> > > +     capability, or has had the keyboard capability in the past.
> > > +     It is a protocol violation to issue this request on a seat that has
> > > +     never had the keyboard capability.
> > >        </description>
> > >        <arg name="id" type="new_id" interface="wl_keyboard"/>
> > >      </request>
> > > @@ -1428,7 +1453,9 @@
> > >       for this seat.
> > >
> > >       This request only takes effect if the seat has the touch
> > > -     capability.
> > > +     capability, or has had the touch capability in the past.
> > > +     It is a protocol violation to issue this request on a seat that has
> > > +     never had the touch capability.
> > >        </description>
> > >        <arg name="id" type="new_id" interface="wl_touch"/>
> > >      </request>
> > > --
> > > 2.5.0
> > >
> >