fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-02-04 02:20:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: fix and improve the tablet documentation

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2016-01-05 13:19:56 +10:00
parent 665daba9a9
commit 8f0016ba8a
2 changed files with 74 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
doc/tablet-support.dox
View file

@ -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.
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.
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
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.
*/

42
src/libinput.h
View file

@ -145,6 +145,9 @@ enum libinput_pointer_axis_source {
* rather than coming from the device directly. Depending on the hardware it
* is possible to track the same physical tool across multiple
* struct libinput_device devices, see @ref tablet-serial-numbers.
*
* This struct is refcounted, use libinput_tablet_tool_ref() and
* libinput_tablet_tool_unref().
*/
struct libinput_tablet_tool;
@ -1530,7 +1533,7 @@ libinput_event_tablet_tool_get_y(struct libinput_event_tablet_tool *event);
* Returns the current pressure being applied on the tool in use, normalized
* to the range [0, 1].
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1544,7 +1547,7 @@ libinput_event_tablet_tool_get_pressure(struct libinput_event_tablet_tool *event
* Returns the current distance from the tablet's sensor, normalized to the
* range [0, 1].
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1558,7 +1561,7 @@ libinput_event_tablet_tool_get_distance(struct libinput_event_tablet_tool *event
* Returns the current tilt along the X axis of the tablet's current logical
* orientation, normalized to the range [-1, 1].
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1572,7 +1575,7 @@ libinput_event_tablet_tool_get_tilt_x(struct libinput_event_tablet_tool *event);
* Returns the current tilt along the Y axis of the tablet's current logical
* orientation, normalized to the range [-1, 1].
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1592,7 +1595,7 @@ libinput_event_tablet_tool_get_tilt_y(struct libinput_event_tablet_tool *event);
* LIBINPUT_TABLET_TOOL_TYPE_BRUSH, the logical neutral position is with the
* buttons pointing up.
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1608,7 +1611,7 @@ libinput_event_tablet_tool_get_rotation(struct libinput_event_tablet_tool *event
* the logical center of the axis. This axis is available on e.g. the Wacom
* Airbrush.
*
* If this axis does not exist on the device, this function returns 0.
* If this axis does not exist on the current tool, this function returns 0.
*
* @param event The libinput tablet event
* @return The current value of the the axis
@ -1684,12 +1687,12 @@ libinput_event_tablet_tool_get_y_transformed(struct libinput_event_tablet_tool *
* @ingroup event_tablet
*
* Returns the tool that was in use during this event.
* By default, a struct libinput_tablet_tool is created on proximity in and
* destroyed on proximity out. The lifetime of the tool may be extended by
* using libinput_tablet_tool_ref() to increment the reference count of the
* tool. This guarantees that the same struct will be used whenever the same
* physical tool comes back into proximity.
*
* If the caller holds at least one reference (see
* libinput_tablet_tool_ref()), this struct is used whenever the
* tools enters proximity. Otherwise, if no references remain when the tool
* leaves proximity, the tool may be destroyed.
*
* @note Physical tool tracking requires hardware support. If unavailable,
* libinput creates one tool per type per tablet. See @ref
* tablet-serial-numbers for more details.
@ -1795,7 +1798,8 @@ libinput_event_tablet_tool_get_time_usec(struct libinput_event_tablet_tool *even
/**
* @ingroup event_tablet
*
* Return the type of tool type for a tool object
* Return the type of tool type for a tool object, see @ref
* tablet-tool-types for details.
*
* @param tool The libinput tool
* @return The tool type for this tool object
@ -1810,7 +1814,8 @@ libinput_tablet_tool_get_type(struct libinput_tablet_tool *tool);
*
* Return the tool ID for a tool object. If nonzero, this number identifies
* the specific type of the tool with more precision than the type returned in
* libinput_tablet_tool_get_type(). Not all tablets support a tool ID.
* libinput_tablet_tool_get_type(), see @ref tablet-tool-types. Not all
* tablets support a tool ID.
*
* Tablets known to support tool IDs include the Wacom Intuos 3, 4, 5, Wacom
* Cintiq and Wacom Intuos Pro series.
@ -1831,6 +1836,8 @@ libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool);
*
* @param tool The tool to increment the ref count of
* @return The passed tool
*
* @see libinput_tablet_tool_unref
*/
struct libinput_tablet_tool *
libinput_tablet_tool_ref(struct libinput_tablet_tool *tool);
@ -1843,6 +1850,8 @@ libinput_tablet_tool_ref(struct libinput_tablet_tool *tool);
*
* @param tool The tool to decrement the ref count of
* @return NULL if the tool was destroyed otherwise the passed tool
*
* @see libinput_tablet_tool_ref
*/
struct libinput_tablet_tool *
libinput_tablet_tool_unref(struct libinput_tablet_tool *tool);
@ -1939,6 +1948,8 @@ libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool,
*
* @param tool A tablet tool
* @return 1 if the tool can be uniquely identified, 0 otherwise.
*
* @see libinput_tablet_tool_get_serial
*/
int
libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
@ -1947,10 +1958,13 @@ libinput_tablet_tool_is_unique(struct libinput_tablet_tool *tool);
* @ingroup event_tablet
*
* Return the serial number of a tool. If the tool does not report a serial
* number, this function returns zero.
* number, this function returns zero. See @ref tablet-serial-numbers for
* details.
*
* @param tool The libinput tool
* @return The tool serial number
*
* @see libinput_tablet_tool_is_unique
*/
uint64_t
libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool);