path: root/hw/dmx/doc/DMXSpec-v1.txt

            Client-to-Server DMX Extension to the X Protocol

           $Date$, $Revision$

               Rickard E. (Rik) Faith (faith@redhat.com)
                    Kevin E. Martin (kem@redhat.com)

    Copyright 2002,2003 Red Hat Inc., Raleigh, North Carolina.

    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 on 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:

    The above copyright notice and this permission notice (including the
    next paragraph) shall be included in all copies or substantial
    portions of the Software.

    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
    NON-INFRINGEMENT. IN NO EVENT SHALL RED HAT AND/OR THEIR SUPPLIERS
    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.



1. Overview

    The client-to-server DMX extension to the X protocol (DMX) provides
    normal client applications with the ability to determine information
    about the characteristics of the Xdmx server and the back-end X
    servers that DMX is using.

    The name for this extension is "DMX".



2. Syntactic conventions

    This document uses the same syntactic conventions requests and data
    types as [X11R6.4].



3. Data types

    No new data types are defined by this extension.  All data types
    referenced in this document are defined in [X11R6.4].



4. Requests

    DMXQueryVersion
        ==>
        majorVersion: CARD32
        minorVersion: CARD32
        patchVersion: CARD32

    The protocol this extension actually supports is indicated by
    majorVersion and minorVersion (patchVersion indicates the
    patchlevel and is for informational purposes only).

    Any incompatible changes to the protocol should be indicated by
    incrementing majorVersion.

    Small, upward-compatible changes should be indicated by incrementing
    minorVersion.

    Servers that support the protocol defined in this document will
    return a majorVersion of 1 and a minorVersion of 1.



    DMXGetScreenCount
        ==>
        screenCount: CARD32

    This request returns the number of back-end screens that the Xdmx
    server controls.  A back-end screen may be managed as a regular X
    screen in the Xdmx server or may be joined with other back-end
    screens using Xinerama.  (The information returned by this request
    does not change while Xdmx is running and may be cached on the
    client side.)
    


    DMXGetScreenInformation
        physicalScreen: CARD32
        ==>
        displayName: STRING8
        width: CARD16
        height: CARD16
        xoffset: INT16
        yoffset: INT16
        logicalScreen: CARD32
        xorigin: INT16
        yorigin: INT16

        Errors: Value

    This request returns information about individual back-end screens.
    The physicalScreen value is between 0 and screenCount-1, inclusive
    (values outside this range will result in a Value error).  The
    displayname is the name used to open the display, either from the
    Xdmx command-line or from the configuration file.  The width,
    height, xoffset, and yoffset values comprise a geometry
    specification (see X(7x)) for the location of the DMX window on the
    back-end screen.  This request will always return non-negative
    (i.e., normalized) values for xoffset and yoffset.  The
    logicalScreen value is the value of the screen that that Xdmx server
    exports to clients.  When Xinerama is in use, this value is
    typically 0 for all values of physicalScreen.  If Xinerama is in
    use, the xorigin and yorigin values specify where the physical
    screen is positioned in the global Xinerama coordinate system.
    Otherwise, these values are set to 0.  (The information returned by
    this request does not change while Xdmx is running and may be cached
    on the client side.)



    DMXGetWindowInformation
        window: CARD32
        ==>
        screenCount: CARD32
        screens: LISTofCARD32
        windows: LISTofCARD32
        pos: LISTofRECTANGLE
        vis: LISTofRECTANGLE

        Errors: Window, Alloc

    This request computed the return values incorrectly for version 1.0
    of this protocol.  Version 1.1 of this protocol conforms to this
    description.

    Given a window ID on the Xdmx server, this request returns data
    about how the window is represented on the back-end X servers.  For
    each back-end X server that displays a portion of the window, the
    following information is returned:
        1) the number of the physical screen containing that portion
           (which can be used with the DMXGetScreenInformation request
           to obtain more information about the screen),
        2) the window ID on the back-end X server of the window
           containing that portion,
        3) the position and dimensions of the window on the back-end, in
           screen coordinates, and
        4) the visible area of the window on the back-end, in
           window-relative coordinates (all zeros for windows that are
           not visible)
    Note that DMX allows multiple back-end windows to overlap in their
    view of the DMX logical window.  Further, a logical window does not
    have to be completely covered by back-end windows -- there may be
    gaps.

    As an example, consider a 500x500 window that spans the top two
    1024x768 back-end displays (A and B) of a 2048x1536 DMX display
    composed of 4 1024x768 back-end displays arranged in a cube:
        A B
        C D

    In this case, the DMXGetWindowInformation call would return the
    following information for the 500x500 window:

    display A: 500x500 window at 1024-250,0 (relative to back end)
               with 250x500 visible at 0,0 (relative to window origin)

    display B: 500x500 window at -250,0 (relative to back end)
               with 250x500 visible at 250,0 (relative to window origin)

    display C: 500x500 window at 1024-250,-768 with 0x0 visible at 0,0

    display D: 500x500 window at -250,-768 with 0x0 visible at 0,0

    Note that if the specified window has not yet been mapped when
    DMXGetWindowInformation is called, then a subsequent XMapWindow call
    might be buffered in xlib while requests directly to the back-end X
    servers are processed.  This race condition can be solved by calling
    DMXSync before talking directly to the back-end X servers.


    DMXGetInputCount
        ==>
        inputCount: CARD32

    This request was first supported in version 1.1 of this protocol.

    This request returns the number of input devices connected to the
    Xdmx server.  This number is the same as that returned by
    XListInputDevices, but is available even when the XInput extension
    is not supported.



    DMXGetInputInformation
        deviceId: CARD32
        ==>
        inputType: CARD32
        physicalScreen: CARD32
        physicalId: CARD32
        isCore: BOOL
        sendsCore: BOOL
        name: STRING8

        Errors: Value

    This request was first supported in version 1.1 of this protocol.

    This request returns information about the specified input device
    that cannot be obtained from the XListInputDeivices call.  The
    deviceId is the same as that used by the XListInputDevices call, and
    must be in the range 0 to inputCount-1, inclusive (values outside
    this range will result in a Value error).

    The value of inputType will always be value, and will be one of the
    following values:
        0 for local (and dummy) devices,
        1 for console devices, and
        2 for back-end devices.

    For local devices, all other fields returned, except isCore and
    sendsCore, are invalid.

    For console devices, the physicalScreen and physicalID will be
    invalid, and the name will return the name of the X server on which
    the console window is displayed.

    For back-end devices, the physicalScreen will identify the back-end
    display and can be used as an argument to DMXGetScreenInformation to
    obtain more information; the physicalId will be the XInput device id
    on the back-end X server; and the name will be invalid (since it
    does not provide any additional information that cannot be obtained
    with DMXGetScreenInformation).

    If isCore is True, then this device is active as a true core input
    device and will send core events.  If sendsCore is True, then this
    device queried an XInput extension device, but sends core events
    instead of extension events.  Note that this behavior is different
    from that of XFree86, where XInput extension devices may send both
    extension events and core events.



    DMXForceWindowCreation
        window: CARD32
        ==>

        Errors: Window

    This request was first supported in version 1.2 of this protocol.

    When using the lazy window creation optimization, windows are not
    created on the back-end X servers until they are required.  This
    request forces the immediate creation of the window requested.



    DMXReconfigureScreen
        screen: CARD32
        x: INT16
        y: INT16
        ==>
        status: CARD32

        Errors: Value

    This request was first supported in version 1.3 of this protocol.

    This request reconfigures the screen position to coordinates (x,y)
    when using the Xinerama extension.  Otherwise, it is a NOP.  Illegal
    values for screen will result in a BadValue error.  Other non-fatal
    errors will be returned in status.



    DMXSync
        ==>

    This request was first supported in version 1.5 of this protocol.

    This request flushes all pending protocol requests between the Xdmx
    server and each back-end X server.  It is used by a client that
    talks directly to back-end X servers

    To ensure proper synchronization semantics, this request has a
    reply, but the reply does not carry any information.



