| 1 | |
| 2 | |
| 3 | Client-to-Server DMX Extension to the X Protocol |
| 4 | |
| 5 | $Date$, $Revision$ |
| 6 | |
| 7 | Rickard E. (Rik) Faith (faith@redhat.com) |
| 8 | Kevin E. Martin (kem@redhat.com) |
| 9 | |
| 10 | Copyright 2002,2003 Red Hat Inc., Raleigh, North Carolina. |
| 11 | |
| 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: |
| 19 | |
| 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. |
| 23 | |
| 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 |
| 31 | SOFTWARE. |
| 32 | |
| 33 | |
| 34 | |
| 35 | 1. Overview |
| 36 | |
| 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. |
| 41 | |
| 42 | The name for this extension is "DMX". |
| 43 | |
| 44 | |
| 45 | |
| 46 | 2. Syntactic conventions |
| 47 | |
| 48 | This document uses the same syntactic conventions requests and data |
| 49 | types as [X11R6.4]. |
| 50 | |
| 51 | |
| 52 | |
| 53 | 3. Data types |
| 54 | |
| 55 | No new data types are defined by this extension. All data types |
| 56 | referenced in this document are defined in [X11R6.4]. |
| 57 | |
| 58 | |
| 59 | |
| 60 | 4. Requests |
| 61 | |
| 62 | DMXQueryVersion |
| 63 | ==> |
| 64 | majorVersion: CARD32 |
| 65 | minorVersion: CARD32 |
| 66 | patchVersion: CARD32 |
| 67 | |
| 68 | The protocol this extension actually supports is indicated by |
| 69 | majorVersion and minorVersion (patchVersion indicates the |
| 70 | patchlevel and is for informational purposes only). |
| 71 | |
| 72 | Any incompatible changes to the protocol should be indicated by |
| 73 | incrementing majorVersion. |
| 74 | |
| 75 | Small, upward-compatible changes should be indicated by incrementing |
| 76 | minorVersion. |
| 77 | |
| 78 | Servers that support the protocol defined in this document will |
| 79 | return a majorVersion of 1 and a minorVersion of 1. |
| 80 | |
| 81 | |
| 82 | |
| 83 | DMXGetScreenCount |
| 84 | ==> |
| 85 | screenCount: CARD32 |
| 86 | |
| 87 | This request returns the number of back-end screens that the Xdmx |
| 88 | server controls. A back-end screen may be managed as a regular X |
| 89 | screen in the Xdmx server or may be joined with other back-end |
| 90 | screens using Xinerama. (The information returned by this request |
| 91 | does not change while Xdmx is running and may be cached on the |
| 92 | client side.) |
| 93 | |
| 94 | |
| 95 | |
| 96 | DMXGetScreenInformation |
| 97 | physicalScreen: CARD32 |
| 98 | ==> |
| 99 | displayName: STRING8 |
| 100 | width: CARD16 |
| 101 | height: CARD16 |
| 102 | xoffset: INT16 |
| 103 | yoffset: INT16 |
| 104 | logicalScreen: CARD32 |
| 105 | xorigin: INT16 |
| 106 | yorigin: INT16 |
| 107 | |
| 108 | Errors: Value |
| 109 | |
| 110 | This request returns information about individual back-end screens. |
| 111 | The physicalScreen value is between 0 and screenCount-1, inclusive |
| 112 | (values outside this range will result in a Value error). The |
| 113 | displayname is the name used to open the display, either from the |
| 114 | Xdmx command-line or from the configuration file. The width, |
| 115 | height, xoffset, and yoffset values comprise a geometry |
| 116 | specification (see X(7x)) for the location of the DMX window on the |
| 117 | back-end screen. This request will always return non-negative |
| 118 | (i.e., normalized) values for xoffset and yoffset. The |
| 119 | logicalScreen value is the value of the screen that that Xdmx server |
| 120 | exports to clients. When Xinerama is in use, this value is |
| 121 | typically 0 for all values of physicalScreen. If Xinerama is in |
| 122 | use, the xorigin and yorigin values specify where the physical |
| 123 | screen is positioned in the global Xinerama coordinate system. |
| 124 | Otherwise, these values are set to 0. (The information returned by |
| 125 | this request does not change while Xdmx is running and may be cached |
| 126 | on the client side.) |
| 127 | |
| 128 | |
| 129 | |
| 130 | DMXGetWindowInformation |
| 131 | window: CARD32 |
| 132 | ==> |
| 133 | screenCount: CARD32 |
| 134 | screens: LISTofCARD32 |
| 135 | windows: LISTofCARD32 |
| 136 | pos: LISTofRECTANGLE |
| 137 | vis: LISTofRECTANGLE |
| 138 | |
| 139 | Errors: Window, Alloc |
| 140 | |
| 141 | This request computed the return values incorrectly for version 1.0 |
| 142 | of this protocol. Version 1.1 of this protocol conforms to this |
| 143 | description. |
| 144 | |
| 145 | Given a window ID on the Xdmx server, this request returns data |
| 146 | about how the window is represented on the back-end X servers. For |
| 147 | each back-end X server that displays a portion of the window, the |
| 148 | following information is returned: |
| 149 | 1) the number of the physical screen containing that portion |
| 150 | (which can be used with the DMXGetScreenInformation request |
| 151 | to obtain more information about the screen), |
| 152 | 2) the window ID on the back-end X server of the window |
| 153 | containing that portion, |
| 154 | 3) the position and dimensions of the window on the back-end, in |
| 155 | screen coordinates, and |
| 156 | 4) the visible area of the window on the back-end, in |
| 157 | window-relative coordinates (all zeros for windows that are |
| 158 | not visible) |
| 159 | Note that DMX allows multiple back-end windows to overlap in their |
| 160 | view of the DMX logical window. Further, a logical window does not |
| 161 | have to be completely covered by back-end windows -- there may be |
| 162 | gaps. |
| 163 | |
| 164 | As an example, consider a 500x500 window that spans the top two |
| 165 | 1024x768 back-end displays (A and B) of a 2048x1536 DMX display |
| 166 | composed of 4 1024x768 back-end displays arranged in a cube: |
| 167 | A B |
| 168 | C D |
| 169 | |
| 170 | In this case, the DMXGetWindowInformation call would return the |
| 171 | following information for the 500x500 window: |
| 172 | |
| 173 | display A: 500x500 window at 1024-250,0 (relative to back end) |
| 174 | with 250x500 visible at 0,0 (relative to window origin) |
| 175 | |
| 176 | display B: 500x500 window at -250,0 (relative to back end) |
| 177 | with 250x500 visible at 250,0 (relative to window origin) |
| 178 | |
| 179 | display C: 500x500 window at 1024-250,-768 with 0x0 visible at 0,0 |
| 180 | |
| 181 | display D: 500x500 window at -250,-768 with 0x0 visible at 0,0 |
| 182 | |
| 183 | Note that if the specified window has not yet been mapped when |
| 184 | DMXGetWindowInformation is called, then a subsequent XMapWindow call |
| 185 | might be buffered in xlib while requests directly to the back-end X |
| 186 | servers are processed. This race condition can be solved by calling |
| 187 | DMXSync before talking directly to the back-end X servers. |
| 188 | |
| 189 | |
| 190 | DMXGetInputCount |
| 191 | ==> |
| 192 | inputCount: CARD32 |
| 193 | |
| 194 | This request was first supported in version 1.1 of this protocol. |
| 195 | |
| 196 | This request returns the number of input devices connected to the |
| 197 | Xdmx server. This number is the same as that returned by |
| 198 | XListInputDevices, but is available even when the XInput extension |
| 199 | is not supported. |
| 200 | |
| 201 | |
| 202 | |
| 203 | DMXGetInputInformation |
| 204 | deviceId: CARD32 |
| 205 | ==> |
| 206 | inputType: CARD32 |
| 207 | physicalScreen: CARD32 |
| 208 | physicalId: CARD32 |
| 209 | isCore: BOOL |
| 210 | sendsCore: BOOL |
| 211 | name: STRING8 |
| 212 | |
| 213 | Errors: Value |
| 214 | |
| 215 | This request was first supported in version 1.1 of this protocol. |
| 216 | |
| 217 | This request returns information about the specified input device |
| 218 | that cannot be obtained from the XListInputDeivices call. The |
| 219 | deviceId is the same as that used by the XListInputDevices call, and |
| 220 | must be in the range 0 to inputCount-1, inclusive (values outside |
| 221 | this range will result in a Value error). |
| 222 | |
| 223 | The value of inputType will always be value, and will be one of the |
| 224 | following values: |
| 225 | 0 for local (and dummy) devices, |
| 226 | 1 for console devices, and |
| 227 | 2 for back-end devices. |
| 228 | |
| 229 | For local devices, all other fields returned, except isCore and |
| 230 | sendsCore, are invalid. |
| 231 | |
| 232 | For console devices, the physicalScreen and physicalID will be |
| 233 | invalid, and the name will return the name of the X server on which |
| 234 | the console window is displayed. |
| 235 | |
| 236 | For back-end devices, the physicalScreen will identify the back-end |
| 237 | display and can be used as an argument to DMXGetScreenInformation to |
| 238 | obtain more information; the physicalId will be the XInput device id |
| 239 | on the back-end X server; and the name will be invalid (since it |
| 240 | does not provide any additional information that cannot be obtained |
| 241 | with DMXGetScreenInformation). |
| 242 | |
| 243 | If isCore is True, then this device is active as a true core input |
| 244 | device and will send core events. If sendsCore is True, then this |
| 245 | device queried an XInput extension device, but sends core events |
| 246 | instead of extension events. Note that this behavior is different |
| 247 | from that of XFree86, where XInput extension devices may send both |
| 248 | extension events and core events. |
| 249 | |
| 250 | |
| 251 | |
| 252 | DMXForceWindowCreation |
| 253 | window: CARD32 |
| 254 | ==> |
| 255 | |
| 256 | Errors: Window |
| 257 | |
| 258 | This request was first supported in version 1.2 of this protocol. |
| 259 | |
| 260 | When using the lazy window creation optimization, windows are not |
| 261 | created on the back-end X servers until they are required. This |
| 262 | request forces the immediate creation of the window requested. |
| 263 | |
| 264 | |
| 265 | |
| 266 | DMXReconfigureScreen |
| 267 | screen: CARD32 |
| 268 | x: INT16 |
| 269 | y: INT16 |
| 270 | ==> |
| 271 | status: CARD32 |
| 272 | |
| 273 | Errors: Value |
| 274 | |
| 275 | This request was first supported in version 1.3 of this protocol. |
| 276 | |
| 277 | This request reconfigures the screen position to coordinates (x,y) |
| 278 | when using the Xinerama extension. Otherwise, it is a NOP. Illegal |
| 279 | values for screen will result in a BadValue error. Other non-fatal |
| 280 | errors will be returned in status. |
| 281 | |
| 282 | |
| 283 | |
| 284 | DMXSync |
| 285 | ==> |
| 286 | |
| 287 | This request was first supported in version 1.5 of this protocol. |
| 288 | |
| 289 | This request flushes all pending protocol requests between the Xdmx |
| 290 | server and each back-end X server. It is used by a client that |
| 291 | talks directly to back-end X servers |
| 292 | |
| 293 | To ensure proper synchronization semantics, this request has a |
| 294 | reply, but the reply does not carry any information. |
| 295 | |
| 296 | |
| 297 | |
| 298 | 5. Events |
| 299 | |
| 300 | No new events are defined by this extension. |
| 301 | |
| 302 | |
| 303 | |
| 304 | 6. Errors |
| 305 | |
| 306 | No new events are defined by this extension. |
| 307 | |
| 308 | |
| 309 | |
| 310 | 7. Encoding |
| 311 | |
| 312 | DMXQueryVersion |
| 313 | 1 CARD8 opcode (X assigned) |
| 314 | 1 0 DMX opcode (X_DMXQueryVersion) |
| 315 | 2 1 request length |
| 316 | ==> |
| 317 | 1 1 Reply |
| 318 | 1 unused |
| 319 | 2 CARD16 sequence number |
| 320 | 4 0 reply length |
| 321 | 4 CARD32 majorVersion |
| 322 | 4 CARD32 minorVersion |
| 323 | 4 CARD32 patchVersion |
| 324 | 12 unused |
| 325 | |
| 326 | DMXGetScreenCount |
| 327 | 1 CARD8 opcode (X assigned) |
| 328 | 1 1 DMX opcode (X_DMXGetScreenCount) |
| 329 | 2 1 request length |
| 330 | ==> |
| 331 | 1 1 Reply |
| 332 | 1 unused |
| 333 | 2 CARD16 sequence number |
| 334 | 4 0 reply length |
| 335 | 4 CARD32 screenCount |
| 336 | 20 unused |
| 337 | |
| 338 | DMXGetScreenInformation |
| 339 | 1 CARD8 opcode (X assigned) |
| 340 | 1 2 DMX opcode (X_DMXGetScreenInformation) |
| 341 | 2 2 request length |
| 342 | 4 CARD32 physicalScreen |
| 343 | ==> |
| 344 | 1 1 Reply |
| 345 | 1 unused |
| 346 | 2 CARD16 sequence number |
| 347 | 4 n/4+p reply length |
| 348 | 4 n displayNameLength |
| 349 | 2 CARD16 width |
| 350 | 2 CARD16 height |
| 351 | 2 INT16 xoffset |
| 352 | 2 INT16 yoffset |
| 353 | 4 CARD32 logicalScreen |
| 354 | 2 INT16 xorigin |
| 355 | 2 INT16 yorigin |
| 356 | 4 unused |
| 357 | n displayName |
| 358 | p pad(n) |
| 359 | |
| 360 | DMXGetWindowInformation |
| 361 | 1 CARD8 opcode (X assigned) |
| 362 | 1 3 DMX opcode (X_DMXGetWindowInformation) |
| 363 | 2 2 request length |
| 364 | 4 CARD32 window |
| 365 | ==> |
| 366 | 1 1 Reply |
| 367 | 1 unused |
| 368 | 2 CARD16 sequence number |
| 369 | 4 n*6 reply length |
| 370 | 4 n screenCount |
| 371 | 20 unused |
| 372 | n*4 LISTofCARD32 screens |
| 373 | n*4 LISTofCARD32 windows |
| 374 | n*8 LISTofRECTANGLE pos |
| 375 | n*8 LISTofRECTANGLE vis |
| 376 | |
| 377 | DMXGetInputCount |
| 378 | 1 CARD8 opcode (X assigned) |
| 379 | 1 DMX opcode (X_DMXGetInputCount) |
| 380 | 2 1 request length |
| 381 | ==> |
| 382 | 1 1 Reply |
| 383 | 1 unused |
| 384 | 2 CARD16 sequence number |
| 385 | 4 0 reply length |
| 386 | 4 CARD32 inputCount |
| 387 | 20 unused |
| 388 | |
| 389 | DMXGetInputInformation |
| 390 | 1 CARD8 opcode (X assigned) |
| 391 | 1 4 DMX opcode (X_DMXGetInputInformation) |
| 392 | 2 2 request length |
| 393 | 4 CARD32 deviceId |
| 394 | ==> |
| 395 | 1 1 Reply |
| 396 | 1 unused |
| 397 | 2 CARD16 sequence number |
| 398 | 4 n/4+p reply length |
| 399 | 4 CARD32 inputType |
| 400 | 4 CARD32 physicalScreen |
| 401 | 4 CARD32 physicalId |
| 402 | 4 n nameLength |
| 403 | 1 BOOL isCore |
| 404 | 1 BOOL sendsCore |
| 405 | 6 unused |
| 406 | n name |
| 407 | p pad(n) |
| 408 | |
| 409 | DMXForceWindowCreation |
| 410 | 1 CARD8 opcode (X assigned) |
| 411 | 1 2 DMX opcode (X_DMXForceWindowCreation) |
| 412 | 2 2 request length |
| 413 | 4 CARD32 window |
| 414 | ==> |
| 415 | |
| 416 | DMXReconfigureScreen |
| 417 | 1 CARD8 opcode (X assigned) |
| 418 | 1 2 DMX opcode (X_DMXReconfigureScreen) |
| 419 | 2 2 request length |
| 420 | 4 CARD32 screen |
| 421 | 2 INT16 x |
| 422 | 2 INT16 y |
| 423 | ==> |
| 424 | 1 1 Reply |
| 425 | 1 unused |
| 426 | 2 CARD16 sequence number |
| 427 | 4 0 reply length |
| 428 | 4 CARD32 status |
| 429 | 20 unused |
| 430 | |
| 431 | DMXSync |
| 432 | 1 CARD8 opcode (X assigned) |
| 433 | 1 0 DMX opcode (X_DMXSync) |
| 434 | 2 1 request length |
| 435 | ==> |
| 436 | 1 1 Reply |
| 437 | 1 unused |
| 438 | 2 CARD16 sequence number |
| 439 | 4 0 reply length |
| 440 | 24 unused |
| 441 | |
| 442 | |
| 443 | 8. Changes to existing requests/replies/events |
| 444 | |
| 445 | No changes to existing requests, replies, or events are necessitated |
| 446 | by this extension. |
| 447 | |
| 448 | |
| 449 | |
| 450 | 9. Acknowledgments |
| 451 | |
| 452 | |
| 453 | |
| 454 | 10. References |
| 455 | |
| 456 | [X11R6.4] Robert W. Sheifler. X Window System Protocol, X Consortium |
| 457 | Standard, X Version 11, Release 6.4. Available from |
| 458 | xc/doc/specs/XProtocol and xc/doc/hardcopy/XProtocol. |