Documentation/input/multi-touch-protocol.rst

4 Multi-touch (MT) Protocol
7 :Copyright: |copy| 2009-2010	Henrik Rydberg <rydberg@euromail.se>
11 ------------
13 In order to utilize the full power of the new multi-touch and multi-user
16 document describes the multi-touch (MT) protocol which allows kernel
30 --------------
34 packet. Since these events are ignored by current single-touch (ST)
48 All drivers mark the end of a multi-touch transfer by calling the usual
67 the ABS_MT_TRACKING_ID of the associated slot.  A non-negative tracking id
68 is interpreted as a contact, and the value -1 denotes an unused slot.  A
93 ------------------
95 Here is what a minimal event sequence for a two-contact touch would look
125 zero-contact event reaching userland.
129 ------------------
131 Here is what a minimal event sequence for a two-contact touch would look
152    ABS_MT_TRACKING_ID -1
162    ABS_MT_TRACKING_ID -1
167 -----------
176 The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
182 ABS_MT_TOOL_X/Y. The touch diameter is ABS_MT_TOUCH_MAJOR and the finger
184 harder against the glass. The touch region will increase, and in general,
186 than unity, is related to the contact pressure. For pressure-based devices,
213 In addition to the MAJOR parameters, the oval shape of the touch and finger
216 the touch ellipse can be described with the ORIENTATION parameter, and the
217 direction of the finger ellipse is given by the vector (a - b).
219 For type A devices, further specification of the touch shape is possible
232 ---------------
260     of TOUCH and WIDTH for pressure-based devices or any device with a spatial
264     If the resolution is non-zero, the pressure data is in units/gram. See
265     :ref:`input-event-codes` for details.
274     quarter of a revolution clockwise around the touch center. The signed value
280     direction, the range -max should be returned.
282     Touch ellipses are symmetrical by default. For devices capable of true 360
284     indicate more than a quarter of a revolution. For an upside-down finger,
287     Orientation can be omitted if the touch area is circular, or if the
301     the device cannot distinguish between the intended touch point and the
306     device cannot distinguish between the intended touch point and the tool
309     The four position values can be used to separate the position of the touch
311     tool axis points towards the touch point [#f1]_. Otherwise, the tool axes are
312     aligned with the touch axes.
327     the contact. This is a low-level anonymous grouping for type A devices, and
328     should not be confused with the high-level trackingID [#f5]_. Most type A
340 -----------------
378 ellipse should align with the vector (T - C), so the diameter must
379 increase with distance(T, C). Finally, assume that the touch diameter is
383 ---------------
393 --------
395 In the specific application of creating gesture events, the TOUCH and WIDTH
403 -----
406 in a finger packet must not be recognized as single-touch events.
411 .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt.