[PATCH v4 wayland] protocol: add wl_pointer.axis_source, axis_stop, axis_discrete and axis_frame

[Peter Hutterer]

The axis_source event determines how an axis event was generated. That enables
clients to judge when to use kinetic scrolling.

The axis_stop event notifies a client about the termination of a scroll
sequence, likewise needed to calculate kinetic scrolling parameters.

The axis_discrete event provides the wheel click count. Previously the axis
value was some hardcoded number (10), with the discrete steps this enables a
client to differ between line-based scrolling on a mouse wheel and smooth
scrolling with a touchpad.

To axis_frame event groups separate vertical/horizontal scroll events
together. Likewise it enables axis_stop events to be grouped so that the final
vector for kinetic scrolling may be calculated correctly.

We can't extend the existing wl_pointer.axis events so we introduce a new
concept: latching events. These events (axis_source and axis_discrete)
are prefixed before a wl_pointer.axis or axis_stop event. The
wl_pointer.axis_frame trails the wl_pointer.axis event and groups any
preceeding events together.

i.e. a sequence may be:

wl_pointer.axis_source
wl_pointer.axis
wl_pointer.axis
wl_pointer.axis_frame
wl_pointer.axis_source
wl_pointer.axis
wl_pointer.axis_frame
wl_pointer.axis_source
wl_pointer.axis
wl_pointer.axis_frame
wl_pointer.axis_source
wl_pointer.axis_stop
wl_pointer.axis_stop
wl_pointer.axis_frame

Note how the first set includes two axis events, with the same source, the
second and third set include a single axis change each, the last frame stops
both axis movements in the same frame.

With wl_pointer.axis_discrete added, a single event may look like this:

wl_pointer.axis_source
wl_pointer.axis_discrete
wl_pointer.axis_axis
wl_pointer.axis_frame

Clients need to combine the state of all events where needed.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
Changes to v3:
- axis_stop contains a single axis rather than the array of axes stopped.
  This makes it effectively equivalent to axis, and with the axis_frame
  event we don't need the array, it's simpler to send multiple events.
- added more documentation, see
  http://lists.freedesktop.org/archives/wayland-devel/2015-July/023324.html
- squashed the patch for axis source/discrete/stop together with the patch
  adding axis frame events, updated the commit message accordingly.
- xml fix, axis_discrete had the args inside the <description> tag
- actually implemented this version in weston, see follow-up patch :)

 protocol/wayland.xml | 124 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 121 insertions(+), 3 deletions(-)

diff --git a/protocol/wayland.xml b/protocol/wayland.xml
index 59819e9..c321b59 100644
--- a/protocol/wayland.xml
+++ b/protocol/wayland.xml
@@ -1411,7 +1411,7 @@
 
   </interface>
 
-  <interface name="wl_pointer" version="3">
+  <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
@@ -1578,9 +1578,127 @@
       </description>
     </request>
 
