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

Fri Apr 22 10:30:11 UTC 2016

Hi!,

On Fri, Apr 22, 2016 at 4:02 AM, Peter Hutterer
<peter.hutterer at who-t.net> wrote:
> 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.

Hmm, I most probably didn't encode that properly in docs in the early
drafts, but I expected this to work by announcing clients the
available button array on focus in, kinda similar in spirit to
wl_keyboard.modifiers (with the obvious "the ones active" vs "the ones
you might expect to receive" differences).

Presumably, in order to get a change in the buttons available to the
client the user will need to configure those to perform
compositor-level actions, and thus focus out the current client and
switch to a different UI. With this scheme, the only UI that might get
buttons (un)reserved while focused is the one mapping buttons itself,
and it should arguably be a compositor facility (or closely tied to
it).

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

We can also go this way, although there should be probably events to
notify both ways.

Cheers,
  Carlos