[PATCH libinput 6/8] tablet: support tool-specific pressure offsets

[Jason Gerecke]

On Sun, Dec 6, 2015 at 8:22 PM, Peter Hutterer <peter.hutterer at who-t.net> wrote:
> On Thu, Dec 03, 2015 at 07:57:30PM -0800, Jason Gerecke wrote:
>> On Wed, Dec 2, 2015 at 5:03 PM, Peter Hutterer <peter.hutterer at who-t.net> wrote:
>> > On Wed, Dec 02, 2015 at 04:21:56PM -0800, Jason Gerecke wrote:
>> >> On Tue, Dec 1, 2015 at 5:46 PM, Peter Hutterer <peter.hutterer at who-t.net> wrote:
>> >> > If a tool wears out, it may have a pre-loaded pressure offset. In that case,
>> >> > even when the tool is not physically in contact with the tablet surface it
>> >> > will send pressure events.
>> >> >
>> >> > The X.Org wacom driver has automatic pressure preload detection, but it is
>> >> > unreliable. A quick tap can trigger the detection, making the pen unusable
>> >> > (see xf86-input-wacom-0.23.0-43-g10cc765).
>> >> >
>> >> > Since this is a hardware-specific property, add a new udev property with the
>> >> > prefix TABLET_TOOL_PRESSURE_OFFSET_ and let it be set system-wide through the
>> >> > hwdb or some other process. Use the value of this property to offset any
>> >> > incoming pressure values and scale into the original normalized axis range.
>> >> >
>> >> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
>> >>
>> >> I've been asked by Ping (who is going to be OOO for the next few days)
>> >> to try and express some of her concerns about how libinput will handle
>> >> pen pressure. The two of us have had some lengthy discussions, and
>> >> though I'm not sure I agree on all points, I'll try to argue them as
>> >> best I can.
>> >>
>> >> The idea behind the X driver's automatic preload detection was to
>> >> provide a way to handle the pen-specific pressure offsets without
>> >> requiring the user to configure or calibrate anything. The minimum
>> >> pressure seen from a pen is a fairly reliable measure of the offset,
>> >> and the X driver attempts to measure this as the pen hovers in
>> >> proximity. This works well in most circumstances, but obviously fails
>> >> if the pen is "stabbed" at the tablet so quickly that it comes into
>> >> contact before it can report an unloaded pressure value. This kind of
>> >> wanton hardware abuse isn't something we encourage ;)
>> >>
>> >> Making the pressure offset a configuration option like you propose
>> >> here doesn't suffer from mis-detection, but does require the user to
>> >> periodically run a tool to update the UDEV HWDB. Updates to the DB
>> >> won't take immediate effect[1], won't propagate across systems[2], and
>> >> are incapable of distinguishing between tools without a serial number.
>> >
>> > a couple of questions here:
>> > * how common is this pressure preload?
>> > * does it affect all pens or only specific pens?
>> > * is there a maximum observed threshold for this pen preload?
>> >
>> > The last one is specifically: is there a point where we can throw up our
>> > hands and tell the user to just buy a new pen rather than needing automatic
>> > detection *and* the udev property for anything that exceeds that threshold?
>> >
>>
>> Pens which are fresh from the factory or only lightly used (e.g., all
>> the pens in my office...) should have a preload of zero. As time goes
>> on and the pen's pressure transducer starts to wear out (especially if
>> the pen is "abused") the preload will increase. Unfortunately, I don't
>> have any data on how quickly preload accumulates or what ranges of
>> values might be expected in the wild. The X driver logs a warning when
>> the preload exceeds 20% of maximum pressure, but the origin of that
>> particular number is unknown.
>
> that number was simply made up, based on the assumption that if you're
> losing 1/5 of your pressure range (and thus granularity) then it's probably
> time to get a new tool. it's a relatively recent commit, so maybe this is
> more common than expected.
>
>> >> One change that could be made to the automatic method that would make
>> >> it a bit more reliable would be to define a maximum pressure that it
>> >> would consider to be a sane preload. A 'stabbed' pen would almost
>> >> certainly overshoot the ceiling and we could simply assume an
>> >> arbitrary preload of our choosing (zero? the ceiling?). A very light
>> >> 'stab' could still cause issues, but its quite difficult to both move
>> >> the pen quickly enough to enter and exit prox at a high enough speed
>> >> to not get an unloaded pressure reading *and* only lightly come into
>> >> contact with the surface.
>> >
>> > at least on the tablets that do distance we can combine the maximum pressure
>> > threshold with the distance measurement. It's harder to do that on tablets
>> > without distance though.
>> >
>>
>> The distance data is pretty rough and I believe varies based on the
>> environment (since its similar to [but I don't think /quite/ the same
>> as] SNR) but that still might be an interesting idea. If the driver
>> has a reasonable idea of a minimum "safe" distance where the pen is
>> almost certainly not in contact, then it can figure out if the
>> pressure can be interpreted as preload or not.
>
> it'd be great if you can talk to your hw engineers or other driver teams to
> figure out whether we can use this. I don't mind having device-specific
> offsets for this in the hwdb if we can make it work nicely.
>
>> >> A second issue that Ping brought up is the tying of pressure
>> >> information to the "down" state (patch 4). Its possible that a user
>> >> would want to have the maximum possible dynamic range for pressure
>> >> (after accounting for the preload) in a drawing app so that the
>> >> lightest strokes were useful, while simultaneously wanting UI elements
>> >> like buttons and menus to only respond to more deliberate (and
>> >> high-pressure) pen events. In terms of protocol and library, this
>> >> would mean allowing applications to see non-zero pressure values even
>> >> before the pen is "down". If we want to do this, we would have to be
>> >> very deliberate in documenting that the behavior so that programmers
>> >> understand the pressure data is useful and should not be discarded (or
>> >> if absolutely necessary, rescaled so that the click threshold is
>> >> reported as 0 pressure). Right now I don't think any toolkits or
>> >> applications make use of pressure prior to click, though TBH I haven't
>> >> actually checked...
>> >
>> > long-term I want the tip down/up to match a distance 0 and have anything
>> > with distance not send any pressure. The current BTN_TOUCH handling isn't
>> > ideal because it discards lower pressure values, I think we should use a
>> > libinput-internal pressure threshold here and fake the BTN_TOUCH based on
>> > that. And the range between max(threshold, preload)-axis_max will then be
>> > mapped into the normalised range.
>> >
>> > So the logic will likely be tilted towards the pressure, with finer-grained
>> > distance measuring:
>> > * if the distance > threshold and pressure != 0 -> pressure preload
>> > * if the distance < other threshold and pressure > preload -> distance 0
>> > this makes BTN_TOUCH relatively obsolete, and also requires a minimum
>> > distance threshold. The big drawback is that the stylus behaviour will
>> > change over time, but hopefully this is in such a subtle measurement that it
>> > won't be perceived by the user.
>> >
>> > Cheers,
>> >    Peter
>> >
>>
>> I think Ping wants to see BTN_TOUCH used to indicate "intentional"
>> touches, not the slightest contact of the pen with the tablet. I'm not
>> sure if that's the responsibility of libinput or its caller to
>> implement, but I think it could be argued either way. If libinput says
>> that pressure will only be non-zero when the pen is in contact (i.e.,
>> it takes care of preload), then using BTN_TOUCH to signal the same
>> thing is redundant.
>
> BTN_TOUCH is a kernel thing and we're not the only consumers of the API.
> also, the wacom kernel driver has accumulated a number of backwards
> compatibility behaviours that we don't need to re-export in libinput. so
> yeah, BTN_TOUCH is redundant if you have pressure.
>
> There are other tablets that don't provide pressure though, BTN_TOUCH serves
> those tablets (and is the reason we need tip down/up in libinput).
>

