多點觸控協議(MTP)
作者翻譯水平有限，歡迎指正，感謝好友lapset和leo的幫助！
Multi-touch (MT) Protocol
-------------------------
Copyright (C)2009-2010
Henrik Rydberg<rydberg@euromail.se>
Introduction
------------
In order to utilize the full power of thenew multi-touch and multi-user devices, a way to report detailed data frommultiple contacts, i.e., objects in direct contact with the device surface, isneeded. This document describes themulti-touch (MT) protocol which allows kernel drivers to report details for anarbitrary number of contacts.
為了使用功能強大的多點觸控設備，一種方案是上報多觸點的詳細數據。本文檔所描述的多點觸控協議(MTP)可以讓內核驅動向用戶層上報任意多個觸點的數據信息。
The protocol is divided into two types,depending on the capabilities of the hardware. For devices handling anonymouscontacts (type A), the protocol describes how to send the raw data for allcontacts to the receiver. For devices capable of tracking identifiable contacts(type B), the protocol describes how to send updates for individual contacts viaevent slots.
根據硬件功能，此協議分為兩種類型。A類型：對於處理未標識的觸點的設備，此類協議描述如何將所有觸點的原始數據上報給上層；B類型：對於能跟蹤可標識的觸點的設備，此類協議描述如何將單個觸點的更新信息通過事件槽上報給上層。
Protocol Usage
--------------
Contact details are sent sequentially asseparate packets of ABS_MT events. Only the ABS_MT events are recognized as partof a contact packet. Since these events are ignored by current single-touch(ST) applications, the MT protocol can be implemented on top of the ST protocolin an existing driver.
觸點的詳細數據作為單獨的ABS_MT事件包按順序發送，只有ABS_MT事件作為觸控數據包時才能被識別。由於這些事件會被單觸點應用所忽略，MTP是在STP上實現的。
Drivers for type A devices separate contactpackets by calling input_mt_sync() at the end of each packet. This generates aSYN_MT_REPORT event, which instructs the receiver to accept the data for thecurrent contact and prepare to receive another.
A類設備的驅動：它會在每個包的最后調用一次input_mt_sync()函數分離接收到的觸點數據包，並且會產生一個SYN_MT_REPORT event ，該事件會告訴接收方接收當前觸點數據，並准備接受其他的。
Drivers for type B devices separate contactpackets by calling input_mt_slot(), with a slot as argument, at the beginningof each packet. This generates an ABS_MT_SLOT event, which instructs thereceiver to prepare for updates of the given slot.
B類設備的驅動：在每個包的開頭調用input_mt_slot()函數並攜帶一個槽作為參數，此時會
產生一個ABS_MT_SLOT event，該事件會告訴接收方准備更新給定的槽。
All drivers mark the end of a multi-touchtransfer by calling the usual input_sync() function. This instructs thereceiver to act upon events accumulated since last EV_SYN/SYN_REPORT andprepare to receive a new set of events/packets.
所有類型的驅動都會調用input_sync()函數來標記多點觸摸傳輸的結束，並會告知接收方開始從最后一次EV_SYN/SYN_REPORT起作事件累計。
The main difference between the statelesstype A protocol and the stateful type B slot protocol lies in the usage ofidentifiable contacts to reduce the amount of data sent to userspace. The slotprotocol requires the use of the ABS_MT_TRACKING_ID, either provided by thehardware or computed from the raw data [5].
A類協議和B類協議的主要區別是B類協議使用ID來標識觸點，減少了上報到用戶空間的數據量。B類協議需要使用ABS_MT_TRACKING_ID，由硬件提供或者通過原始數據計算得來。
For type A devices, the kernel drivershould generate an arbitrary enumeration of the full set of anonymous contactscurrently on the surface. The order in which the packets appear in the eventstream is not important. Event filteringand finger tracking is left to user space [3].
對於A類設備，內核驅動需要對當前的所有觸點進行任意枚舉。數據包在事件流里出現的順序並不是很重要。事件過濾和觸點跟蹤都由用戶空間來處理。
For type B devices, the kernel drivershould associate a slot with each identified contact, and use that slot topropagate changes for the contact. Creation, replacement and destruction ofcontacts is achieved by modifying the ABS_MT_TRACKING_ID of the associatedslot. A non-negative tracking id isinterpreted as a contact, and the value -1 denotes an unused slot. A tracking id not previously present isconsidered new, and a tracking id no longer present is considered removed. Since only changes are propagated, the fullstate of each initiated contact has to reside in the receiving end. Upon receiving an MT event, one simplyupdates the appropriate attribute of the current slot.
對於B類設備，內核驅動需要將slot和每個已標識的觸點關聯，使用slot來傳遞觸點的變化。觸點的創建，替換和銷毀都是通過修改相應slot的ABS_MT_TRACKING_ID來實現。非零的跟蹤ID表示已使用觸點，而-1表示未使用的slot。之前不存在的跟蹤ID被認為是新的，再存在的跟蹤ID被認為是已移除的。由於只有觸點變化才會被傳遞，每個被標識的觸點會駐留接收端，一旦接收到MT事件，就會更新當前slot的相應屬性。
Some devices identify and/or track morecontacts than they can report to the driver. A driver for such a device should associate one type B slot with eachcontact that is reported by the hardware. Whenever the identity of the contact associated with a slot changes, thedriver should invalidate that slot by changing its ABS_MT_TRACKING_ID. If the hardware signals that it is trackingmore contacts than it is currently reporting, the driver should use aBTN_TOOL_*TAP event to inform userspace of the total number of contacts beingtracked by the hardware at that moment. The driver should do this by explicitly sending the correspondingBTN_TOOL_*TAP event and setting use_count to false when callinginput_mt_report_pointer_emulation(). The driver should only advertise as manyslots as the hardware can report. Userspace can detect that a driver can reportmore total contacts than slots by noting that the largest supportedBTN_TOOL_*TAP event is larger than the total number of type B slots reported inthe absinfo for the ABS_MT_SLOT axis.
一些設備標識和跟蹤的觸點比上報給驅動的觸點要多。這種設備的驅動程序需要將一個B類型slot和每個由硬件上報的觸點關聯。只要觸點的標號更改，驅動應該通過改變ABS_MT_TRACKING_ID來使此觸點關聯的slot無效。如果硬件信號跟蹤的觸點要比當前上報的多，此時，驅動應該使用一個BTN_TOOL_*TAP事件來通知用戶空間實際上硬件跟蹤觸點的總數。驅動需要顯示的發送BTN_TOOL_*TAP事件和調用input_mt_report_pointer_emulation()函數設置use_count為false。驅動最多只能上報硬件實現的slot總個數。通過檢查驅動支持的最大BTN_TOOL_* TAP事件大於ABS_MT_SLOT軸absinfo上報的B類slot總數，用戶空間能檢測出驅動程序可以報告比插槽更多的觸點總數。
Protocol Example A
------------------
Here is what a minimal event sequence for atwo-contact touch would look like for a type A device:
對於A類型驅動，下面是報告兩個觸點的最小事件序列：
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
The sequence after moving one of the contactslooks exactly the same; the raw data for all present contacts are sent betweenevery synchronization with SYN_REPORT.
移動其中的一個觸點后的序列也是一樣的，所有的觸點數據包發送完后，會用SYN_REPORT用來同步處理。
Here is the sequence after lifting thefirst contact:
當第一個觸點彈起后的序列：
ABS_MT_POSITION_X x[1]
ABS_MT_POSITION_Y y[1]
SYN_MT_REPORT
SYN_REPORT
And here is the sequence after lifting thesecond contact:
當第二個觸點也彈起后的序列：
SYN_MT_REPORT
SYN_REPORT
If the driver reports one of BTN_TOUCH orABS_PRESSURE in addition to the ABS_MT events, the last SYN_MT_REPORT event maybe omitted. Otherwise, the last SYN_REPORT will be dropped by the input core,resulting in no zero-contact event reaching userland.
如果驅動上報BTN_TOUCH或ABS_PRESSURE事件，SYN_MT_REPORT事件可能會被忽略。否則最后的SYN_REPORT事件會被輸入核心層丟棄，導致沒有產生同步事件。
Protocol Example B
------------------
Here is what a minimal event sequence for atwo-contact touch would look like for a type B device:
下面是報告兩個觸點的最小事件序列：
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
Here is the sequence after moving contact45 in the x direction:
在X方向上移動觸點45后的序列：
ABS_MT_SLOT 0
ABS_MT_POSITION_X x[0]
SYN_REPORT
Here is the sequence after lifting thecontact in slot 0:
與slot 0關聯的觸點彈起后的序列：
ABS_MT_TRACKING_ID -1
SYN_REPORT
The slot being modified is already 0, sothe ABS_MT_SLOT is omitted. The messageremoves the association of slot 0 with contact 45, thereby destroying contact45 and freeing slot 0 to be reused for another contact.
被修改過的slot已經為0了，所以ABS_MT_SLOT會被忽略。把觸點45從slot 0上移除，因此銷毀觸點45和釋放slot 0后，其他觸點又可以重新使用。
Finally, here is the sequence after liftingthe second contact:
最后，第二個觸點也彈起后的序列如下：
ABS_MT_SLOT 1
ABS_MT_TRACKING_ID-1
SYN_REPORT
Event Usage
-----------
A set of ABS_MT events with the desiredproperties is defined. The events are divided into categories, to allow forpartial implementation. The minimum setconsists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which allows for multiplecontacts to be tracked. If the devicesupports it, the ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used toprovide the size of the contact area and approaching contact, respectively.
協議定義了一系列的ABS_MT事件，這些事件被分為幾大類，允許只應用其中的一部分。最小的事件集由ABS_MT_POSITION_X 和ABS_MT_POSITION_Y組成，以此來實現多點觸摸。如果設備支持ABS_MT_TOUCH_MAJOR和 ABS_MT_WIDTH_MAJOR可以分別提供觸點大小和接觸工具的大小。
The TOUCH and WIDTH parameters have ageometrical interpretation; imagine looking through a window at someone gentlyholding a finger against the glass. Youwill see two regions, one inner region consisting of the part of the fingeractually touching the glass, and one outer region formed by the perimeter ofthe finger. The diameter of the inner region is the ABS_MT_TOUCH_MAJOR, thediameter of the outer region is ABS_MT_WIDTH_MAJOR. Now imagine the personpressing the finger harder against the glass. The inner region will increase,and in general, the ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which isalways smaller than unity, is related to the contact pressure. Forpressure-based devices, ABS_MT_PRESSURE may be used to provide the pressure onthe contact area instead. Devices capable of contact hovering can useABS_MT_DISTANCE to indicate the distance between the contact and the surface.
TOUCH和WIDTH參數。想象一下，一個人用手指按在玻璃上，通過玻璃你將看到兩個區域，里面是手指與玻璃實際接觸的區域，區域的直徑用ABS_MT_TOUCH_MAJOR參數來描述；外面是手指本身大小的區域，區域的直徑用ABS_MT_WIDTH_MAJOR參數來描述。手指與玻璃接觸的面積要小於手指本身的大小，通過ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR的比值可以用來反映接觸時的壓力值。對於支持壓力的設備，也可通過 ABS_MT_PRESSURE參數直接提供手指的壓力。同樣可以使用ABS_MT_DISTANCE參數提供接觸點和表面的距離。
In addition to the MAJOR parameters, theoval shape of the contact can be described by adding the MINOR parameters, suchthat MAJOR and MINOR are the major and minor axis of an ellipse. Finally, theorientation of the oval shape can be describe with the ORIENTATION parameter.
另外MAJOR和MINOR參數用來描述橢圓的形狀，觸點的形狀通常被認為是橢圓形。MAJOR和MINOR參數分別是這個橢圓的長軸和短軸，橢圓的方向可以被 ORIENTATION這個參數描述。
For type A devices, further specificationof the touch shape is possible via ABS_MT_BLOB_ID.
The ABS_MT_TOOL_TYPE may be used to specifywhether the touching tool is a finger or a pen or something else. Finally, theABS_MT_TRACKING_ID event may be used to track identified contacts over time[5].
對於A類設備，通過ABS_MT_BLOB_ID來進一步規范觸點的形狀，ABS_MT_TOOL_TYPE參數用來描述觸摸工具的類型(手指，觸控筆等)。ABS_MT_TRACKING_ID參數用來跟蹤標識的觸點。
In the type B protocol, ABS_MT_TOOL_TYPEand ABS_MT_TRACKING_ID are implicitly handled by input core; drivers shouldinstead call input_mt_report_slot_state().
對於B類型協議，ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID都已被輸入核心層隱式處理，驅動程序只需要調用input_mt_report_slot_state()。
Event Semantics
---------------
ABS_MT_TOUCH_MAJOR
The length of the major axis of thecontact. The length should be given in surface units. If the surface has an Xtimes Y resolution, the largest possible value of ABS_MT_TOUCH_MAJOR issqrt(X^2 + Y^2), the diagonal [4].
觸點長軸長度
ABS_MT_TOUCH_MINOR
The length, in surface units, of the minoraxis of the contact. If the contact is circular, this event can be omitted [4].
觸點短軸長度，如果觸點是圓形，則忽略
ABS_MT_WIDTH_MAJOR
The length, in surface units, of the majoraxis of the approaching tool. This should be understood as the size of the toolitself. The orientation of the contact and the approaching tool are assumed tobe the same [4].
接觸工具長軸長度
ABS_MT_WIDTH_MINOR
The length, in surface units, of the minoraxis of the approaching tool. Omit if circular [4].
接觸工具短軸長度，接觸工具切面是圓形，則忽略
The above four values can be used to deriveadditional information about the contact. The ratio ABS_MT_TOUCH_MAJOR /ABS_MT_WIDTH_MAJOR approximates the notion of pressure. The fingers of the handand the palm all have different characteristic widths [1].
可以利用上面的四個值去獲取觸點其它的信息，ABS_MT_TOUCH_MAJOR/ ABS_MT_WIDTH_MAJOR的比值可以用來反應接觸時的壓力值
ABS_MT_PRESSURE
The pressure, in arbitrary units, on thecontact area. May be used instead of TOUCH and WIDTH for pressure-based devicesor any device with a spatial signal intensity distribution.
壓力，如果設備支持壓力功能或者空間信號分布強度功能，可用此參數來替代上面四個參數
ABS_MT_DISTANCE
The distance, in surface units, between thecontact and the surface. Zero distance means the contact is touching thesurface. A positive number means the contact is hovering above the surface.
觸點和表面的距離，0表示觸點接觸到觸摸屏表面，正數意味着觸點在表面上方
ABS_MT_ORIENTATION
The orientation of the ellipse. The valueshould describe a signed quarter of a revolution clockwise around the touchcenter. The signed value range is arbitrary, but zero should be returned for afinger aligned along the Y axis of the surface, a negative value when finger isturned to the left, and a positive value when finger turned to the right. Whencompletely aligned with the X axis, the range max should be returned. Orientation can be omitted if the touchingobject is circular, or if the information is not available in the kerneldriver. Partial orientation support is possible if the device can distinguishbetween the two axis, but not (uniquely) any values in between. In such cases,the range of ABS_MT_ORIENTATION should be [0, 1] [4].
觸點的方向。此值的范圍是任意的，0表示手指和Y軸對齊，負值表示手指向左移，正值表示手指向右移。當和X軸完全對齊時，返回最大值。如果接觸面是圓形或在驅動中此值不可用，會被忽略。如果設備能區分XY軸，部分的方向是有可能支持的。在這種情況下，ABS_MT_ORIENTATION的范圍應該是[0,1]。
ABS_MT_POSITION_X
The surface X coordinate of the center ofthe touching ellipse.
接觸面中心的X坐標值
ABS_MT_POSITION_Y
The surface Y coordinate of the center ofthe touching ellipse.
接觸面中心的Y坐標值
ABS_MT_TOOL_TYPE
The type of approaching tool. A lot ofkernel drivers cannot distinguish between different tool types, such as afinger or a pen. In such cases, the event should be omitted. The protocolcurrently supports MT_TOOL_FINGER and MT_TOOL_PEN [2]. For type B devices, thisevent is handled by input core; drivers should instead useinput_mt_report_slot_state().
觸摸工具的類型，大多數的內核驅動都不能區分工具的類型，所以在這種情況下，應該被忽略。MTP當前只支持MT_TOOL_FINGER(手指) 和MT_TOOL_PEN(筆)。對於B類設備，驅動調用input_mt_report_slot_state()函數將這些事件都交由輸入核心層來處理。
ABS_MT_BLOB_ID
The BLOB_ID groups several packets togetherinto one arbitrarily shaped contact. The sequence of points forms a polygonwhich defines the shape of the contact. This is a low-level anonymous groupingfor type A devices, and should not be confused with the high-level trackingID[5]. Most type A devices do not have blob capability, so drivers can safelyomit this event.
BLOB_ID是形狀集ID，可以用來組合任意的觸點形狀，大多數的A類設備沒有形狀屬性，所以驅動應該將此事件忽略。
ABS_MT_TRACKING_ID
The TRACKING_ID identifies an initiatedcontact throughout its life cycle [5]. The value range of the TRACKING_IDshould be large enough to ensure unique identification of a contact maintainedover an extended period of time. For type B devices, this event is handled byinput core; drivers should instead use input_mt_report_slot_state().
TRACKING_ID用來標識觸點的整個生命周期。TRACKING_ID的范圍必須足夠大，以確保每個觸點都有一個獨一的標號。對於B類設備，驅動調用input_mt_report_slot_state()函數將這些事件都交由輸入核心層來處理。
Event Computation
-----------------
The flora of different hardware unavoidablyleads to some devices fitting better to the MT protocol than others. Tosimplify and unify the mapping, this section gives recipes for how to computecertain events.
由於硬件上的差異，導致一些設備不能更好的使用MTP。為了簡化和統一，本節給出來某些事件的計算方法。
For devices reporting contacts asrectangular shapes, signed orientation cannot be obtained. Assuming X and Y arethe lengths of the sides of the touching rectangle, here is a simple formulathat retains the most information possible:
一些設備將接觸面作為一個矩形上報，假設X和Y是矩形接觸面的邊，可以通過下面一些公式獲取一些信息：
ABS_MT_TOUCH_MAJOR := max(X, Y)
ABS_MT_TOUCH_MINOR := min(X, Y)
ABS_MT_ORIENTATION := bool(X > Y)
The range of ABS_MT_ORIENTATION should beset to [0, 1], to indicate that the device can distinguish between a fingeralong the Y axis (0) and a finger along the X axis (1).
ABS_MT_ORIENTATION的取值范圍為０至１，用來標識矩形接觸面偏向Ｙ軸(0)或Ｘ軸(1)的程度。
Finger Tracking
---------------
The process of finger tracking, i.e., toassign a unique trackingID to each initiated contact on the surface, is aEuclidian Bipartite Matching problem. Ateach event synchronization, the set of actual contacts is matched to the set ofcontacts from the previous synchronization. A full implementation can be foundin [3].
觸點跟蹤過程，比如為每個觸點分配一個獨一的跟蹤ID號。每一個事件同步時，實際的觸點集是和之前同步的觸點集匹配的。
Gestures
--------
In the specific application of creating gestureevents, the TOUCH and WIDTH parameters can be used to, e.g., approximate fingerpressure or distinguish between index finger and thumb. With the addition ofthe MINOR parameters, one can also distinguish between a sweeping finger and apointing finger, and with ORIENTATION, one can detect twisting of fingers.
對於創建手勢事件這類特殊的應用中，TOUCH和 WIDTH參數經常用來，例如區分拇指和食指或者手指大約的壓力，另外 MINOR參數可以用來區別設備的接觸面的大小(點接觸還是面接觸),ORIENTATION可以檢測旋轉方向。
Notes
-----
In order to staycompatible with existing applications, the data reported
in a finger packet mustnot be recognized as single-touch events.
為了和現有的應用兼容，在上報的觸點數據包中的數據不能識別為單點觸控事件。
For type A devices, allfinger data bypasses input filtering, since
subsequent events of thesame type refer to different fingers.
對於A類型的設備，由於隨后相同類型的事件關聯不同的觸控，所有的數據會繞過輸入過濾.
For example usage of thetype A protocol, see the bcm5974 driver. For
example usage of thetype B protocol, see the hid-egalax driver.
比如A類型協議的使用，可以參考內核中實現的bcm5974驅動。再如B類型協議的使用，可以參考hid-egalax驅動。
[1] With the extensionABS_MT_APPROACH_X and ABS_MT_APPROACH_Y, the
difference between thecontact position and the approaching tool position
could be used to derivetilt.
有了ABS_MT_APPROACH_X 和 ABS_MT_APPROACH_Y 的擴展，在觸控位置和觸控工具的位置的差異可以推導出傾斜度。
[2] The list can ofcourse be extended.
[3] The mtdev project:http://bitmath.org/code/mtdev/.
[4] See the section onevent computation.
[5] See the section onfinger tracking.