[PATCH v3 wayland-protocols 4/4] tablet: Add pad support to the tablet protocol

Wed May 18 05:52:28 UTC 2016

On Tue, May 17, 2016 at 02:07:39PM -0700, Jason Gerecke wrote:
> On 05/17/2016 03:02 AM, Carlos Garnacho wrote:
> > Hey :),
> > 
> > On Tue, May 17, 2016 at 2:50 AM, Peter Hutterer
> > <peter.hutterer at who-t.net> wrote:
> >> On Tue, May 17, 2016 at 01:30:03AM +0200, Carlos Garnacho wrote:
> >>> Hey :),
> >>>
> >>> On Wed, May 11, 2016 at 4:51 AM, 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).
> >>>>
> >>>> Buttons are sequentially indexed starting with zero, unlike other protocols
> >>>> where a linux/input.h-style semantic event code is used. Since we expect all
> >>>> buttons to have client-specific functionality, an additional event tells the
> >>>> client when a given button index is not available, usually because the
> >>>> compositor assignes some function to it (e.g. mode switching, see below).
> >>>>
> >>>> 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 v2:
> >>>> - change to v2 of the protocol
> >>>> - various comments and suggestions for improved wording incorporated
> >>>> - ring is in wl_fixed degrees now (was int, in 0.01 of a degree)
> >>>> - button events changed to sequential indices
> >>>> - new buttons_reserved event
> >>>>
> >>>>  unstable/tablet/tablet-unstable-v2.xml | 436 +++++++++++++++++++++++++++++++++
> >>>>  1 file changed, 436 insertions(+)
> >>>>
> >>
> >> ..
> >>
> >>>> +    <event name="buttons_reserved">
> >>>> +      <description summary="reserved button indices">
> >>>> +       Sent on wp_tablet_pad initialization and/or at a later time to notify the
> >>>> +       client of reserved buttons.
> >>>> +
> >>>> +       Compositors may consume some buttons for global actions, those
> >>>> +       global actions will not trigger wl_tablet_pad.button events (e.g.
> >>>> +       the button to switch between modes, if any). This event notifies the
> >>>> +       client that some button indices are reserved by the compositor and
> >>>> +       will not generate events visible to the client. Button indices start
> >>>> +       at 0.
> >>>> +
> >>>> +       This event may is sent in the initial burst of events before the
> >>>> +       wp_tablet_pad.done event and/or at any later time when the
> >>>> +       compositor changes the list of reserved buttons. This event is only
> >>>> +       sent when the compositor reserves at least one button.
> >>>> +      </description>
> >>>> +      <arg name="buttons_reserved" type="array" summary="the reserved button indices"/>
> >>>> +    </event>
> >>>> +
> >>>> +    <event name="modes">
> >>>
> >>> After some hands-on experience, I see this API in libwacom:
> >>>
> >>> int libwacom_get_ring_num_modes(const WacomDevice *device);
> >>> int libwacom_get_ring2_num_modes(const WacomDevice *device);
> >>> int libwacom_get_strips_num_modes(const WacomDevice *device);
> >>>
> >>> This makes me think, are there devices with more than one of these
> >>> modes? In that case I guess would be better to move .modes and .mode
> >>> to wp_tablet_pad_ring/strip than exposing the NxM combinations here. I
> >>> guess it also means renouncing to making these modes affect anything
> >>> else than the ring/strip.
> >>>
> >>> If we move these events there, I wonder if we better add .done events
> >>> there too, or it suffices with wp_tablet_pad.done. I'd expect all
> >>> device characteristics to be announced before wp_tablet_pad.done
> >>> anyway.
> >>
> >> the only device that had two rings and modes was the 24HD and both had 4
> >> modes iirc. that device isn't on sale anymore and given the current gen of
> >> wacom tablets I doubt it comes back.
> >>
> 
> 3 modes on each side, actually :)
> 
> >> however, the 22hd has two touch strips at the back and two mode switch
> >> buttons. I don't think there's much of a use-case for having different
> >> numbers of modes but having the modes switch independently is certainly
> >> something we should support.
> >>
> 
> The chances of a device having multiple mode switches with a different
> number of modes is pretty low. The reason has to do with why some
> devices have a second set of buttons/rings/switches in the first place:
> left-handed users. While it's trivial enough to rotate an Intuos around
> so the pad controls are under the users's non-dominant hand, that's not
> the case with the Cintiqs. To address this, a mirror-image set of pad
> controls is present to make things equally accessible to either hand.
> 
> There's basically zero chance that a tablet would have a different
> number of modes on its two mirrored halves. More likely is a device that
> doesn't have a mirrored layout but still has two mode switches, but even
> that's a stretch...
> 
> >> the next step is then the buttons of course: on the 22hd I'd expect only the
> >> right set of buttons to switch mode when the center button is pressed, but
> >> the strip could/should be paird with that right set of buttons.
> >> so we effectively need something like button groups within the pad, and the
> >> strip/ring (and later LEDs) could be part of that button group.
> >>
> >> The two options we have here is to either nest them within the tablet_pad
> >> with most of the current pad events/requests move to the button group:
> >> wp_tablet_manager
> >>   wp_tablet_seat
> >>     wp_tablet_pad
> >>       wp_tablet_pad_button_group
> >>         wp_tablet_pad_ring
> >>         wp_tablet_pad_strip
> > 
> > Hmm, with this interface hierarchy, it seems to me that you will
> > always get the same set of button groups with a same pad device, and
> > those can never change. This means we can announce the whole hierarchy
> > of button groups, rings and strips before wp_tablet_pad.done.
> > Something tells me this extra level of indirection is kinda
> > superfluous :).
> > 
> > Also, side thought. If we embarked into separating button groups, we
> > no longer can guarantee that the button numbering starts at 0 for a
> > given group.

