summaryrefslogtreecommitdiff
path: root/randrproto.txt
blob: 67179f09ccc207e53dfa7e0de5496b42928a8e96 (plain)
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
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
         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:
      ► Modern toolkits (in this case, GTK+ 2.x) have progressed to the point
        of implementing migration between screens of arbitrary depths
      ► 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
      ► The continued decline of legacy toolkits whose design would have
        required depth switching to support migration
      ► 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,
zero or more video outputs are associated with each CRT controller which
defines both a set of video timings and a 'viewport' within the larger
screen. This viewport is independent of the overall size of the screen, and
may be located anywhere within the screen. 

The effect is to decouple the reported size of the screen from the size
presented by each video output, and to permit multiple outputs to present
information for a single screen.

To extend RandR for this model, we separate out the output, CRTC 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) CRTC and
output. The set of available outputs are presented with UTF-8 encoded names
and may be connected to CRTCs as permitted by the underlying hardware. CRTC
configuration is now done with full mode information instead of just size
and refresh rate, and these modes have names. These names also use UTF-8
encoding. New modes may also be added by the user.

Additional requests and events are provided for this new functionality.

       ┌────────────────────────────────┬──────────┐
    ┏━━━━━━━┳───────────────┐       ╔════════╗ ╔════════╗
    ┃   1   ┃               │       ║   A    ║ ║   B    ║
    ┃   ┏━━━╋━━━━━━━━━━━━━━━┫       ║        ║ ║        ║
    ┣━━━╋━━━┛               ┃       ╚════════╝ ╚════════╝
    │   ┃         2         ┃─────────────────┐
    │   ┃                   ┃        ╔═══════════════════╗ 
    │   ┃                   ┃        ║                   ║
    │   ┗━━━━━━━━━━━━━━━━━━━┫        ║        C          ║
    └───────────────────────┘        ║                   ║
    ┌──────┐  ┏━━━━┓  ╔══════╗       ║                   ║
    │screen│  ┃CRTC┃  ║output║       ╚═══════════════════╝
    └──────┘  ┗━━━━┛  ╚══════╝

In this picture, the screen is covered (incompletely) by two CRTCs. CRTC1
is connected to two outputs, A and B. CRTC2 is connected to output C.
Outputs A and B will present exactly the same region of the screen using
the same mode line. Output C will present a different (larger) region of
the screen using a different mode line.

RandR provides information about each available CRTC and output; the
connection between CRTC and output is under application control, although
the hardware will probably impose restrictions on the possible
configurations. The protocol doesn't try to describe these restrictions,
instead it provides a mechanism to find out what combinations are supported.

For instance, dual-link DVI gangs two CRTC outputs togther to provide higher
bandwidth for large resolution screens. This is exposed in RandR by
requiring that nothing be connected to the second CRTC when driving a high
resolution screen on the first.

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
Matthew Tippet and Kevin Martin for splitting outputs and CRTCs to more
fully expose what video hardware can do

2. Screen change model

Screens may change dynamically, either under control of this extension, or
due to external events. Examples include: monitors being swapped, 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 or Express Card 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
	       RRCrtcChangeNotifyMask (New in version 1.2)
	       RROutputChangeNotifyMask (New in version 1.2) }

SIZEID { CARD16 }

MODE { XID or None }

CRTC { CARD16 }

OUTPUT { 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 }

MODEFLAG { hsync_positive hsync_negative
	   vsync_positive vsync_negative
	   interlace double_scan
	   csync csync_positive csync_negative
	   hskew_present
	   bcast
	   pixel_multiplex
	   double_clock
	   clock_divide_by_2 }

