Input: convert multi-touch protocol spec into ReST format

+94 -102

1 changed file

expand all

Documentation

input

+94 -102

Documentation/input/multi-touch-protocol.txt

··· 1 + .. include:: <isonum.txt> 2 + 3 + ========================= 1 4 Multi-touch (MT) Protocol 2 - ------------------------- 3 - Copyright (C) 2009-2010 Henrik Rydberg <rydberg@euromail.se> 5 + ========================= 6 + 7 + :Copyright: |copy| 2009-2010 Henrik Rydberg <rydberg@euromail.se> 4 8 5 9 6 10 Introduction ··· 51 47 type B slot protocol lies in the usage of identifiable contacts to reduce 52 48 the amount of data sent to userspace. The slot protocol requires the use of 53 49 the ABS_MT_TRACKING_ID, either provided by the hardware or computed from 54 - the raw data [5]. 50 + the raw data [#f5]_. 55 51 56 52 For type A devices, the kernel driver should generate an arbitrary 57 53 enumeration of the full set of anonymous contacts currently on the 58 54 surface. The order in which the packets appear in the event stream is not 59 - important. Event filtering and finger tracking is left to user space [3]. 55 + important. Event filtering and finger tracking is left to user space [#f3]_. 60 56 61 57 For type B devices, the kernel driver should associate a slot with each 62 58 identified contact, and use that slot to propagate changes for the contact. ··· 90 86 ------------------ 91 87 92 88 Here is what a minimal event sequence for a two-contact touch would look 93 - like for a type A device: 89 + like for a type A device:: 94 90 95 91 ABS_MT_POSITION_X x[0] 96 92 ABS_MT_POSITION_Y y[0] ··· 104 100 raw data for all present contacts are sent between every synchronization 105 101 with SYN_REPORT. 106 102 107 - Here is the sequence after lifting the first contact: 103 + Here is the sequence after lifting the first contact:: 108 104 109 105 ABS_MT_POSITION_X x[1] 110 106 ABS_MT_POSITION_Y y[1] 111 107 SYN_MT_REPORT 112 108 SYN_REPORT 113 109 114 - And here is the sequence after lifting the second contact: 110 + And here is the sequence after lifting the second contact:: 115 111 116 112 SYN_MT_REPORT 117 113 SYN_REPORT ··· 126 122 ------------------ 127 123 128 124 Here is what a minimal event sequence for a two-contact touch would look 129 - like for a type B device: 125 + like for a type B device:: 130 126 131 127 ABS_MT_SLOT 0 132 128 ABS_MT_TRACKING_ID 45 ··· 138 134 ABS_MT_POSITION_Y y[1] 139 135 SYN_REPORT 140 136 141 - Here is the sequence after moving contact 45 in the x direction: 137 + Here is the sequence after moving contact 45 in the x direction:: 142 138 143 139 ABS_MT_SLOT 0 144 140 ABS_MT_POSITION_X x[0] 145 141 SYN_REPORT 146 142 147 - Here is the sequence after lifting the contact in slot 0: 143 + Here is the sequence after lifting the contact in slot 0:: 148 144 149 145 ABS_MT_TRACKING_ID -1 150 146 SYN_REPORT ··· 153 149 message removes the association of slot 0 with contact 45, thereby 154 150 destroying contact 45 and freeing slot 0 to be reused for another contact. 155 151 156 - Finally, here is the sequence after lifting the second contact: 152 + Finally, here is the sequence after lifting the second contact:: 157 153 158 154 ABS_MT_SLOT 1 159 155 ABS_MT_TRACKING_ID -1 ··· 184 180 ABS_MT_PRESSURE may be used to provide the pressure on the contact area 185 181 instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to 186 182 indicate the distance between the contact and the surface. 183 + 184 + :: 187 185 188 186 189 187 Linux MT Win8 ··· 218 212 219 213 The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a 220 214 finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event 221 - may be used to track identified contacts over time [5]. 215 + may be used to track identified contacts over time [#f5]_. 222 216 223 217 In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are 224 218 implicitly handled by input core; drivers should instead call ··· 229 223 --------------- 230 224 231 225 ABS_MT_TOUCH_MAJOR 232 - 233 - The length of the major axis of the contact. The length should be given in 234 - surface units. If the surface has an X times Y resolution, the largest 235 - possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. 226 + The length of the major axis of the contact. The length should be given in 227 + surface units. If the surface has an X times Y resolution, the largest 228 + possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [#f4]_. 236 229 237 230 ABS_MT_TOUCH_MINOR 238 - 239 - The length, in surface units, of the minor axis of the contact. If the 240 - contact is circular, this event can be omitted [4]. 231 + The length, in surface units, of the minor axis of the contact. If the 232 + contact is circular, this event can be omitted [#f4]_. 241 233 242 234 ABS_MT_WIDTH_MAJOR 243 - 244 - The length, in surface units, of the major axis of the approaching 245 - tool. This should be understood as the size of the tool itself. The 246 - orientation of the contact and the approaching tool are assumed to be the 247 - same [4]. 235 + The length, in surface units, of the major axis of the approaching 236 + tool. This should be understood as the size of the tool itself. The 237 + orientation of the contact and the approaching tool are assumed to be the 238 + same [#f4]_. 248 239 249 240 ABS_MT_WIDTH_MINOR 241 + The length, in surface units, of the minor axis of the approaching 242 + tool. Omit if circular [#f4]_. 250 243 251 - The length, in surface units, of the minor axis of the approaching 252 - tool. Omit if circular [4]. 253 - 254 - The above four values can be used to derive additional information about 255 - the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates 256 - the notion of pressure. The fingers of the hand and the palm all have 257 - different characteristic widths. 244 + The above four values can be used to derive additional information about 245 + the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates 246 + the notion of pressure. The fingers of the hand and the palm all have 247 + different characteristic widths. 258 248 259 249 ABS_MT_PRESSURE 260 - 261 - The pressure, in arbitrary units, on the contact area. May be used instead 262 - of TOUCH and WIDTH for pressure-based devices or any device with a spatial 263 - signal intensity distribution. 250 + The pressure, in arbitrary units, on the contact area. May be used instead 251 + of TOUCH and WIDTH for pressure-based devices or any device with a spatial 252 + signal intensity distribution. 264 253 265 254 ABS_MT_DISTANCE 266 - 267 - The distance, in surface units, between the contact and the surface. Zero 268 - distance means the contact is touching the surface. A positive number means 269 - the contact is hovering above the surface. 255 + The distance, in surface units, between the contact and the surface. Zero 256 + distance means the contact is touching the surface. A positive number means 257 + the contact is hovering above the surface. 270 258 271 259 ABS_MT_ORIENTATION 260 + The orientation of the touching ellipse. The value should describe a signed 261 + quarter of a revolution clockwise around the touch center. The signed value 262 + range is arbitrary, but zero should be returned for an ellipse aligned with 263 + the Y axis of the surface, a negative value when the ellipse is turned to 264 + the left, and a positive value when the ellipse is turned to the 265 + right. When completely aligned with the X axis, the range max should be 266 + returned. 272 267 273 - The orientation of the touching ellipse. The value should describe a signed 274 - quarter of a revolution clockwise around the touch center. The signed value 275 - range is arbitrary, but zero should be returned for an ellipse aligned with 276 - the Y axis of the surface, a negative value when the ellipse is turned to 277 - the left, and a positive value when the ellipse is turned to the 278 - right. When completely aligned with the X axis, the range max should be 279 - returned. 268 + Touch ellipsis are symmetrical by default. For devices capable of true 360 269 + degree orientation, the reported orientation must exceed the range max to 270 + indicate more than a quarter of a revolution. For an upside-down finger, 271 + range max * 2 should be returned. 280 272 281 - Touch ellipsis are symmetrical by default. For devices capable of true 360 282 - degree orientation, the reported orientation must exceed the range max to 283 - indicate more than a quarter of a revolution. For an upside-down finger, 284 - range max * 2 should be returned. 285 - 286 - Orientation can be omitted if the touch area is circular, or if the 287 - information is not available in the kernel driver. Partial orientation 288 - support is possible if the device can distinguish between the two axis, but 289 - not (uniquely) any values in between. In such cases, the range of 290 - ABS_MT_ORIENTATION should be [0, 1] [4]. 273 + Orientation can be omitted if the touch area is circular, or if the 274 + information is not available in the kernel driver. Partial orientation 275 + support is possible if the device can distinguish between the two axis, but 276 + not (uniquely) any values in between. In such cases, the range of 277 + ABS_MT_ORIENTATION should be [0, 1] [#f4]_. 291 278 292 279 ABS_MT_POSITION_X 293 - 294 - The surface X coordinate of the center of the touching ellipse. 280 + The surface X coordinate of the center of the touching ellipse. 295 281 296 282 ABS_MT_POSITION_Y 297 - 298 - The surface Y coordinate of the center of the touching ellipse. 283 + The surface Y coordinate of the center of the touching ellipse. 299 284 300 285 ABS_MT_TOOL_X 301 - 302 - The surface X coordinate of the center of the approaching tool. Omit if 303 - the device cannot distinguish between the intended touch point and the 304 - tool itself. 286 + The surface X coordinate of the center of the approaching tool. Omit if 287 + the device cannot distinguish between the intended touch point and the 288 + tool itself. 305 289 306 290 ABS_MT_TOOL_Y 291 + The surface Y coordinate of the center of the approaching tool. Omit if the 292 + device cannot distinguish between the intended touch point and the tool 293 + itself. 307 294 308 - The surface Y coordinate of the center of the approaching tool. Omit if the 309 - device cannot distinguish between the intended touch point and the tool 310 - itself. 311 - 312 - The four position values can be used to separate the position of the touch 313 - from the position of the tool. If both positions are present, the major 314 - tool axis points towards the touch point [1]. Otherwise, the tool axes are 315 - aligned with the touch axes. 295 + The four position values can be used to separate the position of the touch 296 + from the position of the tool. If both positions are present, the major 297 + tool axis points towards the touch point [#f1]_. Otherwise, the tool axes are 298 + aligned with the touch axes. 316 299 317 300 ABS_MT_TOOL_TYPE 318 - 319 - The type of approaching tool. A lot of kernel drivers cannot distinguish 320 - between different tool types, such as a finger or a pen. In such cases, the 321 - event should be omitted. The protocol currently supports MT_TOOL_FINGER, 322 - MT_TOOL_PEN, and MT_TOOL_PALM [2]. For type B devices, this event is handled 323 - by input core; drivers should instead use input_mt_report_slot_state(). 324 - A contact's ABS_MT_TOOL_TYPE may change over time while still touching the 325 - device, because the firmware may not be able to determine which tool is being 326 - used when it first appears. 301 + The type of approaching tool. A lot of kernel drivers cannot distinguish 302 + between different tool types, such as a finger or a pen. In such cases, the 303 + event should be omitted. The protocol currently supports MT_TOOL_FINGER, 304 + MT_TOOL_PEN, and MT_TOOL_PALM [#f2]_. For type B devices, this event is 305 + handled by input core; drivers should instead use 306 + input_mt_report_slot_state(). A contact's ABS_MT_TOOL_TYPE may change over 307 + time while still touching the device, because the firmware may not be able 308 + to determine which tool is being used when it first appears. 327 309 328 310 ABS_MT_BLOB_ID 329 - 330 - The BLOB_ID groups several packets together into one arbitrarily shaped 331 - contact. The sequence of points forms a polygon which defines the shape of 332 - the contact. This is a low-level anonymous grouping for type A devices, and 333 - should not be confused with the high-level trackingID [5]. Most type A 334 - devices do not have blob capability, so drivers can safely omit this event. 311 + The BLOB_ID groups several packets together into one arbitrarily shaped 312 + contact. The sequence of points forms a polygon which defines the shape of 313 + the contact. This is a low-level anonymous grouping for type A devices, and 314 + should not be confused with the high-level trackingID [#f5]_. Most type A 315 + devices do not have blob capability, so drivers can safely omit this event. 335 316 336 317 ABS_MT_TRACKING_ID 337 - 338 - The TRACKING_ID identifies an initiated contact throughout its life cycle 339 - [5]. The value range of the TRACKING_ID should be large enough to ensure 340 - unique identification of a contact maintained over an extended period of 341 - time. For type B devices, this event is handled by input core; drivers 342 - should instead use input_mt_report_slot_state(). 318 + The TRACKING_ID identifies an initiated contact throughout its life cycle 319 + [#f5]_. The value range of the TRACKING_ID should be large enough to ensure 320 + unique identification of a contact maintained over an extended period of 321 + time. For type B devices, this event is handled by input core; drivers 322 + should instead use input_mt_report_slot_state(). 343 323 344 324 345 325 Event Computation ··· 338 346 For devices reporting contacts as rectangular shapes, signed orientation 339 347 cannot be obtained. Assuming X and Y are the lengths of the sides of the 340 348 touching rectangle, here is a simple formula that retains the most 341 - information possible: 349 + information possible:: 342 350 343 351 ABS_MT_TOUCH_MAJOR := max(X, Y) 344 352 ABS_MT_TOUCH_MINOR := min(X, Y) ··· 348 356 the device can distinguish between a finger along the Y axis (0) and a 349 357 finger along the X axis (1). 350 358 351 - For win8 devices with both T and C coordinates, the position mapping is 359 + For win8 devices with both T and C coordinates, the position mapping is:: 352 360 353 361 ABS_MT_POSITION_X := T_X 354 362 ABS_MT_POSITION_Y := T_Y ··· 357 365 358 366 Unfortunately, there is not enough information to specify both the touching 359 367 ellipse and the tool ellipse, so one has to resort to approximations. One 360 - simple scheme, which is compatible with earlier usage, is: 368 + simple scheme, which is compatible with earlier usage, is:: 361 369 362 370 ABS_MT_TOUCH_MAJOR := min(X, Y) 363 371 ABS_MT_TOUCH_MINOR := <not used> ··· 378 386 initiated contact on the surface, is a Euclidian Bipartite Matching 379 387 problem. At each event synchronization, the set of actual contacts is 380 388 matched to the set of contacts from the previous synchronization. A full 381 - implementation can be found in [3]. 389 + implementation can be found in [#f3]_. 382 390 383 391 384 392 Gestures ··· 403 411 For example usage of the type A protocol, see the bcm5974 driver. For 404 412 example usage of the type B protocol, see the hid-egalax driver. 405 413 406 - [1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. 407 - [2] The list can of course be extended. 408 - [3] The mtdev project: http://bitmath.org/code/mtdev/. 409 - [4] See the section on event computation. 410 - [5] See the section on finger tracking. 414 + .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt. 415 + .. [#f2] The list can of course be extended. 416 + .. [#f3] The mtdev project: http://bitmath.org/code/mtdev/. 417 + .. [#f4] See the section on event computation. 418 + .. [#f5] See the section on finger tracking.

Configure Feed

Configure Feed