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 three profiles: **"adaptive"**, **"flat"** and
23**"custom"**.
24
25- The **adaptive** profile is the default profile for all devices and takes the
26  current speed of the device into account when deciding on acceleration.
27- The **flat** profile is simply a constant factor applied to all device deltas,
28  regardless of the speed of motion (see :ref:`ptraccel-profile-flat`).
29- The **custom** profile allows the user to define a custom acceleration
30  function, giving full control over accelerations behavior at different speed
31  (see :ref:`ptraccel-profile-custom`).
32
33Most of this document describes the adaptive pointer acceleration.
34
35.. _ptraccel-velocity:
36
37------------------------------------------------------------------------------
38Velocity calculation
39------------------------------------------------------------------------------
40
41The device's speed of movement is measured across multiple input events
42through so-called "trackers". Each event prepends a the tracker item, each
43subsequent tracker contains the delta of that item to the current position,
44the timestamp of the event that created it and the cardinal direction of the
45movement at the time. If a device moves into the same direction, the
46velocity is calculated across multiple trackers. For example, if a device
47moves steadily for 10 events to the left, the velocity is calculated across
48all 10 events.
49
50Whenever the movement changes direction or significantly changes speed, the
51velocity is calculated from the direction/speed change only. For example, if
52a device moves steadily for 8 events to the left and then 2 events to the
53right, the velocity is only that of the last 2 events.
54
55An extra time limit prevents events that are too old to factor into the
56velocity calculation. For example, if a device moves steadily for 5 events
57to the left, then pauses, then moves again for 5 events to the left, only
58the last 5 events are used for velocity calculation.
59
60The velocity is then used to calculate the acceleration factor
61
62.. _ptraccel-factor:
63
64------------------------------------------------------------------------------
65Acceleration factor
66------------------------------------------------------------------------------
67
68The acceleration factor is the final outcome of the pointer acceleration
69calculations. It is a unitless factor that is applied to the current delta,
70a factor of 2 doubles the delta (i.e. speeds up the movement), a factor of
71less than 1 reduces the delta (i.e. slows the movement).
72
73Any factor less than 1 requires the user to move the device further to move
74the visible pointer. This is called deceleration and enables high precision
75target selection through subpixel movements. libinput's current maximum
76deceleration factor is 0.3 (i.e. slow down to 30% of the pointer speed).
77
78A factor higher than 1 moves the pointer further than the physical device
79moves. This is acceleration and allows a user to cross the screen quickly
80but effectively skips pixels. libinput's current maximum acceleration factor
81is 3.5.
82
83.. _ptraccel-linear:
84
85------------------------------------------------------------------------------
86Linear pointer acceleration
87------------------------------------------------------------------------------
88
89The linear pointer acceleration method is the default for most pointer
90devices. It provides deceleration at very slow movements, a 1:1 mapping for
91regular movements and a linear increase to the maximum acceleration factor
92for fast movements.
93
94Linear pointer acceleration applies to devices with above 1000dpi resolution
95and after :ref:`motion_normalization` is applied.
96
97.. figure:: ptraccel-linear.svg
98    :align: center
99
100    Linear pointer acceleration
101
102The image above shows the linear pointer acceleration settings at various
103speeds. The line for 0.0 is the default acceleration curve, speed settings
104above 0.0 accelerate sooner, faster and to a higher maximum acceleration.
105Speed settings below 0 delay when acceleration kicks in, how soon the
106maximum acceleration is reached and the maximum acceleration factor.
107
108Extremely low speed settings provide no acceleration and additionally
109decelerate all movement by a constant factor.
110
111.. _ptraccel-low-dpi:
112
113------------------------------------------------------------------------------
114Pointer acceleration for low-dpi devices
115------------------------------------------------------------------------------
116
117Low-dpi devices are those with a physical resolution of less than 1000 dots
118per inch (dpi). The pointer acceleration is adjusted to provide roughly the
119same feel for all devices at normal to high speeds. At slow speeds, the
120pointer acceleration works on device-units rather than normalized
121coordinates (see :ref:`motion_normalization`).
122
123.. figure:: ptraccel-low-dpi.svg
124    :align: center
125
126    Pointer acceleration for low-dpi devices
127
128The image above shows the default pointer acceleration curve for a speed of
1290.0 at different DPI settings. A device with low DPI has the acceleration
130applied sooner and with a stronger acceleration factor.
131
132.. _ptraccel-touchpad:
133
134------------------------------------------------------------------------------
135Pointer acceleration on touchpads
136------------------------------------------------------------------------------
137
138Touchpad pointer acceleration uses the same approach as the
139:ref:`ptraccel-linear` profile, with a constant deceleration factor applied. The
140user expectation of how much a pointer should move in response to finger
141movement is different to that of a mouse device, hence the constant
142deceleration factor.
143
144.. figure:: ptraccel-touchpad.svg
145    :align: center
146
147    Pointer acceleration curve for touchpads
148
149The image above shows the touchpad acceleration profile in comparison to the
150:ref:`ptraccel-linear`. The shape of the curve is identical but vertically squashed.
151
152.. _ptraccel-trackpoint:
153
154------------------------------------------------------------------------------
155Pointer acceleration on trackpoints
156------------------------------------------------------------------------------
157
158The main difference between trackpoint hardware and mice or touchpads is
159that trackpoint speed is a function of pressure rather than moving speed.
160But trackpoint hardware is quite varied in how it reacts to user pressure
161and unlike other devices it cannot easily be normalized for physical
162properties. Measuring pressure objectively across a variety of hardware is
163nontrivial. See :ref:`trackpoints` for more details.
164
165The deltas for trackpoints are converted units/ms but there is no common
166physical reference point for a unit. Thus, the same pressure on different
167trackpoints will generate different speeds and thus different acceleration
168behaviors. Additionally, some trackpoints provide the ability to adjust the
169sensitivity in hardware by modifying a sysfs file on the serio node. A
170higher sensitivity results in higher deltas, thus changing the definition of
171what is a unit again.
172
173libinput attempts to normalize unit data to the best of its abilities, see
174:ref:`trackpoint_multiplier`. Beyond this, it is not possible to have
175consistent behavior across different touchpad devices.
176
177.. figure:: ptraccel-trackpoint.svg
178    :align: center
179
180    Pointer acceleration curves for trackpoints
181
182The image above shows the trackpoint acceleration profile for the speed in
183units/ms.
184
185.. _ptraccel-profile-flat:
186
187------------------------------------------------------------------------------
188The flat pointer acceleration profile
189------------------------------------------------------------------------------
190
191In a flat profile, the acceleration factor is constant regardless of the
192velocity of the pointer and each delta (dx, dy) results in an accelerated delta
193(dx * factor, dy * factor). This provides 1:1 movement between the device
194and the pointer on-screen.
195
196.. _ptraccel-tablet:
197
198------------------------------------------------------------------------------
199Pointer acceleration on tablets
200------------------------------------------------------------------------------
201
202Pointer acceleration for relative motion on tablet devices is a flat
203acceleration, with the speed setting slowing down or speeding up the pointer
204motion by a constant factor. Tablets do not allow for switchable profiles.
205
206.. _ptraccel-profile-custom:
207
208------------------------------------------------------------------------------
209The custom acceleration profile
210------------------------------------------------------------------------------
211
212libinput supports a user-defined custom acceleration profile, which can be
213adjusted for different movement types supported by a device. Movement types
214include pointer movement, scrolling, etc. but the set of supported
215movement types depends on the device.
216
217The custom pointer acceleration profile gives users full control over the
218acceleration behavior at different speeds. libinput exposes
219an acceleration function ``f(x)`` where the x axis is the device speed in
220device units per millisecond and the y axis is the pointer speed. By
221supplying the y axis values for this function, users can control the
222behavior of the device.
223
224The user should take into account the native device dpi and screen dpi in
225order to achieve the desired behavior/feel.
226
227The custom acceleration function is defined using ``n`` points which are spaced
228uniformly along the x axis, starting from 0 and continuing in constant steps.
229At least two points must be defined and there is an implementation-defined
230limit on how many points may be added.
231
232Thus the points defining the custom function are:
233``(0 * step, f[0]), (1 * step, f[1]), ..., ((n-1) * step, f[n-1])``
234where ``f`` is a list of ``n`` values defining the output velocity for each
235input velocity.
236The acceleration factor is defined by the ratio of the output velocity to the
237input velocity.
238When a velocity value does not lie exactly on those points, a linear
239interpolation of the two closest points will be calculated.
240When a velocity value is greater than the max point defined, a linear
241extrapolation of the two biggest points will be calculated.
242
243the calculation made by libinput: ::
244
245    input_delta = device delta units
246    delta_time = time in ms since last input_delta
247    input_speed = hypot(input_delta) / delta_time
248    output_speed = user_custom_function(input_speed)
249    acceleration_factor = output_speed / input_speed
250    output_delta = input_delta * acceleration_factor
251
252An example is the curve of ``0.0, 1.0`` with a step of ``1.0``. This curve
253is the equivalent of the flat acceleration profile with any input speed ``N``
254mapped to the same pointer speed ``N``. The curve ``1.0, 1.0`` neutralizes
255any input speed differences and results in a fixed pointer speed.
256
257Another example is the custom acceleration function ``x**2``,
258sampling the function at ``4`` points up to
259a maximum input speed of ``9`` will give us a custom function with
260a step of ``3`` and points ``[0.0, 9.0, 36.0, 81.0]``:
261
262.. figure:: ptraccel-custom.svg
263    :align: center
264
265More sampled points can be added to improve the accuracy of the user custom
266function.
267
268Supported Movement types:
269
270+---------------+---------------------------------+----------------------+
271| Movement type | Uses                            | supported by         |
272+===============+=================================+======================+
273| Fallback      | Catch-all default movement type | All devices          |
274+---------------+---------------------------------+----------------------+
275| Motion        | Used for pointer motion         | All devices          |
276+---------------+---------------------------------+----------------------+
277| Scroll        | Used for scroll movement        | Mouse, Touchpad      |
278+---------------+---------------------------------+----------------------+
279
280If a user does not provide the fallback custom acceleration function, a
281flat acceleration function is used, i.e. no acceleration.
282
283The fallback acceleration may be used for different types of movements, it is
284strongly recommended that this acceleration function is a constant function.
285
286For example, a touchpad has multiple movement types: pointer
287movement, scroll movement, zoom movement (pinch), etc. As there is no separate
288movement type for zoom yet, zoom movement is accelerated using the Fallback
289acceleration function. Pointer movement is accelerated using the Motion
290acceleration function, and Scroll movement is accelerated using the Scroll
291acceleration function. If no Motion/Scroll acceleration function is set, the
292Fallback acceleration function is used.
293
294When using custom acceleration profile, any calls to set the speed have no
295effect on the behavior of the custom acceleration function, but any future calls to
296get the speed will reflect the requested speed setting.
297