Xi specs: add blurb about XI 2 device handling.

1 files changed, 222 insertions, 15 deletions

diff --git a/specs/Xi/protocol.xml b/specs/Xi/protocol.xml
index fc2cba5..a617ed3 100644
--- a/specs/Xi/protocol.xml
+++ b/specs/Xi/protocol.xml
@@ -44,6 +44,25 @@
             used in advertising or otherwise to promote the sale, use or other dealings
             in this Software without prior written authorization from the X Consortium.
             <emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.</para>
+
+        <para>Copyright &copy; 2008 by Peter Hutterer</para>
+        <para>Permission is hereby granted, free of charge, to any person obtaining a
+            copy of this software and associated documentation files (the "Software"),
+            to deal in the Software without restriction, including without limitation
+            the rights to use, copy, modify, merge, publish, distribute, sublicense,
+            and/or sell copies of the Software, and to permit persons to whom the
+            Software is furnished to do so, subject to the following conditions:</para>
+        <para>The above copyright notice and this permission notice (including the next
+        paragraph) shall be included in all copies or substantial portions of the
+        Software.</para>
+        <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+        THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+        DEALINGS IN THE SOFTWARE.</para>
+        <beginpage/>
         <sect2>
             <title>Input Extension Overview</title>
             <para>This document defines an extension to the X11 protocol to support 
@@ -53,7 +72,27 @@
                 This first section gives an overview of the input extension. The 
                 next section defines the new protocol requests defined by the extension.
                 We conclude with a description of the new input events generated by
-                the additional input devices.</para>
+                the additional input devices.
+            </para>
+        </sect2>
+        <sect2>
+            <title>Input Extension Versions</title>
+            <para>
+                This document includes the specifications for X Input
+                Extension Version 1.x and X Input Version 2.x (XI2). The
+                differences for each version are spelled out in the respective
+                descriptions for requests and events.
+            </para>
+            <para>
+                There are three notable versions of XI. Most of this document
+                describes the behaviour of the Input Extension 1.0, 1.1, 1.2,
+                and 1.2. XI 1.4 introduced virtual devices that act as core
+                devices (see <xref linkend='core_input_devices'/>) and input
+                device hotplugging. XI 2.0 introduces the ability to create
+                multiple virtual core devices. Unless stated otherwise, the
+                content of this document applies to all versions of the Input
+                Extension.
+            </para>
         </sect2>
         <sect2 id='design_approach'>
             <title>Design Approach</title>
@@ -63,7 +102,8 @@
                 and from the core input devices. These requests and events make use
                 of a device identifier and support the reporting of n-dimensional motion 
                 data as well as other data that is not reportable via the core 
-                input events.</para>
+                input events.
+            </para>
         </sect2>
         <sect2 id='core_input_devices'>
             <title>Core Input Devices</title>
@@ -74,20 +114,30 @@
                 current location and focus of the X keyboard. To accomplish this, the server 
                 echoes a cursor at the current position of the X pointer. Unless the X
                 keyboard has been explicitly focused, this cursor also shows the current
