linux/Documentation/input/multi-touch-protocol.txt
<<
>>
Prefs
   1Multi-touch (MT) Protocol
   2-------------------------
   3        Copyright (C) 2009      Henrik Rydberg <rydberg@euromail.se>
   4
   5
   6Introduction
   7------------
   8
   9In order to utilize the full power of the new multi-touch devices, a way to
  10report detailed finger data to user space is needed. This document
  11describes the multi-touch (MT) protocol which allows kernel drivers to
  12report details for an arbitrary number of fingers.
  13
  14
  15Usage
  16-----
  17
  18Anonymous finger details are sent sequentially as separate packets of ABS
  19events. Only the ABS_MT events are recognized as part of a finger
  20packet. The end of a packet is marked by calling the input_mt_sync()
  21function, which generates a SYN_MT_REPORT event. This instructs the
  22receiver to accept the data for the current finger and prepare to receive
  23another. The end of a multi-touch transfer is marked by calling the usual
  24input_sync() function. This instructs the receiver to act upon events
  25accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new
  26set of events/packets.
  27
  28A set of ABS_MT events with the desired properties is defined. The events
  29are divided into categories, to allow for partial implementation.  The
  30minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
  31ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked.  If the
  32device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
  33of the approaching finger. Anisotropy and direction may be specified with
  34ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION.  The
  35ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
  36finger or a pen or something else.  Devices with more granular information
  37may specify general shapes as blobs, i.e., as a sequence of rectangular
  38shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
  39that currently support it, the ABS_MT_TRACKING_ID event may be used to
  40report finger tracking from hardware [5].
  41
  42Here is what a minimal event sequence for a two-finger touch would look
  43like:
  44
  45   ABS_MT_TOUCH_MAJOR
  46   ABS_MT_POSITION_X
  47   ABS_MT_POSITION_Y
  48   SYN_MT_REPORT
  49   ABS_MT_TOUCH_MAJOR
  50   ABS_MT_POSITION_X
  51   ABS_MT_POSITION_Y
  52   SYN_MT_REPORT
  53   SYN_REPORT
  54
  55
  56Event Semantics
  57---------------
  58
  59The word "contact" is used to describe a tool which is in direct contact
  60with the surface. A finger, a pen or a rubber all classify as contacts.
  61
  62ABS_MT_TOUCH_MAJOR
  63
  64The length of the major axis of the contact. The length should be given in
  65surface units. If the surface has an X times Y resolution, the largest
  66possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
  67
  68ABS_MT_TOUCH_MINOR
  69
  70The length, in surface units, of the minor axis of the contact. If the
  71contact is circular, this event can be omitted [4].
  72
  73ABS_MT_WIDTH_MAJOR
  74
  75The length, in surface units, of the major axis of the approaching
  76tool. This should be understood as the size of the tool itself. The
  77orientation of the contact and the approaching tool are assumed to be the
  78same [4].
  79
  80ABS_MT_WIDTH_MINOR
  81
  82The length, in surface units, of the minor axis of the approaching
  83tool. Omit if circular [4].
  84
  85The above four values can be used to derive additional information about
  86the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
  87the notion of pressure. The fingers of the hand and the palm all have
  88different characteristic widths [1].
  89
  90ABS_MT_ORIENTATION
  91
  92The orientation of the ellipse. The value should describe a signed quarter
  93of a revolution clockwise around the touch center. The signed value range
  94is arbitrary, but zero should be returned for a finger aligned along the Y
  95axis of the surface, a negative value when finger is turned to the left, and
  96a positive value when finger turned to the right. When completely aligned with
  97the X axis, the range max should be returned.  Orientation can be omitted
  98if the touching object is circular, or if the information is not available
  99in the kernel driver. Partial orientation support is possible if the device
 100can distinguish between the two axis, but not (uniquely) any values in
 101between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
 102[4].
 103
 104ABS_MT_POSITION_X
 105
 106The surface X coordinate of the center of the touching ellipse.
 107
 108ABS_MT_POSITION_Y
 109
 110The surface Y coordinate of the center of the touching ellipse.
 111
 112ABS_MT_TOOL_TYPE
 113
 114The type of approaching tool. A lot of kernel drivers cannot distinguish
 115between different tool types, such as a finger or a pen. In such cases, the
 116event should be omitted. The protocol currently supports MT_TOOL_FINGER and
 117MT_TOOL_PEN [2].
 118
 119ABS_MT_BLOB_ID
 120
 121The BLOB_ID groups several packets together into one arbitrarily shaped
 122contact. This is a low-level anonymous grouping, and should not be confused
 123with the high-level trackingID [5]. Most kernel drivers will not have blob
 124capability, and can safely omit the event.
 125
 126ABS_MT_TRACKING_ID
 127
 128The TRACKING_ID identifies an initiated contact throughout its life cycle
 129[5]. There are currently only a few devices that support it, so this event
 130should normally be omitted.
 131
 132
 133Event Computation
 134-----------------
 135
 136The flora of different hardware unavoidably leads to some devices fitting
 137better to the MT protocol than others. To simplify and unify the mapping,
 138this section gives recipes for how to compute certain events.
 139
 140For devices reporting contacts as rectangular shapes, signed orientation
 141cannot be obtained. Assuming X and Y are the lengths of the sides of the
 142touching rectangle, here is a simple formula that retains the most
 143information possible:
 144
 145   ABS_MT_TOUCH_MAJOR := max(X, Y)
 146   ABS_MT_TOUCH_MINOR := min(X, Y)
 147   ABS_MT_ORIENTATION := bool(X > Y)
 148
 149The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
 150the device can distinguish between a finger along the Y axis (0) and a
 151finger along the X axis (1).
 152
 153
 154Finger Tracking
 155---------------
 156
 157The kernel driver should generate an arbitrary enumeration of the set of
 158anonymous contacts currently on the surface. The order in which the packets
 159appear in the event stream is not important.
 160
 161The process of finger tracking, i.e., to assign a unique trackingID to each
 162initiated contact on the surface, is left to user space; preferably the
 163multi-touch X driver [3]. In that driver, the trackingID stays the same and
 164unique until the contact vanishes (when the finger leaves the surface). The
 165problem of assigning a set of anonymous fingers to a set of identified
 166fingers is a euclidian bipartite matching problem at each event update, and
 167relies on a sufficiently rapid update rate.
 168
 169There are a few devices that support trackingID in hardware. User space can
 170make use of these native identifiers to reduce bandwidth and cpu usage.
 171
 172
 173Notes
 174-----
 175
 176In order to stay compatible with existing applications, the data
 177reported in a finger packet must not be recognized as single-touch
 178events. In addition, all finger data must bypass input filtering,
 179since subsequent events of the same type refer to different fingers.
 180
 181The first kernel driver to utilize the MT protocol is the bcm5974 driver,
 182where examples can be found.
 183
 184[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
 185difference between the contact position and the approaching tool position
 186could be used to derive tilt.
 187[2] The list can of course be extended.
 188[3] The multi-touch X driver is currently in the prototyping stage. At the
 189time of writing (April 2009), the MT protocol is not yet merged, and the
 190prototype implements finger matching, basic mouse support and two-finger
 191scrolling. The project aims at improving the quality of current multi-touch
 192functionality available in the Synaptics X driver, and in addition
 193implement more advanced gestures.
 194[4] See the section on event computation.
 195[5] See the section on finger tracking.
 196