Debian Codegraph @

doc/user/touchpad-pressure.rst

raw
1 .. _touchpad_pressure:
2
3 ==============================================================================
4 Touchpad pressure-based touch detection
5 ==============================================================================
6
7 libinput uses the touchpad pressure values and/or touch size values to
8 detect whether a finger has been placed on the touchpad. This is
9 :ref:`kernel_pressure_information` and combines with a libinput-specific hardware
10 database to adjust the thresholds on a per-device basis. libinput uses
11 these thresholds primarily to filter out accidental light touches but
12 the information is also used for some :ref:`palm_detection`.
13
14 Most devices only support one of either touch pressure or touch size.
15 libinput uses whichever is available but a preference is given to touch size
16 as it provides more specific information. Since most devices only provide
17 one type anyway, this internal preference does not usually matter.
18
19 Pressure and touch size thresholds are **not** directly configurable by the
20 user. Instead, libinput provides these thresholds for each device where
21 necessary. See :ref:`touchpad_pressure_hwdb` for instructions on how to adjust
22 the pressure ranges and :ref:`touchpad_touch_size_hwdb` for instructions on
23 how to adjust the touch size ranges.
24
25 .. _kernel_pressure_information:
26
27 ------------------------------------------------------------------------------
28 Information provided by the kernel
29 ------------------------------------------------------------------------------
30
31 The kernel sends multiple values to inform userspace about a finger touching
32 the touchpad. The most basic is the ``EV_KEY/BTN_TOUCH`` boolean event
33 that simply announces physical contact with the touchpad. The decision when
34 this event is sent is usually made by the kernel driver and may depend on
35 device-specific thresholds. These thresholds are transparent to userspace
36 and cannot be modified. On touchpads where pressure or touch size is not
37 available, libinput uses ``BTN_TOUCH`` to determine when a finger is
38 logically down.
39
40 Many contemporary touchpad devices provide an absolute pressure axis in
41 addition to ``BTN_TOUCH``. This pressure generally increases as the pressure
42 increases, however few touchpads are capable of detecting true pressure. The
43 pressure value is usually related to the covered area - as the pressure
44 increases a finger flattens and thus covers a larger area. The range
45 provided by the kernel is not mapped to a specific physical range and
46 often requires adjustment. Pressure is sent by the ``ABS_PRESSURE`` axis
47 for single-touch touchpads or ``ABS_MT_PRESSURE`` on multi-touch capable
48 touchpads. Some devices can detect multiple fingers but only provide
49 ``ABS_PRESSURE``.
50
51 Some devices provide additional touch size information through
52 the ``ABS_MT_TOUCH_MAJOR/ABS_MT_TOUCH_MINOR`` axes and/or
53 the ``ABS_MT_WIDTH_MAJOR/ABS_MT_WIDTH_MINOR`` axes. These axes specifcy
54 the size of the touch ellipse. While the kernel documentation specifies how
55 these axes are supposed to be mapped, few devices forward reliable
56 information. libinput uses these values together with a device-specific
57 :ref:`device-quirks` entry. In other words, touch size detection does not work
58 unless a device quirk is present for the device.