Linux input SUBSYSTEM: Multi-Touch Protocol--multi-touch-protocol.txt768

Transferred from: http://blog.csdn.net/droidphone/article/details/8434768

Multi-Touch (MT) Protocol

-------------------------

Copyright (C) 2009-2010 Henrik rydberg<[email protected]>

Brief introduction

------------

To make the most of the new multi-touch and multi-user devices, it is necessary to define a method for multi-touch reporting of detailed data (such as having multiple objects directly touching the surface of the device). This document describes the multi-Touch Protocol (MULTI-TOUCH,MT), which is a kernel driver that can escalate detailed data information to a number of random touch events.

Hardware-based capabilities, the protocol is divided into two types. For devices that can handle only anonymous contact (type A), the protocol describes how to send all the raw touch data to the recipient. For devices that have the ability to track and identify each touch point (type B), the protocol describes how individual updates for each touch point are sent to the recipient via event slots.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This article is translated by Droidphone: Http://blog.csdn.net/droidphone
Kernel version: V3.7
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use of the Protocol

--------------

Detailed touch information is split sequentially into multiple ABS_MT event packets for sending. Only the ABS_MT event information is recognized as part of the touch packet because these events are ignored in the current single-Touch (SINGLE-TOUCH,ST) application, and we can implement the MT protocol on the existing driver based on the ST protocol.

For the type a device driver, multiple touch packs are split at the end of each packet with Input_mt_sync (), which results in a Syn_mt_report event that notifies the receiver to accept the current touch information and prepares to receive the next message.

For the Type B device driver, at the beginning of each packet, it is split by calling Input_mt_slot () and bringing in a parameter: slot. This produces a Abs_mt_slot event that notifies the recipient to be ready to update the information for a given slot:

Both types of drivers typically mark the end of a multi-touch data transfer by calling the Input_sync () function, which notifies the receiver to respond to all accumulated events since the previous Ev_syn/syn_report and prepares to receive a new set of events/packets.

The main difference between a stateless type a protocol and a stateful type B-slot protocol is to reduce the amount of data sent to the user space by identifying the same contact point. The slot protocol needs to be used to abs_mt_tracking_id, which is either supplied by the hardware or calculated "5" from the original data.

For type a devices, the kernel driver should enumerate and generate events based on all the effective touch on the device surface. The order of each touch point packet in this event stream is not important. The work of event filtering and finger tracking is left to the user space to implement "3".

For type B devices, the kernel driver should correlate each identified touch with a slot and use that slot to propagate changes in the touch state. The creation, substitution, and destruction of touch points is achieved by modifying the abs_mt_tracking_id of the associated slots. A non-negative Tracking ID is interpreted as a valid touch, and 1 represents a slot that is no longer in use. A trace ID that was not previously seen is considered a new touchpoint and is considered to have been removed when a Tracking ID no longer appears. Since only the changed parts are propagated, the state information of each initiated touchpoint must reside on the receiving side. Whenever a MT event is received, simply update the relevant properties of the current slot once.

Some devices can identify and/or track more contact points than it can report to the driver, and the driver for such a device should associate a slot of type B with each contact point that the hardware escalated. Once a contact point that is associated with the slot has been identified, the driver should invalidate the slot by changing his abs_mt_tracking_id. If the hardware notifies it that it tracks more touchpoints than is currently reported, the driver should use the Btn_tool_*tap event to inform the user space that the total number of contact points for hardware tracking at the moment has changed. To complete this work, the driver should explicitly send the Btn_tool_*tap event and set the Use_count parameter to False when calling Input_mt_report_pointer_emulation (). The driver should only advertise the number of slots that the hardware can report. User space can detect whether the driver can report more than slots number of touch points by noting that the maximum supported Btn_tool_*tap event is greater than the total number of slots of type B reported in the absinfo of the abs_mt_slot axis.

Protocol Example A

------------------

For a two-touch touch message, the smallest sequence of events for a device of type a looks like this:

Abs_mt_position_x X[0]

Abs_mt_position_y Y[0]

Syn_mt_report

Abs_mt_position_x X[1]

Abs_mt_position_y Y[1]

Syn_mt_report

Syn_report

In fact, the escalation sequence after moving one of the touch points looks the same, all the original data that has the touch points are sent, and then synchronized with syn_report between them.

When the first point of contact leaves, the sequence of events is as follows:

Abs_mt_position_x X[1]

Abs_mt_position_y Y[1]

Syn_mt_report

Syn_report

When the second point of contact leaves, the sequence of events is as follows:

Syn_mt_report

Syn_report

If the driver reports a Btn_touch or Abs_pressure event outside of the ABS_MT event, the last Syn_mt_report can be omitted, otherwise, the final syn_report will be thrown away by the input core layer, The result is a 0 touch point event being uploaded to the user space.

Protocol Example B

------------------

For a two-touch touch message, the smallest sequence of events for type B devices looks like this:

