doc/user: add documentation for the new thumb detection

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

doc/user/features.rst

@@ -18,6 +18,7 @@ to be useful.
    gestures.rst
    middle-button-emulation.rst
    palm-detection.rst
+   touchpad-thumb-detection.rst
    scrolling.rst
    t440-support.rst
    tapping.rst

doc/user/meson.build

@@ -159,6 +159,7 @@ src_rst = files(
 	'touchpad-pressure.rst',
 	'touchpad-pressure-debugging.rst',
 	'touchpad-jitter.rst',
+	'touchpad-thumb-detection.rst',
 	'touchpads.rst',
 	'trackpoints.rst',
 	'trackpoint-configuration.rst',

doc/user/touchpad-thumb-detection.rst

@@ -0,0 +1,89 @@
+.. _thumb_detection:
+
+==============================================================================
+Thumb detection
+==============================================================================
+
+Thumb detection tries to identify touches triggered by a thumb rather than a
+pointer-moving finger. This is necessary on :ref:`touchpads_buttons_clickpads`
+as a finger pressing a button always creates a new touch, causing
+misinterpretation of gestures. Click-and-drag with two fingers (one holding
+the button, one moving) would be interpreted as two-finger scrolling without
+working thumb detection.
+
+libinput has built-in thumb detection, partially dependent on
+hardware-specific capabilities.
+
+- :ref:`thumb_pressure`
+- :ref:`thumb_areas`
+- :ref:`thumb_speed`
+
+Thumb detection uses multiple approaches and the final decision on whether
+to ignore a thumb depends on the interaction at the time.
+
+.. _thumb_pressure:
+
+------------------------------------------------------------------------------
+Thumb detection based on pressure or size
+------------------------------------------------------------------------------
+
+The simplest form of thumb detection identifies a touch as thumb when the
+pressure value goes above a certain threshold. This threshold is usually
+high enough that it cannot be triggered by a finger movement.
+
+On touchpads that support the ``ABS_MT_TOUCH_MAJOR`` axes, libinput can perform
+thumb detection based on the size of the touch ellipse. This works similar to
+the pressure-based palm detection in that a touch is labelled as palm when
+it exceeds the (device-specific) touch size threshold.
+
+Pressure- and size-based thumb detection depends on the location of the
+thumb and usually only applies within the :ref:`thumb_areas`.
+
+For some information on how to detect pressure on a touch and debug the
+pressure ranges, see :ref:`touchpad_pressure`. Pressure- and size-based
+thumb detection require thresholds set in the :ref:`device-quirks`.
+
+.. _thumb_areas:
+
+------------------------------------------------------------------------------
+Thumb detection areas
+------------------------------------------------------------------------------
+
+Pressure and size readings are unreliable at the far bottom of the touchpad.
+A thumb hanging mostly off the touchpad will have a small surface area.
+libinput has a definitive thumb zone where any touch is considered a
+thumb. Immediately above that area is the area where libinput will label a
+thumb as such if the pressure or size thresholds are exceeded.
+
+
+.. figure:: thumb-detection.svg
+    :align: center
+
+The picture above shows the two detection areas. In the larger (light red)
+area, a touch is labelled as thumb when it exceeds a device-specific
+pressure threshold. In the lower (dark red) area, a touch is always labelled
+as thumb.
+
+Moving outside the areas generally releases the thumb from being a thumb.
+
+.. _thumb_speed:
+
+------------------------------------------------------------------------------
+Thumb movement based on speed
+------------------------------------------------------------------------------
+
+Regular interactions with thumbs do not usually move the thumb. When fingers
+are moving across the touchpad and a thumb is dropped, this can cause
+erroneous scroll motion or similar issues. libinput observes the finger
+motion speed for all touches - where a finger has been moving a newly
+dropped finger is more likely to be labeled as thumb.
+
+------------------------------------------------------------------------------
+Thumb detection based on finger positions
+------------------------------------------------------------------------------
+
+The shape of the human hand and the interactions that usually involve a
+thumb imply that a thumb is situated in a specific position relative to
+other fingers (usually to the side and below). This is used by libinput to
+detect thumbs during some interactions that do not implicitly require a
+thumb (e.g. pinch-and-rotate).