wl_tablet draft v2

Sat Aug 2 12:31:19 PDT 2014

I'm sorry I took so long to reply to this! I only just found this e-mail
while I was cleaning my inbox up.

On Wed, 2014-07-30 at 17:33 -0700, Jason Gerecke wrote:
> On Tue, Jul 29, 2014 at 12:44 PM, Lyude <thatslyude at gmail.com> wrote:
> > I'm more then willing to add something to get the resolution
> > information, it wouldn't be too difficult to implement. I think I'm
> > missing or forgetting something here though; why wouldn't we be able to
> > get an actual value in degrees from the normalized values we're getting
> > from the compositor? The value should be mapped from (-65535.0) -
> > 65535.0 by the compositor (libinput is the portion that maps it from
> > (-1.0) - 1.0), couldn't we just map that to 0-180°? I would have thought
> > the max value tilt value on a tool should always be equal to 180°, and
> > the minimum 0°.
> >
> It is my understanding that libinput normalizes the values so that the
> minimum tilt => -1.0 and maximum tilt => +1.0. This data is then
> up-scaled by the compositor so that -1.0 => 65535 and +1.0 => +65535.
> This alone does not provide enough information to an application to
> recover the physical angle. One tablet may have a maximum tilt from
> vertical of 45°, another 60°, and yet another 90°. In each case
> maximum tilt would be represented by +1.0 or +65535, but there's no
> way an application can figure out how many degrees that corresponds
> to.
Okay, I had assumed that all tablets just provided values between 0° and
180°.

> One solution -- as you suggest -- is to have libinput/Wayland define a
> unit system and send what I call "canonicalized" instead of
> "normalized" data. You could define that in libinput -1.0 == 0° and
> +1.0 == 180°; in Wayland -65535 == 0° and +65535 == 180°. In this
> case, reports of 0.50/0.67/1.0 and 32768/43690/65535 would be sent
> when my hypothetical tablets above were at maximum tilt. As long as
> the correspondences were documented, a programmer would have enough
> information to convert the values to whatever values they want.
> 
> Of course, the unit system you define for your canonical data is
> arbitrary, as you point out:
> 
> > Also, since we're talking about getting the value in degrees, it might
> > be worth it just to have the Wayland protocol return the values in
> > degrees by default to save some time for the clients.
> >
> 
> This is one of the downsides of canonical data. There's always someone
> out there who disagrees on units and so needs to perform a conversion.
> Degrees would make things easy for Qt and could be expressed directly
> in Wayland's 24.8 fixed-point format with a fair amount of precision.
> Radians are used natively by all the trigonometric functions, are the
> unit of choice for Android, and are the front-runner in designing
> Enlightenment's pen API. The "half-turn" is an uncommon units, but
> it's what GTK+ applications like GIMP and Inkscape assume they've been
> handed.
> 
> There are other reasons I'm not a big fan of passing around data in
> canonical forms as well (can't send data from devices that don't
> advertise a resolution, inconsistent API, doesn't really cut down on
> the amount of data that needs to be exposed, etc.). As an alternative
> to the canonical route, you can leave the data normalized but provide
> a function that returns a scale factor defining what +1.0 (or +65535)
> means in physical units. Whatever program receives the value /may/ do
> a conversion if they wish, or can leave the value normalized for
> others further down the line.
> 
> I wouldn't have libinput use degrees, but it might make some sense for
> Wayland. The downsides probably don't outweigh the ugliness involved
> with shuttling normalized data across the wire*.
I actually think using degrees might be a good idea if we have the
guarantee that they're accurate enough most of the time. To be honest,
the more that I think about it, I think it would be better to try to
avoid the use of normalized values when we can convert them to something
better. And, like you said, the number of clients that want the value in
something other than degrees is in the minority. Of course this brings
up the issue you just mentioned though: not all tablets report
resolution information, and this has the potential of limiting the API.

So, I'm guessing there's two situations where we'd have a device that
can't advertise it's resolution:
     1. A device that can report it's resolution, but for whatever
        reason the kernel driver doesn't have support for this feature.
     2. A device that is physically incapable of reporting resolution
        information
For #1, I think we'd be better off not worrying about this. In
situations where we have a kernel driver for a device that doesn't
forward it's resolution, I think the best solution would be to fix the
kernel driver instead of trying to work around it.
For #2, I think that even if the device doesn't report a resolution,
that we could still figure out a resolution for the device just by
measuring it by hand. E.g., measure the max/min angle of the tablet,
come up with a scale for that to translate the raw values from the
tablet into degrees, and then have the kernel advertise that as the
resolution. Again though, this assumes that the device's tilt values are
reliable.

So, for devices that we don't have any resolution information for yet,
we could report a range of 0-180° and add a flag to the
wl_tablet_manager::device_added event that tells the client that we
don't have any resolution information for this device, and that the
range we're reporting for the device may not be accurate.

So, with each tablet we would specify the actual maximum and minimum it
can report in terms of degrees. Because we're reporting this, anyone who
needs the value in a normalized form would easily be able to calculate
it, and we'd still be able to report the values in degrees by default.

> 
> * Seriously, can anyone explain why the wire protocol doesn't have a
> floating-point type? Practically every system supports the 32-bit
> IEEE754 single-precision binary format, and to for those that don't,
> we can pull a play from the fixed-point playbook and define a
> "wl_single_t" and associated conversion functions (which would just do
> a cast unless you happen to be on one of those weird architectures).
> Should I just make a patch for this already? :P
I've asked Peter about this, and he's told me the reasons but I can't
remember them off the top of my head.

Since we're sticking to fixed-width integers in the protocol, I think we
should add something like "wl_fraction_t", where we have 30 bits
dedicated to the fractional portion and 2 bits dedicated to the integer
portion, allowing us to represent the values -1.0 to 1.0 with
fixed-width numbers. This would be kind of a big change though, but it
would mean we wouldn't have to stick to values like (-65535)-65535.

Cheers,
	Lyude
> ---
> 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....
> 
> 
> > On Tue, 2014-07-29 at 10:07 -0700, Jason Gerecke wrote:
> >> On Mon, Jul 28, 2014 at 10:54 AM, Bill Spitzak <spitzak at gmail.com> wrote:
> >> > On 07/28/2014 09:41 AM, Jason Gerecke wrote:
> >> >
> >> >> Normalizing the data is fine, but the resolution data needs to be
> >> >> available somewhere as well. The GTK+ API doesn't require anything
> >> >> more than the former, but Qt requires that there be some way to turn
> >> >> the normalized value into degrees. For libinput this could be
> >> >> something as simple as a "get_axis_resolution" function that returns
> >> >> the number of radians (or mm, or newtons, or some other physical unit)
> >> >> that the normalized value +1.0 corresponds to. I suppose Wayland would
> >> >> let make the value available through the wl_tablet_manager somehow.
> >> >
> >> >
> >> > Are you sure about these terms? I would think "resolution" should be used to
> >> > identify how many discreet positions the device can obtain. What you are
> >> > asking for I think would be better to call a "range" or "scale".
> >> >
> >>
> >> Yeah, good catch. Looks like I'm getting imprecise with my terminology *wince*
> >>
> >> I think I prefer "scale" over "range" personally, since it's only a
> >> single logical-to-physical scaling factor (not the physical minimum
> >> and maximum extents of the axis).
> >>
> >> 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....
> >> _______________________________________________
> >> wayland-devel mailing list
> >> wayland-devel at lists.freedesktop.org
> >> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
> >

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140802/d7b661be/attachment.sig>