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 351. 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 462. Syntactic conventions 47 48 This document uses the same syntactic conventions requests and data 49 types as [X11R6.4]. 50 51 52 533. 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 604. 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 2985. Events 299 300 No new events are defined by this extension. 301 302 303 3046. Errors 305 306 No new events are defined by this extension. 307 308 309 3107. 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 4438. 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 4509. Acknowledgments 451 452 453 45410. 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. 459