diff options
author | Henrik Rydberg <rydberg@euromail.se> | 2009-05-23 12:51:21 -0400 |
---|---|---|
committer | Dmitry Torokhov <dmitry.torokhov@gmail.com> | 2009-05-23 12:53:26 -0400 |
commit | f9fcfc3b4627a1ec9b50411060f1b384926d6610 (patch) | |
tree | 1eb1533ef954e04111323ca2ce71a33f4bb83779 | |
parent | df391e0eda1e678add56a8e34226edf05d89af6a (diff) |
Input: multitouch - augment event semantics documentation
Through the collaboration to adapt the N-trig and Stantum HID
drivers to the MT protocol, some semantic clarifications to the
protocol have been made. This patch adds them to the MT documentation.
Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
Tested-by: Stéphane Chatty <chatty@enac.fr>
Signed-off-by: Dmitry Torokhov <dtor@mail.ru>
-rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 103 |
1 files changed, 79 insertions, 24 deletions
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index 9f09557aea39..a12ea3b586e6 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt | |||
@@ -18,8 +18,12 @@ Usage | |||
18 | Anonymous finger details are sent sequentially as separate packets of ABS | 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 | 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() | 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 | 21 | function, which generates a SYN_MT_REPORT event. This instructs the |
22 | transfer is marked by calling the usual input_sync() function. | 22 | receiver to accept the data for the current finger and prepare to receive |
23 | another. The end of a multi-touch transfer is marked by calling the usual | ||
24 | input_sync() function. This instructs the receiver to act upon events | ||
25 | accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new | ||
26 | set of events/packets. | ||
23 | 27 | ||
24 | A set of ABS_MT events with the desired properties is defined. The events | 28 | 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 | 29 | are divided into categories, to allow for partial implementation. The |
@@ -27,11 +31,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 | 31 | 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 | 32 | 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 | 33 | 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 | 34 | ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. The |
31 | more granular information may specify general shapes as blobs, i.e., as a | 35 | ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a |
32 | sequence of rectangular shapes grouped together by an | 36 | finger or a pen or something else. Devices with more granular information |
33 | ABS_MT_BLOB_ID. Finally, the ABS_MT_TOOL_TYPE may be used to specify | 37 | may specify general shapes as blobs, i.e., as a sequence of rectangular |
34 | whether the touching tool is a finger or a pen or something else. | 38 | shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices |
39 | that currently support it, the ABS_MT_TRACKING_ID event may be used to | ||
40 | report finger tracking from hardware [5]. | ||
41 | |||
42 | Here is what a minimal event sequence for a two-finger touch would look | ||
43 | like: | ||
44 | |||
45 | ABS_MT_TOUCH_MAJOR | ||
46 | ABS_MT_POSITION_X | ||
47 | ABS_MT_POSITION_Y | ||
48 | SYN_MT_REPORT | ||
49 | ABS_MT_TOUCH_MAJOR | ||
50 | ABS_MT_POSITION_X | ||
51 | ABS_MT_POSITION_Y | ||
52 | SYN_MT_REPORT | ||
53 | SYN_REPORT | ||
35 | 54 | ||
36 | 55 | ||
37 | Event Semantics | 56 | Event Semantics |
@@ -44,24 +63,24 @@ ABS_MT_TOUCH_MAJOR | |||
44 | 63 | ||
45 | The length of the major axis of the contact. The length should be given in | 64 | 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 | 65 | 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. | 66 | possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. |
48 | 67 | ||
49 | ABS_MT_TOUCH_MINOR | 68 | ABS_MT_TOUCH_MINOR |
50 | 69 | ||
51 | The length, in surface units, of the minor axis of the contact. If the | 70 | The length, in surface units, of the minor axis of the contact. If the |
52 | contact is circular, this event can be omitted. | 71 | contact is circular, this event can be omitted [4]. |
53 | 72 | ||
54 | ABS_MT_WIDTH_MAJOR | 73 | ABS_MT_WIDTH_MAJOR |
55 | 74 | ||
56 | The length, in surface units, of the major axis of the approaching | 75 | 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 | 76 | 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 | 77 | orientation of the contact and the approaching tool are assumed to be the |
59 | same. | 78 | same [4]. |
60 | 79 | ||
61 | ABS_MT_WIDTH_MINOR | 80 | ABS_MT_WIDTH_MINOR |
62 | 81 | ||
63 | The length, in surface units, of the minor axis of the approaching | 82 | The length, in surface units, of the minor axis of the approaching |
64 | tool. Omit if circular. | 83 | tool. Omit if circular [4]. |
65 | 84 | ||
66 | The above four values can be used to derive additional information about | 85 | 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 | 86 | the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates |
@@ -70,14 +89,17 @@ different characteristic widths [1]. | |||
70 | 89 | ||
71 | ABS_MT_ORIENTATION | 90 | ABS_MT_ORIENTATION |
72 | 91 | ||
73 | The orientation of the ellipse. The value should describe half a revolution | 92 | The orientation of the ellipse. The value should describe a signed quarter |
74 | clockwise around the touch center. The scale of the value is arbitrary, but | 93 | of a revolution clockwise around the touch center. The signed value range |
75 | zero should be returned for an ellipse aligned along the Y axis of the | 94 | is arbitrary, but zero should be returned for a finger aligned along the Y |
76 | surface. As an example, an index finger placed straight onto the axis could | 95 | axis of the surface, a negative value when finger is turned to the left, and |
77 | return zero orientation, something negative when twisted to the left, and | 96 | a positive value when finger turned to the right. When completely aligned with |
78 | something positive when twisted to the right. This value can be omitted if | 97 | the X axis, the range max should be returned. Orientation can be omitted |
79 | the touching object is circular, or if the information is not available in | 98 | if the touching object is circular, or if the information is not available |
80 | the kernel driver. | 99 | in the kernel driver. Partial orientation support is possible if the device |
100 | can distinguish between the two axis, but not (uniquely) any values in | ||
101 | between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] | ||
102 | [4]. | ||
81 | 103 | ||
82 | ABS_MT_POSITION_X | 104 | ABS_MT_POSITION_X |
83 | 105 | ||
@@ -98,8 +120,35 @@ ABS_MT_BLOB_ID | |||
98 | 120 | ||
99 | The BLOB_ID groups several packets together into one arbitrarily shaped | 121 | 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 | 122 | 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 | 123 | with the high-level trackingID [5]. Most kernel drivers will not have blob |
102 | not have this capability, and can safely omit the event. | 124 | capability, and can safely omit the event. |
125 | |||
126 | ABS_MT_TRACKING_ID | ||
127 | |||
128 | The TRACKING_ID identifies an initiated contact throughout its life cycle | ||
129 | [5]. There are currently only a few devices that support it, so this event | ||
130 | should normally be omitted. | ||
131 | |||
132 | |||
133 | Event Computation | ||
134 | ----------------- | ||
135 | |||
136 | The flora of different hardware unavoidably leads to some devices fitting | ||
137 | better to the MT protocol than others. To simplify and unify the mapping, | ||
138 | this section gives recipes for how to compute certain events. | ||
139 | |||
140 | For devices reporting contacts as rectangular shapes, signed orientation | ||
141 | cannot be obtained. Assuming X and Y are the lengths of the sides of the | ||
142 | touching rectangle, here is a simple formula that retains the most | ||
143 | information possible: | ||
144 | |||
145 | ABS_MT_TOUCH_MAJOR := max(X, Y) | ||
146 | ABS_MT_TOUCH_MINOR := min(X, Y) | ||
147 | ABS_MT_ORIENTATION := bool(X > Y) | ||
148 | |||
149 | The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that | ||
150 | the device can distinguish between a finger along the Y axis (0) and a | ||
151 | finger along the X axis (1). | ||
103 | 152 | ||
104 | 153 | ||
105 | Finger Tracking | 154 | Finger Tracking |
@@ -109,14 +158,18 @@ 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 | 158 | anonymous contacts currently on the surface. The order in which the packets |
110 | appear in the event stream is not important. | 159 | appear in the event stream is not important. |
111 | 160 | ||
112 | The process of finger tracking, i.e., to assign a unique contactID to each | 161 | The process of finger tracking, i.e., to assign a unique trackingID to each |
113 | initiated contact on the surface, is left to user space; preferably the | 162 | 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 | 163 | multi-touch X driver [3]. In that driver, the trackingID stays the same and |
115 | unique until the contact vanishes (when the finger leaves the surface). The | 164 | 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 | 165 | 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 | 166 | fingers is a euclidian bipartite matching problem at each event update, and |
118 | relies on a sufficiently rapid update rate. | 167 | relies on a sufficiently rapid update rate. |
119 | 168 | ||
169 | There are a few devices that support trackingID in hardware. User space can | ||
170 | make use of these native identifiers to reduce bandwidth and cpu usage. | ||
171 | |||
172 | |||
120 | Notes | 173 | Notes |
121 | ----- | 174 | ----- |
122 | 175 | ||
@@ -136,5 +189,7 @@ could be used to derive tilt. | |||
136 | time of writing (April 2009), the MT protocol is not yet merged, and the | 189 | 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 | 190 | prototype implements finger matching, basic mouse support and two-finger |
138 | scrolling. The project aims at improving the quality of current multi-touch | 191 | scrolling. The project aims at improving the quality of current multi-touch |
139 | functionality available in the synaptics X driver, and in addition | 192 | functionality available in the Synaptics X driver, and in addition |
140 | implement more advanced gestures. | 193 | implement more advanced gestures. |
194 | [4] See the section on event computation. | ||
195 | [5] See the section on finger tracking. | ||