true, we'd have some awkward formulation around buttons being numbered from
0 per pad, not group. which is probably counterproductive.
fwiw, we still have the same issue for multiple tablet_pads, esp. because
the button numbers won't correspond to the libwacom numbering anymore.

> >> An alternative would be to provide multiple tablet_pads for the same
> >> physical device, one for each virtual button group. That just avoids one
> >> nesting layer at the cost of less clarity of what belongs to what. OTOH,
> >> does that matter? because the only case we have where can have two
> >> physically separate pads connected to the same tablet is two EKRs.
> >> Any opinions? I'd prefer the button group approach for its clarity even
> >> though in 90% of the use-cases it's just a (minor) overhead.
> 
> I actually find the multiple tablet_pad approach clearer, personally.
> Knowing "what belongs to what" doesn't seem like terribly useful
> knowledge since all that matters in the vast majority of cases is which
> tablet the pads are associated with, which is already explicit.
> 
> Speaking of this, I just noticed there's no equivalent to the
> wp_tablet.path event for pads. Is that going to be a problem now that
> the pad is typically a separate kernel device? Is attaching an EKR to a
> tablet going to be problematic?

hm. yes, it might be because if the compositor decides to pair the two into
the same wp_tablet (and IMO it should) then there's no way to figure out
what the pad is. that also goes for vid/pid.

> > Just throwing the idea: How about handling this completely on the
> > client side? We relate modes to rings/strips, and the client may just
> > lookup the button groups in libwacom. After all, the client is free to
> > update a button action (and issue .set_feedback) at any time. Hmm,
> > although there should be then some positional (or emission order)
> > guarantees for rings/strips then, so those may be related to button
> > groups.

the positional guarantee can be arranged, that's something we can enforce in
libinput, together with libwacom. all we need is some sort of guarantee that
the strips are always in english reading order (columns left-right times
rows top-to-bottom). that's effectively what we're already doing anyway,
afaict (unless the 24hd has the ABS_WHEEL2 on the left?)

> > Anyhow, I think the problem is easy enough to solve with some libwacom
> > lookups. Having no groups in the protocol also sits nicely IMO with
> > the lack of semantics we (don't) attribute to buttons.
> > 
> > Cheers,
> >   Carlos
> > 
> 
> I suppose this could also work, though it doesn't feel right to me. Why
> relate rings/strips to modes in the protocol, but not buttons? Unless we
> expect most clients to change ring/strip actions but not button actions
> in response to a mode switch, there's little reason I see in
> spoon-feeding them the former and requiring them to ask libwacom for the
> latter.

I agree, pushing this to the client should decouple the modes completely so
you're only left with a mode-switch event that signals that the mode button
has been pressed (which is still the compositor's choice). but what happens
should the be fully in the client. so effectively we can leave the current
wl_tablet_pad.mode event as-is.

What we could also do is have the mode event carry a group information*,
similar to what the LEDs already do in the gnome pkexec helper. so a click
on the right mode button would simply cycle through modes (1, [0..4]).

Cheers,
   Peter

* or call it mode-switch-button-number