OUTPUTMODE { id: MODE
             widthInPixels, heightInPixels: CARD16
             widthInMillimeters, heightInMillimeters: CARD32
             dotClock: CARD32
             hSyncStart, hSyncEnd, hTotal, hSkew: CARD16
             vSyncStart, vSyncEnd, vTotal: CARD16
             modeFlags: SETofMODEFLAG }

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 when 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.

	New for version 1.2:
	
	If 'enable' contains RRCrtcChangeMask, RRCrtcChangeNotify events
	will be sent when a the configuration for a CRTC associated with the
	screen changes, either through this protocol extension or due to
	detected external changes. RRCrtcChangeNotify may also be sent when
	this request executes if the CRTC configuration has changed since
	the client connected, to avoid race conditions. 
	
	If 'enable' contains RROutputChangeMask, RROutputChangeNotify events
	will be sent when a the configuration for an output associated with
	the screen changes, either through this protocol extension or due to
	detected external changes. RROutputChangeNotify may also be sent
	when this request executes if the output configuration has changed
	since the client connected, to avoid race conditions. 
	
RRSetScreenConfig
	window: WINDOW
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	size-id: 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
	window.

	'subpixelOrder' contains the resulting subpixel order of the screen
	to allow correct subpixel rendering.

	Value errors are generated when 'rotation', 'rate' or 'size-id'
	are invalid.

RRGetScreenInfo
	window: WINDOW

	▶	

	rotations: SETofROTATION
	root: WINDOW
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	size-id: 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.
	
	'size-id' 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 crtc and output configuration, permitting the subset of the screen
presented by multiple outputs to be configured. As a separate notion, the
size of the screen itself may be arbitrarily configured within a defined
range. As crtcs and outputs are added and removed from the system, the set
returned by the extension will change so that applications can detect
dynamic changes in the display environment.

RRGetScreenSizeRange
	window: WINDOW

	▶

	CARD16	minWidth, minHeight
	CARD16	maxWidth, maxHeight

	Errors: Window

	Returns the range of possible screen sizes. The screen may be set to
	any size within this range.

RRSetScreenSize
	window: WINDOW
	width: CARD16
	height: CARD16
	width-in-millimeters: CARD32
	height-in-millimeters: CARD32

	Errors: Window, 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.

	'width-in-millimeters' and 'height-in-millimeters' can be set to
	reflect the physical size of the screen reported both through this
	extension and the core protocol. They must be non-zero, or Value
	error results.

RRGetScreenResources
	window: WINDOW

	▶

	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	number-of-crtcs: CARD16
	number-of-outputs: CARD16

	Errors: Window

RRGetOutputInfo
	window: WINDOW
	output: OUTPUT

	▶

	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	name: STRING
	crtc: CRTC
	crtcs: LISTofCRTC
	clones: LISTofOUTPUT
	modes: LISTofOUTPUTMODE

RRGetCrtcInfo
	window: WINDOW
	crtc: CRTC

	▶

	timestamp: TIMESTAMP
	x, y: INT16
	mode: MODE
	rotation: ROTATION
	
	config-timestamp: TIMESTAMP
	rotations: SETofROTATION
	default-mode: MODE
	outputs: LISTofOUTPUT

	Errors: Window

	RRGetCrtcModes returns information about the current and available
	configurations for the specified crtc connected to the screen
	associated with 'window'.

	'timestamp' indicates when the configuration was last set.
	
	'x' and 'y' indicate the position of this CRTC within the screen
	region. They will be set to 0 when the CRTC is disabled.
	
	'mode' indicates which mode is active, or Disabled indicating
	that the CRTC has been disabled and is not displaying the screen
	contents.

	'rotation' indicates the active rotation. It is set to Rotate_0
	when the CRTC is disabled.
	
	'config-timestamp' indicates when the configuration information last
	changed: requests to configure the CRTC 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. 
	
	'rotations' contains the set of rotations and reflections supported
	by the CRTC.

	'default-mode' is the mode the CRTC is set to at server
	reset time.

RRAddOutputMode
	window: WINDOW
	output: OUTPUT
	mode: OUTPUTMODE
	config-timestamp: TIMESTAMP
	timestamp: TIMESTAMP
	
	▶

	Errors: Window, Value, Match, Name

	'window' and 'output' which output is to be configured. If 'output'
	is out of range, a Value error is returned.

	'mode' provides a new mode for the output. If the name of 'mode'
	names an existing mode, a Name error is returned. If 'mode' cannot be
	supported by the specified output, a Match error is returned. If some
	parameter of the mode is not valid in some other way, a Value error
	is returned.

	This request generates OutputChangeNotify events.

