summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorPeter Hutterer <peter.hutterer@who-t.net>2016-01-05 13:19:56 +1000
committerPeter Hutterer <peter.hutterer@who-t.net>2016-01-05 13:58:54 +1000
commit8f0016ba8a1f482f86e2ba423d327a908917d972 (patch)
treeb5aeecc4716183c644556e9846145c9cba70c1a9 /doc
parent665daba9a9c79b832b9b82e6f09cf0742f0e5446 (diff)
doc: fix and improve the tablet documentation
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Diffstat (limited to 'doc')
-rw-r--r--doc/tablet-support.dox96
1 files changed, 47 insertions, 49 deletions
diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
index fbe778da..90c2e098 100644
--- a/doc/tablet-support.dox
+++ b/doc/tablet-support.dox
@@ -16,11 +16,13 @@ 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.
+Touch events on the tablet integrated into a screen itself are exposed
+through the @ref LIBINPUT_DEVICE_CAP_TOUCH capability. Touch events on a
+standalone tablet are exposed through the @ref 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.
@section tablet-tip Tool tip events vs. button events
@@ -30,8 +32,8 @@ 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.
+unrelated to the tip. A button event is independent of the tip and can while
+the tip is down or up.
@section tablet-axes Special axes on tablet tools
@@ -44,53 +46,28 @@ additionally provide tilt information along the x and y axis.
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.
+libinput normalizes distance and pressure into the [0, 1] range and the tilt
+axes into the [-1, 1] range with 0 as the neutral point.
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.
+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
+libinput's @ref 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.
@section tablet-pressure-offset Pressure offset on worn-out tools
@@ -145,4 +122,25 @@ 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.
+@section tablet-tool-types 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 @ref 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 @ref LIBINPUT_TABLET_TOOL_TYPE_ERASER would normally be
+mapped to an eraser-like virtual tool. See @ref 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.
+
*/