diff options
author | Ingo Molnar <mingo@elte.hu> | 2009-05-07 05:17:13 -0400 |
---|---|---|
committer | Ingo Molnar <mingo@elte.hu> | 2009-05-07 05:17:34 -0400 |
commit | 44347d947f628060b92449702071bfe1d31dfb75 (patch) | |
tree | c6ed74610d5b3295df4296659f80f5feb94b28cc /Documentation/input/multi-touch-protocol.txt | |
parent | d94fc523f3c35bd8013f04827e94756cbc0212f4 (diff) | |
parent | 413f81eba35d6ede9289b0c8a920c013a84fac71 (diff) |
Merge branch 'linus' into tracing/core
Merge reason: tracing/core was on a .30-rc1 base and was missing out on
on a handful of tracing fixes present in .30-rc5-almost.
Signed-off-by: Ingo Molnar <mingo@elte.hu>
Diffstat (limited to 'Documentation/input/multi-touch-protocol.txt')
-rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt new file mode 100644 index 000000000000..9f09557aea39 --- /dev/null +++ b/Documentation/input/multi-touch-protocol.txt | |||
@@ -0,0 +1,140 @@ | |||
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. The end of multi-touch | ||
22 | transfer is marked by calling the usual input_sync() function. | ||
23 | |||
24 | A set of ABS_MT events with the desired properties is defined. The events | ||
25 | are divided into categories, to allow for partial implementation. The | ||
26 | minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and | ||
27 | ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the | ||
28 | device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size | ||
29 | of the approaching finger. Anisotropy and direction may be specified with | ||
30 | ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. Devices with | ||
31 | more granular information may specify general shapes as blobs, i.e., as a | ||
32 | sequence of rectangular shapes grouped together by an | ||
33 | ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify | ||
34 | whether the touching tool is a finger or a pen or something else. | ||
35 | |||
36 | |||
37 | Event Semantics | ||
38 | --------------- | ||
39 | |||
40 | The word "contact" is used to describe a tool which is in direct contact | ||
41 | with the surface. A finger, a pen or a rubber all classify as contacts. | ||
42 | |||
43 | ABS_MT_TOUCH_MAJOR | ||
44 | |||
45 | The length of the major axis of the contact. The length should be given in | ||
46 | surface units. If the surface has an X times Y resolution, the largest | ||
47 | possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal. | ||
48 | |||
49 | ABS_MT_TOUCH_MINOR | ||
50 | |||
51 | The length, in surface units, of the minor axis of the contact. If the | ||
52 | contact is circular, this event can be omitted. | ||
53 | |||
54 | ABS_MT_WIDTH_MAJOR | ||
55 | |||
56 | The length, in surface units, of the major axis of the approaching | ||
57 | tool. This should be understood as the size of the tool itself. The | ||
58 | orientation of the contact and the approaching tool are assumed to be the | ||
59 | same. | ||
60 | |||
61 | ABS_MT_WIDTH_MINOR | ||
62 | |||
63 | The length, in surface units, of the minor axis of the approaching | ||
64 | tool. Omit if circular. | ||
65 | |||
66 | The above four values can be used to derive additional information about | ||
67 | the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates | ||
68 | the notion of pressure. The fingers of the hand and the palm all have | ||
69 | different characteristic widths [1]. | ||
70 | |||
71 | ABS_MT_ORIENTATION | ||
72 | |||
73 | The orientation of the ellipse. The value should describe half a revolution | ||
74 | clockwise around the touch center. The scale of the value is arbitrary, but | ||
75 | zero should be returned for an ellipse aligned along the Y axis of the | ||
76 | surface. As an example, an index finger placed straight onto the axis could | ||
77 | return zero orientation, something negative when twisted to the left, and | ||
78 | something positive when twisted to the right. This value can be omitted if | ||
79 | the touching object is circular, or if the information is not available in | ||
80 | the kernel driver. | ||
81 | |||
82 | ABS_MT_POSITION_X | ||
83 | |||
84 | The surface X coordinate of the center of the touching ellipse. | ||
85 | |||
86 | ABS_MT_POSITION_Y | ||
87 | |||
88 | The surface Y coordinate of the center of the touching ellipse. | ||
89 | |||
90 | ABS_MT_TOOL_TYPE | ||
91 | |||
92 | The type of approaching tool. A lot of kernel drivers cannot distinguish | ||
93 | between different tool types, such as a finger or a pen. In such cases, the | ||
94 | event should be omitted. The protocol currently supports MT_TOOL_FINGER and | ||
95 | MT_TOOL_PEN [2]. | ||
96 | |||
97 | ABS_MT_BLOB_ID | ||
98 | |||
99 | The BLOB_ID groups several packets together into one arbitrarily shaped | ||
100 | contact. This is a low-level anonymous grouping, and should not be confused | ||
101 | with the high-level contactID, explained below. Most kernel drivers will | ||
102 | not have this capability, and can safely omit the event. | ||
103 | |||
104 | |||
105 | Finger Tracking | ||
106 | --------------- | ||
107 | |||
108 | The kernel driver should generate an arbitrary enumeration of the set of | ||
109 | anonymous contacts currently on the surface. The order in which the packets | ||
110 | appear in the event stream is not important. | ||
111 | |||
112 | The process of finger tracking, i.e., to assign a unique contactID to each | ||
113 | initiated contact on the surface, is left to user space; preferably the | ||
114 | multi-touch X driver [3]. In that driver, the contactID stays the same and | ||
115 | unique until the contact vanishes (when the finger leaves the surface). The | ||
116 | problem of assigning a set of anonymous fingers to a set of identified | ||
117 | fingers is a euclidian bipartite matching problem at each event update, and | ||
118 | relies on a sufficiently rapid update rate. | ||
119 | |||
120 | Notes | ||
121 | ----- | ||
122 | |||
123 | In order to stay compatible with existing applications, the data | ||
124 | reported in a finger packet must not be recognized as single-touch | ||
125 | events. In addition, all finger data must bypass input filtering, | ||
126 | since subsequent events of the same type refer to different fingers. | ||
127 | |||
128 | The first kernel driver to utilize the MT protocol is the bcm5974 driver, | ||
129 | where examples can be found. | ||
130 | |||
131 | [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the | ||
132 | difference between the contact position and the approaching tool position | ||
133 | could be used to derive tilt. | ||
134 | [2] The list can of course be extended. | ||
135 | [3] The multi-touch X driver is currently in the prototyping stage. At the | ||
136 | time of writing (April 2009), the MT protocol is not yet merged, and the | ||
137 | prototype implements finger matching, basic mouse support and two-finger | ||
138 | scrolling. The project aims at improving the quality of current multi-touch | ||
139 | functionality available in the synaptics X driver, and in addition | ||
140 | implement more advanced gestures. | ||