1.. _pointer-acceleration: 2 3============================================================================== 4 Pointer acceleration 5============================================================================== 6 7libinput uses device-specific pointer acceleration methods, with the default 8being the :ref:`ptraccel-linear`. The methods share common properties, such as 9:ref:`ptraccel-velocity`. 10 11This page explains the high-level concepts used in the code. It aims to 12provide an overview for developers and is not necessarily useful for 13users. 14 15.. _ptraccel-profiles: 16 17------------------------------------------------------------------------------ 18Pointer acceleration profiles 19------------------------------------------------------------------------------ 20 21The profile decides the general method of pointer acceleration. 22libinput currently supports two profiles: "adaptive" and "flat". The adaptive 23profile is the default profile for all devices and takes the current speed 24of the device into account when deciding on acceleration. The flat profile 25is simply a constant factor applied to all device deltas, regardless of the 26speed of motion (see :ref:`ptraccel-profile-flat`). Most of this document 27describes the adaptive pointer acceleration. 28 29.. _ptraccel-velocity: 30 31------------------------------------------------------------------------------ 32Velocity calculation 33------------------------------------------------------------------------------ 34 35The device's speed of movement is measured across multiple input events 36through so-called "trackers". Each event prepends a the tracker item, each 37subsequent tracker contains the delta of that item to the current position, 38the timestamp of the event that created it and the cardinal direction of the 39movement at the time. If a device moves into the same direction, the 40velocity is calculated across multiple trackers. For example, if a device 41moves steadily for 10 events to the left, the velocity is calculated across 42all 10 events. 43 44Whenever the movement changes direction or significantly changes speed, the 45velocity is calculated from the direction/speed change only. For example, if 46a device moves steadily for 8 events to the left and then 2 events to the 47right, the velocity is only that of the last 2 events. 48 49An extra time limit prevents events that are too old to factor into the 50velocity calculation. For example, if a device moves steadily for 5 events 51to the left, then pauses, then moves again for 5 events to the left, only 52the last 5 events are used for velocity calculation. 53 54The velocity is then used to calculate the acceleration factor 55 56.. _ptraccel-factor: 57 58------------------------------------------------------------------------------ 59Acceleration factor 60------------------------------------------------------------------------------ 61 62The acceleration factor is the final outcome of the pointer acceleration 63calculations. It is a unitless factor that is applied to the current delta, 64a factor of 2 doubles the delta (i.e. speeds up the movement), a factor of 65less than 1 reduces the delta (i.e. slows the movement). 66 67Any factor less than 1 requires the user to move the device further to move 68the visible pointer. This is called deceleration and enables high precision 69target selection through subpixel movements. libinput's current maximum 70deceleration factor is 0.3 (i.e. slow down to 30% of the pointer speed). 71 72A factor higher than 1 moves the pointer further than the physical device 73moves. This is acceleration and allows a user to cross the screen quickly 74but effectively skips pixels. libinput's current maximum acceleration factor 75is 3.5. 76 77.. _ptraccel-linear: 78 79------------------------------------------------------------------------------ 80Linear pointer acceleration 81------------------------------------------------------------------------------ 82 83The linear pointer acceleration method is the default for most pointer 84devices. It provides deceleration at very slow movements, a 1:1 mapping for 85regular movements and a linear increase to the maximum acceleration factor 86for fast movements. 87 88Linear pointer acceleration applies to devices with above 1000dpi resolution 89and after :ref:`motion_normalization` is applied. 90 91.. figure:: ptraccel-linear.svg 92 :align: center 93 94 Linear pointer acceleration 95 96The image above shows the linear pointer acceleration settings at various 97speeds. The line for 0.0 is the default acceleration curve, speed settings 98above 0.0 accelerate sooner, faster and to a higher maximum acceleration. 99Speed settings below 0 delay when acceleration kicks in, how soon the 100maximum acceleration is reached and the maximum acceleration factor. 101 102Extremely low speed settings provide no acceleration and additionally 103decelerate all movement by a constant factor. 104 105.. _ptraccel-low-dpi: 106 107------------------------------------------------------------------------------ 108Pointer acceleration for low-dpi devices 109------------------------------------------------------------------------------ 110 111Low-dpi devices are those with a physical resolution of less than 1000 dots 112per inch (dpi). The pointer acceleration is adjusted to provide roughly the 113same feel for all devices at normal to high speeds. At slow speeds, the 114pointer acceleration works on device-units rather than normalized 115coordinates (see :ref:`motion_normalization`). 116 117.. figure:: ptraccel-low-dpi.svg 118 :align: center 119 120 Pointer acceleration for low-dpi devices 121 122The image above shows the default pointer acceleration curve for a speed of 1230.0 at different DPI settings. A device with low DPI has the acceleration 124applied sooner and with a stronger acceleration factor. 125 126.. _ptraccel-touchpad: 127 128------------------------------------------------------------------------------ 129Pointer acceleration on touchpads 130------------------------------------------------------------------------------ 131 132Touchpad pointer acceleration uses the same approach as the 133:ref:`ptraccel-linear` profile, with a constant deceleration factor applied. The 134user expectation of how much a pointer should move in response to finger 135movement is different to that of a mouse device, hence the constant 136deceleration factor. 137 138.. figure:: ptraccel-touchpad.svg 139 :align: center 140 141 Pointer acceleration curve for touchpads 142 143The image above shows the touchpad acceleration profile in comparison to the 144:ref:`ptraccel-linear`. The shape of the curve is identical but vertically squashed. 145 146.. _ptraccel-trackpoint: 147 148------------------------------------------------------------------------------ 149Pointer acceleration on trackpoints 150------------------------------------------------------------------------------ 151 152The main difference between trackpoint hardware and mice or touchpads is 153that trackpoint speed is a function of pressure rather than moving speed. 154But trackpoint hardware is quite varied in how it reacts to user pressure 155and unlike other devices it cannot easily be normalized for physical 156properties. Measuring pressure objectively across a variety of hardware is 157nontrivial. See :ref:`trackpoints` for more details. 158 159The deltas for trackpoints are converted units/ms but there is no common 160physical reference point for a unit. Thus, the same pressure on different 161trackpoints will generate different speeds and thus different acceleration 162behaviors. Additionally, some trackpoints provide the ability to adjust the 163sensitivity in hardware by modifying a sysfs file on the serio node. A 164higher sensitivity results in higher deltas, thus changing the definition of 165what is a unit again. 166 167libinput attempts to normalize unit data to the best of its abilities, see 168:ref:`trackpoint_multiplier`. Beyond this, it is not possible to have 169consistent behavior across different touchpad devices. 170 171.. figure:: ptraccel-trackpoint.svg 172 :align: center 173 174 Pointer acceleration curves for trackpoints 175 176The image above shows the trackpoint acceleration profile for the speed in 177units/ms. 178 179.. _ptraccel-profile-flat: 180 181------------------------------------------------------------------------------ 182The flat pointer acceleration profile 183------------------------------------------------------------------------------ 184 185In a flat profile, the acceleration factor is constant regardless of the 186velocity of the pointer and each delta (dx, dy) results in an accelerated delta 187(dx * factor, dy * factor). This provides 1:1 movement between the device 188and the pointer on-screen. 189 190.. _ptraccel-tablet: 191 192------------------------------------------------------------------------------ 193Pointer acceleration on tablets 194------------------------------------------------------------------------------ 195 196Pointer acceleration for relative motion on tablet devices is a flat 197acceleration, with the speed setting slowing down or speeding up the pointer 198motion by a constant factor. Tablets do not allow for switchable profiles. 199
