doc: document recommended handling of fake proximity events in the caller

Fake proximity events are context dependent and libinput doesn't have access
to the context. For example, fake proximity on the Wacom mouse is only required
in relative mode - but whether to use relative or absolute events is decided
in the caller.

Document what the recommended approach is since it's a bit quirky and leave it
at that.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Benjamin Tissoires <benjamin.tissoires@gmail.com>

doc/Makefile.am

@@ -15,6 +15,7 @@ header_files = \
 	$(srcdir)/scrolling.dox \
 	$(srcdir)/seats.dox \
 	$(srcdir)/t440-support.dox \
+	$(srcdir)/tablet-support.dox \
 	$(srcdir)/tapping.dox
 
 diagram_files = \

doc/tablet-support.dox

@@ -0,0 +1,49 @@
+/**
+@page tablet-support Tablet support
+
+This page provides details about the graphics tablet
+support in libinput. Note that the term "tablet" in libinput refers to
+graphics tablets only (e.g. Wacom Intuos), not to tablet devices like the
+Apple iPad.
+
+@section fake-proximity Handling of proximity events
+
+libinput's @ref LIBINPUT_EVENT_TABLET_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_pointer_get_axis_value(device,
+					      LIBINPUT_TABLET_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
+
+*/

src/libinput.h

@@ -1185,6 +1185,8 @@ libinput_event_tablet_get_tool(struct libinput_event_tablet *event);
  * Used to check whether or not a tool came in or out of proximity during an
  * event of type @ref LIBINPUT_EVENT_TABLET_PROXIMITY.
  *
+ * See @ref fake-proximity for recommendations on proximity handling.
+ *
  * @param event The libinput tablet event
  * @return The new proximity state of the tool from the event.
  */