Debian Codegraph @

doc/user/normalization-of-relative-motion.rst

raw
1 .. _motion_normalization:
2
3 ==============================================================================
4 Normalization of relative motion
5 ==============================================================================
6
7 Most relative input devices generate input in so-called "mickeys". A
8 mickey is in device-specific units that depend on the resolution
9 of the sensor. Most optical mice use sensors with 1000dpi resolution, but
10 some devices range from 100dpi to well above 8000dpi.
11
12 Without a physical reference point, a relative coordinate cannot be
13 interpreted correctly. A delta of 10 mickeys may be a millimeter of
14 physical movement or 10 millimeters, depending on the sensor. This
15 affects pointer acceleration in libinput and interpretation of relative
16 coordinates in callers.
17
18 libinput does partial normalization of relative input. For devices with a
19 resolution of 1000dpi and higher, motion events are normalized to a default
20 of 1000dpi before pointer acceleration is applied. As a result, devices with
21 1000dpi and above feel the same.
22
23 Devices below 1000dpi are not normalized (normalization of a 1-device unit
24 movement on a 400dpi mouse would cause a 2.5 pixel movement). Instead,
25 libinput applies a dpi-dependent acceleration function. At low speeds, a
26 1-device unit movement usually translates into a 1-pixel movements. As the
27 movement speed increases, acceleration is applied - at high speeds a low-dpi
28 device will roughly feel the same as a higher-dpi mouse.
29
30 The reason for the normalization is convenience: a caller can assume that a
31 delta of 1 should result in a movement of 1 pixel on a traditional
32 (low-dpi) screen. On screens with high resolutions, the caller must scale
33 according to the UI scale factors.
34
35 This normalization only applies to accelerated coordinates, unaccelerated
36 coordinates are left in device-units. It is up to the caller to interpret
37 those coordinates correctly.
38
39 .. _motion_normalization_touchpad:
40
41 ------------------------------------------------------------------------------
42 Normalization of touchpad coordinates
43 ------------------------------------------------------------------------------
44
45 Touchpads may have a different resolution for the horizontal and vertical
46 axis. Interpreting coordinates from the touchpad without taking resolution
47 into account results in uneven motion.
48
49 libinput scales unaccelerated touchpad motion to the resolution of the
50 touchpad's x axis, i.e. the unaccelerated value for the y axis is:
51 ``y = (x / resolution_x) * resolution_y``.
52
53 .. _motion_normalization_tablet:
54
55 ------------------------------------------------------------------------------
56 Normalization of tablet coordinates
57 ------------------------------------------------------------------------------
58
59 See :ref:`tablet-relative-motion`
60
61 .. _motion_normalization_customization:
62
63 ------------------------------------------------------------------------------
64 Setting custom DPI settings
65 ------------------------------------------------------------------------------
66
67 Devices usually do not advertise their resolution and libinput relies on
68 the udev property **MOUSE_DPI** for this information. This property is usually
69 set via the
70 `udev hwdb <http://cgit.freedesktop.org/systemd/systemd/tree/hwdb/70-mouse.hwdb>`_.
71 The ``mouse-dpi-tool`` utility provided by
72 `libevdev <https://freedesktop.org/wiki/Software/libevdev/>`_ should be
73 used to measure a device's resolution.
74
75 The format of the property for single-resolution mice is: ::
76
77 MOUSE_DPI=resolution@frequency
78
79 The resolution is in dots per inch, the frequency in Hz.
80 The format of the property for multi-resolution mice may list multiple
81 resolutions and frequencies: ::
82
83 MOUSE_DPI=r1@f1 *r2@f2 r3@f3
84
85 The default frequency must be pre-fixed with an asterisk.
86
87 For example, these two properties are valid: ::
88
89 MOUSE_DPI=800@125
90 MOUSE_DPI=400@125 800@125 *1000@500 5500@500
91
92 The behavior for a malformed property is undefined. If the property is
93 unset, libinput assumes the resolution is 1000dpi.
94
95 Note that HW does not usually provide information about run-time
96 resolution changes, libinput will thus not detect when a resolution
97 changes to the non-default value.