Multi-touch (MT) Protocol
-------------------------
- Copyright (C) 2009 Henrik Rydberg <rydberg@euromail.se>
+ Copyright (C) 2009-2010 Henrik Rydberg <rydberg@euromail.se>
Introduction
------------
-In order to utilize the full power of the new multi-touch devices, a way to
-report detailed finger data to user space is needed. This document
-describes the multi-touch (MT) protocol which allows kernel drivers to
-report details for an arbitrary number of fingers.
+In order to utilize the full power of the new multi-touch and multi-user
+devices, a way to report detailed data from multiple contacts, i.e.,
+objects in direct contact with the device surface, is needed. This
+document describes the multi-touch (MT) protocol which allows kernel
+drivers to report details for an arbitrary number of contacts.
+The protocol is divided into two types, depending on the capabilities of the
+hardware. For devices handling anonymous contacts (type A), the protocol
+describes how to send the raw data for all contacts to the receiver. For
+devices capable of tracking identifiable contacts (type B), the protocol
+describes how to send updates for individual contacts via event slots.
-Usage
------
-Anonymous finger details are sent sequentially as separate packets of ABS
-events. Only the ABS_MT events are recognized as part of a finger
-packet. The end of a packet is marked by calling the input_mt_sync()
-function, which generates a SYN_MT_REPORT event. This instructs the
-receiver to accept the data for the current finger and prepare to receive
-another. The end of a multi-touch transfer is marked by calling the usual
+Protocol Usage
+--------------
+
+Contact details are sent sequentially as separate packets of ABS_MT
+events. Only the ABS_MT events are recognized as part of a contact
+packet. Since these events are ignored by current single-touch (ST)
+applications, the MT protocol can be implemented on top of the ST protocol
+in an existing driver.
+
+Drivers for type A devices separate contact packets by calling
+input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
+event, which instructs the receiver to accept the data for the current
+contact and prepare to receive another.
+
+Drivers for type B devices separate contact packets by calling
+input_mt_slot(), with a slot as argument, at the beginning of each packet.
+This generates an ABS_MT_SLOT event, which instructs the receiver to
+prepare for updates of the given slot.
+
+All drivers mark the end of a multi-touch transfer by calling the usual
input_sync() function. This instructs the receiver to act upon events
-accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new
-set of events/packets.
+accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set
+of events/packets.
+
+The main difference between the stateless type A protocol and the stateful
+type B slot protocol lies in the usage of identifiable contacts to reduce
+the amount of data sent to userspace. The slot protocol requires the use of
+the ABS_MT_TRACKING_ID, either provided by the hardware or computed from
+the raw data [5].
+
+For type A devices, the kernel driver should generate an arbitrary
+enumeration of the full set of anonymous contacts currently on the
+surface. The order in which the packets appear in the event stream is not
+important. Event filtering and finger tracking is left to user space [3].
+
+For type B devices, the kernel driver should associate a slot with each
+identified contact, and use that slot to propagate changes for the contact.
+Creation, replacement and destruction of contacts is achieved by modifying
+the ABS_MT_TRACKING_ID of the associated slot. A non-negative tracking id
+is interpreted as a contact, and the value -1 denotes an unused slot. A
+tracking id not previously present is considered new, and a tracking id no
+longer present is considered removed. Since only changes are propagated,
+the full state of each initiated contact has to reside in the receiving
+end. Upon receiving an MT event, one simply updates the appropriate
+attribute of the current slot.
+
+
+Protocol Example A
+------------------
+
+Here is what a minimal event sequence for a two-contact touch would look
+like for a type A device:
+
+ ABS_MT_POSITION_X x[0]
+ ABS_MT_POSITION_Y y[0]
+ SYN_MT_REPORT
+ ABS_MT_POSITION_X x[1]
+ ABS_MT_POSITION_Y y[1]
+ SYN_MT_REPORT
+ SYN_REPORT
+
+The sequence after moving one of the contacts looks exactly the same; the
+raw data for all present contacts are sent between every synchronization
+with SYN_REPORT.
+
+Here is the sequence after lifting the first contact:
+
+ ABS_MT_POSITION_X x[1]
+ ABS_MT_POSITION_Y y[1]
+ SYN_MT_REPORT
+ SYN_REPORT
+
+And here is the sequence after lifting the second contact:
+
+ SYN_MT_REPORT
+ SYN_REPORT
+
+If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
+ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
+last SYN_REPORT will be dropped by the input core, resulting in no
+zero-contact event reaching userland.
+
+
+Protocol Example B
+------------------
+
+Here is what a minimal event sequence for a two-contact touch would look
+like for a type B device:
+
+ ABS_MT_SLOT 0
+ ABS_MT_TRACKING_ID 45
+ ABS_MT_POSITION_X x[0]
+ ABS_MT_POSITION_Y y[0]
+ ABS_MT_SLOT 1
+ ABS_MT_TRACKING_ID 46
+ ABS_MT_POSITION_X x[1]
+ ABS_MT_POSITION_Y y[1]
+ SYN_REPORT
+
+Here is the sequence after moving contact 45 in the x direction:
+
+ ABS_MT_SLOT 0
+ ABS_MT_POSITION_X x[0]
+ SYN_REPORT
+
+Here is the sequence after lifting the contact in slot 0:
+
+ ABS_MT_TRACKING_ID -1
+ SYN_REPORT
+
+The slot being modified is already 0, so the ABS_MT_SLOT is omitted. The
+message removes the association of slot 0 with contact 45, thereby
+destroying contact 45 and freeing slot 0 to be reused for another contact.
+
+Finally, here is the sequence after lifting the second contact:
+
+ ABS_MT_SLOT 1
+ ABS_MT_TRACKING_ID -1
+ SYN_REPORT
+
+
+Event Usage
+-----------
A set of ABS_MT events with the desired properties is defined. The events
are divided into categories, to allow for partial implementation. The
minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
-allows for multiple fingers to be tracked. If the device supports it, the
+allows for multiple contacts to be tracked. If the device supports it, the
ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
-of the contact area and approaching finger, respectively.
+of the contact area and approaching contact, respectively.
The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
looking through a window at someone gently holding a finger against the
ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
against the glass. The inner region will increase, and in general, the
ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
-unity, is related to the finger pressure. For pressure-based devices,
+unity, is related to the contact pressure. For pressure-based devices,
ABS_MT_PRESSURE may be used to provide the pressure on the contact area
-instead.
+instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to
+indicate the distance between the contact and the surface.
-In addition to the MAJOR parameters, the oval shape of the finger can be
+In addition to the MAJOR parameters, the oval shape of the contact can be
described by adding the MINOR parameters, such that MAJOR and MINOR are the
major and minor axis of an ellipse. Finally, the orientation of the oval
shape can be describe with the ORIENTATION parameter.
-The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
-finger or a pen or something else. Devices with more granular information
-may specify general shapes as blobs, i.e., as a sequence of rectangular
-shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
-that currently support it, the ABS_MT_TRACKING_ID event may be used to
-report finger tracking from hardware [5].
-
-Here is what a minimal event sequence for a two-finger touch would look
-like:
-
- ABS_MT_POSITION_X
- ABS_MT_POSITION_Y
- SYN_MT_REPORT
- ABS_MT_POSITION_X
- ABS_MT_POSITION_Y
- SYN_MT_REPORT
- SYN_REPORT
-
-Here is the sequence after lifting one of the fingers:
+For type A devices, further specification of the touch shape is possible
+via ABS_MT_BLOB_ID.
- ABS_MT_POSITION_X
- ABS_MT_POSITION_Y
- SYN_MT_REPORT
- SYN_REPORT
+The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
+finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
+may be used to track identified contacts over time [5].
-And here is the sequence after lifting the remaining finger:
+In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are
+implicitly handled by input core; drivers should instead call
+input_mt_report_slot_state().
- SYN_MT_REPORT
- SYN_REPORT
-
-If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
-ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
-last SYN_REPORT will be dropped by the input core, resulting in no
-zero-finger event reaching userland.
Event Semantics
---------------
-The word "contact" is used to describe a tool which is in direct contact
-with the surface. A finger, a pen or a rubber all classify as contacts.
-
ABS_MT_TOUCH_MAJOR
The length of the major axis of the contact. The length should be given in
of TOUCH and WIDTH for pressure-based devices or any device with a spatial
signal intensity distribution.
+ABS_MT_DISTANCE
+
+The distance, in surface units, between the contact and the surface. Zero
+distance means the contact is touching the surface. A positive number means
+the contact is hovering above the surface.
+
ABS_MT_ORIENTATION
The orientation of the ellipse. The value should describe a signed quarter
The type of approaching tool. A lot of kernel drivers cannot distinguish
between different tool types, such as a finger or a pen. In such cases, the
event should be omitted. The protocol currently supports MT_TOOL_FINGER and
-MT_TOOL_PEN [2].
+MT_TOOL_PEN [2]. For type B devices, this event is handled by input core;
+drivers should instead use input_mt_report_slot_state().
ABS_MT_BLOB_ID
The BLOB_ID groups several packets together into one arbitrarily shaped
-contact. This is a low-level anonymous grouping, and should not be confused
-with the high-level trackingID [5]. Most kernel drivers will not have blob
-capability, and can safely omit the event.
+contact. The sequence of points forms a polygon which defines the shape of
+the contact. This is a low-level anonymous grouping for type A devices, and
+should not be confused with the high-level trackingID [5]. Most type A
+devices do not have blob capability, so drivers can safely omit this event.
ABS_MT_TRACKING_ID
The TRACKING_ID identifies an initiated contact throughout its life cycle
-[5]. There are currently only a few devices that support it, so this event
-should normally be omitted.
+[5]. The value range of the TRACKING_ID should be large enough to ensure
+unique identification of a contact maintained over an extended period of
+time. For type B devices, this event is handled by input core; drivers
+should instead use input_mt_report_slot_state().
Event Computation
Finger Tracking
---------------
-The kernel driver should generate an arbitrary enumeration of the set of
-anonymous contacts currently on the surface. The order in which the packets
-appear in the event stream is not important.
-
The process of finger tracking, i.e., to assign a unique trackingID to each
-initiated contact on the surface, is left to user space; preferably the
-multi-touch X driver [3]. In that driver, the trackingID stays the same and
-unique until the contact vanishes (when the finger leaves the surface). The
-problem of assigning a set of anonymous fingers to a set of identified
-fingers is a euclidian bipartite matching problem at each event update, and
-relies on a sufficiently rapid update rate.
-
-There are a few devices that support trackingID in hardware. User space can
-make use of these native identifiers to reduce bandwidth and cpu usage.
+initiated contact on the surface, is a Euclidian Bipartite Matching
+problem. At each event synchronization, the set of actual contacts is
+matched to the set of contacts from the previous synchronization. A full
+implementation can be found in [3].
Gestures
Notes
-----
-In order to stay compatible with existing applications, the data
-reported in a finger packet must not be recognized as single-touch
-events. In addition, all finger data must bypass input filtering,
-since subsequent events of the same type refer to different fingers.
+In order to stay compatible with existing applications, the data reported
+in a finger packet must not be recognized as single-touch events.
+
+For type A devices, all finger data bypasses input filtering, since
+subsequent events of the same type refer to different fingers.
-The first kernel driver to utilize the MT protocol is the bcm5974 driver,
-where examples can be found.
+For example usage of the type A protocol, see the bcm5974 driver. For
+example usage of the type B protocol, see the hid-egalax driver.
[1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
difference between the contact position and the approaching tool position
could be used to derive tilt.
[2] The list can of course be extended.
-[3] Multitouch X driver project: http://bitmath.org/code/multitouch/.
+[3] The mtdev project: http://bitmath.org/code/mtdev/.
[4] See the section on event computation.
[5] See the section on finger tracking.
git.openpandora.org / pandora-kernel.git / blobdiff