Client-to-Server DMX Extension to the X Protocol $Date: 2010/12/05 15:36:04 $, $Revision: 1.5 $ 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.