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)
39 input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
48 All drivers mark the end of a multi-touch transfer by calling the usual
62 important.  Event filtering and finger tracking is left to user space [#f3]_.
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
72 end.  Upon receiving an MT event, one simply updates the appropriate
93 ------------------
95 Here is what a minimal event sequence for a two-contact touch would look
124 last SYN_REPORT will be dropped by the input core, resulting in no
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,
217 direction of the finger ellipse is given by the vector (a - b).
227 implicitly handled by input core; drivers should instead call
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.
277     turned to the left, and a positive value when the ellipse is turned to the
280     direction, the range -max should be returned.
284     indicate more than a quarter of a revolution. For an upside-down finger,
319     For type B devices, this event is handled by input core; drivers should
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
335     time. For type B devices, this event is handled by input core; drivers
340 -----------------
378 ellipse should align with the vector (T - C), so the diameter must
383 ---------------
393 --------
403 -----
406 in a finger packet must not be recognized as single-touch events.
408 For type A devices, all finger data bypasses input filtering, since
411 .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt.