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

[Jonas Ådahl]

On Mon, Dec 07, 2015 at 03:08:19PM +1000, Peter Hutterer wrote:
> 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.

Ah, I see. I suspected so, but it didn't sound like it.

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

It needs to be clear that it's the objects created from the wl_seat
bound to version 5 or later, and only those objects, that may implement
the misbehaviour. Another suggestion that tries to document that:

	In some compositors, if a seat regains the pointer capability
	and a client has a previously obtained a wl_pointer object of
	version 4 or less, that object may start sending pointer events
	again. This behaviour is considered a misinterpretation and must
	not be relied upon by the client. wl_pointer objects of version
	5 or must not send events if created before the most recent
	event notifying the client of an added pointer capability was
	sent.


Jonas

> 
> 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
> > >