[PATCH v3 wayland-protocols] Add the tablet protocol

[Jason Gerecke]

On Sun, Jan 31, 2016 at 2:27 PM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> On Fri, Jan 29, 2016 at 11:40:44AM -0800, Jason Gerecke wrote:
>> On Thu, Jan 28, 2016 at 8:32 PM, Peter Hutterer
>> <peter.hutterer at who-t.net> wrote:
>> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
>> > ---
>> > Changes to v2:
>> > - renamed hwserial to hardware_serial
>> > - renamed to hwid event to a hardware_id_wacom. no-one else uses this ID
>> >   type, so having a generic event with a wacom-specific type + enum is
>> >   optimistic. The next company may use a string instead, so it'll be
>> >   non-generic anyway. Might as well rename it to something specific now.
>> > - added slider, rotation and wheel axes
>> > - couple of documentation fixes
>
> [...]
>
>> > +
>> > +    <event name="distance">
>> > +      <description summary="distance change event">
>> > +       Sent whenever the distance axis on a tool changes. The value of this
>> > +       event is normalized to a value between 0 and 65535.
>> > +
>> > +       Note that distance may be nonzero even when a tool is not in logical
>> > +       contact. See the down and up events for more details.
>> > +      </description>
>> > +      <arg name="distance" type="uint" summary="The current distance value"/>
>> > +    </event>
>> > +
>> > +    <event name="tilt">
>> > +      <description summary="tilt change event">
>> > +       Sent whenever one or both of the tilt axes on a tool change. Each tilt
>> > +       value is normalized between -65535 and 65535.
>> > +      </description>
>> > +      <arg name="tilt_x" type="int" summary="The current value of the X tilt axis"/>
>> > +      <arg name="tilt_y" type="int" summary="The current value of the Y tilt axis"/>
>> > +    </event>
>> > +
>> > +    <event name="rotation">
>> > +      <description summary="z-rotation change event">
>> > +       Sent whenever the z-rotation axis on the tool changes. The
>> > +       rotation value is in 0.01 of a degree clockwise from the tool's
>> > +       logical neutral position.
>> > +      </description>
>>
>> From the protocol description: "Any extra axis is normalized, i.e. the
>> client knows the range as specified in the protocol (e.g. [0, 65535]),
>> the granularity however is unknown." This was chosen because we don't
>> always have the necessary information to translate a kernel value for
>> a given device's axis into a physical measurement, but we can always
>> report a normalized value that that gives clients a sense of its
>> relative magnitude.
>
> yeah, we did this for pressure and distance because we know we can't convert
> them into anything useful. rotation I thought was different and libinput
> advertises z-rotation in degrees as well. That means two things:
> * either we commit to degrees and fix it up per-device as needed in libinput
> * admit that we really can't even get degrees out of rotation and change
>   libinput's API to normalize into a [-1, 1] range. If so, we need to do
>   this *now*, I'm about to release it as a stable API.
>
> I am ok with the second option so it's your call really. You have better
> access to the hw. fwiw, adding degrees later if/when the HW gets more
> precise is easy enough.
>

I don't think precision (more correctly, accuracy) is really the issue
at hand. Its more about the difference between qualitative axes like
pressure and distance (where there are basically no information about
the physical values that even minimum and maximum correspond to) and
quantitative axes like position, tilt, and rotation (which have
varying degrees of accuracy but are at least specified to have a
conversion to physical units). Devices based on different technologies
may have different qualitative and quantitative axes, so reporting
normalized data as a least common denominator format can be useful.

I would have expected rotation and tilt to both be reported in the
same format -- either in degrees or normalized. I think both formats
are fine (since its hard for me to imagine either as a
merely-qualitative axis), though there are advantages to using the
normalized format like everything else.

>> We do need to provide a way for clients to translate the normalized
>> values into physical measurements if possible though. I would suggest
>> adding the following event to the tool definition. Several could be
>> sent as part of the initial pre-"done" burst.
>>
>>  <event name="physical_range">
>>    <description summary="tool physical range notification">
>>      This event provides information about the physical range of one
>>      of the axes of the tool. This information can be used to translateIts a little difficult to imagine a merely-qualitative tilt axis
>>      the normalized values (0 to 65535, or -65535 to +65535) axis values
>>      sent by events into physical quantities.
>>
>>      Minimum and maximum values have units of gram-force for pressure,
>>      millimeters for distance, and degrees of arc for tilt and rotation.
>>      This event will not be sent for axes whose physical minimum and
>>      maximum is not known.
>
> from what I gathered: for distance the sensors aren't precise enough which
> is why we switched to normalised values. pressure I'm not sure, but I
> vaguely remember tilt is blurry and imprecise too.
>
> So I'm hesistant to add this event, it looks like we don't have hardware
> that would send this event. which means we don't have clients that use it.
> Which means we don't need it.
> Let's wait until we have a use-case and a clear conversion before adding
> extra events.
>

This would be used for tilt and rotation axes. The only reason I
mentioned distance and pressure were to provide you with a better idea
of how it might be used if we had the had the necessary information
for those axes (... I don't want to characterize the pressure curves
of the various pens, but it /could/ be done; or a more linear force
sensor used in some future pen ...).

The use case would be supporting most every toolkit out there. It
seems like everything except GTK specifies that tilt information is
reported in some kind of physical unit. Qt needs to be able to
transform the normalized data into degrees. I believe EFL is the same.
Android (on the odd chance Google decides to replace their input layer
with libinput :P) uses radians. I suppose they could all hardcode a
transformation that assumes every device has the same physical tilt
range, but that's fragile, ugly, and just plain wrong.

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

> From a technical POV, I'd do this as separate events (pressure_range,
> distance_range, ...). Gives us better control over what we're sending out
> and more flexible in the corner cases.
>
> Cheers,
>    Peter
>
>>    </description>
>>    <arg name="capability" type="uint" enum="capability" summary="the
>> capability"/>
>>    <arg name="minimum" type="fixed" summary="physical value of axis minimum"/>
>>    <arg name="maximum" type="fixed" summary="physical value of axis maximum"/>
>>  </event>