Abs_mt_slot 0

ABS_MT_TRACKING_ID 45

Abs_mt_position_x X[0]

Abs_mt_position_y Y[0]

Abs_mt_slot 1

ABS_MT_TRACKING_ID 46

Abs_mt_position_x X[1]

Abs_mt_position_y Y[1]

Syn_report

The sequence of events after the touch point of ID 45 moves in the x direction is as follows:

Abs_mt_slot 0

Abs_mt_position_x X[0]

Syn_report

After the contact point for slot 0 is left, the corresponding sequence of events is as follows:

Abs_mt_tracking_id-1

Syn_report

The last modified slot is also 0, so Abs_mt_slot is omitted. This message removes the slot 0 associated with the contact point 45, so the contact point 45 is destroyed and slot 0 is freed to be reused by another point of contact.

Finally, the time sequence after the second contact point leaves is as follows:

Abs_mt_slot 1

Abs_mt_tracking_id-1

Syn_report

Use of events

-----------

A set of ABS_MT event sets is defined as required attributes. These events are divided into groups to allow only a subset of them to be implemented. The smallest set consists of abs_mt_position_x and abs_mt_position_y, which are used to track multi-point contact. If supported by the device, Abs_mt_touch_major and abs_mt_width_major can be used to provide contact area and corresponding contact tool.

The touch and width parameters have a geometric interpretation. Imagine a window observing a person pressing a finger on the opposite glass, and you will see two areas where the inner ring contains the actual part of the contact with the glass, and the outer rim is the contour of the finger. The contact area (a) is abs_mt_position_x/y, and the center of the finger Contour area (b) is abs_mt_tool_x/y. The diameter of the contact area is abs_mt_touch_major, and the diameter of the finger contour is abs_mt_width_major. Now imagine the person pressing the finger closer to the glass, the contact area increases, and usually the abs_mt_touch_major/abs_mt_width_major ratio is always less than 1, which is associated with the pressure of the contact. However, for pressure-based equipment, the abs_mt_pressure should be used instead to provide the pressure value of the contact. Devices that can detect suspension can use Abs_mt_distance to indicate the distance from the surface.

Linux MT Win8

__________                    _______________________

/                         \                   | |

/                           \                  | |

/      ____              \                 | |

/     /           \               \                | |

\ \ a \ \ | A |

\      \____/                \              | |

\                                 \             | |

\ b \ | B |

\                                \           | |

\                                \          | |

\                                \         | |

\                               /         | |

\                            /          | |

\                         /           | |

\__________/            |_______________________|

In addition to the major parameter, the oval shape of the contact and finger areas can also add a minor parameter, with major and minor parameters equivalent to the long and short axes of the ellipse. The direction of the ellipse in the contact area can be described by the orientation parameter, while the elliptical direction of the finger region can be obtained by the vector operation (A-B).

For type a devices, future specifications may be abs_mt_blob_id to describe the shape of the contact.

Abs_mt_tool_type can be used to indicate whether a touch tool is a finger or a pen or other object. Finally, the abs_mt_tracking_id should always be used to track the identified contact point "5".

In the Type B protocol, Abs_mt_tool_type and abs_mt_tracking_id are hidden in the input core layer for processing, and the driver should instead call Input_mt_report_slot_state ().

Semantic description of the event

---------------

Abs_mt_touch_major

Length of the long axis of the contact area. The length should be supplied in units of the contact surface. If the resolution of the surface is X-y, the maximum possible value for Abs_mt_touch_major is sqrt (x^2 + y^2), which is the diagonal "4".

Abs_mt_touch_minor

The surface unit length of the short axis of the contact area. If the area is a circle, the event can ignore "4".

Abs_mt_width_major

The surface unit length of the long axis of the tool outline area. This should be the size of the tool province. The orientation of the contact surface and the contour surface is assumed to be the same as "4".

Abs_mt_width_minor

Tool Contour Area Short axis surface unit length, circular words can be ignored "4".

The above 4 values can be used to derive additional information about the contact surface. Abs_mt_touch_major/abs_mt_width_major can be used as a close pressure. The fingers and palms have no characteristic width.

Abs_mt_pressure

The pressure value of the contact area can be any unit. Pressure-based devices should use this event instead of the touch and width events. Also used for devices that can report the strength of a space signal.

Abs_mt_distance

The unit distance between the contact surface and the surface of the contact. The distance of 0 indicates that the surface has been touched. A positive value indicates that the contact is suspended above the surface.

Abs_mt_orientation

The direction of the contact Ellipse area. This value describes the number of signed 1/4 clockwise rotations around the touch center. The range of the number is not qualified, but should return a value of 0 when the ellipse and the Y-direction of the surface are aligned, the ellipse should return a negative when it turns to the left, and positive values should be returned to the right. When fully aligned with the x-axis, the maximum value should be returned.

