[PATCH (v5) inputproto 1/1] Add touch classes and events, bump to 2.1
Daniel Stone
daniel at fooishbar.org
Wed Jan 19 15:11:32 PST 2011
Introduce multitouch support through a new TouchClass, as well as new
TouchBegin, TouchEnd and TouchMotion events. Bump to version 2.1.
Signed-off-by: Daniel Stone <daniel at fooishbar.org>
Co-authored-by: Chase Douglas <chase.douglas at canonical.com>
Co-authored-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>
---
v5: Introduce separate TouchMotionUnowned and TouchOwnership events.
Elaborate a little on usecases.
XI2.h | 33 +++++-
XI2proto.h | 65 +++++++++-
XI2proto.txt | 395 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
configure.ac | 2 +-
4 files changed, 479 insertions(+), 16 deletions(-)
diff --git a/XI2.h b/XI2.h
index 6ba1377..3f4d2c3 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
@@ -65,6 +66,7 @@
#define XIGrabtypeKeycode 1
#define XIGrabtypeEnter 2
#define XIGrabtypeFocusIn 3
+#define XIGrabtypeTouchBegin 4
/* Passive grab modifier */
#define XIAnyModifier (1U << 31)
@@ -79,6 +81,11 @@
#define XIAsyncPair 4
#define XISyncPair 5
+/* XIAllowTouchEvents bitmask event-modes */
+#define XITouchOwnerAccept (1 << 0)
+#define XITouchOwnerReject (1 << 1)
+#define XITouchNoPointerEmulation (1 << 2)
+
/* DeviceChangedEvent change reasons */
#define XISlaveSwitch 1
#define XIDeviceChange 2
@@ -113,15 +120,27 @@
#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 << 16)
+/* Device event flags (touch events only) */
+#define XITouchOwner (1 << 16)
+#define XITouchOwnerAccepted (1 << 17)
+#define XITouchPendingFinish (1 << 18)
+
+/* 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 +170,12 @@
#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_TouchOwnership 20
+#define XI_TouchMotion 21
+#define XI_TouchMotionUnowned 22
+#define XI_LASTEVENT XI_TouchMotionUnowned
/* 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 +201,10 @@
#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_TouchOwnershipChangedMask (1 << XI_TouchOwnershipChanged)
+#define XI_TouchMotionMask (1 << XI_TouchMotion)
+#define XI_TouchMotionUnownedMask (1 << XI_TouchMotionUnowned)
#endif /* _XI2_H_ */
diff --git a/XI2proto.h b/XI2proto.h
index 84574a5..6a5280c 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -92,9 +92,10 @@
#define X_XIDeleteProperty 58
#define X_XIGetProperty 59
#define X_XIGetSelectedEvents 60
+#define X_XIAllowTouchEvents 61
/** Number of XI requests */
-#define XI2REQUESTS (X_XIGetSelectedEvents - X_XIQueryPointer + 1)
+#define XI2REQUESTS (X_XIAllowTouchEvents - X_XIQueryPointer + 1)
/** Number of XI2 events */
#define XI2EVENTS (XI_LASTEVENT + 1)
@@ -188,6 +189,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.
@@ -772,6 +798,20 @@ typedef struct {
} xXIGetPropertyReply;
#define sz_xXIGetPropertyReply 32
+/**
+ * Accept or reject a grabbed touch sequence.
+ */
+typedef struct {
+ uint8_t reqType;
+ uint8_t ReqType; /**< Always ::X_XIAllowTouchEvents */
+ uint16_t length; /**< Length in 4 byte units */
+ uint32_t touchid;
+ uint16_t deviceid;
+ uint8_t mode; /**< bitmask */
+ uint8_t pad;
+} xXIAllowTouchEventsReq;
+#define sz_xXIAllowTouchEventsReq 12
+
/*************************************************************************************
* *
* EVENTS *
@@ -857,7 +897,28 @@ typedef struct
} xXIDeviceChangedEvent;
/**
- * Default input event for pointer or keyboard input.
+ * The owner of a touch stream has passed on ownership to another client.
+ */
+typedef struct
+{
+ uint8_t type; /**< Always GenericEvent */
+ uint8_t extension; /**< XI extension offset */
+ uint16_t sequenceNumber;
+ uint32_t length; /**< Length in 4 byte units */
+ uint16_t evtype; /**< XI_TouchOwnership */
+ uint16_t deviceid; /**< Device that has changed */
+ Time time;
+ uint16_t sourceid; /**< Source of the new classes */
+ uint8_t reason; /**< ::XITouchOwnerReject */
+ uint8_t pad0;
+ uint32_t touchid;
+ uint32_t flags;
+ uint32_t pad1;
+ uint32_t pad2;
+} xXITouchOwnershipEvent;
+
+/**
+ * Default input event for pointer, keyboard or touch input.
*/
typedef struct
{
diff --git a/XI2proto.txt b/XI2proto.txt
index 10f58c2..d079ddb 100644
--- a/XI2proto.txt
+++ b/XI2proto.txt
@@ -1,11 +1,20 @@
The X Input Extension
Version 2.0
+ Version 2.1
Peter Hutterer
peter.hutterer at redhat.com
Red Hat, Inc.
+ Daniel Stone
+ daniel at fooishbar.org
+ Collabora, Ltd.
+
+ Chase Douglas
+ chase.douglas at canonical.com
+ Canonical, Ltd.
+
1. Introduction
@@ -31,6 +40,44 @@ 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:
+- support a dynamic number of simultaneous touch points,
+- support devices that are both multi-touch and traditional pointer devices.
+
+It is also hoped to provide backwards compatible pointer emulation for
+single-touch interaction, but the exact semantics of pointer emulation have
+not yet been determined. While it is likely that most of the semantics will
+remain implementation-defined, future revisions of the specification are
+likely to clarify and expand on pointer emulation behaviour.
+
+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 usable with XI 2.1.
+
❧❧❧❧❧❧❧❧❧❧❧
2. Notations used in this document
@@ -149,7 +196,68 @@ 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 a few 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 - move - ... - destroy,
+i.e. “init” the sequence by touching the device, “move” the current touch
+location any number of times, and finally “destroy” the sequence by ceasing
+to touch the device. The init and destroy stage of this sequence are always
+present, while 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.
+
+A touch sequence is only considered to be meaningful in its entirety: clients
+may not capture part of a touch sequence, interpret only that part, and then
+pass a partial touch sequence on to the next client. To this end, all clients
+with active “grabs” on the window hierarchy for a touch sequence receive events
+from that touch sequence, as well as the client with the deepest selection
+(i.e. furthest from the root window). Clients currently in control of the
+touch sequence receive TouchMotion events, whereas clients not in control
+receive TouchMotionUnowned events.
+
+Touch grabs are similar to standard input event grabs in that they take
+precedence over selections and are searched from the root window to the child
+window. The first grab found for a touch sequence will be the owner of that
+touch sequence, however events for that touch sequence will continue to be
+delivered to all clients with grabs in the window tree, as well as the client
+with the deepest selection. The grabbing client may either “accept” the
+touch, which claims the touch sequence and stops delivery to all other
+clients for the duration of the touch sequence, or “reject” the touch sequence,
+which will remove that client from the delivery set and pass ownership on to
+the next client.
+
+Window sets for direct device touches contain the windows from the root to the
+child in which the touch originated.
+
+Dependent device window sets depend on whether other touches are active. For
+the first dependent touch on a device, the window set contains the windows from
+the root to the current window underneath the position of the device's pointer.
+For subsequent touches on this device, the window set is identical to
+the window set of the first touch. Once all touches have been released, the
+window set is reset and re-calculated on the first subsequent touch.
+
+No touches from a dependent device may begin while the device is floating, as
+it does not have an associated pointer position to focus events.
+
+The delivery of touch events is not changed by any modifications to the window
+hierarchy after the window set has been determined for the touch, nor is it
+affected by new grabs or selections.
+
+A TouchEnd event will always be sent to a client when it will receive no more
+events from a particular touch, regardless of why (grab or selection removed,
+owner accepted, the client having rejected that touch, etc).
+
+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, however any pointer event generated from a touch
+event will have the TouchPointer flag set. 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 +379,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 +404,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 +525,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 simultaneous 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 for this axis.
+ max
+ Maximum value for this axis.
+ resolution
+ Resolution in counts/meter.
+
+ Devices generating touch events must provide exactly one TouchClass and
+ two 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
@@ -439,6 +614,14 @@ are required to be 0.
The mask for XIHierarchyEvents may only be selected for XIAllDevices.
Setting it for any other device results in a BadValue error.
+ A client selecting for any of XI_TouchBegin, XI_TouchMotion or XI_TouchEnd
+ must select for all three events at the same time, else BadValue will be
+ returned. A client selecting for XI_TouchMotionUnowned must select for all
+ three of the other touch events. If the selection for these touch events
+ overlaps a current selection by another client (e.g. selecting for a
+ specific device when another client has a selection for XIAllDevices), a
+ BadAccess error occurs.
+
┌───
XIGetSelectedEvents
window: Window
@@ -999,7 +1182,7 @@ are required to be 0.
└───
GRABTYPE { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
- GrabtypeFocusIn}
+ GrabtypeFocusIn, GrabtypeTouchBegin }
GRABMODIFIERINFO { status: Access
modifiers: CARD32 }
@@ -1015,7 +1198,8 @@ are required to be 0.
AllMasterDevices.
detail
The button number, or key symbol to grab for.
- Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
+ Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
+ GrabtypeTouchBegin.
grab_type
The type of grab to establish.
grab_window
@@ -1030,6 +1214,7 @@ are required to be 0.
releasing XIAllowEvents request or until the device grab is
released. Actual device input events are not lost while the device
is frozen; they are simply queued for later processing.
+ Must be Asynchronous for GrabtypeTouchBegin (see section 4.4).
mask_len
Length of mask in 4 byte units.
mask
@@ -1087,6 +1272,13 @@ are required to be 0.
- a passive grab of the same grab_type + modifier combination does not
does not exist on an ancestor of grab_window.
+ Or if grab_type is GrabtypeTouchBegin, a touch grab (see section 4.4)
+ begins if:
+ - a touch begins in grab_window or one of its ancestors, and
+ - the specified modifier keys are down, and
+ - a passive grab of the same grab_type + modifier combination does not
+ exist on an ancestor of grab_window.
+
A modifier of GrabAnyModifier is equivalent to issuing the request for
all possible modifier combinations (including no modifiers). A client
may request a grab for GrabAnyModifier and explicit modifier
@@ -1097,6 +1289,9 @@ are required to be 0.
A GrabtypeEnter or GrabtypeFocusIn grab is released when the
pointer or focus leaves the window and all of its descendants,
independent of the state of modifier keys.
+ A GrabtypeTouchBegin grab is released when the touch sequence ends,
+ or a client uses XIAllowTouchEvents to reject the touch and remove
+ itself from the touch delivery sequence.
Note that the logical state of a device (as seen by means of the
protocol) may lag the physical state if device event processing is
frozen.
@@ -1109,10 +1304,10 @@ are required to be 0.
with the same button or keycode and modifier combination, the
failed modifier combinations is returned in modifiers_return. If some
other client already has issued an XIPassiveGrabDevice request of
- grab_type XIGrabtypeEnter or XIGrabtypeFocusIn with the same
- grab_window and the same modifier combination, the failed modifier
- combinations are returned in modifiers_return. If num_modifiers_return
- is zero, all passive grabs have been successful.
+ grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, or XIGrabtypeTouchBegin
+ with the same grab_window and the same modifier combination, the failed
+ modifier combinations are returned in modifiers_return. If
+ num_modifiers_return is zero, all passive grabs have been successful.
If a button grab or enter grab activates, EnterNotify and LeaveNotify
events with mode Grab are generated as if the pointer were to suddenly
@@ -1133,6 +1328,11 @@ are required to be 0.
XIPassiveUngrabNotify are generated and sent to the grabbing client
before the grab deactivates.
+ See section 4.4 for additional notes on touch grabs, as they do not
+ behave like traditional grabs: in particular, they do not freeze the
+ device, and delivery of touch events continues even if the device is
+ frozen due to a grab by another client.
+
┌───
XIPassiveUngrabDevice
deviceid: DEVICEID
@@ -1149,7 +1349,8 @@ are required to be 0.
The device to establish the passive grab on.
detail
The button number or key symbol to ungrab.
- Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
+ Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
+ GrabtypeTouchBegin.
grab_type
The type of grab to establish.
grab_window
@@ -1308,6 +1509,40 @@ are required to be 0.
deleted from the device, and a XIPropertyNotify event is generated on
the device.
+ ┌───
+ XIAllowTouchEvents: (since XI 2.1)
+ deviceid: DEVICEID
+ touchid: CARD32
+ event_mode: SETofALLOWTOUCHMODEs
+ └───
+
+ ALLOWTOUCHMODE { TouchOwnerAccept, TouchOwnerReject,
+ TouchNoPointerEmulation }
+
+ The XIAllowTouchEvents request allows the current owner of a touch
+ sequence to direct further delivery.
+
+ deviceid
+ The grabbed device ID.
+ touchid
+ The ID of the currently-grabbed touch sequence.
+ event_mode
+ A bitmask of event modes for future delivery:
+ If TouchOwnerAccept is set, the client is deemed to have taken control
+ of the touch sequence, and no further events will be sent to any other
+ clients for this touch sequence. Additionally, if
+ TouchNoPointerEmulation is set, then no more emulated pointer events
+ will be generated from this touch sequence. Setting
+ TouchNoPointerEmulation with anything other than TouchOwnerAccept will
+ result in a BadValue error.
+ If TouchOwnerReject is set, the client is no longer interested in the
+ touch sequence, and ownership will be passed on to the next delivery
+ candidate (a grab on a child window, or a selection).
+
+ A BadValue error occurs if the touch ID is invalid, or BadAccess if this
+ client is not the current owner of the specified touchid. BadValue errors
+ also occur if an invalid value is given for event_mode.
+
8. Events:
@@ -1338,6 +1573,12 @@ Version 2.0:
FocusIn
FocusOut
PropertyEvent
+Version 2.1:
+ TouchBegin
+ TouchMotion
+ TouchMotionUnowned
+ TouchOwnership
+ TouchEnd
All events have a set of common fields specified as EVENTHEADER.
@@ -1481,15 +1722,20 @@ EVENTHEADER { type: BYTE
DEVICEEVENTFLAGS (all events): none
DEVICEEVENTFLAGS (key events only): { KeyRepeat }
- DEVICEEVENTFLAGS (pointer events only): none
+ DEVICEEVENTFLAGS (pointer events only): { TouchPointer }
+ DEVICEEVENTFLAGS (touch events only): { TouchPendingFinish }
+ DEVICEEVENTFLAGS (touch end events only): { TouchOwnerAccepted }
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,
+ TouchMotionUnowned, or TouchEnd.
+
detail
- The button number or key code, or 0.
+ The button number, key code, touch ID, or 0.
root
event
child
@@ -1517,8 +1763,12 @@ EVENTHEADER { type: BYTE
Button state before the event.
valuators
Bitmask of valuators provided in axisvalues.
+ XI 2.1: For event types TouchBegin, TouchMotion, TouchMotionUnowned, and
+ TouchEnd, the valuators are those specified as TouchAxisClass.
axisvalues
Valuator data in device-native resolution.
+ XI 2.1: For event types TouchBegin, TouchMotion, TouchMotionUnowned, and
+ 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 +1776,20 @@ 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. This is only valid for pointer events (MotionNotify,
+ ButtonPress, ButtonRelease).
+ TouchOwnerAccepted (for TouchEnd events only) means that the current
+ owner of the touch stream has “accepted” it, and this client will not
+ receive any further events from that touch sequence.
+ TouchPendingFinish (for touch events only) means that the touch
+ has physically ended, however another client still holds a grab, so the
+ touch should be considered alive until all grabbing clients have
+ accepted or passed on ownership. The touch will not generate any
+ further motion events once an event with TouchPendingFinish has been
+ received.
Modifier state in mods is detailed as follows:
base_mods
@@ -1543,6 +1807,28 @@ 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, or a flag (e.g. pending finish) has changed for that touch
+ sequence; this may result in a TouchMotion event being sent with zero
+ valuators. A TouchOwnership event is sent when a client becomes the owner
+ of a touch.
+
+ 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 provided in the detail field of touch events. Its
+ value is always provided in every touch event. Tracking IDs are
+ represented as unsigned 32-bit values and 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, and are not affected by
+ other grabs (including device freezing).
+
┌───
RawEvent
EVENTHEADER
@@ -1673,5 +1959,92 @@ EVENTHEADER { type: BYTE
what
Specifies what has been changed.
+XI 2.1:
+
+ ┌───
+ TouchOwnershipEvent (since XI 2.1):
+ EVENTHEADER
+ sourceid: DEVICEID
+ reason: TOUCHOWNERSHIPREASON
+ touchid: CARD32
+ flags: SETofTOUCHOWNERSHIPFLAGS
+ └───
+
+ TOUCHOWNERSHIPREASON: { XITouchOwnerAccept, XITouchOwnerReject }
+ TOUCHOWNERSHIPFLAGS: (none currently defined)
+
+ A TouchOwnershipEvent indicates that ownership has changed, and the client
+ is now the owner of the touch sequence specified by touchid. The reason
+ field optionally provides an indication of why this occurred.
+
+ sourceid
+ The source device that originally generated the event.
+ reason
+ The reason ownership changed; at present, XITouchOwnerReject is the
+ only defined reason.
+ touchid
+ The identifier of the touch sequence.
+ flags
+ A bitmask of flags for this event; none are currently defined.
+
❧❧❧❧❧❧❧❧❧❧❧
+
+
+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 calls XISelectEvent for
+ XI_Touch{Begin|Motion|MotionUnowned|Ownership|End} from D on W.
+ ⊳ C receives TouchBegin whenever a touch sequence starts within
+ W's borders.
+ ⊳ C receives a TouchOwnership event indicating that it is now the owner
+ of the touch sequence.
+ ⊳ C receives TouchMotion events whenever a touch axis valuator value
+ changes for a touch sequence it received a TouchBegin event for.
+ ⊳ C receives TouchEnd whenever a touch it received an TouchBegin event
+ for ceases.
+
+∙ Client C wants to process touch events from a device D on window W, while
+ client I wants to pre-process these events.
+ ⊳ C calls XISelectEvent for
+ XI_Touch{Begin|Motion|MotionUnowned|Ownership|End} from D on W.
+ ⊳ I calls XIPassiveGrab for
+ XI_Touch{Begin|Motion|MotionUnowned|Ownership|End} from D on a parent
+ window of W.
+ ⊳ I receives TouchBegin whenever a touch begins within window W, as well
+ as a TouchOwnership event indicating that it currently owns the touch
+ sequence. C receives a TouchBegin event as well, but without
+ TouchOwnership.
+ ⊳ When a touch axis valuator changes in this touch sequence, I receives a
+ TouchMotion event, while C receives a TouchMotionUnowned event. I may
+ process the events to determine if it is going to claim or reject the
+ touch, whereas C may perform reversible processing.
+ ⊳ If I decides it is going to claim the event for its exclusive
+ processing, it calls XIAllowTouchEvents with the XITouchOwnerAccept flag
+ set; at this point, C receives a TouchEnd event with the
+ TouchOwnerAccepted flag set, and undoes any processing it may have done
+ on the touch sequence. Further TouchMotion events are delivered only
+ to I.
+ ⊳ Alternately, if I decides it does not want to receive further events from
+ this touch sequence, it calls XIAllowTouchEvents with the
+ XITouchOwnerReject flag set; at this point, I receives a TouchEnd event
+ confirming that it has rejected the touch. C receives a TouchOwnership
+ event confirming that it is now the new owner of the touch, and further
+ TouchMotion events are delivered only to C. As C now owns the touch,
+ it is free to perform irreversible processing of the sequence.
+ ⊳ When the touch physically ceases, a TouchEnd event is sent to all
+ clients still receiving TouchMotion events.
+
+∙ Driver DRV provides touch support from tracked device D:
+ XXX: Pointer emulation semantics are yet to be determined.
+ ⊳ 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 39e4df9..894d2cd 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,5 +1,5 @@
AC_PREREQ([2.60])
-AC_INIT([InputProto], [2.0.1], [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.2.3
More information about the xorg-devel
mailing list