path: root/doc
diff options
authorPeter Hutterer <>2015-12-15 08:29:00 +1000
committerPeter Hutterer <>2015-12-15 09:52:08 +1000
commit60b05c5696da4301b2333a0ac1d1c1b8da87ca7c (patch)
tree5b68b3d9b710bbacbfdbbd9d7146ce89d8a7457e /doc
parentdb852ef0dbb61eb68d26affb3d01c194e0242369 (diff)
doc: a couple of tablet documentation fixes
Signed-off-by: Peter Hutterer <>
Diffstat (limited to 'doc')
1 files changed, 22 insertions, 0 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
+@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