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

[Jason Gerecke]

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

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

Jason
---
Now instead of four in the eights place /
you’ve got three, ‘Cause you added one /
(That is to say, eight) to the two, /
But you can’t take seven from three, /
So you look at the sixty-fours....