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-2004 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
Errors: None
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 2 and a minorVersion of 2.
(Version 1.5 was the last version in the 1.x series; version 2.0 was
a testing version that was poorly defined.)
DMXSync
==>
status: CARD32
Errors: None
This request was first supported in version 1.5 of this protocol.
The status field in the reply was introduced in version 2.0 of this
protocol. Since the status field is ignored, no changes to the
underlying protocol were required.
This request flushes all pending protocol requests between the Xdmx
server and each back-end X server. It is used by clients that
talk directly to back-end X servers to ensure that all pending Xdmx
requests have reached all back-end servers and have been processed
by those servers.
The value of status is always 0.
DMXForceWindowCreation
window: CARD32
==>
status: CARD32
Errors: Window
This request was first supported in version 1.2 of this protocol.
This request was changed to have a reply in version 2.0 of this
protocol. The old version of this request was deprecated and will
return BadImplementation.
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.
The value of status is always 0.
DMXGetScreenCount
==>
screenCount: CARD32
Errors: None
This request returns the number of screens that the Xdmx server
controls. Since a DMX screen usually fills all of the available
area on a back-end server, there is usually a one-to-one
correspondence between DMX screens and backend servers. However, it
is also possible for a DMX screen to cover only part of the
available area on a back-end server, and for more than one DMX
screen to occupy different parts of the visible area on the same
back-end server.
A DMX screen may be managed as a regular X screen in the Xdmx server
or may be joined with other DMX screens using Xinerama.
DMXGetScreenAttributes
physicalScreen: CARD32
==>
displayName: STRING8
logicalScreen: CARD32
screenWindowWidth: CARD16
screenWindowHeight: CARD16
screenWindowXoffset: INT16
screenWindowYoffset: INT16
rootWindowWidth: CARD16
rootWindowHeight: CARD16
rootWindowXoffset: INT16
rootWindowYoffset: INT16
rootWindowXorigin: INT16
rootWindowYorigin: INT16
Errors: Value
This request is new in version 2.0 of this protocol. The old
DMXGetScreenInformation request is deprecated and will now return
BadImplementation.
This request returns attributes about a single DMX screen.
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 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 rootWindowXOrigin and rootWindowYOrigin values specify
where the physical screen is positioned in the global Xinerama
coordinate system. Otherwise, these values are set to 0.
The screenWindow values comprise a geometry specification (see
X(7x)) for the location of the DMX screen on the back-end screen.
The coordinant system of the back-end display is used.
The first four rootWindow values comprise a geometry specification
(see X(7x)) for the location of the root window on the screen
window. The coordinant system of the screen window is used. In
most cases, the root window will have the same geometry as the DMX
screen window, and will occupy the same area of the back-end
display. (This would not be the case, for example, if automatic
projector alignment is used.)
DMXChangeScreensAttributes
screenCount: CARD32
maskCount: CARD32
screens: LISTofCARD32
valueMasks: LISTofCARD32
valueList: LISTofVALUES
==>
status: CARD32
errorScreen: CARD32
Errors: Length, Alloc
This request was first supported in version 2.0 of this protocol.
(A singular version of this request with the ability to change some
RootWindow attributes was supported in version 1.3 of this protocol,
has been deprecated, and will return BadImplementation.)
This request changes the geometries and positions of the DMX screen
and DMX root windows on the back-end X servers.
The valueMask and valueList specify which attributes are to be
changed. The possible values are:
Attribute Type
ScreenWindowWidth CARD16
ScreenWindowHeight CARD16
ScreenWindowXoffset INT16
ScreenWindowYoffset INT16
RootWindowWidth CARD16
RootWindowHeight CARD16
RootWindowXoffset INT16
RootWindowYoffset INT16
RootWindowXorigin INT16
RootWindowYorigin INT16
The attribute values have the same meaning as do the corresponding
values for DMXGetScreenAttributes.
Non-fatal errors will be returned in status (0 otherwise):
DmxBadXinerama: Xinerama is not active
DmxBadValue: The resulting position is not allowed
(e.g., one corner is outside the bounding box)
On error, errorScreen will contain the number of the screen that
caused the first error.
DMXAddScreen
displayName: STRING8
physicalScreen: CARD32
valueMask: CARD32
valueList: LISTofVALUES
==>
status: CARD32
physicalScreen: CARD32
Errors: Length, Alloc, Value
This request was first supported in version 2.2 of this protocol.
This request re-attaches the back-end physicalScreen to the Xdmx
server. Only back-end screens that have been previously detached
with DMXRemoveScreen may be added. The name of the back-end display
is given in displayName, and this will replace the name of the
back-end screen that was detached. Both the displayName and
physicalScreen must be correct for this request to work.
The valueMask and valueList specify the attributes to be used. The
possible values are:
Attribute Type
ScreenWindowWidth CARD16
ScreenWindowHeight CARD16
ScreenWindowXoffset INT16
ScreenWindowYoffset INT16
RootWindowWidth CARD16
RootWindowHeight CARD16
RootWindowXoffset INT16
RootWindowYoffset INT16
RootWindowXorigin INT16
RootWindowYorigin INT16
The attribute values have the same meaning as do the corresponding
values for DMXGetScreenAttributes.
On success, status will be 0 and physicalScreen will contain the new
screen number. On failure, status will be non-zero. The status
will be 1 if any of the following occured:
* the -addremovescreens command-line option was not specified on
the Xdmx command line
* the value of physicalScreen is out of range
* physicalScreen has not been detached (with DMXRemoveScreen)
* displayName cannot be opened
* the visuals of displayname do not match the visuals that Xdmx
is using
* the screen data for displayName does not match the data for the
previously removed display
The status will be DmxBadValue if the attribute values are out of
range.
DMXRemoveScreen
physicalScreen: CARD32
==>
status: CARD32
Errors: None
This request was first supported in version 2.2 of this protocol.
This request detaches the physicalScreen screen.
On success, status will be 0. On failure, the status will 1 if any
of the following occur:
* the -addremovescreens command-line option was not specified on
the Xdmx command line
* the value of physicalScreen is out of range
* the back-end screen has already been detached.
DMXGetWindowAttributes
window: CARD32
==>
screenCount: CARD32
screens: LISTofCARD32
windows: LISTofCARD32
pos: LISTofRECTANGLE
vis: LISTofRECTANGLE
Errors: Window, Alloc
This request computes the return values incorrectly for version 1.0
of this protocol. Version 1.1 of this protocol conforms to this
description. In version 2.0, the name of this request was changed
from DMXGetWindowInformation. However, since the request itself did
not change, no changes to the underlying protocol were made.
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 DMXGetScreenAttributes 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 DMXGetWindowAttributes 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
DMXGetWindowAttributes 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.
DMXGetDesktopAttributes
==>
width: INT16
height: INT16
shiftX: INT16
shiftY: INT16
Errors: None
This request was first supported in version 2.0 of this protocol.
This request returns the size of the bounding box of the whole
screen in width and height. The shiftX and shiftY values will
always be 0. The global bounding box is computed whether or not
Xinerama is active, and may be larger than the Xinerama screen size
because of information in the configuration file.
DMXChangeDesktopAttributes
valueMask: BITMASK
valueList: LISTofVALUE
==>
status: CARD32
Errors: Length, Value
This request was first supported in version 2.0 of this protocol.
This request resizes the bounding box of the whole screen when using
the Xinerama extension. Otherwise, it has no effect on the screen
layout. The valueMask and valueList specify which attributes are to
be changed. The possible values are:
Attriubute Type
Width INT16
Height INT16
ShiftX INT16
ShiftY INT16
Width and Height specify the new width and height for the bounding
box. ShiftX and ShiftY specify where the Xinerama origin will be
placed with respect to the origin of the new bounding box. This
allows the left and upper edges of the bounding box to be changed
without changing the visual position of the windows on the desktop.
If Width or Height is not specified, the current values will be
used. If ShiftX or ShiftY is not specified, 0 will be used.
All coordinants are in the global DMX coordinant system. If
Xinerama is not active, this request is not useful.
Non-fatal errors will be returned in status (0 otherwise):
DmxBadXinerama: Xinerama is not active
DmxBadValue: The size of the bounding box is too large
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.
DMXGetInputAttributes
deviceId: CARD32
==>
inputType: CARD32
physicalScreen: CARD32
physicalId: CARD32
isCore: BOOL
sendsCore: BOOL
detached: BOOL
name: STRING8
Errors: Value
This request was first supported in version 1.1 of this protocol.
In version 2.0, the name of this request was changed from
DMXGetInputInformation. However, since the request itself did not
change, no changes to the underlying protocol were made. In version
2.2, the name of detached was changed from reservation. There was
no change in underlying 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 valid, 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 DMXGetScreenAttributes 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 DMXGetScreenAttributes).
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 is an XInput extension device, but sends core events instead
of extension events. Note that this behavior is different from that
of XFree86 or Xorg, where XInput extension devices may send both
extension events and core events.
If detached is True, then this device has been detached and is no
longer producing input events. The device may be reattached using
DMXAddInput.
DMXAddInput
displayName: STRING8
valueMask: CARD32
valueList: LISTofVALUES
==>
status: CARD32
physicalId: CARD32
Errors: Value, Access
This request was first supported in version 2.2 of this protocol.
The valueMask and valueList specify the attributes to be used. The
possible values are:
Attribute Type
InputType CARD32
InputPhysicalScreen CARD32
InputSendsCore BOOL
This request attaches an input device to the Xdmx server. The value
of inputType will be one:
1 for console devices, and
2 for back-end devices.
Other values of InputType will return a BadValue error. Local
devices (inputType=0 in DMXGetInputAttributes) cannot be attached or
removed. For console devices, displayName will store the name of
the display to be used.
For back-end devices, InputPhysicalScreen will specify the screen
number. BadValue will be returned if the screen number is out of
range. BadAccess will be returned if the input has already been
attached or if the backend screen is currently detached.
If InputSendsCore is True, the new device will be added as a true
core device.
If a device was removed with DMXRemoveInput an attempt will be made
to reconnect the previous devices (InputSendsCore is ignored in this
case).
DMXRemoveInput
physicalId: CARD32
==>
status: CARD32
Errors: Value, Access
This request was first supported in version 2.2 of this protocol.
This request detaches the input device with physicalId, and all
associated inputs (e.g., if the physicalId is a backend mouse, and a
keyboard is also attached to the backend, then both devices will be
detached). If the physicalId is outside the valid range (0 to one
less than the value returned by DMXInputCount), BadValue is
returned. If the physicalId has already been detached, BadAccess is
returned. The status is always 0.
5. Events
No new events are defined by this extension.
6. Errors
No new events are defined by this extension.
7. Encoding
Deprecated DMX opcodes:
DMXGetScreenInformation 2
DMXForceWindowCreation 6
DMXReconfigureScreen 7
Valid DMX opcodes:
DMXQueryVersion 0
DMXSync 8
DMXForceWindowCreation 9
DMXGetScreenCount 1
DMXGetScreenAttributes 10
DMXChangeScreensAttributes 11
DMXAddScreen 12
DMXRemoveScreen 13
DMXGetWindowAttributes 3
DMXGetDesktopAttributes 14
DMXChangeDesktopAttributes 15
DMXGetInputCount 4
DMXGetInputAttributes 5
DMXAddInput 16
DMXRemoveInput 17
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
DMXSync
1 CARD8 opcode (X assigned)
1 8 DMX opcode (X_DMXSync)
2 1 request length
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
20 unused
DMXForceWindowCreation
1 CARD8 opcode (X assigned)
1 9 DMX opcode (X_DMXForceWindowCreation)
2 2 request length
4 CARD32 window
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
20 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
DMXGetScreenAttributes
1 CARD8 opcode (X assigned)
1 10 DMX opcode (X_DMXGetScreenAttributes)
2 2 request length
4 CARD32 physicalScreen
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 1+(n+p)/4 reply length
4 n displayNameLength
4 CARD32 logicalScreen
2 CARD16 screenWindowWidth
2 CARD16 screenWindowHeight
2 INT16 screenWindowXoffset
2 INT16 screenWindowYoffset
2 CARD16 rootWindowWidth
2 CARD16 rootWindowHeight
2 INT16 rootWindowXoffset
2 INT16 rootWindowYoffset
2 INT16 rootWindowXorigin
2 INT16 rootWindowYorigin
n displayName
p pad(n)
DMXChangeScreensAttributes
1 CARD8 opcode (X assigned)
1 11 DMX opcode (X_DMXChangeScreenAttributes)
2 3+s+m+n request length
4 s screenCount
4 m maskCount
4s LISTofCARD32 screens
4m LISTofCARD32 valueMasks
4n LISTofVALUES valueList
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
4 CARD32 errorScreen
16 unused
DMXAddScreen
1 CARD8 opcode (X assigned)
1 12 DMX opcode (X_DMXAddScreen)
2 3+m+(n+p)/4 request length
4 n displayNameLength
4 CARD32 physicalScreen
4 CARD32 valueMask
4m LISTofVALUES valueList
n displayName
p pad(n)
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
4 CARD32 physicalScreen
16 unused
DMXRemoveScreen
1 CARD8 opcode (X assigned)
1 13 DMX opcode (X_DMXRemoveScreen)
2 2 request length
4 CARD32 physicalScreen
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
20 unused
DMXGetWindowAttributes
1 CARD8 opcode (X assigned)
1 3 DMX opcode (X_DMXGetWindowAttributes)
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
DMXGetDesktopAttributes
1 CARD8 opcode (X assigned)
1 14 DMX opcode (X_DMXGetDesktopAttributes)
2 1 request length
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
2 INT16 width
2 INT16 height
2 INT16 shiftX
2 INT16 shiftY
16 unused
DMXChangeDesktopAttributes
1 CARD8 opcode (X assigned)
1 15 DMX opcode (X_DMXChangeDesktopAttributes)
2 2+n request length
4 BITMASK valueMask
4n LISTofVALUES valueList
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
20 unused
DMXGetInputCount
1 CARD8 opcode (X assigned)
1 4 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
DMXGetInputAttributes
1 CARD8 opcode (X assigned)
1 5 DMX opcode (X_DMXGetInputAttributes)
2 2 request length
4 CARD32 deviceId
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 (n+p)/4 reply length
4 CARD32 inputType
4 CARD32 physicalScreen
4 CARD32 physicalId
4 n nameLength
1 BOOL isCore
1 BOOL sendsCore
1 BOOL detached
5 unused
n name
p pad(n)
DMXAddInput
1 CARD8 opcode (X assigned)
1 16 DMX opcode (X_DMXAddInput)
2 3+m+(n+p)/4 request length
4 n displayNameLength
4 CARD32 valueMask
4m LISTofVALUES valueList
n displayName
p pad(n)
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
4 CARD32 physicalId
16 unused
DMXRemoveInput
1 CARD8 opcode (X assigned)
1 17 DMX opcode (X_DMXRemoveInput)
2 3 request length
4 CARD32 physicalId
==>
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
4 CARD32 status
20 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.