[PATCH v3 wayland-protocols] Add the tablet protocol

[Peter Hutterer]

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.

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

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