doc: add a page about touchpads

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

2 files changed, 164 insertions, 1 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 01bcd1b..c9dccfd 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -24,7 +24,8 @@ header_files = \
 	$(srcdir)/t440-support.dox \
 	$(srcdir)/tapping.dox \
 	$(srcdir)/test-suite.dox \
-	$(srcdir)/tools.dox
+	$(srcdir)/tools.dox \
+	$(srcdir)/touchpads.dox
 
 diagram_files = \
 	$(srcdir)/dot/seats-sketch.gv \
diff --git a/doc/touchpads.dox b/doc/touchpads.dox
new file mode 100644
index 0000000..fa509bc
--- /dev/null
+++ b/doc/touchpads.dox
@@ -0,0 +1,162 @@
+/**
+@page touchpads Touchpads
+
+This page provides an outline of touchpad devices. Touchpads aren't simply
+categorised into a single type, instead they have a set of properties, a
+combination of number of physical buttons, multitouch support abilities and
+other properties.
+
+@section touchpads_buttons Number of buttons
+
+@subsection touchapds_buttons_phys Physically separate buttons
+
+Touchpads with physical buttons usually provide two buttons, left and right.
+A few touchpads with three buttons exist, and Apple used to have touchpads
+with a single physical buttons until ca 2008. Touchpads with only two
+buttons require the software stack to emulate a middle button. libinput does
+this when both buttons are pressed simultaneously.
+
+Note that many Lenovo laptops provide a pointing stick above the touchpad.
+This pointing stick has a set of physical buttons just above the touchpad.
+While many users use those as substitute touchpad buttons, they logically
+belong to the pointing stick. The *40 and *50 series are an exception here,
+the former had no physical buttons on the touchpad and required the top
+section of the pad to emulate pointing stick buttons, the *50 series has
+physical buttons but they are wired to the touchpads. The kernel re-routes
+those buttons through the trackstick device. See @ref t440_support for more
+information.
+
+@subsection touchpads_buttons_clickpads Clickpads
+
+Clickpads are the most common type of touchpads these days. A Clickpad has
+no separate physical buttons, instead the touchpad itself is clickable as a
+whole, i.e. a user presses down on the touch area and triggers a physical
+click. Clickpads thus only provide a single button, everything else needs to
+be software-emulated. See @ref clickpad_softbuttons for more information.
+
+Clickpads are labelled by the kernel with the @c INPUT_PROP_BUTTONPAD input
+property.
+
+@subsection touchpads_buttons_forcepads Forcepads
+
+Forcepads are Clickpads without a physical button underneath the hardware.
+They provide pressure and may have a vibration element that is
+software-controlled. This element can simulate the feel of a physical
+click or be co-opted for other tasks.
+
+
+@section touchpads_touch Touch capabilities
+
+Virtually all touchpads available now can <b>detect</b> multiple fingers on
+the touchpad, i.e. provide information on how many fingers are on the
+touchpad. The touch capabilities described here specify how many fingers a
+device can <b>track</b>, i.e. provide reliable positional information for. 
+In the kernel each finger is tracked in a so-called "slot", the number of
+slots thus equals the number of simultaneous touches a device can track.
+
+@subsection touchapds_touch_st Single-touch touchpads
+
+Single-finger touchpads can track a single touchpoint. Most single-touch
+touchpads can also detect three fingers on the touchpad, but no positional
+information is provided for those. In libinput, these touches are termed
+"fake touches". The kernel sends @c BTN_TOOL_DOUBLETAP, @c
+BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events when
+multiple fingers are detected.
+
+@subsection touchpads_touch_mt Pure multi-touch touchpads
+
+Pure multi-touch touchpads are those that can track, i.e. identify the
+location of all fingers on the touchpad. Apple's touchpads support 16
+touches, others support 5 touches like the Synaptics touchpads when using
+SMBus.
+
+These touchpads usually also provide extra information. Apple touchpads
+provide an ellipsis and the orientation of the ellipsis for each touch point.
+Other touchpads provide a pressure value for each touch point (see @ref
+touchpads_pressure_handling).
+
+Note that the kernel sends @c BTN_TOOL_DOUBLETAP, @c
+BTN_TOOL_TRIPLETAP, @c BTN_TOOL_QUADTAP and @c BTN_TOOL_QUINTTAP events for
+all touches for backwards compatibility. libinput ignores these events if
+the touchpad can track touches correctly.
+
+@subsection touchpads_touch_partial_mt Partial multi-touch touchpads
+
+The vast majority of touchpads fall into this category, the half-way
+point between single-touch and pure multi-touch. These devices can track N
+fingers, but detect more than N. For example, when using the serial
+protocol, Synaptics touchpads can track two fingers but may detect up to
+five.
+
+The number of slots may limit which features are available in libinput.
+Any device with two slots can support two-finger scrolling, but @ref
+thumb-detection or @ref palm_detection may be limited if only two slots are
+available.
+
+@subsection touchpads_touch_semi_mt Semi-mt touchpads
+
+A sub-class of partial multi-touch touchpads. These touchpads can
+technically detect two fingers but the location of both is limited to the
+bounding box, i.e. the first touch is always the top-left one and the second
+touch is the bottom-right one. Coordinates jump around as fingers move past
+each other.
+
+Many semi-mt touchpads also have a lower resolution for the second touch, or
+both touches. This may limit some features such as @ref gestures or
+@ref scrolling.
+
+Semi-mt are labelled by the kernel with the @c INPUT_PROP_SEMI_MT input
+property.
+
+@section touchpads_mis Other touchpad properties
+
+@subsection touchpads_external External touchpads
+
+External touchpads are USB or Bluetooth touchpads not in a laptop chassis,
+e.g. Apple Magic Trackpad or the Logitech T650. These are usually @ref
+touchpads_buttons_clickpads the biggest difference is that they can be
+removed or added at runtime. 
+
+One interaction method that is only possible on external touchpads is a
+thumb resting on the very edge/immediately next to the touchpad. On the far
+edge, touchpads don't always detect the finger location so clicking with a
+thumb barely touching the edge makes it hard or impossible to figure out
+which software button area the finger is on.
+
+These touchpads also don't need @ref palm_detection - since they're not
+located underneath the keyboard, accidental palm touches are a non-issue.
+
+@subsection touchpads_pressure_handling Touchpads pressure handling
+
+Pressure is usually directly related to contact area. Human fingers flatten
+out as the pressure on the pad increases, resulting in a bigger contact area
+and the firmware then calculates that back into a ressure reading.
+
+libinput uses pressure to detect accidental palm contact and thumbs, though
+pressure data is often device-specific and unreliable.
+
+@subsection touchpads_circular Circular touchpads
+
+Only listed for completeness, circular touchpads have not been used in
+laptops for a number of years. These touchpad shaped in an ellipsis or
+straight.
+
+@subsection touchpads_tablets Graphics tablets
+
+Touch-capable graphics tablets are effectively external touchpads, with two
+differentiators: they are larger than normal touchpads and they have no
+regular touchpad buttons. They either work like a @ref
+touchpads_buttons_forcepads Forcepad, or rely on interaction methods that
+don't require buttons (like @ref tapping). Since the physical device is
+shared with the pen input, some touch arbitration is required to avoid touch
+input interfering when the pen is in use.  
+
+@subsection touchpads_edge_zone Dedicated edge scroll area
+
+Before @ref twofinger_scrolling became the default scroll method, some
+touchpads provided a marking on the touch area that designates the
+edge to be used for scrolling. A finger movement in that edge zone should
+trigger vertical motions. Some touchpads had markers for a horizontal
+scroll area too at the bottom of the touchpad.
+*/
+