Fwd: Draft XI 2 protocol specification - wine-devel

13 Jan 2009


      Hi Vitaliy,
Peter Hutterer has submitted a draft specification of Xinput2 to the xorg mailinglist. As you know it will offer relative mouse movements. He is asking for feedback. Since I have no experience with Xinput you might want to review it and see if it works out for Wine.
Roderick
-------- Original-Message--------
From: Peter Hutterer peter.hutterer@who-t.net
To: "X.Org List" xorg@lists.freedesktop.org
CC: Daniel Stone daniel@fooishbar.org
Subject: Draft XI 2 protocol specification
I know we're all thinking about getting 1.6 out, but here's the next lot of
big changes that I really need some feedback on. LCA is coming up and napkins
want to be written on, so the more feedback before that happens, the better.
As a friendly reminder, the X Protocol has a tendency to be set in stone, so
if you don't speak up now you will have to explain yourself to your
grandchildren why GUI's still suck.
Short story long, X Input 2.0 is in the making and should come out with server
1.7 somewhen later this decade. Server 1.6 has all the internal changes but
doesn't expose anything to the clients. So far, I have bits and pieces of XI2
that compile and henceforth are bug-free. But I need your review is needed,
before I go further down a dead end.
Some clarification:
XI2 ........  X Input Extension version 2.0 Protocol
XI 1.x .....  X Input Extension version 1.x Protocol 
server 1.6 .  X server version 1.6 (supports XI 1.5)
server 1.7 .  X server version 1.7 (will support XI 2.0)
If you want to skip the background, scroll down to "Protocol Specification"
== Background ==
The biggest change between XI 1.5 and XI 2.0 will be the master/slave device
hierarchy being visible to the client and the ability to create additional
master devices (i.e. cursors/keyboard foci).
The current state of XI2 in master is that we're using the XI 1.x events plus
a few new ones (some of which are GenericEvents) and we have a few new
requests.
This has some shortcomings:
- XI 1.x events are "full", there is no more space in the 32 bytes that allow
  for more data.
- XI 1.x events suck for event registration. It is not possible to just
  register for motion events, you have to open all devices, get the class,
  etc.
- The pointer/keyboard distinction is not really a good idea these days, many
  devices are both.
- XI 1.x does not allow for both rel+abs axes on a device.
- Subpixel precision only for absolute valuators.
- Static input devices. Devices cannot change capabilities (e.g. add an axis)
  at runtime.
- Keycode range 255. This is also a limitation with XKB.
== Protocol Specification ==
Basically the idea is to provide GenericEvents for *all* XI2 events, even
those covered through XI 1.x. Which means that we have another API to support
for those clients that keep using XI 1. This however can be achieved in a
similar fashion to the core emulation we already do anyway.
Why? GenericEvent have a length-field, so we can keep extending in future
versions without having to modify the client. Clients are expected to read the
full event off the wire, but only access the fields that they know of,
allowing us to tack on data to the end of the event.
Below is the preliminary specification for those XI2 events I was planning to
add/implement for XI 2.0. If anything doesn't make sense, is missing, etc.
please state so.
I am not yet covering requests, this is events only for now.
In the remainder of this email, the following notation is used
┌───
       Name of event
            name of field:               type of field
            name of field:               type of field
            ───
            name of field:               type of field
    └───
Where ─── denotes the 32 byte boundary of the event, padded accordingly if
necessary. Fields after ─── require the event to have a length greater than 0.
If ───  is missing, the event is exactly 32 bytes long.
┌───
        XIGenericDeviceEvent
            type:                       BYTE
            extension:                  BYTE
            sequenceNumber:             CARD16
            length:                     CARD32
            evtype:                     CARD16
            deviceid:                   CARD16
            time:                       CARD32
    └───
XGenericDeviceEvent is the generic header for all XI 2 events.
    type is always GenericEvent.
    extension is always the X Input extension offset.
    evtype is the XI-specific event type.
For brevity, this information is specified as GENERICEVENTDATA in the
    following events.
┌───
        XIDeviceHierarchyEvent:
            GENERICEVENTDATA
            flags:                      SETofHIERARCHYMASK
            ndevices:                   CARD16
            ───
            devices:                    LISTofINT16
    └───
