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