[RFC XI 2.1 - inputproto] Add touch classes and events, bump to 2.1
Chase Douglas
chase.douglas at canonical.com
Wed Nov 17 08:59:47 PST 2010
Introduce multitouch support through a new TouchClass, as well as new
TouchBegin, TouchEnd and TouchMotion events. Bump to version 2.1.
Based on an initial patch by Daniel Stone (headers) and Peter Hutterer
(protocol documentation).
Signed-off-by: Daniel Stone <daniel at fooishbar.org>
Signed-off-by: Chase Douglas <chase.douglas at canonical.com>
---
XI2.h | 19 +++++-
XI2proto.h | 25 ++++++++
XI2proto.txt | 191 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
configure.ac | 2 +-
4 files changed, 231 insertions(+), 6 deletions(-)
diff --git a/XI2.h b/XI2.h
index 6ba1377..5d407ea 100644
--- a/XI2.h
+++ b/XI2.h
@@ -36,6 +36,7 @@
#define XI_2_Major 2
#define XI_2_Minor 0
+#define XI_2_1_Minor 1
/* Property event flags */
#define XIPropertyDeleted 0
@@ -113,15 +114,23 @@
#define XISlaveKeyboard 4
#define XIFloatingSlave 5
-/* Device classes */
+/* Device classes: classes that are not identical to Xi 1.x classes must be
+ * numbered starting from 8. */
#define XIKeyClass 0
#define XIButtonClass 1
#define XIValuatorClass 2
+#define XITouchClass 8
+#define XITouchValuatorClass 9
/* Device event flags (common) */
/* Device event flags (key events only) */
#define XIKeyRepeat (1 << 16)
/* Device event flags (pointer events only) */
+#define XITouchPointer (1 << 24)
+
+/* Touch modes */
+#define XIDirectTouch 1
+#define XIDependentTouch 2
/* XI2 event mask macros */
#define XISetMask(ptr, event) (((unsigned char*)(ptr))[(event)>>3] |= (1 << ((event) & 7)))
@@ -151,7 +160,10 @@
#define XI_RawButtonPress 15
#define XI_RawButtonRelease 16
#define XI_RawMotion 17
-#define XI_LASTEVENT XI_RawMotion
+#define XI_TouchBegin 18
+#define XI_TouchEnd 19
+#define XI_TouchMotion 20
+#define XI_LASTEVENT XI_TouchMotion
/* NOTE: XI2LASTEVENT in xserver/include/inputstr.h must be the same value
* as XI_LASTEVENT if the server is supposed to handle masks etc. for this
* type of event. */
@@ -177,5 +189,8 @@
#define XI_RawButtonPressMask (1 << XI_RawButtonPress)
#define XI_RawButtonReleaseMask (1 << XI_RawButtonRelease)
#define XI_RawMotionMask (1 << XI_RawMotion)
+#define XI_TouchBeginMask (1 << XI_TouchBegin)
+#define XI_TouchEndMask (1 << XI_TouchEnd)
+#define XI_TouchMotionMask (1 << XI_TouchMotion)
#endif /* _XI2_H_ */
diff --git a/XI2proto.h b/XI2proto.h
index 84574a5..418c23d 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -188,6 +188,31 @@ typedef struct {
uint16_t pad2;
} xXIValuatorInfo;
+/**
+ * Denotes multitouch capability on a device.
+ */
+typedef struct {
+ uint16_t type; /**< Always TouchClass */
+ uint16_t length; /**< Length in 4 byte units */
+ uint16_t sourceid; /**< source device for this class */
+ uint8_t mode; /**< DirectTouch or DependentTouch */
+ uint8_t num_touches; /**< Maximum number of touches */
+} xXITouchInfo;
+
+/**
+ * Denotes a multitouch valuator capability on a device.
+ * One XITouchValuatorInfo describes exactly one valuator (axis) on the device.
+ */
+typedef struct {
+ uint16_t type; /**< Always TouchValuatorClass */
+ uint16_t length; /**< Length in 4 byte units */
+ uint16_t sourceid; /**< source device for this class */
+ uint16_t number; /**< Valuator number */
+ Atom label; /**< Axis label */
+ FP3232 min; /**< Min value */
+ FP3232 max; /**< Max value */
+ uint32_t resolution; /**< Resolutions in units/m */
+} xXITouchValuatorInfo;
/**
* Used to select for events on a given window.
diff --git a/XI2proto.txt b/XI2proto.txt
index 10f58c2..fd47643 100644
--- a/XI2proto.txt
+++ b/XI2proto.txt
@@ -1,6 +1,7 @@
The X Input Extension
Version 2.0
+ Version 2.1
Peter Hutterer
peter.hutterer at redhat.com
@@ -31,6 +32,40 @@ used on applications employing the core protocol. XI2 addresses both of these
issues by enabling devices to be both extended and core devices and providing
device information in each event (with the exception of core events).
+1.1 X Input Extension version 2.1 (XI 2.1)
+XI 2.1 introduces support for multi-touch devices. The traditional
+pointer/keyboard approach enforced by XI 2.0 with the master/slave device
+hierarchy is not always suitable for multi-touch devices that can provide a
+dynamic number of multiple independent input points per physical device.
+Furthermore, such devices are often direct input devices, the virtual
+abstraction of master devices is not necessary.
+
+The additions in XI 2.1 aim to:
+- provide backwards compatible pointer emulation for single-touch
+ interaction,
+- support a dynamic number of simultaneous touch points,
+- support devices that are both multi-touch and traditional pointer devices.
+
+XI 2.1 caters for two modes of touch input devices:
+- direct multi-touch input devices such as touch screens. These devices
+ provide independent touchpoints that can occur anywhere on the screen and
+ are usually the result of direct touch interaction.
+- indirect touch input devices such as multi-touch trackpads. These devices
+ provide independent touchpoints that may need to be interpreted
+ relative to the current position of the pointer on that same device. Such
+ interactions are usually the result of a gesture performed on the device.
+
+A device may change its touch mode at runtime. Clients are informed which
+type of touch device they are dealing with. See XIQueryDevice for more
+information.
+
+Touch device support is only available to clients supporting version 2.1 or
+later of the X Input Extension. Clients must use the XIQueryVersion request to
+announce support of this version.
+
+XI 2.1 requires devices to track touch points over time. Devices that cannot
+do so in hardware must employ software trackers to be useable with XI 2.1.
+
â§â§â§â§â§â§â§â§â§â§â§
2. Notations used in this document
@@ -149,7 +184,31 @@ to P is only attempted if neither the XI event, nor the core event has been
delivered on W. Once an event has been delivered as either XI or core event,
event processing stops.
-4.4. The ClientPointer principle
+4.4 Touch device support
+Touch event processing differs from normal event processing in ways, most
+notably in that touch events are processed partially out-of-band from
+pointer and keyboard events.
+
+Touch input follows a three-stage cycle: init - move - destroy, i.e.
+"init" the sequence by touching the device, "move" the current touch
+location, "destroy" the sequence by ceasing to touch the device.
+The init and destroy stage of this sequence are always present, the move
+stage is optional. Within this document, the term "touch sequence" is used to
+describe the above chain of events. A client wishing to receive touch events
+must register for all three touch events simultaneously.
+
+Touch events are sent to all clients registered for them on any window in the
+window tree from the root window to the child window directly under the touch.
+
+A touch event is not delivered according to the device hierarchy. All touch
+events are sent only through their originating slave devices.
+
+A device that sends touch events may also generate pointer events on demand.
+The decision of which touch events are converted into pointer events is
+implementation-specific. Emulated pointer/keyboard events follow the core
+and XI2 grab semantics.
+
+4.5. The ClientPointer principle
Many core protocol and some extension requests are ambiguous when multiple
master devices are available (e.g. QueryPointer does not specfy which pointer).
@@ -271,7 +330,7 @@ are required to be 0.
name: LISTofCHAR8
classes: LISTofCLASS }
- CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS }
+ CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, TOUCHCLASS*, TOUCHAXISCLASS* }
BUTTONCLASS { type: ButtonClass
length: CARD16
@@ -296,6 +355,26 @@ are required to be 0.
value: FP3232
resolution: CARD32 }
+ TOUCHCLASS* { type: TouchClass
+ length: CARD16
+ sourceid: CARD16
+ mode: TOUCHMODE
+ num_touches: CARD16 }
+
+ TOUCHAXISCLASS* {
+ type: TouchAxisClass
+ length: CARD16
+ sourceid: CARD16
+ axisnumber: CARD16
+ label: ATOM
+ min: FP3232
+ max: FP3232
+ resolution: CARD32 }
+
+ TOUCHMODE* { DirectTouch, DependentTouch }
+
+ * since XI 2.1
+
XIQueryDevice details information about the requested input devices.
devices
@@ -397,6 +476,53 @@ are required to be 0.
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.
+ XI 2.1:
+
+ TouchClass:
+ type
+ Always TouchClass.
+ length
+ Length in 4 byte units.
+ sourceid
+ The device this class originates from.
+ mode
+ The device type of the touch device. Touch sequences from a device
+ of type DirectTouch should be interpreted as directly occuring on
+ the position they are reported on. Touch sequences from a device of
+ type DependentTouch should be interpreted as dependent of the
+ current position of the pointer.
+ num_touches
+ The maximum number of sumultaneous touchpoints the device may send.
+ If num_touches is 0, the number of supported touches is unknown.
+
+ A device with a TouchClass must provide one or more TOUCHAXISCLASS
+ specifiers.
+
+ TouchAxisClass:
+ type
+ Always TouchAxisClass.
+ length
+ Length in 4 byte units.
+ sourceid
+ The device this class originates from.
+ axisnumber
+ Axis number of this axis. The axis number is in device-native
+ order and potential axis mappings are ignored.
+ label
+ Atom specifying the axis name. An Atom of None specifies an unlabeled
+ axis.
+ min
+ Minimum value.
+ max
+ Minimum value.
+ resolution
+ Resolution in counts/meter.
+
+ Devices generating touch events must provide exactly one TouchClass and
+ one or more TouchAxisClasses. TouchAxisClasses and AxisClasses are not
+ interchangable. A TouchAxisClass may only be part of a touch event,
+ whereas an AxisClass may only be part of non-touch events.
+
┌───
XISelectEvents
window: Window
@@ -1338,6 +1464,10 @@ Version 2.0:
FocusIn
FocusOut
PropertyEvent
+Version 2.1:
+ TouchBegin
+ TouchMotion
+ TouchEnd
All events have a set of common fields specified as EVENTHEADER.
@@ -1481,13 +1611,15 @@ EVENTHEADER { type: BYTE
DEVICEEVENTFLAGS (all events): none
DEVICEEVENTFLAGS (key events only): { KeyRepeat }
- DEVICEEVENTFLAGS (pointer events only): none
+ DEVICEEVENTFLAGS (pointer events only): { TouchPointer }
An XIDeviceEvent is generated whenever the logical state of a device
changes in response to a button press, a button release, a motion, a key
press or a key release. The event type may be one of KeyPress,
KeyRelease, ButtonPress, ButtonRelease, Motion.
+ XI 2.1: The event type may also be TouchBegin, TouchMotion, or TouchEnd.
+
detail
The button number or key code, or 0.
root
@@ -1505,6 +1637,8 @@ EVENTHEADER { type: BYTE
buttons_len
The length of buttons in 4 byte units.
+ XI 2.1: For event types TouchBegin, TouchMotion, TouchEnd, buttons_len
+ is zero.
valuators_len
The length of valuators in 4 byte units.
sourceid
@@ -1517,8 +1651,12 @@ EVENTHEADER { type: BYTE
Button state before the event.
valuators
Bitmask of valuators provided in axisvalues.
+ XI 2.1: For event types TouchBegin, TouchMotion, TouchEnd, the
+ valuators are those specified as TouchAxisClass.
axisvalues
Valuator data in device-native resolution.
+ XI 2.1: For event types TouchBegin, TouchMotion, TouchEnd, the
+ valuators are those specified as TouchAxisClass.
flags
Miscellaneous information about this event; the union of the
common flag set and either the key or pointer flag set,
@@ -1526,6 +1664,10 @@ EVENTHEADER { type: BYTE
KeyRepeat means that this event is for repeating purposes, and
the physical state of the key has not changed. This is only
valid for KeyPress events.
+ TouchPointer means that this event is an emulated pointer event caused
+ by a touch device. A client listening to touch events and pointer
+ events should ignore TouchPointer events to avoid duplicate
+ processing.
Modifier state in mods is detailed as follows:
base_mods
@@ -1543,6 +1685,25 @@ EVENTHEADER { type: BYTE
locked_group
XKB locked group state.
+ XI 2.1:
+
+ A TouchBegin event is generated whenever a new touch sequence initializes
+ A TouchEnd event is generated whenever a touch sequence ceases. A
+ TouchMotion event is generated whenever a touch axis valuator value
+ changes.
+
+ The average finger size is significantly larger than one pixel. The
+ selection of the hotspot of a touchpoint is implementation dependent and
+ may not be the logical center of the touch.
+
+ Touch tracking IDs are always provided through one of the touch axis
+ valuators. Its value is always provided in every touch event. Tracking IDs
+ are represented as unsigned 32-bit values and are required to increase in
+ value for each new touch. Values will wrap back to 0 upon reaching the
+ numerical limit of IDs.
+
+ Touch events do not generate enter/leave events.
+
┌───
RawEvent
EVENTHEADER
@@ -1675,3 +1836,27 @@ EVENTHEADER { type: BYTE
â§â§â§â§â§â§â§â§â§â§â§
+
+
+Appendix A: XI 2.1 Use-cases
+
+All use-cases that include the receiving and processing of touch events
+require the client to announce XI 2.1 support in the XIQueryVersion request.
+
+∙ Client C wants to process touch events from a device D on window W.
+ ⊳ C registers for XITouch{Begin|Motion|End}Event from D on W.
+ ⊳ C receives XITouchBeginEvent whenever a touch sequence starts within
+ W's borders.
+ ⊳ C receives XITouchMotionEvents whenever a touch axis valuator value
+ changes for a touch that began within W's borders.
+ ⊳ C receives XITouchEndEvent whenever a touch that began within W's
+ borders ceases.
+
+∙ Driver DRV provides touch support from tracked device D:
+ ⊳ DRV initializes a TouchClass for the device and a TouchAxisClass for
+ each axis available on the device.
+ ⊳ DRV parses D's device protocol and selects one touch sequence to be
+ emulated as pointer event.
+ ⊳ DRV calls the respective input driver API with the touch sequence
+ data. The touch sequence emulating a pointer has the respective flag
+ set. DRV does not submit pointer data for any touchpoint.
diff --git a/configure.ac b/configure.ac
index 7466dc3..894d2cd 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,5 +1,5 @@
AC_PREREQ([2.60])
-AC_INIT([InputProto], [2.0], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
+AC_INIT([InputProto], [2.0.99.1], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AM_INIT_AUTOMAKE([foreign dist-bzip2])
AM_MAINTAINER_MODE
--
1.7.1
More information about the xorg-devel
mailing list