* [PATCH] input: mt: add tracking ID to the MT protocol @ 2009-05-17 20:51 Henrik Rydberg 2009-05-17 20:51 ` [PATCH] input: mt: Augment the event semantics documentation Henrik Rydberg 0 siblings, 1 reply; 6+ messages in thread From: Henrik Rydberg @ 2009-05-17 20:51 UTC (permalink / raw) To: Dmitry Torokhov; +Cc: Andrew Morton, linux-input, linux-kernel, Henrik Rydberg There are a few multi-touch devices that support finger tracking well in hardware, Stantum being the prime example. By exposing the tracking ID in the MT protocol, evdev bandwidth and cpu usage in user space can be reduced. This patch adds the ABS_MT_TRACKING_ID to the MT protocol. Signed-off-by: Henrik Rydberg <rydberg@euromail.se> Tested-by: Stéphane Chatty <chatty@enac.fr> --- drivers/input/input.c | 1 + include/linux/input.h | 1 + 2 files changed, 2 insertions(+), 0 deletions(-) diff --git a/drivers/input/input.c b/drivers/input/input.c index e54e002..5d445f4 100644 --- a/drivers/input/input.c +++ b/drivers/input/input.c @@ -42,6 +42,7 @@ static unsigned int input_abs_bypass_init_data[] __initdata = { ABS_MT_POSITION_Y, ABS_MT_TOOL_TYPE, ABS_MT_BLOB_ID, + ABS_MT_TRACKING_ID, 0 }; static unsigned long input_abs_bypass[BITS_TO_LONGS(ABS_CNT)]; diff --git a/include/linux/input.h b/include/linux/input.h index 0e6ff5d..6fed4f6 100644 --- a/include/linux/input.h +++ b/include/linux/input.h @@ -656,6 +656,7 @@ struct input_absinfo { #define ABS_MT_POSITION_Y 0x36 /* Center Y ellipse position */ #define ABS_MT_TOOL_TYPE 0x37 /* Type of touching device */ #define ABS_MT_BLOB_ID 0x38 /* Group a set of packets as a blob */ +#define ABS_MT_TRACKING_ID 0x39 /* Unique ID of initiated contact */ #define ABS_MAX 0x3f #define ABS_CNT (ABS_MAX+1) -- 1.5.6.3 -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH] input: mt: Augment the event semantics documentation 2009-05-17 20:51 [PATCH] input: mt: add tracking ID to the MT protocol Henrik Rydberg @ 2009-05-17 20:51 ` Henrik Rydberg 2009-05-20 2:59 ` Dmitry Torokhov 0 siblings, 1 reply; 6+ messages in thread From: Henrik Rydberg @ 2009-05-17 20:51 UTC (permalink / raw) To: Dmitry Torokhov; +Cc: Andrew Morton, linux-input, linux-kernel, Henrik Rydberg Through the collaboration to adapt the N-trig and Stantum HID drivers to the MT protocol, some semantic clarifications to the protocol have been made. This patch adds them to the MT documentation. Signed-off-by: Henrik Rydberg <rydberg@euromail.se> Tested-by: Stéphane Chatty <chatty@enac.fr> --- Documentation/input/multi-touch-protocol.txt | 88 +++++++++++++++++++------- 1 files changed, 65 insertions(+), 23 deletions(-) diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index 9f09557..dd755c2 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -18,8 +18,12 @@ Usage Anonymous finger details are sent sequentially as separate packets of ABS events. Only the ABS_MT events are recognized as part of a finger packet. The end of a packet is marked by calling the input_mt_sync() -function, which generates a SYN_MT_REPORT event. The end of multi-touch -transfer is marked by calling the usual input_sync() function. +function, which generates a SYN_MT_REPORT event. This instructs the +receiver to accept the data for the current finger and prepare to receive +another. The end of a multi-touch transfer is marked by calling the usual +input_sync() function. This instructs the receiver to perform actions based +on the received packets, and prepare to receive a new set of finger +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 @@ -27,11 +31,13 @@ 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. 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, the ABS_MT_TOOL_TYPE may be used to specify -whether the touching tool is a finger or a pen or something else. +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 +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 +that currently support it, the ABS_MT_TRACKING_ID event may be used to +report finger tracking from hardware [5]. Event Semantics @@ -44,24 +50,24 @@ ABS_MT_TOUCH_MAJOR The length of the major axis of the contact. The length should be given in surface units. If the surface has an X times Y resolution, the largest -possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal. +possible value of ABS_MT_TOUCH_MAJOR is sqrt(X^2 + Y^2), the diagonal [4]. ABS_MT_TOUCH_MINOR The length, in surface units, of the minor axis of the contact. If the -contact is circular, this event can be omitted. +contact is circular, this event can be omitted [4]. ABS_MT_WIDTH_MAJOR The length, in surface units, of the major axis of the approaching tool. This should be understood as the size of the tool itself. The orientation of the contact and the approaching tool are assumed to be the -same. +same [4]. ABS_MT_WIDTH_MINOR The length, in surface units, of the minor axis of the approaching -tool. Omit if circular. +tool. Omit if circular [4]. The above four values can be used to derive additional information about the contact. The ratio ABS_MT_TOUCH_MAJOR / ABS_MT_WIDTH_MAJOR approximates @@ -70,14 +76,17 @@ different characteristic widths [1]. ABS_MT_ORIENTATION -The orientation of the ellipse. The value should describe half a revolution -clockwise around the touch center. The scale of the value is arbitrary, but -zero should be returned for an ellipse aligned along the Y axis of the -surface. As an example, an index finger placed straight onto the axis could -return zero orientation, something negative when twisted to the left, and -something positive when twisted to the right. This value can be omitted if -the touching object is circular, or if the information is not available in -the kernel driver. +The orientation of the ellipse. The value should describe a signed quarter +of a revolution clockwise around the touch center. The signed value range +is arbitrary, but zero should be returned for a finger aligned along the Y +axis of the surface, something negative when twisted to the left, and +something positive when twisted to the right. When completely aligned with +the X axis, the range max should be returned. Orientation can be omitted +if the touching object is circular, or if the information is not available +in the kernel driver. Partial orientation support is possible if the device +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]. ABS_MT_POSITION_X @@ -98,8 +107,35 @@ ABS_MT_BLOB_ID The BLOB_ID groups several packets together into one arbitrarily shaped contact. This is a low-level anonymous grouping, and should not be confused -with the high-level contactID, explained below. Most kernel drivers will -not have this capability, and can safely omit the event. +with the high-level trackingID [5]. Most kernel drivers will not have this +capability, and can safely omit the event. + +ABS_MT_TRACKING_ID + +The TRACKING_ID identifies an initiated contact throughout its life cycle +[5]. There are currently only a few devices that support it, so this event +should normally be omitted. + + +Event Computation +----------------- + +The flora of different hardware unavoidably leads to some devices fitting +better to the MT protocol than others. To simplify and unify the mapping, +this section gives recipes for how to compute certain events. + +For devices reporting contacts as rectangular shapes, signed orientation +cannot be obtained. Assuming X and Y are the lengths of the sides of the +touching rectangle, here is a simple formula that retains the most +information possible: + + 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 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). Finger Tracking @@ -109,14 +145,18 @@ The kernel driver should generate an arbitrary enumeration of the set of anonymous contacts currently on the surface. The order in which the packets appear in the event stream is not important. -The process of finger tracking, i.e., to assign a unique contactID to each +The process of finger tracking, i.e., to assign a unique trackingID to each initiated contact on the surface, is left to user space; preferably the -multi-touch X driver [3]. In that driver, the contactID stays the same and +multi-touch X driver [3]. In that driver, the trackingID stays the same and unique until the contact vanishes (when the finger leaves the surface). The problem of assigning a set of anonymous fingers to a set of identified fingers is a euclidian bipartite matching problem at each event update, and relies on a sufficiently rapid update rate. +There are a few devices that support trackingID in hardware. The X driver +can make use of these native identifiers to reduce evdev bandwidth and cpu +usage. + Notes ----- @@ -138,3 +178,5 @@ prototype implements finger matching, basic mouse support and two-finger scrolling. The project aims at improving the quality of current multi-touch functionality available in the synaptics X driver, and in addition implement more advanced gestures. +[4] See the section on event computation. +[5] See the section on finger tracking. -- 1.5.6.3 -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] input: mt: Augment the event semantics documentation 2009-05-17 20:51 ` [PATCH] input: mt: Augment the event semantics documentation Henrik Rydberg @ 2009-05-20 2:59 ` Dmitry Torokhov 2009-05-20 8:16 ` Henrik Rydberg 0 siblings, 1 reply; 6+ messages in thread From: Dmitry Torokhov @ 2009-05-20 2:59 UTC (permalink / raw) To: Henrik Rydberg; +Cc: Andrew Morton, linux-input, linux-kernel Hi Henrik, On Sun, May 17, 2009 at 10:51:19PM +0200, Henrik Rydberg wrote: > Through the collaboration to adapt the N-trig and Stantum HID > drivers to the MT protocol, some semantic clarifications to the > protocol have been made. This patch adds them to the MT documentation. > > Signed-off-by: Henrik Rydberg <rydberg@euromail.se> > Tested-by: Stéphane Chatty <chatty@enac.fr> I was wondering if the following changes would not make the text a bit better: diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index dd755c2..12f98fb 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -21,9 +21,9 @@ packet. The end of a packet is marked by calling the input_mt_sync() function, which generates a SYN_MT_REPORT event. This instructs the receiver to accept the data for the current finger and prepare to receive another. The end of a multi-touch transfer is marked by calling the usual -input_sync() function. This instructs the receiver to perform actions based -on the received packets, and prepare to receive a new set of finger -packets. +input_sync() function. This instructs the receiver to act upon events +accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new +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 @@ -79,8 +79,8 @@ ABS_MT_ORIENTATION The orientation of the ellipse. The value should describe a signed quarter of a revolution clockwise around the touch center. The signed value range is arbitrary, but zero should be returned for a finger aligned along the Y -axis of the surface, something negative when twisted to the left, and -something positive when twisted to the right. When completely aligned with +axis of the surface, a negative value when finger is turned to the left, and +a positive value when finger turned to the right. When completely aligned with the X axis, the range max should be returned. Orientation can be omitted if the touching object is circular, or if the information is not available in the kernel driver. Partial orientation support is possible if the device @@ -176,7 +176,7 @@ could be used to derive tilt. time of writing (April 2009), the MT protocol is not yet merged, and the prototype implements finger matching, basic mouse support and two-finger scrolling. The project aims at improving the quality of current multi-touch -functionality available in the synaptics X driver, and in addition +functionality available in the Synaptics X driver, and in addition implement more advanced gestures. [4] See the section on event computation. [5] See the section on finger tracking. -- Dmitry -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] input: mt: Augment the event semantics documentation 2009-05-20 2:59 ` Dmitry Torokhov @ 2009-05-20 8:16 ` Henrik Rydberg 2009-05-20 8:44 ` Dmitry Torokhov 0 siblings, 1 reply; 6+ messages in thread From: Henrik Rydberg @ 2009-05-20 8:16 UTC (permalink / raw) To: Dmitry Torokhov; +Cc: Andrew Morton, linux-input, linux-kernel Dmitry Torokhov wrote: > Hi Henrik, > > On Sun, May 17, 2009 at 10:51:19PM +0200, Henrik Rydberg wrote: >> Through the collaboration to adapt the N-trig and Stantum HID >> drivers to the MT protocol, some semantic clarifications to the >> protocol have been made. This patch adds them to the MT documentation. >> >> Signed-off-by: Henrik Rydberg <rydberg@euromail.se> >> Tested-by: Stéphane Chatty <chatty@enac.fr> > > I was wondering if the following changes would not make the text a bit > better: They do, thanks. I got more comments on the text, perhaps it is easiest if I send an additional patch on top of this one, with your changes included? It seems folding a patch is easier than to find out what changes were made to the changes. Cheers, Henrik -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] input: mt: Augment the event semantics documentation 2009-05-20 8:16 ` Henrik Rydberg @ 2009-05-20 8:44 ` Dmitry Torokhov 2009-05-20 8:58 ` Henrik Rydberg 0 siblings, 1 reply; 6+ messages in thread From: Dmitry Torokhov @ 2009-05-20 8:44 UTC (permalink / raw) To: Henrik Rydberg; +Cc: Andrew Morton, linux-input, linux-kernel On Wednesday 20 May 2009 01:16:16 Henrik Rydberg wrote: > Dmitry Torokhov wrote: > > Hi Henrik, > > > > On Sun, May 17, 2009 at 10:51:19PM +0200, Henrik Rydberg wrote: > >> Through the collaboration to adapt the N-trig and Stantum HID > >> drivers to the MT protocol, some semantic clarifications to the > >> protocol have been made. This patch adds them to the MT documentation. > >> > >> Signed-off-by: Henrik Rydberg <rydberg@euromail.se> > >> Tested-by: Stéphane Chatty <chatty@enac.fr> > > > > I was wondering if the following changes would not make the text a bit > > better: > > They do, thanks. I got more comments on the text, perhaps it is easiest > if I send an additional patch on top of this one, with your changes > included? It seems folding a patch is easier than to find out what > changes were made to the changes. > Sure, send it along. -- Dmitry -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] input: mt: Augment the event semantics documentation 2009-05-20 8:44 ` Dmitry Torokhov @ 2009-05-20 8:58 ` Henrik Rydberg 0 siblings, 0 replies; 6+ messages in thread From: Henrik Rydberg @ 2009-05-20 8:58 UTC (permalink / raw) To: Dmitry Torokhov; +Cc: Andrew Morton, linux-input, linux-kernel Dmitry Torokhov wrote: > On Wednesday 20 May 2009 01:16:16 Henrik Rydberg wrote: >> Dmitry Torokhov wrote: >>> Hi Henrik, >>> >>> On Sun, May 17, 2009 at 10:51:19PM +0200, Henrik Rydberg wrote: >>>> Through the collaboration to adapt the N-trig and Stantum HID >>>> drivers to the MT protocol, some semantic clarifications to the >>>> protocol have been made. This patch adds them to the MT documentation. >>>> >>>> Signed-off-by: Henrik Rydberg <rydberg@euromail.se> >>>> Tested-by: Stéphane Chatty <chatty@enac.fr> >>> I was wondering if the following changes would not make the text a bit >>> better: >> They do, thanks. I got more comments on the text, perhaps it is easiest >> if I send an additional patch on top of this one, with your changes >> included? It seems folding a patch is easier than to find out what >> changes were made to the changes. >> > > Sure, send it along. > Signed-off-by: Henrik Rydberg <rydberg@euromail.se> diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt index dd755c2..a12ea3b 100644 --- a/Documentation/input/multi-touch-protocol.txt +++ b/Documentation/input/multi-touch-protocol.txt @@ -21,9 +21,9 @@ packet. The end of a packet is marked by calling the input_mt_sync() function, which generates a SYN_MT_REPORT event. This instructs the receiver to accept the data for the current finger and prepare to receive another. The end of a multi-touch transfer is marked by calling the usual -input_sync() function. This instructs the receiver to perform actions based -on the received packets, and prepare to receive a new set of finger -packets. +input_sync() function. This instructs the receiver to act upon events +accumulated since last EV_SYN/SYN_REPORT and prepare to receive a new +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 @@ -39,6 +39,19 @@ shapes grouped together by an ABS_MT_BLOB_ID. Finally, for the few devices that currently support it, the ABS_MT_TRACKING_ID event may be used to 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 + SYN_REPORT + Event Semantics --------------- @@ -79,8 +92,8 @@ ABS_MT_ORIENTATION The orientation of the ellipse. The value should describe a signed quarter of a revolution clockwise around the touch center. The signed value range is arbitrary, but zero should be returned for a finger aligned along the Y -axis of the surface, something negative when twisted to the left, and -something positive when twisted to the right. When completely aligned with +axis of the surface, a negative value when finger is turned to the left, and +a positive value when finger turned to the right. When completely aligned with the X axis, the range max should be returned. Orientation can be omitted if the touching object is circular, or if the information is not available in the kernel driver. Partial orientation support is possible if the device @@ -107,7 +120,7 @@ ABS_MT_BLOB_ID The BLOB_ID groups several packets together into one arbitrarily shaped contact. This is a low-level anonymous grouping, and should not be confused -with the high-level trackingID [5]. Most kernel drivers will not have this +with the high-level trackingID [5]. Most kernel drivers will not have blob capability, and can safely omit the event. ABS_MT_TRACKING_ID @@ -153,9 +166,9 @@ problem of assigning a set of anonymous fingers to a set of identified fingers is a euclidian bipartite matching problem at each event update, and relies on a sufficiently rapid update rate. -There are a few devices that support trackingID in hardware. The X driver -can make use of these native identifiers to reduce evdev bandwidth and cpu -usage. +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. + Notes ----- @@ -176,7 +189,7 @@ could be used to derive tilt. time of writing (April 2009), the MT protocol is not yet merged, and the prototype implements finger matching, basic mouse support and two-finger scrolling. The project aims at improving the quality of current multi-touch -functionality available in the synaptics X driver, and in addition +functionality available in the Synaptics X driver, and in addition implement more advanced gestures. [4] See the section on event computation. [5] See the section on finger tracking. -- To unsubscribe from this list: send the line "unsubscribe linux-input" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html ^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2009-05-20 8:58 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-05-17 20:51 [PATCH] input: mt: add tracking ID to the MT protocol Henrik Rydberg 2009-05-17 20:51 ` [PATCH] input: mt: Augment the event semantics documentation Henrik Rydberg 2009-05-20 2:59 ` Dmitry Torokhov 2009-05-20 8:16 ` Henrik Rydberg 2009-05-20 8:44 ` Dmitry Torokhov 2009-05-20 8:58 ` Henrik Rydberg
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).