239 lines
9.2 KiB
Plaintext
239 lines
9.2 KiB
Plaintext
Multi-touch (MT) Protocol
|
|
-------------------------
|
|
Copyright (C) 2009 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.
|
|
|
|
|
|
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
|
|
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.
|
|
|
|
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
|
|
ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
|
|
of the contact area and approaching finger, respectively.
|
|
|
|
The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
|
|
looking through a window at someone gently holding a finger against the
|
|
glass. You will see two regions, one inner region consisting of the part
|
|
of the finger actually touching the glass, and one outer region formed by
|
|
the perimeter of the finger. The diameter of the inner region is the
|
|
ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
|
|
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,
|
|
ABS_MT_PRESSURE may be used to provide the pressure on the contact area
|
|
instead.
|
|
|
|
In addition to the MAJOR parameters, the oval shape of the finger 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:
|
|
|
|
ABS_MT_POSITION_X
|
|
ABS_MT_POSITION_Y
|
|
SYN_MT_REPORT
|
|
SYN_REPORT
|
|
|
|
And here is the sequence after lifting the remaining finger:
|
|
|
|
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
|
|
surface units. If the surface has an X times Y resolution, the largest
|
|
possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4].
|
|
|
|
ABS_MT_TOUCH_MINOR
|
|
|
|
The length, in surface units, of the minor axis of the contact. If the
|
|
contact is circular, this event can be omitted [4].
|
|
|
|
ABS_MT_WIDTH_MAJOR
|
|
|
|
The length, in surface units, of the major axis of the approaching
|
|
tool. This should be understood as the size of the tool itself. The
|
|
orientation of the contact and the approaching tool are assumed to be the
|
|
same [4].
|
|
|
|
ABS_MT_WIDTH_MINOR
|
|
|
|
The length, in surface units, of the minor axis of the approaching
|
|
tool. Omit if circular [4].
|
|
|
|
The above four values can be used to derive additional information about
|
|
the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
|
|
the notion of pressure. The fingers of the hand and the palm all have
|
|
different characteristic widths [1].
|
|
|
|
ABS_MT_PRESSURE
|
|
|
|
The pressure, in arbitrary units, on the contact area. May be used instead
|
|
of TOUCH and WIDTH for pressure-based devices or any device with a spatial
|
|
signal intensity distribution.
|
|
|
|
ABS_MT_ORIENTATION
|
|
|
|
The orientation of the ellipse. The value should describe a signed quarter
|
|
of a revolution clockwise around the touch center. The signed value range
|
|
is arbitrary, but zero should be returned for a finger aligned along the Y
|
|
axis of the surface, a negative value when finger is turned to the left, and
|
|
a positive value when finger turned to the right. When completely aligned with
|
|
the X axis, the range max should be returned. Orientation can be omitted
|
|
if the touching object is circular, or if the information is not available
|
|
in the kernel driver. Partial orientation support is possible if the device
|
|
can distinguish between the two axis, but not (uniquely) any values in
|
|
between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
|
|
[4].
|
|
|
|
ABS_MT_POSITION_X
|
|
|
|
The surface X coordinate of the center of the touching ellipse.
|
|
|
|
ABS_MT_POSITION_Y
|
|
|
|
The surface Y coordinate of the center of the touching ellipse.
|
|
|
|
ABS_MT_TOOL_TYPE
|
|
|
|
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].
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
Event Computation
|
|
-----------------
|
|
|
|
The flora of different hardware unavoidably leads to some devices fitting
|
|
better to the MT protocol than others. To simplify and unify the mapping,
|
|
this section gives recipes for how to compute certain events.
|
|
|
|
For devices reporting contacts as rectangular shapes, signed orientation
|
|
cannot be obtained. Assuming X and Y are the lengths of the sides of the
|
|
touching rectangle, here is a simple formula that retains the most
|
|
information possible:
|
|
|
|
ABS_MT_TOUCH_MAJOR := max(X, Y)
|
|
ABS_MT_TOUCH_MINOR := min(X, Y)
|
|
ABS_MT_ORIENTATION := bool(X > Y)
|
|
|
|
The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
|
|
the device can distinguish between a finger along the Y axis (0) and a
|
|
finger along the X axis (1).
|
|
|
|
|
|
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.
|
|
|
|
|
|
Gestures
|
|
--------
|
|
|
|
In the specific application of creating gesture events, the TOUCH and WIDTH
|
|
parameters can be used to, e.g., approximate finger pressure or distinguish
|
|
between index finger and thumb. With the addition of the MINOR parameters,
|
|
one can also distinguish between a sweeping finger and a pointing finger,
|
|
and with ORIENTATION, one can detect twisting of fingers.
|
|
|
|
|
|
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.
|
|
|
|
The first kernel driver to utilize the MT protocol is the bcm5974 driver,
|
|
where examples can be found.
|
|
|
|
[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/.
|
|
[4] See the section on event computation.
|
|
[5] See the section on finger tracking.
|