From 2d032019b6a46ae0ce837137a4890fc2f6409c7c Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Mon, 1 May 2017 19:58:13 +1000 Subject: doc: document the event timestamps Signed-off-by: Peter Hutterer --- doc/Makefile.am | 1 + doc/page-hierarchy.dox | 3 ++- doc/timestamps.dox | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 doc/timestamps.dox (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index 5391f22..382f64d 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -27,6 +27,7 @@ header_files = \ $(srcdir)/tablet-support.dox \ $(srcdir)/tapping.dox \ $(srcdir)/test-suite.dox \ + $(srcdir)/timestamps.dox \ $(srcdir)/tools.dox \ $(srcdir)/touchpad-jumping-cursors.dox \ $(srcdir)/touchpad-pressure.dox \ diff --git a/doc/page-hierarchy.dox b/doc/page-hierarchy.dox index 65749fe..1f0b735 100644 --- a/doc/page-hierarchy.dox +++ b/doc/page-hierarchy.dox @@ -24,10 +24,11 @@ - @subpage tablet-support -@page general General setup +@page general General - @subpage udev_config - @subpage seats +- @subpage timestamps @page misc Users diff --git a/doc/timestamps.dox b/doc/timestamps.dox new file mode 100644 index 0000000..a823c00 --- /dev/null +++ b/doc/timestamps.dox @@ -0,0 +1,36 @@ +/** + +@page timestamps Timestamps + +@section event_timestamps Event timestamps + +Most libinput events provide a timestamp in millisecond and/or microsecond +resolution. These timestamp usually increase monotonically, but libinput +does not guarantee that this always the case. In other words, it is possible +to receive an event with a timestamp earlier than the previous event. + +For example, if a touchpad has @ref tapping enabled, a button event may have a +lower timestamp than an event from a different device. Tapping requires the +use of timeouts to detect multi-finger taps and/or @ref tapndrag. + +Consider the following event sequences from a touchpad and a mouse: + +
+Time      Touchpad      Mouse
+---------------------------------
+t1       finger down
+t2        finger up
+t3                     movement
+t4       tap timeout
+
+ +For this event sequence, the first event to be sent to a caller is in +response to the mouse movement: an event of type @ref +LIBINPUT_EVENT_POINTER_MOTION with the timestamp t3. +Once the timeout expires at t4, libinput generates an event of +@ref LIBINPUT_EVENT_POINTER_BUTTON (press) with a timestamp t1 and an event +@ref LIBINPUT_EVENT_POINTER_BUTTON (release) with a timestamp t2. + +Thus, the caller gets events with timestamps in the order t3, t1, t2, +despite t3 > t2 > t1. +*/ -- cgit v1.2.3