This page provides details about the graphics tablet support in libinput.
Note that the term "tablet" in libinput refers to graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the Apple iPad.
Tablet buttons vs. tablet tools
Most tablets provide two types of devices. The pysical tablet often provides a number of buttons and a touch ring or strip. Interaction on the drawing surface of the tablet requires a tool, usually in the shape of a stylus. The libinput interface exposed by devices with the LIBINPUT_DEVICE_CAP_TABLET_TOOL capability applies only to events generated by tools.
Touch events on the tablet integrated into a screen itself are exposed through the LIBINPUT_DEVICE_CAP_TOUCH capability. Touch events on a standalone tablet are exposed through the LIBINPUT_DEVICE_CAP_POINTER capability. In both cases, the kernel usually provides a separate event node for the touch device, resulting in a separate libinput device. See libinput_device_get_device_group() for information on how to associate the touch part with other devices exposed by the same physical hardware.
Tool tip events vs. button events
The primary use of a tablet tool is to draw on the surface of the tablet. When the tool tip comes into contact with the surface, libinput sends an event of type LIBINPUT_EVENT_TABLET_TOOL_TIP, and again when the tip ceases contact with the surface.
Tablet tools may send button events; these are exclusively for extra buttons unrelated to the tip. A button event is independent of the tip and can while the tip is down or up.
Some tablet tools' pressure detection is too sensitive, causing phantom touches when the user only slightly brushes the surfaces. For example, some tools are capable of detecting 1 gram of pressure.
libinput uses a device-specific pressure threshold to determine when the tip is considered logically down. As a result, libinput may send a nonzero pressure value while the tip is logically up. Most application can and should ignore pressure information until they receive the event of type LIBINPUT_EVENT_TABLET_TOOL_TIP. Applications that require extremely fine-grained pressure sensitivity should use the pressure data instead of the tip events to determine a logical tip down state and treat the tip events like axis events otherwise.
Note that the pressure threshold to trigger a logical tip event may be zero on some devices. On tools without pressure sensitivity, determining when a tip is down is device-specific.
Relative motion for tablet tools
libinput calculates the relative motion vector for each event and converts it to the same coordinate space that a normal mouse device would use. For the caller, this means that the delta coordinates returned by libinput_event_tablet_tool_get_dx() and libinput_event_tablet_tool_get_dy() can be used identical to the delta coordinates from any other pointer event. Any resolution differences between the x and y axes are accommodated for, a delta of N/N represents a 45 degree diagonal move on the tablet.
The delta coordinates are available for all tablet events, it is up to the caller to decide when a tool should be used in relative mode. It is recommended that mouse and lens cursor tool default to relative mode and all pen-like tools to absolute mode.
If a tool in relative mode must not use pointer acceleration, callers should use the absolute coordinates returned by libinput_event_tablet_tool_get_x() and libinput_event_tablet_tool_get_y() and calculate the delta themselves. Callers that require exact physical distance should also use these functions to calculate delta movements.
Special axes on tablet tools
A tablet tool usually provides additional information beyond x/y positional information and the tip state. A tool may provide the distance to the tablet surface and the pressure exerted on the tip when in contact. Some tablets additionally provide tilt information along the x and y axis.
The granularity and precision of the distance and pressure axes varies between tablet devices and cannot usually be mapped into a physical unit. libinput normalizes distance and pressure into the [0, 1] range.
While the normalization range is identical for these axes, a caller should not interpret identical values as identical across axes, i.e. a value v1 on the distance axis has no relation to the same value v1 on the pressure axis.
The tilt axes provide the angle in degrees between a vertical line out of the tablet and the top of the stylus. The angle is measured along the x and y axis, respectively, a positive tilt angle thus means that the stylus' top is tilted towards the logical right and/or bottom of the tablet.
Handling of proximity events
libinput's LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY events notify a caller when a tool comes into sensor range or leaves the sensor range. On some tools this range does not represent the physical range but a reduced tool-specific logical range. If the range is reduced, this is done transparent to the caller.
For example, the Wacom mouse and lens cursor tools are usually used in relative mode, lying flat on the tablet. Movement typically follows the interaction normal mouse movements have, i.e. slightly lift the tool and place it in a separate location. The proximity detection on Wacom tablets however extends further than the user may lift the mouse, i.e. the tool may not be lifted out of physical proximity. For such tools, libinput provides software-emulated proximity.
Pressure offset on worn-out tools
When a tool is used for an extended period it can wear down physically. A worn-down tool may never return a zero pressure value. Even when hovering above the surface, the pressure value returned by the tool is nonzero, creating a fake surface touch and making interaction with the tablet less predictable.
libinput automatically detects pressure offsets and rescales the remaining pressure range into the available range, making pressure-offsets transparent to the caller. A tool with a pressure offset will thus send a 0 pressure value for the detected offset and nonzero pressure values for values higher than that offset.
Some limitations apply to avoid misdetection of pressure offsets, specifically:
- pressure offset is only detected on proximity in, and if a device is capable of detection distances,
- pressure offset is only detected if the distance between the tool and the tablet is high enough,
- pressure offset is only used if it is 20% or less of the pressure range available to the tool. A pressure offset higher than 20% indicates either a misdetection or a tool that should be replaced, and
- if a pressure value less than the current pressure offset is seen, the offset resets to that value.
Pressure offsets are not detected on LIBINPUT_TABLET_TOOL_TYPE_MOUSE and LIBINPUT_TABLET_TOOL_TYPE_LENS tools.
Tracking unique tools
Some tools provide hardware information that enables libinput to uniquely identify the physical device. For example, tools compatible with the Wacom Intuos 4, Intuos 5, Intuos Pro and Cintiq series are uniquely identifiable through a serial number. libinput does not specify how a tool can be identified uniquely, a caller should use libinput_tablet_tool_is_unique() to check if the tool is unique.
libinput creates a struct libinput_tablet_tool on the first proximity in of this tool. By default, this struct is destroyed on proximity out and re-initialized on the next proximity in. If a caller keeps a reference to the tool by using libinput_tablet_tool_ref() libinput re-uses this struct whenever that same physical tool comes into proximity on any tablet recognized by libinput. It is possible to attach tool-specific virtual state to the tool. For example, a graphics program such as the GIMP may assign a specific color to each tool, allowing the artist to use the tools like physical pens of different color. In multi-tablet setups it is also possible to track the tool across devices.
If the tool does not have a unique identifier, libinput creates a single struct libinput_tablet_tool per tool type on each tablet the tool is used on.
Vendor-specific tablet tool types
libinput supports a number of high-level tool types that describe the general interaction expected with the tool. For example, a user would expect a tool of type LIBINPUT_TABLET_TOOL_TYPE_PEN to interact with a graphics application taking pressure and tilt into account. The default virtual tool assigned should be a drawing tool, e.g. a virtual pen or brush. A tool of type LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be mapped to an eraser-like virtual tool. See libinput_tablet_tool_type for the list of all available tools.
Vendors may provide more fine-grained information about the tool in use by adding a hardware-specific tool ID. libinput provides this ID to the caller with libinput_tablet_tool_get_tool_id() but makes no promises about the content or format of the ID.
libinput currently supports Wacom-style tool IDs as provided on the Wacom Intuos 3, 4, 5, Wacon Cintiq and Wacom Intuos Pro series. The tool ID can be used to distinguish between e.g. a Wacom Classic Pen or a Wacom Pro Pen. It is the caller's responsibility to interpret the tool ID.
Out-of-bounds motion events
Some tablets integrated into a screen (e.g. Wacom Cintiq 24HD, 27QHD and 13HD series, etc.) have a sensor larger than the display area. libinput uses the range advertised by the kernel as the valid range unless device-specific quirks are present. Events outside this range will produce coordinates that may be negative or larger than the tablet's width and/or height. It is up to the caller to ignore these events.
In the image above, the display area is shown in black. The red area around the display illustrates the sensor area that generates input events. Events within this area will have negative coordinate or coordinates larger than the width/height of the tablet.
If events outside the logical bounds of the input area are scaled into a custom range with libinput_event_tablet_tool_get_x_transformed() and libinput_event_tablet_tool_get_y_transformed() the resulting value may be less than 0 or larger than the upper range provided. It is up to the caller to test for this and handle or ignore these events accordingly.
