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

[Jonas Ådahl]

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

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

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
>