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