RRDeleteOutputMode
	window: WINDOW
	output: OUTPUT
	name: STRING

	▶

	Errors: Window, Value, Name

	'window' and 'output' indicate which output is to be configured. If
	'output' is out of range, a Value error is returned.

	'name' specifies which mode to delete. If no mode of the specified
	name exists, a Name error is returned. The named mode must have been
	added with RRAddOutputMode, else an Access error is returned. The
	named mode must not be active, else a Match error is returned.

RRSetCrtcConfig
	window: WINDOW
	crtc: CRTC
	timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	x, y: INT16
	mode: MODE
	rotation: ROTATION
	outputs: LISTofOUTPUT

	▶

	status: RRCONFIGSTATUS
	new-timestamp: TIMESTAMP
	config-timestamp: TIMESTAMP
	root: WINDOW
	monitor: CRTC
	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 monitor's
	configuration last changed, the request is ignored and
	InvalidConfigTime returned in status. This could occur if the
	monitor changed since you last made a RRGetScreenInfo request,
	perhaps by a different monitor being connected to the machine.
	Rather than allowing an incorrect call to be executed based on stale
	data, the server will ignore the request.

	'x' and 'y' contain the desired location within the screen for this
	monitor's content. 'x' and 'y' must be within the screen size, else
	a Value error results.

	'mode' is either the desired mode or None indicating the CRTC should
	be disabled. If 'mode' is not one of these values, a Value
	error results. 'mode' must be valid for all of the configured outputs,
	else a Match error.

	'rotation' contains the desired rotation along with which
	reflections should be enabled. The rotation and reflection values
	must be among those allowed for this monitor, else a Value error
	results.

	'outputs' contains the set of outputs that this CRTC should be
	connected to. The set must be among the list of acceptable output
	sets for this CRTC or a Match error results. 
	
	If 'mode' is None, then 'outputs' must be empty, else a Match error
	results. Conversly, if 'mode' is not None, then 'outputs' must not be
	empty, else a Match error results.
	
	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 CRTC to the specified position, mode, rotation
	and reflection. The entire area of the CRTC must fit within the
	screen size, else a Match error results. As an example, rotating the
	screen so that a single CRTC fills the entire screen before and
	after may necessitate disabling the CRTC, resizing the screen,
	then re-enabling the CRTC at the new configuration to avoid an
	invalid intermediate configuration.

	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
	window.

	'subpixelOrder' contains the resulting subpixel order of the monitor
	to allow correct subpixel rendering.

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
	size-id: SIZEID			index of new size
	subpixelOrder: SUBPIXELORDER	order of subpixels
	widthInPixels: CARD16
	heightInPixels: CARD16
	widthInMillimeters: CARD16
	heightInMillimeters: CARD16

	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. 'size-id' 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.

8.1 Events added in version 1.2 of the RandR extension

RROutputChangeNotify:
	sequence-number: CARD16		low 16 bits of request's seq. number
	timestamp: TIMESTAMP		time screen was reconfigured
	config-timestamp: TIMESTAMP	time available config data was changed
	root: WINDOW			root window of screen
	window: WINDOW			window requesting notification
	output: OUTPUT			output which changed

	This event is generated whenever the available output configurations
	have changed and is sent to requesting clients. 'timestamp'
	indicates when the crtc configuration was changed by a client.
	'config-timestamp' says when the last time the available
	configurations changed. 'root' is the root of the screen the change
	occurred on, 'window' is window selecting for this event.

