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 -----------
186 than unity, is related to the contact pressure. For pressure-based devices,
187 ABS_MT_PRESSURE may be used to provide the pressure on the contact area
217 direction of the finger ellipse is given by the vector (a - b).
232 ---------------
255     the notion of pressure. The fingers of the hand and the palm all have
259     The pressure, in arbitrary units, on the contact area. May be used instead
260     of TOUCH and WIDTH for pressure-based devices or any device with a spatial
263     If the resolution is zero, the pressure data is in arbitrary units.
264     If the resolution is non-zero, the pressure data is in units/gram. See
265     :ref:`input-event-codes` for details.
279     max should be returned; when aligned with the X axis in the negative
280     direction, the range -max should be returned.
283     degree orientation, the reported orientation must exceed the range max to
284     indicate more than a quarter of a revolution. For an upside-down finger,
285     range max * 2 should be returned.
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 -----------------
351    ABS_MT_TOUCH_MAJOR := max(X, Y)
378 ellipse should align with the vector (T - C), so the diameter must
383 ---------------
393 --------
396 parameters can be used to, e.g., approximate finger pressure or distinguish
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.