[PATCH v2 wayland-protocols] Add pad support to the tablet protocol

[Peter Hutterer]

On Thu, Apr 21, 2016 at 05:46:24PM -0700, Jason Gerecke wrote:
> On Mon, Apr 18, 2016 at 10:00 PM, Peter Hutterer
> <peter.hutterer at who-t.net> wrote:
> > From: Carlos Garnacho <carlosg at gnome.org>
> >
> > The pad's interface is similar to the tool interface, a client is notified of
> > the pad after the tablet_added event.
> >
> > The pad has three functionalities: buttons, rings and strips.
> > Buttons are fairly straightforward, rings and strips are separate interfaces
> > with a pointer-axis-like source/value/frame events.
> > The two interfaces are effectively identical but for the actual value they
> > send (degrees vs normalized position).
> >
> > Specific to the pad device is the set_feedback request which enables a client
> > to set a user-defined string to display for an OSD on the current mappings.
> > This request is available for buttons, rings and strips.
> >
> > Finally, the pad supports "modes", effectively sets of button/ring/strip
> > configurations.
> >
> > Signed-off-by: Carlos Garnacho <carlosg at gnome.org>
> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> > ---
> > Changes to v1:
> > - typos fixed
> >
> >  unstable/tablet/tablet-unstable-v1.xml | 423 ++++++++++++++++++++++++++++++++-
> >  1 file changed, 421 insertions(+), 2 deletions(-)
> >
> > diff --git a/unstable/tablet/tablet-unstable-v1.xml b/unstable/tablet/tablet-unstable-v1.xml
> > index 907126c..36b9ae8 100644
> > --- a/unstable/tablet/tablet-unstable-v1.xml
> > +++ b/unstable/tablet/tablet-unstable-v1.xml
> > @@ -115,7 +115,7 @@
> >      interface version number is reset.
> >    </description>
> >
> > -  <interface name="zwp_tablet_manager_v1" version="1">
> > +  <interface name="zwp_tablet_manager_v1" version="2">
> >      <description summary="controller object for graphic tablet devices">
> >        An object that provides access to the graphics tablets available on this
> >        system. All tablets are associated with a seat, to get access to the
> > @@ -139,7 +139,7 @@
> >      </request>
> >    </interface>
> >
> > -  <interface name="zwp_tablet_seat_v1" version="1">
> > +  <interface name="zwp_tablet_seat_v1" version="2">
> >      <description summary="controller object for graphic tablet devices of a seat">
> >        An object that provides access to the graphics tablets available on this
> >        seat. After binding to this interface, the compositor sends a set of
> > @@ -172,6 +172,23 @@
> >        </description>
> >        <arg name="id" type="new_id" interface="zwp_tablet_tool_v1" summary="the newly added tablet tool"/>
> >      </event>
> > +
> > +    <!-- version 2 additions -->
> > +
> > +    <event name="pad_added" since="2">
> > +      <description summary="new pad notification">
> > +       This event is sent whenever a new pad is known to the system. Typically,
> > +       pads are physically attached to tablets and a pad_added event is
> > +       sent immediately after the wp_tablet_seat.tablet_added.
> > +       However, some standalone pad devices logically attach to tablets at
> > +       runtime, the client must wait for wp_tablet_pad.enter to know the
> > +       tablet a pad is attached to.
> > +
> 
> If a compositor wanted to support "bare" pad devices, I'm assuming
> they'd have to fake one or more wp_tablet objects for that use,
> correct?