5. Events

    No new events are defined by this extension.



6. Errors

    No new events are defined by this extension.



7. Encoding

    DMXQueryVersion
        1           CARD8           opcode (X assigned)
        1           0               DMX opcode (X_DMXQueryVersion)
        2           1               request length
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           0               reply length
        4           CARD32          majorVersion
        4           CARD32          minorVersion
        4           CARD32          patchVersion
        12                          unused

    DMXGetScreenCount
        1           CARD8           opcode (X assigned)
        1           1               DMX opcode (X_DMXGetScreenCount)
        2           1               request length
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           0               reply length
        4           CARD32          screenCount
        20                          unused

    DMXGetScreenInformation
        1           CARD8           opcode (X assigned)
        1           2               DMX opcode (X_DMXGetScreenInformation)
        2           2               request length
        4           CARD32          physicalScreen
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           n/4+p           reply length
        4           n               displayNameLength
        2           CARD16          width
        2           CARD16          height
        2           INT16           xoffset
        2           INT16           yoffset
        4           CARD32          logicalScreen
        2           INT16           xorigin
        2           INT16           yorigin
        4                           unused
        n                           displayName
        p                           pad(n)

    DMXGetWindowInformation
        1           CARD8           opcode (X assigned)
        1           3               DMX opcode (X_DMXGetWindowInformation)
        2           2               request length
        4           CARD32          window
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           n*6             reply length
        4           n               screenCount
        20                          unused
        n*4         LISTofCARD32    screens
        n*4         LISTofCARD32    windows
        n*8         LISTofRECTANGLE pos
        n*8         LISTofRECTANGLE vis

    DMXGetInputCount
        1           CARD8           opcode (X assigned)
        1                           DMX opcode (X_DMXGetInputCount)
        2           1               request length
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           0               reply length
        4           CARD32          inputCount
        20                          unused

    DMXGetInputInformation
        1           CARD8           opcode (X assigned)
        1           4               DMX opcode (X_DMXGetInputInformation)
        2           2               request length
        4           CARD32          deviceId
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           n/4+p           reply length
        4           CARD32          inputType
        4           CARD32          physicalScreen
        4           CARD32          physicalId
        4           n               nameLength
        1           BOOL            isCore
        1           BOOL            sendsCore
        6                           unused
        n                           name
        p                           pad(n)

    DMXForceWindowCreation
        1           CARD8           opcode (X assigned)
        1           2               DMX opcode (X_DMXForceWindowCreation)
        2           2               request length
        4           CARD32          window
    ==>

    DMXReconfigureScreen
        1           CARD8           opcode (X assigned)
        1           2               DMX opcode (X_DMXReconfigureScreen)
        2           2               request length
        4           CARD32          screen
        2           INT16           x
        2           INT16           y
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           0               reply length
        4           CARD32          status
        20                          unused

    DMXSync
        1           CARD8           opcode (X assigned)
        1           0               DMX opcode (X_DMXSync)
        2           1               request length
    ==>
        1           1               Reply
        1                           unused
        2           CARD16          sequence number
        4           0               reply length
        24                          unused


8. Changes to existing requests/replies/events

    No changes to existing requests, replies, or events are necessitated
    by this extension.



9. Acknowledgments



10. References

    [X11R6.4] Robert W. Sheifler.  X Window System Protocol, X Consortium
              Standard, X Version 11, Release 6.4.  Available from
              xc/doc/specs/XProtocol and xc/doc/hardcopy/XProtocol.