diff options
Diffstat (limited to 'xorg-server/hw/dmx/doc/DMXSpec-v1.txt')
| -rw-r--r-- | xorg-server/hw/dmx/doc/DMXSpec-v1.txt | 458 |
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. |