459 lines
16 KiB
Plaintext
459 lines
16 KiB
Plaintext
|
|
|
|
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.
|