aboutsummaryrefslogtreecommitdiff
path: root/xorg-server/hw/dmx/doc/DMXSpec-v1.txt
diff options
context:
space:
mode:
Diffstat (limited to 'xorg-server/hw/dmx/doc/DMXSpec-v1.txt')
-rw-r--r--xorg-server/hw/dmx/doc/DMXSpec-v1.txt458
1 files changed, 458 insertions, 0 deletions
diff --git a/xorg-server/hw/dmx/doc/DMXSpec-v1.txt b/xorg-server/hw/dmx/doc/DMXSpec-v1.txt
new file mode 100644
index 000000000..cea97b9fe
--- /dev/null
+++ b/xorg-server/hw/dmx/doc/DMXSpec-v1.txt
@@ -0,0 +1,458 @@
+
+
+ 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.