HIERARCHYMASK { MasterAdded, MasterRemoved, SlaveAttached, SlaveDetached,
                    SlaveAdded, SlaveRemoved }
type is XI_HierarchyChangedNotify.
    flags specifies all types of hierarchy modifiations that have occured.
    ndevices specifies the number of devices.
    devices is the list of all devices affected by this hierarchy change.
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.
Note: Because multiple modification affecting multiple devices may take
    place in one request, deviceid in an XDeviceHierarchyChangedEvent is
    always the first affected device. Clients should ignore deviceid and
    instead use the devices list.
┌───
        XIDeviceChangedEvent:
            GENERICEVENTDATA
            num_classes:                CARD8
            new_slave:                  BOOL
            slaveid:                    CARD16
            ───
            classes:                    LISTofINPUTINFO
    └───
type is XI_DeviceChangedNotify.
    Sent whenever an MD changes due to a new SD sending events through it.
         - new_slave is TRUE, slavedi is the deviceid of the new SD.
    Sent whenever a device changes any of its classes.
        - new_slave is FALSE, slaveid is undefined.
    Classes is a list of input device classes that are now provided by the
    device, see XI 1.x specification for more details.
┌───
        XIDeviceEvent:
            GENERICEVENTDATA
            detail:                     CARD32
            root:                       Window
            event:                      Window
            child:                      Window
            ───
            root_x:                     CARD32
            root_y:                     CARD32
            event_x:                    CARD32
            event_y:                    CARD32
            last_button:                CARD16
            last_modifier:              CARD16
            last_valuator:              CARD16
            sourceid:                   CARD16
            buttons:                    SETofBUTTONBIT
            modifiers:                  SETofMODIFIERBIT
            valuators:                  SETofVALUATORBIT
            axisvalues:                 LISTofCARD32
    └───
BUTTONBIT { (1 << Button1), (1 << Button2), ... , (1 << ButtonN) }
    MODIFIERBIT { ShiftMask, LockMask, ControlMask, Mod1Mask, ... , ModNMask }
    VALUATORBIT { (1 << 1), ( 1 << 2), ... ( 1 << n) }
SETofBUTTONBIT, SETofMODIFIERBIT and SETofVALUTORBIT are always padded to
    4 bytes.
Generic event structure for motion, button and key events.
    type is one of XI_ButtonPress, XI_ButtonRelease, XI_KeyPress, XI_KeyRelease,
        XI_Motion, XI_Proximity.
        detail is the button number or key code, or 0.
    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.
    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
    sourceid is the device id of the SD that generated the event.
    buttons is the button state before the event, with a button mask set if the
        matching button is down.
    modifiers is the modifier state before the event, with a modifier mask set
        if the matching modifier is down.
    valuators specifies which valuators are provided in this event. If a
        valuator's mask is specified, the valuator is provided in axisvalues.
    axisvalues specifies the current value of the valuator in it's current
        mode (relative or absolute).
┌───
        XRelativeMotionEvent
            GENERICEVENTDATA
            last_button:                CARD16
            last_modifier:              CARD16
            last_valuator:              CARD16
            sourceid:                   CARD16
            ───
            buttons:                    SETofBUTTONBIT
            modifiers:                  SETofMODIFIERBIT
            valuators:                  SETofVALUATORBIT
            axisvalues:                 LISTofCARD32
    └───
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.
All fields are equivalent to the respective fields in the XDeviceEvent.
┌───
        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.
=== Current Status ===
The current status is that I have switched parts of the server over to
generate and process XI2 events (it requires *a lot* of changes, but also
cleans the server up a bit).
I'm not sure about the following things:
- modifiers. daniel, can you chime in here how to solve this the best way?
- device controls in XI2? Really? (see Presence event)
- this isn't fixing the problem we have with devices that are both pointers and keyboards
- how do go about input classes. refurbish them?
- having 16 bit device ids requires to re-implement all requests and replies.
  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.
- am I heading down a dead end?
- is it beer o'clock yet?
Cheers,
  Peter
_______________________________________________
xorg mailing list
xorg@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/xorg
-- 
Sensationsangebot verlängert: GMX FreeDSL - Telefonanschluss + DSL 
für nur 16,37 Euro/mtl.!* http://dsl.gmx.de/?ac=OM.AD.PD003K1308T4569a