tablet: add support for relative x/y motion deltas

Instead of an explicit tablet mode that device must be changed into, let the
caller decide which coordinates are preferred. The tablet mode may be
application-specific and usually depends on the tool as well.

This patch adds an interface to get a motion delta for the x/y axes in
pixel-like coordinates. libinput provides some magic to convert the tablet
data into something that resembles pixels from a mouse motion.
For unaccelerated relative motion, the caller should use the mm values from
the tablet and calculate deltas manually.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Jason Gerecke <jason.gerecke@wacom.com>

doc/normalization-of-relative-motion.dox

@@ -38,6 +38,10 @@ libinput scales unaccelerated touchpad motion to the resolution of the
 touchpad's x axis, i.e. the unaccelerated value for the y axis is:
      y = (x / resolution_x) * resolution_y
 
+@section motion_normalization_tablet Normalization of tablet coordinates
+
+See @ref tablet-relative-motion
+
 @section motion_normalization_customization Setting custom DPI settings
 
 Devices usually do not advertise their resolution and libinput relies on

doc/tablet-support.dox

@@ -52,6 +52,28 @@ Note that the pressure threshold to trigger a logical tip event may be zero
 on some devices. On tools without pressure sensitivity, determining when a
 tip is down is device-specific.
 
+@section tablet-relative-motion Relative motion for tablet tools
+
+libinput calculates the relative motion vector for each event and converts
+it to the same coordinate space that a normal mouse device would use. For
+the caller, this means that the delta coordinates returned by
+libinput_event_tablet_tool_get_dx() and
+libinput_event_tablet_tool_get_dy() can be used identical to the delta
+coordinates from any other pointer event. Any resolution differences between
+the x and y axes are accommodated for, a delta of N/N represents a 45 degree
+diagonal move on the tablet.
+
+The delta coordinates are available for all tablet events, it is up to the
+caller to decide when a tool should be used in relative mode. It is
+recommended that mouse and lens cursor tool default to relative mode and
+all pen-like tools to absolute mode.
+
+If a tool in relative mode must not use pointer acceleration, callers
+should use the absolute coordinates returned by
+libinput_event_tablet_tool_get_x() and libinput_event_tablet_tool_get_y()
+and calculate the delta themselves. Callers that require exact physical
+distance should also use these functions to calculate delta movements.
+
 @section tablet-axes Special axes on tablet tools
 
 A tablet tool usually provides additional information beyond x/y positional

src/libinput-private.h

@@ -71,6 +71,7 @@ struct threshold {
 
 struct tablet_axes {
 	struct device_coords point;
+	struct normalized_coords delta;
 	double distance;
 	double pressure;
 	struct normalized_range_coords tilt;

src/libinput.c

@@ -1089,6 +1089,32 @@ libinput_event_tablet_tool_get_y(struct libinput_event_tablet_tool *event)
 				   event->axes.point.y);
 }
 
+LIBINPUT_EXPORT double
+libinput_event_tablet_tool_get_dx(struct libinput_event_tablet_tool *event)
+{
+	require_event_type(libinput_event_get_context(&event->base),
+			   event->base.type,
+			   0,
+			   LIBINPUT_EVENT_TABLET_TOOL_AXIS,
+			   LIBINPUT_EVENT_TABLET_TOOL_TIP,
+			   LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY);
+
+	return event->axes.delta.x;
+}
+
+LIBINPUT_EXPORT double
+libinput_event_tablet_tool_get_dy(struct libinput_event_tablet_tool *event)
+{
+	require_event_type(libinput_event_get_context(&event->base),
+			   event->base.type,
+			   0,
+			   LIBINPUT_EVENT_TABLET_TOOL_AXIS,
+			   LIBINPUT_EVENT_TABLET_TOOL_TIP,
+			   LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY);
+
+	return event->axes.delta.y;
+}
+
 LIBINPUT_EXPORT double
 libinput_event_tablet_tool_get_pressure(struct libinput_event_tablet_tool *event)
 {

src/libinput.h

@@ -1580,6 +1580,40 @@ libinput_event_tablet_tool_get_x(struct libinput_event_tablet_tool *event);
 double
 libinput_event_tablet_tool_get_y(struct libinput_event_tablet_tool *event);
 
+/**
+ * @ingroup event_tablet
+ *
+ * Return the delta between the last event and the current event.
+ * If the tool employs pointer acceleration, the delta returned by this
+ * function is the accelerated delta.
+ *
+ * This value is in screen coordinate space, the delta is to be interpreted
+ * like the return value of libinput_event_pointer_get_dx().
+ * See @ref tablet-relative-motion for more details.
+ *
+ * @param event The libinput tablet event
+ * @return The relative x movement since the last event
+ */
+double
+libinput_event_tablet_tool_get_dx(struct libinput_event_tablet_tool *event);
+
+/**
+ * @ingroup event_tablet
+ *
+ * Return the delta between the last event and the current event.
+ * If the tool employs pointer acceleration, the delta returned by this
+ * function is the accelerated delta.
+ *
+ * This value is in screen coordinate space, the delta is to be interpreted
+ * like the return value of libinput_event_pointer_get_dx().
+ * See @ref tablet-relative-motion for more details.
+ *
+ * @param event The libinput tablet event
+ * @return The relative y movement since the last event
+ */
+double
+libinput_event_tablet_tool_get_dy(struct libinput_event_tablet_tool *event);
+
 /**
  * @ingroup event_tablet
  *

src/libinput.sym

@@ -194,6 +194,8 @@ LIBINPUT_TABLET_SUPPORT {
 	libinput_event_tablet_tool_tilt_y_has_changed;
 	libinput_event_tablet_tool_wheel_has_changed;
 	libinput_event_tablet_tool_slider_has_changed;
+	libinput_event_tablet_tool_get_dx;
+	libinput_event_tablet_tool_get_dy;
 	libinput_event_tablet_tool_get_x;
 	libinput_event_tablet_tool_get_y;
 	libinput_event_tablet_tool_get_pressure;