From 60b05c5696da4301b2333a0ac1d1c1b8da87ca7c Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 15 Dec 2015 08:29:00 +1000 Subject: [PATCH] doc: a couple of tablet documentation fixes Signed-off-by: Peter Hutterer --- doc/tablet-support.dox | 22 ++++++++++++++++++ src/libinput.h | 52 +++++++++++++++++++++++------------------- 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox index 5468c6ff..ac56e47a 100644 --- a/doc/tablet-support.dox +++ b/doc/tablet-support.dox @@ -121,4 +121,26 @@ specifically: 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 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. + */ diff --git a/src/libinput.h b/src/libinput.h index 48f72a17..1cd6ea33 100644 --- a/src/libinput.h +++ b/src/libinput.h @@ -136,6 +136,7 @@ enum libinput_pointer_axis_source { /** * @ingroup device + * @struct libinput_tablet_tool * * Available axis types for a device. It must have the @ref * LIBINPUT_DEVICE_CAP_TABLET_TOOL capability. @@ -1346,7 +1347,7 @@ libinput_event_gesture_get_angle_delta(struct libinput_event_gesture *event); /** * @defgroup event_tablet Tablet events * - * Events that come from tablet devices. + * Events that come from tools on tablet devices. */ /** @@ -1497,15 +1498,15 @@ 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, each tool will stay valid for as long as it is being used, and is - * destroyed when another tool comes into proximity. However, 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 whenever the tool comes - * back into proximity of the tablet, that the same structure will be used to - * represent the tool. + * 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. * - * @note On tablets where the serial number of tools is not reported, each tool - * cannot be guaranteed to be unique. + * @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. * * @param event The libinput tablet event * @return The new tool triggering this event @@ -1639,7 +1640,8 @@ libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool); /** * @ingroup event_tablet * - * Increment the ref count of tool by one + * Increment the reference count of the tool by one. A tool is destroyed + * whenever the reference count reaches 0. See libinput_tablet_tool_unref(). * * @param tool The tool to increment the ref count of * @return The passed tool @@ -1647,6 +1649,18 @@ libinput_tablet_tool_get_tool_id(struct libinput_tablet_tool *tool); struct libinput_tablet_tool * libinput_tablet_tool_ref(struct libinput_tablet_tool *tool); +/** + * @ingroup event_tablet + * + * Decrement the reference count of the tool by one. When the reference + * count of tool reaches 0, the memory allocated for tool will be freed. + * + * @param tool The tool to decrement the ref count of + * @return NULL if the tool was destroyed otherwise the passed tool + */ +struct libinput_tablet_tool * +libinput_tablet_tool_unref(struct libinput_tablet_tool *tool); + /** * @ingroup event_tablet * @@ -1675,18 +1689,6 @@ int libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool, uint32_t code); -/** - * @ingroup event_tablet - * - * Decrement the ref count of tool by one. When the ref count of tool reaches 0, - * the memory allocated for tool will be freed. - * - * @param tool The tool to decrement the ref count of - * @return NULL if the tool was destroyed otherwise the passed tool - */ -struct libinput_tablet_tool * -libinput_tablet_tool_unref(struct libinput_tablet_tool *tool); - /** * @ingroup event_tablet * @@ -1705,7 +1707,9 @@ libinput_tablet_tool_get_serial(struct libinput_tablet_tool *tool); /** * @ingroup event_tablet * - * Return the user data associated with a tool object. + * Return the user data associated with a tool object. libinput does + * not manage, look at, or modify this data. The caller must ensure the + * data is valid. * * @param tool The libinput tool * @return The user data associated with the tool object @@ -1716,7 +1720,7 @@ libinput_tablet_tool_get_user_data(struct libinput_tablet_tool *tool); /** * @ingroup event_tablet * - * Set the user data associated with a tool object. + * Set the user data associated with a tool object, if any. * * @param tool The libinput tool * @param user_data The user data to associate with the tool object