The recent input-mt interface changes together with
recent discussions about pen and touch and support
for legacy multitouch pads suggest that the documentation
on MT tool types be expanded. This patch adds references
to the new interface, and adds a section for MT_TOOL types,
in particular documenting the use of MT_TOOL_ENVELOPE.
Signed-off-by: Henrik Rydberg <[email protected]>
---
Documentation/input/multi-touch-protocol.txt | 37 ++++++++++++++++++-------
1 files changed, 26 insertions(+), 11 deletions(-)
diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
index 351fab8..e190943 100644
--- a/Documentation/input/multi-touch-protocol.txt
+++ b/Documentation/input/multi-touch-protocol.txt
@@ -169,12 +169,14 @@ 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.
+For type A devices, further specification of the touch shape is possible
+via ABS_MT_BLOB_ID.
+
The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
-contact 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 contact tracking from hardware [5].
+contact or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
+may be used to track identified contacts over time [5]. In the type B
+protocol, the use of ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID is implicit
+via the input_mt_report_slot_state() function.
Event Semantics
@@ -247,21 +249,34 @@ ABS_MT_TOOL_TYPE
The type of approaching tool. A lot of kernel drivers cannot distinguish
between different tool types, such as a finger or a pen. In such cases, the
event should be omitted. The protocol currently supports MT_TOOL_FINGER and
-MT_TOOL_PEN and MT_TOOL_ENVELOPE [2].
+MT_TOOL_PEN and MT_TOOL_ENVELOPE [2]. For type B devices, this event is
+handled by input core, via the input_mt interface.
+
+- The MT_TOOL_FINGER type is the default, and represents a finger touch.
+
+- The MT_TOOL_PEN type represents a pen, and the list of related tools is
+expected to grow with time.
+
+- The MT_TOOL_ENVELOPE type is used to indicate that the contact position
+is not well-defined, and is only used for legacy hardware. The real contact
+positions are to be found within the bounding rectangle formed by the
+envelope contact positions.
ABS_MT_BLOB_ID
The BLOB_ID groups several packets together into one arbitrarily shaped
-contact. This is a low-level anonymous grouping for type A devices, and
+contact. The sequence of points forms a polygon which defines the shape of
+the contact. This is a low-level anonymous grouping for type A devices, and
should not be confused with the high-level trackingID [5]. Most type A
devices do not have blob capability, so drivers can safely omit this event.
ABS_MT_TRACKING_ID
The TRACKING_ID identifies an initiated contact throughout its life cycle
-[5]. This event is mandatory for type B devices. The value range of the
-TRACKING_ID should be large enough to ensure unique identification of a
-contact maintained over an extended period of time.
+[5]. The value range of the TRACKING_ID should be large enough to ensure
+unique identification of a contact maintained over an extended period of
+time. For type B devices, this event is handled by input core, via the
+input_mt interface.
Event Computation
@@ -321,6 +336,6 @@ difference between the contact position and the approaching tool position
could be used to derive tilt.
[2] ABS_MT_ENVELOPE contacts represent an envelope of the contacts rather
than the actual contacts. Used with older, not fully MT capable, devices.
-[3] Multitouch X driver project: http://bitmath.org/code/multitouch/.
+[3] The mtdev project: http://bitmath.org/code/mtdev/.
[4] See the section on event computation.
[5] See the section on finger tracking.
--
1.7.1
On Thu, Dec 09, 2010 at 10:22:12PM +0100, Henrik Rydberg wrote:
> The recent input-mt interface changes together with
> recent discussions about pen and touch and support
> for legacy multitouch pads suggest that the documentation
> on MT tool types be expanded. This patch adds references
> to the new interface, and adds a section for MT_TOOL types,
> in particular documenting the use of MT_TOOL_ENVELOPE.
>
> Signed-off-by: Henrik Rydberg <[email protected]>
The explanation of the new types makes sense to me... Do you think we
could add some comments directly to input.h?
> @@ -247,21 +249,34 @@ ABS_MT_TOOL_TYPE
> The type of approaching tool. A lot of kernel drivers cannot distinguish
> between different tool types, such as a finger or a pen. In such cases, the
> event should be omitted. The protocol currently supports MT_TOOL_FINGER and
s/and/,/
> -MT_TOOL_PEN and MT_TOOL_ENVELOPE [2].
> +MT_TOOL_PEN and MT_TOOL_ENVELOPE [2]. For type B devices, this event is
> +handled by input core, via the input_mt interface.
> +
Thanks.
--
Dmitry
On 12/10/2010 08:43 AM, Dmitry Torokhov wrote:
> On Thu, Dec 09, 2010 at 10:22:12PM +0100, Henrik Rydberg wrote:
>> The recent input-mt interface changes together with
>> recent discussions about pen and touch and support
>> for legacy multitouch pads suggest that the documentation
>> on MT tool types be expanded. This patch adds references
>> to the new interface, and adds a section for MT_TOOL types,
>> in particular documenting the use of MT_TOOL_ENVELOPE.
>>
>> Signed-off-by: Henrik Rydberg <[email protected]>
>
>
> The explanation of the new types makes sense to me... Do you think we
> could add some comments directly to input.h?
Good idea, will do.
Thanks,
Henrik
On Thu, Dec 9, 2010 at 1:22 PM, Henrik Rydberg <[email protected]> wrote:
> The recent input-mt interface changes together with
> recent discussions about pen and touch and support
> for legacy multitouch pads suggest that the documentation
> on MT tool types be expanded. This patch adds references
> to the new interface, and adds a section for MT_TOOL types,
> in particular documenting the use of MT_TOOL_ENVELOPE.
>
> Signed-off-by: Henrik Rydberg <[email protected]>
> ---
> ?Documentation/input/multi-touch-protocol.txt | ? 37 ++++++++++++++++++-------
> ?1 files changed, 26 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
> index 351fab8..e190943 100644
> --- a/Documentation/input/multi-touch-protocol.txt
> +++ b/Documentation/input/multi-touch-protocol.txt
> @@ -169,12 +169,14 @@ 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.
>
> +For type A devices, further specification of the touch shape is possible
> +via ABS_MT_BLOB_ID.
> +
> ?The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
> -contact 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 contact tracking from hardware [5].
> +contact or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
> +may be used to track identified contacts over time [5]. In the type B
> +protocol, the use of ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID is implicit
> +via the input_mt_report_slot_state() function.
>
>
> ?Event Semantics
> @@ -247,21 +249,34 @@ ABS_MT_TOOL_TYPE
> ?The type of approaching tool. A lot of kernel drivers cannot distinguish
> ?between different tool types, such as a finger or a pen. In such cases, the
> ?event should be omitted. The protocol currently supports MT_TOOL_FINGER and
> -MT_TOOL_PEN and MT_TOOL_ENVELOPE [2].
> +MT_TOOL_PEN and MT_TOOL_ENVELOPE [2]. For type B devices, this event is
> +handled by input core, via the input_mt interface.
> +
> +- The MT_TOOL_FINGER type is the default, and represents a finger touch.
> +
> +- The MT_TOOL_PEN type represents a pen, and the list of related tools is
> +expected to grow with time.
> +
> +- The MT_TOOL_ENVELOPE type is used to indicate that the contact position
> +is not well-defined, and is only used for legacy hardware. The real contact
> +positions are to be found within the bounding rectangle formed by the
> +envelope contact positions.
Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
1. Removing ", and is only used for legacy hardware";
2. Adding "Or the number of contacts inside the bounding rectangle is
reported if hardware provides the number but not the real contact
positions" to the end of the paragraph.
Ping
> ?ABS_MT_BLOB_ID
>
> ?The BLOB_ID groups several packets together into one arbitrarily shaped
> -contact. This is a low-level anonymous grouping for type A devices, and
> +contact. The sequence of points forms a polygon which defines the shape of
> +the contact. This is a low-level anonymous grouping for type A devices, and
> ?should not be confused with the high-level trackingID [5]. Most type A
> ?devices do not have blob capability, so drivers can safely omit this event.
>
> ?ABS_MT_TRACKING_ID
>
> ?The TRACKING_ID identifies an initiated contact throughout its life cycle
> -[5]. This event is mandatory for type B devices. The value range of the
> -TRACKING_ID should be large enough to ensure unique identification of a
> -contact maintained over an extended period of time.
> +[5]. The value range of the TRACKING_ID should be large enough to ensure
> +unique identification of a contact maintained over an extended period of
> +time. For type B devices, this event is handled by input core, via the
> +input_mt interface.
>
>
> ?Event Computation
> @@ -321,6 +336,6 @@ difference between the contact position and the approaching tool position
> ?could be used to derive tilt.
> ?[2] ABS_MT_ENVELOPE contacts represent an envelope of the contacts rather
> ?than the actual contacts. Used with older, not fully MT capable, devices.
> -[3] Multitouch X driver project: http://bitmath.org/code/multitouch/.
> +[3] The mtdev project: http://bitmath.org/code/mtdev/.
> ?[4] See the section on event computation.
> ?[5] See the section on finger tracking.
> --
> 1.7.1
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-input" in
> the body of a message to [email protected]
> More majordomo info at ?http://vger.kernel.org/majordomo-info.html
>
On Fri, Dec 10, 2010 at 09:55:12AM -0800, Ping Cheng wrote:
> On Thu, Dec 9, 2010 at 1:22 PM, Henrik Rydberg <[email protected]> wrote:
> > The recent input-mt interface changes together with
> > recent discussions about pen and touch and support
> > for legacy multitouch pads suggest that the documentation
> > on MT tool types be expanded. This patch adds references
> > to the new interface, and adds a section for MT_TOOL types,
> > in particular documenting the use of MT_TOOL_ENVELOPE.
> >
> > Signed-off-by: Henrik Rydberg <[email protected]>
> > ---
> > ?Documentation/input/multi-touch-protocol.txt | ? 37 ++++++++++++++++++-------
> > ?1 files changed, 26 insertions(+), 11 deletions(-)
> >
> > diff --git a/Documentation/input/multi-touch-protocol.txt b/Documentation/input/multi-touch-protocol.txt
> > index 351fab8..e190943 100644
> > --- a/Documentation/input/multi-touch-protocol.txt
> > +++ b/Documentation/input/multi-touch-protocol.txt
> > @@ -169,12 +169,14 @@ 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.
> >
> > +For type A devices, further specification of the touch shape is possible
> > +via ABS_MT_BLOB_ID.
> > +
> > ?The ABS_MT_TOOL_TYPE may be used to specify whether the touching tool is a
> > -contact 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 contact tracking from hardware [5].
> > +contact or a pen or something else. Finally, the ABS_MT_TRACKING_ID event
> > +may be used to track identified contacts over time [5]. In the type B
> > +protocol, the use of ABS_MT_TOOL_TYPE and ABS_MT_TRACKING_ID is implicit
> > +via the input_mt_report_slot_state() function.
> >
> >
> > ?Event Semantics
> > @@ -247,21 +249,34 @@ ABS_MT_TOOL_TYPE
> > ?The type of approaching tool. A lot of kernel drivers cannot distinguish
> > ?between different tool types, such as a finger or a pen. In such cases, the
> > ?event should be omitted. The protocol currently supports MT_TOOL_FINGER and
> > -MT_TOOL_PEN and MT_TOOL_ENVELOPE [2].
> > +MT_TOOL_PEN and MT_TOOL_ENVELOPE [2]. For type B devices, this event is
> > +handled by input core, via the input_mt interface.
> > +
> > +- The MT_TOOL_FINGER type is the default, and represents a finger touch.
> > +
> > +- The MT_TOOL_PEN type represents a pen, and the list of related tools is
> > +expected to grow with time.
> > +
> > +- The MT_TOOL_ENVELOPE type is used to indicate that the contact position
> > +is not well-defined, and is only used for legacy hardware. The real contact
> > +positions are to be found within the bounding rectangle formed by the
> > +envelope contact positions.
>
> Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
>
> 1. Removing ", and is only used for legacy hardware";
> 2. Adding "Or the number of contacts inside the bounding rectangle is
> reported if hardware provides the number but not the real contact
> positions" to the end of the paragraph.
Are you saying that there is upcoming hardware models that do not report
individual contacts?
--
Dmitry
>
> Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
>
> 1. Removing ", and is only used for legacy hardware";
> 2. Adding "Or the number of contacts inside the bounding rectangle is
> reported if hardware provides the number but not the real contact
> positions" to the end of the paragraph.
You might disagree, but "old" is still somewhat apt in this situation. How would
you suggest we report the number of fingers?
Henrik
On Fri, Dec 10, 2010 at 10:13:06AM -0800, Dmitry Torokhov wrote:
> On Fri, Dec 10, 2010 at 09:55:12AM -0800, Ping Cheng wrote:
> > On Thu, Dec 9, 2010 at 1:22 PM, Henrik Rydberg <[email protected]> wrote:
> > > +
> > > +- The MT_TOOL_ENVELOPE type is used to indicate that the contact position
> > > +is not well-defined, and is only used for legacy hardware. The real contact
> > > +positions are to be found within the bounding rectangle formed by the
> > > +envelope contact positions.
> >
> > Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
> >
> > 1. Removing ", and is only used for legacy hardware";
> > 2. Adding "Or the number of contacts inside the bounding rectangle is
> > reported if hardware provides the number but not the real contact
> > positions" to the end of the paragraph.
>
> Are you saying that there is upcoming hardware models that do not report
> individual contacts?
>
Anyway, if we plot the evolution of hardware:
ST -> ST + #fingers -> Envelope -> Full MT
I think we can rigthfully say that at this time all hardware that is not
full MT is legacy technology...
--
Dmitry
On Fri, Dec 10, 2010 at 07:13:05PM +0100, Henrik Rydberg wrote:
> >
>
> > Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
> >
> > 1. Removing ", and is only used for legacy hardware";
> > 2. Adding "Or the number of contacts inside the bounding rectangle is
> > reported if hardware provides the number but not the real contact
> > positions" to the end of the paragraph.
>
>
> You might disagree, but "old" is still somewhat apt in this situation. How would
> you suggest we report the number of fingers?
>
BTN_TOOL_xxxTAP I guess...
--
Dmitry
On Fri, Dec 10, 2010 at 10:13 AM, Henrik Rydberg <[email protected]> wrote:
>
>> Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
>>
>> 1. Removing ", and is only used for legacy hardware";
>> 2. Adding "Or the number of contacts inside the bounding rectangle is
>> reported if hardware provides the number but not the real contact
>> positions" to the end of the paragraph.
>
> You might disagree, but "old" is still somewhat apt in this situation.
It's ok if we say the new type was inspired by legacy hardware. But
saying that it "is only used for legacy hardware" closes the door for
future development. That's not what we are trying to do, right?
> How would you suggest we report the number of fingers?
I guess if we want to make it generic, we could have something like
ABS_MT_NUM_CONTACTS to go with MT_TOOL_ENVELOPE. Clients, such as
synaptics touchpads, that only care about the number of contacts
inside the envelope don't need to process the contact positions even
when they are reported. This also resolve the potential that
BTN_TOOL_QUADTAP is not enough to tell us how many contacts are on the
surface.
Maybe we should also tell the clients whether they are going to get
the contact positions or not.
Ping
On 12/10/2010 08:00 PM, Ping Cheng wrote:
> On Fri, Dec 10, 2010 at 10:13 AM, Henrik Rydberg <[email protected]> wrote:
>>
>>> Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
>>>
>>> 1. Removing ", and is only used for legacy hardware";
>>> 2. Adding "Or the number of contacts inside the bounding rectangle is
>>> reported if hardware provides the number but not the real contact
>>> positions" to the end of the paragraph.
>>
>> You might disagree, but "old" is still somewhat apt in this situation.
>
> It's ok if we say the new type was inspired by legacy hardware. But
> saying that it "is only used for legacy hardware" closes the door for
> future development. That's not what we are trying to do, right?
Well, in a sense we are. I would agree that data aiming to provide gestures as a
2D transformation matrix can be handled quite well with two tracked points and a
finger count. However, a multitouch interface where users manipulate different
objects on the screen simultaneously is a different story.
>
>> How would you suggest we report the number of fingers?
>
> I guess if we want to make it generic, we could have something like
> ABS_MT_NUM_CONTACTS to go with MT_TOOL_ENVELOPE. Clients, such as
> synaptics touchpads, that only care about the number of contacts
> inside the envelope don't need to process the contact positions even
> when they are reported. This also resolve the potential that
> BTN_TOOL_QUADTAP is not enough to tell us how many contacts are on the
> surface.
I really would like to avoid adding a new way to solve an old problem, in
particular given the statement above. Adding something like BTN_TOOL_QUINTAP
would hurt a little bit, but not nearly as much.
>
> Maybe we should also tell the clients whether they are going to get
> the contact positions or not.
I may not understand what you mean here, but if you are referring to an up-front
declaration of what MT_TOOL types are to be expected, we did discuss this
before, without any conclusion. Perhaps it is relevant to outline why this would
be important.
Thanks,
Henrik
On Fri, Dec 10, 2010 at 12:01 PM, Henrik Rydberg <[email protected]> wrote:
> On 12/10/2010 08:00 PM, Ping Cheng wrote:
>
>> On Fri, Dec 10, 2010 at 10:13 AM, Henrik Rydberg <[email protected]> wrote:
>>>
>>>> Can we make MT_TOOL_ENVELOPE cover a bit more cases by:
>>>>
>>>> 1. Removing ", and is only used for legacy hardware";
>>>> 2. Adding "Or the number of contacts inside the bounding rectangle is
>>>> reported if hardware provides the number but not the real contact
>>>> positions" to the end of the paragraph.
>>>
>>> You might disagree, but "old" is still somewhat apt in this situation.
>>
>> It's ok if we say the new type was inspired by legacy hardware. But
>> saying that it "is only used for legacy hardware" closes the door for
>> future development. That's not what we are trying to do, right?
>
>
> Well, in a sense we are. I would agree that data aiming to provide gestures as a
> 2D transformation matrix can be handled quite well with two tracked points and a
> finger count. However, a multitouch interface where users manipulate different
> objects on the screen simultaneously is a different story.
>
>>
>>> How would you suggest we report the number of fingers?
>>
>> I guess if we want to make it generic, we could have something like
>> ABS_MT_NUM_CONTACTS to go with MT_TOOL_ENVELOPE. Clients, such as
>> synaptics touchpads, that only care about the number of contacts
>> inside the envelope don't need to process the contact positions even
>> when they are reported. This also resolve the potential that
>> BTN_TOOL_QUADTAP is not enough to tell us how many contacts are on the
>> surface.
>
>
> I really would like to avoid adding a new way to solve an old problem, in
> particular given the statement above. Adding something like BTN_TOOL_QUINTAP
> would hurt a little bit, but not nearly as much.
If we plan to add BTN_TOOL_QUINTAP, you can ignore my previous comments.
>> Maybe we should also tell the clients whether they are going to get
>> the contact positions or not.
>
>
> I may not understand what you mean here, but if you are referring to an up-front
> declaration of what MT_TOOL types are to be expected, we did discuss this
> before, without any conclusion. Perhaps it is relevant to outline why this would
> be important.
With BTN_TOOL_QUINTAP, this question can be ignored too.
Thank you.
Ping