xorg-server-1.4/hw/dmx/doc/DMXSpec-v1.txt

   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.