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

Fri Nov 4 02:38:57 UTC 2016

Hi Dennis,

> On Nov 3, 2016, at 3:52 PM, Dennis Kempin <denniskempin at google.com> 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>

My apologies for not noticing the following sooner, but some issues are noted
inline below. Also, the line lengths of those descriptions should max out at
80 characters (please). I've noted them inline for convenience.

> ---
> protocol/wayland.xml | 79 +++++++++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 75 insertions(+), 4 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 6c6d078..31902e6 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,14 @@
> 
>     <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 +2283,70 @@
>     <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

This event does not...

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

Above line exceeds 80 characters followed by other protocol descriptions.

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

The two lines above exceed 80 characters followed by other protocol descriptions.

> +	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.
> +
> +	The orientation describes the clockwise angle of a touchpoint's major axis to
> +	the positive surface y-axis and is normalized to the -180 to +180 degrees range.

-180 to +180 degree range.

> +	The granuality of orientation depends on the touch device, some devices only

The granularity of...

Above three lines exceeds 80 characters followed by other protocol descriptions.

Regards,
yong

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