diff options
author | Henrik Rydberg <rydberg@euromail.se> | 2012-06-27 03:53:47 -0400 |
---|---|---|
committer | Henrik Rydberg <rydberg@euromail.se> | 2012-07-05 01:13:51 -0400 |
commit | cab7faca5e446b84e829d57d2095035d72edba09 (patch) | |
tree | 2dd72400210b44cdc0d85edb4d3f46de21138b04 /Documentation/input | |
parent | fdf804210f297b7a114fa7a216c2ab65b0f693da (diff) |
Input: MT - Include win8 support
The newly released HID protocol for win8 multitouch devices is capable
of transmitting more information about each touch. In particular, it
includes details useful for touch alignment. This patch completes the
MT protocol with the ABS_MT_TOOL_X/Y events, and documents how to map
win8 devices.
Cc: Stephane Chatty <chatty@enac.fr>
Cc: Benjamin Tissoires <benjamin.tissoires@enac.fr>
Cc: Peter Hutterer <peter.hutterer@who-t.net>
Acked-by: Chase Douglas <chase.douglas@canonical.com>
Signed-off-by: Henrik Rydberg <rydberg@euromail.se>
Diffstat (limited to 'Documentation/input')
-rw-r--r-- | Documentation/input/multi-touch-protocol.txt | 118 |
1 files changed, 92 insertions, 26 deletions
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index 543101c5bf26..2c179613f81b 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt | |||
@@ -162,26 +162,48 @@ are divided into categories, to allow for partial implementation. The | |||
162 | minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which | 162 | minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which |
163 | allows for multiple contacts to be tracked. If the device supports it, the | 163 | allows for multiple contacts to be tracked. If the device supports it, the |
164 | ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size | 164 | ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size |
165 | of the contact area and approaching contact, respectively. | 165 | of the contact area and approaching tool, respectively. |
166 | 166 | ||
167 | The TOUCH and WIDTH parameters have a geometrical interpretation; imagine | 167 | The TOUCH and WIDTH parameters have a geometrical interpretation; imagine |
168 | looking through a window at someone gently holding a finger against the | 168 | looking through a window at someone gently holding a finger against the |
169 | glass. You will see two regions, one inner region consisting of the part | 169 | glass. You will see two regions, one inner region consisting of the part |
170 | of the finger actually touching the glass, and one outer region formed by | 170 | of the finger actually touching the glass, and one outer region formed by |
171 | the perimeter of the finger. The diameter of the inner region is the | 171 | the perimeter of the finger. The center of the touching region (a) is |
172 | ABS_MT_TOUCH_MAJOR, the diameter of the outer region is | 172 | ABS_MT_POSITION_X/Y and the center of the approaching finger (b) is |
173 | ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder | 173 | ABS_MT_TOOL_X/Y. The touch diameter is ABS_MT_TOUCH_MAJOR and the finger |
174 | against the glass. The inner region will increase, and in general, the | 174 | diameter is ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger |
175 | ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than | 175 | harder against the glass. The touch region will increase, and in general, |
176 | unity, is related to the contact pressure. For pressure-based devices, | 176 | the ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller |
177 | than unity, is related to the contact pressure. For pressure-based devices, | ||
177 | ABS_MT_PRESSURE may be used to provide the pressure on the contact area | 178 | ABS_MT_PRESSURE may be used to provide the pressure on the contact area |
178 | instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to | 179 | instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to |
179 | indicate the distance between the contact and the surface. | 180 | indicate the distance between the contact and the surface. |
180 | 181 | ||
181 | In addition to the MAJOR parameters, the oval shape of the contact can be | 182 | |
182 | described by adding the MINOR parameters, such that MAJOR and MINOR are the | 183 | Linux MT Win8 |
183 | major and minor axis of an ellipse. Finally, the orientation of the oval | 184 | __________ _______________________ |
184 | shape can be describe with the ORIENTATION parameter. | 185 | / \ | | |
186 | / \ | | | ||
187 | / ____ \ | | | ||
188 | / / \ \ | | | ||
189 | \ \ a \ \ | a | | ||
190 | \ \____/ \ | | | ||
191 | \ \ | | | ||
192 | \ b \ | b | | ||
193 | \ \ | | | ||
194 | \ \ | | | ||
195 | \ \ | | | ||
196 | \ / | | | ||
197 | \ / | | | ||
198 | \ / | | | ||
199 | \__________/ |_______________________| | ||
200 | |||
201 | |||
202 | In addition to the MAJOR parameters, the oval shape of the touch and finger | ||
203 | regions can be described by adding the MINOR parameters, such that MAJOR | ||
204 | and MINOR are the major and minor axis of an ellipse. The orientation of | ||
205 | the touch ellipse can be described with the ORIENTATION parameter, and the | ||
206 | direction of the finger ellipse is given by the vector (a - b). | ||
185 | 207 | ||
186 | For type A devices, further specification of the touch shape is possible | 208 | For type A devices, further specification of the touch shape is possible |
187 | via ABS_MT_BLOB_ID. | 209 | via ABS_MT_BLOB_ID. |
@@ -224,7 +246,7 @@ tool. Omit if circular [4]. | |||
224 | The above four values can be used to derive additional information about | 246 | The above four values can be used to derive additional information about |
225 | the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates | 247 | the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates |
226 | the notion of pressure. The fingers of the hand and the palm all have | 248 | the notion of pressure. The fingers of the hand and the palm all have |
227 | different characteristic widths [1]. | 249 | different characteristic widths. |
228 | 250 | ||
229 | ABS_MT_PRESSURE | 251 | ABS_MT_PRESSURE |
230 | 252 | ||
@@ -240,17 +262,24 @@ the contact is hovering above the surface. | |||
240 | 262 | ||
241 | ABS_MT_ORIENTATION | 263 | ABS_MT_ORIENTATION |
242 | 264 | ||
243 | The orientation of the ellipse. The value should describe a signed quarter | 265 | The orientation of the touching ellipse. The value should describe a signed |
244 | of a revolution clockwise around the touch center. The signed value range | 266 | quarter of a revolution clockwise around the touch center. The signed value |
245 | is arbitrary, but zero should be returned for a finger aligned along the Y | 267 | range is arbitrary, but zero should be returned for an ellipse aligned with |
246 | axis of the surface, a negative value when finger is turned to the left, and | 268 | the Y axis of the surface, a negative value when the ellipse is turned to |
247 | a positive value when finger turned to the right. When completely aligned with | 269 | the left, and a positive value when the ellipse is turned to the |
248 | the X axis, the range max should be returned. Orientation can be omitted | 270 | right. When completely aligned with the X axis, the range max should be |
249 | if the touching object is circular, or if the information is not available | 271 | returned. |
250 | in the kernel driver. Partial orientation support is possible if the device | 272 | |
251 | can distinguish between the two axis, but not (uniquely) any values in | 273 | Touch ellipsis are symmetrical by default. For devices capable of true 360 |
252 | between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1] | 274 | degree orientation, the reported orientation must exceed the range max to |
253 | [4]. | 275 | indicate more than a quarter of a revolution. For an upside-down finger, |
276 | range max * 2 should be returned. | ||
277 | |||
278 | Orientation can be omitted if the touch area is circular, or if the | ||
279 | information is not available in the kernel driver. Partial orientation | ||
280 | support is possible if the device can distinguish between the two axis, but | ||
281 | not (uniquely) any values in between. In such cases, the range of | ||
282 | ABS_MT_ORIENTATION should be [0, 1] [4]. | ||
254 | 283 | ||
255 | ABS_MT_POSITION_X | 284 | ABS_MT_POSITION_X |
256 | 285 | ||
@@ -260,6 +289,23 @@ ABS_MT_POSITION_Y | |||
260 | 289 | ||
261 | The surface Y coordinate of the center of the touching ellipse. | 290 | The surface Y coordinate of the center of the touching ellipse. |
262 | 291 | ||
292 | ABS_MT_TOOL_X | ||
293 | |||
294 | The surface X coordinate of the center of the approaching tool. Omit if | ||
295 | the device cannot distinguish between the intended touch point and the | ||
296 | tool itself. | ||
297 | |||
298 | ABS_MT_TOOL_Y | ||
299 | |||
300 | The surface Y coordinate of the center of the approaching tool. Omit if the | ||
301 | device cannot distinguish between the intended touch point and the tool | ||
302 | itself. | ||
303 | |||
304 | The four position values can be used to separate the position of the touch | ||
305 | from the position of the tool. If both positions are present, the major | ||
306 | tool axis points towards the touch point [1]. Otherwise, the tool axes are | ||
307 | aligned with the touch axes. | ||
308 | |||
263 | ABS_MT_TOOL_TYPE | 309 | ABS_MT_TOOL_TYPE |
264 | 310 | ||
265 | The type of approaching tool. A lot of kernel drivers cannot distinguish | 311 | The type of approaching tool. A lot of kernel drivers cannot distinguish |
@@ -305,6 +351,28 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that | |||
305 | the device can distinguish between a finger along the Y axis (0) and a | 351 | the device can distinguish between a finger along the Y axis (0) and a |
306 | finger along the X axis (1). | 352 | finger along the X axis (1). |
307 | 353 | ||
354 | For win8 devices with both T and C coordinates, the position mapping is | ||
355 | |||
356 | ABS_MT_POSITION_X := T_X | ||
357 | ABS_MT_POSITION_Y := T_Y | ||
358 | ABS_MT_TOOL_X := C_X | ||
359 | ABS_MT_TOOL_X := C_Y | ||
360 | |||
361 | Unfortunately, there is not enough information to specify both the touching | ||
362 | ellipse and the tool ellipse, so one has to resort to approximations. One | ||
363 | simple scheme, which is compatible with earlier usage, is: | ||
364 | |||
365 | ABS_MT_TOUCH_MAJOR := min(X, Y) | ||
366 | ABS_MT_TOUCH_MINOR := <not used> | ||
367 | ABS_MT_ORIENTATION := <not used> | ||
368 | ABS_MT_WIDTH_MAJOR := min(X, Y) + distance(T, C) | ||
369 | ABS_MT_WIDTH_MINOR := min(X, Y) | ||
370 | |||
371 | Rationale: We have no information about the orientation of the touching | ||
372 | ellipse, so approximate it with an inscribed circle instead. The tool | ||
373 | ellipse should align with the the vector (T - C), so the diameter must | ||
374 | increase with distance(T, C). Finally, assume that the touch diameter is | ||
375 | equal to the tool thickness, and we arrive at the formulas above. | ||
308 | 376 | ||
309 | Finger Tracking | 377 | Finger Tracking |
310 | --------------- | 378 | --------------- |
@@ -338,9 +406,7 @@ subsequent events of the same type refer to different fingers. | |||
338 | For example usage of the type A protocol, see the bcm5974 driver. For | 406 | For example usage of the type A protocol, see the bcm5974 driver. For |
339 | example usage of the type B protocol, see the hid-egalax driver. | 407 | example usage of the type B protocol, see the hid-egalax driver. |
340 | 408 | ||
341 | [1] With the extension ABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the | 409 | [1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. |
342 | difference between the contact position and the approaching tool position | ||
343 | could be used to derive tilt. | ||
344 | [2] The list can of course be extended. | 410 | [2] The list can of course be extended. |
345 | [3] The mtdev project: http://bitmath.org/code/mtdev/. | 411 | [3] The mtdev project: http://bitmath.org/code/mtdev/. |
346 | [4] See the section on event computation. | 412 | [4] See the section on event computation. |