RRCrtcChangeNotify

	sequence-number: CARD16		low 16 bits of request's seq. number
	timestamp: TIMESTAMP		time monitor was changed
	config-timestamp: TIMESTAMP	time config data was changed
	root: WINDOW			root window of screen
	window: WINDOW			window requesting notification
	crtc-index: CRTC		monitor which changed
	mode: MODE			new mode
	rotation: ROTATION;		new rotation
	subpixelOrder: SUBPIXELORDER	order of subpixels
	x: INT16			x position of monitor within screen
	y: INT16			y position of monitor within screen

	This event is generated whenever the monitor configuration is changed
	and sent to requesting clients. 'timestamp' indicates when the
	monitor configuration was changed. 'config-timestamp' 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. 'size-id' contains the index of the current size.

	This event is sent whenever the monitor's configuration changes
	or if a new monitor 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 RRGetCrtcModes), the client MUST call
	RRGetCrtcModes to update its view of possible monitor
	configurations to have a correct view of possible monitor
	organizations.

	Clients which select monitor change notification events may be
	sent an event immediately if the monitor 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 monitor 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, switch to full VESA modes

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.

10. Relationship with other extensions

Two other extensions have a direct relationship with this extension. This
section attempts to explain how these three are supposed to work together.

10.1 XFree86-VidModeExtension

XFree86-VidModeExtension changes the configuration of a single monitor
attached to the screen without changing the configuration of the screen
itself. It provides the ability to specify new mode lines for the server to
use along with selecting among existing mode lines. As it uses screen
numbers instead of window identifiers, it can be used to affect multiple
monitors in a single-screen Xinerama configuration. However, the association
between screen numbers and root windows in a multi-Screen environment is not
defined by the extension. Version 2.0 of this extension added the ability to
adjust the DAC values in a TrueColor server to modify the brightness curves
of the display.

Most of the utility of this extension is subsumed by RandR version 1.2,
except for the gamma adjustments. If this features continue to be useful,
either some relationship between the screen indices used in the
XFree86-VidModeExtension and the screen/monitor pairs used int RandR or an
incorporation of this functionality into RandR might be needed.

10.2 Xinerama

Xinerama provides a mechanism for describing the relationship between the
overall screen display and monitors placed within that area. As such, it
provides the query functionality of RandR 1.2 without any of the
configuration functionality. Applications using Xinerama to discover
monitor geometry can continue to do so, with the caveat that they will not be
informed of changes when they occur. However, Xinerama configuration data
will be updated, so applications selecting for RandR notification and
re-querying the configuration with the Xinerama extension will get updated
information. It is probably better to view RandR as a superset of Xinerama
at this point and use it in preference to Xinerama where both are present.

Appendix A. Protocol Encoding

Syntactic Conventions

This document uses the same syntactic conventions as the core X
protocol encoding document.


