wl_tablet specification draft
Ping Cheng
pinglinux at gmail.com
Thu Jun 26 21:38:29 PDT 2014
On Thursday, June 26, 2014, Peter Hutterer <peter.hutterer at who-t.net> wrote:
> 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 <javascript:;>> 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 <javascript:;>> 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?)
With my experience, mapping whole tablet to a window or a
specific display area is preferred. That is how mapping works on Windows
and Mac too.
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.
As Jason mentioned, mapping to a window in Gimp is hardly usable. That
was partially because Gimp did not process mapping well; partially because
tablet to specific display area mapping was not properly supported.
the common use-case right now is having the tablet mapped to either all
> screens or a single screen.
This common use case is for normal users. Artists/drawing app users prefer
to map whole tablet to their whole drawing areas. They use mode toggle to
reach objects/button/functions outside of the drawing area.
Ping
> > > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20140626/57c9eff5/attachment-0001.html>
More information about the wayland-devel
mailing list