[RFC] Input: MT - Include win8 support

[Henrik Rydberg]

The newly released HID protocol for win8 input devices is capable of
transmitting the same information found in the Apple HID and Linux MT
protocols. In addition, it includes an extension useful for touch
alignment. This patch completes the MT protocol with the
ABS_MT_APPROACH_X/Y events, and documents how to map win8 devices.

Signed-off-by: Henrik Rydberg <rydberg@xxxxxxxxxxx>
---
Hi all,

In response to the win8 HID protocol and Benjamin's work on this, here
is a first draft of the needed extension to the MT protocol. I am
cc:ing the usual suspects, as this will affect userland. Comments and
criticism expected. :-)

Cheers,
Henrik

 Documentation/input/multi-touch-protocol.txt |   35 +++++++++++++++++++++++++-
 include/linux/input.h                        |    4 ++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index 543101c..504ca6d 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -168,7 +168,9 @@ The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
 looking through a window at someone gently holding a finger against the
 glass.  You will see two regions, one inner region consisting of the part
 of the finger actually touching the glass, and one outer region formed by
-the perimeter of the finger. The diameter of the inner region is the
+the perimeter of the finger. The center of the inner region is
+ABS_MT_POSITION_X/Y. The center of the outer region may be different,
+denoted by ABS_MT_APPROACH_X/Y. The diameter of the inner region is the
 ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
 ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
 against the glass. The inner region will increase, and in general, the
@@ -252,6 +254,9 @@ can distinguish between the two axis, but not (uniquely) any values in
 between. In such cases, the range of ABS_MT_ORIENTATION should be [0, 1]
 [4].
 
+For devices capable of 360 degree orientation, the reported orientation
+should be twice the given range.
+
 ABS_MT_POSITION_X
 
 The surface X coordinate of the center of the touching ellipse.
@@ -260,6 +265,23 @@ ABS_MT_POSITION_Y
 
 The surface Y coordinate of the center of the touching ellipse.
 
+ABS_MT_APPROACH_X
+
+The surface X coordinate of the center of the approaching ellipse. Omit if
+the device cannot distinguish between the intended touching point and the
+center of the approaching contact.
+
+ABS_MT_APPROACH_Y
+
+The surface Y coordinate of the center of the approaching ellipse. Omit if
+the device cannot distinguish between the intended touching point and the
+center of the approaching contact.
+
+The four position values can be used to separate the intended touch point
+from the center of the approaching object. The difference also yields an
+approximation of the directed orientation of the approaching ellipse, with
+ABS_MT_WIDTH_MAJOR pointing towards the touch center.
+
 ABS_MT_TOOL_TYPE
 
 The type of approaching tool. A lot of kernel drivers cannot distinguish
@@ -305,6 +327,17 @@ The range of ABS_MT_ORIENTATION should be set to [0, 1], to indicate that
 the device can distinguish between a finger along the Y axis (0) and a
 finger along the X axis (1).
 
+For win8 devices with both T and C coordinates, the position mapping is
+
+   ABS_MT_POSITION_X := T_X
+   ABS_MT_POSITION_Y := T_Y
+   ABS_MT_APPROACH_X := C_X
+   ABS_MT_APPROACH_X := C_Y
+
+For win8 devices with Azimuth or Twist defined, the range max is the value
+for 90 degrees, and the orientation mapping is
+
+   ABS_MT_ORIENTATION := twist < 2 * max ? twist : twist - 4 * max
 
 Finger Tracking
 ---------------
diff --git a/include/linux/input.h b/include/linux/input.h
index a816714..039234e 100644
--- a/include/linux/input.h
+++ b/include/linux/input.h
@@ -813,11 +813,13 @@ struct input_keymap_entry {
 #define ABS_MT_TRACKING_ID	0x39	/* Unique ID of initiated contact */
 #define ABS_MT_PRESSURE		0x3a	/* Pressure on contact area */
 #define ABS_MT_DISTANCE		0x3b	/* Contact hover distance */
+#define ABS_MT_APPROACH_X	0x3c	/* Center X approaching ellipse */
+#define ABS_MT_APPROACH_Y	0x3d	/* Center Y approaching ellipse */
 
 #ifdef __KERNEL__
 /* Implementation details, userspace should not care about these */
 #define ABS_MT_FIRST		ABS_MT_TOUCH_MAJOR
-#define ABS_MT_LAST		ABS_MT_DISTANCE
+#define ABS_MT_LAST		ABS_MT_APPROACH_Y
 #endif
 
 #define ABS_MAX			0x3f
-- 
1.7.10

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/