yeah, I think so. but there is the question of what a standalone pad (I
assume you're talking about the EKR) would do in a wacom/tablet context?
and whether the EKR would just be better off as a buttonset device when it's
not connected to a tablet.

> > +    <event name="source" since="2">
> > +      <description summary="ring event source">
> > +       Source information for ring events.
> > +
> > +       This event does not occur on its own. It is sent before a
> > +       wp_tablet_pad_ring.frame event and carries the source information
> > +       for all events within that frame.
> > +
> > +       The source specifies how this event was generated. If the source is
> > +       wp_tablet_pad_ring.source.finger, a wp_tablet_pad_ring.stop event
> > +       will be sent when the user lifts the finger off the device.
> > +
> > +       This event is optional. If the source is unknown for an interaction,
> > +       no event is sent.
> > +      </description>
> > +      <arg name="source" type="uint" summary="the event source"/>
> > +    </event>
> > +
> > +    <event name="angle" since="2">
> > +      <description summary="angle changed">
> > +       Sent whenever the angle on a ring changes.
> > +
> > +       The angle is provided in 0.01 of a degree clockwise from the logical
> > +       north of the ring in the pad's current rotation.
> > +      </description>
> > +      <arg name="angle" type="uint" summary="The current angle"/>
> 
> I assume this will be updated to use the "fixed" type (along with pen
> tilt and rotation) in a subsequent patch?

yes, I want to merge the change to doubles as v2 since it's an ABI break,
but it's such low impact that merging this as v1 is better, IMO

> > +    <event name="frame" since="2">
> > +      <description summary="end of a ring event sequence">
> > +       Indicates the end of a set of events that logically belong together.
> > +       A client is expected to accumulate the data in all events within the
> > +       frame before proceeding.
> > +
> > +       All wp_tablet_pad_ring events before a wp_tablet_pad_ring.frame event belong
> > +       logically together. For example, on termination of a finger interaction
> > +       on a ring the compositor will send wp_tablet_pad_ring.source event,
> > +       a wp_tablet_pad_ring.stop event and a wp_tablet_pad_ring.frame
> > +       event.
> > +
> > +       A wp_tablet_pad_ring.frame event is sent for every logical event
> > +       group, even if the group only contains a single wp_tablet_pad_ring
> > +       event.  Specifically, a client may get a sequence: angle, frame,
> > +       angle, frame, etc.
> > +      </description>
> 
> This is a little confusing. At first I read this to mean that the
> frames bracket the entire ring interaction, but the the final
> paragraph instead makes it sound like frames act the same as they do
> for a stylus (i.e., basically acting the same as the kernel's
> SYN_REPORT event). I imagine the latter interpretation is intended,
> but a little rewording of the first paragraph (esp. "set of events
> that logically belong together") might be a good idea.

yes, they act like SYN_REPORT but only within the ring interaction. so you
may get more frame events than SYN_REPORT if you're using rings and strips
at the same time.


I've changed this locally to:
         Indicates the end of a set of events that represent one logical
         hardware strip event. A client is expected to accumulate
         the data in all events within the frame before proceeding.


any better rewordings are welcome ;)

[...]

> > +    <event name="buttons" since="2">
> > +      <description summary="buttons announced">
> > +       Sent on wp_tablet_pad initialization to announce the available buttons.
> > +       Compositors may consume some buttons for global actions, those
> > +       will not be announced in this event (e.g. the button to switch
> > +       between modes, if any).
> > +
> > +       This event is sent in the initial burst of events before the
> > +       wp_tablet_tool.done event.
> > +      </description>
> 
> Do we need to have the ability to change the set of announced buttons
> on the fly? Its possible the compositor would want to change which
> buttons it reserves by user request. For example, right now it is
> possible to configure GNOME to have a button pop up an OSD of button
> assignments (which is a global compositor action). The choice of the
> button is up to the user, and if the user later changes their mind
> then applications will have to be informed that the set of available
> buttons has changed. I might be thinking about this case
> wrong-headedly and that there's no need for the list of available
> buttons to change, but I don't think so...
> 
> Its also not entirely clear to me what the array that would be
> received is supposed to contain or how clients are supposed to
> interpret it.

hmm, good point. This is from before we switched libinput over to report
numerical buttons, it makes sense to do the same here and change this event
into a simple "here's the number of buttons" event and change the value of
the "button" event into a button index.

if we need to change the set of announced buttons I think a better option
would be a "button_reserved" event later down the track that tells the
client that they cannot expect that particular button to send events.

Cheers,
   Peter