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

[Peter Hutterer]

On Fri, Dec 04, 2015 at 09:01:09AM +0800, Jonas Ådahl wrote:
> On Fri, Dec 04, 2015 at 10:34:34AM +1000, Peter Hutterer wrote:
> > Also applies to touch/keyboard
> > 
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v1:
> > - make it clear that from the next version onwards sending events to an
> >   earlier wl_pointer object is a no-no.
> > 
> >  protocol/wayland.xml | 36 +++++++++++++++++++++++++++++++++---
> >  1 file changed, 33 insertions(+), 3 deletions(-)
> > 
> > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > index 7ca5049..471c1fe 100644
> > --- a/protocol/wayland.xml
> > +++ b/protocol/wayland.xml
> > @@ -1396,6 +1396,30 @@
> >  	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.
> > +
> > +	If a seat regains the pointer capability and a client has a pointer
> > +	object obtained previously, that object may start sending pointer
> > +	events. This behavior was implemented in some compositors supporting
> > +	version 5 or less of the wl_seat interface and is considered a
> 
> 5 -> 4

oh, right. we haven't released v5 yet, sorry.
 
> > +	misinterpretation of the intended behavior.
> 
> tricycleshed: This newline will be ignored when displayed as HTML, so I
> don't think it that good to rely on such formatting.
> 
> > +	This behavior must not be relied upon by the client. A compositor
> > +	implementing version 6 or later of the wl_seat or wl_pointer
> 
> 6 -> 5
> 
> > +	interface must not send events to a wl_pointer object created
> > +	before the most recent event notifying the client of an added
> > +	pointer capability.
> 
> 
> This to me reads like we are now aiming to break those clients, as if
> they happen to connect to a newer compositor supporting version >= 5
> of wl_seat will not continue supporting the old behaviour. Was that the
> conclusion drawn?

don't you get to pick which version you support? so if a client v1 connects
to a compositor supporting v5 you still run v1 of the protocol on that
connection and the compositor needs to be backwards compatible. This is what
the wording was supposed to convey, anyway.

Maybe better to reword this as "If client and compositor use version 5 or
later ...".

Cheers,
   Peter

 
> If so is the case, the text sounds correct to me, but I think it could be
> made to sound more obvious that the behaviour is not supported any more.
> 
> 	In some compositors only supporting version 4 or less of the
> 	wl_seat, if a seat regains the pointer capability and a client
> 	has a pointer object obtained previously, that object may start
> 	sending pointer events. This behaviour is considered a
> 	misinterpretation and must not be relied upon by the client. A
> 	compositor implementing version 5 or later of the wl_seat or
> 	wl_pointer interface must not send events to a wl_pointer object
> 	created before the most recent event notifying the client of an
> 	added pointer capability.
> 
> That way its more up front that its old unsupported behaviour.
> 
> 
> Jonas
> 
> > +
> > +	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 +1430,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 +1443,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 +1456,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
> >