wl_tablet specification draft
Peter Hutterer
peter.hutterer at who-t.net
Thu Jun 26 00:12:17 PDT 2014
On Thu, Jun 26, 2014 at 09:48:37AM +0300, Pekka Paalanen wrote:
> Hi,
>
> it seems you forgot to reply-to-all, so I have re-added everyone and
> not trimmed the quotation.
>
> On Wed, 25 Jun 2014 18:37:08 -0400
> Lyude <thatslyude at gmail.com> wrote:
>
> > On Wed, 2014-06-25 at 15:19 +0300, Pekka Paalanen wrote:
> > > On Tue, 24 Jun 2014 21:56:09 -0400
> > > Chandler Paul <thatslyude at gmail.com> wrote:
> > >
> > > > Hello! As you all know I've been working on adding drawing tablet
> > > > support to the Wayland protocol. Now that we've added support for
> > > > tablets to libinput, the next step is writing the actual protocol that
> > > > will be implemented by the compositor. Following this blurb is the
> > > > current draft of the tablet protocol we have. Feel free to critique it.
> > > >
> > > > Cheers,
> > > > Lyude
> > > >
> > > > ----------------------------------------------------------------------------
> > > >
> > > > wl_tablet specifications
> > > >
> > > > 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 arithmatic 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.
> > > >
> > > > Definitions:
> > > > - WL_TABLET_AXIS_MAX = 65535
> > > > - WL_TABLET_AXIS_MIN = (-65535)
> > > >
> > > > Enumerators:
> > > > - wl_tablet_axis:
> > > > - WL_TABLET_AXIS_X
> > > > - WL_TABLET_AXIS_Y
> > > > Represents the X and Y axes respectively. Only used in bitfields to
> > > > indicate whether or not they've changed since the last event.
> > > >
> > > > - WL_TABLET_AXIS_DISTANCE
> > > > Represents the distance axis on a tablet. Normalized from 0 to
> > > > WL_TABLET_AXIS_MAX. For tablets that do not support reporting the
> > > > distance, this will always be 0.
> > > >
> > > > - WL_TABLET_AXIS_PRESSURE
> > > > Represents the pressure axis on a tablet. Normalized from 0 to
> > > > WL_TABLET_AXIS_MAX. For tablets that do not support reporting the
> > > > pressure, this will always be WL_TABLET_AXIS_MAX.
> > > >
> > > > - WL_TABLET_AXIS_TILT_VERTICAL
> > > > - WL_TABLET_AXIS_TILT_HORIZONTAL
> > > > Each represents the vertical and horizontal tilt axes respectfully.
> > > > Normalized from WL_TABLET_AXIS_MIN to WL_TABLET_AXIS_MAX. For
> > > > tablets that do not support this, this value will always be 0.
> > > >
> > > > - WL_TABLET_AXIS_CNT
> > > > Represents the number of axes
> > > > - wl_tablet_tool_type:
> > > > - pen
> > > > - eraser
> > > > - brush
> > > > - pencil
> > > > - airbrush
> > > > - finger
> > > > - mouse
> > > > - lens
> > > > - 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.
> > > > 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: x
> > > > Type: fixed
> > > > Surface relative x coordinate
> > > >
> > > > - Name: y
> > > > Type: fixed
> > > > Surface relative y coordinate
> > > >
> > > > - 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.
> > > >
> > > > - Name: axes
> > > > Type: array
> > > > The current values of each of the tablet axes starting at
> > > > WL_TABLET_AXIS_DISTANCE. The length of the array is equal to the
> > > > number of axes that are reported. Any axes >= WL_TABLET_AXIS_CNT
> > > > must be ignored. The size of the array remains fixed for the
> > > > lifetime of the tablet.
> > > >
> > > > - proximity_out
> > > > Send whenever the tool leaves the proximity of the tablet or moves out of
> > > > the client surface. When the tool goes out of proximity, a set of button
> > > > release events are sent before the initial proximity_out event for each
> > > > button that was held down before the tablet tool left proximity. In
> > > > addition, axis updates always come before a proximity-out event.
> > > > Arguments:
> > > > - Name: id
> > > > Type: uint
> > > > The id of the tablet sending this event.
> > > >
> > > > - Name: time
> > > > Type: uint
> > > > The time of the event with millisecond granularity.
> > > >
> > > > - axis
> > > > Sent whenever an axis on the tool changes. This can include movement on the
> > > > X and Y axis.
> > > > Arguments:
> > > > - Name: id
> > > > Type: uint
> > > > The id of the tablet sending this event.
> > > >
> > > > - Name: x
> > > > Type: fixed
> > > > Surface relative x coordinate
> > > >
> > > > - Name: y
> > > > Type: fixed
> > > > Surface relative y coordinate
> > > >
> > > > - Name: surface
> > > > Type: object
> > > > Interface: wl_surface
> > > > The current surface the tablet tool is over
> > >
> > > How about using enter/leave events telling the client which wl_surface
> > > the input device is targeting? That way you don't have to repeat the
> > > wl_surface argument in every event
> > I did originally have enter/leave events in the protocol but we ended up
> > removing them because they end up being somewhat redundant. When you
> > think about it, there's not much use in differentiating the two. Most
> > clients are only really going to care about whether or not the tool is
> > on their surface, not whether or not it's in proximity while it's on
> > their surface. And of course when the tool is out of proximity on the
> > surface, there's no useful data it can send to the tablet. In that case
> > we might as well get rid of the proximity_(in/out) stuff and just use
> > enter and leave to minimize the amount we have to add to the protocol. I
> > also don't think including the surface in all of the enter/leave events
> > is too big of a deal.
>
> Making proximity_in/out work as enter/leave would be fine by me, if it
> works for you. I'm just looking to reduce the amount of duplicated data
> in the most heavily used events sent over the wire.
Lyude: what Pekka is referring to here is to have the surface _only_ in the
proximity events, and then skipping the surface field for motion/button
events.
> I only now realized that you can have several different tools on the
> same tablet. You'd probably have per-tool enter/leave rather than
> per-tablet, sort of depending on how (or if?) the tablet maps to the
> screen.
Indeed, and that is why we dropped enter/leave in favour of prox in/out. To
the client it doesn't really matter if we move off the surface by removing
the tool, or off the surface by moving into another surface.
And those prox in/out events have the tool ID, so they're technically
per-tool and per-tablet already. Only one tool can be in proximity at a
time, but you can have two tools in prox on two different tablets.
> Does the tablet map to the screen in a way that you can use the tablet
> address any window on screen at any time like a touchscreen does, or
> would it be more appropriate to have the whole tablet surface assigned
> to "the current" window and let the client use the whole range of the
> tablet instead of just the sub-region determined by its window on
> screen? (That is probably a stupid question, but would have you
> considered if the latter way had any solid benefits?)
GIMP used to/still has that feature, I don't know how common it's being used
(need to chase this up). We had that in the original draft but decided to
remove it from this version, it's something we can add later with little
changes.
the common use-case right now is having the tablet mapped to either all
screens or a single screen.
> > Of course though, if you know of uses where a client would want to know
> > when the tool's gone out of proximity without leaving the surface and
> > couldn't just settle with a single event for both, feel free to bring it
> > up.
>
> I have never used tablets, so I can't imagine real use cases. What
> happens if you press a physical button on a tool that is out of
> proximity? Should it be ignored completely, or should it still be
> delivered to the app?
The HW doesn't know about the event then. The best you can do is move into
proximity with a button already down, but that'll just trigger a button
press anyway.
Cheers,
Peter
More information about the wayland-devel
mailing list