diff options
| -rw-r--r-- | doc/tablet-support.dox | 22 | ||||
| -rw-r--r-- | src/libinput.h | 52 |
2 files changed, 50 insertions, 24 deletions
diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox index 5468c6f..ac56e47 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 48f72a1..1cd6ea3 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 @@ -1650,6 +1652,18 @@ 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 + * * Return whether or not a tablet tool supports the specified axis * * @param tool The tool to check the axis capabilities of @@ -1678,18 +1692,6 @@ libinput_tablet_tool_has_button(struct libinput_tablet_tool *tool, /** * @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 - * * Return the serial number of a tool * * @note Not all tablets report a serial number along with the type of tool @@ -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 |