[PATCH wayland-protocols] Add the tablet protocol

[Carlos Garnacho]

Hey :),

On Mon, Nov 16, 2015 at 12:21 PM, Daniel Stone <daniel at fooishbar.org> wrote:
> Peter, Stephen,
>
> On 6 November 2015 at 04:24, Peter Hutterer <peter.hutterer at who-t.net> wrote:
>> This is the revamped version of the tablet protocol for graphics tablets
>> (e.g. Wacom tablets). Too many changes from the last version (a year ago or
>> so), so I won't detail them, best to look at it with fresh eyes.
>
> Thanks a lot for doing this! Looks really good to me, and I think
> getting it in wayland-protocols would be good.
>
> Do you have other implementations, e.g. GTK+/Mutter? If so, a pointer
> (ha) to those would be great.

The branch in mutter corresponding to this last version is:
https://git.gnome.org/browse/mutter/log/?h=wip/tablet-protocol-v3

There's also:
https://git.gnome.org/browse/gtk+/log/?h=wip/wayland-tablet

For GTK+, but that one hasn't caught up yet with wayland-protocols

>
> Obligatory nitpicks follow:
>
>> +<?xml version="1.0" encoding="UTF-8"?>
>> +<protocol name="wayland_tablet_unstable_v1">
>> +  <description summary="Wayland protocol for graphics tablets">
>> +    This description provides a high-level overview of the interplay between
>> +    the interfaces defined this protocol. For details, see the protocol
>> +    specification.
>> +
>> +    More than one tablet may exist, and device-specifics matter. Tablets are
>> +    not represented by a single virtual device like wl_pointer. A client
>> +    binds to the tablet manager object which is just a proxy object. From
>> +    that, the client requests wp_tablet_manager.get_tablet_seat(wl_seat)
>> +    and that returns the actual interface that has all the tablets. With
>> +    this indirection, we can avoid merging wp_tablet into the actual wayland
>> +    protocol, a long-term benefit.
>
> Yes, it turns out the wl_seat.get_* model was probably a pretty bad
> anti-pattern. Oh well. To avoid too much object proliferation though,
> how about something like:
> <interface name="wp_tablet_manager">
>   <request name="add_seat">
>     <description summary="Add seat of interest">
>       Add a seat of interest to this tablet manager. The client will
> receive events for all tablets currently on this seat, as well as
> tablets added to this seat in future.
>     </description>
>     <arg name="seat" type="object" interface="wl_seat"/>
>   </request>
>   [inline wp_tablet_seat here ...]
> </interface>
>
> Then you can just bin wp_tablet_seat.
>
> Not a pattern we've previously employed, but I think it's a good one
> that avoids one extra step of indirection, as well as making it a bit
> easier for clients to do the right thing.
>
>> +    The wp_tablet_seat sends a "tablet added" for each tablet connected.
>> +    That event is followed by descriptive events about the hardware;
>> +    currently that includes events for name, vid/pid and
>> +    internal/external/display type, and a wp_tablet.path event that
>> +    describes a local path. This path can be used to uniquely identify a
>> +    tablet, or get more information through libwacom.  Emulated or nested
>> +    tablets can skip any of those, e.g. a virtual tablet may not have a
>> +    vid/pid. The sequence of descriptive events is terminated by a
>> +    wp_tablet.done event to signal that a client may now finalize any
>> +    initialization for that tablet.
>
> Is VID/PID in USB space? (Answers in diff form preferred.)
>
>> +    Two special events (that don't exist in X) are down and up. They signal
>> +    "tip touching the surface". For tablets without real proximity
>> +    detection, the sequence is: proximity_in, motion, down, frame.
>> +
>> +    When the tool leaves proximity, a proximity_out event is sent, followed
>> +    by button release events for any button still down. This signals to
>> +    the client that the buttons were held when the tool left proximity.
>> +    Those events are all sent within the same frame.
>
> Can we please enforce a strict bracketing of down/up occurring in
> matched pairs inside of proximity_in/out? So, the total event stream
> would be:
>   - proximity_in
>     - motion
>     - down
>       - motion/motion/button/...
>     - up
>   - proximity_out
>
> I assume the implementation does this, but it would be nice to have
> encoded in the protocol.

It is worth noting that stylus button events can be obtained while in
proximity regardless of down/up state, so that'd roughly be:

- proximity_in
  - motion/button/...
  - down
    - motion/button/...
  - up
  - motion/button/...
- proximity_out

Cheers,
  Carlos