+    <!-- Version 5 additions -->
+    <event name="axis_frame" since="5">
+      <description summary="end of axis set event">
+	Indicates the end of a set of wl_pointer.axis events that logically
+	belong together.
+
+	All wl_pointer.axis, wl_pointer.axis_stop, and
+	wl_pointer.axis_source before a wl_pointer.axis_frame event belong
+	logically together. For example, in a diagonal scroll motion the
+	compositor will send an optional wl_pointer.axis_source event, two
+	wl_pointer.axis events (horizontal and vertical) and finally a
+	wl_pointer.axis_frame event. The client may use this information to
+	calculate a diagonal vector for scrolling.
+
+	When multiple wl_pointer.axis events occur within the same frame,
+	the motion vector is the combined motion of all events.
+	When a wl_pointer.axis and a wl_pointer.axis_stop event occur within
+	the same frame, this indicates that axis movement in one axis has
+	stopped but continues in the other axis.
+	When multiple wl_pointer.axis_stop events occur within in the same
+	frame, this indicates that these axes stopped in the same instance.
+
+	Only one wl_pointer.axis_source event is permitted per axis frame.
+
+	A wl_pointer.axis_frame event is sent for every logical axis event
+	group, even if the group only contains a single wl_pointer.axis or
+	wl_pointer.axis_stop event. In other words, a client may get the
+	sequence: axis, axis_frame, axis, axis_frame, ...
+      </description>
+    </event>
+
+    <enum name="axis_source">
+      <description summary="axis source types">
+	Describes the source types for axis events. This indicates to the
+	client how an axis event was physically generated; a client may
+	adjust the user interface accordingly. For example, scroll events
+	from a "finger" source may be in a smooth coordinate space with
+	kinetic scrolling whereas a "wheel" source may be in discrete steps
+	of a number of lines.
+
+	The "continous" axis source is a device generating events in a
+	continuous coordinate space, but using something other than a
+	finger. One example for this source is button-based scrolling where
+	the vertical motion of a device is converted to scroll events while
+	a button is held down.
+      </description>
+      <entry name="wheel" value="0" summary="A physical wheel" />
+      <entry name="finger" value="1" summary="Finger on a touch surface" />
+      <entry name="continuous" value="2" summary="Continuous coordinate space"/>
+    </enum>
+
+    <event name="axis_source" since="5">
+      <description summary="axis source event">
+	Source information for scroll and other axes.
+
+	This event does not occur on its own. It is sent before a
+	wl_pointer.axis_frame event and carries the source information for
+	all events within that frame. A client is expected to accumulate the
+	data in all events events within the frame before proceeding.
+
+	The source specifies how this event was generated. If the source is
+	wl_pointer.axis_source.finger, a wl_pointer.axis_stop event will be
+	sent when the user lifts the finger off the device.
+
+	If the source is wl_pointer.axis_source.wheel or
+	wl_pointer.axis_source.continuous, a wl_pointer.axis_stop event may
+	be sent but is not guaranteed to be sent.
+
+	This event is optional. If the source is unknown for a particular
+	axis event sequence, no event is sent.
+
+	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
+	not guaranteed.
+      </description>
+      <arg name="axis_source" type="uint"/>
+    </event>
+
+    <event name="axis_stop" since="5">
+      <description summary="axis stop event">
+	Stop notification for scroll and other axes.
+
+	For some wl_pointer.axis_source types, a wl_pointer.axis_stop event
+	is sent to notify a client that the axis sequence has terminated.
+	This enables the client to implement kinetic scrolling.
+	See the wl_pointer.axis_source documentation for information on when
+	this event may be generated.
+
+	Any wl_pointer.axis events with the same axis_source after this
+	event should be considered as the start of a new axis motion.
+
+	The timestamp is to be interpreted identical to the timestamp in the
+	wl_pointer.axis event. The timestamp value may be the same as a
+	preceeding wl_pointer.axis event.
+      </description>
+      <arg name="time" type="uint" summary="timestamp with millisecond granularity"/>
+      <arg name="axis" type="uint" summary="the axis stopped with this event"/>
+    </event>
+
+    <event name="axis_discrete" since="5">
+      <description summary="axis click event">
+	Discrete step information for scroll and other axes.
+
+	This event does not occur on its own. It is sent before a
+	wl_pointer.axis event and carries the axis value of the
+	wl_pointer.axis event in discrete steps (e.g. mouse wheel clicks).
+
+	This event is optional, continuous scrolling devices
+	like two-finger scrolling on touchpads do not have discrete
+	steps and do not generate this event.
+
+	The discrete value carries the directional information. e.g. a value
+	of -2 is two steps towards the negative direction of this axis.
+
+	The order of wl_pointer.axis_discrete and wl_pointer.axis_source is
+	not guaranteed.
+      </description>
+      <arg name="discrete" type="int"/>
+    </event>
   </interface>
 
-  <interface name="wl_keyboard" version="4">
+  <interface name="wl_keyboard" version="5">
     <description summary="keyboard input device">
       The wl_keyboard interface represents one or more keyboards
       associated with a seat.
@@ -1694,7 +1812,7 @@
     </event>
   </interface>
 
-  <interface name="wl_touch" version="3">
+  <interface name="wl_touch" version="5">
     <description summary="touchscreen input device">
       The wl_touch interface represents a touchscreen
       associated with a seat.
-- 
2.4.3