-                location and focus of the X keyboard.</para>
-            <para>The X keyboard is used to generate input that client programs can detect.</para>
-            <para>The X keyboard and X pointer are referred to in this document as 
-                the <emphasis remap='I'>core devices</emphasis>, and the input
-                events they generate (<emphasis>KeyPress</emphasis>,
+                location and focus of the X keyboard. The X keyboard is used
+                to generate input that client programs can detect.</para>
+            <para>
+                In servers supporting XI 1.4 and above, the core pointer and
+                the core keyboard are virtual devices that do not represent a
+                physical device connected to the host computer. In XI 2.0 and
+                above, multiple core pointers and core keyboards may exist,
+                but for each core pointer there must be one core keyboard. No
+                odd number of core devices is possible.
+            </para>
+            <para>The X keyboard and X pointer are referred to in this
+                document as the <emphasis remap='I'>core devices</emphasis>,
+                and the input events they generate
+                (<emphasis>KeyPress</emphasis>,
                 <emphasis>KeyRelease</emphasis>, 
                 <emphasis>ButtonPress</emphasis>, 
                 <emphasis>ButtonRelease</emphasis>, and
                 <emphasis>MotionNotify</emphasis>) are known as the
                 <emphasis remap='I'>core input events</emphasis>. All other
                 input devices are referred to as <emphasis remap='I'>extension
-                    input devices</emphasis> and the input events they
-                generate are referred to as <emphasis remap='I'>extension
-                    input events</emphasis>.</para> <para>This input extension
+                input devices</emphasis> and the input events they generate
+                are referred to as <emphasis remap='I'>extension input events</emphasis>.
+            </para> 
+            <para>In servers supporting only XI 1.x, this input extension
                 does not change the behavior or functionality of the
                 core input devices, core events, or core protocol requests, with the
                 exception of the core grab requests. These requests may affect the
@@ -99,12 +149,20 @@
                 core devices is left implementation-dependent. Requests are defined that
                 allow client programs to change which physical devices are used as the
                 core devices.</para>
+            <para>
+                In servers supporting XI 2.0 and above, core devices are also
+                exteension devices and generate both core and input extension
+                events.  For a detailed description of the handling of input
+                devices in XI 2.0 and above, see <xref linkend='xi2_device_handling'/>.</para>
         </sect2>
         <sect2 id='extension_input_devices'>
             <title>Extension Input Devices</title>
-            <para>The input extension controls access to input devices other than the X keyboard
+            <para>The input extension v1.x controls access to input devices other than the X keyboard
                 and X pointer. It allows client programs to select input from these devices 
-                independently from each other and independently from the core devices.</para>  
+                independently from each other and independently from the core
+                devices. XI 2.0 and above also enable access to the X keyboard
+                and the X pointer.
+            </para>  
             <para>A client that wishes to access a specific device must first determine
                 whether that device is connected to the X server. This is done through the
                 <emphasis>ListInputDevices</emphasis> request, which will return a list of all devices that
@@ -135,15 +193,21 @@
                 classes of input devices without changing the protocol requests.
                 Input classes are unique numbers registered with the X Consortium.
                 Each extension input device may support multiple input classes.</para>
-            <para>All extension input devices are treated like the core X keyboard in 
+            <para>
+                In XI 1.x, all extension input devices are treated like the core X keyboard in 
                 determining their location and focus. The server does not track the 
                 location of these devices on an individual basis, and therefore
                 does not echo a cursor to indicate their current location.
                 Instead, their location is determined by the location of the core X pointer.
                 Like the core X keyboard, some may be explicitly focused. If they are
                 not explicitly focused,  their focus is determined by the location of the 
-                core X pointer.</para>
-            <para>Input events reported by the server to a client are of fixed size (32 bytes).
+                core X pointer.
+            </para>
+            <para>
+                In XI 2.x, the location and focus of an extension input device
+                is determined by its attachment. See <xref linkend="xi2_device_handling"/>.
+            </para>
+            <para>Most Input events reported by the server to a client are of fixed size (32 bytes).
                 In order to represent the change in state of an input device the extension
                 may need to generate a sequence of input events. A client side library
                 (such as Xlib) will typically take these raw input events and format
@@ -234,6 +298,149 @@
                     these requests to be recompiled.</para>
             </sect3>
         </sect2>
+        <sect2 id='xi2_device_handling'>
+            <title>XI 2.0 device handling</title>
+            <para>XI Version 2.0 introduces a device hierarchy split up into
+                so-called &quot;Master Devices&quot; (MD) and &quot;Slave
+                Devices&quot; (SD). This distinction is key to both the device
+                handling and the event handling in the server.</para>
+            <para>An MD is always a virtual device and does not represent a
+                physical device connected to the host computer. MDs come in
+                two forms: as master pointers or as master keyboards. 
+                A master pointer is reflected by a visible cursor on the
+                screen. A master keyboard is reflected by a keyboard focus.
+            </para>
+            <para>
+                Each master pointer is &quot;paired&quot; with the respective
+                master keyboard and vice versa, and this pairing is maintained
+                for the lifetime of both input devices.  Clients can utilise
+                this pairing behaviour to implement combinatory input
+                paradigms such as SHIFT + Click. For a description on how to
+                obtain this pairing, see <xref linkend="listing_available_devices"/>.
+            </para>
+            <para>
+                MDs may send core events and XI events. However, as an MD does
+                not represent a physical device, they rely on SDs for event
+                generation.
+            </para>
+            <para>
+                An SD is a physical device configured in the server. SDs are
+                not represented by a cursor or keyboard focus. An SD may be
+                &quot;attached&quot; to a master pointer or master keyboard.
+                In this case, each event generated by the SD is
+                <emphasis>also</emphasis> routed through the MD. Such an event
+                is modified inside the server and appears to the client as if
+                generated by the MD. See <xref linkend="xi2_event_processing"/>
+                for more details.
+            </para>
+            <para>SDs can only send XI events.</para>
+            <para>
+                <example width='3in'>
+                    <title>Example device setup</title>
+                    <para>A server may have two master devices (one master pointer
+                    and one master keyboard). It thus displays one cursor and
+                    provides one keyboard focus.</para>
+                <para>One mouse and one keyboard are connected to the server.
+                    The server thus controls two slave devices. The mouse is
+                    attached to the master pointer and the keyboard to the
+                    master keyboard.</para>
+                <para>When the mouse moves, the matching slave device
+                    generates an XI event. This event is processed until
+                    delivered. After that, the same event is modified to
+                    appear as being generated by the master pointer. This
+                    modified event is then processed until delivered. To a
+                    client, the latter event appears to be coming from the
+                    master pointer.</para>
+                </example>
+            </para>
+            <sect3 id='xi2_attachment'>
+                <title>Attachment of slave devices</title>
+                <para>
+                    SDs can be attached to any master of the same type (e.g. a
+                    physical pointer device can be attached to any master
+                    pointer). In this case, the SD controls the MDs cursor and
+                    a movement of the SD will change the cursor position of
+                    this MD. Likewise, an attached keyboard device shares the
+                    keyboard focus of the respective master keyboard.
+                </para>
+                <para>
+                    SDs can be &quot;floating&quot;, in which case they are
+                    not attached to an MD. Such a floating devices does not
+                    route events through any MD and does not have a visible
+                    cursor. The focus of such a floating device must be
+                    explicitly controlled by the client program.
+                </para>
+            </sect3>
+            <sect3 id='xi2_event_processing'>
+                <title>Event processing for attached slave devices</title>
+                <para>
+                    If an SD generates an event, this event is processed as
+                    normal and delivered to any client that previously
+                    registered for the respective event type. Such events are
+                    always input extension events and the SD can be identified
+                    by the device identifier in event.
+                </para>
+                <para>
+                    After the SD's event has been processed, the event's
+                    device identifier is modified and set to the SD's master
+                    device. The event is then processed again, this time
+                    appearing as if generated by the master device.
+                    During event processing, a core event is generated from
+                    the input extension event. If the core event is delivered
+                    to a client, the input extension event is not processed
+                    further and the server continues with the next input
+                    event. Only if the core event is not delivered may the
+                    input extension event be delivered to a client.
+                </para>
+                <para>
+                    Before the MD's event is processed, the MD switches state 
+                    to represent the capabilities of the SD. As previously
+                    described in <xref linkend="input_classes"/>, each SD
+                    describes its capabilities through a number of input
+                    classes. When the MD switches state, it duplicates the
+                    input classes of the SD and thus appears to have the same
+                    capabilities as the SD. Clients are notified of this
+                    switch.
+                </para>
+                <para>
+                    <example width='3in'>
+                        <title>Event routing with two pointer devices.</title>
+                        <para>
+                            A server has a traditional USB mouse and a
+                            graphics tablet attached. The USB mouse provides 3
+                            buttons and relative x/y axes. The graphics tablet
+                            provides 8 buttons and 3 absolute axes in a
+                            device-specific coordinate system.
+                            Both devices are attached to the same master
+                            pointer.
+                        </para>
+                        <para>
+                            When the mouse generates an event, this input
+                            extension event is delivered as normal. The event
+                            is then modified to appear as being generated by
+                            the master pointer. The master pointer modifies
+                            its input classes to appear as a device that
+                            provides 3 buttons and two relative axes. The
+                            input extension event is then processed.
+                            A core event may be delivered instead of the input
+                            extension event.
+                        </para>
+                        <para>
+                            When the graphics tablet generates an event, this
+                            input extension event is deliveredd as normal. The
+                            event is ethen modified to appear as being
+                            generated by the master pointer. The master
+                            pointer modifies its input classes to appear as a
+                            devices that provides 8 buttons and thre absolute
+                            axes in a device-specific coordinate system. The
+                            input extension event is then processed, and a
+                            core event may be delivered instead of the input
+                            extension event.
+                        </para>
+                    </example>
+                </para>
+            </sect3>
+        </sect2>
     </sect1>
     <sect1 id='requests'>
         <title>Requests</title>