Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   1) .. include:: <isonum.txt>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   3) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   4) Multi-touch (MT) Protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   5) =========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   7) :Copyright: |copy| 2009-2010	Henrik Rydberg <rydberg@euromail.se>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   8) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300   9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  10) Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  11) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  13) In order to utilize the full power of the new multi-touch and multi-user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  14) devices, a way to report detailed data from multiple contacts, i.e.,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  15) objects in direct contact with the device surface, is needed.  This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  16) document describes the multi-touch (MT) protocol which allows kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  17) drivers to report details for an arbitrary number of contacts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  18) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  19) The protocol is divided into two types, depending on the capabilities of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  20) hardware. For devices handling anonymous contacts (type A), the protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  21) describes how to send the raw data for all contacts to the receiver. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  22) devices capable of tracking identifiable contacts (type B), the protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  23) describes how to send updates for individual contacts via event slots.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  24) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  25) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  26)    MT protocol type A is obsolete, all kernel drivers have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  27)    converted to use type B.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  28) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  29) Protocol Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  30) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  31) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  32) Contact details are sent sequentially as separate packets of ABS_MT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  33) events. Only the ABS_MT events are recognized as part of a contact
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  34) packet. Since these events are ignored by current single-touch (ST)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  35) applications, the MT protocol can be implemented on top of the ST protocol
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  36) in an existing driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  38) Drivers for type A devices separate contact packets by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  39) input_mt_sync() at the end of each packet. This generates a SYN_MT_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  40) event, which instructs the receiver to accept the data for the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  41) contact and prepare to receive another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  42) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  43) Drivers for type B devices separate contact packets by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  44) input_mt_slot(), with a slot as argument, at the beginning of each packet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  45) This generates an ABS_MT_SLOT event, which instructs the receiver to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  46) prepare for updates of the given slot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  47) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  48) All drivers mark the end of a multi-touch transfer by calling the usual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  49) input_sync() function. This instructs the receiver to act upon events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  50) accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  51) of events/packets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  53) The main difference between the stateless type A protocol and the stateful
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  54) type B slot protocol lies in the usage of identifiable contacts to reduce
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  55) the amount of data sent to userspace. The slot protocol requires the use of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  56) the ABS_MT_TRACKING_ID, either provided by the hardware or computed from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  57) the raw data [#f5]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  58) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  59) For type A devices, the kernel driver should generate an arbitrary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  60) enumeration of the full set of anonymous contacts currently on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  61) surface. The order in which the packets appear in the event stream is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  62) important.  Event filtering and finger tracking is left to user space [#f3]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  64) For type B devices, the kernel driver should associate a slot with each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  65) identified contact, and use that slot to propagate changes for the contact.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  66) Creation, replacement and destruction of contacts is achieved by modifying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  67) the ABS_MT_TRACKING_ID of the associated slot.  A non-negative tracking id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  68) is interpreted as a contact, and the value -1 denotes an unused slot.  A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  69) tracking id not previously present is considered new, and a tracking id no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  70) longer present is considered removed.  Since only changes are propagated,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  71) the full state of each initiated contact has to reside in the receiving
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  72) end.  Upon receiving an MT event, one simply updates the appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  73) attribute of the current slot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  75) Some devices identify and/or track more contacts than they can report to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  76) driver.  A driver for such a device should associate one type B slot with each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  77) contact that is reported by the hardware.  Whenever the identity of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  78) contact associated with a slot changes, the driver should invalidate that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  79) slot by changing its ABS_MT_TRACKING_ID.  If the hardware signals that it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  80) tracking more contacts than it is currently reporting, the driver should use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  81) a BTN_TOOL_*TAP event to inform userspace of the total number of contacts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  82) being tracked by the hardware at that moment.  The driver should do this by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  83) explicitly sending the corresponding BTN_TOOL_*TAP event and setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  84) use_count to false when calling input_mt_report_pointer_emulation().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  85) The driver should only advertise as many slots as the hardware can report.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  86) Userspace can detect that a driver can report more total contacts than slots
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  87) by noting that the largest supported BTN_TOOL_*TAP event is larger than the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  88) total number of type B slots reported in the absinfo for the ABS_MT_SLOT axis.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  89) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  90) The minimum value of the ABS_MT_SLOT axis must be 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  91) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  92) Protocol Example A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  93) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  94) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  95) Here is what a minimal event sequence for a two-contact touch would look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  96) like for a type A device::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  97) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  98)    ABS_MT_POSITION_X x[0]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  99)    ABS_MT_POSITION_Y y[0]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)    SYN_MT_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)    ABS_MT_POSITION_X x[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)    ABS_MT_POSITION_Y y[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)    SYN_MT_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) The sequence after moving one of the contacts looks exactly the same; the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) raw data for all present contacts are sent between every synchronization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) with SYN_REPORT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Here is the sequence after lifting the first contact::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)    ABS_MT_POSITION_X x[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)    ABS_MT_POSITION_Y y[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)    SYN_MT_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) And here is the sequence after lifting the second contact::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)    SYN_MT_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) If the driver reports one of BTN_TOUCH or ABS_PRESSURE in addition to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) ABS_MT events, the last SYN_MT_REPORT event may be omitted. Otherwise, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) last SYN_REPORT will be dropped by the input core, resulting in no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) zero-contact event reaching userland.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Protocol Example B
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) Here is what a minimal event sequence for a two-contact touch would look
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) like for a type B device::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)    ABS_MT_SLOT 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135)    ABS_MT_TRACKING_ID 45
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)    ABS_MT_POSITION_X x[0]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)    ABS_MT_POSITION_Y y[0]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)    ABS_MT_SLOT 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)    ABS_MT_TRACKING_ID 46
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)    ABS_MT_POSITION_X x[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)    ABS_MT_POSITION_Y y[1]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Here is the sequence after moving contact 45 in the x direction::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)    ABS_MT_SLOT 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147)    ABS_MT_POSITION_X x[0]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Here is the sequence after lifting the contact in slot 0::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)    ABS_MT_TRACKING_ID -1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) The slot being modified is already 0, so the ABS_MT_SLOT is omitted.  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) message removes the association of slot 0 with contact 45, thereby
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) destroying contact 45 and freeing slot 0 to be reused for another contact.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) Finally, here is the sequence after lifting the second contact::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)    ABS_MT_SLOT 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)    ABS_MT_TRACKING_ID -1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)    SYN_REPORT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Event Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) A set of ABS_MT events with the desired properties is defined. The events
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) are divided into categories, to allow for partial implementation.  The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) allows for multiple contacts to be tracked.  If the device supports it, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) of the contact area and approaching tool, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) looking through a window at someone gently holding a finger against the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) glass.  You will see two regions, one inner region consisting of the part
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) of the finger actually touching the glass, and one outer region formed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) the perimeter of the finger. The center of the touching region (a) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) ABS_MT_POSITION_X/Y and the center of the approaching finger (b) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) ABS_MT_TOOL_X/Y. The touch diameter is ABS_MT_TOUCH_MAJOR and the finger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) diameter is ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) harder against the glass. The touch region will increase, and in general,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) the ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) than unity, is related to the contact pressure. For pressure-based devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) ABS_MT_PRESSURE may be used to provide the pressure on the contact area
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) instead. Devices capable of contact hovering can use ABS_MT_DISTANCE to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) indicate the distance between the contact and the surface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) 	  Linux MT                               Win8
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)          __________                     _______________________
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)         /          \                   |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)        /            \                  |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)       /     ____     \                 |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)      /     /    \     \                |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)      \     \  a  \     \               |       a               |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)       \     \____/      \              |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202)        \                 \             |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)         \        b        \            |           b           |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)          \                 \           |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)           \                 \          |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)            \                 \         |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)             \                /         |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)              \              /          |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)               \            /           |                       |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)                \__________/            |_______________________|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) In addition to the MAJOR parameters, the oval shape of the touch and finger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) regions can be described by adding the MINOR parameters, such that MAJOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) and MINOR are the major and minor axis of an ellipse. The orientation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) the touch ellipse can be described with the ORIENTATION parameter, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) direction of the finger ellipse is given by the vector (a - b).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) For type A devices, further specification of the touch shape is possible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) via ABS_MT_BLOB_ID.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) finger or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) may be used to track identified contacts over time [#f5]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) In the type B protocol, ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) implicitly handled by input core; drivers should instead call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) input_mt_report_slot_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) Event Semantics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) ABS_MT_TOUCH_MAJOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)     The length of the major axis of the contact. The length should be given in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)     surface units. If the surface has an X times Y resolution, the largest
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)     possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [#f4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) ABS_MT_TOUCH_MINOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)     The length, in surface units, of the minor axis of the contact. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)     contact is circular, this event can be omitted [#f4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) ABS_MT_WIDTH_MAJOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)     The length, in surface units, of the major axis of the approaching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)     tool. This should be understood as the size of the tool itself. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246)     orientation of the contact and the approaching tool are assumed to be the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)     same [#f4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) ABS_MT_WIDTH_MINOR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)     The length, in surface units, of the minor axis of the approaching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)     tool. Omit if circular [#f4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)     The above four values can be used to derive additional information about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)     the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)     the notion of pressure. The fingers of the hand and the palm all have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)     different characteristic widths.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) ABS_MT_PRESSURE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259)     The pressure, in arbitrary units, on the contact area. May be used instead
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)     of TOUCH and WIDTH for pressure-based devices or any device with a spatial
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)     signal intensity distribution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) ABS_MT_DISTANCE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)     The distance, in surface units, between the contact and the surface. Zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)     distance means the contact is touching the surface. A positive number means
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)     the contact is hovering above the surface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) ABS_MT_ORIENTATION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)     The orientation of the touching ellipse. The value should describe a signed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270)     quarter of a revolution clockwise around the touch center. The signed value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)     range is arbitrary, but zero should be returned for an ellipse aligned with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)     the Y axis (north) of the surface, a negative value when the ellipse is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)     turned to the left, and a positive value when the ellipse is turned to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)     right. When aligned with the X axis in the positive direction, the range
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)     max should be returned; when aligned with the X axis in the negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276)     direction, the range -max should be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)     Touch ellipsis are symmetrical by default. For devices capable of true 360
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)     degree orientation, the reported orientation must exceed the range max to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)     indicate more than a quarter of a revolution. For an upside-down finger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)     range max * 2 should be returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283)     Orientation can be omitted if the touch area is circular, or if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)     information is not available in the kernel driver. Partial orientation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)     support is possible if the device can distinguish between the two axis, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)     not (uniquely) any values in between. In such cases, the range of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)     ABS_MT_ORIENTATION should be [0, 1] [#f4]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) ABS_MT_POSITION_X
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)     The surface X coordinate of the center of the touching ellipse.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) ABS_MT_POSITION_Y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)     The surface Y coordinate of the center of the touching ellipse.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) ABS_MT_TOOL_X
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)     The surface X coordinate of the center of the approaching tool. Omit if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)     the device cannot distinguish between the intended touch point and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)     tool itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) ABS_MT_TOOL_Y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)     The surface Y coordinate of the center of the approaching tool. Omit if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)     device cannot distinguish between the intended touch point and the tool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)     itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)     The four position values can be used to separate the position of the touch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)     from the position of the tool. If both positions are present, the major
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)     tool axis points towards the touch point [#f1]_. Otherwise, the tool axes are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308)     aligned with the touch axes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) ABS_MT_TOOL_TYPE
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)     The type of approaching tool. A lot of kernel drivers cannot distinguish
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)     between different tool types, such as a finger or a pen. In such cases, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313)     event should be omitted. The protocol currently mainly supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)     MT_TOOL_FINGER, MT_TOOL_PEN, and MT_TOOL_PALM [#f2]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)     For type B devices, this event is handled by input core; drivers should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)     instead use input_mt_report_slot_state(). A contact's ABS_MT_TOOL_TYPE may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)     change over time while still touching the device, because the firmware may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318)     not be able to determine which tool is being used when it first appears.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) ABS_MT_BLOB_ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321)     The BLOB_ID groups several packets together into one arbitrarily shaped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)     contact. The sequence of points forms a polygon which defines the shape of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)     the contact. This is a low-level anonymous grouping for type A devices, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)     should not be confused with the high-level trackingID [#f5]_. Most type A
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)     devices do not have blob capability, so drivers can safely omit this event.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) ABS_MT_TRACKING_ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)     The TRACKING_ID identifies an initiated contact throughout its life cycle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329)     [#f5]_. The value range of the TRACKING_ID should be large enough to ensure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)     unique identification of a contact maintained over an extended period of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)     time. For type B devices, this event is handled by input core; drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)     should instead use input_mt_report_slot_state().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) Event Computation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) The flora of different hardware unavoidably leads to some devices fitting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) better to the MT protocol than others. To simplify and unify the mapping,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) this section gives recipes for how to compute certain events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) For devices reporting contacts as rectangular shapes, signed orientation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) cannot be obtained. Assuming X and Y are the lengths of the sides of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) touching rectangle, here is a simple formula that retains the most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) information possible::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)    ABS_MT_TOUCH_MAJOR := max(X, Y)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348)    ABS_MT_TOUCH_MINOR := min(X, Y)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)    ABS_MT_ORIENTATION := bool(X > Y)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) the device can distinguish between a finger along the Y axis (0) and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) finger along the X axis (1).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) For win8 devices with both T and C coordinates, the position mapping is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)    ABS_MT_POSITION_X := T_X
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)    ABS_MT_POSITION_Y := T_Y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)    ABS_MT_TOOL_X := C_X
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360)    ABS_MT_TOOL_Y := C_Y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) Unfortunately, there is not enough information to specify both the touching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) ellipse and the tool ellipse, so one has to resort to approximations.  One
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) simple scheme, which is compatible with earlier usage, is::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)    ABS_MT_TOUCH_MAJOR := min(X, Y)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)    ABS_MT_TOUCH_MINOR := <not used>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)    ABS_MT_ORIENTATION := <not used>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)    ABS_MT_WIDTH_MAJOR := min(X, Y) + distance(T, C)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)    ABS_MT_WIDTH_MINOR := min(X, Y)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) Rationale: We have no information about the orientation of the touching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) ellipse, so approximate it with an inscribed circle instead. The tool
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) ellipse should align with the vector (T - C), so the diameter must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) increase with distance(T, C). Finally, assume that the touch diameter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) equal to the tool thickness, and we arrive at the formulas above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) Finger Tracking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) The process of finger tracking, i.e., to assign a unique trackingID to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) initiated contact on the surface, is a Euclidian Bipartite Matching
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) problem.  At each event synchronization, the set of actual contacts is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) matched to the set of contacts from the previous synchronization. A full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) implementation can be found in [#f3]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) Gestures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) In the specific application of creating gesture events, the TOUCH and WIDTH
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) parameters can be used to, e.g., approximate finger pressure or distinguish
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) between index finger and thumb. With the addition of the MINOR parameters,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) one can also distinguish between a sweeping finger and a pointing finger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) and with ORIENTATION, one can detect twisting of fingers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) Notes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) -----
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) In order to stay compatible with existing applications, the data reported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) in a finger packet must not be recognized as single-touch events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) For type A devices, all finger data bypasses input filtering, since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) subsequent events of the same type refer to different fingers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) .. [#f1] Also, the difference (TOOL_X - POSITION_X) can be used to model tilt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) .. [#f2] The list can of course be extended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) .. [#f3] The mtdev project: http://bitmath.org/code/mtdev/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) .. [#f4] See the section on event computation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) .. [#f5] See the section on finger tracking.