Input: update multi-touch protocol documentation

This patch documents a new ABS_MT parameter and adds further text to clarify some points around the MT protocol. Requested-by: Yoonyoung Shim <jy0922.shim@samsung.com> Requested-by: Mika Kuoppala <mika.kuoppala@nokia.com> Requested-by: Peter Hutterer <peter.hutterer@who-t.net> Signed-off-by: Henrik Rydberg <rydberg@euromail.se> Signed-off-by: Dmitry Torokhov <dtor@mail.ru>

Input: update multi-touch protocol documentation
This patch documents a new ABS_MT parameter and adds further text to clarify some points around the MT protocol. Requested-by: Yoonyoung Shim <jy0922.shim@samsung.com> Requested-by: Mika Kuoppala <mika.kuoppala@nokia.com> Requested-by: Peter Hutterer <peter.hutterer@who-t.net> Signed-off-by: Henrik Rydberg <rydberg@euromail.se> Signed-off-by: Dmitry Torokhov <dtor@mail.ru>
Henrik Rydberg · Dmitry Torokhov
1 parent cb6ecf6f7a
Showing 1 changed file with 40 additions and 8 deletions Side-by-side Diff
Documentation/input/multi-touch-protocol.txt
@@ -27,12 +27,30 @@
  
 A set of ABS_MT events with the desired properties is defined. The events
 are divided into categories, to allow for partial implementation.  The
-minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
-ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked.  If the
-device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
-of the approaching finger. Anisotropy and direction may be specified with
-ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION.  The
-ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
+minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
+allows for multiple fingers to be tracked.  If the device supports it, the
+ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
+of the contact area and approaching finger, respectively.
+
+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
+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
+ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
+unity, is related to the finger pressure. For pressure-based devices,
+ABS_MT_PRESSURE may be used to provide the pressure on the contact area
+instead.
+
+In addition to the MAJOR parameters, the oval shape of the finger can be
+described by adding the MINOR parameters, such that MAJOR and MINOR are the
+major and minor axis of an ellipse. Finally, the orientation of the oval
+shape can be describe with the ORIENTATION parameter.
+
+The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
 finger or a pen or something else.  Devices with more granular information
 may specify general shapes as blobs, i.e., as a sequence of rectangular
 shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
  
@@ -42,11 +60,9 @@
 Here is what a minimal event sequence for a two-finger touch would look
 like:
  
-   ABS_MT_TOUCH_MAJOR
    ABS_MT_POSITION_X
    ABS_MT_POSITION_Y
    SYN_MT_REPORT
-   ABS_MT_TOUCH_MAJOR
    ABS_MT_POSITION_X
    ABS_MT_POSITION_Y
    SYN_MT_REPORT
@@ -87,6 +103,12 @@
 the notion of pressure. The fingers of the hand and the palm all have
 different characteristic widths [1].
  
+ABS_MT_PRESSURE
+
+The pressure, in arbitrary units, on the contact area. May be used instead
+of TOUCH and WIDTH for pressure-based devices or any device with a spatial
+signal intensity distribution.
+
 ABS_MT_ORIENTATION
  
 The orientation of the ellipse. The value should describe a signed quarter
@@ -168,6 +190,16 @@
  
 There are a few devices that support trackingID in hardware. User space can
 make use of these native identifiers to reduce bandwidth and cpu usage.
+
+
+Gestures
+--------
+
+In the specific application of creating gesture events, the TOUCH and WIDTH
+parameters can be used to, e.g., approximate finger pressure or distinguish
+between index finger and thumb. With the addition of the MINOR parameters,
+one can also distinguish between a sweeping finger and a pointing finger,
+and with ORIENTATION, one can detect twisting of fingers.
  
  
 Notes
