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