diff --git a/doc/Makefile.am b/doc/Makefile.am index c9dccfda..a8d41822 100644 --- a/doc/Makefile.am +++ b/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 \ diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index 1e82535f..3fdb1f72 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -31,5 +31,6 @@ - @subpage test-suite - @subpage tools +- @subpage pointer-acceleration */ diff --git a/doc/pointer-acceleration.dox b/doc/pointer-acceleration.dox new file mode 100644 index 00000000..a372e154 --- /dev/null +++ b/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. + +*/ diff --git a/doc/svg/ptraccel-linear.svg b/doc/svg/ptraccel-linear.svg new file mode 100644 index 00000000..cb575f21 --- /dev/null +++ b/doc/svg/ptraccel-linear.svg @@ -0,0 +1,5486 @@ + + + + +Gnuplot +Produced by GNUPLOT 5.0 patchlevel 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 0.5 + + + + + 1 + + + + + 1.5 + + + + + 2 + + + + + 2.5 + + + + + 3 + + + + + 0 + + + + + 0.0005 + + + + + 0.001 + + + + + 0.0015 + + + + + 0.002 + + + + + 0.0025 + + + + + 0.003 + + + + + + + + + accel factor + + + + + speed in units/us + + + + + -1.0 + + + -1.0 + + + + + + -0.75 + + + -0.75 + + + + + + -0.5 + + + -0.5 + + + + + + -0.25 + + + -0.25 + + + + + + 0.0 + + + 0.0 + + + + + + 0.5 + + + 0.5 + + + + + + 1.0 + + + 1.0 + + + + + + + + + + + + + + + + + + diff --git a/doc/svg/ptraccel-low-dpi.svg b/doc/svg/ptraccel-low-dpi.svg new file mode 100644 index 00000000..e31eaa1a --- /dev/null +++ b/doc/svg/ptraccel-low-dpi.svg @@ -0,0 +1,3748 @@ + + + + +Gnuplot +Produced by GNUPLOT 5.0 patchlevel 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + 0 + + + + + 0.0005 + + + + + 0.001 + + + + + 0.0015 + + + + + 0.002 + + + + + 0.0025 + + + + + 0.003 + + + + + + + + + accel factor + + + + + speed in units/us + + + + + 200dpi + + + 200dpi + + + + + + 400dpi + + + 400dpi + + + + + + 800dpi + + + 800dpi + + + + + + 1000dpi + + + 1000dpi + + + + + + + + + + + + + + + + + + diff --git a/doc/svg/ptraccel-touchpad.svg b/doc/svg/ptraccel-touchpad.svg new file mode 100644 index 00000000..1befa1e5 --- /dev/null +++ b/doc/svg/ptraccel-touchpad.svg @@ -0,0 +1,1723 @@ + + + + +Gnuplot +Produced by GNUPLOT 5.0 patchlevel 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 0.5 + + + + + 1 + + + + + 1.5 + + + + + 2 + + + + + 2.5 + + + + + 3 + + + + + 0 + + + + + 0.0005 + + + + + 0.001 + + + + + 0.0015 + + + + + 0.002 + + + + + 0.0025 + + + + + 0.003 + + + + + + + + + accel factor + + + + + speed in units/us + + + + + linear (mouse) + + + linear (mouse) + + + + + + touchpad + + + touchpad + + + + + + + + + + + + + + + + + + diff --git a/doc/svg/ptraccel-trackpoint.svg b/doc/svg/ptraccel-trackpoint.svg new file mode 100644 index 00000000..79589c24 --- /dev/null +++ b/doc/svg/ptraccel-trackpoint.svg @@ -0,0 +1,3689 @@ + + + + +Gnuplot +Produced by GNUPLOT 5.0 patchlevel 0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 0 + + + + + 1 + + + + + 2 + + + + + 3 + + + + + 4 + + + + + 5 + + + + + 0 + + + + + 0.0005 + + + + + 0.001 + + + + + 0.0015 + + + + + 0.002 + + + + + 0.0025 + + + + + 0.003 + + + + + + + + + accel factor + + + + + speed in units/us + + + + + linear (mouse) + + + linear (mouse) + + + + + + const accel 1 + + + const accel 1 + + + + + + const accel 2 + + + const accel 2 + + + + + + const accel 3 + + + const accel 3 + + + + + + + + + + + + + + + + + +