Signed-off-by: Peter Hutterer <peter.hutte...@who-t.net>
---
doc/Makefile.am | 1 +
doc/page-hierarchy.dox | 3 ++-
doc/timestamps.dox | 36 ++++++++++++++++++++++++++++++++++++
src/libinput.h | 42 ++++++++++++++++++++++++++++++++++++++++++
4 files changed, 81 insertions(+), 1 deletion(-)
create mode 100644 doc/timestamps.dox
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:
+
+<pre>
+Time Touchpad Mouse
+---------------------------------
+t1 finger down
+t2 finger up
+t3 movement
+t4 tap timeout
+</pre>
+
+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.
+*/
diff --git a/src/libinput.h b/src/libinput.h
index 430fe18..54bbc7f 100644
--- a/src/libinput.h
+++ b/src/libinput.h
@@ -972,6 +972,9 @@ libinput_event_device_notify_get_base_event(struct
libinput_event_device_notify
/**
* @ingroup event_keyboard
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event
*/
uint32_t
@@ -980,6 +983,9 @@ libinput_event_keyboard_get_time(struct
libinput_event_keyboard *event);
/**
* @ingroup event_keyboard
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event in microseconds
*/
uint64_t
@@ -1035,6 +1041,9 @@ libinput_event_keyboard_get_seat_key_count(
/**
* @ingroup event_pointer
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event
*/
uint32_t
@@ -1043,6 +1052,9 @@ libinput_event_pointer_get_time(struct
libinput_event_pointer *event);
/**
* @ingroup event_pointer
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event in microseconds
*/
uint64_t
@@ -1400,6 +1412,9 @@ libinput_event_pointer_get_base_event(struct
libinput_event_pointer *event);
/**
* @ingroup event_touch
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event
*/
uint32_t
@@ -1408,6 +1423,9 @@ libinput_event_touch_get_time(struct libinput_event_touch
*event);
/**
* @ingroup event_touch
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event in microseconds
*/
uint64_t
@@ -1564,6 +1582,9 @@ libinput_event_touch_get_base_event(struct
libinput_event_touch *event);
/**
* @ingroup event_gesture
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event
*/
uint32_t
@@ -1572,6 +1593,9 @@ libinput_event_gesture_get_time(struct
libinput_event_gesture *event);
/**
* @ingroup event_gesture
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @return The event time for this event in microseconds
*/
uint64_t
@@ -2300,6 +2324,9 @@ libinput_event_tablet_tool_get_seat_button_count(struct
libinput_event_tablet_to
/**
* @ingroup event_tablet
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput tablet tool event
* @return The event time for this event
*/
@@ -2309,6 +2336,9 @@ libinput_event_tablet_tool_get_time(struct
libinput_event_tablet_tool *event);
/**
* @ingroup event_tablet
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput tablet tool event
* @return The event time for this event in microseconds
*/
@@ -2735,6 +2765,9 @@ libinput_event_tablet_pad_get_mode_group(struct
libinput_event_tablet_pad *event
/**
* @ingroup event_tablet
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput tablet pad event
* @return The event time for this event
*/
@@ -2744,6 +2777,9 @@ libinput_event_tablet_pad_get_time(struct
libinput_event_tablet_pad *event);
/**
* @ingroup event_tablet_pad
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput tablet pad event
* @return The event time for this event in microseconds
*/
@@ -2799,6 +2835,9 @@ libinput_event_switch_get_base_event(struct
libinput_event_switch *event);
/**
* @ingroup event_switch
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput switch event
* @return The event time for this event
*/
@@ -2808,6 +2847,9 @@ libinput_event_switch_get_time(struct
libinput_event_switch *event);
/**
* @ingroup event_switch
*
+ * @note Timestamps may not always increase. See @ref event_timestamps for
+ * details.
+ *
* @param event The libinput switch event
* @return The event time for this event in microseconds
*/
--
2.9.3
_______________________________________________
wayland-devel mailing list
wayland-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/wayland-devel
