libinput/doc/tablet-support.dox

/**
@page tablet-support Tablet support

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.

@image html tablet.svg "Illustration of a graphics tablet"

@section tablet-tools 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 @ref
LIBINPUT_DEVICE_CAP_TABLET_TOOL applies only to events generated by tools.

Touch events on the tablet itself are exposed
through the @ref LIBINPUT_DEVICE_CAP_TOUCH capability and are often found on
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.

@section tablet-tip 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 @ref 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 occur
at any time.

@section tablet-axes 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.

@image html tablet-axes.svg "Illustration of the distance, pressure and tilt axes"

The granularity and precision of these axes varies between tablet devices
and cannot usually be mapped into a physical unit.
libinput normalizes distance and pressure into a fixed positive 2-byte
integer range. The tilt axes are normalized into a signed 2-byte integer
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.

@section tablet-fake-proximity Handling of proximity events

libinput's @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY events represent the
physical proximity limits of the device. In some cases the caller should
emulate proximity based on the distance events. For example, the Wacom mouse
and lens cursor tools are usually used in relative mode, lying flat on the
tablet. A user typically expects that lifting the tool off the tablet to a
different location has the same effect as with a normal mouse. 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.

To enable normal use as a mouse it is recommended that the caller treats
proximity separate from libinput's proximity events. There is no simple way
to detect the proximity motion threshold, it is different on each tablet and
differs between tools. The recommended algorithm is to remember the minimum
distance value seen on the tool and assume a proximity out when the distance
exceeds a threshold above this minimum value. In pseudo-code:

@code
const double threshold = ...;
static double min;
static bool in_proximity;

double value;

value = libinput_event_tablet_tool_get_axis_value(device,
					      LIBINPUT_TABLET_TOOL_AXIS_DISTANCE);

if (value < min) {
	min = value;
	return;
} else if (in_proximity &&
	   value > min + threshold) {
	   in_proximity = false;
} else if (!in_proximity &&
	   value < min + threshold) {
	   in_proximity = true;
}
@endcode

@section tablet-pressure-offset 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 @ref LIBINPUT_TABLET_TOOL_TYPE_MOUSE
and @ref LIBINPUT_TABLET_TOOL_TYPE_LENS tools.

@section tablet-serial-numbers 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.

*/