diff options
author | Peter Hutterer <peter.hutterer@who-t.net> | 2014-12-03 11:57:35 +1000 |
---|---|---|
committer | Peter Hutterer <peter.hutterer@who-t.net> | 2014-12-03 11:57:35 +1000 |
commit | 1cd5e81fbc4b39f8551e877456d6bddbba70fa0b (patch) | |
tree | 69692eaeb61e1a1ed15d0e69056802ff4108258d | |
parent | 56b5f846ac7f8243da4ba2f288654becf1014c46 (diff) | |
download | libinput-1cd5e81fbc4b39f8551e877456d6bddbba70fa0b.tar.gz |
Document relative motion normalization
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
-rw-r--r-- | src/libinput.h | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/src/libinput.h b/src/libinput.h index db56da7f..5608eaa3 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -124,6 +124,10 @@ extern "C" { * <dd>Assigns the logical seat for this device. See * libinput_seat_get_logical_name() * context. Defaults to "default".</dd> + * <dt>MOUSE_DPI</dt> + * <dd>HW resolution and sampling frequency of a relative pointer device. + * See @ref motion_normalization for details. + * </dd> * </dl> * * Below is an example udev rule to assign "seat1" to a device from vendor @@ -136,6 +140,57 @@ extern "C" { */ /** + * @page motion_normalization Normalization of relative motion + * + * Most relative input devices generate input in so-called "mickeys". A + * mickey is in device-specific units that depend on the resolution + * of the sensor. Most optical mice use sensors with 1000dpi resolution, but + * some devices range from 100dpi to well above 8000dpi. + * + * Without a physical reference point, a relative coordinate cannot be + * interpreted correctly. A delta of 10 mickeys may be a millimeter of + * physical movement or 10 millimeters, depending on the sensor. This + * affects pointer acceleration in libinput and interpretation of relative + * coordinates in callers. + * + * libinput normalizes all relative input to a physical resolution of + * 1000dpi, the same delta from two different devices thus represents the + * same physical movement of those two devices (within sensor error + * margins). + * + * Devices usually do not advertise their resolution and libinput relies on + * the udev property MOUSE_DPI for this information. + * + * The format of the property for single-resolution mice is: + * @code + * MOUSE_DPI=resolution@frequency + * @endcode + * + * The resolution is in dots per inch, the frequency in Hz. + * The format of the property for multi-resolution mice may list multiple + * resolutions and frequencies: + * @code + * MOUSE_DPI=r1@f1 *r2@f2 r3@f3 + * @endcode + * + * The default frequency must be pre-fixed with an asterisk. + * + * For example, these two properties are valid: + * @code + * MOUSE_DPI=800@125 + * MOUSE_DPI=400@125 800@125 *1000@500 5500@500 + * @endcode + * + * The behavior for a malformed property is undefined. + * + * If the property is unset, libinput assumes the resolution is 1000dpi. + * + * Note that HW does not usually provide information about the resolution + * changes, libinput will thus not detect when a resolution changes to the + * non-default value. + */ + +/** * Log priority for internal logging messages. */ enum libinput_log_priority { @@ -468,6 +523,9 @@ libinput_event_pointer_get_time(struct libinput_event_pointer *event); * If a device employs pointer acceleration, the delta returned by this * function is the accelerated delta. * + * Relative motion deltas are normalized to represent those of a device with + * 1000dpi resolution. See @ref motion_normalization for more details. + * * @note It is an application bug to call this function for events other than * @ref LIBINPUT_EVENT_POINTER_MOTION. * @@ -486,6 +544,9 @@ libinput_event_pointer_get_dx(struct libinput_event_pointer *event); * If a device employs pointer acceleration, the delta returned by this * function is the accelerated delta. * + * Relative motion deltas are normalized to represent those of a device with + * 1000dpi resolution. See @ref motion_normalization for more details. + * * @note It is an application bug to call this function for events other than * @ref LIBINPUT_EVENT_POINTER_MOTION. * |