[PATCH inputproto] Add touch classes and events, bump to 2.1

Peter Hutterer peter.hutterer at who-t.net
Tue Jan 4 21:24:21 PST 2011


On Tue, Dec 28, 2010 at 05:58:01PM +0000, Daniel Stone wrote:
> 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>
> ---

typo in section 4.4, s/hierachy/hierachy/ will fix it.
a FIXME for the pointer emulation section claiming that we haven't actually
figured that out yet would be nice too.

Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>

thanks for all the work!

Cheers,
  Peter

>  XI2.h        |   29 +++++-
>  XI2proto.h   |   44 +++++++-
>  XI2proto.txt |  337 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  configure.ac |    2 +-
>  4 files changed, 396 insertions(+), 16 deletions(-)
> 
> diff --git a/XI2.h b/XI2.h
> index 6ba1377..18602f8 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,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 +199,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..f7510cc 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,7 @@ typedef struct
>  } xXIDeviceChangedEvent;
>  
>  /**
> - * Default input event for pointer or keyboard input.
> + * Default input event for pointer, keyboard or touch input.
>   */
>  typedef struct
>  {
> diff --git a/XI2proto.txt b/XI2proto.txt
> index 10f58c2..70cdd39 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,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 +192,63 @@ 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 hierachy 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).  An “owner” flag is provided for clients
> +to know whether they are currently in control of the touch sequence or not.
> +
> +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 the current window underneath the position of the device's
> +sprite. 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 a sprite to focus events to.
> +
> +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 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 +370,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 +395,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 +516,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
> +    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 +605,12 @@ 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. 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 +1171,7 @@ are required to be 0.
>      └───
>  
>          GRABTYPE         { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
> -                           GrabtypeFocusIn}
> +                           GrabtypeFocusIn, GrabtypeTouchBegin }
>  
>          GRABMODIFIERINFO {   status:    Access
>                               modifiers: CARD32 }
> @@ -1015,7 +1187,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 +1203,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 +1261,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 +1278,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 +1293,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 +1317,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 +1338,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 +1498,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 +1562,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,15 +1709,19 @@ 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): { TouchOwner, TouchOwnerAccepted,
> +                                            TouchPendingFinish }
>  
>      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.
> +        The button number, key code, touch ID, or 0.
>      root
>      event
>      child
> @@ -1517,8 +1749,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 +1762,17 @@ 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.
> +        TouchOwner means that the client is the current owner of the touch.
> +        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 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.
>  
>      Modifier state in mods is detailed as follows:
>      base_mods
> @@ -1543,6 +1790,26 @@ 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 ownership has changed for that touch sequence; ownership
> +    change may result in a TouchMotion event being sent with zero valuators.
> +
> +    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
> @@ -1675,3 +1942,51 @@ 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 calls XISelectEvent for XI_Touch{Begin|Motion|End} from D on W.
> +    ⊳ C receives XITouchBegin whenever a touch sequence starts within
> +      W's borders.
> +    ⊳ C receives XITouchMotion events whenever a touch axis valuator value
> +      changes for a touch sequence it received an XITouchBegin event for.
> +    ⊳ C receives XITouchEnd whenever a touch it received an XITouchBegin 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|End} from D on W.
> +    ⊳ I calls XIPassiveGrab for XI_Touch{Begin|Motion|End} from D on a parent
> +      window of W.
> +    ⊳ I receives XITouchBegin whenever a touch begins within window W, with the
> +      XITouchOwner flag set; C receives an XITouchBegin event, but without the
> +      XITouchOwner flag.
> +    ⊳ When a touch axis valuator changes in this touch sequence, both I and C
> +      receive XITouchMotion events, but only I has the XITouchOwner flag set.
> +    ⊳ 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 an XITouchEnd event with the
> +      XITouchOwnerAccepted flag set, and further XITouchMotion 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 an XITouchEnd event
> +      confirming that it has rejected the touch, C receives an XITouchMotion
> +      event with the XITouchOwner flag set, and further XITouchMotion events
> +      are delivered only to C.
> +    ⊳ When the touch physically ceases, an XITouchEnd event is sent to all
> +      clients still receiving XITouchMotion events.
> +
> +∙  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 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