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
23 describes how to send updates for individual contacts via event slots.
30 --------------
34 packet. Since these events are ignored by current single-touch (ST)
40 event, which instructs the receiver to accept the data for the current
45 This generates an ABS_MT_SLOT event, which instructs the receiver to
48 All drivers mark the end of a multi-touch transfer by calling the usual
61 surface. The order in which the packets appear in the event stream is not
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
81 a BTN_TOOL_*TAP event to inform userspace of the total number of contacts
83 explicitly sending the corresponding BTN_TOOL_*TAP event and setting
87 by noting that the largest supported BTN_TOOL_*TAP event is larger than the
93 ------------------
95 Here is what a minimal event sequence for a two-contact touch would look
123 ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
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
166 Event Usage
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
223 finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
231 Event Semantics
232 ---------------
241     contact is circular, this event can be omitted [#f4]_.
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.
317     event should be omitted. The protocol currently mainly supports
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
329     devices do not have blob capability, so drivers can safely omit this event.
335     time. For type B devices, this event is handled by input core; drivers
339 Event Computation
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 ---------------
387 problem.  At each event synchronization, the set of actual contacts is
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.
414 .. [#f4] See the section on event computation.