wl_tablet draft v2
Jason Gerecke
killertofu at gmail.com
Mon Jul 14 13:25:09 PDT 2014
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 :)
> 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.
> Arguments:
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - down
> Sent when the tool makes contact with the surface of the tablet.
> Arguments:
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - up
> Sent when the tool is no longer making contact with the surface of
> the tablet.
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - motion
> Sent whenever the tool moves.
> - Name: x
> Type: fixed
> Surface relative x coordinate
>
> - Name: y
> Type: fixed
> Surface relative y coordinate
>
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - distance
> Sent whenever the distance of the tool from the tablet changes. The
> value of the axis is normalized from 0 to WL_TABLET_AXIS_MAX.
> - Name: distance
> Type: fixed
> The new distance of the tool
>
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - pressure
> Sent whenever the pressure of the tool tablet changes. The value of
> the axis is normalized from 0 to WL_TABLET_AXIS_MAX.
> - Name: pressure
> Type: fixed
> The new pressure value for the tool
>
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - tilt
> Sent whenever the tilt of the tool changes. Each axis value is
> normalized from WL_TABLET_AXIS_MIN to WL_TABLET_AXIS_MAX.
Is resolution information available anywhere for these axes? If I have
one tablet that reports +-64 degrees of tilt and another that reports
+-90 degrees, how does a client translate a value of
WL_TABLET_AXIS_MAX into an appropriate physical value in each case?
> - Name: tilt_x
> Type: fixed
> The X tilt axis of the tool
>
> - Name: tilt_y
> Type: fixed
> The Y tilt axis of the tool
>
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - button
> Sent whenever a button on the tool is pressed or released.
> Arguments:
> - Name: button
> Type: uint
> The button whose state has changed
>
> - Name: state
> Type: uint
> Whether the button was pressed or released
>
> - Name: time
> Type: uint
> The time of the event with millisecond granularity.
>
> - frame
> Indicates the end of a sequence of device events
>
> - device_removed
> Sent when this tablet has been removed from the host
>
> Requests:
> - release
> Releases the wl_tablet object, resulting in the reference count
> being decremented by one. When the reference count reaches 0, the
> wl_tablet object will be destroyed.
>
> - wl_tablet_manager
> Enumerators:
> - tablet_type:
> - external
> The drawing tablet is external and lacks a display, like the
> Wacom Intuos series.
> - internal
> The tablet is part of a display that is built into the
> computer, like the ones built into the Microsoft Surface.
> - display
> The tablet is part of a display that is connected to the
> computer externally, like the Wacom Cintiq series.
> - axis_flag
> Used along with the supported_axes bitfield to indicate which
> additional axes a tablet can support
> - tilt
> - pressure
> - distance
>
> Events:
> - device_added
> Sent when a new tablet has been connected to the host.
> Arguments:
> - Name: id
> Type: new_id
> Interface: wl_tablet
> The new wl_tablet object for the tablet
>
> - Name: name
> Type: string
> The name of the tablet device
>
> - Name: vid
> Type: uint
> The vendor id of the tablet
>
> - Name: pid
> Type: uint
> The product id of the tablet
>
> - Name: type
> Type: uint
> The type of tablet. Uses values from
> wl_tablet_manager::tablet_type
>
> - Name: extra_axes
> Type: uint
> A bitfield containing information on which extra axes are
> supported.
>
> Ideas:
> - wl_tablet_tool
> This is something that hasn't really been decided on. Basically, the concept
> of this is a lot similar to the concept of how tablet tools are currently
> handled in libinput, we return a struct with all of the tool information
> inside it, instead of just providing a separate tool type variable and
> serial number we provide an entire object, which may or may not be easier
> for the client to work with.
It sounds like this would be in addition to the above definitions, correct?
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....
> Enumerators:
> - wl_tablet_tool_type:
> - pen
> - eraser
> - brush
> - pencil
> - airbrush
> - finger
> - mouse
> - lens
> Events:
> - Name: removed
> Sent when a tool has been removed from the system.
>
> Using this would require us changing the proximity_in event to provide the
> object ID of the tool currently in use, instead of the serial number and
> type.
> In addition, we would have to add this event to wl_tablet_manager:
> - Name: tool_added
> Sent when a new tool is being used with one of the tablets connected
> to the system
> Arguments:
> - Name: id
> Type: new_id
> Interface: wl_tablet_tool
> The ID of the new tool
>
> - Name: type
> Type: uint
> Returns the tool's physical type
>
> - Name: serial
> Type: uint
> Returns the tool's serial numbers. On tablets where this is
> not supported, this will always be 0.
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list