1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
|
The X Resize, Rotate and Reflect Extension
Version 1.0
2002-10-4
Jim Gettys
Jim.Gettys@hp.com
Keith Packard
keithp@xfree86.org
Cambridge Research Laboratory
HP Labs
Hewlett Packard Company
1. Introduction
The X Resize, Rotate and Reflect Extension, called RandR for short,
brings the ability to resize, rotate and reflect the root window of a
screen. It is based on the X Resize and Rotate Extension as specified
in the Proceedings of the 2001 Usenix Technical Conference [RANDR].
RandR as implemented and integrated into the XFree86 server differs in
one substantial fashion from the design discussed in that paper: that
is, RandR 1.0 does not implement the depth switching described in that
document, and the support described for that in the protocol in that
document and in the XFree86 implementationhas been removed from the
protocol described here, as it has been overtaken by events.
These events include:
o Modern toolkits (in this case, GTK+ 2.x) have progressed to the point
of implementing migration between screens of arbitrary depths
o The continued advance of Moore's law has made limited amounts of VRAM
less of an issue, reducing the pressure to implement depth switching
on laptops or desktop systems
o The continued decline of legacy toolkits whose design would have
required depth switching to support migration
o The lack of depth switchin implementation experience in the
intervening time, due to events beyond our control
Additionally, the requirement to support depth switching might
complicate other re-engineering of the device independent part of the
X server that is currently being contemplated.
Rather than further delaying RandR's widespread deployment for a
feature long wanted by the community (resizing of screens,
particularly on laptops), or the deployment of a protocol design that
might be flawed due to lack of implementation experience, we decided
to remove depth switching from the protocol. It may be implementated
at a later time if resources and interests permit as a revision to the
protocol described here, which will remain a stable base for
applications. The protocol described here has been implemented in the
main XFree86 server, and more fully in the TinyX implementation in the
XFree86 distribution, which fully implements resizing, rotation and
reflection.
2. Acknowlegements
Our thanks to the contributors to the design found on the xpert mailing list.
2. Screen change model
Screens may change dynamically, either under control of this
extension, or due to external events. Examples include: monitors being
swapped, you pressing a button to switch from internal display to an
external monitor on a laptop, or, eventually, the hotplug of a display
card entirely on busses such as Cardbus which permit hot-swap (which
will require other work in addition to this extension).
Since the screen configuration is dynamic and asynchronous to the
client and may change at any time RandR provides mechanisms to ensure
that your clients view is up to date with the configuration
possibilities of the moment and enforces applications that wish to
control the configuration to prove that their information is up to
date before honoring requests to change the screen configuration (by
requiring a timestamp on the request).
Interested applications are notified whenever the screen configuration
changes, providing the current size of the screen and subpixel order
(see the Render extension [RENDER]), to enabel proper rendering of
subpixel decimated client text to continue, along with a time stamp of
the configuration change. A client must refresh its knowledge of the
screen configuration before attempting to change the configuration
after a notification, or the request will fail.
To avoid multiplicative explosion between orientation, reflection
and sizes, the sizes are only those sizes in the normal (0) rotation.
Rotation and reflection and how they interact can be confusing. In
Randr, the coordinate system is rotated in a counter-clockwise
direction relative to the normal orientation. Reflection is along the
window system coordinate system, not the physical screen X and Y axis,
so that rotation and reflection do not interact. The other way to
consider reflection is to is specified in the "normal" orientation,
before rotation, if you find the other way confusing.
We expect that most clients and toolkits will be oblivious to changes
to the screen stucture, as they generally use the values in the
connections Display structure directly. By toolkits updating the
values on the fly, we believe pop-up menus and other pop up windows
will position themselves correctly in the face of screen configuration
changes (the issue is ensuring that pop-ups are visible on the
reconfigured screen).
3. Data Types
The subpixel order is shared with the Render extension, and is
documented there. The only datatype defined is the screen size,
defined in the normal (0 degree) orientation.
4. Errors
There are no new error types defined by this extension.
5. Protocol Types
ROTATION {
RR_rotate_0
RR_rotate_90
RR_rotate_180
RR_rotate_270
RR-Reflect_X
RR_Reflect_Y }
RRSELECTMASK { RRScreenChangeNotifyMask }
SIZEID { CARD16 }
SUBPIXELORDER { SubPixelUnknown The subpixel order uses the Render
SubPixelHorizontalRGB extensions definitions; they are here
SubPixelHorizontalBGR only for convenience.
SubPixelVerticalRGB
SubPixelVerticalBGR
SubPixelNone }
6. Extension Initialization
The name of this extension is "RANDR".
RRQueryVersion
client-major-version: CARD32
client-minor-version: CARD32
->
major-version: CARD32
minor-version: CARD32
The client sends the highest supported version to the server
and the server sends the highest version it supports, but no
higher than the requested version. Major versions changes can
introduce incompatibilities in existing functionality, minor
version changes introduce only backward compatible changes.
It is the clients responsibility to ensure that the server
supports a version which is compatible with its expectations.
7. Extension Requests
RRSelectInput
window: WINDOW
enable: SETofRRSELECTMASK
Errors: BadWindow, BadValue
If enable is RRScreenChangeNotifyMask, RRScreenChangeNotify
events will be sent anytime the screen configuration changes,
either from this protocol extension, or due to detected
external screen configuration changes. RRScreenChangeNotify
may also be sent immediately if the screen configuration has
changed since the client connected, to avoid race conditions.
RRSetScreenConfig
drawable: DRAWABLE
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
sizeID: SIZEID
rotation: ROTATION
rate: CARD16
->
new-timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
root: WINDOW
subpixelOrder: SUBPIXELORDER
Errors: BadValue, BadMatch
If the timestamp in this request is less than the time when
the configuration was last successfully set, the request is
ignored and False returned in success. If the
config-timestamp in this request is not equal to when the
server's screen configurations last changed, the request is
ignored and False returned in success. This could occur if
the screen changed since you last made a RRGetScreenInfo
request, perhaps by a different piece of display hardware
being installed. Rather than allowing an incorrect call to be
executed based on stale data, the server will ignore the
request.
If rate is zero, the server selects an appropriate rate.
If the request succeeds, this request sets the screen to the
specified size, rate, rotation and reflection. If the requests
succeeds, the new-time-stamp is returned containing the time
when the screen configuration was changed and config-timestamp
is returned to indicate when the possible screen
configurations were last changed, and success is set to True.
The root window for the screen indicated by the drawable
argument is also returned, along with the subpixel order, to
allow correct subpixel rendering.
BadValue errors are generated if the rotation is not an
allowed rotation. BadValue errors are generated, if, when the
timestamps would allow the operation to succeed, or size-index
are not possible (out of range).
RRGetScreenInfo
window: WINDOW
->
rotations: SETofROTATION
root: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
nSizes: CARD16
sizeID: SIZEID
rotation: ROTATION
rate: CARD16
sizes: LISTofSCREENSIZE
refresh: LISTofREFRESH
where:
SCREENSIZE {
widthInPixels, heightInPixels: CARD16
widthInMillimeters, heightInMillimeters: CARD16 }
REFRESH {
rates: LISTofCARD16
}
Errors: BadWindow
This event is delivered to clients selecting for notification
with RRSelectInput requests using a RRScreenChangeNotifyMask.
Size-index indicates which size is active. The returned
window is the window requsting notification.
This call returns the root window of the screen which has changed.
Rotations contains the set of rotations and reflections
supported by the screen of the window requested. The root
window of that screen is reported. The number of current sizes
supported is returned, along with which size rotation and
reflection the screen is currently set to.
The config-timestamp indicates when the screen configuration
information last changed: requests to set the screen will fail
unless the timestamp indicates that the information the client
is using is up to date, to ensure clients can be well behaved
in the face of race conditions. Similarly, timestamp indicates
when the configuration was last set, and must both must be up
to date in a call to RRSetScreenConfig for it to succeed.
Rate is the current refresh rate. This is zero when the refresh
rate is unknown or on devices for which refresh is not relevant.
Sizes is the list of possible frame buffer sizes (at the
normal orientation, each provide both the linear physical size
of the screen and the pixel size.
Refresh is the list of refresh rates for each size, each element
of sizes has a cooresponding element in refresh. An empty list
indicates no known rates, or a device for which refresh is not
relevant.
The default size of the screen (the size that would become the
current size when the server resets) is the first size in the
list. The potential screen sizes themselves are also
returned.
Toolkits SHOULD use RRScreenChangeSelectInput to be notified
via a RRScreenChangeNotify event, so that they can adapt to
screen size changes.
8. Extension Events
Clients MAY select for ConfigureNotify on the root window to be
informed of screen changes. This may be advantageous if all your
clients need to know is the size of the root window, as it avoids
round trips to set up the extension.
RRScreenChangeNotify is sent if RRSelectInput has requested it
whenever properties of the screen change, which may be due to external
factors, such as recabling a monitor, etc.
RRScreenChangeNotify
rotation: ROTATION; new rotation
sequenceNumber: CARD16 low 16 bits of request's seq. number
timestamp: TIMESTAMP time screen was changed
configTimestamp: TIMESTAMP time config data was changed
root: WINDOW root window of screen
window: WINDOW window requesting notification
sizeID: SIZEID new ID of size
subpixelOrder: SUBPIXELORDER order of subpixels
widthInPixels: INT16
heightInPixels: INT16
widthInMillimeters: INT16
heightInMillimeters: INT16
This event is generated whenever the screen configuration is
changed and sent to requesting clients. The timestamp included
indicates when the screen configuration was changed, and
configTimestamp says when the last time the configuration was
changed. The root is the root of the screen the change
occurred on, and the event window is also returned. SizeID
contains an index indicating which size is current.
This event is sent whenever the screen's configuration changes
or if a new screen configuration becomes available that was
not available in the past. In this case (config-timestamp in
the event not being equal to the config-timestamp returned in
the last call to RRGetScreenInfo), the client MUST call
RRGetScreenInfo to update its view of possible screen
configurations to have a correct view of possible screen
organizations. Timestamp is set to when the active screen
configuration was changed.
Clients which select screen change notification events may be
sent an event immediately if the screen configuration was
changed between when they connected to the X server and
selected for notification. This is to prevent a common race
that might occur on log-in, where many applications start up
just at the time when a display manager or log in script might
be changing the screen size or configuration.
9. Extension Versioning
The RandR extension was developed in parallel with the implementation
to ensure the feasibility of various portions of the design. As
portions of the extension are implemented, the version number of the
extension has changed to reflect the portions of the standard provied.
This document describes the version 1.0 of the specification, the
partial implementations have version numbers less than that. Here's a
list of what each version before 1.0 implemented:
0.0: This prototype implemented resize and rotation in the
TinyX server Used approximately the protocol described in
the Usenix paper. Appeared in the TinyX server in
XFree86 4.2, but not in the XFree86 main server.
0.1: Added subpixel order, added an event for subpixel order.
This version was never checked in to XFree86 CVS.
1.0: Implements resize, rotation, and reflection. Implemented
both in the XFree86 main server (size change only at this
date), and fully (size change, rotation, and reflection)
in XFree86's TinyX server.
1.1: Added refresh rates
Compatibility between 0.0 and 1.0 was *NOT* preserved, and 0.0 clients
will fail against 1.0 servers. The wire encoding op-codes were
changed for GetScreenInfo to ensure this failure in a relatively
graceful way. Version 1.1 servers and clients are cross compatible with
1.0. Version 1.1 is considered to be stable and we intend upward
compatibility from this point.
Appendix A. Protocol Encoding
Syntactic Conventions
This document uses the same syntactic conventions as the core X
protocol encoding document.
A.1 Common Types
SETofROTATION
0x0001 RR_Rotate_0
0x0002 RR_Rotate_90
0x0004 RR_Rotate_180
0x0008 RR_Rotate_270
0x0010 RR_Reflect_X
0x0020 RR_Reflect_Y
SETofRRSELECTMASK
0x0001 RRScreenChangeNotifyMask
A.2 Protocol Requests
Opcodes 0x1 and 0x3 were used in the 0.0 protocols, and will return
errors if used in version 1.0.
RRQueryVersion
1 CARD8 major opcode
1 0x01 RandR opcode
2 3 length
4 CARD32 major version
4 CARD32 minor version
->
1 1 Reply
1 unused
2 CARD16 sequence number
4 0 reply length
1 CARD32 major version
1 CARD32 minor version
RRSetScreenConfig
1 CARD8 major opcode
1 0x02 RandR opcode
2 5 length
4 DRAWABLE drawable on screen to be configured
4 TIMESTAMP timestamp
2 SIZEID size id
2 ROTATION rotation/reflection
2 CARD16 refresh rate (1.1 only)
2 CARD16 pad
->
1 1 Reply
1 CARD8 status
0x0 RRSetConfigSuccess
0x1 RRSetConfigInvalidConfigTime
0x2 RRSetConfigInvalidTime
0x3 RRSetConfigFailed
2 CARD16 sequence number
4 0 reply length
4 TIMESTAMP new timestamp
4 TIMESTAMP new configuration timestamp
4 WINDOW root
2 SUBPIXELORDER subpixel order defined in Render
2 CARD16 pad4
4 CARD32 pad5
4 CARD32 pad6
RRSelectInput
1 CARD8 major opcode
1 0x04 RandR opcode
2 3 length
4 WINDOW window
2 SETofRRSELECTMASK enable
2 CARD16 pad
RRGetScreenInfo
1 CARD8 major opcode
1 0x05 RandR opcode
2 2 length
4 WINDOW window
->
1 1 Reply
1 CARD8 set of Rotations
2 CARD16 sequence number
4 0 reply length
4 WINDOW root window
4 TIMESTAMP timestamp
4 TIMESTAMP config timestamp
2 CARD16 number of SIZE following
2 SIZEID sizeID
2 ROTATION current rotation and reflection
2 CARD16 rate (1.1)
2 CARD16 length of rate info (number of CARD16s)
2 CARD16 pad
SIZE
2 CARD16 width in pixels
2 CARD16 height in pixels
2 CARD16 width in millimeters
2 CARD16 height in millimeters
REFRESH
2 CARD16 number of rates (n)
2n CARD16 rates
A.2 Protocol Event
RRScreenChangeNotify
1 Base + 0 code
1 ROTATION new rotation and reflection
2 CARD16 sequence number
4 TIMESTAMP timestamp
4 TIMESTAMP configuration timestamp
4 WINDOW root window
4 WINDOW request window
2 SIZEID size ID
2 SUBPIXELORDER subpixel order defined in Render
2 CARD16 width in pixels
2 CARD16 height in pixels
2 CARD16 width in millimeters
2 CARD16 height in millimeters
Bibliography
[RANDR] Gettys, Jim and Keith Packard, "The X Resize and Rotate
Extension - RandR", Proceedings of the 2001 USENIX Annual
Technical Conference, Boston, MA
[RENDER]
Packard, Keith, "The X Rendering Extension", work in progress,
documents found in xc/specs/Render.
|