From f6bdc2303da6786cc22a7d24b6790e9f75b4cfdc Mon Sep 17 00:00:00 2001 From: Henrik Rydberg Date: Thu, 28 Jan 2010 22:28:28 -0800 Subject: 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 Requested-by: Mika Kuoppala Requested-by: Peter Hutterer Signed-off-by: Henrik Rydberg Signed-off-by: Dmitry Torokhov --- Documentation/input/multi-touch-protocol.txt | 48 +++++++++++++++++++++++----- 1 file changed, 40 insertions(+), 8 deletions(-) (limited to 'Documentation') diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index a12ea3b586e..8490480ce43 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -27,12 +27,30 @@ set of events/packets. 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 @@ report finger tracking from hardware [5]. 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 contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates 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 @@ -170,6 +192,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 ----- -- cgit v1.2.3-70-g09d2