3 Client-to-Server DMX Extension to the X Protocol
7 Rickard E. (Rik) Faith (faith@redhat.com)
8 Kevin E. Martin (kem@redhat.com)
10 Copyright 2002-2004 Red Hat Inc., Raleigh, North Carolina.
12 Permission is hereby granted, free of charge, to any person
13 obtaining a copy of this software and associated documentation files
14 (the "Software"), to deal in the Software without restriction,
15 including without limitation on the rights to use, copy, modify,
16 merge, publish, distribute, sublicense, and/or sell copies of the
17 Software, and to permit persons to whom the Software is furnished to
18 do so, subject to the following conditions:
20 The above copyright notice and this permission notice (including the
21 next paragraph) shall be included in all copies or substantial
22 portions of the Software.
24 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
25 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
26 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
27 NON-INFRINGEMENT. IN NO EVENT SHALL RED HAT AND/OR THEIR SUPPLIERS
28 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
29 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
30 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
37 The client-to-server DMX extension to the X protocol (DMX) provides
38 normal client applications with the ability to determine information
39 about the characteristics of the Xdmx server and the back-end X
40 servers that DMX is using.
42 The name for this extension is "DMX".
46 2. Syntactic conventions
48 This document uses the same syntactic conventions requests and data
55 No new data types are defined by this extension. All data types
56 referenced in this document are defined in [X11R6.4].
70 The protocol this extension actually supports is indicated by
71 majorVersion and minorVersion (patchVersion indicates the
72 patchlevel and is for informational purposes only).
74 Any incompatible changes to the protocol should be indicated by
75 incrementing majorVersion.
77 Small, upward-compatible changes should be indicated by incrementing
80 Servers that support the protocol defined in this document will
81 return a majorVersion of 2 and a minorVersion of 2.
83 (Version 1.5 was the last version in the 1.x series; version 2.0 was
84 a testing version that was poorly defined.)
94 This request was first supported in version 1.5 of this protocol.
95 The status field in the reply was introduced in version 2.0 of this
96 protocol. Since the status field is ignored, no changes to the
97 underlying protocol were required.
99 This request flushes all pending protocol requests between the Xdmx
100 server and each back-end X server. It is used by clients that
101 talk directly to back-end X servers to ensure that all pending Xdmx
102 requests have reached all back-end servers and have been processed
105 The value of status is always 0.
109 DMXForceWindowCreation
116 This request was first supported in version 1.2 of this protocol.
117 This request was changed to have a reply in version 2.0 of this
118 protocol. The old version of this request was deprecated and will
119 return BadImplementation.
121 When using the lazy window creation optimization, windows are not
122 created on the back-end X servers until they are required. This
123 request forces the immediate creation of the window requested.
125 The value of status is always 0.
136 This request returns the number of screens that the Xdmx server
137 controls. Since a DMX screen usually fills all of the available
138 area on a back-end server, there is usually a one-to-one
139 correspondence between DMX screens and backend servers. However, it
140 is also possible for a DMX screen to cover only part of the
141 available area on a back-end server, and for more than one DMX
142 screen to occupy different parts of the visible area on the same
145 A DMX screen may be managed as a regular X screen in the Xdmx server
146 or may be joined with other DMX screens using Xinerama.
150 DMXGetScreenAttributes
151 physicalScreen: CARD32
154 logicalScreen: CARD32
155 screenWindowWidth: CARD16
156 screenWindowHeight: CARD16
157 screenWindowXoffset: INT16
158 screenWindowYoffset: INT16
159 rootWindowWidth: CARD16
160 rootWindowHeight: CARD16
161 rootWindowXoffset: INT16
162 rootWindowYoffset: INT16
163 rootWindowXorigin: INT16
164 rootWindowYorigin: INT16
168 This request is new in version 2.0 of this protocol. The old
169 DMXGetScreenInformation request is deprecated and will now return
172 This request returns attributes about a single DMX screen.
174 The physicalScreen value is between 0 and screenCount-1, inclusive
175 (values outside this range will result in a Value error).
177 The displayname is the name used to open the display, either from
178 the Xdmx command-line or from the configuration file.
180 The logicalScreen value is the value of the screen that that Xdmx
181 server exports to clients. When Xinerama is in use, this value is
182 typically 0 for all values of physicalScreen. If Xinerama is in
183 use, the rootWindowXOrigin and rootWindowYOrigin values specify
184 where the physical screen is positioned in the global Xinerama
185 coordinate system. Otherwise, these values are set to 0.
187 The screenWindow values comprise a geometry specification (see
188 X(7x)) for the location of the DMX screen on the back-end screen.
189 The coordinant system of the back-end display is used.
191 The first four rootWindow values comprise a geometry specification
192 (see X(7x)) for the location of the root window on the screen
193 window. The coordinant system of the screen window is used. In
194 most cases, the root window will have the same geometry as the DMX
195 screen window, and will occupy the same area of the back-end
196 display. (This would not be the case, for example, if automatic
197 projector alignment is used.)
201 DMXChangeScreensAttributes
204 screens: LISTofCARD32
205 valueMasks: LISTofCARD32
206 valueList: LISTofVALUES
211 Errors: Length, Alloc
213 This request was first supported in version 2.0 of this protocol.
214 (A singular version of this request with the ability to change some
215 RootWindow attributes was supported in version 1.3 of this protocol,
216 has been deprecated, and will return BadImplementation.)
218 This request changes the geometries and positions of the DMX screen
219 and DMX root windows on the back-end X servers.
221 The valueMask and valueList specify which attributes are to be
222 changed. The possible values are:
226 ScreenWindowWidth CARD16
227 ScreenWindowHeight CARD16
228 ScreenWindowXoffset INT16
229 ScreenWindowYoffset INT16
230 RootWindowWidth CARD16
231 RootWindowHeight CARD16
232 RootWindowXoffset INT16
233 RootWindowYoffset INT16
234 RootWindowXorigin INT16
235 RootWindowYorigin INT16
237 The attribute values have the same meaning as do the corresponding
238 values for DMXGetScreenAttributes.
240 Non-fatal errors will be returned in status (0 otherwise):
241 DmxBadXinerama: Xinerama is not active
242 DmxBadValue: The resulting position is not allowed
243 (e.g., one corner is outside the bounding box)
244 On error, errorScreen will contain the number of the screen that
245 caused the first error.
251 physicalScreen: CARD32
253 valueList: LISTofVALUES
256 physicalScreen: CARD32
258 Errors: Length, Alloc, Value
260 This request was first supported in version 2.2 of this protocol.
262 This request re-attaches the back-end physicalScreen to the Xdmx
263 server. Only back-end screens that have been previously detached
264 with DMXRemoveScreen may be added. The name of the back-end display
265 is given in displayName, and this will replace the name of the
266 back-end screen that was detached. Both the displayName and
267 physicalScreen must be correct for this request to work.
269 The valueMask and valueList specify the attributes to be used. The
274 ScreenWindowWidth CARD16
275 ScreenWindowHeight CARD16
276 ScreenWindowXoffset INT16
277 ScreenWindowYoffset INT16
278 RootWindowWidth CARD16
279 RootWindowHeight CARD16
280 RootWindowXoffset INT16
281 RootWindowYoffset INT16
282 RootWindowXorigin INT16
283 RootWindowYorigin INT16
285 The attribute values have the same meaning as do the corresponding
286 values for DMXGetScreenAttributes.
288 On success, status will be 0 and physicalScreen will contain the new
289 screen number. On failure, status will be non-zero. The status
290 will be 1 if any of the following occured:
291 * the -addremovescreens command-line option was not specified on
292 the Xdmx command line
293 * the value of physicalScreen is out of range
294 * physicalScreen has not been detached (with DMXRemoveScreen)
295 * displayName cannot be opened
296 * the visuals of displayname do not match the visuals that Xdmx
298 * the screen data for displayName does not match the data for the
299 previously removed display
300 The status will be DmxBadValue if the attribute values are out of
306 physicalScreen: CARD32
312 This request was first supported in version 2.2 of this protocol.
314 This request detaches the physicalScreen screen.
316 On success, status will be 0. On failure, the status will 1 if any
317 of the following occur:
318 * the -addremovescreens command-line option was not specified on
319 the Xdmx command line
320 * the value of physicalScreen is out of range
321 * the back-end screen has already been detached.
325 DMXGetWindowAttributes
329 screens: LISTofCARD32
330 windows: LISTofCARD32
334 Errors: Window, Alloc
336 This request computes the return values incorrectly for version 1.0
337 of this protocol. Version 1.1 of this protocol conforms to this
338 description. In version 2.0, the name of this request was changed
339 from DMXGetWindowInformation. However, since the request itself did
340 not change, no changes to the underlying protocol were made.
342 Given a window ID on the Xdmx server, this request returns data
343 about how the window is represented on the back-end X servers. For
344 each back-end X server that displays a portion of the window, the
345 following information is returned:
346 1) the number of the physical screen containing that portion
347 (which can be used with the DMXGetScreenAttributes request
348 to obtain more information about the screen),
349 2) the window ID on the back-end X server of the window
350 containing that portion,
351 3) the position and dimensions of the window on the back-end, in
352 screen coordinates, and
353 4) the visible area of the window on the back-end, in
354 window-relative coordinates (all zeros for windows that are
356 Note that DMX allows multiple back-end windows to overlap in their
357 view of the DMX logical window. Further, a logical window does not
358 have to be completely covered by back-end windows -- there may be
361 As an example, consider a 500x500 window that spans the top two
362 1024x768 back-end displays (A and B) of a 2048x1536 DMX display
363 composed of 4 1024x768 back-end displays arranged in a cube:
367 In this case, the DMXGetWindowAttributes call would return the
368 following information for the 500x500 window:
370 display A: 500x500 window at 1024-250,0 (relative to back end)
371 with 250x500 visible at 0,0 (relative to window origin)
373 display B: 500x500 window at -250,0 (relative to back end)
374 with 250x500 visible at 250,0 (relative to window origin)
376 display C: 500x500 window at 1024-250,-768 with 0x0 visible at 0,0
378 display D: 500x500 window at -250,-768 with 0x0 visible at 0,0
380 Note that if the specified window has not yet been mapped when
381 DMXGetWindowAttributes is called, then a subsequent XMapWindow call
382 might be buffered in xlib while requests directly to the back-end X
383 servers are processed. This race condition can be solved by calling
384 DMXSync before talking directly to the back-end X servers.
388 DMXGetDesktopAttributes
397 This request was first supported in version 2.0 of this protocol.
399 This request returns the size of the bounding box of the whole
400 screen in width and height. The shiftX and shiftY values will
401 always be 0. The global bounding box is computed whether or not
402 Xinerama is active, and may be larger than the Xinerama screen size
403 because of information in the configuration file.
407 DMXChangeDesktopAttributes
409 valueList: LISTofVALUE
413 Errors: Length, Value
415 This request was first supported in version 2.0 of this protocol.
417 This request resizes the bounding box of the whole screen when using
418 the Xinerama extension. Otherwise, it has no effect on the screen
419 layout. The valueMask and valueList specify which attributes are to
420 be changed. The possible values are:
429 Width and Height specify the new width and height for the bounding
430 box. ShiftX and ShiftY specify where the Xinerama origin will be
431 placed with respect to the origin of the new bounding box. This
432 allows the left and upper edges of the bounding box to be changed
433 without changing the visual position of the windows on the desktop.
434 If Width or Height is not specified, the current values will be
435 used. If ShiftX or ShiftY is not specified, 0 will be used.
437 All coordinants are in the global DMX coordinant system. If
438 Xinerama is not active, this request is not useful.
440 Non-fatal errors will be returned in status (0 otherwise):
441 DmxBadXinerama: Xinerama is not active
442 DmxBadValue: The size of the bounding box is too large
450 This request was first supported in version 1.1 of this protocol.
452 This request returns the number of input devices connected to the
453 Xdmx server. This number is the same as that returned by
454 XListInputDevices, but is available even when the XInput extension
459 DMXGetInputAttributes
463 physicalScreen: CARD32
472 This request was first supported in version 1.1 of this protocol.
473 In version 2.0, the name of this request was changed from
474 DMXGetInputInformation. However, since the request itself did not
475 change, no changes to the underlying protocol were made. In version
476 2.2, the name of detached was changed from reservation. There was
477 no change in underlying protocol.
479 This request returns information about the specified input device
480 that cannot be obtained from the XListInputDeivices call. The
481 deviceId is the same as that used by the XListInputDevices call, and
482 must be in the range 0 to inputCount-1, inclusive (values outside
483 this range will result in a Value error).
485 The value of inputType will always be valid, and will be one of the
487 0 for local (and dummy) devices,
488 1 for console devices, and
489 2 for back-end devices.
491 For local devices, all other fields returned, except isCore and
492 sendsCore, are invalid.
494 For console devices, the physicalScreen and physicalID will be
495 invalid, and the name will return the name of the X server on which
496 the console window is displayed.
498 For back-end devices, the physicalScreen will identify the back-end
499 display and can be used as an argument to DMXGetScreenAttributes to
500 obtain more information; the physicalId will be the XInput device id
501 on the back-end X server; and the name will be invalid (since it
502 does not provide any additional information that cannot be obtained
503 with DMXGetScreenAttributes).
505 If isCore is True, then this device is active as a true core input
506 device and will send core events. If sendsCore is True, then this
507 device is an XInput extension device, but sends core events instead
508 of extension events. Note that this behavior is different from that
509 of XFree86 or Xorg, where XInput extension devices may send both
510 extension events and core events.
512 If detached is True, then this device has been detached and is no
513 longer producing input events. The device may be reattached using
521 valueList: LISTofVALUES
526 Errors: Value, Access
528 This request was first supported in version 2.2 of this protocol.
530 The valueMask and valueList specify the attributes to be used. The
536 InputPhysicalScreen CARD32
539 This request attaches an input device to the Xdmx server. The value
540 of inputType will be one:
541 1 for console devices, and
542 2 for back-end devices.
543 Other values of InputType will return a BadValue error. Local
544 devices (inputType=0 in DMXGetInputAttributes) cannot be attached or
545 removed. For console devices, displayName will store the name of
546 the display to be used.
548 For back-end devices, InputPhysicalScreen will specify the screen
549 number. BadValue will be returned if the screen number is out of
550 range. BadAccess will be returned if the input has already been
551 attached or if the backend screen is currently detached.
553 If InputSendsCore is True, the new device will be added as a true
556 If a device was removed with DMXRemoveInput an attempt will be made
557 to reconnect the previous devices (InputSendsCore is ignored in this
567 Errors: Value, Access
569 This request was first supported in version 2.2 of this protocol.
571 This request detaches the input device with physicalId, and all
572 associated inputs (e.g., if the physicalId is a backend mouse, and a
573 keyboard is also attached to the backend, then both devices will be
574 detached). If the physicalId is outside the valid range (0 to one
575 less than the value returned by DMXInputCount), BadValue is
576 returned. If the physicalId has already been detached, BadAccess is
577 returned. The status is always 0.
583 No new events are defined by this extension.
589 No new events are defined by this extension.
595 Deprecated DMX opcodes:
596 DMXGetScreenInformation 2
597 DMXForceWindowCreation 6
598 DMXReconfigureScreen 7
603 DMXForceWindowCreation 9
606 DMXGetScreenAttributes 10
607 DMXChangeScreensAttributes 11
611 DMXGetWindowAttributes 3
613 DMXGetDesktopAttributes 14
614 DMXChangeDesktopAttributes 15
617 DMXGetInputAttributes 5
622 1 CARD8 opcode (X assigned)
623 1 0 DMX opcode (X_DMXQueryVersion)
628 2 CARD16 sequence number
630 4 CARD32 majorVersion
631 4 CARD32 minorVersion
632 4 CARD32 patchVersion
636 1 CARD8 opcode (X assigned)
637 1 8 DMX opcode (X_DMXSync)
642 2 CARD16 sequence number
647 DMXForceWindowCreation
648 1 CARD8 opcode (X assigned)
649 1 9 DMX opcode (X_DMXForceWindowCreation)
655 2 CARD16 sequence number
662 1 CARD8 opcode (X assigned)
663 1 1 DMX opcode (X_DMXGetScreenCount)
668 2 CARD16 sequence number
673 DMXGetScreenAttributes
674 1 CARD8 opcode (X assigned)
675 1 10 DMX opcode (X_DMXGetScreenAttributes)
677 4 CARD32 physicalScreen
681 2 CARD16 sequence number
682 4 1+(n+p)/4 reply length
683 4 n displayNameLength
684 4 CARD32 logicalScreen
685 2 CARD16 screenWindowWidth
686 2 CARD16 screenWindowHeight
687 2 INT16 screenWindowXoffset
688 2 INT16 screenWindowYoffset
689 2 CARD16 rootWindowWidth
690 2 CARD16 rootWindowHeight
691 2 INT16 rootWindowXoffset
692 2 INT16 rootWindowYoffset
693 2 INT16 rootWindowXorigin
694 2 INT16 rootWindowYorigin
698 DMXChangeScreensAttributes
699 1 CARD8 opcode (X assigned)
700 1 11 DMX opcode (X_DMXChangeScreenAttributes)
701 2 3+s+m+n request length
704 4s LISTofCARD32 screens
705 4m LISTofCARD32 valueMasks
706 4n LISTofVALUES valueList
710 2 CARD16 sequence number
718 1 CARD8 opcode (X assigned)
719 1 12 DMX opcode (X_DMXAddScreen)
720 2 3+m+(n+p)/4 request length
721 4 n displayNameLength
722 4 CARD32 physicalScreen
724 4m LISTofVALUES valueList
730 2 CARD16 sequence number
733 4 CARD32 physicalScreen
737 1 CARD8 opcode (X assigned)
738 1 13 DMX opcode (X_DMXRemoveScreen)
740 4 CARD32 physicalScreen
744 2 CARD16 sequence number
749 DMXGetWindowAttributes
750 1 CARD8 opcode (X assigned)
751 1 3 DMX opcode (X_DMXGetWindowAttributes)
757 2 CARD16 sequence number
761 n*4 LISTofCARD32 screens
762 n*4 LISTofCARD32 windows
763 n*8 LISTofRECTANGLE pos
764 n*8 LISTofRECTANGLE vis
766 DMXGetDesktopAttributes
767 1 CARD8 opcode (X assigned)
768 1 14 DMX opcode (X_DMXGetDesktopAttributes)
773 2 CARD16 sequence number
781 DMXChangeDesktopAttributes
782 1 CARD8 opcode (X assigned)
783 1 15 DMX opcode (X_DMXChangeDesktopAttributes)
786 4n LISTofVALUES valueList
790 2 CARD16 sequence number
796 1 CARD8 opcode (X assigned)
797 1 4 DMX opcode (X_DMXGetInputCount)
802 2 CARD16 sequence number
807 DMXGetInputAttributes
808 1 CARD8 opcode (X assigned)
809 1 5 DMX opcode (X_DMXGetInputAttributes)
815 2 CARD16 sequence number
816 4 (n+p)/4 reply length
818 4 CARD32 physicalScreen
829 1 CARD8 opcode (X assigned)
830 1 16 DMX opcode (X_DMXAddInput)
831 2 3+m+(n+p)/4 request length
832 4 n displayNameLength
834 4m LISTofVALUES valueList
840 2 CARD16 sequence number
847 1 CARD8 opcode (X assigned)
848 1 17 DMX opcode (X_DMXRemoveInput)
854 2 CARD16 sequence number
860 8. Changes to existing requests/replies/events
862 No changes to existing requests, replies, or events are necessitated
873 [X11R6.4] Robert W. Sheifler. X Window System Protocol, X Consortium
874 Standard, X Version 11, Release 6.4. Available from
875 xc/doc/specs/XProtocol and xc/doc/hardcopy/XProtocol.