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

[Peter Hutterer]

On Tue, Dec 08, 2015 at 05:37:52PM -0800, Jason Gerecke wrote:
> 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.

I'm fine with that,the current BTN_TOUCH handling already gives us that on
those tablets where it's set by the kernel based on the pressure values.
Making this inside libinput should be a relatively easy change. but it
leaves the question open of whether we should have a non-zero pressure value
before BTN_TOUCH.

making distance/pressure exclusive is unaffected by that, so it mostly comes
down to whether we want to allow this sequence:

distance X pressure 0
distance 0 pressure X
distance 0 pressure Y
tip down
distance 0 pressure Z

Other than being 'not nice' I don't see any immediate drawbacks, the average
client will likely use the tip down as trigger to start interpreting
things, and those clients that care about super-fine touches can ignore the
tip event.

Cheers,
   Peter

> >> 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.