I suppose I shouldn't have used the term "BTN_TOUCH" when I'm not
talking about the kernel APIs. What I meant was that the libinput API
could/should use a pressure threshold to provide callers with a notion
of "down" that is more intentional than implied by
TABLET_STYLUS_IN_CONTACT. Hardware which doesn't report pressure would
obviously fall back to assuming that contact implies "down", but
tablets that report contact for very light touches wouldn't be "down"
until a reasonably-high value was seen.

>> It also doesn't make a lot of sense to send
>> BTN_TOUCH for non-zero pressures since as little as 1 gram of force
>> would trigger it. Instead, BTN_TOUCH should only be triggered once the
>> pressure value raises to a reasonably high value, and then latched so
>> that if the pressure varies slightly applications don't see a storm of
>> events that indicate repeated touches when that was not physically the
>> case.
>
> but isn't that exactly what happens?
> if you touch the surface so light that it flickers between 0 and nonzero
> pressure, then the up/down storm is representative of the user's action.
> That is not the case when you have a magic threshold, because you can
> trigger the up/down storm even while holding the stylus down on the tablet.
>
> Cheers,
>    Peter
>

Bill already covered it, but the idea would be to leave the pen in the
"down" state until its pressure drops back to zero. You could
theoretically define a lower threshold at some point other than zero
(to reduce the amount of hysteresis), but isn't strictly necessary.

Jason
---
Now instead of four in the eights place /
you’ve got three, ‘Cause you added one  /
(That is to say, eight) to the two,     /
But you can’t take seven from three,    /
So you look at the sixty-fours....