wl_tablet draft v2

[Peter Hutterer]

On Wed, Jul 16, 2014 at 08:08:29PM -0400, Lyude wrote:
> On Mon, 2014-07-14 at 13:25 -0700, Jason Gerecke wrote:
> > On Sun, Jul 13, 2014 at 12:17 PM, Lyude <thatslyude at gmail.com> wrote:
> > >                            wl_tablet specifications
> > >                                   Version 2
> > >
> > > General notes:
> > > - Many of the axis values in this are normalized to either 0-65535 or
> > >   (-65535)-65535. I would leave the axis values as-is since libinput reports
> > >   them as doubles, but since we only have 8 bits of precision we'd lose way
> > >   too many values. 65535 seemed like the best choice since it's the maximum
> > >   length of a signed short, it's a whole number, it's way higher then the
> > >   range of any of the axes (with the exception of X and Y, but these aren't
> > >   normalized anyway) and we can do just about any basic arithmetic with it
> > >   without having to worry about overflowing. Plus, all we have to do is
> > >   multiply the value by 65535 after we get it from libinput.
> > >
> > Speaking of overflow, what's Wayland's stance on whether the
> > compositor or client is responsible for dealing with it? I remember
> > Google mentioned that while working on Android's input driver, they
> > noticed some input devices could be "turned up to 11" and report
> > values beyond the kernel-indicated minimum/maximum. They decided to
> > punt the problem to app developers and documented that an app may e.g.
> > see 110% pressure if that's what the hardware reported. The question
> > is mostly academic since the Wacom kernel driver shouldn't be an
> > offender, but I might as well ask :)
> If it comes down to handling overflow, it'll probably be up to the
> client. I'm hoping it shouldn't though. The reason I choose 65535 in the
> first place is because it can more then cover any of the axes (other
> then the X and Y axes, but those aren't normalized anyway so I'm not
> worried about that), and it's difficult to accidentally overflow doing
> general arithmetic with a value of 65535. In most situations, addition,
> subtraction, multiplication, etc. shouldn't overflow. In fact you can
> (almost) square it at least once without overflowing. I'm assuming if
> there's a chance they might, then the client's doing something that the
> developers understand the risk of. It's just a number though, so we can
> always turn it down if we need to.

And as for the "turning up to 11", we can/must handle that in libinput
anyway, since that already provides normalized values. The simple approach
of clipping the first event sequence above the max and then rescaling
min/max to fit in the future will probably cater for most use-cases.

> > > Changes since the last version:
> > > - The surface argument is now only included in the proximity-in events
> > > - wl_tablet_manager has been added. Events no longer have a separate id
> > >   argument, and instead rely on wl_tablet objects to differentiate each tablet
> > >   from each other. A lot of it was copied from Peter's initial wl_tablet
> > >   proposal, but a few additions have been made; I've added an argument for
> > >   each of the axis events that a tablet supports to the device_added event.
> > > - Axis changes have been split up into a couple different events
> > > - Added a generic frame event. Because of the different kinds of click
> > >   emulations done with tablets, having each event packed into a frame is
> > >   convenient.
> > > - All of the starting values for each axis are provided as normal events in
> > >   the same frame as a proximity_in event. The same goes for the status of each
> > >   button on the tool. This makes the protocol a lot cleaner
> > >
> > > Definitions:
> > > - WL_TABLET_AXIS_MAX = 65535
> > > - WL_TABLET_AXIS_MIN = (-65535)
> > >
> > > Interfaces:
> > > - wl_tablet
> > >         Enumerators:
> > >         - wl_tablet_tool_type:
> > >                 - pen
> > >                 - eraser
> > >                 - brush
> > >                 - pencil
> > >                 - airbrush
> > >                 - finger
> > >                 - mouse
> > >                 - lens
> > >         - wl_tablet_button
> > >                 - stylus_1
> > >                 - stylus_2
> > >         - wl_tablet_button_state
> > >                 - pressed
> > >                 - released
> > >
> > >         Events:
> > >         - proximity_in
> > >           Sent when the tool comes into proximity above the client surface,
> > >           either by the tool coming into proximity or a tool being
> > >           in-proximity and moving to the client surface. If a tablet tool
> > >           makes contact with the tablet at the same time that the tool comes
> > >           into proximity, the proximity event comes first and the down event
> > >           comes afterwards.
> > >           A proximity_in event is immediately followed by the following
> > >           sequence of events in the same frame:
> > >                 - motion
> > >                 - down (if the tool is touching the tablet's surface at the
> > >                   same time it comes into proximity)
> > >                 - a button press event for each button held down on the tool
> > >                   as it comes into proximity
> > >                 - pressure (if supported by the tablet)
> > >                 - distance (if supported by the tablet)
> > >                 - tilt (if supported by the tablet)
> > >           This allows a client to get the starting values for all of the axes,
> > >           along with the starting coordinates of the tool, and the state of
> > >           each button on the tool.
> > >
> > >           Arguments:
> > >                 - Name: id
> > >                   Type: uint
> > >                   the id of the tablet sending this event.
> > >
> > >                 - Name: type
> > >                   Type: uint
> > >                   The type of tool that came into proximity, e.g. pen,
> > >                   airbrush, etc.
> > >
> > >                 - Name: serial
> > >                   Type: uint
> > >                   The serial number of the tool that came into proximity. On
> > >                   tablets where this isn't provided, this value will always be
> > >                   0.
> > >
> > >                 - Name: surface
> > >                   Type: object
> > >                   Interface: wl_surface
> > >                   The current surface the tablet tool is over
> > >
> > >                 - Name: time
> > >                   Type: uint
> > >                   The time of the event with millisecond granularity.
> > >
> > >         - proximity_out
> > >           Sent whenever the tool leaves the proximity of the tablet or moves
> > >           out of the client surface. When the tool goes out of proximity,
> > >           button release events are sent before the initial proximity_out
> > >           event for each button that was held down before the tablet tool left
> > >           proximity. Following that, an up event will be sent if the tool was
> > >           in contact with the surface of the tablet before it went out of
> > >           proximity. In addition, axis updates always come before a
> > >           proximity-out event.
> > 
> > How does this compare to the event sequence sent when a mouse leaves a
> > surface? If, for example, I hold down the left mouse button inside a
> > client and drag outside, does the client see a button-up event?
> > Sending the sequence above seems sane enough, but I wonder if there
> > are cases where it would cause an application to run into trouble.
> Currently, dragging with a mouse makes the mouse continue to report a
> button being held down to the surface it was originally on until it
> reaches the surface we're dragging an item too. Tablet's will most
> likely work the same way.

agree, this should copy the enter/leave semantics. The main reason we called
it proximity here is because unlike a mouse we can leave while being in the
middle of a surface in the vertical direction.

Cheers,
   Peter