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