From 4677c48ab66c90cda2b66f57061401482f6d9f09 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 16 Nov 2015 16:36:05 +1000 Subject: doc: tablet documentation updates Signed-off-by: Peter Hutterer Reviewed-by: Hans de Goede --- doc/svg/tablet.svg | 199 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/tablet-support.dox | 52 ++++++++++++- src/libinput.h | 5 +- 3 files changed, 252 insertions(+), 4 deletions(-) create mode 100644 doc/svg/tablet.svg diff --git a/doc/svg/tablet.svg b/doc/svg/tablet.svg new file mode 100644 index 00000000..7a9dda83 --- /dev/null +++ b/doc/svg/tablet.svg @@ -0,0 +1,199 @@ + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + 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; diff --git a/src/libinput.h b/src/libinput.h index be815e7b..a9eee3cc 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -139,6 +139,9 @@ enum libinput_pointer_axis_source { * * Available axis types for a device. It must have the @ref * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. + * + * For details on the interpretation of these axes see + * libinput_event_tablet_tool_get_axis_value(). */ enum libinput_tablet_tool_axis { LIBINPUT_TABLET_TOOL_AXIS_X = 1, @@ -1518,7 +1521,7 @@ libinput_event_tablet_tool_get_tool(struct libinput_event_tablet_tool *event); * Used to check whether or not a tool came in or out of proximity during an * event of type @ref LIBINPUT_EVENT_TABLET_TOOL_PROXIMITY. * - * See @ref fake-proximity for recommendations on proximity handling. + * See @ref tablet-fake-proximity for recommendations on proximity handling. * * @param event The libinput tablet event * @return The new proximity state of the tool from the event. -- cgit v1.2.3