The contact ellipse is assumed to be a symmetric point. For devices that can be rotated 360 degrees, it is necessary to report out the maximum range to indicate more than 1/4 turns. For inverted fingers, the maximum range of twice times should be reported.

If the contact surface is a circle, or the orientation information is not available in the kernel driver, the direction parameter can be ignored. If the device can identify two axis orientations, it is possible to support only partially discontinuous orientations, in which case the Abs_mt_orientation range should be [0,1] "4".

Abs_mt_position_x

The x-coordinate of the contact center.

Abs_mt_position_y

Y-coordinate of contact center

Abs_mt_tool_x

The x-coordinate that touches the center of the tool outline. This event can be ignored if the device cannot differentiate between the contact surface and the tool itself.

Abs_mt_tool_y

The y-coordinate of the center of the contact tool outline. This event can be ignored if the device cannot differentiate between the contact surface and the tool itself.

These 4 position values can be used to detach the actual contact position from the touch tool position. If both position information is present, then the long axis of the touch tool points to the contact point, otherwise the tool and the axis of the contact face pair it with each other.

Abs_mt_tool_type

The type of the proximity tool. Many kernel drivers cannot distinguish between different touch tools, such as fingers and pens. In this case, the event can be ignored. The current protocol supports both Mt_tool_finger and Mt_tool_pen "2" types. For type B devices, the event is handled by the input core layer, and the driver should be escalated using input_mt_report_slot_state () instead.

abs_mt_blob_id

The BLOB_ID event combines several packets together to form an arbitrary contact shape. Some points consist of a sequence that defines the shape of a polygon. This is an underlying anonymous data combination of type a devices and should not be confused with the tracking IDs of the upper layers. Most type a devices do not have the ability to blog, so the driver can safely ignore the event.

abs_mt_tracking_id

The tracking_id identifies the entire life cycle "5" of a touch point that is initiated. The scope of the tracking_id should be large enough to ensure that a unique value can be maintained for a long enough period of time. For type B devices, the event is handled by the input core layer, and the driver should instead use Input_mt_report_slot_state () to escalate the event.

Calculation of events

-----------------

A bunch of different hardware inevitably leads to some devices that are better suited to the MT protocol than others. For simple and uniform correspondence, this section gives some methods to determine how certain events are calculated.

For devices that report contact shapes as rectangles, we cannot get the signed directional values, assuming that x and Y are the two sides of the contact rectangle respectively, and the following formulas are the most likely to get the most information:

Abs_mt_touch_major: = Max (X, Y)

Abs_mt_touch_minor: = Min (X, Y)

Abs_mt_orientation: = bool (X > Y)

The range of the abs_mt_orientation should be set to [0,1] so that the device can differentiate whether the finger is along the y axis or along the x axis "1".

For WIN8 devices with T and C coordinates, the correspondence between location information is:

Abs_mt_position_x: = t_x

Abs_mt_position_y: = t_y

Abs_mt_tool_x: = c_x

Abs_mt_tool_x: = c_y

Unfortunately, there is not enough information to determine the touch ellipse and the tool ellipse, so you can only resort to approximate algorithms. A simple solution that is compatible with earlier uses is:

Abs_mt_touch_major: = Min (X, Y)

Abs_mt_touch_minor: = <not used>

Abs_mt_orientation: = <not used>

Abs_mt_width_major: = Min (X, Y) + distance (T, C)

Abs_mt_width_minor: = Min (X, Y)

The rationale is that we do not have information about the touch ellipse, so we use its inscribed circle shape to approximate it. The ellipse of the Touch tool should be aligned with the vector (T-C), so its diameter must be increased (T, C) between the distances. Finally, assuming that the diameter of the touch area equals the thickness of the touch tool, we can get the above formula.

Finger tracking

---------------

Tracking finger processing, for example, assigning a unique trackingid to each touch point initiated on the surface, is a Euclidean parity match problem. In each event synchronization, a set of actual touch points to match a set of touch points in the previous synchronization, the complete implementation please refer to "3".

Gesture

--------

In some special applications that can produce gesture events, you can use the touch and width parameters, such as the pressure on the finger or the index finger and thumb. Using the extra minor parameter, you can tell whether the whole finger is pressed or just a point pressure of the finger. Using the orientation parameter, we can detect the twist of the finger.

Precautions

------------

To be compatible with existing applications, the data reported in a finger packet cannot be identified as a single-touch event.

For type a devices, all finger data is skipped through the input filtering algorithm because the next event of the same type points to a different finger.

For examples of using Type a protocol devices, refer to the bcm5974 driver. For an example of type B protocol, refer to the Hid-egalax driver.

[1] Also, the difference (tool_x-position_x) can be used to model tilt.

[2] The list can of course be extended.

[3] Mtdev project: http://bitmath.org/code/mtdev/.

[4] See the contents of the Event Calculation section.

[5] Refer to the contents of the Finger tracking section.

Linux input SUBSYSTEM: Multi-Touch Protocol--multi-touch-protocol.txt768