doc: add pointer acceleration documentation

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Jonas Ådahl <jadahl@gmail.com>

doc/Makefile.am

@@ -18,6 +18,7 @@ header_files = \
 	$(srcdir)/normalization-of-relative-motion.dox \
 	$(srcdir)/palm-detection.dox \
 	$(srcdir)/page-hierarchy.dox \
+	$(srcdir)/pointer-acceleration.dox \
 	$(srcdir)/reporting-bugs.dox \
 	$(srcdir)/scrolling.dox \
 	$(srcdir)/seats.dox \
@@ -39,6 +40,10 @@ diagram_files = \
 	$(srcdir)/svg/edge-scrolling.svg \
 	$(srcdir)/svg/palm-detection.svg \
 	$(srcdir)/svg/pinch-gestures.svg \
+	$(srcdir)/svg/ptraccel-linear.svg \
+	$(srcdir)/svg/ptraccel-low-dpi.svg \
+	$(srcdir)/svg/ptraccel-touchpad.svg \
+	$(srcdir)/svg/ptraccel-trackpoint.svg \
 	$(srcdir)/svg/swipe-gestures.svg \
 	$(srcdir)/svg/tap-n-drag.svg \
 	$(srcdir)/svg/thumb-detection.svg \

doc/page-hierarchy.dox

@@ -31,5 +31,6 @@
 
 - @subpage test-suite
 - @subpage tools
+- @subpage pointer-acceleration
 
 */

doc/pointer-acceleration.dox

@@ -0,0 +1,110 @@
+/**
+@page pointer-acceleration  Pointer acceleration
+
+libinput uses device-specific pointer acceleration methods, with the default
+being the @ref ptraccel-linear. The methods share common properties, such as
+@ref ptraccel-velocity.
+
+This page explains the high-level concepts used in the code. It aims to
+provide an overview for developers and is not necessarily useful for
+users.
+
+@section ptraccel-velocity Velocity calculation
+
+The device's speed of movement is measured across multiple input events
+through so-called "trackers". Each event prepends a the tracker item, each
+subsequent tracker contains the delta of that item to the current position,
+the timestamp of the event that created it and the cardinal direction of the
+movement at the time. If a device moves into the same direction, the
+velocity is calculated across multiple trackers. For example, if a device
+moves steadily for 10 events to the left, the velocity is calculated across
+all 10 events.
+
+Whenever the movement changes direction or significantly changes speed, the
+velocity is calculated from the direction/speed change only. For example, if
+a device moves steadily for 8 events to the left and then 2 events to the
+right, the velocity is only that of the last 2 events.
+
+An extra time limit prevents events that are too old to factor into the
+velocity calculation. For example, if a device moves steadily for 5 events
+to the left, then pauses, then moves again for 5 events to the left, only
+the last 5 events are used for velocity calculation.
+
+The velocity is then used to calculate the acceleration factor
+
+@section ptraccel-factor Acceleration factor
+
+The acceleration factor is the final outcome of the pointer acceleration
+calculations. It is a unitless factor that is applied to the current delta,
+a factor of 2 doubles the delta (i.e. speeds up the movement), a factor of
+less than 1 reduces the delta (i.e. slows the movement).
+
+Any factor less than 1 requires the user to move the device further to move
+the visible pointer. This is called deceleration and enables high precision
+target selection through subpixel movements. libinput's current maximum
+deceleration factor is 0.3 (i.e. slow down to 30% of the pointer speed).
+
+A factor higher than 1 moves the pointer further than the physical device
+moves. This is acceleration and allows a user to cross the screen quickly
+but effectively skips pixels. libinput's current maximum acceleration factor
+is 3.5.
+
+@section ptraccel-linear Linear pointer acceleration
+
+The linear pointer acceleration method is the default for most pointer
+devices. It provides deceleration at very slow movements, a 1:1 mapping for
+regular movements and a linear increase to the maximum acceleration factor
+for fast movements.
+
+Linear pointer acceleration applies to devices with above 1000dpi resolution
+and after @ref motion_normalization is applied.
+
+@image html ptraccel-linear.svg "Linear pointer acceleration"
+
+The image above shows the linear pointer acceleration settings at various
+speeds. The line for 0.0 is the default acceleration curve, speed settings
+above 0.0 accelerate sooner, faster and to a higher maximum acceleration.
+Speed settings below 0 delay when acceleration kicks in, how soon the
+maximum acceleration is reached and the maximum acceleration factor.
+
+Extremely low speed settings provide no acceleration and additionally
+decelerate all movement by a constant factor.
+
+@section ptraccel-low-dpi Pointer acceleration for low-dpi devices
+
+Low-dpi devices are those with a physical resolution of less than 1000 dots
+per inch (dpi). The pointer acceleration is adjusted to provide roughly the
+same feel for all devices at normal to high speeds. At slow speeds, the
+pointer acceleration works on device-units rather than normalized
+coordinates (see @ref motion_normalization).
+
+@image html ptraccel-low-dpi.svg "Pointer acceleration for low-dpi devices"
+
+The image above shows the default pointer acceleration curve for a speed of
+0.0 at different DPI settings. A device with low DPI has the acceleration
+applied sooner and with a stronger acceleration factor.
+
+@section ptraccel-touchpad Pointer acceleration on touchpads
+
+Touchpad pointer acceleration uses the @ref ptraccel-linear profile, with a
+constant deceleration factor applied. The user expectation of how much a
+pointer should move in response to finger movement is different to that of a
+mouse device, hence the constant deceleration factor.
+
+@image html ptraccel-touchpad.svg "Pointer acceleration curve for touchpads"
+
+The image above shows the touchpad acceleration profile in comparison to the
+@ref ptraccel-linear. The shape of the curve is identical but vertically squashed.
+
+@section ptraccel-trackpoint Pointer acceleration on trackpoints
+
+Trackpoint pointer acceleration uses the @ref ptraccel-low-dpi profile, with a
+constant deceleration factor taking the place of the DPI settings.
+
+@image html ptraccel-trackpoint.svg "Pointer acceleration curves for trackpoints"
+
+The image above shows the trackpoint acceleration profile in comparison to the
+@ref ptraccel-linear. The constant acceleration factor, usually applied by
+udev, shapes the acceleration profile.
+
+*/