[RFC XI 2.1 - inputproto] Add touch classes and events, bump to 2.1

[Chase Douglas]

On 11/19/2010 12:52 AM, Peter Hutterer wrote:
> On Wed, Nov 17, 2010 at 11:59:47AM -0500, Chase Douglas wrote:

[...]

>> @@ -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)
> 
> If it is a requirement to register for all three, a XI_TouchMask may be
> in order as (XI_TouchBeginMask | XI_TouchMotionMask | XI_TouchEndMask).

Good idea :).

[...]

>> -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.
> 
> Define "directly under the touch" for DependentTouch mode devices?

Good point :). I forgot to cover the difference between direct and
dependent devices here.

>> +
>> +A touch event is not delivered according to the device hierarchy. All touch
>> +events are sent only through their originating slave devices.
> 
> even for DependentTouch devices? the whole point of them is that they're
> relative to the cursor position, so there is a strong dependency between the
> two.
> 
> if events aren't delivered through the master device, why attach them in the
> first place? Should we consider them as new device type?
> (I know some of these questions have cropped up before, but I'd like to
> reiterate them here nonetheless)

There is a strong dependency between the two in the dependent touch
device case. For example, and I need to note this in the protocol spec
too, if a slave dependent device is not attached to a master device it
will not emit any touch events.

However, even though dependent touch device behaviour depends on the
device hierarchy, funnelling events through the master device seems
pointless and confusing. The point of a master device is to coallesce
all attached slave devices into a single cursor. Touch devices have no
effect on the cursor (save for pointer emulation performed in the input
module, but that's different). The only master device data needed by the
client is the location of the cursor, which is provided through the root
and event coordinates in the touch device events. The raw MT coordinates
are provided through valuators in device coordinate space.

I don't see any benefit to treating touch devices as a new device type
either. That's not to say I couldn't be persuaded if a need was identified.

[...]

>> @@ -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.
> 
> why not stuff the tracking ID into the detail field, it's unused for touch
> events anyway? having a valuator track IDs is just bad design.

I wasn't too crazy about having tracking IDs as just another valuator
either, but I wasn't sure what device event field I could override.
After taking another look, the detail field looks to be a good place to
stuff the tracking ID.

>> +
>> +    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.
> 
> given that this lacks grab support completely, the appendix should also
> acknowledge "known missing features". I'm happy to go along with this for
> now but we should also start spelling out what is missing.

Will do.

Thanks,

-- Chase