Document how raised touches should be reported
It wasn't immediately clear before whether a raised touch should be
reported one last time with tracking_id = -1 in its FingerState, or just
dropped from the fingers array altogether. It turns out to be the latter
[0], so add some comments to make that clear.
Also move the information from a comment that had somehow been separated
from the FingerState struct, while we're at it.
[0]: https://crsrc.org/c/ui/events/ozone/evdev/libgestures_glue/gesture_interpreter_libevdev_cros.cc;l=199;drc=3e1a26c44c024d97dc9a4c09bbc6a2365398ca2c
BUG=None
TEST=emerge-volteer chromeos-base/gestures
Change-Id: I8325a1b9bfedaa88c9a5d15a85d1b7d1b3498e59
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/gestures/+/4360158
Tested-by: Harry Cutts <hcutts@chromium.org>
Auto-Submit: Harry Cutts <hcutts@chromium.org>
Reviewed-by: Torsha Banerjee <torsha@google.com>
Code-Coverage: Torsha Banerjee <torsha@google.com>
Reviewed-by: Sean O'Brien <seobrien@chromium.org>
Commit-Queue: Harry Cutts <hcutts@chromium.org>
diff --git a/include/gestures.h b/include/gestures.h
index f21d531..f3005a0 100644
--- a/include/gestures.h
+++ b/include/gestures.h
@@ -106,15 +106,6 @@
#endif // __cplusplus
};
-// position is the (x,y) cartesian coord of the finger on the trackpad.
-// touch_major/minor are the large/small radii of the ellipse of the touching
-// finger. width_major/minor are also radii, but of the finger itself,
-// including a little bit that isn't touching. So, width* is generally a tad
-// larger than touch*.
-// tracking_id: If a finger is the same physical finger across two
-// consecutive frames, it must have the same tracking id; if it's a different
-// finger, it may (should) have a different tracking id.
-
// Warp: If a finger has the 'warp' flag set for an axis, it means that while
// the finger may have moved, it should not cause any motion in that direction.
// This may occur is some situations where we thought a finger was in one place,
@@ -168,16 +159,27 @@
#define GESTURES_FINGER_WARP_Y (GESTURES_FINGER_WARP_Y_NON_MOVE | \
GESTURES_FINGER_WARP_Y_MOVE)
-// Describes a single contact on a touch surface. Unless otherwise noted, the
-// fields have the same meaning as the equivalent ABS_MT_... axis in the Linux
-// evdev protocol.
+// Describes a single contact on a touch surface. Generally, the fields have the
+// same meaning as the equivalent ABS_MT_... axis in the Linux evdev protocol.
struct FingerState {
+ // The large and small radii of the ellipse of the finger touching the pad.
float touch_major, touch_minor;
+
+ // The large and small radii of the ellipse of the finger, including parts
+ // that are hovering over the pad but not quite touching. Devices normally
+ // don't report these values, in which case they should be left at 0.
float width_major, width_minor;
float pressure;
float orientation;
+
float position_x;
float position_y;
+
+ // A number that identifies a single physical finger across consecutive
+ // frames. If a finger is the same physical finger across two consecutive
+ // frames, it must have the same tracking ID; if it's a different finger, it
+ // should have a different tracking ID. It should be ≥ 0 (see documentation
+ // comment for HardwareState::fingers).
short tracking_id;
// A bit field of flags that are used internally by the library. (See the
@@ -229,8 +231,13 @@
unsigned short finger_cnt;
// The number of fingers touching the pad, which may be more than finger_cnt.
unsigned short touch_cnt;
- // A pointer to finger_cnt FingerState structs representing the contacts
- // currently being tracked.
+ // A pointer to an array of FingerState structs with finger_cnt entries,
+ // representing the contacts currently being tracked. The order in which
+ // FingerStates appear need not be stable between HardwareStates — only the
+ // tracking ID is used to track individual contacts over time. Accordingly,
+ // when a finger is lifted from the pad (and therefore its ABS_MT_TRACKING_ID
+ // becomes -1), the client should simply stop including it in this array,
+ // rather than including a final FingerState for it.
struct FingerState* fingers;
// Mouse axes, which have the same meanings as the Linux evdev axes of the
