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.