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.
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.
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.
- 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.
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
[email protected]
http://lists.freedesktop.org/mailman/listinfo/wayland-devel
