[PATCH wayland] protocol: Add pointer gestures (swipe/pinch) protocol

[Carlos Garnacho]

Hey,

Keen eye on those :), my last proofreading wasn't as successful. I've
just sent a new patch that contains Pekka's suggestions, fixes for
your comments and your r-b.

Cheers,
  Carlos

On Thu, Jul 16, 2015 at 2:13 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> On Wed, Jul 15, 2015 at 08:02:10PM +0200, Carlos Garnacho wrote:
>> The lifetime and progress of gestures is maintained by the separate
>> wl_pointer_gesture_pinch and wl_pointer_gesture_swipe interfaces,
>> each of these has begin/update(optional)/end phases, as transmitted
>> by their events.
>>
>> The gesture interfaces can be obtained from the wl_pointer, and
>> must be interpreted on the last surface entered by the pointer,
>> starting from the pointer coordinates.
>>
>> Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
>> ---
>>  protocol/wayland.xml | 153 ++++++++++++++++++++++++++++++++++++++++++++++++++-
>>  1 file changed, 151 insertions(+), 2 deletions(-)
>>
>> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
>> index 42c9309..51effad 100644
>> --- a/protocol/wayland.xml
>> +++ b/protocol/wayland.xml
>> @@ -1329,7 +1329,7 @@
>>      </request>
>>     </interface>
>>
>> -  <interface name="wl_seat" version="4">
>> +  <interface name="wl_seat" version="5">
>>      <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
>> @@ -1402,7 +1402,139 @@
>>
>>    </interface>
>>
>> -  <interface name="wl_pointer" version="3">
>> +  <interface name="wl_pointer_gesture_swipe" version="5">
>> +    <description summary="a swipe gesture object">
>> +      A swipe gesture object notifies a client about a multi-finger swipe
>> +      gesture detected on an indirect input device such as a touchpad.
>> +      The gesture is usually initiated by multiple fingers moving in the
>> +      same direction but once initiated the direction may change.
>> +      The precise conditions of when such a gesture is detected are
>> +      implementation-dependent.
>> +
>> +      A gesture consists of three stages: begin, update (optional) and end.
>> +
>> +      A gesture may be cancelled by the compositor or the hardware.
>> +      Destructive actions should not be considered until the end of a
>> +      gesture has been received.
>> +    </description>
>> +
>> +    <request name="release" since="5">
>> +      <description summary="release the pointer swipe gesture object"/>
>> +    </request>
>> +
>> +    <event name="begin" since="5">
>> +      <description summary="multi-finger swipe begin">
>> +     This event is sent when a multi-finger swipe gesture is detected
>> +     on the device.
>> +      </description>
>> +      <arg name="serial" type="uint"/>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="fingers" type="uint" summary="number of fingers"/>
>> +    </event>
>> +
>> +    <event name="update" since="5">
>> +      <description summary="multi-finger swipe motion">
>> +     This event is sent when a multi-finger swipe gesture changes the
>> +     position of the logical center.
>> +
>> +     The dx and dy coordinates are relative coordinates of the logical
>> +     center of the gesture compared to the previous event.
>> +      </description>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
>> +      <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
>> +    </event>
>> +
>> +    <event name="end" since="5">
>> +      <description summary="multi-finger swipe end">
>> +     This event is sent when a multi-finger swipe gesture ceases to
>> +     be valid. This may happen when one or more finger is lifted or
>> +     the gesture is cancelled.
>> +
>> +     When a gesture is cancelled, the client should undo state changes
>> +     caused by this gesture. What causes a gesture to be cancelled is
>> +     implementation-dependent.
>> +      </description>
>> +      <arg name="serial" type="uint"/>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="cancelled" type="int" summary="number of fingers"/>
>
> copy/paste error here (sorry, my fault)
>
>> +    </event>
>> +  </interface>
>> +
>> +  <interface name="wl_pointer_gesture_pinch" version="5">
>> +    <description summary="a pinch gesture object">
>> +      A swipe gesture object notifies a client about a multi-finger pinch
>
> s/swipe/pinch/
>
>> +      gesture detected on an indirect input device such as a touchpad.
>> +      The gesture is usually initiated by multiple fingers moving towards
>> +      each other or away from each other, or by two or more fingers rotating
>> +      around a logical center of gravity.  The precise conditions of when
>> +      such a gesture is detected are implementation-dependent.
>> +
>> +      A gesture consists of three stages: begin, update (optional) and end.
>> +
>> +      A gesture may be cancelled by the compositor or the hardware.
>> +      Destructive actions should not be considered until the end of a
>> +      gesture has been received.
>> +    </description>
>> +
>> +    <request name="release" since="5">
>> +      <description summary="release the pinch gesture object"/>
>> +    </request>
>> +
>> +    <event name="begin" since="5">
>> +      <description summary="multi-finger pinch begin">
>> +     This event is sent when a multi-finger pinch gesture is detected
>> +     on the device.
>> +
>> +     The gesture is assigned a unique @id. Future events from this
>> +     gesture reference this ID. The ID ceases to be valid after a
>> +     pointer_gesture_swipe.end and may be re-used in the future.
>
> you can drop this paragraph now. for the archives: the original version of
> this patchset had an ID for each gesture sequence similar to touches.
>
> Carlos and I agreed that this isn't really necessary - while it's
> technically possible to have two gestures on two different devices at the
> same time this is something that the compositor should suppress. If we find
> a sensible use-case for this, we can add the gesture sequence ID later.
>
> Carlos: you may want to add a paragraph explicitly stating that only one
> gesture of a type may be active at a time.
>
>> +      </description>
>> +      <arg name="serial" type="uint"/>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="fingers" type="uint" summary="number of fingers"/>
>> +    </event>
>> +
>> +    <event name="update" since="5">
>> +      <description summary="multi-finger pinch motion">
>> +     This event is sent when a multi-finger pinch gesture changes the
>> +     position of the logical center, the rotation or the relative scale.
>> +
>> +     The dx and dy coordinates are relative coordinates in the
>> +     surface coordinate space of the logical center of the gesture.
>> +
>> +     The scale factor is an absolute scale compared to the
>> +     pointer_gesture_pinch.begin event, i.e. a scale of 2 means the fingers
>
> actually, this should be e.g., not i.e. (though I guess both would be ok here)
>
> Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net> with the above fixed
>
> Cheers,
>    Peter
>
>> +     are now twice as far apart as on pointer_gesture_pinch.begin.
>> +
>> +     The rotation is the relative angle in degrees clockwise compared to the previous
>> +     pointer_gesture_pinch.begin or pointer_gesture_pinch.update event.
>> +      </description>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="dx" type="fixed" summary="delta x coordinate in surface coordinate space"/>
>> +      <arg name="dy" type="fixed" summary="delta y coordinate in surface coordinate space"/>
>> +      <arg name="scale" type="fixed" summary="scale relative to the initial finger position"/>
>> +      <arg name="rotation" type="fixed" summary="angle in degrees cw relative to the previous event"/>
>> +    </event>
>> +
>> +    <event name="end" since="5">
>> +      <description summary="multi-finger pinch end">
>> +     This event is sent when a multi-finger pinch gesture ceases to
>> +     be valid. This may happen when one or more finger is lifted or
>> +     the gesture is cancelled.
>> +
>> +     When a gesture is cancelled, the client should undo state changes
>> +     caused by this gesture. What causes a gesture to be cancelled is
>> +     implementation-dependent.
>> +      </description>
>> +      <arg name="serial" type="uint"/>
>> +      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
>> +      <arg name="cancelled" type="int" summary="number of fingers"/>
>> +    </event>
>> +
>> +  </interface>
>> +
>> +  <interface name="wl_pointer" version="5">
>>      <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
>> @@ -1569,6 +1701,23 @@
>>        </description>
>>      </request>
>>
>> +    <!-- Version 5 additions -->
>> +
>> +    <request name="get_swipe_gesture" since="5">
>> +      <description summary="get swipe gesture">
>> +     Create a swipe gesture object for the given pointer. See the
>> +     wl_pointer_gesture_swipe interface for details.
>> +      </description>
>> +      <arg name="id" type="new_id" interface="wl_pointer_gesture_swipe"/>
>> +    </request>
>> +
>> +    <request name="get_pinch_gesture" since="5">
>> +      <description summary="get pinch gesture">
>> +     Create a pinch gesture object for the given pointer. See the
>> +     wl_pointer_gesture_pinch interface for details.
>> +      </description>
>> +      <arg name="id" type="new_id" interface="wl_pointer_gesture_pinch"/>
>> +    </request>
>>    </interface>
>>
>>    <interface name="wl_keyboard" version="4">
>> --
>> 2.4.3
>>