...	...	@@ -27,12 +27,30 @@
27	27
28	28	A set of ABS_MT events with the desired properties is defined. The events
29	29	are divided into categories, to allow for partial implementation. The
30		-minimum set consists of ABS_MT_TOUCH_MAJOR, ABS_MT_POSITION_X and
31		-ABS_MT_POSITION_Y, which allows for multiple fingers to be tracked. If the
32		-device supports it, the ABS_MT_WIDTH_MAJOR may be used to provide the size
33		-of the approaching finger. Anisotropy and direction may be specified with
34		-ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MINOR and ABS_MT_ORIENTATION. The
35		-ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
	30	+minimum set consists of ABS_MT_POSITION_X and ABS_MT_POSITION_Y, which
	31	+allows for multiple fingers to be tracked. If the device supports it, the
	32	+ABS_MT_TOUCH_MAJOR and ABS_MT_WIDTH_MAJOR may be used to provide the size
	33	+of the contact area and approaching finger, respectively.
	34	+
	35	+The TOUCH and WIDTH parameters have a geometrical interpretation; imagine
	36	+looking through a window at someone gently holding a finger against the
	37	+glass. You will see two regions, one inner region consisting of the part
	38	+of the finger actually touching the glass, and one outer region formed by
	39	+the perimeter of the finger. The diameter of the inner region is the
	40	+ABS_MT_TOUCH_MAJOR, the diameter of the outer region is
	41	+ABS_MT_WIDTH_MAJOR. Now imagine the person pressing the finger harder
	42	+against the glass. The inner region will increase, and in general, the
	43	+ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR, which is always smaller than
	44	+unity, is related to the finger pressure. For pressure-based devices,
	45	+ABS_MT_PRESSURE may be used to provide the pressure on the contact area
	46	+instead.
	47	+
	48	+In addition to the MAJOR parameters, the oval shape of the finger can be
	49	+described by adding the MINOR parameters, such that MAJOR and MINOR are the
	50	+major and minor axis of an ellipse. Finally, the orientation of the oval
	51	+shape can be describe with the ORIENTATION parameter.
	52	+
	53	+The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
36	54	finger or a pen or something else. Devices with more granular information
37	55	may specify general shapes as blobs, i.e., as a sequence of rectangular
38	56	shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices
39	57
...	...	@@ -42,11 +60,9 @@
42	60	Here is what a minimal event sequence for a two-finger touch would look
43	61	like:
44	62
45		- ABS_MT_TOUCH_MAJOR
46	63	ABS_MT_POSITION_X
47	64	ABS_MT_POSITION_Y
48	65	SYN_MT_REPORT
49		- ABS_MT_TOUCH_MAJOR
50	66	ABS_MT_POSITION_X
51	67	ABS_MT_POSITION_Y
52	68	SYN_MT_REPORT
...	...	@@ -87,6 +103,12 @@
87	103	the notion of pressure. The fingers of the hand and the palm all have
88	104	different characteristic widths [1].
89	105
	106	+ABS_MT_PRESSURE
	107	+
	108	+The pressure, in arbitrary units, on the contact area. May be used instead
	109	+of TOUCH and WIDTH for pressure-based devices or any device with a spatial
	110	+signal intensity distribution.
	111	+
90	112	ABS_MT_ORIENTATION
91	113
92	114	The orientation of the ellipse. The value should describe a signed quarter
...	...	@@ -168,6 +190,16 @@
168	190
169	191	There are a few devices that support trackingID in hardware. User space can
170	192	make use of these native identifiers to reduce bandwidth and cpu usage.
	193	+
	194	+
	195	+Gestures
	196	+--------
	197	+
	198	+In the specific application of creating gesture events, the TOUCH and WIDTH
	199	+parameters can be used to, e.g., approximate finger pressure or distinguish
	200	+between index finger and thumb. With the addition of the MINOR parameters,
	201	+one can also distinguish between a sweeping finger and a pointing finger,
	202	+and with ORIENTATION, one can detect twisting of fingers.
171	203
172	204
173	205	Notes