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
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
|
The X Resize, Rotate and Reflect Extension
Version 1.2
2006-4-13
Jim Gettys
Jim.Gettys@hp.com
Cambridge Research Laboratory
HP Labs
Hewlett Packard Company
Keith Packard
keith.packard@intel.com
Open Source Technology Center
Intel Corporation
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 X 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 implementation has 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 X.org server, and more fully in the hw/kdrive
implementation in the distribution, which fully implements resizing,
rotation and reflection.
1.2 Introduction to version 1.2 of the extension
One of the significant limitations found in version 1.1 of the RandR
protocol was the inability to deal with the Xinerama model where multiple
monitors display portions of a common underlying screen. In this environment,
the size of the 'porthole' shown by each monitor is independent of the
overall size of the screen, and the porthole may be located anywhere within
the screen.
The effect is to decouple the reported size of the screen from the size
presented by each monitor, and to permit multiple monitors to present
information for a single screen.
To extend RandR for this model, we separate out the monitor and screen
configuration information and permit them to be configured separately. For
compatibility with the 1.1 version of the protocol, we make the 1.1 requests
simultaneously affect both the screen and the (presumably sole) monitor.
Additional requests and events are provided for this new functionality.
2. Acknowlegements
Our thanks to the contributors to the design found on the xpert mailing
list, in particular:
Alan Hourihane for work on the early implementation
Andrew C. Aitchison for help with the XFree86 DDX implementation
Andy Ritger for early questions about how mergefb/Xinerama work with RandR
Carl Worth for editing the specification and Usenix paper
David Dawes for XFree86 DDX integration work
Thomas Winischhofer for the hardware-accelerated SiS rotation implementation
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
RRCONFIGSTATUS {
Success
InvalidConfigTime
InvalidTime
Failed }
ROTATION {
Rotate_0
Rotate_90
Rotate_180
Rotate_270
Reflect_X
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 }
SCREENSIZE {
widthInPixels, heightInPixels: CARD16
widthInMillimeters, heightInMillimeters: CARD16 }
REFRESH {
rates: LISTofCARD16 }
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: Window, Value
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 when
this request executes 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
->
status: RRCONFIGSTATUS
new-timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
root: WINDOW
subpixelOrder: SUBPIXELORDER
Errors: Value, Match
If 'timestamp' is less than the time when the configuration was last
successfully set, the request is ignored and InvalidTime returned in
status.
If 'config-timestamp' is not equal to when the server's screen
configurations last changed, the request is ignored and
InvalidConfigTime returned in status. 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.
'rate' contains the desired refresh rate. If it is zero, the server
selects an appropriate rate.
This request may fail for other indeterminate reasons, in which case
'status' will be set to Failed and no configuration change will be
made.
This request sets the screen to the specified size, rate, rotation
and reflection.
When this request succeeds, 'status' contains Success and the
requested changes to configuration will have been made.
'new-time-stamp' contains the time at which this request was
executed.
'config-timestamp' contains the time when the possible screen
configurations were last changed.
'root' contains the root window for the screen indicated by the
drawable.
'subpixelOrder' contains the resulting subpixel order of the screen
to allow correct subpixel rendering.
Value errors are generated when 'rotation', 'rate' or 'sizeID' are
invalid.
RRGetScreenInfo
window: WINDOW
->
rotations: SETofROTATION
root: WINDOW
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
sizeID: SIZEID
rotation: ROTATION
rate: CARD16
sizes: LISTofSCREENSIZE
refresh: LISTofREFRESH
where:
Errors: Window
RRGetScreenInfo returns information about the current and available
configurations for the screen associated with 'window'.
'rotations' contains the set of rotations and reflections supported
by the screen.
'root' is the root window of the screen.
'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.
'timestamp' indicates when the configuration was last set.
'sizeID' indicates which size is active.
'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 size indicates 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.
7.1. Extension Requests added in version 1.2 of the extension
As introduced above, version 1.2 of the extension splits the screen size
from the monitor configuration, permitting the subset of the screen
presented by multiple monitors to be configured. As a separate notion, the
size of the screen itself may be arbitrarily configured within a defined
range.
RRGetScreenSizeRange
drawable: DRAWABLE
->
CARD16 minWidth, minHeight
CARD16 maxWidth, maxHeight
Errors: Drawable
Returns the range of possible screen sizes. The screen may be set to
any size within this range.
RRSetScreenSize
drawable: DRAWABLE
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
width: CARD16
height: CARD16
Errors: Drawable, Match, Value
Sets the screen to the specified size. 'width' and 'height' must be
within the range allowed by GetScreenSizeRanges, otherwise a Value
error results. All active monitors must be configured to display a
subset of the specified size, else a Match error results.
RRGetMonitorInfo
drawable: DRAWABLE
->
root: WINDOW
monitors: LISTofMONITOR
where:
MONITOR {
name: STRING
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
x, y: INT16
sizeID: SIZEID or Disabled
rotation: ROTATION
rate: CARD16
rotations: SETofROTATION
defaultSizeID: SIZEID or Disabled
sizes: LISTofSCREENSIZE
refresh: LISTofREFRESH
}
Errors: Drawable
RRGetMonitorInfo returns information about the current and available
configurations for all monitors connected to the screen associated
with 'window'.
'root' is the root window of the screen.
'timestamp' indicates when the configuration was last set.
'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.
'x' and 'y' indicate the position of this monitor within the screen
region. They will be set to 0 when the monitor is disabled.
'sizeID' indicates which size is active, or 'Disabled' indicating
that the monitor has been disabled and is not displaying the screen
contents.
'rotation' indicates the active rotation. It is set to Rotate_0
when the monitor is disabled.
'rate' is the current refresh rate. This is zero when monitor is
disabled, when the refresh rate is unknown or on devices for which
refresh is not relevant.
'rotations' contains the set of rotations and reflections supported
by the monitor.
'defaultSizeID' is the size the monitor is set to at server reset
time.
'sizes' is the list of possible displayed sizes (with rotation set
to Rotate_0). Each size indicates both the linear physical size of
the monitor and the pixel size of the displayed area.
'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.
RRSetMonitorConfig
drawable: DRAWABLE
monitor: CARD32
timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
x,y: INT16
sizeID: SIZEID
rotation: ROTATION
rate: CARD16
->
status: RRStatus
new-timestamp: TIMESTAMP
config-timestamp: TIMESTAMP
root: WINDOW
subpixelOrder: SUBPIXELORDER
Errors: Drawable, Value, Match
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.
Value errors are generated if the rotation is not an
allowed rotation. Value errors are generated, if, when the
timestamps would allow the operation to succeed, or size-index
are not possible (out of range).
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. 'timestamp' indicates when the
screen configuration was changed. 'configTimestamp' says when the
last time the configuration was changed. 'root' is the root of the
screen the change occurred on, 'window' is window selecting for this
event. 'sizeID' contains the index of the current size.
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.
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
1.2: Separate out screens from monitors
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 Rotate_0
0x0002 Rotate_90
0x0004 Rotate_180
0x0008 Rotate_270
0x0010 Reflect_X
0x0020 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.
|