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

[Carlos Garnacho]

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

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