Input: wacom - Add POINTER and DIRECT device properties

Adds INPUT_PROP_POINTER or INPUT_PROP_DIRECT as necessary to the hardware supported by the Wacom driver. The DIRECT property is assigned to devices with an embedded screen (i.e. touchscreens and display tablets). The POINTER property is assigned to those without embedded screens.

Signed-off-by Jason Gerecke <[email protected]>

---
 drivers/hid/hid-wacom.c                 |    2 ++ drivers/input/tablet/wacom_wac.c        |   25 ++++++++++++++++++++++++- drivers/input/touchscreen/wacom_w8001.c |    2 ++

 3 files changed, 28 insertions(+), 1 deletions(-)

drivers/hid/hid-wacom.c +2 -0

index 0688832..5b9267d 100644
@@ -383,6 +383,8 @@ move_on:
        hidinput = list_entry(hdev->inputs.next, struct hid_input, list);
        input = hidinput->input;
 
+       __set_bit(INPUT_PROP_POINTER, input->propbit);
+
        /* Basics */
        input->evbit[0] |= BIT(EV_KEY) | BIT(EV_ABS) | BIT(EV_REL);
 

drivers/input/tablet/wacom_wac.c +2 -0

index 87b0e0d..a28d48c 100644
@@ -1098,6 +1098,8 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,
                __set_bit(BTN_TOOL_MOUSE, input_dev->keybit);
                __set_bit(BTN_STYLUS, input_dev->keybit);
                __set_bit(BTN_STYLUS2, input_dev->keybit);
+
+               __set_bit(INPUT_PROP_POINTER, input_dev->propbit);
                break;
 

       case WACOM_21UX2:

drivers/input/tablet/wacom_wac.c +3 -0

@@ -1126,6 +1128,9 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,
                }
 
                input_set_abs_params(input_dev, ABS_Z, -900, 899, 0, 0);
+
+               __set_bit(INPUT_PROP_DIRECT, input_dev->propbit);
+
                wacom_setup_cintiq(wacom_wac);
                break;
 

@@ -1150,6 +1155,8 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,
                /* fall through */
 

       case INTUOS:
+               __set_bit(INPUT_PROP_POINTER, input_dev->propbit); +
               wacom_setup_intuos(wacom_wac);
               break;

drivers/input/tablet/wacom_wac.c +2 -0

@@ -1165,6 +1172,8 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,
 
                input_set_abs_params(input_dev, ABS_Z, -900, 899, 0, 0);
                wacom_setup_intuos(wacom_wac);
+
+               __set_bit(INPUT_PROP_POINTER, input_dev->propbit);
                break;
 

       case TABLETPC2FG:

drivers/input/tablet/wacom_wac.c +0 -0

@@ -1183,14 +1192,24 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,

       case TABLETPC:
               __clear_bit(ABS_MISC, input_dev->absbit);

+               __set_bit(INPUT_PROP_DIRECT, input_dev->propbit); +
               if (features->device_type != BTN_TOOL_PEN) break;  /* no need to process stylus stuff */

               /* fall through */

       case PL:
-       case PTU:
       case DTU:
+               __set_bit(BTN_TOOL_PEN, input_dev->keybit);
+               __set_bit(BTN_TOOL_RUBBER, input_dev->keybit);
+               __set_bit(BTN_STYLUS, input_dev->keybit);
+               __set_bit(BTN_STYLUS2, input_dev->keybit);

drivers/input/tablet/wacom_wac.c +5 -0

+
+               __set_bit(INPUT_PROP_DIRECT, input_dev->propbit);
+               break;
+
+       case PTU:

               __set_bit(BTN_STYLUS2, input_dev->keybit); /* fall through */

drivers/input/tablet/wacom_wac.c +2 -0