A.1 Common Types

	ROTATION
	0x0001	Rotate_0
	0x0002	Rotate_90
	0x0004	Rotate_180
	0x0008	Rotate_270
	0x0010	Reflect_X
	0x0020	Reflect_Y


	RRSELECTMASK
	0x0001	ScreenChangeNotifyMask
	0x0002	CrtcChangeNotifyMask		Added in version 1.2

	RRCONFIGSTATUS
	0x0 Success
	0x1 InvalidConfigTime
	0x2 InvalidTime
	0x3 Failed

	SIZEID
	0xffff	Disabled

	CRTCMODE (36)			Added in version 1.2
	2	CARD16		width in pixels
	2	CARD16		height in pixels
	4	CARD32		width in millimeters
	4	CARD32		height in millimeters
	4	CARD32		dot clock
	2	CARD16		h sync start
	2	CARD16		h sync end
	2	CARD16		h total
	2	CARD16		h skew
	2	CARD16		v sync start
	2	CARD16		v sync end
	2	CARD16		v total
	2	CARD16		name length (n)
	4	SETofMODEFLAG	mode flags
	
	A monitor mode specifies the complete CRTC timings for
	a specfic mode. The vertical and horizontal synchronization rates
	can be computed given the dot clock and the h total/v total
	values. If the dot clock is zero, then all of the timing
	parameters and flags are not used, and must be zero as this
	indicates that the timings are unknown or otherwise unused.
	
	The location of the name in the encoding is specified separately
	
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	6			length
	4	WINDOW			window on screen to be configured
	4	TIMESTAMP		timestamp
	4	TIMESTAMP		config timestamp
	2	SIZEID			size index
	2	ROTATION		rotation/reflection
	2	CARD16			refresh rate (1.1 only)
	2	CARD16			pad
	▶
	1	1			Reply
	1	RRCONFIGSTATUS		status
	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 SCREENSIZE following
	2	SIZEID			current size index
	2	ROTATION		current rotation and reflection
	2	CARD16			current rate (added in version 1.1)
	2	CARD16			length of rate info (number of CARD16s)
	2	CARD16			pad

	SCREENSIZE
	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.1 Protocol Requests added with version 1.2

	RRGetScreenSizeRange
	
	1	CARD8			major opcode
	1	0x06			RandR opcode
	2	2			length
	4	WINDOW			window
	▶
	1	1			Reply
	1				unused
	2	CARD16			sequence number
	4	0			reply length
	2	CARD16			minWidth
	2	CARD16			minHeight
	2	CARD16			maxWidth
	2	CARD16			maxHeight
	4				unused
	4				unused
	4				unused
	4				unused
	
	
	RRSetScreenSize
	
	1	CARD8			major opcode
	1	0x07			RandR opcode
	2	5			length
	4	WINDOW			window
	2	CARD16			width
	2	CARD16			height
	4	CARD32			width in millimeters
	4	CARD32			height in millimeters
	

	RRGetCrtcInfo
	
	1	CARD8			major opcode
	1	0x08			RandR opcode
	2	2			length
	4	WINDOW			window
	▶
	1	1			Reply
	1				unused
	2	CARD16			sequence number
	4	i*6 + m*9 + (b+p)/4	reply length
	4	WINDOW			root
	2	CARD16			i = number of CRTCINFO following
	2	CARD16			m = number of CRTCMODE following
	2	CARD16			b = size of name array following
	14				unused
	i*24	LISTofCRTCINFO	one per monitor
	m*36	LISTofCRTCMODE	for all monitors
	b	LISTofCARD8		list of mode names
	p	pad			pad(b)

	CRTCINFO
	4	TIMESTAMP		timestamp
	4	TIMESTAMP		config-timestamp
	2	INT16			x
	2	INT16			y
	2	ROTATION		rotation
	2	MODE			mode
	2	MODE			default mode
	2	SETofROTATION		rotations
	2	CARD16			start offset in LISTofCRTCMODE
	2	CARD16			number of CRTCMODE

	RRAddCrtcMode
	1	CARD8			major opcode
	1	0x09			RandR opcode
	2	12+(b+p)/4		length
	4	WINDOW			window
	2	CRTC			monitor index
	2				unused
	36	CRTCMODE		mode
	b	STRING			mode name
	p				pad(b)
	
	RRDeleteCrtcMode
	1	CARD8			major opcode
	1	0x0a			RandR opcode
	2	3+(b+p)/4		length
	4	WINDOW			window
	2	CRTC			monitor index
	2	CARD16			mode name length
	b	STRING			mode name
	p				pad(b)
	
	RRSetCrtcConfig

	1	CARD8			major opcode
	1	0x0b			RandR opcode
	2	7			length
	4	WINDOW			window
	4	TIMESTAMP		timestamp
	4	TIMESTAMP		config timestamp
	2	CRTC			monitor index
	2	INT16			x
	2	INT16			y
	2	MODE			mode index
	2	ROTATION		rotation/reflection
	2				unused
	▶
	1	1			Reply
	1	RRCONFIGSTATUS		status
	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	CRTC			monitor
	8				unused
	

A.3 Protocol Events

	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

A.3.1 Protocol Events added with version 1.2

	RRCrtcChangeNotify

	1	Base + 1		code
	1	0			sub-code
	2	CARD16			sequence number
	4	TIMESTAMP		timestamp
	4	TIMESTAMP		configuration timestamp
	4	WINDOW			root window
	4	WINDOW			request window
	2	CRTC			monitor index
	2	MODE			mode ID
	2	ROTATION		new rotation and reflection
	2	SUBPIXELORDER		new subpixel order
	2	INT16			x
	2	INT16			y

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.