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.