@@ -1198,11 +1217,15 @@ void wacom_setup_input_capabilities(struct input_dev *input_dev,
                __set_bit(BTN_TOOL_PEN, input_dev->keybit);
                __set_bit(BTN_TOOL_RUBBER, input_dev->keybit);
                __set_bit(BTN_STYLUS, input_dev->keybit);
+
+               __set_bit(INPUT_PROP_POINTER, input_dev->propbit);
                break;
 

       case BAMBOO_PT:
               __clear_bit(ABS_MISC, input_dev->absbit);

+               __set_bit(INPUT_PROP_POINTER, input_dev->propbit); +
               if (features->device_type == BTN_TOOL_DOUBLETAP) { __set_bit(BTN_LEFT, input_dev->keybit); __set_bit(BTN_FORWARD, input_dev->keybit);

drivers/input/touchscreen/wacom_w8001.c +2 -1

index c14412e..9941d39 100644
@@ -383,6 +383,8 @@ static int w8001_setup(struct w8001 *w8001)
        dev->evbit[0] = BIT_MASK(EV_KEY) | BIT_MASK(EV_ABS);
        strlcat(w8001->name, "Wacom Serial", sizeof(w8001->name));
 
+       __set_bit(INPUT_PROP_DIRECT, dev->propbit);
+
        /* penabled? */
        error = w8001_command(w8001, W8001_CMD_QUERY, true);
        if (!error) {
--

1.7.6

Adds INPUT_PROP_POINTER or INPUT_PROP_DIRECT as necessary to the hardware supported by the Wacom driver. The DIRECT property is assigned to devices with an embedded screen (i.e. touchscreens and display tablets). The POINTER property is assigned to those without embedded screens.

Signed-off-by Jason Gerecke <[email protected]>

---

The question is then what behavior should be assigned to
a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

Hi Jason,

Quoted 8 lines

Adds INPUT_PROP_POINTER or INPUT_PROP_DIRECT as necessary to the hardware supported by the Wacom driver. The DIRECT property is assigned to devices with an embedded screen (i.e. touchscreens and display tablets). The POINTER property is assigned to those without embedded screens.

Signed-off-by Jason Gerecke <[email protected]>

---

According to the discussion leading up to the properties interface
(https://lkml.org/lkml/2010/12/15/263), a tablet is a direct pointer device, as opposed to a touchpad, which is an indirect pointer device. The distinction determines the direction of two-finger scroll, for instance. The question is then what behavior should be assigned to a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

Quoted 11 lines · Henrik Rydberg

Hi Jason,

Quoted 8 lines

Adds INPUT_PROP_POINTER or INPUT_PROP_DIRECT as necessary to the hardware supported by the Wacom driver. The DIRECT property is assigned to devices with an embedded screen (i.e. touchscreens and display tablets). The POINTER property is assigned to those without embedded screens.

Signed-off-by Jason Gerecke <[email protected]>

---

Quoted 7 lines

According to the discussion leading up to the properties interface
(https://lkml.org/lkml/2010/12/15/263), a tablet is a direct pointer device, as opposed to a touchpad, which is an indirect pointer device. The distinction determines the direction of two-finger scroll, for instance. The question is then what behavior should be assigned to a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

Here are all the possible combinations based on my understanding of their intended usage.

 * Touch interface without screen should have POINTER only to indicate pointer needed and to treat absolute coordinates as relative movement.  Relative movement is product's default behavior as documented in its own manual and what I think should be advertised by default.
 * Pen interface without screen should have both POINTER and DIRECT to indicate pointer needed and to treat absolute coordinates as absolute movement.

 * Touch interfaces with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
 * Pen interface with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
* A Pen+Touch touchscreen (only the wacom_w8001.c), should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.

Assuming we all agree on those combination, then in the patch the Graphire and Intuos tablets are missing a DIRECT, the touchscreens are correct, and the Bamboo's need to add DIRECT for the PEN interface only.

Quoted 12 lines · Chris Bagwell

Quoted 11 lines · Henrik Rydberg

Hi Jason,

Quoted 8 lines

Adds INPUT_PROP_POINTER or INPUT_PROP_DIRECT as necessary to the hardware supported by the Wacom driver. The DIRECT property is assigned to devices with an embedded screen (i.e. touchscreens and display tablets). The POINTER property is assigned to those without embedded screens.

Signed-off-by Jason Gerecke <[email protected]>

---

Quoted 7 lines

Quoted 7 lines

According to the discussion leading up to the properties interface
(https://lkml.org/lkml/2010/12/15/263), a tablet is a direct pointer device, as opposed to a touchpad, which is an indirect pointer device. The distinction determines the direction of two-finger scroll, for instance. The question is then what behavior should be assigned to a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

We have discussed and debated the above before the patch was posted.

As Ikbel pointed out, a standalone tablet can be DIRECT or INDIRECT, depending on how it is used. So, it is more a property that is decided by the client than by the kernel driver.

Quoted 4 lines

Here are all the possible combinations based on my understanding of their intended usage.

Quoted 8 lines

 * Touch interface without screen should have POINTER only to indicate pointer needed and to treat absolute coordinates as relative movement.  Relative movement is product's default behavior as documented in its own manual and what I think should be advertised by default.
 * Pen interface without screen should have both POINTER and DIRECT to indicate pointer needed and to treat absolute coordinates as absolute movement.

Reporting it as DIRECT indicates it can only be used as DIRECT. We don't want client to make that assumption. User-land clients can distinguish a touch POINTER from a pen POINTER by the tool types.

Quoted 9 lines

 * Touch interfaces with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
 * Pen interface with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
* A Pen+Touch touchscreen (only the wacom_w8001.c), should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.

Quoted 4 lines

Assuming we all agree on those combination, then in the patch the Graphire and Intuos tablets are missing a DIRECT, the touchscreens are correct, and the Bamboo's need to add DIRECT for the PEN interface only.

I agree with all the other assumptions except this one.

Ping

 * Touch interface without screen should have POINTER only to indicate pointer needed and to treat absolute coordinates as relative movement.  Relative movement is product's default behavior as documented in its own manual and what I think should be advertised by default.

 * Pen interface without screen should have both POINTER and DIRECT to indicate pointer needed and to treat absolute coordinates as absolute movement.

 * Touch interfaces with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
 * Pen interface with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
* A Pen+Touch touchscreen (only the wacom_w8001.c), should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.

Assuming we all agree on those combination, then in the patch the Graphire and Intuos tablets are missing a DIRECT, the touchscreens are correct, and the Bamboo's need to add DIRECT for the PEN interface only.

Quoted 3 lines

 * Pen interface without screen should have both POINTER and DIRECT to indicate pointer needed and to treat absolute coordinates as absolute movement.

No. DIRECT should not be set because the Pen is not directly touching the objects on a screen. The motions must still be translated through some indirect means (a mapping function) onto the plane of the screen.

Therefore should only specify POINTER.

Quoted 7 lines

 * Touch interfaces with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
 * Pen interface with screen should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.
* A Pen+Touch touchscreen (only the wacom_w8001.c), should have DIRECT only to indicate no pointer displayed and absolute coordinates as absolute movement.

Yes, but not for this reason. Touch interfaces with screen should have DIRECT to indicate that touches are directly upon objects on the screen.

It happens that the absolute coordinates of a tablet are usually mapped 1-1 with the screen, but that's not what is meant by a direct input device. It's the usage that matters, not the mapping function itself.

Note that a tablet's mapping function need not be precisely 1-1. It could be constrained to part of a window on the display, or it could be rotated or skewed with respect to the display. This is a fundamental difference between direct and indirect input devices. The mapping function for a direct input devices must be a natural mapping based on what is actually seen and directly touches. The mapping function for an indirect input device can be almost anything because a pointer is being used to provide visual feedback so it is not constrained by the physical position of objects on screen.

Quoted 4 lines

Assuming we all agree on those combination, then in the patch the Graphire and Intuos tablets are missing a DIRECT, the touchscreens are correct, and the Bamboo's need to add DIRECT for the PEN interface only.

I disagree.

A touchscreen is DIRECT.
A tablet or trackpad is INDIRECT (and POINTER).

Further absolute/relative distinctions need to be made by tool. Finger / mouse on tablet uses relative motion. Pen uses absolute motion. Essentially the tool types qualify the mapping function used by indirect devices.

Hi,

Quoted 4 lines · Henrik Rydberg

. The question is then what behavior should be assigned to a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

Any large tablet without an embedded screen can be used in the 2 different ways:
1. The projection on top of it so it becomes a direct device.
(this case is also used when you project 3d 120hz on top of multitouch
devices: iMuts)

2. Simple indirect device, even if it's large:
http://10gui.com/video/

Quoted 8 lines · Mohamed Ikbel Boulabiar

Hi,

Quoted 4 lines · Henrik Rydberg

. The question is then what behavior should be assigned to a large tablet without an embedded screen. It should have POINTER set for sure, but should it also have DIRECT set?

Quoted 7 lines

Any large tablet without an embedded screen can be used in the 2 different ways:
1. The projection on top of it so it becomes a direct device.
(this case is also used when you project 3d 120hz on top of multitouch
devices: iMuts)

2. Simple indirect device, even if it's large:
http://10gui.com/video/

Two-finger scroll is actually used in a direct manner in that video. (Which, btw, does display some fresh concepts. :-))

I think the bottom line is that even if the "directness" of a device is configurable, it still needs to have a default. Moreover, the notion of kernel mode settings could be applicable here too.

Quoted 3 lines

I think the bottom line is that even if the "directness" of a device is configurable, it still needs to have a default. Moreover, the notion of kernel mode settings could be applicable here too.

Talking about default mode, there are cases that the mode is decided by the tools running on the device/tablet, instead of the tablet itself.

Take Wacom's Intuos and Graphire series for example, those tablets support both styli and mice. For styli, the default is absolute mode; while for mice, it is relative. So, only valid property the tablet can tell the user-land is: I am a tablet, i.e., not a touchscreen. Clients have to check the tool types to set the default mode to relative (BTN_TOOL_MOUSE/LENS) or absolute (BTN_TOOL_PEN/AIRBRUSH/RUBBER...).

Quoted 8 lines

Quoted 3 lines

I think the bottom line is that even if the "directness" of a device is configurable, it still needs to have a default. Moreover, the notion of kernel mode settings could be applicable here too.

Talking about default mode, there are cases that the mode is decided by the tools running on the device/tablet, instead of the tablet itself.

Quoted 6 lines

Take Wacom's Intuos and Graphire series for example, those tablets support both styli and mice. For styli, the default is absolute mode; while for mice, it is relative. So, only valid property the tablet can tell the user-land is: I am a tablet, i.e., not a touchscreen. Clients have to check the tool types to set the default mode to relative (BTN_TOOL_MOUSE/LENS) or absolute (BTN_TOOL_PEN/AIRBRUSH/RUBBER...).

And those modes can be determined using the available axes. However, when all axes are the same, a statement like "I am a tablet" does not exist. In that case, distinguishing between touchscreen, touchpad and tablet becomes a question of interpreting the properties. Such a distinction cannot be achieved using a single bit of information, and that was never the intention.

Quoted 3 lines

Reporting it as DIRECT indicates it can only be used as DIRECT. We don't want client to make that assumption. User-land clients can distinguish a touch POINTER from a pen POINTER by the tool types.

I see your logic now and patch does follow that logic.

I can actually buy into that although it seems to make the need for both POINTER and DIRECT redundant. Touchscreen = DIRECT while Tablet (pen, touch, or both) = POINTER. No overlap.

Quoted 7 lines

Quoted 6 lines

Take Wacom's Intuos and Graphire series for example, those tablets support both styli and mice. For styli, the default is absolute mode; while for mice, it is relative. So, only valid property the tablet can tell the user-land is: I am a tablet, i.e., not a touchscreen. Clients have to check the tool types to set the default mode to relative (BTN_TOOL_MOUSE/LENS) or absolute (BTN_TOOL_PEN/AIRBRUSH/RUBBER...).

Quoted 7 lines

And those modes can be determined using the available axes. However, when all axes are the same, a statement like "I am a tablet" does not exist. In that case, distinguishing between touchscreen, touchpad and tablet becomes a question of interpreting the properties. Such a distinction cannot be achieved using a single bit of information, and that was never the intention.

It is certainly true that you cannot separate out the different cases with a single bit. The more properties and hints we can expose to userspace the better. However, at the device level, there's only so much information we *can* expose. We know if its a direct input device or not. We don't know if its relative or absolute, since that depends on the tool in use at any given moment.

From these definitions, it follows that a device could well be both

To be honest, I'm not sure why we need to further disambiguate touchpads and tablets (though I'd be interested in finding out). From what I can tell, the difference between a touchpad and a tablet is in the tools they use; identical tools (i.e. BTN_TOOL_FINGER) should have identical absoluteness. The absoluteness of tool would depends on what it is (BTN_TOOL_FINGER is relative, BTN_TOOL_PEN is absolute) and if the underlying device is a direct input device (if it is, all tools are absolute) -- not on some arbitrarily distinction between "touchpad" and "tablet".

Hi Jason,

Quoted 14 lines

Quoted 7 lines

Quoted 6 lines

Take Wacom's Intuos and Graphire series for example, those tablets support both styli and mice. For styli, the default is absolute mode; while for mice, it is relative. So, only valid property the tablet can tell the user-land is: I am a tablet, i.e., not a touchscreen. Clients have to check the tool types to set the default mode to relative (BTN_TOOL_MOUSE/LENS) or absolute (BTN_TOOL_PEN/AIRBRUSH/RUBBER...).

Quoted 7 lines

And those modes can be determined using the available axes. However, when all axes are the same, a statement like "I am a tablet" does not exist. In that case, distinguishing between touchscreen, touchpad and tablet becomes a question of interpreting the properties. Such a distinction cannot be achieved using a single bit of information, and that was never the intention.

Quoted 6 lines

It is certainly true that you cannot separate out the different cases with a single bit. The more properties and hints we can expose to userspace the better. However, at the device level, there's only so much information we *can* expose. We know if its a direct input device or not. We don't know if its relative or absolute, since that depends on the tool in use at any given moment.

It seems the various arguments we have seen in this thread are all logical and well founded, but they originate in different assumptions about the semantics of POINTER and DIRECT. Such a debate does obviously not satisfy everyone.

The original intention of the properties are these:

POINTER - The device needs a visual guide in order to be useful. In most cirumstances, this is equivalent to not having a screen directly beneath the surface.

DIRECT - The input device is to be used as if it was overlaying a sreen. It could be separate from the screen, but the expected behavior should be the same.

From these definitions, it follows that a device could well be both POINTER and DIRECT. For instance, a multitouch tablet designed to replace the keyboard would fall into this category.

I think these are the clearest definitions I've seen of these properties. It would be good to get them documented in Documentation/input. Henrik, would you be able to do this?

Quoted 3 lines · Chase Douglas

I think these are the clearest definitions I've seen of these properties. It would be good to get them documented in Documentation/input. Henrik, would you be able to do this?

Agreed, but I feel we also need some clarity around the desired interpretations of different tools in relation to direct / indirect motion and these bits.

For example:

BTN_TOOL_FINGER / MT_FINGER:
- Positions are absolute is INPUT_PROP_DIRECT, or relative otherwise.
- Shows a pointer only if INPUT_PROP_POINTER is set.

(IMHO, relative motion should be preferred for touch pads that are not physically coupled to a particular display. Trackpad-like vs. tablet-like behavior, especially if "hovering" is not supported or if the touch pad is small.)

BTN_TOOL_PEN / BTN_TOOL_BRUSH / MT_PEN:
- Positions are always one-to-one with screen coordinates regardless of INPUT_PROP_DIRECT. If INPUT_PROP_DIRECT is set then we can take it as a stronger indication of the pen being coupled to a particular display (rather than spanning all displays or being bound to a specific window, perhaps).

- Shows a pointer only if INPUT_PROP_POINTER is set.

BTN_TOOL_MOUSE / BTN_TOOL_LENS:
- Positions are always relative, regardless of INPUT_PROP_DIRECT.
- Shows a pointer, regardless of INPUT_PROP_POINTER.

We should also define heuristics for legacy devices that don't set either INPUT_PROP_DIRECT or INPUT_PROP_POINTER.

To condense all of the above, we can generalize the rules to:

* INPUT_PROP_DIRECT only has meaning for BTN_TOOL_FINGER etc.
* INPUT_PROP_POINTER only has meaning for BTN_TOOL_PEN / BTN_TOOL_BRUSH etc.

Quoted 2 lines

We should also define heuristics for legacy devices that don't set either INPUT_PROP_DIRECT or INPUT_PROP_POINTER.

The above generalization should take care of this.