Draft XI 2 protocol specification
Peter Hutterer
peter.hutterer at who-t.net
Mon Jan 12 22:46:19 PST 2009
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
More information about the xorg
mailing list