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>

1 files changed, 21 insertions, 14 deletions

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 @@ struct HardwareProperties {
 #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 @@ struct HardwareProperties {
 #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 @@ struct HardwareState {
   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