Draft XI 2 protocol specification

[Peter Hutterer]

First, thanks for the comments.

On Mon, Jan 12, 2009 at 11:09:22PM -0800, Keith Packard wrote:
> On Tue, 2009-01-13 at 16:46 +1000, Peter Hutterer wrote:
> 
> >     An XDeviceHierarchyChangedEvent is sent whenever the device hierarchy has
> >     been changed by either the client, or by server-internal events. The flags
> >     specify all types of hierarchy modifiations that have occured. 
> >     Clients are expected to query the server for the new hierarchy.
> 
> If clients need to take another round-trip, why pack any info into this
> event other than the 'something changed' bit? Presumably this doesn't
> happen very often, right?

The idea here was to be able to filter easily. I expect that many clients
won't care much about reattachment, but they would care about new MDs.
Having this information may prove useful. As for the deviceids - same idea.

> Alternatively, pack the whole change into the event?
> 
> >     Classes is a list of input device classes that are now provided by the
> >     device, see XI 1.x specification for more details.
> 
> Similarly, any reason to not just have the client download the new
> device state after it receives this event?
> 
> A viable answer here might be that placing the data in events instead of
> later replies is that clients can correctly parse the intervening event
> stream. This doesn't apply to XDHCE events above as clients must query
> state anyway.

Not having this state makes us prone for race conditions. Class changes are
expected to happen often, and a different XDCE may be generated while the
request is waiting to be processed. In this case, the client cannot process
events with the correct axis information.
At least for XDCE, it is mandatory that the new information is part of the
event. XDHCE is less frequent, justifying the query.
 
 
> >     root, event, child are the root window, event window or subwindow,
> >         respectively. See core protocol spec for more detail.
> >     root_x, root_y is the position of the pointer in screen coordinates
> >     event_x, event_y is the position of the pointer in screen coordinates
> >         relative to the event window.
> 
> Send these in floating point so we capture sub-pixel positions
> trivially?

ok.

> >     last_button is the highest bit set in buttons and determines the size of
> >         buttons.
> >     last_modifier is the highest bit set in modifiers and determines the size
> >         of modifiers.
> >     last_valuator is the highest bit set in valuators and determines the size
> >         of valuators
> 
> Clients are likely to decode this incorrectly as you have to be careful
> about all of these. Any reason to not just  indicate the length of each
> bit vector in 32-bit units?

That works too, and makes the coding a bit easer.

> >     axisvalues specifies the current value of the valuator in it's current
> >         mode (relative or absolute).
> 
> I assume the native values for all devices are integers?

correct, they are traditionally CARD32.

> >     Relative Motion event.
> >     type is XI_RelativeMotion
> >     This event is sent regardless of clipping and always provides the
> >     device-specific data. Pointer acceleration does not affect the axis
> >     values.
> 
> Uh. What about absolute devices? Can those send XRelativeMotionEvents?
> If so, this seems more like an XIDeviceRawEvent.
> (same comments about last_* apply here)

Good point. I will revise.

> >     ┌───
> >         XIPresence
> >             GENERICEVENTDATA
> >             devchange:                  SETofDEVICECHANGE
> >             control:                    CARD16
> >     └───
> > 
> >     DEVICECHANGE { DeviceAdded, DeviceRemoved, DeviceEnabled, DeviceDisabled,
> >                    DeviceControlChanged }
> > 
> >     DevicePresence event, equivalent to the XI 1.4 event. 
> >     type is XI_PresenceNotify
> >     devchange specifies the type of device change that has occured. If
> >     devchange is DeviceControlChanged, control specifies the ID of the device
> >     control that has changed. Otherwise, control is unspecified.
> > 
> >     The length of a Presence event is always 0.
> 
> How about describing this event in detail, rather than saying 'Like XI
> 1.4, except'. Keeping the XI 2 spec stand-alone would reduce the amount
> of reading when learning how to do input.

This is what I plan for the final version. This is the first draft (and half
of it was transcoded from code for this email), so I try to keep the amount of
typing down. FWIW, Presence events are in fact exactly the same as the 1.4
ones, bar the differnet wire format of course.

> > - this isn't fixing the problem we have with devices that are both pointers and keyboards
> 
> So make all devices both pointers and keyboards and have XIDeviceEvent
> include keys as well as buttons.

The best way to go about this is to have a single MD instead of a separate MD
pointer and an MD keyboard. However, core requires us to allow both pointer
and keyboard grab on the matching devices but there's only one XI grab. This
adds the necessity to support two different grabs on the same device and we
need to define the semantics for that.

The easiest way would be to state that XI grabs block both core grabs, and
either core grab blocks the XI grab. Same of course with event delivery but
that is quite restrictive.  
In the current system, if a client has a core keyboard grab on an MD, the
paired MD pointer can still send events. In a simple single MD system, a core
keyboard grab would block XI events. Rather than that, we may have to look at
filtering events per type (XI key events if a core pointer grab is on the MD)
and it gets complicated from there.

I don't have an answer for all that yet and it strikes me as one of those
things that just need testing to see what works best.

> > - how do go about input classes. refurbish them?
> 
> I'm wondering whether input classes have any place now; just make all
> devices the union of all classes?

The main point of input classes in XI2 would be to specifiy capabilities in
detail. Some of the input classes aren't particularly great for that so they
could do with a redesign. Example here is the ValuatorInfo that only allows
for a single state across all axes.
Whether a device is a union of all classes or just the classes it
claims to is IMHO trivial there.

> > - having 16 bit device ids requires to re-implement all requests and replies.
> 
> Use 32-bit device ids then.

Current deviceids are CARD8, so CARD32 would still require a reimplementation.
Now, at least for XI2 this may not be a problem as we could decide the upper
24 bit as "reserved for future use" and continue to only use 8 bits in
requests and replies - until those are reimplemented at a later point in time.

16 bit ids were chosen mainly because the fit nicely after the event type in
the GenericEvent. Before we run out of 2^16 deviceids per X server, we run
into other issues anyway.

> >   Mostly just typing, but it has to be done. 
> > - 32 bit keycodes is good but requires XKB2. I think. Daniel?
> 
> > - still no subpixel precision, unless we decide to make the valuators 24.8, or
> >   provide 32+32 or something.
> 
> 16.16 is sufficient as X screens can't be larger than 16 bits anyway. Or
> floats.

XI valuators are already 32 bits, and we probably shouldn't scale down.
we accept integer-only format in the valuator

> > - am I heading down a dead end?
> 
> I don't think so; let's keep pushing towards eliminating weird
> distinctions between devices and make sure we've got effectively two
> kinds of events -- clipped and processed by the server, and raw device
> events.

Good, thanks again for the comments.

I'm just tacking on (summarised) comments from daniel over IRC for the
archives:
- modifier state as at least 2 bits to represent XKB's latched, locked,
  latched-to-locked states.
  generally, squash more information (e.g. groups) in as well.

  [this needs more knowledge than I currently have off-hand, so parts of this
   will be delayed until after LCA]
- >255 keycode support in XKB has been started

Another thing discussed briefly was the use of a separate format internal to
the server, i.e. the XI events are assembled at delivery time, not carried
through the server. This is an implementation detail though and shouldn't be
too hard to support.

Cheers,
  Peter