doc: fix and improve the tablet documentation

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

2 files changed, 75 insertions, 63 deletions

diff --git a/doc/tablet-support.dox b/doc/tablet-support.dox
index fbe778da..90c2e098 100644
--- a/doc/tablet-support.dox
+++ b/doc/tablet-support.dox
@@ -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.
-
-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
+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.
+
+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.
+
 */
diff --git a/src/libinput.h b/src/libinput.h
index 71d28203..f1142340 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -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);