Document dx/dy sign for moves, scrolls, and swipes

Which direction is meant by a negative or positive value appears to be
quite inconsistent between the various gesture types. As far as I can
tell, this is due to the history of how scrolling and its settings were
handled in the past. Adding comments stating which direction is
indicated by which sign of number (from observations of the gestures
reported when running on Android) should at least make this documented
confusion, rather than just confusion.

BUG=None
TEST=Verify the information against logs of reported gestures

Change-Id: Ie045deaa3610389aba5605c015760283cf7b6d12
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/gestures/+/4166157
Tested-by: Harry Cutts <hcutts@chromium.org>
Code-Coverage: Torsha Banerjee <torsha@google.com>
Commit-Queue: Harry Cutts <hcutts@chromium.org>
Reviewed-by: Sean O'Brien <seobrien@chromium.org>

1 files changed, 36 insertions, 6 deletions

diff --git a/include/gestures.h b/include/gestures.h
index 5a1acc9..e4f7cc2 100644
--- a/include/gestures.h
+++ b/include/gestures.h
@@ -261,13 +261,23 @@ struct HardwareState {
 // the ordinal_* fields.
 
 typedef struct {
-  float dx, dy;
+  // The movement in the X axis. Positive values indicate motion to the right.
+  float dx;
+  // The movement in the Y axis. Positive values indicate downwards motion.
+  float dy;
   float ordinal_dx, ordinal_dy;
 } GestureMove;
 
 // Represents scroll gestures on a touch device.
 typedef struct{
-  float dx, dy;
+  // The scroll movement in the X axis. Unlike with move gestures, *negative*
+  // values indicate the fingers moving to the right, unless the "Australian
+  // Scrolling" or "Invert Scrolling" properties are set.
+  float dx;
+  // The scroll movement in the Y axis. Unlike with move gestures, *negative*
+  // values indicate the fingers moving downwards, unless the "Australian
+  // Scrolling" or "Invert Scrolling" properties are set.
+  float dy;
   float ordinal_dx, ordinal_dy;
   // If set, stop_fling means that this scroll should stop flinging, thus
   // if an interpreter suppresses it for any reason (e.g., rounds the size
@@ -293,19 +303,39 @@ typedef struct {
 } GestureButtonsChange;
 
 typedef struct {
-  // fling velocity (valid when fling_state is GESTURES_FLING_START):
-  float vx, vy;
+  // The fling velocity in the X axis, only valid when fling_state is
+  // GESTURES_FLING_START. Unlike with move gestures, *negative* values indicate
+  // the fingers moving to the right, unless the "Australian Scrolling" or
+  // "Invert Scrolling" properties are set.
+  float vx;
+  // The fling velocity in the Y axis, only valid when fling_state is
+  // GESTURES_FLING_START. Unlike with move gestures, *negative* values indicate
+  // the fingers moving downwards, unless the "Australian Scrolling" or "Invert
+  // Scrolling" properties are set.
+  float vy;
   float ordinal_vx, ordinal_vy;
   unsigned fling_state:1;  // GESTURES_FLING_START or GESTURES_FLING_TAP_DOWN
 } GestureFling;
 
 typedef struct {
-  float dx, dy;
+  // The swipe movement in the X axis. Positive values indicate motion to the
+  // right.
+  float dx;
+  // The swipe movement in the Y axis. Unlike with move gestures, *negative*
+  // values indicate downwards motion, unless the "Australian Scrolling"
+  // property is set.
+  float dy;
   float ordinal_dx, ordinal_dy;
 } GestureSwipe;
 
 typedef struct {
-  float dx, dy;
+  // The swipe movement in the X axis. Positive values indicate motion to the
+  // right.
+  float dx;
+  // The swipe movement in the Y axis. Unlike with move gestures, *negative*
+  // values indicate downwards motion, unless the "Australian Scrolling"
+  // property is set.
+  float dy;
   float ordinal_dx, ordinal_dy;
 } GestureFourFingerSwipe;