Debian Codegraph @

doc/user/pointer-acceleration.rst

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