| 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. |