Move scroll information into a new class.

Using labels only to mark smooth scrolling axes disallows scrolling from
hardware events (e.g. a mouse wheel). If those axes are marked as scrolling
axes instead, the clients lose information which hardware axis this event
corresponds to.

For example, on Wacom devices, the client can benefit from smooth scrolling
on the strip or wheel event but may still require the knowledge whether the
axis is a vertical strip (e.g. Intuos3) or a absolute scrolling wheel (e.g.
Intuos4).

Thus, add a new class to XIQueryDevice that represents scrolling information
on a valuator. One of these ScrollClass may exist for each ValuatorClass if
that valuator is a scrolling valuator. The increment field of this class
removes the requirement for 1.0 == 1 unit of scrolling.

This isn't true in most cases, especially where physical scroll axes are
involved. Wacom Intuos4 scroll rings have a unit size of 3.0 and the driver
historically sent one scroll event per 3.0 increment or decrement. Mapping
one scroll event to 1.0 makes the ring mostly unusable through legacy
button events.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

3 files changed, 90 insertions, 15 deletions

diff --git a/XI2.h b/XI2.h
index 29ffdd1..18dd172 100644
--- a/XI2.h
+++ b/XI2.h
@@ -141,6 +141,15 @@
 #define XIKeyClass                              0
 #define XIButtonClass                           1
 #define XIValuatorClass                         2
+#define XIScrollClass                           3
+
+/* Scroll class types */
+#define XIScrollTypeVertical                    1
+#define XIScrollTypeHorizontal                  2
+
+/* Scroll class flags */
+#define XIScrollFlagNoEmulation                 (1 << 0)
+#define XIScrollFlagPreferred                   (1 << 1)
 
 /* Device event flags (common) */
 /* Device event flags (key events only) */
diff --git a/XI2proto.h b/XI2proto.h
index 8977e87..adcd0f3 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -188,6 +188,21 @@ typedef struct {
     uint16_t    pad2;
 } xXIValuatorInfo;
 
+/***
+ * Denotes a scroll valuator on a device.
+ * One XIScrollInfo describes exactly one scroll valuator that must have a
+ * XIValuatorInfo struct.
+ */
+typedef struct {
+    uint16_t    type;           /**< Always ValuatorClass         */
+    uint16_t    length;         /**< Length in 4 byte units       */
+    uint16_t    sourceid;       /**< source device for this class */
+    uint16_t    number;         /**< Valuator number              */
+    uint16_t    scroll_type;    /**< ::XIScrollTypeVertical, ::XIScrollTypeHorizontal */
+    uint16_t    pad0;
+    uint32_t    flags;          /**< ::XIScrollFlagEmulate, ::XIScrollFlagPreferred   */
+    FP3232      increment;      /**< Increment for one unit of scrolling              */
+} xXIScrollInfo;
 
 /**
  * Used to select for events on a given window.
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 4acb5a8..2b13845 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -126,20 +126,31 @@ are able to provide scrolling events through multi-finger drag gestures, or
 simply dragging your finger along a designated strip along the side of the
 touchpad.
 
-Newer X servers may provide 'Rel Vert Scroll' and 'Rel Horiz Scroll' valuators
-to provide scroll events with more precision than the button events.  If these
-valuators are present on a device, the server must provide two-way emulation
-between these valuators and the legacy button events.  A cumulative value of
-1.0 in either magnitude is considered to be equivalent to one button event for
-the legacy events, e.g., -2.0 on 'Rel Vert Scroll' sends two button
-press/release events for button 4.  Likewise, a button press event for
-button 7 generates a Rel Horiz Scroll valuator event with a value of +1.0.
-
-Any server providing this behaviour marks all button 4/5/6/7 events with the
-XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag for raw
-events, to hint that applications should be using the new valuators in
-preference to the buttons.
-
+Newer X servers may provide scrolling information through valuators to
+provide scroll events with more precision than the button events. Valuators
+for axes sending scrolling information must have one ScrollClass for each
+scrolling axis.
+
+If scrolling valuators are present on a device, the server must provide
+two-way emulation between these valuators and the legacy button events for
+each delta unit of scrolling.
+
+One unit of scrolling in either direction is considered to be equivalent to
+one button event, e.g. for a unit size of 1.0, -2.0 on an valuator type
+Vertical sends two button press/release events for button 4. Likewise, a
+button press event for button 7 generates an event on the Horizontal
+valuator with a value of +1.0. The server may accumulate deltas of less than
+one unit of scrolling.
+
+Any server providing this behaviour marks emulated button or valuator events
+with the XIPointerEmulated flag for DeviceEvents, and the XIRawEmulated flag
+for raw events, to hint at applications which event is a hardware event.
+
+If more than one scroll valuator of the same type is present on a device,
+the valuator marked with Preferred is used to convert legacy button events
+into scroll valuator events. If no valuator is marked Preferred or more than
+one valuator is marked with Preferred, this should be considered a driver
+bug and the behaviour is implementation-dependent.
 
 4. The Master/Slave device hierarchy
 ------------------------------------
@@ -329,7 +340,7 @@ If major_version is less than 2, a BadValue error occurs.
                  name:                  LISTofCHAR8
                  classes:               LISTofCLASS }
 
-    CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS }
+    CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, SCROLLCLASS }
 
     BUTTONCLASS { type:                 ButtonClass
                   length:               CARD16
@@ -355,6 +366,20 @@ If major_version is less than 2, a BadValue error occurs.
                   resolution:           CARD32
                   mode:                 CARD8 }
 
+    SCROLLCLASS* {type:                 ScrollClass
+                  length:               CARD16
+                  sourceid:             CARD16
+                  axisnumber:           CARD16
+                  scroll_type:          SCROLLTYPE
+                  flags:                SETofSCROLLFLAGS
+                  increment:            FP3232 }
+
+    * since XI 2.1
+
+    SCROLLTYPE { Vertical, Horizontal }
+
+    SCROLLFLAGS { NoEmulation, Preferred }
+
 XIQueryDevice details information about the requested input devices.
 
     devices
@@ -457,6 +482,32 @@ The following classes may occur only once: ButtonClass, KeyClass
 An axis in Relative mode may specify min and max as a hint to the
 client. If no min and max information is available, both must be 0.
 
+    ScrollClass:
+    type
+        Always ScrollClass.
+    length
+        Length in 4 byte units.
+    sourceid
+        The device this class originates from.
+    axisnumber
+        Axis number that is referred to. This axis number must be listed in
+        the ValuatorClassInfo.
+    scroll_type:
+        Vertical for a vertical scrolling axis, Horizontal for a horizontal
+        scrolling axis.
+    flags:
+        A set of flags that apply to this scroll axis.
+        NoEmulation: no legacy scroll button events are generated for events
+                     on this scrolling axis.
+        Preferred: This axis is the preferred axis for emulating valuator
+                   events from legacy scroll button events.
+    increment:
+        The valuator delta equivalent to one positive unit of scrolling.
+
+A ScrollClass may only exist if the device has at least one ValuatorClass
+and each axisnumber listed in any ScrollClass. Only one ScrollClass may
+exist per ValuatorClass.
+
     ┌───
         XISelectEvents
             window:         Window