[PATCH v5] protocol: Extend wl_touch with touchpoint shape and orientation

Thu Nov 3 00:13:05 UTC 2016

On Wed, Nov 02, 2016 at 12:37:18PM -0700, Dennis Kempin wrote:
> This CL updates the wl_touch interface with a shape and
> orientation event.
> The shape/orientation of a touch point is not relevant for most UI
> applications, but allows a better experience in some cases
> such as drawing apps.
> 
> The events are used by the compositor to inform the client
> about changes in the shape and orientation of a touchpoint, which is
> approximated by an ellipse and it's angle to the y-axis.
> 
> The event is optional and only sent when compositor and the
> touch device support this type of information. The client is
> responsible for making a reasonable assumption about the
> touch shape if no shape is reported.
> 
> Signed-off-by: Dennis Kempin <denniskempin at google.com>

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>

though I'd like to see two bits below added:

> ---
>  protocol/wayland.xml | 73 +++++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 69 insertions(+), 4 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 6c6d078..06134bd 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1669,7 +1669,7 @@
>      </request>
>     </interface>
>  
> -  <interface name="wl_seat" version="5">
> +  <interface name="wl_seat" version="6">
>      <description summary="group of input devices">
>        A seat is a group of keyboards, pointer and touch devices. This
>        object is published as a global during start up, or when such a
> @@ -1778,7 +1778,7 @@
>  
>    </interface>
>  
> -  <interface name="wl_pointer" version="5">
> +  <interface name="wl_pointer" version="6">
>      <description summary="pointer input device">
>        The wl_pointer interface represents one or more input devices,
>        such as mice, which control the pointer location and pointer_focus
> @@ -2092,7 +2092,7 @@
>      </event>
>    </interface>
>  
> -  <interface name="wl_keyboard" version="5">
> +  <interface name="wl_keyboard" version="6">
>      <description summary="keyboard input device">
>        The wl_keyboard interface represents one or more keyboards
>        associated with a seat.
> @@ -2256,7 +2256,13 @@
>  
>      <event name="frame">
>        <description summary="end of touch frame event">
> -	Indicates the end of a contact point list.
> +	Indicates the end of a set of events that logically belong together.
> +	A client is expected to accumulate the data in all events within the
> +	frame before proceeding.
> +	A wl_touch.frame terminates at least one event but otherwise no
> +	guarantee is provided about the set of events within a frame.
> +	A client must assume that any state not updated in a frame is unchanged
> +	from the previously known state.
>        </description>
>      </event>
>  
> @@ -2276,6 +2282,65 @@
>      <request name="release" type="destructor" since="3">
>        <description summary="release the touch object"/>
>      </request>
> +
> +    <!-- Version 6 additions -->
> +
> +    <event name="shape" since="6">
> +      <description summary="update shape of touch point">
> +	Sent when a touchpoint has changed its shape.
> +
> +	This event event does not occur on its own. It is sent before a
> +	wl_touch.frame event and carries the new shape information for
> +	any previously reported, or new touch points of that frame.
> +
> +	Other events describing the touch point such as wl_touch.down,
> +	wl_touch.motion or wl_touch.orientation may be sent within the
> +	same wl_touch.frame. A client should treat these events as a single
> +	logical touch point update. The order of wl_touch.shape,
> +	wl_touch.orientation and wl_touch.motion is not guaranteed.

A wl_touch.down event is guaranteed to occur before the first
wl_touch.shape event for this touch ID but both events may occur within the
same wl_touch.frame.

> +
> +	A touchpoint shape is approximated by an ellipse through the major and
> +	minor axis length. The major axis length describes the longer diameter
> +	of the ellipse, while the minor axis length describes the shorter
> +	diameter. Major and minor are orthogonal and both are specified in
> +	surface coordinates. The center of the ellipse is always at the
> +	touchpoint location as reported by wl_touch.down or wl_touch.move.
> +
> +	This event is only sent by the compositor if the touch device supports shape
> +	reports. The client has to make reasonable assumptions about the shape if
> +	it did not receive this event.

> +      </description>
> +      <arg name="id" type="int" summary="the unique ID of this touch point"/>
> +      <arg name="major" type="fixed" summary="length of the major axis in surface-local coordinates"/>
> +      <arg name="minor" type="fixed" summary="length of the minor axis in surface-local coordinates"/>
> +    </event>
> +
> +    <event name="orientation" since="6">
> +      <description summary="update orientation of touch point">
> +	Sent when a touchpoint has changed its orientation.
> +
> +	This event event does not occur on its own. It is sent before a
> +	wl_touch.frame event and carries the new shape information for
> +	any previously reported, or new touch points of that frame.
> +
> +	Other events describing the touch point such as wl_touch.down,
> +	wl_touch.motion or wl_touch.shape may be sent within the
> +	same wl_touch.frame. A client should treat these events as a single
> +	logical touch point update. The order of wl_touch.shape,
> +	wl_touch.orientation and wl_touch.motion is not guaranteed.

A wl_touch.down event is guaranteed to occur before the first
wl_touch.orientation event for this touch ID but both events may occur
within the same wl_touch.frame.

(both of these just ensure that wl_touch.down remains the single arbiter of
touch IDs)

Cheers,
   Peter

> +
> +	The orientation describes the clockwise angle of touchpoints major axis to
> +	the positive surface y-axis and is normalized to the -180 to +180 degrees range.
> +	The granuality of orientation depends on the touch device, some devices only
> +	support binary rotation values between 0 and 90 degrees.
> +
> +	This event is only sent by the compositor if the touch device supports
> +	orientation reports.
> +      </description>
> +      <arg name="id" type="int" summary="the unique ID of this touch point"/>
> +      <arg name="orientation" type="fixed" summary="angle between major axis and positive surface y-axis in degrees"/>
> +    </event>
> +
>    </interface>
>  
>    <interface name="wl_output" version="3">
> -- 
> 2.8.0.rc3.226.g39d4020
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
> 