diff options
Diffstat (limited to 'doc/tablet-support.dox')
| -rw-r--r-- | doc/tablet-support.dox | 52 |
1 files changed, 49 insertions, 3 deletions
diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox index 47ad0054..24d08d20 100644 --- a/doc/tablet-support.dox +++ b/doc/tablet-support.dox @@ -6,7 +6,53 @@ 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. -@section fake-proximity Handling of proximity events +@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 @@ -31,8 +77,8 @@ static bool in_proximity; double value; -value = libinput_event_pointer_get_axis_value(device, - LIBINPUT_TABLET_AXIS_DISTANCE); +value = libinput_event_tablet_tool_get_axis_value(device, + LIBINPUT_TABLET_TOOL_AXIS_DISTANCE); if (value < min) { min = value; |